visus
/
toolchain-gcc-arm-embedded
İzle 1
Yıldızla 0
Çatalla 0
Kod Sorunlar 0 Değişiklik İstekleri 0 Sürümler 0 Wiki Aktivite
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 İşlemeler
1 Dal
Dal: main
Dallar Biçim İmleri
${ item.name }
Branş ${ searchTerm } oluştur
'main'den
${ noResults }
toolchain-gcc-arm-embedded/share/doc/gcc-arm-none-eabi/info/gdb.info

58304 satır
2.4MB
Ham Kalıcı Bağlantı Bahset Geçmiş 

  1. This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo.

  2. 

  3. Copyright (C) 1988-2020 Free Software Foundation, Inc.

  4. 

  5.    Permission is granted to copy, distribute and/or modify this document

  6. under the terms of the GNU Free Documentation License, Version 1.3 or

  7. any later version published by the Free Software Foundation; with the

  8. Invariant Sections being "Free Software" and "Free Software Needs Free

  9. Documentation", with the Front-Cover Texts being "A GNU Manual," and

  10. with the Back-Cover Texts as in (a) below.

  11. 

  12.    (a) The FSF's Back-Cover Text is: "You are free to copy and modify

  13. this GNU Manual.  Buying copies from GNU Press supports the FSF in

  14. developing GNU and promoting software freedom."

  15. INFO-DIR-SECTION Software development

  16. START-INFO-DIR-ENTRY

  17. * Gdb: (gdb).                     The GNU debugger.

  18. * gdbserver: (gdb) Server.        The GNU debugging server.

  19. END-INFO-DIR-ENTRY

  20. 

  21.    This file documents the GNU debugger GDB.

  22. 

  23.    This is the Tenth Edition, of 'Debugging with GDB: the GNU

  24. Source-Level Debugger' for GDB (GNU Arm Embedded Toolchain

  25. 10-2020-q4-major) Version 10.1.90.20201028-git.

  26. 

  27.    Copyright (C) 1988-2020 Free Software Foundation, Inc.

  28. 

  29.    Permission is granted to copy, distribute and/or modify this document

  30. under the terms of the GNU Free Documentation License, Version 1.3 or

  31. any later version published by the Free Software Foundation; with the

  32. Invariant Sections being "Free Software" and "Free Software Needs Free

  33. Documentation", with the Front-Cover Texts being "A GNU Manual," and

  34. with the Back-Cover Texts as in (a) below.

  35. 

  36.    (a) The FSF's Back-Cover Text is: "You are free to copy and modify

  37. this GNU Manual.  Buying copies from GNU Press supports the FSF in

  38. developing GNU and promoting software freedom."

  39. 

  40. 

  41. File: gdb.info,  Node: Top,  Next: Summary

  42. 

  43. Debugging with GDB

  44. ******************

  45. 

  46. This file describes GDB, the GNU symbolic debugger.

  47. 

  48.    This is the Tenth Edition, for GDB (GNU Arm Embedded Toolchain

  49. 10-2020-q4-major) Version 10.1.90.20201028-git.

  50. 

  51.    Copyright (C) 1988-2020 Free Software Foundation, Inc.

  52. 

  53.    This edition of the GDB manual is dedicated to the memory of Fred

  54. Fish.  Fred was a long-standing contributor to GDB and to Free software

  55. in general.  We will miss him.

  56. 

  57. * Menu:

  58. 

  59. * Summary::                     Summary of GDB

  60. * Sample Session::              A sample GDB session

  61. 

  62. * Invocation::                  Getting in and out of GDB

  63. * Commands::                    GDB commands

  64. * Running::                     Running programs under GDB

  65. * Stopping::                    Stopping and continuing

  66. * Reverse Execution::           Running programs backward

  67. * Process Record and Replay::   Recording inferior's execution and replaying it

  68. * Stack::                       Examining the stack

  69. * Source::                      Examining source files

  70. * Data::                        Examining data

  71. * Optimized Code::              Debugging optimized code

  72. * Macros::                      Preprocessor Macros

  73. * Tracepoints::                 Debugging remote targets non-intrusively

  74. * Overlays::                    Debugging programs that use overlays

  75. 

  76. * Languages::                   Using GDB with different languages

  77. 

  78. * Symbols::                     Examining the symbol table

  79. * Altering::                    Altering execution

  80. * GDB Files::                   GDB files

  81. * Targets::                     Specifying a debugging target

  82. * Remote Debugging::            Debugging remote programs

  83. * Configurations::              Configuration-specific information

  84. * Controlling GDB::             Controlling GDB

  85. * Extending GDB::               Extending GDB

  86. * Interpreters::		Command Interpreters

  87. * TUI::                         GDB Text User Interface

  88. * Emacs::                       Using GDB under GNU Emacs

  89. * GDB/MI::                      GDB's Machine Interface.

  90. * Annotations::                 GDB's annotation interface.

  91. * JIT Interface::               Using the JIT debugging interface.

  92. * In-Process Agent::            In-Process Agent

  93. 

  94. * GDB Bugs::                    Reporting bugs in GDB

  95. 

  96. * Command Line Editing::        Command Line Editing

  97. * Using History Interactively:: Using History Interactively

  98. * In Memoriam::                 In Memoriam

  99. * Formatting Documentation::    How to format and print GDB documentation

  100. * Installing GDB::              Installing GDB

  101. * Maintenance Commands::        Maintenance Commands

  102. * Remote Protocol::             GDB Remote Serial Protocol

  103. * Agent Expressions::           The GDB Agent Expression Mechanism

  104. * Target Descriptions::         How targets can describe themselves to

  105.                                 GDB

  106. * Operating System Information:: Getting additional information from

  107.                                  the operating system

  108. * Trace File Format::		GDB trace file format

  109. * Index Section Format::        .gdb_index section format

  110. * Man Pages::			Manual pages

  111. * Copying::			GNU General Public License says

  112.                                 how you can copy and share GDB

  113. * GNU Free Documentation License::  The license for this documentation

  114. * Concept Index::               Index of GDB concepts

  115. * Command and Variable Index::  Index of GDB commands, variables,

  116.                                   functions, and Python data types

  117. 

  118. 

  119. File: gdb.info,  Node: Summary,  Next: Sample Session,  Up: Top

  120. 

  121. Summary of GDB

  122. **************

  123. 

  124. The purpose of a debugger such as GDB is to allow you to see what is

  125. going on "inside" another program while it executes--or what another

  126. program was doing at the moment it crashed.

  127. 

  128.    GDB can do four main kinds of things (plus other things in support of

  129. these) to help you catch bugs in the act:

  130. 

  131.    * Start your program, specifying anything that might affect its

  132.      behavior.

  133. 

  134.    * Make your program stop on specified conditions.

  135. 

  136.    * Examine what has happened, when your program has stopped.

  137. 

  138.    * Change things in your program, so you can experiment with

  139.      correcting the effects of one bug and go on to learn about another.

  140. 

  141.    You can use GDB to debug programs written in C and C++.  For more

  142. information, see *note Supported Languages: Supported Languages.  For

  143. more information, see *note C and C++: C.

  144. 

  145.    Support for D is partial.  For information on D, see *note D: D.

  146. 

  147.    Support for Modula-2 is partial.  For information on Modula-2, see

  148. *note Modula-2: Modula-2.

  149. 

  150.    Support for OpenCL C is partial.  For information on OpenCL C, see

  151. *note OpenCL C: OpenCL C.

  152. 

  153.    Debugging Pascal programs which use sets, subranges, file variables,

  154. or nested functions does not currently work.  GDB does not support

  155. entering expressions, printing values, or similar features using Pascal

  156. syntax.

  157. 

  158.    GDB can be used to debug programs written in Fortran, although it may

  159. be necessary to refer to some variables with a trailing underscore.

  160. 

  161.    GDB can be used to debug programs written in Objective-C, using

  162. either the Apple/NeXT or the GNU Objective-C runtime.

  163. 

  164. * Menu:

  165. 

  166. * Free Software::               Freely redistributable software

  167. * Free Documentation::          Free Software Needs Free Documentation

  168. * Contributors::                Contributors to GDB

  169. 

  170. 

  171. File: gdb.info,  Node: Free Software,  Next: Free Documentation,  Up: Summary

  172. 

  173. Free Software

  174. =============

  175. 

  176. GDB is "free software", protected by the GNU General Public License

  177. (GPL). The GPL gives you the freedom to copy or adapt a licensed

  178. program--but every person getting a copy also gets with it the freedom

  179. to modify that copy (which means that they must get access to the source

  180. code), and the freedom to distribute further copies.  Typical software

  181. companies use copyrights to limit your freedoms; the Free Software

  182. Foundation uses the GPL to preserve these freedoms.

  183. 

  184.    Fundamentally, the General Public License is a license which says

  185. that you have these freedoms and that you cannot take these freedoms

  186. away from anyone else.

  187. 

  188. 

  189. File: gdb.info,  Node: Free Documentation,  Next: Contributors,  Prev: Free Software,  Up: Summary

  190. 

  191. Free Software Needs Free Documentation

  192. ======================================

  193. 

  194. The biggest deficiency in the free software community today is not in

  195. the software--it is the lack of good free documentation that we can

  196. include with the free software.  Many of our most important programs do

  197. not come with free reference manuals and free introductory texts.

  198. Documentation is an essential part of any software package; when an

  199. important free software package does not come with a free manual and a

  200. free tutorial, that is a major gap.  We have many such gaps today.

  201. 

  202.    Consider Perl, for instance.  The tutorial manuals that people

  203. normally use are non-free.  How did this come about?  Because the

  204. authors of those manuals published them with restrictive terms--no

  205. copying, no modification, source files not available--which exclude them

  206. from the free software world.

  207. 

  208.    That wasn't the first time this sort of thing happened, and it was

  209. far from the last.  Many times we have heard a GNU user eagerly describe

  210. a manual that he is writing, his intended contribution to the community,

  211. only to learn that he had ruined everything by signing a publication

  212. contract to make it non-free.

  213. 

  214.    Free documentation, like free software, is a matter of freedom, not

  215. price.  The problem with the non-free manual is not that publishers

  216. charge a price for printed copies--that in itself is fine.  (The Free

  217. Software Foundation sells printed copies of manuals, too.)  The problem

  218. is the restrictions on the use of the manual.  Free manuals are

  219. available in source code form, and give you permission to copy and

  220. modify.  Non-free manuals do not allow this.

  221. 

  222.    The criteria of freedom for a free manual are roughly the same as for

  223. free software.  Redistribution (including the normal kinds of commercial

  224. redistribution) must be permitted, so that the manual can accompany

  225. every copy of the program, both on-line and on paper.

  226. 

  227.    Permission for modification of the technical content is crucial too.

  228. When people modify the software, adding or changing features, if they

  229. are conscientious they will change the manual too--so they can provide

  230. accurate and clear documentation for the modified program.  A manual

  231. that leaves you no choice but to write a new manual to document a

  232. changed version of the program is not really available to our community.

  233. 

  234.    Some kinds of limits on the way modification is handled are

  235. acceptable.  For example, requirements to preserve the original author's

  236. copyright notice, the distribution terms, or the list of authors, are

  237. ok.  It is also no problem to require modified versions to include

  238. notice that they were modified.  Even entire sections that may not be

  239. deleted or changed are acceptable, as long as they deal with

  240. nontechnical topics (like this one).  These kinds of restrictions are

  241. acceptable because they don't obstruct the community's normal use of the

  242. manual.

  243. 

  244.    However, it must be possible to modify all the _technical_ content of

  245. the manual, and then distribute the result in all the usual media,

  246. through all the usual channels.  Otherwise, the restrictions obstruct

  247. the use of the manual, it is not free, and we need another manual to

  248. replace it.

  249. 

  250.    Please spread the word about this issue.  Our community continues to

  251. lose manuals to proprietary publishing.  If we spread the word that free

  252. software needs free reference manuals and free tutorials, perhaps the

  253. next person who wants to contribute by writing documentation will

  254. realize, before it is too late, that only free manuals contribute to the

  255. free software community.

  256. 

  257.    If you are writing documentation, please insist on publishing it

  258. under the GNU Free Documentation License or another free documentation

  259. license.  Remember that this decision requires your approval--you don't

  260. have to let the publisher decide.  Some commercial publishers will use a

  261. free license if you insist, but they will not propose the option; it is

  262. up to you to raise the issue and say firmly that this is what you want.

  263. If the publisher you are dealing with refuses, please try other

  264. publishers.  If you're not sure whether a proposed license is free,

  265. write to <licensing@gnu.org>.

  266. 

  267.    You can encourage commercial publishers to sell more free, copylefted

  268. manuals and tutorials by buying them, and particularly by buying copies

  269. from the publishers that paid for their writing or for major

  270. improvements.  Meanwhile, try to avoid buying non-free documentation at

  271. all.  Check the distribution terms of a manual before you buy it, and

  272. insist that whoever seeks your business must respect your freedom.

  273. Check the history of the book, and try to reward the publishers that

  274. have paid or pay the authors to work on it.

  275. 

  276.    The Free Software Foundation maintains a list of free documentation

  277. published by other publishers, at

  278. <http://www.fsf.org/doc/other-free-books.html>.

  279. 

  280. 

  281. File: gdb.info,  Node: Contributors,  Prev: Free Documentation,  Up: Summary

  282. 

  283. Contributors to GDB

  284. ===================

  285. 

  286. Richard Stallman was the original author of GDB, and of many other GNU

  287. programs.  Many others have contributed to its development.  This

  288. section attempts to credit major contributors.  One of the virtues of

  289. free software is that everyone is free to contribute to it; with regret,

  290. we cannot actually acknowledge everyone here.  The file 'ChangeLog' in

  291. the GDB distribution approximates a blow-by-blow account.

  292. 

  293.    Changes much prior to version 2.0 are lost in the mists of time.

  294. 

  295.      _Plea:_ Additions to this section are particularly welcome.  If you

  296.      or your friends (or enemies, to be evenhanded) have been unfairly

  297.      omitted from this list, we would like to add your names!

  298. 

  299.    So that they may not regard their many labors as thankless, we

  300. particularly thank those who shepherded GDB through major releases:

  301. Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim

  302. Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release

  303. 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);

  304. Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);

  305. John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon

  306. (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and

  307. 3.0).

  308. 

  309.    Richard Stallman, assisted at various times by Peter TerMaat, Chris

  310. Hanson, and Richard Mlynarik, handled releases through 2.8.

  311. 

  312.    Michael Tiemann is the author of most of the GNU C++ support in GDB,

  313. with significant additional contributions from Per Bothner and Daniel

  314. Berlin.  James Clark wrote the GNU C++ demangler.  Early work on C++ was

  315. by Peter TerMaat (who also did much general update work leading to

  316. release 3.0).

  317. 

  318.    GDB uses the BFD subroutine library to examine multiple object-file

  319. formats; BFD was a joint project of David V. Henkel-Wallace, Rich

  320. Pixley, Steve Chamberlain, and John Gilmore.

  321. 

  322.    David Johnson wrote the original COFF support; Pace Willison did the

  323. original support for encapsulated COFF.

  324. 

  325.    Brent Benson of Harris Computer Systems contributed DWARF 2 support.

  326. 

  327.    Adam de Boor and Bradley Davis contributed the ISI Optimum V support.

  328. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS

  329. support.  Jean-Daniel Fekete contributed Sun 386i support.  Chris Hanson

  330. improved the HP9000 support.  Noboyuki Hikichi and Tomoyuki Hasei

  331. contributed Sony/News OS 3 support.  David Johnson contributed Encore

  332. Umax support.  Jyrki Kuoppala contributed Altos 3068 support.  Jeff Law

  333. contributed HP PA and SOM support.  Keith Packard contributed NS32K

  334. support.  Doug Rabson contributed Acorn Risc Machine support.  Bob Rusk

  335. contributed Harris Nighthawk CX-UX support.  Chris Smith contributed

  336. Convex support (and Fortran debugging).  Jonathan Stone contributed

  337. Pyramid support.  Michael Tiemann contributed SPARC support.  Tim Tucker

  338. contributed support for the Gould NP1 and Gould Powernode.  Pace

  339. Willison contributed Intel 386 support.  Jay Vosburgh contributed

  340. Symmetry support.  Marko Mlinar contributed OpenRISC 1000 support.

  341. 

  342.    Andreas Schwab contributed M68K GNU/Linux support.

  343. 

  344.    Rich Schaefer and Peter Schauer helped with support of SunOS shared

  345. libraries.

  346. 

  347.    Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about

  348. several machine instruction sets.

  349. 

  350.    Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped

  351. develop remote debugging.  Intel Corporation, Wind River Systems, AMD,

  352. and ARM contributed remote debugging modules for the i960, VxWorks, A29K

  353. UDI, and RDI targets, respectively.

  354. 

  355.    Brian Fox is the author of the readline libraries providing

  356. command-line editing and command history.

  357. 

  358.    Andrew Beers of SUNY Buffalo wrote the language-switching code, the

  359. Modula-2 support, and contributed the Languages chapter of this manual.

  360. 

  361.    Fred Fish wrote most of the support for Unix System Vr4.  He also

  362. enhanced the command-completion support to cover C++ overloaded symbols.

  363. 

  364.    Hitachi America (now Renesas America), Ltd.  sponsored the support

  365. for H8/300, H8/500, and Super-H processors.

  366. 

  367.    NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx

  368. processors.

  369. 

  370.    Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and

  371. M32R/D processors.

  372. 

  373.    Toshiba sponsored the support for the TX39 Mips processor.

  374. 

  375.    Matsushita sponsored the support for the MN10200 and MN10300

  376. processors.

  377. 

  378.    Fujitsu sponsored the support for SPARClite and FR30 processors.

  379. 

  380.    Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware

  381. watchpoints.

  382. 

  383.    Michael Snyder added support for tracepoints.

  384. 

  385.    Stu Grossman wrote gdbserver.

  386. 

  387.    Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly

  388. innumerable bug fixes and cleanups throughout GDB.

  389. 

  390.    The following people at the Hewlett-Packard Company contributed

  391. support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0

  392. (narrow mode), HP's implementation of kernel threads, HP's aC++

  393. compiler, and the Text User Interface (nee Terminal User Interface): Ben

  394. Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish

  395. Pai, India Paul, Steve Rehrauer, and Elena Zannoni.  Kim Haase provided

  396. HP-specific information in this manual.

  397. 

  398.    DJ Delorie ported GDB to MS-DOS, for the DJGPP project.  Robert

  399. Hoehne made significant contributions to the DJGPP port.

  400. 

  401.    Cygnus Solutions has sponsored GDB maintenance and much of its

  402. development since 1991.  Cygnus engineers who have worked on GDB

  403. fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin

  404. Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim

  405. Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,

  406. Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek

  407. Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni.  In

  408. addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,

  409. JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug

  410. Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff

  411. Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,

  412. Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin

  413. Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela

  414. Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David

  415. Zuhn have made contributions both large and small.

  416. 

  417.    Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for

  418. Cygnus Solutions, implemented the original GDB/MI interface.

  419. 

  420.    Jim Blandy added support for preprocessor macros, while working for

  421. Red Hat.

  422. 

  423.    Andrew Cagney designed GDB's architecture vector.  Many people

  424. including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,

  425. Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,

  426. Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna

  427. Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration

  428. of old architectures to this new framework.

  429. 

  430.    Andrew Cagney completely re-designed and re-implemented GDB's

  431. unwinder framework, this consisting of a fresh new design featuring

  432. frame IDs, independent frame sniffers, and the sentinel frame.  Mark

  433. Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind

  434. unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad

  435. unwinders.  The architecture-specific changes, each involving a complete

  436. rewrite of the architecture's frame code, were carried out by Jim

  437. Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez,

  438. Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz,

  439. Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori

  440. Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand.

  441. 

  442.    Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from

  443. Tensilica, Inc. contributed support for Xtensa processors.  Others who

  444. have worked on the Xtensa port of GDB in the past include Steve Tjiang,

  445. John Newlin, and Scott Foehner.

  446. 

  447.    Michael Eager and staff of Xilinx, Inc., contributed support for the

  448. Xilinx MicroBlaze architecture.

  449. 

  450.    Initial support for the FreeBSD/mips target and native configuration

  451. was developed by SRI International and the University of Cambridge

  452. Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237

  453. ("CTSRD"), as part of the DARPA CRASH research programme.

  454. 

  455.    Initial support for the FreeBSD/riscv target and native configuration

  456. was developed by SRI International and the University of Cambridge

  457. Computer Laboratory (Department of Computer Science and Technology)

  458. under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA

  459. SSITH research programme.

  460. 

  461.    The original port to the OpenRISC 1000 is believed to be due to

  462. Alessandro Forin and Per Bothner.  More recent ports have been the work

  463. of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and Stafford

  464. Horne.

  465. 

  466.    Weimin Pan, David Faust and Jose E. Marchesi contributed support for

  467. the Linux kernel BPF virtual architecture.  This work was sponsored by

  468. Oracle.

  469. 

  470. 

  471. File: gdb.info,  Node: Sample Session,  Next: Invocation,  Prev: Summary,  Up: Top

  472. 

  473. 1 A Sample GDB Session

  474. **********************

  475. 

  476. You can use this manual at your leisure to read all about GDB.  However,

  477. a handful of commands are enough to get started using the debugger.

  478. This chapter illustrates those commands.

  479. 

  480.    One of the preliminary versions of GNU 'm4' (a generic macro

  481. processor) exhibits the following bug: sometimes, when we change its

  482. quote strings from the default, the commands used to capture one macro

  483. definition within another stop working.  In the following short 'm4'

  484. session, we define a macro 'foo' which expands to '0000'; we then use

  485. the 'm4' built-in 'defn' to define 'bar' as the same thing.  However,

  486. when we change the open quote string to '<QUOTE>' and the close quote

  487. string to '<UNQUOTE>', the same procedure fails to define a new synonym

  488. 'baz':

  489. 

  490.      $ cd gnu/m4

  491.      $ ./m4

  492.      define(foo,0000)

  493. 

  494.      foo

  495.      0000

  496.      define(bar,defn('foo'))

  497. 

  498.      bar

  499.      0000

  500.      changequote(<QUOTE>,<UNQUOTE>)

  501. 

  502.      define(baz,defn(<QUOTE>foo<UNQUOTE>))

  503.      baz

  504.      Ctrl-d

  505.      m4: End of input: 0: fatal error: EOF in string

  506. 

  507. Let us use GDB to try to see what is going on.

  508. 

  509.      $ gdb m4

  510.      GDB is free software and you are welcome to distribute copies

  511.       of it under certain conditions; type "show copying" to see

  512.       the conditions.

  513.      There is absolutely no warranty for GDB; type "show warranty"

  514.       for details.

  515. 

  516.      GDB 10.1.90.20201028-git, Copyright 1999 Free Software Foundation, Inc...

  517.      (gdb)

  518. 

  519. GDB reads only enough symbol data to know where to find the rest when

  520. needed; as a result, the first prompt comes up very quickly.  We now

  521. tell GDB to use a narrower display width than usual, so that examples

  522. fit in this manual.

  523. 

  524.      (gdb) set width 70

  525. 

  526. We need to see how the 'm4' built-in 'changequote' works.  Having looked

  527. at the source, we know the relevant subroutine is 'm4_changequote', so

  528. we set a breakpoint there with the GDB 'break' command.

  529. 

  530.      (gdb) break m4_changequote

  531.      Breakpoint 1 at 0x62f4: file builtin.c, line 879.

  532. 

  533. Using the 'run' command, we start 'm4' running under GDB control; as

  534. long as control does not reach the 'm4_changequote' subroutine, the

  535. program runs as usual:

  536. 

  537.      (gdb) run

  538.      Starting program: /work/Editorial/gdb/gnu/m4/m4

  539.      define(foo,0000)

  540. 

  541.      foo

  542.      0000

  543. 

  544. To trigger the breakpoint, we call 'changequote'.  GDB suspends

  545. execution of 'm4', displaying information about the context where it

  546. stops.

  547. 

  548.      changequote(<QUOTE>,<UNQUOTE>)

  549. 

  550.      Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)

  551.          at builtin.c:879

  552.      879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

  553. 

  554. Now we use the command 'n' ('next') to advance execution to the next

  555. line of the current function.

  556. 

  557.      (gdb) n

  558.      882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\

  559.       : nil,

  560. 

  561. 'set_quotes' looks like a promising subroutine.  We can go into it by

  562. using the command 's' ('step') instead of 'next'.  'step' goes to the

  563. next line to be executed in _any_ subroutine, so it steps into

  564. 'set_quotes'.

  565. 

  566.      (gdb) s

  567.      set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")

  568.          at input.c:530

  569.      530         if (lquote != def_lquote)

  570. 

  571. The display that shows the subroutine where 'm4' is now suspended (and

  572. its arguments) is called a stack frame display.  It shows a summary of

  573. the stack.  We can use the 'backtrace' command (which can also be

  574. spelled 'bt'), to see where we are in the stack as a whole: the

  575. 'backtrace' command displays a stack frame for each active subroutine.

  576. 

  577.      (gdb) bt

  578.      #0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")

  579.          at input.c:530

  580.      #1  0x6344 in m4_changequote (argc=3, argv=0x33c70)

  581.          at builtin.c:882

  582.      #2  0x8174 in expand_macro (sym=0x33320) at macro.c:242

  583.      #3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)

  584.          at macro.c:71

  585.      #4  0x79dc in expand_input () at macro.c:40

  586.      #5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

  587. 

  588. We step through a few more lines to see what happens.  The first two

  589. times, we can use 's'; the next two times we use 'n' to avoid falling

  590. into the 'xstrdup' subroutine.

  591. 

  592.      (gdb) s

  593.      0x3b5c  532         if (rquote != def_rquote)

  594.      (gdb) s

  595.      0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \

  596.      def_lquote : xstrdup(lq);

  597.      (gdb) n

  598.      536         rquote = (rq == nil || *rq == '\0') ? def_rquote\

  599.       : xstrdup(rq);

  600.      (gdb) n

  601.      538         len_lquote = strlen(rquote);

  602. 

  603. The last line displayed looks a little odd; we can examine the variables

  604. 'lquote' and 'rquote' to see if they are in fact the new left and right

  605. quotes we specified.  We use the command 'p' ('print') to see their

  606. values.

  607. 

  608.      (gdb) p lquote

  609.      $1 = 0x35d40 "<QUOTE>"

  610.      (gdb) p rquote

  611.      $2 = 0x35d50 "<UNQUOTE>"

  612. 

  613. 'lquote' and 'rquote' are indeed the new left and right quotes.  To look

  614. at some context, we can display ten lines of source surrounding the

  615. current line with the 'l' ('list') command.

  616. 

  617.      (gdb) l

  618.      533             xfree(rquote);

  619.      534

  620.      535         lquote = (lq == nil || *lq == '\0') ? def_lquote\

  621.       : xstrdup (lq);

  622.      536         rquote = (rq == nil || *rq == '\0') ? def_rquote\

  623.       : xstrdup (rq);

  624.      537

  625.      538         len_lquote = strlen(rquote);

  626.      539         len_rquote = strlen(lquote);

  627.      540     }

  628.      541

  629.      542     void

  630. 

  631. Let us step past the two lines that set 'len_lquote' and 'len_rquote',

  632. and then examine the values of those variables.

  633. 

  634.      (gdb) n

  635.      539         len_rquote = strlen(lquote);

  636.      (gdb) n

  637.      540     }

  638.      (gdb) p len_lquote

  639.      $3 = 9

  640.      (gdb) p len_rquote

  641.      $4 = 7

  642. 

  643. That certainly looks wrong, assuming 'len_lquote' and 'len_rquote' are

  644. meant to be the lengths of 'lquote' and 'rquote' respectively.  We can

  645. set them to better values using the 'p' command, since it can print the

  646. value of any expression--and that expression can include subroutine

  647. calls and assignments.

  648. 

  649.      (gdb) p len_lquote=strlen(lquote)

  650.      $5 = 7

  651.      (gdb) p len_rquote=strlen(rquote)

  652.      $6 = 9

  653. 

  654. Is that enough to fix the problem of using the new quotes with the 'm4'

  655. built-in 'defn'?  We can allow 'm4' to continue executing with the 'c'

  656. ('continue') command, and then try the example that caused trouble

  657. initially:

  658. 

  659.      (gdb) c

  660.      Continuing.

  661. 

  662.      define(baz,defn(<QUOTE>foo<UNQUOTE>))

  663. 

  664.      baz

  665.      0000

  666. 

  667. Success!  The new quotes now work just as well as the default ones.  The

  668. problem seems to have been just the two typos defining the wrong

  669. lengths.  We allow 'm4' exit by giving it an EOF as input:

  670. 

  671.      Ctrl-d

  672.      Program exited normally.

  673. 

  674. The message 'Program exited normally.' is from GDB; it indicates 'm4'

  675. has finished executing.  We can end our GDB session with the GDB 'quit'

  676. command.

  677. 

  678.      (gdb) quit

  679. 

  680. 

  681. File: gdb.info,  Node: Invocation,  Next: Commands,  Prev: Sample Session,  Up: Top

  682. 

  683. 2 Getting In and Out of GDB

  684. ***************************

  685. 

  686. This chapter discusses how to start GDB, and how to get out of it.  The

  687. essentials are:

  688.    * type 'gdb' to start GDB.

  689.    * type 'quit' or 'Ctrl-d' to exit.

  690. 

  691. * Menu:

  692. 

  693. * Invoking GDB::                How to start GDB

  694. * Quitting GDB::                How to quit GDB

  695. * Shell Commands::              How to use shell commands inside GDB

  696. * Logging Output::              How to log GDB's output to a file

  697. 

  698. 

  699. File: gdb.info,  Node: Invoking GDB,  Next: Quitting GDB,  Up: Invocation

  700. 

  701. 2.1 Invoking GDB

  702. ================

  703. 

  704. Invoke GDB by running the program 'gdb'.  Once started, GDB reads

  705. commands from the terminal until you tell it to exit.

  706. 

  707.    You can also run 'gdb' with a variety of arguments and options, to

  708. specify more of your debugging environment at the outset.

  709. 

  710.    The command-line options described here are designed to cover a

  711. variety of situations; in some environments, some of these options may

  712. effectively be unavailable.

  713. 

  714.    The most usual way to start GDB is with one argument, specifying an

  715. executable program:

  716. 

  717.      gdb PROGRAM

  718. 

  719. You can also start with both an executable program and a core file

  720. specified:

  721. 

  722.      gdb PROGRAM CORE

  723. 

  724.    You can, instead, specify a process ID as a second argument or use

  725. option '-p', if you want to debug a running process:

  726. 

  727.      gdb PROGRAM 1234

  728.      gdb -p 1234

  729. 

  730. would attach GDB to process '1234'.  With option '-p' you can omit the

  731. PROGRAM filename.

  732. 

  733.    Taking advantage of the second command-line argument requires a

  734. fairly complete operating system; when you use GDB as a remote debugger

  735. attached to a bare board, there may not be any notion of "process", and

  736. there is often no way to get a core dump.  GDB will warn you if it is

  737. unable to attach or to read core dumps.

  738. 

  739.    You can optionally have 'gdb' pass any arguments after the executable

  740. file to the inferior using '--args'.  This option stops option

  741. processing.

  742.      gdb --args gcc -O2 -c foo.c

  743.    This will cause 'gdb' to debug 'gcc', and to set 'gcc''s command-line

  744. arguments (*note Arguments::) to '-O2 -c foo.c'.

  745. 

  746.    You can run 'gdb' without printing the front material, which

  747. describes GDB's non-warranty, by specifying '--silent' (or

  748. '-q'/'--quiet'):

  749. 

  750.      gdb --silent

  751. 

  752. You can further control how GDB starts up by using command-line options.

  753. GDB itself can remind you of the options available.

  754. 

  755. Type

  756. 

  757.      gdb -help

  758. 

  759. to display all available options and briefly describe their use ('gdb

  760. -h' is a shorter equivalent).

  761. 

  762.    All options and command line arguments you give are processed in

  763. sequential order.  The order makes a difference when the '-x' option is

  764. used.

  765. 

  766. * Menu:

  767. 

  768. * File Options::                Choosing files

  769. * Mode Options::                Choosing modes

  770. * Startup::                     What GDB does during startup

  771. 

  772. 

  773. File: gdb.info,  Node: File Options,  Next: Mode Options,  Up: Invoking GDB

  774. 

  775. 2.1.1 Choosing Files

  776. --------------------

  777. 

  778. When GDB starts, it reads any arguments other than options as specifying

  779. an executable file and core file (or process ID). This is the same as if

  780. the arguments were specified by the '-se' and '-c' (or '-p') options

  781. respectively.  (GDB reads the first argument that does not have an

  782. associated option flag as equivalent to the '-se' option followed by

  783. that argument; and the second argument that does not have an associated

  784. option flag, if any, as equivalent to the '-c'/'-p' option followed by

  785. that argument.)  If the second argument begins with a decimal digit, GDB

  786. will first attempt to attach to it as a process, and if that fails,

  787. attempt to open it as a corefile.  If you have a corefile whose name

  788. begins with a digit, you can prevent GDB from treating it as a pid by

  789. prefixing it with './', e.g. './12345'.

  790. 

  791.    If GDB has not been configured to included core file support, such as

  792. for most embedded targets, then it will complain about a second argument

  793. and ignore it.

  794. 

  795.    Many options have both long and short forms; both are shown in the

  796. following list.  GDB also recognizes the long forms if you truncate

  797. them, so long as enough of the option is present to be unambiguous.  (If

  798. you prefer, you can flag option arguments with '--' rather than '-',

  799. though we illustrate the more usual convention.)

  800. 

  801. '-symbols FILE'

  802. '-s FILE'

  803.      Read symbol table from file FILE.

  804. 

  805. '-exec FILE'

  806. '-e FILE'

  807.      Use file FILE as the executable file to execute when appropriate,

  808.      and for examining pure data in conjunction with a core dump.

  809. 

  810. '-se FILE'

  811.      Read symbol table from file FILE and use it as the executable file.

  812. 

  813. '-core FILE'

  814. '-c FILE'

  815.      Use file FILE as a core dump to examine.

  816. 

  817. '-pid NUMBER'

  818. '-p NUMBER'

  819.      Connect to process ID NUMBER, as with the 'attach' command.

  820. 

  821. '-command FILE'

  822. '-x FILE'

  823.      Execute commands from file FILE.  The contents of this file is

  824.      evaluated exactly as the 'source' command would.  *Note Command

  825.      files: Command Files.

  826. 

  827. '-eval-command COMMAND'

  828. '-ex COMMAND'

  829.      Execute a single GDB command.

  830. 

  831.      This option may be used multiple times to call multiple commands.

  832.      It may also be interleaved with '-command' as required.

  833. 

  834.           gdb -ex 'target sim' -ex 'load' \

  835.              -x setbreakpoints -ex 'run' a.out

  836. 

  837. '-init-command FILE'

  838. '-ix FILE'

  839.      Execute commands from file FILE before loading the inferior (but

  840.      after loading gdbinit files).  *Note Startup::.

  841. 

  842. '-init-eval-command COMMAND'

  843. '-iex COMMAND'

  844.      Execute a single GDB command before loading the inferior (but after

  845.      loading gdbinit files).  *Note Startup::.

  846. 

  847. '-directory DIRECTORY'

  848. '-d DIRECTORY'

  849.      Add DIRECTORY to the path to search for source and script files.

  850. 

  851. '-r'

  852. '-readnow'

  853.      Read each symbol file's entire symbol table immediately, rather

  854.      than the default, which is to read it incrementally as it is

  855.      needed.  This makes startup slower, but makes future operations

  856.      faster.

  857. 

  858. '--readnever'

  859.      Do not read each symbol file's symbolic debug information.  This

  860.      makes startup faster but at the expense of not being able to

  861.      perform symbolic debugging.  DWARF unwind information is also not

  862.      read, meaning backtraces may become incomplete or inaccurate.  One

  863.      use of this is when a user simply wants to do the following

  864.      sequence: attach, dump core, detach.  Loading the debugging

  865.      information in this case is an unnecessary cause of delay.

  866. 

  867. 

  868. File: gdb.info,  Node: Mode Options,  Next: Startup,  Prev: File Options,  Up: Invoking GDB

  869. 

  870. 2.1.2 Choosing Modes

  871. --------------------

  872. 

  873. You can run GDB in various alternative modes--for example, in batch mode

  874. or quiet mode.

  875. 

  876. '-nx'

  877. '-n'

  878.      Do not execute commands found in any initialization file.  There

  879.      are three init files, loaded in the following order:

  880. 

  881.      'system.gdbinit'

  882.           This is the system-wide init file.  Its location is specified

  883.           with the '--with-system-gdbinit' configure option (*note

  884.           System-wide configuration::).  It is loaded first when GDB

  885.           starts, before command line options have been processed.

  886.      'system.gdbinit.d'

  887.           This is the system-wide init directory.  Its location is

  888.           specified with the '--with-system-gdbinit-dir' configure

  889.           option (*note System-wide configuration::).  Files in this

  890.           directory are loaded in alphabetical order immediately after

  891.           system.gdbinit (if enabled) when GDB starts, before command

  892.           line options have been processed.  Files need to have a

  893.           recognized scripting language extension ('.py'/'.scm') or be

  894.           named with a '.gdb' extension to be interpreted as regular GDB

  895.           commands.  GDB will not recurse into any subdirectories of

  896.           this directory.

  897.      '~/.gdbinit'

  898.           This is the init file in your home directory.  It is loaded

  899.           next, after 'system.gdbinit', and before command options have

  900.           been processed.

  901.      './.gdbinit'

  902.           This is the init file in the current directory.  It is loaded

  903.           last, after command line options other than '-x' and '-ex'

  904.           have been processed.  Command line options '-x' and '-ex' are

  905.           processed last, after './.gdbinit' has been loaded.

  906. 

  907.      For further documentation on startup processing, *Note Startup::.

  908.      For documentation on how to write command files, *Note Command

  909.      Files: Command Files.

  910. 

  911. '-nh'

  912.      Do not execute commands found in '~/.gdbinit', the init file in

  913.      your home directory.  *Note Startup::.

  914. 

  915. '-quiet'

  916. '-silent'

  917. '-q'

  918.      "Quiet".  Do not print the introductory and copyright messages.

  919.      These messages are also suppressed in batch mode.

  920. 

  921. '-batch'

  922.      Run in batch mode.  Exit with status '0' after processing all the

  923.      command files specified with '-x' (and all commands from

  924.      initialization files, if not inhibited with '-n').  Exit with

  925.      nonzero status if an error occurs in executing the GDB commands in

  926.      the command files.  Batch mode also disables pagination, sets

  927.      unlimited terminal width and height *note Screen Size::, and acts

  928.      as if 'set confirm off' were in effect (*note Messages/Warnings::).

  929. 

  930.      Batch mode may be useful for running GDB as a filter, for example

  931.      to download and run a program on another computer; in order to make

  932.      this more useful, the message

  933. 

  934.           Program exited normally.

  935. 

  936.      (which is ordinarily issued whenever a program running under GDB

  937.      control terminates) is not issued when running in batch mode.

  938. 

  939. '-batch-silent'

  940.      Run in batch mode exactly like '-batch', but totally silently.  All

  941.      GDB output to 'stdout' is prevented ('stderr' is unaffected).  This

  942.      is much quieter than '-silent' and would be useless for an

  943.      interactive session.

  944. 

  945.      This is particularly useful when using targets that give 'Loading

  946.      section' messages, for example.

  947. 

  948.      Note that targets that give their output via GDB, as opposed to

  949.      writing directly to 'stdout', will also be made silent.

  950. 

  951. '-return-child-result'

  952.      The return code from GDB will be the return code from the child

  953.      process (the process being debugged), with the following

  954.      exceptions:

  955. 

  956.         * GDB exits abnormally.  E.g., due to an incorrect argument or

  957.           an internal error.  In this case the exit code is the same as

  958.           it would have been without '-return-child-result'.

  959.         * The user quits with an explicit value.  E.g., 'quit 1'.

  960.         * The child process never runs, or is not allowed to terminate,

  961.           in which case the exit code will be -1.

  962. 

  963.      This option is useful in conjunction with '-batch' or

  964.      '-batch-silent', when GDB is being used as a remote program loader

  965.      or simulator interface.

  966. 

  967. '-nowindows'

  968. '-nw'

  969.      "No windows".  If GDB comes with a graphical user interface (GUI)

  970.      built in, then this option tells GDB to only use the command-line

  971.      interface.  If no GUI is available, this option has no effect.

  972. 

  973. '-windows'

  974. '-w'

  975.      If GDB includes a GUI, then this option requires it to be used if

  976.      possible.

  977. 

  978. '-cd DIRECTORY'

  979.      Run GDB using DIRECTORY as its working directory, instead of the

  980.      current directory.

  981. 

  982. '-data-directory DIRECTORY'

  983. '-D DIRECTORY'

  984.      Run GDB using DIRECTORY as its data directory.  The data directory

  985.      is where GDB searches for its auxiliary files.  *Note Data Files::.

  986. 

  987. '-fullname'

  988. '-f'

  989.      GNU Emacs sets this option when it runs GDB as a subprocess.  It

  990.      tells GDB to output the full file name and line number in a

  991.      standard, recognizable fashion each time a stack frame is displayed

  992.      (which includes each time your program stops).  This recognizable

  993.      format looks like two '\032' characters, followed by the file name,

  994.      line number and character position separated by colons, and a

  995.      newline.  The Emacs-to-GDB interface program uses the two '\032'

  996.      characters as a signal to display the source code for the frame.

  997. 

  998. '-annotate LEVEL'

  999.      This option sets the "annotation level" inside GDB.  Its effect is

  1000.      identical to using 'set annotate LEVEL' (*note Annotations::).  The

  1001.      annotation LEVEL controls how much information GDB prints together

  1002.      with its prompt, values of expressions, source lines, and other

  1003.      types of output.  Level 0 is the normal, level 1 is for use when

  1004.      GDB is run as a subprocess of GNU Emacs, level 3 is the maximum

  1005.      annotation suitable for programs that control GDB, and level 2 has

  1006.      been deprecated.

  1007. 

  1008.      The annotation mechanism has largely been superseded by GDB/MI

  1009.      (*note GDB/MI::).

  1010. 

  1011. '--args'

  1012.      Change interpretation of command line so that arguments following

  1013.      the executable file are passed as command line arguments to the

  1014.      inferior.  This option stops option processing.

  1015. 

  1016. '-baud BPS'

  1017. '-b BPS'

  1018.      Set the line speed (baud rate or bits per second) of any serial

  1019.      interface used by GDB for remote debugging.

  1020. 

  1021. '-l TIMEOUT'

  1022.      Set the timeout (in seconds) of any communication used by GDB for

  1023.      remote debugging.

  1024. 

  1025. '-tty DEVICE'

  1026. '-t DEVICE'

  1027.      Run using DEVICE for your program's standard input and output.

  1028. 

  1029. '-tui'

  1030.      Activate the "Text User Interface" when starting.  The Text User

  1031.      Interface manages several text windows on the terminal, showing

  1032.      source, assembly, registers and GDB command outputs (*note GDB Text

  1033.      User Interface: TUI.). Do not use this option if you run GDB from

  1034.      Emacs (*note Using GDB under GNU Emacs: Emacs.).

  1035. 

  1036. '-interpreter INTERP'

  1037.      Use the interpreter INTERP for interface with the controlling

  1038.      program or device.  This option is meant to be set by programs

  1039.      which communicate with GDB using it as a back end.  *Note Command

  1040.      Interpreters: Interpreters.

  1041. 

  1042.      '--interpreter=mi' (or '--interpreter=mi3') causes GDB to use the

  1043.      "GDB/MI interface" version 3 (*note The GDB/MI Interface: GDB/MI.)

  1044.      included since GDB version 9.1.  GDB/MI version 2 ('mi2'), included

  1045.      in GDB 6.0 and version 1 ('mi1'), included in GDB 5.3, are also

  1046.      available.  Earlier GDB/MI interfaces are no longer supported.

  1047. 

  1048. '-write'

  1049.      Open the executable and core files for both reading and writing.

  1050.      This is equivalent to the 'set write on' command inside GDB (*note

  1051.      Patching::).

  1052. 

  1053. '-statistics'

  1054.      This option causes GDB to print statistics about time and memory

  1055.      usage after it completes each command and returns to the prompt.

  1056. 

  1057. '-version'

  1058.      This option causes GDB to print its version number and no-warranty

  1059.      blurb, and exit.

  1060. 

  1061. '-configuration'

  1062.      This option causes GDB to print details about its build-time

  1063.      configuration parameters, and then exit.  These details can be

  1064.      important when reporting GDB bugs (*note GDB Bugs::).

  1065. 

  1066. 

  1067. File: gdb.info,  Node: Startup,  Prev: Mode Options,  Up: Invoking GDB

  1068. 

  1069. 2.1.3 What GDB Does During Startup

  1070. ----------------------------------

  1071. 

  1072. Here's the description of what GDB does during session startup:

  1073. 

  1074.   1. Sets up the command interpreter as specified by the command line

  1075.      (*note interpreter: Mode Options.).

  1076. 

  1077.   2. Reads the system-wide "init file" (if '--with-system-gdbinit' was

  1078.      used when building GDB; *note System-wide configuration and

  1079.      settings: System-wide configuration.) and the files in the

  1080.      system-wide gdbinit directory (if '--with-system-gdbinit-dir' was

  1081.      used) and executes all the commands in those files.  The files need

  1082.      to be named with a '.gdb' extension to be interpreted as GDB

  1083.      commands, or they can be written in a supported scripting language

  1084.      with an appropriate file extension.

  1085. 

  1086.   3. Reads the init file (if any) in your home directory(1) and executes

  1087.      all the commands in that file.

  1088. 

  1089.   4. Executes commands and command files specified by the '-iex' and

  1090.      '-ix' options in their specified order.  Usually you should use the

  1091.      '-ex' and '-x' options instead, but this way you can apply settings

  1092.      before GDB init files get executed and before inferior gets loaded.

  1093. 

  1094.   5. Processes command line options and operands.

  1095. 

  1096.   6. Reads and executes the commands from init file (if any) in the

  1097.      current working directory as long as 'set auto-load local-gdbinit'

  1098.      is set to 'on' (*note Init File in the Current Directory::).  This

  1099.      is only done if the current directory is different from your home

  1100.      directory.  Thus, you can have more than one init file, one generic

  1101.      in your home directory, and another, specific to the program you

  1102.      are debugging, in the directory where you invoke GDB.

  1103. 

  1104.   7. If the command line specified a program to debug, or a process to

  1105.      attach to, or a core file, GDB loads any auto-loaded scripts

  1106.      provided for the program or for its loaded shared libraries.  *Note

  1107.      Auto-loading::.

  1108. 

  1109.      If you wish to disable the auto-loading during startup, you must do

  1110.      something like the following:

  1111. 

  1112.           $ gdb -iex "set auto-load python-scripts off" myprogram

  1113. 

  1114.      Option '-ex' does not work because the auto-loading is then turned

  1115.      off too late.

  1116. 

  1117.   8. Executes commands and command files specified by the '-ex' and '-x'

  1118.      options in their specified order.  *Note Command Files::, for more

  1119.      details about GDB command files.

  1120. 

  1121.   9. Reads the command history recorded in the "history file".  *Note

  1122.      Command History::, for more details about the command history and

  1123.      the files where GDB records it.

  1124. 

  1125.    Init files use the same syntax as "command files" (*note Command

  1126. Files::) and are processed by GDB in the same way.  The init file in

  1127. your home directory can set options (such as 'set complaints') that

  1128. affect subsequent processing of command line options and operands.  Init

  1129. files are not executed if you use the '-nx' option (*note Choosing

  1130. Modes: Mode Options.).

  1131. 

  1132.    To display the list of init files loaded by gdb at startup, you can

  1133. use 'gdb --help'.

  1134. 

  1135.    The GDB init files are normally called '.gdbinit'.  The DJGPP port of

  1136. GDB uses the name 'gdb.ini', due to the limitations of file names

  1137. imposed by DOS filesystems.  The Windows port of GDB uses the standard

  1138. name, but if it finds a 'gdb.ini' file in your home directory, it warns

  1139. you about that and suggests to rename the file to the standard name.

  1140. 

  1141.    ---------- Footnotes ----------

  1142. 

  1143.    (1) On DOS/Windows systems, the home directory is the one pointed to

  1144. by the 'HOME' environment variable.

  1145. 

  1146. 

  1147. File: gdb.info,  Node: Quitting GDB,  Next: Shell Commands,  Prev: Invoking GDB,  Up: Invocation

  1148. 

  1149. 2.2 Quitting GDB

  1150. ================

  1151. 

  1152. 'quit [EXPRESSION]'

  1153. 'q'

  1154.      To exit GDB, use the 'quit' command (abbreviated 'q'), or type an

  1155.      end-of-file character (usually 'Ctrl-d').  If you do not supply

  1156.      EXPRESSION, GDB will terminate normally; otherwise it will

  1157.      terminate using the result of EXPRESSION as the error code.

  1158. 

  1159.    An interrupt (often 'Ctrl-c') does not exit from GDB, but rather

  1160. terminates the action of any GDB command that is in progress and returns

  1161. to GDB command level.  It is safe to type the interrupt character at any

  1162. time because GDB does not allow it to take effect until a time when it

  1163. is safe.

  1164. 

  1165.    If you have been using GDB to control an attached process or device,

  1166. you can release it with the 'detach' command (*note Debugging an

  1167. Already-running Process: Attach.).

  1168. 

  1169. 

  1170. File: gdb.info,  Node: Shell Commands,  Next: Logging Output,  Prev: Quitting GDB,  Up: Invocation

  1171. 

  1172. 2.3 Shell Commands

  1173. ==================

  1174. 

  1175. If you need to execute occasional shell commands during your debugging

  1176. session, there is no need to leave or suspend GDB; you can just use the

  1177. 'shell' command.

  1178. 

  1179. 'shell COMMAND-STRING'

  1180. '!COMMAND-STRING'

  1181.      Invoke a standard shell to execute COMMAND-STRING.  Note that no

  1182.      space is needed between '!' and COMMAND-STRING.  On GNU and Unix

  1183.      systems, the environment variable 'SHELL', if it exists, determines

  1184.      which shell to run.  Otherwise GDB uses the default shell

  1185.      ('/bin/sh' on GNU and Unix systems, 'cmd.exe' on MS-Windows,

  1186.      'COMMAND.COM' on MS-DOS, etc.).

  1187. 

  1188.    The utility 'make' is often needed in development environments.  You

  1189. do not have to use the 'shell' command for this purpose in GDB:

  1190. 

  1191. 'make MAKE-ARGS'

  1192.      Execute the 'make' program with the specified arguments.  This is

  1193.      equivalent to 'shell make MAKE-ARGS'.

  1194. 

  1195. 'pipe [COMMAND] | SHELL_COMMAND'

  1196. '| [COMMAND] | SHELL_COMMAND'

  1197. 'pipe -d DELIM COMMAND DELIM SHELL_COMMAND'

  1198. '| -d DELIM COMMAND DELIM SHELL_COMMAND'

  1199.      Executes COMMAND and sends its output to SHELL_COMMAND.  Note that

  1200.      no space is needed around '|'.  If no COMMAND is provided, the last

  1201.      command executed is repeated.

  1202. 

  1203.      In case the COMMAND contains a '|', the option '-d DELIM' can be

  1204.      used to specify an alternate delimiter string DELIM that separates

  1205.      the COMMAND from the SHELL_COMMAND.

  1206. 

  1207.      Example:

  1208.           (gdb) p var

  1209.           $1 = {

  1210.             black = 144,

  1211.             red = 233,

  1212.             green = 377,

  1213.             blue = 610,

  1214.             white = 987

  1215.           }

  1216.           (gdb) pipe p var|wc

  1217.                 7      19      80

  1218.           (gdb) |p var|wc -l

  1219.           7

  1220.           (gdb) p /x var

  1221.           $4 = {

  1222.             black = 0x90,

  1223.             red = 0xe9,

  1224.             green = 0x179,

  1225.             blue = 0x262,

  1226.             white = 0x3db

  1227.           }

  1228.           (gdb) ||grep red

  1229.             red => 0xe9,

  1230.           (gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'

  1231.           this contains a PIPE char

  1232.           (gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'

  1233.           this contains a PIPE char!

  1234.           (gdb)

  1235. 

  1236.    The convenience variables '$_shell_exitcode' and '$_shell_exitsignal'

  1237. can be used to examine the exit status of the last shell command

  1238. launched by 'shell', 'make', 'pipe' and '|'.  *Note Convenience

  1239. Variables: Convenience Vars.

  1240. 

  1241. 

  1242. File: gdb.info,  Node: Logging Output,  Prev: Shell Commands,  Up: Invocation

  1243. 

  1244. 2.4 Logging Output

  1245. ==================

  1246. 

  1247. You may want to save the output of GDB commands to a file.  There are

  1248. several commands to control GDB's logging.

  1249. 

  1250. 'set logging on'

  1251.      Enable logging.

  1252. 'set logging off'

  1253.      Disable logging.

  1254. 'set logging file FILE'

  1255.      Change the name of the current logfile.  The default logfile is

  1256.      'gdb.txt'.

  1257. 'set logging overwrite [on|off]'

  1258.      By default, GDB will append to the logfile.  Set 'overwrite' if you

  1259.      want 'set logging on' to overwrite the logfile instead.

  1260. 'set logging redirect [on|off]'

  1261.      By default, GDB output will go to both the terminal and the

  1262.      logfile.  Set 'redirect' if you want output to go only to the log

  1263.      file.

  1264. 'set logging debugredirect [on|off]'

  1265.      By default, GDB debug output will go to both the terminal and the

  1266.      logfile.  Set 'debugredirect' if you want debug output to go only

  1267.      to the log file.

  1268. 'show logging'

  1269.      Show the current values of the logging settings.

  1270. 

  1271.    You can also redirect the output of a GDB command to a shell command.

  1272. *Note pipe::.

  1273. 

  1274. 

  1275. File: gdb.info,  Node: Commands,  Next: Running,  Prev: Invocation,  Up: Top

  1276. 

  1277. 3 GDB Commands

  1278. **************

  1279. 

  1280. You can abbreviate a GDB command to the first few letters of the command

  1281. name, if that abbreviation is unambiguous; and you can repeat certain

  1282. GDB commands by typing just <RET>.  You can also use the <TAB> key to

  1283. get GDB to fill out the rest of a word in a command (or to show you the

  1284. alternatives available, if there is more than one possibility).

  1285. 

  1286. * Menu:

  1287. 

  1288. * Command Syntax::              How to give commands to GDB

  1289. * Command Settings::            How to change default behavior of commands

  1290. * Completion::                  Command completion

  1291. * Command Options::             Command options

  1292. * Command aliases default args::        Automatically prepend default arguments to user-defined aliases

  1293. * Help::                        How to ask GDB for help

  1294. 

  1295. 

  1296. File: gdb.info,  Node: Command Syntax,  Next: Command Settings,  Up: Commands

  1297. 

  1298. 3.1 Command Syntax

  1299. ==================

  1300. 

  1301. A GDB command is a single line of input.  There is no limit on how long

  1302. it can be.  It starts with a command name, which is followed by

  1303. arguments whose meaning depends on the command name.  For example, the

  1304. command 'step' accepts an argument which is the number of times to step,

  1305. as in 'step 5'.  You can also use the 'step' command with no arguments.

  1306. Some commands do not allow any arguments.

  1307. 

  1308.    GDB command names may always be truncated if that abbreviation is

  1309. unambiguous.  Other possible command abbreviations are listed in the

  1310. documentation for individual commands.  In some cases, even ambiguous

  1311. abbreviations are allowed; for example, 's' is specially defined as

  1312. equivalent to 'step' even though there are other commands whose names

  1313. start with 's'.  You can test abbreviations by using them as arguments

  1314. to the 'help' command.

  1315. 

  1316.    A blank line as input to GDB (typing just <RET>) means to repeat the

  1317. previous command.  Certain commands (for example, 'run') will not repeat

  1318. this way; these are commands whose unintentional repetition might cause

  1319. trouble and which you are unlikely to want to repeat.  User-defined

  1320. commands can disable this feature; see *note dont-repeat: Define.

  1321. 

  1322.    The 'list' and 'x' commands, when you repeat them with <RET>,

  1323. construct new arguments rather than repeating exactly as typed.  This

  1324. permits easy scanning of source or memory.

  1325. 

  1326.    GDB can also use <RET> in another way: to partition lengthy output,

  1327. in a way similar to the common utility 'more' (*note Screen Size: Screen

  1328. Size.).  Since it is easy to press one <RET> too many in this situation,

  1329. GDB disables command repetition after any command that generates this

  1330. sort of display.

  1331. 

  1332.    Any text from a '#' to the end of the line is a comment; it does

  1333. nothing.  This is useful mainly in command files (*note Command Files:

  1334. Command Files.).

  1335. 

  1336.    The 'Ctrl-o' binding is useful for repeating a complex sequence of

  1337. commands.  This command accepts the current line, like <RET>, and then

  1338. fetches the next line relative to the current line from the history for

  1339. editing.

  1340. 

  1341. 

  1342. File: gdb.info,  Node: Command Settings,  Next: Completion,  Prev: Command Syntax,  Up: Commands

  1343. 

  1344. 3.2 Command Settings

  1345. ====================

  1346. 

  1347. Many commands change their behavior according to command-specific

  1348. variables or settings.  These settings can be changed with the 'set'

  1349. subcommands.  For example, the 'print' command (*note Examining Data:

  1350. Data.) prints arrays differently depending on settings changeable with

  1351. the commands 'set print elements NUMBER-OF-ELEMENTS' and 'set print

  1352. array-indexes', among others.

  1353. 

  1354.    You can change these settings to your preference in the gdbinit files

  1355. loaded at GDB startup.  *Note Startup::.

  1356. 

  1357.    The settings can also be changed interactively during the debugging

  1358. session.  For example, to change the limit of array elements to print,

  1359. you can do the following:

  1360.      (GDB) set print elements 10

  1361.      (GDB) print some_array

  1362.      $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

  1363. 

  1364.    The above 'set print elements 10' command changes the number of

  1365. elements to print from the default of 200 to 10.  If you only intend

  1366. this limit of 10 to be used for printing 'some_array', then you must

  1367. restore the limit back to 200, with 'set print elements 200'.

  1368. 

  1369.    Some commands allow overriding settings with command options.  For

  1370. example, the 'print' command supports a number of options that allow

  1371. overriding relevant global print settings as set by 'set print'

  1372. subcommands.  *Note print options::.  The example above could be

  1373. rewritten as:

  1374.      (GDB) print -elements 10 -- some_array

  1375.      $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

  1376. 

  1377.    Alternatively, you can use the 'with' command to change a setting

  1378. temporarily, for the duration of a command invocation.

  1379. 

  1380. 'with SETTING [VALUE] [-- COMMAND]'

  1381. 'w SETTING [VALUE] [-- COMMAND]'

  1382.      Temporarily set SETTING to VALUE for the duration of COMMAND.

  1383. 

  1384.      SETTING is any setting you can change with the 'set' subcommands.

  1385.      VALUE is the value to assign to 'setting' while running 'command'.

  1386. 

  1387.      If no COMMAND is provided, the last command executed is repeated.

  1388. 

  1389.      If a COMMAND is provided, it must be preceded by a double dash

  1390.      ('--') separator.  This is required because some settings accept

  1391.      free-form arguments, such as expressions or filenames.

  1392. 

  1393.      For example, the command

  1394.           (GDB) with print array on -- print some_array

  1395.      is equivalent to the following 3 commands:

  1396.           (GDB) set print array on

  1397.           (GDB) print some_array

  1398.           (GDB) set print array off

  1399. 

  1400.      The 'with' command is particularly useful when you want to override

  1401.      a setting while running user-defined commands, or commands defined

  1402.      in Python or Guile.  *Note Extending GDB: Extending GDB.

  1403. 

  1404.           (GDB) with print pretty on -- my_complex_command

  1405. 

  1406.      To change several settings for the same command, you can nest

  1407.      'with' commands.  For example, 'with language ada -- with print

  1408.      elements 10' temporarily changes the language to Ada and sets a

  1409.      limit of 10 elements to print for arrays and strings.

  1410. 

  1411. 

  1412. File: gdb.info,  Node: Completion,  Next: Command Options,  Prev: Command Settings,  Up: Commands

  1413. 

  1414. 3.3 Command Completion

  1415. ======================

  1416. 

  1417. GDB can fill in the rest of a word in a command for you, if there is

  1418. only one possibility; it can also show you what the valid possibilities

  1419. are for the next word in a command, at any time.  This works for GDB

  1420. commands, GDB subcommands, command options, and the names of symbols in

  1421. your program.

  1422. 

  1423.    Press the <TAB> key whenever you want GDB to fill out the rest of a

  1424. word.  If there is only one possibility, GDB fills in the word, and

  1425. waits for you to finish the command (or press <RET> to enter it).  For

  1426. example, if you type

  1427. 

  1428.      (gdb) info bre <TAB>

  1429. 

  1430. GDB fills in the rest of the word 'breakpoints', since that is the only

  1431. 'info' subcommand beginning with 'bre':

  1432. 

  1433.      (gdb) info breakpoints

  1434. 

  1435. You can either press <RET> at this point, to run the 'info breakpoints'

  1436. command, or backspace and enter something else, if 'breakpoints' does

  1437. not look like the command you expected.  (If you were sure you wanted

  1438. 'info breakpoints' in the first place, you might as well just type <RET>

  1439. immediately after 'info bre', to exploit command abbreviations rather

  1440. than command completion).

  1441. 

  1442.    If there is more than one possibility for the next word when you

  1443. press <TAB>, GDB sounds a bell.  You can either supply more characters

  1444. and try again, or just press <TAB> a second time; GDB displays all the

  1445. possible completions for that word.  For example, you might want to set

  1446. a breakpoint on a subroutine whose name begins with 'make_', but when

  1447. you type 'b make_<TAB>' GDB just sounds the bell.  Typing <TAB> again

  1448. displays all the function names in your program that begin with those

  1449. characters, for example:

  1450. 

  1451.      (gdb) b make_ <TAB>

  1452. GDB sounds bell; press <TAB> again, to see:

  1453.      make_a_section_from_file     make_environ

  1454.      make_abs_section             make_function_type

  1455.      make_blockvector             make_pointer_type

  1456.      make_cleanup                 make_reference_type

  1457.      make_command                 make_symbol_completion_list

  1458.      (gdb) b make_

  1459. 

  1460. After displaying the available possibilities, GDB copies your partial

  1461. input ('b make_' in the example) so you can finish the command.

  1462. 

  1463.    If you just want to see the list of alternatives in the first place,

  1464. you can press 'M-?' rather than pressing <TAB> twice.  'M-?' means

  1465. '<META> ?'.  You can type this either by holding down a key designated

  1466. as the <META> shift on your keyboard (if there is one) while typing '?',

  1467. or as <ESC> followed by '?'.

  1468. 

  1469.    If the number of possible completions is large, GDB will print as

  1470. much of the list as it has collected, as well as a message indicating

  1471. that the list may be truncated.

  1472. 

  1473.      (gdb) b m<TAB><TAB>

  1474.      main

  1475.      <... the rest of the possible completions ...>

  1476.      *** List may be truncated, max-completions reached. ***

  1477.      (gdb) b m

  1478. 

  1479. This behavior can be controlled with the following commands:

  1480. 

  1481. 'set max-completions LIMIT'

  1482. 'set max-completions unlimited'

  1483.      Set the maximum number of completion candidates.  GDB will stop

  1484.      looking for more completions once it collects this many candidates.

  1485.      This is useful when completing on things like function names as

  1486.      collecting all the possible candidates can be time consuming.  The

  1487.      default value is 200.  A value of zero disables tab-completion.

  1488.      Note that setting either no limit or a very large limit can make

  1489.      completion slow.

  1490. 'show max-completions'

  1491.      Show the maximum number of candidates that GDB will collect and

  1492.      show during completion.

  1493. 

  1494.    Sometimes the string you need, while logically a "word", may contain

  1495. parentheses or other characters that GDB normally excludes from its

  1496. notion of a word.  To permit word completion to work in this situation,

  1497. you may enclose words in ''' (single quote marks) in GDB commands.

  1498. 

  1499.    A likely situation where you might need this is in typing an

  1500. expression that involves a C++ symbol name with template parameters.

  1501. This is because when completing expressions, GDB treats the '<'

  1502. character as word delimiter, assuming that it's the less-than comparison

  1503. operator (*note C and C++ Operators: C Operators.).

  1504. 

  1505.    For example, when you want to call a C++ template function

  1506. interactively using the 'print' or 'call' commands, you may need to

  1507. distinguish whether you mean the version of 'name' that was specialized

  1508. for 'int', 'name<int>()', or the version that was specialized for

  1509. 'float', 'name<float>()'.  To use the word-completion facilities in this

  1510. situation, type a single quote ''' at the beginning of the function

  1511. name.  This alerts GDB that it may need to consider more information

  1512. than usual when you press <TAB> or 'M-?' to request word completion:

  1513. 

  1514.      (gdb) p 'func< M-?

  1515.      func<int>()    func<float>()

  1516.      (gdb) p 'func<

  1517. 

  1518.    When setting breakpoints however (*note Specify Location::), you

  1519. don't usually need to type a quote before the function name, because GDB

  1520. understands that you want to set a breakpoint on a function:

  1521. 

  1522.      (gdb) b func< M-?

  1523.      func<int>()    func<float>()

  1524.      (gdb) b func<

  1525. 

  1526.    This is true even in the case of typing the name of C++ overloaded

  1527. functions (multiple definitions of the same function, distinguished by

  1528. argument type).  For example, when you want to set a breakpoint you

  1529. don't need to distinguish whether you mean the version of 'name' that

  1530. takes an 'int' parameter, 'name(int)', or the version that takes a

  1531. 'float' parameter, 'name(float)'.

  1532. 

  1533.      (gdb) b bubble( M-?

  1534.      bubble(int)    bubble(double)

  1535.      (gdb) b bubble(dou M-?

  1536.      bubble(double)

  1537. 

  1538.    See *note quoting names:: for a description of other scenarios that

  1539. require quoting.

  1540. 

  1541.    For more information about overloaded functions, see *note C++

  1542. Expressions: C Plus Plus Expressions.  You can use the command 'set

  1543. overload-resolution off' to disable overload resolution; see *note GDB

  1544. Features for C++: Debugging C Plus Plus.

  1545. 

  1546.    When completing in an expression which looks up a field in a

  1547. structure, GDB also tries(1) to limit completions to the field names

  1548. available in the type of the left-hand-side:

  1549. 

  1550.      (gdb) p gdb_stdout.M-?

  1551.      magic                to_fputs             to_rewind

  1552.      to_data              to_isatty            to_write

  1553.      to_delete            to_put               to_write_async_safe

  1554.      to_flush             to_read

  1555. 

  1556. This is because the 'gdb_stdout' is a variable of the type 'struct

  1557. ui_file' that is defined in GDB sources as follows:

  1558. 

  1559.      struct ui_file

  1560.      {

  1561.         int *magic;

  1562.         ui_file_flush_ftype *to_flush;

  1563.         ui_file_write_ftype *to_write;

  1564.         ui_file_write_async_safe_ftype *to_write_async_safe;

  1565.         ui_file_fputs_ftype *to_fputs;

  1566.         ui_file_read_ftype *to_read;

  1567.         ui_file_delete_ftype *to_delete;

  1568.         ui_file_isatty_ftype *to_isatty;

  1569.         ui_file_rewind_ftype *to_rewind;

  1570.         ui_file_put_ftype *to_put;

  1571.         void *to_data;

  1572.      }

  1573. 

  1574.    ---------- Footnotes ----------

  1575. 

  1576.    (1) The completer can be confused by certain kinds of invalid

  1577. expressions.  Also, it only examines the static type of the expression,

  1578. not the dynamic type.

  1579. 

  1580. 

  1581. File: gdb.info,  Node: Command Options,  Next: Command aliases default args,  Prev: Completion,  Up: Commands

  1582. 

  1583. 3.4 Command options

  1584. ===================

  1585. 

  1586. Some commands accept options starting with a leading dash.  For example,

  1587. 'print -pretty'.  Similarly to command names, you can abbreviate a GDB

  1588. option to the first few letters of the option name, if that abbreviation

  1589. is unambiguous, and you can also use the <TAB> key to get GDB to fill

  1590. out the rest of a word in an option (or to show you the alternatives

  1591. available, if there is more than one possibility).

  1592. 

  1593.    Some commands take raw input as argument.  For example, the print

  1594. command processes arbitrary expressions in any of the languages

  1595. supported by GDB.  With such commands, because raw input may start with

  1596. a leading dash that would be confused with an option or any of its

  1597. abbreviations, e.g. 'print -p' (short for 'print -pretty' or printing

  1598. negative 'p'?), if you specify any command option, then you must use a

  1599. double-dash ('--') delimiter to indicate the end of options.

  1600. 

  1601.    Some options are described as accepting an argument which can be

  1602. either 'on' or 'off'.  These are known as "boolean options".  Similarly

  1603. to boolean settings commands--'on' and 'off' are the typical values, but

  1604. any of '1', 'yes' and 'enable' can also be used as "true" value, and any

  1605. of '0', 'no' and 'disable' can also be used as "false" value.  You can

  1606. also omit a "true" value, as it is implied by default.

  1607. 

  1608.    For example, these are equivalent:

  1609. 

  1610.      (gdb) print -object on -pretty off -element unlimited -- *myptr

  1611.      (gdb) p -o -p 0 -e u -- *myptr

  1612. 

  1613.    You can discover the set of options some command accepts by

  1614. completing on '-' after the command name.  For example:

  1615. 

  1616.      (gdb) print -<TAB><TAB>

  1617.      -address         -max-depth       -raw-values      -union

  1618.      -array           -null-stop       -repeats         -vtbl

  1619.      -array-indexes   -object          -static-members

  1620.      -elements        -pretty          -symbol

  1621. 

  1622.    Completion will in some cases guide you with a suggestion of what

  1623. kind of argument an option expects.  For example:

  1624. 

  1625.      (gdb) print -elements <TAB><TAB>

  1626.      NUMBER     unlimited

  1627. 

  1628.    Here, the option expects a number (e.g., '100'), not literal

  1629. 'NUMBER'.  Such metasyntactical arguments are always presented in

  1630. uppercase.

  1631. 

  1632.    (For more on using the 'print' command, see *note Examining Data:

  1633. Data.)

  1634. 

  1635. 

  1636. File: gdb.info,  Node: Command aliases default args,  Next: Help,  Prev: Command Options,  Up: Commands

  1637. 

  1638. 3.5 Automatically prepend default arguments to user-defined aliases

  1639. ===================================================================

  1640. 

  1641. You can tell GDB to always prepend some default arguments to the list of

  1642. arguments provided explicitly by the user when using a user-defined

  1643. alias.

  1644. 

  1645.    If you repeatedly use the same arguments or options for a command,

  1646. you can define an alias for this command and tell GDB to automatically

  1647. prepend these arguments or options to the list of arguments you type

  1648. explicitly when using the alias(1).

  1649. 

  1650.    For example, if you often use the command 'thread apply all'

  1651. specifying to work on the threads in ascending order and to continue in

  1652. case it encounters an error, you can tell GDB to automatically preprend

  1653. the '-ascending' and '-c' options by using:

  1654. 

  1655.      (gdb) alias thread apply asc-all = thread apply all -ascending -c

  1656. 

  1657.    Once you have defined this alias with its default args, any time you

  1658. type the 'thread apply asc-all' followed by 'some arguments', GDB will

  1659. execute 'thread apply all -ascending -c some arguments'.

  1660. 

  1661.    To have even less to type, you can also define a one word alias:

  1662.      (gdb) alias t_a_c = thread apply all -ascending -c

  1663. 

  1664.    As usual, unambiguous abbreviations can be used for ALIAS and

  1665. DEFAULT-ARGS.

  1666. 

  1667.    The different aliases of a command do not share their default args.

  1668. For example, you define a new alias 'bt_ALL' showing all possible

  1669. information and another alias 'bt_SMALL' showing very limited

  1670. information using:

  1671.      (gdb) alias bt_ALL = backtrace -entry-values both -frame-arg all \

  1672.         -past-main -past-entry -full

  1673.      (gdb) alias bt_SMALL = backtrace -entry-values no -frame-arg none \

  1674.         -past-main off -past-entry off

  1675. 

  1676.    (For more on using the 'alias' command, see *note Aliases::.)

  1677. 

  1678.    Default args are not limited to the arguments and options of COMMAND,

  1679. but can specify nested commands if COMMAND accepts such a nested command

  1680. as argument.  For example, the below defines 'faalocalsoftype' that

  1681. lists the frames having locals of a certain type, together with the

  1682. matching local vars:

  1683.      (gdb) alias faalocalsoftype = frame apply all info locals -q -t

  1684.      (gdb) faalocalsoftype int

  1685.      #1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86

  1686.      i = 0

  1687.      ret = 21845

  1688. 

  1689.    This is also very useful to define an alias for a set of nested

  1690. 'with' commands to have a particular combination of temporary settings.

  1691. For example, the below defines the alias 'pp10' that pretty prints an

  1692. expression argument, with a maximum of 10 elements if the expression is

  1693. a string or an array:

  1694.      (gdb) alias pp10 = with print pretty -- with print elements 10 -- print

  1695.    This defines the alias 'pp10' as being a sequence of 3 commands.  The

  1696. first part 'with print pretty --' temporarily activates the setting 'set

  1697. print pretty', then launches the command that follows the separator

  1698. '--'.  The command following the first part is also a 'with' command

  1699. that temporarily changes the setting 'set print elements' to 10, then

  1700. launches the command that follows the second separator '--'.  The third

  1701. part 'print' is the command the 'pp10' alias will launch, using the

  1702. temporary values of the settings and the arguments explicitly given by

  1703. the user.  For more information about the 'with' command usage, see

  1704. *note Command Settings::.

  1705. 

  1706.    ---------- Footnotes ----------

  1707. 

  1708.    (1) GDB could easily accept default arguments for pre-defined

  1709. commands and aliases, but it was deemed this would be confusing, and so

  1710. is not allowed.

  1711. 

  1712. 

  1713. File: gdb.info,  Node: Help,  Prev: Command aliases default args,  Up: Commands

  1714. 

  1715. 3.6 Getting Help

  1716. ================

  1717. 

  1718. You can always ask GDB itself for information on its commands, using the

  1719. command 'help'.

  1720. 

  1721. 'help'

  1722. 'h'

  1723.      You can use 'help' (abbreviated 'h') with no arguments to display a

  1724.      short list of named classes of commands:

  1725. 

  1726.           (gdb) help

  1727.           List of classes of commands:

  1728. 

  1729.           aliases -- User-defined aliases of other commands

  1730.           breakpoints -- Making program stop at certain points

  1731.           data -- Examining data

  1732.           files -- Specifying and examining files

  1733.           internals -- Maintenance commands

  1734.           obscure -- Obscure features

  1735.           running -- Running the program

  1736.           stack -- Examining the stack

  1737.           status -- Status inquiries

  1738.           support -- Support facilities

  1739.           tracepoints -- Tracing of program execution without

  1740.                          stopping the program

  1741.           user-defined -- User-defined commands

  1742. 

  1743.           Type "help" followed by a class name for a list of

  1744.           commands in that class.

  1745.           Type "help" followed by command name for full

  1746.           documentation.

  1747.           Command name abbreviations are allowed if unambiguous.

  1748.           (gdb)

  1749. 

  1750. 'help CLASS'

  1751.      Using one of the general help classes as an argument, you can get a

  1752.      list of the individual commands in that class.  If a command has

  1753.      aliases, the aliases are given after the command name, separated by

  1754.      commas.  If an alias has default arguments, the full definition of

  1755.      the alias is given after the first line.  For example, here is the

  1756.      help display for the class 'status':

  1757. 

  1758.           (gdb) help status

  1759.           Status inquiries.

  1760. 

  1761.           List of commands:

  1762. 

  1763.           info, inf, i -- Generic command for showing things

  1764.                   about the program being debugged

  1765.           info address, iamain  -- Describe where symbol SYM is stored.

  1766.             alias iamain = info address main

  1767.           info all-registers -- List of all registers and their contents,

  1768.                   for selected stack frame.

  1769.           ...

  1770.           show, info set -- Generic command for showing things

  1771.                   about the debugger

  1772. 

  1773.           Type "help" followed by command name for full

  1774.           documentation.

  1775.           Command name abbreviations are allowed if unambiguous.

  1776.           (gdb)

  1777. 

  1778. 'help COMMAND'

  1779.      With a command name as 'help' argument, GDB displays a short

  1780.      paragraph on how to use that command.  If that command has one or

  1781.      more aliases, GDB will display a first line with the command name

  1782.      and all its aliases separated by commas.  This first line will be

  1783.      followed by the full definition of all aliases having default

  1784.      arguments.

  1785. 

  1786. 'apropos [-v] REGEXP'

  1787.      The 'apropos' command searches through all of the GDB commands, and

  1788.      their documentation, for the regular expression specified in ARGS.

  1789.      It prints out all matches found.  The optional flag '-v', which

  1790.      stands for 'verbose', indicates to output the full documentation of

  1791.      the matching commands and highlight the parts of the documentation

  1792.      matching REGEXP.  For example:

  1793. 

  1794.           apropos alias

  1795. 

  1796.      results in:

  1797. 

  1798.           alias -- Define a new command that is an alias of an existing command

  1799.           aliases -- User-defined aliases of other commands

  1800. 

  1801.      while

  1802. 

  1803.           apropos -v cut.*thread apply

  1804. 

  1805.      results in the below output, where 'cut for 'thread apply' is

  1806.      highlighted if styling is enabled.

  1807. 

  1808.           taas -- Apply a command to all threads (ignoring errors

  1809.           and empty output).

  1810.           Usage: taas COMMAND

  1811.           shortcut for 'thread apply all -s COMMAND'

  1812. 

  1813.           tfaas -- Apply a command to all frames of all threads

  1814.           (ignoring errors and empty output).

  1815.           Usage: tfaas COMMAND

  1816.           shortcut for 'thread apply all -s frame apply all -s COMMAND'

  1817. 

  1818. 'complete ARGS'

  1819.      The 'complete ARGS' command lists all the possible completions for

  1820.      the beginning of a command.  Use ARGS to specify the beginning of

  1821.      the command you want completed.  For example:

  1822. 

  1823.           complete i

  1824. 

  1825.      results in:

  1826. 

  1827.           if

  1828.           ignore

  1829.           info

  1830.           inspect

  1831. 

  1832.      This is intended for use by GNU Emacs.

  1833. 

  1834.    In addition to 'help', you can use the GDB commands 'info' and 'show'

  1835. to inquire about the state of your program, or the state of GDB itself.

  1836. Each command supports many topics of inquiry; this manual introduces

  1837. each of them in the appropriate context.  The listings under 'info' and

  1838. under 'show' in the Command, Variable, and Function Index point to all

  1839. the sub-commands.  *Note Command and Variable Index::.

  1840. 

  1841. 'info'

  1842.      This command (abbreviated 'i') is for describing the state of your

  1843.      program.  For example, you can show the arguments passed to a

  1844.      function with 'info args', list the registers currently in use with

  1845.      'info registers', or list the breakpoints you have set with 'info

  1846.      breakpoints'.  You can get a complete list of the 'info'

  1847.      sub-commands with 'help info'.

  1848. 

  1849. 'set'

  1850.      You can assign the result of an expression to an environment

  1851.      variable with 'set'.  For example, you can set the GDB prompt to a

  1852.      $-sign with 'set prompt $'.

  1853. 

  1854. 'show'

  1855.      In contrast to 'info', 'show' is for describing the state of GDB

  1856.      itself.  You can change most of the things you can 'show', by using

  1857.      the related command 'set'; for example, you can control what number

  1858.      system is used for displays with 'set radix', or simply inquire

  1859.      which is currently in use with 'show radix'.

  1860. 

  1861.      To display all the settable parameters and their current values,

  1862.      you can use 'show' with no arguments; you may also use 'info set'.

  1863.      Both commands produce the same display.

  1864. 

  1865.    Here are several miscellaneous 'show' subcommands, all of which are

  1866. exceptional in lacking corresponding 'set' commands:

  1867. 

  1868. 'show version'

  1869.      Show what version of GDB is running.  You should include this

  1870.      information in GDB bug-reports.  If multiple versions of GDB are in

  1871.      use at your site, you may need to determine which version of GDB

  1872.      you are running; as GDB evolves, new commands are introduced, and

  1873.      old ones may wither away.  Also, many system vendors ship variant

  1874.      versions of GDB, and there are variant versions of GDB in GNU/Linux

  1875.      distributions as well.  The version number is the same as the one

  1876.      announced when you start GDB.

  1877. 

  1878. 'show copying'

  1879. 'info copying'

  1880.      Display information about permission for copying GDB.

  1881. 

  1882. 'show warranty'

  1883. 'info warranty'

  1884.      Display the GNU "NO WARRANTY" statement, or a warranty, if your

  1885.      version of GDB comes with one.

  1886. 

  1887. 'show configuration'

  1888.      Display detailed information about the way GDB was configured when

  1889.      it was built.  This displays the optional arguments passed to the

  1890.      'configure' script and also configuration parameters detected

  1891.      automatically by 'configure'.  When reporting a GDB bug (*note GDB

  1892.      Bugs::), it is important to include this information in your

  1893.      report.

  1894. 

  1895. 

  1896. File: gdb.info,  Node: Running,  Next: Stopping,  Prev: Commands,  Up: Top

  1897. 

  1898. 4 Running Programs Under GDB

  1899. ****************************

  1900. 

  1901. When you run a program under GDB, you must first generate debugging

  1902. information when you compile it.

  1903. 

  1904.    You may start GDB with its arguments, if any, in an environment of

  1905. your choice.  If you are doing native debugging, you may redirect your

  1906. program's input and output, debug an already running process, or kill a

  1907. child process.

  1908. 

  1909. * Menu:

  1910. 

  1911. * Compilation::                 Compiling for debugging

  1912. * Starting::                    Starting your program

  1913. * Arguments::                   Your program's arguments

  1914. * Environment::                 Your program's environment

  1915. 

  1916. * Working Directory::           Your program's working directory

  1917. * Input/Output::                Your program's input and output

  1918. * Attach::                      Debugging an already-running process

  1919. * Kill Process::                Killing the child process

  1920. * Inferiors Connections and Programs:: Debugging multiple inferiors

  1921. 					 connections and programs

  1922. * Threads::                     Debugging programs with multiple threads

  1923. * Forks::                       Debugging forks

  1924. * Checkpoint/Restart::          Setting a _bookmark_ to return to later

  1925. 

  1926. 

  1927. File: gdb.info,  Node: Compilation,  Next: Starting,  Up: Running

  1928. 

  1929. 4.1 Compiling for Debugging

  1930. ===========================

  1931. 

  1932. In order to debug a program effectively, you need to generate debugging

  1933. information when you compile it.  This debugging information is stored

  1934. in the object file; it describes the data type of each variable or

  1935. function and the correspondence between source line numbers and

  1936. addresses in the executable code.

  1937. 

  1938.    To request debugging information, specify the '-g' option when you

  1939. run the compiler.

  1940. 

  1941.    Programs that are to be shipped to your customers are compiled with

  1942. optimizations, using the '-O' compiler option.  However, some compilers

  1943. are unable to handle the '-g' and '-O' options together.  Using those

  1944. compilers, you cannot generate optimized executables containing

  1945. debugging information.

  1946. 

  1947.    GCC, the GNU C/C++ compiler, supports '-g' with or without '-O',

  1948. making it possible to debug optimized code.  We recommend that you

  1949. _always_ use '-g' whenever you compile a program.  You may think your

  1950. program is correct, but there is no sense in pushing your luck.  For

  1951. more information, see *note Optimized Code::.

  1952. 

  1953.    Older versions of the GNU C compiler permitted a variant option '-gg'

  1954. for debugging information.  GDB no longer supports this format; if your

  1955. GNU C compiler has this option, do not use it.

  1956. 

  1957.    GDB knows about preprocessor macros and can show you their expansion

  1958. (*note Macros::).  Most compilers do not include information about

  1959. preprocessor macros in the debugging information if you specify the '-g'

  1960. flag alone.  Version 3.1 and later of GCC, the GNU C compiler, provides

  1961. macro information if you are using the DWARF debugging format, and

  1962. specify the option '-g3'.

  1963. 

  1964.    *Note Options for Debugging Your Program or GCC: (gcc)Debugging

  1965. Options, for more information on GCC options affecting debug

  1966. information.

  1967. 

  1968.    You will have the best debugging experience if you use the latest

  1969. version of the DWARF debugging format that your compiler supports.

  1970. DWARF is currently the most expressive and best supported debugging

  1971. format in GDB.

  1972. 

  1973. 

  1974. File: gdb.info,  Node: Starting,  Next: Arguments,  Prev: Compilation,  Up: Running

  1975. 

  1976. 4.2 Starting your Program

  1977. =========================

  1978. 

  1979. 'run'

  1980. 'r'

  1981.      Use the 'run' command to start your program under GDB.  You must

  1982.      first specify the program name with an argument to GDB (*note

  1983.      Getting In and Out of GDB: Invocation.), or by using the 'file' or

  1984.      'exec-file' command (*note Commands to Specify Files: Files.).

  1985. 

  1986.    If you are running your program in an execution environment that

  1987. supports processes, 'run' creates an inferior process and makes that

  1988. process run your program.  In some environments without processes, 'run'

  1989. jumps to the start of your program.  Other targets, like 'remote', are

  1990. always running.  If you get an error message like this one:

  1991. 

  1992.      The "remote" target does not support "run".

  1993.      Try "help target" or "continue".

  1994. 

  1995. then use 'continue' to run your program.  You may need 'load' first

  1996. (*note load::).

  1997. 

  1998.    The execution of a program is affected by certain information it

  1999. receives from its superior.  GDB provides ways to specify this

  2000. information, which you must do _before_ starting your program.  (You can

  2001. change it after starting your program, but such changes only affect your

  2002. program the next time you start it.)  This information may be divided

  2003. into four categories:

  2004. 

  2005. The _arguments._

  2006.      Specify the arguments to give your program as the arguments of the

  2007.      'run' command.  If a shell is available on your target, the shell

  2008.      is used to pass the arguments, so that you may use normal

  2009.      conventions (such as wildcard expansion or variable substitution)

  2010.      in describing the arguments.  In Unix systems, you can control

  2011.      which shell is used with the 'SHELL' environment variable.  If you

  2012.      do not define 'SHELL', GDB uses the default shell ('/bin/sh').  You

  2013.      can disable use of any shell with the 'set startup-with-shell'

  2014.      command (see below for details).

  2015. 

  2016. The _environment._

  2017.      Your program normally inherits its environment from GDB, but you

  2018.      can use the GDB commands 'set environment' and 'unset environment'

  2019.      to change parts of the environment that affect your program.  *Note

  2020.      Your Program's Environment: Environment.

  2021. 

  2022. The _working directory._

  2023.      You can set your program's working directory with the command 'set

  2024.      cwd'.  If you do not set any working directory with this command,

  2025.      your program will inherit GDB's working directory if native

  2026.      debugging, or the remote server's working directory if remote

  2027.      debugging.  *Note Your Program's Working Directory: Working

  2028.      Directory.

  2029. 

  2030. The _standard input and output._

  2031.      Your program normally uses the same device for standard input and

  2032.      standard output as GDB is using.  You can redirect input and output

  2033.      in the 'run' command line, or you can use the 'tty' command to set

  2034.      a different device for your program.  *Note Your Program's Input

  2035.      and Output: Input/Output.

  2036. 

  2037.      _Warning:_ While input and output redirection work, you cannot use

  2038.      pipes to pass the output of the program you are debugging to

  2039.      another program; if you attempt this, GDB is likely to wind up

  2040.      debugging the wrong program.

  2041. 

  2042.    When you issue the 'run' command, your program begins to execute

  2043. immediately.  *Note Stopping and Continuing: Stopping, for discussion of

  2044. how to arrange for your program to stop.  Once your program has stopped,

  2045. you may call functions in your program, using the 'print' or 'call'

  2046. commands.  *Note Examining Data: Data.

  2047. 

  2048.    If the modification time of your symbol file has changed since the

  2049. last time GDB read its symbols, GDB discards its symbol table, and reads

  2050. it again.  When it does this, GDB tries to retain your current

  2051. breakpoints.

  2052. 

  2053. 'start'

  2054.      The name of the main procedure can vary from language to language.

  2055.      With C or C++, the main procedure name is always 'main', but other

  2056.      languages such as Ada do not require a specific name for their main

  2057.      procedure.  The debugger provides a convenient way to start the

  2058.      execution of the program and to stop at the beginning of the main

  2059.      procedure, depending on the language used.

  2060. 

  2061.      The 'start' command does the equivalent of setting a temporary

  2062.      breakpoint at the beginning of the main procedure and then invoking

  2063.      the 'run' command.

  2064. 

  2065.      Some programs contain an "elaboration" phase where some startup

  2066.      code is executed before the main procedure is called.  This depends

  2067.      on the languages used to write your program.  In C++, for instance,

  2068.      constructors for static and global objects are executed before

  2069.      'main' is called.  It is therefore possible that the debugger stops

  2070.      before reaching the main procedure.  However, the temporary

  2071.      breakpoint will remain to halt execution.

  2072. 

  2073.      Specify the arguments to give to your program as arguments to the

  2074.      'start' command.  These arguments will be given verbatim to the

  2075.      underlying 'run' command.  Note that the same arguments will be

  2076.      reused if no argument is provided during subsequent calls to

  2077.      'start' or 'run'.

  2078. 

  2079.      It is sometimes necessary to debug the program during elaboration.

  2080.      In these cases, using the 'start' command would stop the execution

  2081.      of your program too late, as the program would have already

  2082.      completed the elaboration phase.  Under these circumstances, either

  2083.      insert breakpoints in your elaboration code before running your

  2084.      program or use the 'starti' command.

  2085. 

  2086. 'starti'

  2087.      The 'starti' command does the equivalent of setting a temporary

  2088.      breakpoint at the first instruction of a program's execution and

  2089.      then invoking the 'run' command.  For programs containing an

  2090.      elaboration phase, the 'starti' command will stop execution at the

  2091.      start of the elaboration phase.

  2092. 

  2093. 'set exec-wrapper WRAPPER'

  2094. 'show exec-wrapper'

  2095. 'unset exec-wrapper'

  2096.      When 'exec-wrapper' is set, the specified wrapper is used to launch

  2097.      programs for debugging.  GDB starts your program with a shell

  2098.      command of the form 'exec WRAPPER PROGRAM'.  Quoting is added to

  2099.      PROGRAM and its arguments, but not to WRAPPER, so you should add

  2100.      quotes if appropriate for your shell.  The wrapper runs until it

  2101.      executes your program, and then GDB takes control.

  2102. 

  2103.      You can use any program that eventually calls 'execve' with its

  2104.      arguments as a wrapper.  Several standard Unix utilities do this,

  2105.      e.g. 'env' and 'nohup'.  Any Unix shell script ending with 'exec

  2106.      "$@"' will also work.

  2107. 

  2108.      For example, you can use 'env' to pass an environment variable to

  2109.      the debugged program, without setting the variable in your shell's

  2110.      environment:

  2111. 

  2112.           (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'

  2113.           (gdb) run

  2114. 

  2115.      This command is available when debugging locally on most targets,

  2116.      excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.

  2117. 

  2118. 'set startup-with-shell'

  2119. 'set startup-with-shell on'

  2120. 'set startup-with-shell off'

  2121. 'show startup-with-shell'

  2122.      On Unix systems, by default, if a shell is available on your

  2123.      target, GDB) uses it to start your program.  Arguments of the 'run'

  2124.      command are passed to the shell, which does variable substitution,

  2125.      expands wildcard characters and performs redirection of I/O. In

  2126.      some circumstances, it may be useful to disable such use of a

  2127.      shell, for example, when debugging the shell itself or diagnosing

  2128.      startup failures such as:

  2129. 

  2130.           (gdb) run

  2131.           Starting program: ./a.out

  2132.           During startup program terminated with signal SIGSEGV, Segmentation fault.

  2133. 

  2134.      which indicates the shell or the wrapper specified with

  2135.      'exec-wrapper' crashed, not your program.  Most often, this is

  2136.      caused by something odd in your shell's non-interactive mode

  2137.      initialization file--such as '.cshrc' for C-shell, $'.zshenv' for

  2138.      the Z shell, or the file specified in the 'BASH_ENV' environment

  2139.      variable for BASH.

  2140. 

  2141. 'set auto-connect-native-target'

  2142. 'set auto-connect-native-target on'

  2143. 'set auto-connect-native-target off'

  2144. 'show auto-connect-native-target'

  2145. 

  2146.      By default, if the current inferior is not connected to any target

  2147.      yet (e.g., with 'target remote'), the 'run' command starts your

  2148.      program as a native process under GDB, on your local machine.  If

  2149.      you're sure you don't want to debug programs on your local machine,

  2150.      you can tell GDB to not connect to the native target automatically

  2151.      with the 'set auto-connect-native-target off' command.

  2152. 

  2153.      If 'on', which is the default, and if the current inferior is not

  2154.      connected to a target already, the 'run' command automaticaly

  2155.      connects to the native target, if one is available.

  2156. 

  2157.      If 'off', and if the current inferior is not connected to a target

  2158.      already, the 'run' command fails with an error:

  2159. 

  2160.           (gdb) run

  2161.           Don't know how to run.  Try "help target".

  2162. 

  2163.      If the current inferior is already connected to a target, GDB

  2164.      always uses it with the 'run' command.

  2165. 

  2166.      In any case, you can explicitly connect to the native target with

  2167.      the 'target native' command.  For example,

  2168. 

  2169.           (gdb) set auto-connect-native-target off

  2170.           (gdb) run

  2171.           Don't know how to run.  Try "help target".

  2172.           (gdb) target native

  2173.           (gdb) run

  2174.           Starting program: ./a.out

  2175.           [Inferior 1 (process 10421) exited normally]

  2176. 

  2177.      In case you connected explicitly to the 'native' target, GDB

  2178.      remains connected even if all inferiors exit, ready for the next

  2179.      'run' command.  Use the 'disconnect' command to disconnect.

  2180. 

  2181.      Examples of other commands that likewise respect the

  2182.      'auto-connect-native-target' setting: 'attach', 'info proc', 'info

  2183.      os'.

  2184. 

  2185. 'set disable-randomization'

  2186. 'set disable-randomization on'

  2187.      This option (enabled by default in GDB) will turn off the native

  2188.      randomization of the virtual address space of the started program.

  2189.      This option is useful for multiple debugging sessions to make the

  2190.      execution better reproducible and memory addresses reusable across

  2191.      debugging sessions.

  2192. 

  2193.      This feature is implemented only on certain targets, including

  2194.      GNU/Linux.  On GNU/Linux you can get the same behavior using

  2195. 

  2196.           (gdb) set exec-wrapper setarch `uname -m` -R

  2197. 

  2198. 'set disable-randomization off'

  2199.      Leave the behavior of the started executable unchanged.  Some bugs

  2200.      rear their ugly heads only when the program is loaded at certain

  2201.      addresses.  If your bug disappears when you run the program under

  2202.      GDB, that might be because GDB by default disables the address

  2203.      randomization on platforms, such as GNU/Linux, which do that for

  2204.      stand-alone programs.  Use 'set disable-randomization off' to try

  2205.      to reproduce such elusive bugs.

  2206. 

  2207.      On targets where it is available, virtual address space

  2208.      randomization protects the programs against certain kinds of

  2209.      security attacks.  In these cases the attacker needs to know the

  2210.      exact location of a concrete executable code.  Randomizing its

  2211.      location makes it impossible to inject jumps misusing a code at its

  2212.      expected addresses.

  2213. 

  2214.      Prelinking shared libraries provides a startup performance

  2215.      advantage but it makes addresses in these libraries predictable for

  2216.      privileged processes by having just unprivileged access at the

  2217.      target system.  Reading the shared library binary gives enough

  2218.      information for assembling the malicious code misusing it.  Still

  2219.      even a prelinked shared library can get loaded at a new random

  2220.      address just requiring the regular relocation process during the

  2221.      startup.  Shared libraries not already prelinked are always loaded

  2222.      at a randomly chosen address.

  2223. 

  2224.      Position independent executables (PIE) contain position independent

  2225.      code similar to the shared libraries and therefore such executables

  2226.      get loaded at a randomly chosen address upon startup.  PIE

  2227.      executables always load even already prelinked shared libraries at

  2228.      a random address.  You can build such executable using 'gcc -fPIE

  2229.      -pie'.

  2230. 

  2231.      Heap (malloc storage), stack and custom mmap areas are always

  2232.      placed randomly (as long as the randomization is enabled).

  2233. 

  2234. 'show disable-randomization'

  2235.      Show the current setting of the explicit disable of the native

  2236.      randomization of the virtual address space of the started program.

  2237. 

  2238. 

  2239. File: gdb.info,  Node: Arguments,  Next: Environment,  Prev: Starting,  Up: Running

  2240. 

  2241. 4.3 Your Program's Arguments

  2242. ============================

  2243. 

  2244. The arguments to your program can be specified by the arguments of the

  2245. 'run' command.  They are passed to a shell, which expands wildcard

  2246. characters and performs redirection of I/O, and thence to your program.

  2247. Your 'SHELL' environment variable (if it exists) specifies what shell

  2248. GDB uses.  If you do not define 'SHELL', GDB uses the default shell

  2249. ('/bin/sh' on Unix).

  2250. 

  2251.    On non-Unix systems, the program is usually invoked directly by GDB,

  2252. which emulates I/O redirection via the appropriate system calls, and the

  2253. wildcard characters are expanded by the startup code of the program, not

  2254. by the shell.

  2255. 

  2256.    'run' with no arguments uses the same arguments used by the previous

  2257. 'run', or those set by the 'set args' command.

  2258. 

  2259. 'set args'

  2260.      Specify the arguments to be used the next time your program is run.

  2261.      If 'set args' has no arguments, 'run' executes your program with no

  2262.      arguments.  Once you have run your program with arguments, using

  2263.      'set args' before the next 'run' is the only way to run it again

  2264.      without arguments.

  2265. 

  2266. 'show args'

  2267.      Show the arguments to give your program when it is started.

  2268. 

  2269. 

  2270. File: gdb.info,  Node: Environment,  Next: Working Directory,  Prev: Arguments,  Up: Running

  2271. 

  2272. 4.4 Your Program's Environment

  2273. ==============================

  2274. 

  2275. The "environment" consists of a set of environment variables and their

  2276. values.  Environment variables conventionally record such things as your

  2277. user name, your home directory, your terminal type, and your search path

  2278. for programs to run.  Usually you set up environment variables with the

  2279. shell and they are inherited by all the other programs you run.  When

  2280. debugging, it can be useful to try running your program with a modified

  2281. environment without having to start GDB over again.

  2282. 

  2283. 'path DIRECTORY'

  2284.      Add DIRECTORY to the front of the 'PATH' environment variable (the

  2285.      search path for executables) that will be passed to your program.

  2286.      The value of 'PATH' used by GDB does not change.  You may specify

  2287.      several directory names, separated by whitespace or by a

  2288.      system-dependent separator character (':' on Unix, ';' on MS-DOS

  2289.      and MS-Windows).  If DIRECTORY is already in the path, it is moved

  2290.      to the front, so it is searched sooner.

  2291. 

  2292.      You can use the string '$cwd' to refer to whatever is the current

  2293.      working directory at the time GDB searches the path.  If you use

  2294.      '.' instead, it refers to the directory where you executed the

  2295.      'path' command.  GDB replaces '.' in the DIRECTORY argument (with

  2296.      the current path) before adding DIRECTORY to the search path.

  2297. 

  2298. 'show paths'

  2299.      Display the list of search paths for executables (the 'PATH'

  2300.      environment variable).

  2301. 

  2302. 'show environment [VARNAME]'

  2303.      Print the value of environment variable VARNAME to be given to your

  2304.      program when it starts.  If you do not supply VARNAME, print the

  2305.      names and values of all environment variables to be given to your

  2306.      program.  You can abbreviate 'environment' as 'env'.

  2307. 

  2308. 'set environment VARNAME [=VALUE]'

  2309.      Set environment variable VARNAME to VALUE.  The value changes for

  2310.      your program (and the shell GDB uses to launch it), not for GDB

  2311.      itself.  The VALUE may be any string; the values of environment

  2312.      variables are just strings, and any interpretation is supplied by

  2313.      your program itself.  The VALUE parameter is optional; if it is

  2314.      eliminated, the variable is set to a null value.

  2315. 

  2316.      For example, this command:

  2317. 

  2318.           set env USER = foo

  2319. 

  2320.      tells the debugged program, when subsequently run, that its user is

  2321.      named 'foo'.  (The spaces around '=' are used for clarity here;

  2322.      they are not actually required.)

  2323. 

  2324.      Note that on Unix systems, GDB runs your program via a shell, which

  2325.      also inherits the environment set with 'set environment'.  If

  2326.      necessary, you can avoid that by using the 'env' program as a

  2327.      wrapper instead of using 'set environment'.  *Note set

  2328.      exec-wrapper::, for an example doing just that.

  2329. 

  2330.      Environment variables that are set by the user are also transmitted

  2331.      to 'gdbserver' to be used when starting the remote inferior.  *note

  2332.      QEnvironmentHexEncoded::.

  2333. 

  2334. 'unset environment VARNAME'

  2335.      Remove variable VARNAME from the environment to be passed to your

  2336.      program.  This is different from 'set env VARNAME ='; 'unset

  2337.      environment' removes the variable from the environment, rather than

  2338.      assigning it an empty value.

  2339. 

  2340.      Environment variables that are unset by the user are also unset on

  2341.      'gdbserver' when starting the remote inferior.  *note

  2342.      QEnvironmentUnset::.

  2343. 

  2344.    _Warning:_ On Unix systems, GDB runs your program using the shell

  2345. indicated by your 'SHELL' environment variable if it exists (or

  2346. '/bin/sh' if not).  If your 'SHELL' variable names a shell that runs an

  2347. initialization file when started non-interactively--such as '.cshrc' for

  2348. C-shell, $'.zshenv' for the Z shell, or the file specified in the

  2349. 'BASH_ENV' environment variable for BASH--any variables you set in that

  2350. file affect your program.  You may wish to move setting of environment

  2351. variables to files that are only run when you sign on, such as '.login'

  2352. or '.profile'.

  2353. 

  2354. 

  2355. File: gdb.info,  Node: Working Directory,  Next: Input/Output,  Prev: Environment,  Up: Running

  2356. 

  2357. 4.5 Your Program's Working Directory

  2358. ====================================

  2359. 

  2360. Each time you start your program with 'run', the inferior will be

  2361. initialized with the current working directory specified by the 'set

  2362. cwd' command.  If no directory has been specified by this command, then

  2363. the inferior will inherit GDB's current working directory as its working

  2364. directory if native debugging, or it will inherit the remote server's

  2365. current working directory if remote debugging.

  2366. 

  2367. 'set cwd [DIRECTORY]'

  2368.      Set the inferior's working directory to DIRECTORY, which will be

  2369.      'glob'-expanded in order to resolve tildes ('~').  If no argument

  2370.      has been specified, the command clears the setting and resets it to

  2371.      an empty state.  This setting has no effect on GDB's working

  2372.      directory, and it only takes effect the next time you start the

  2373.      inferior.  The '~' in DIRECTORY is a short for the "home

  2374.      directory", usually pointed to by the 'HOME' environment variable.

  2375.      On MS-Windows, if 'HOME' is not defined, GDB uses the concatenation

  2376.      of 'HOMEDRIVE' and 'HOMEPATH' as fallback.

  2377. 

  2378.      You can also change GDB's current working directory by using the

  2379.      'cd' command.  *Note cd command::.

  2380. 

  2381. 'show cwd'

  2382.      Show the inferior's working directory.  If no directory has been

  2383.      specified by 'set cwd', then the default inferior's working

  2384.      directory is the same as GDB's working directory.

  2385. 

  2386. 'cd [DIRECTORY]'

  2387.      Set the GDB working directory to DIRECTORY.  If not given,

  2388.      DIRECTORY uses ''~''.

  2389. 

  2390.      The GDB working directory serves as a default for the commands that

  2391.      specify files for GDB to operate on.  *Note Commands to Specify

  2392.      Files: Files.  *Note set cwd command::.

  2393. 

  2394. 'pwd'

  2395.      Print the GDB working directory.

  2396. 

  2397.    It is generally impossible to find the current working directory of

  2398. the process being debugged (since a program can change its directory

  2399. during its run).  If you work on a system where GDB supports the 'info

  2400. proc' command (*note Process Information::), you can use the 'info proc'

  2401. command to find out the current working directory of the debuggee.

  2402. 

  2403. 

  2404. File: gdb.info,  Node: Input/Output,  Next: Attach,  Prev: Working Directory,  Up: Running

  2405. 

  2406. 4.6 Your Program's Input and Output

  2407. ===================================

  2408. 

  2409. By default, the program you run under GDB does input and output to the

  2410. same terminal that GDB uses.  GDB switches the terminal to its own

  2411. terminal modes to interact with you, but it records the terminal modes

  2412. your program was using and switches back to them when you continue

  2413. running your program.

  2414. 

  2415. 'info terminal'

  2416.      Displays information recorded by GDB about the terminal modes your

  2417.      program is using.

  2418. 

  2419.    You can redirect your program's input and/or output using shell

  2420. redirection with the 'run' command.  For example,

  2421. 

  2422.      run > outfile

  2423. 

  2424. starts your program, diverting its output to the file 'outfile'.

  2425. 

  2426.    Another way to specify where your program should do input and output

  2427. is with the 'tty' command.  This command accepts a file name as

  2428. argument, and causes this file to be the default for future 'run'

  2429. commands.  It also resets the controlling terminal for the child

  2430. process, for future 'run' commands.  For example,

  2431. 

  2432.      tty /dev/ttyb

  2433. 

  2434. directs that processes started with subsequent 'run' commands default to

  2435. do input and output on the terminal '/dev/ttyb' and have that as their

  2436. controlling terminal.

  2437. 

  2438.    An explicit redirection in 'run' overrides the 'tty' command's effect

  2439. on the input/output device, but not its effect on the controlling

  2440. terminal.

  2441. 

  2442.    When you use the 'tty' command or redirect input in the 'run'

  2443. command, only the input _for your program_ is affected.  The input for

  2444. GDB still comes from your terminal.  'tty' is an alias for 'set

  2445. inferior-tty'.

  2446. 

  2447.    You can use the 'show inferior-tty' command to tell GDB to display

  2448. the name of the terminal that will be used for future runs of your

  2449. program.

  2450. 

  2451. 'set inferior-tty [ TTY ]'

  2452.      Set the tty for the program being debugged to TTY.  Omitting TTY

  2453.      restores the default behavior, which is to use the same terminal as

  2454.      GDB.

  2455. 

  2456. 'show inferior-tty'

  2457.      Show the current tty for the program being debugged.

  2458. 

  2459. 

  2460. File: gdb.info,  Node: Attach,  Next: Kill Process,  Prev: Input/Output,  Up: Running

  2461. 

  2462. 4.7 Debugging an Already-running Process

  2463. ========================================

  2464. 

  2465. 'attach PROCESS-ID'

  2466.      This command attaches to a running process--one that was started

  2467.      outside GDB.  ('info files' shows your active targets.)  The

  2468.      command takes as argument a process ID. The usual way to find out

  2469.      the PROCESS-ID of a Unix process is with the 'ps' utility, or with

  2470.      the 'jobs -l' shell command.

  2471. 

  2472.      'attach' does not repeat if you press <RET> a second time after

  2473.      executing the command.

  2474. 

  2475.    To use 'attach', your program must be running in an environment which

  2476. supports processes; for example, 'attach' does not work for programs on

  2477. bare-board targets that lack an operating system.  You must also have

  2478. permission to send the process a signal.

  2479. 

  2480.    When you use 'attach', the debugger finds the program running in the

  2481. process first by looking in the current working directory, then (if the

  2482. program is not found) by using the source file search path (*note

  2483. Specifying Source Directories: Source Path.).  You can also use the

  2484. 'file' command to load the program.  *Note Commands to Specify Files:

  2485. Files.

  2486. 

  2487.    If the debugger can determine that the executable file running in the

  2488. process it is attaching to does not match the current exec-file loaded

  2489. by GDB, the option 'exec-file-mismatch' specifies how to handle the

  2490. mismatch.  GDB tries to compare the files by comparing their build IDs

  2491. (*note build ID::), if available.

  2492. 

  2493. 'set exec-file-mismatch 'ask|warn|off''

  2494. 

  2495.      Whether to detect mismatch between the current executable file

  2496.      loaded by GDB and the executable file used to start the process.

  2497.      If 'ask', the default, display a warning and ask the user whether

  2498.      to load the process executable file; if 'warn', just display a

  2499.      warning; if 'off', don't attempt to detect a mismatch.  If the user

  2500.      confirms loading the process executable file, then its symbols will

  2501.      be loaded as well.

  2502. 

  2503. 'show exec-file-mismatch'

  2504.      Show the current value of 'exec-file-mismatch'.

  2505. 

  2506.    The first thing GDB does after arranging to debug the specified

  2507. process is to stop it.  You can examine and modify an attached process

  2508. with all the GDB commands that are ordinarily available when you start

  2509. processes with 'run'.  You can insert breakpoints; you can step and

  2510. continue; you can modify storage.  If you would rather the process

  2511. continue running, you may use the 'continue' command after attaching GDB

  2512. to the process.

  2513. 

  2514. 'detach'

  2515.      When you have finished debugging the attached process, you can use

  2516.      the 'detach' command to release it from GDB control.  Detaching the

  2517.      process continues its execution.  After the 'detach' command, that

  2518.      process and GDB become completely independent once more, and you

  2519.      are ready to 'attach' another process or start one with 'run'.

  2520.      'detach' does not repeat if you press <RET> again after executing

  2521.      the command.

  2522. 

  2523.    If you exit GDB while you have an attached process, you detach that

  2524. process.  If you use the 'run' command, you kill that process.  By

  2525. default, GDB asks for confirmation if you try to do either of these

  2526. things; you can control whether or not you need to confirm by using the

  2527. 'set confirm' command (*note Optional Warnings and Messages:

  2528. Messages/Warnings.).

  2529. 

  2530. 

  2531. File: gdb.info,  Node: Kill Process,  Next: Inferiors Connections and Programs,  Prev: Attach,  Up: Running

  2532. 

  2533. 4.8 Killing the Child Process

  2534. =============================

  2535. 

  2536. 'kill'

  2537.      Kill the child process in which your program is running under GDB.

  2538. 

  2539.    This command is useful if you wish to debug a core dump instead of a

  2540. running process.  GDB ignores any core dump file while your program is

  2541. running.

  2542. 

  2543.    On some operating systems, a program cannot be executed outside GDB

  2544. while you have breakpoints set on it inside GDB.  You can use the 'kill'

  2545. command in this situation to permit running your program outside the

  2546. debugger.

  2547. 

  2548.    The 'kill' command is also useful if you wish to recompile and relink

  2549. your program, since on many systems it is impossible to modify an

  2550. executable file while it is running in a process.  In this case, when

  2551. you next type 'run', GDB notices that the file has changed, and reads

  2552. the symbol table again (while trying to preserve your current breakpoint

  2553. settings).

  2554. 

  2555. 

  2556. File: gdb.info,  Node: Inferiors Connections and Programs,  Next: Threads,  Prev: Kill Process,  Up: Running

  2557. 

  2558. 4.9 Debugging Multiple Inferiors Connections and Programs

  2559. =========================================================

  2560. 

  2561. GDB lets you run and debug multiple programs in a single session.  In

  2562. addition, GDB on some systems may let you run several programs

  2563. simultaneously (otherwise you have to exit from one before starting

  2564. another).  On some systems GDB may even let you debug several programs

  2565. simultaneously on different remote systems.  In the most general case,

  2566. you can have multiple threads of execution in each of multiple

  2567. processes, launched from multiple executables, running on different

  2568. machines.

  2569. 

  2570.    GDB represents the state of each program execution with an object

  2571. called an "inferior".  An inferior typically corresponds to a process,

  2572. but is more general and applies also to targets that do not have

  2573. processes.  Inferiors may be created before a process runs, and may be

  2574. retained after a process exits.  Inferiors have unique identifiers that

  2575. are different from process ids.  Usually each inferior will also have

  2576. its own distinct address space, although some embedded targets may have

  2577. several inferiors running in different parts of a single address space.

  2578. Each inferior may in turn have multiple threads running in it.

  2579. 

  2580.    To find out what inferiors exist at any moment, use 'info inferiors':

  2581. 

  2582. 'info inferiors'

  2583.      Print a list of all inferiors currently being managed by GDB.  By

  2584.      default all inferiors are printed, but the argument ID... - a space

  2585.      separated list of inferior numbers - can be used to limit the

  2586.      display to just the requested inferiors.

  2587. 

  2588.      GDB displays for each inferior (in this order):

  2589. 

  2590.        1. the inferior number assigned by GDB

  2591. 

  2592.        2. the target system's inferior identifier

  2593. 

  2594.        3. the target connection the inferior is bound to, including the

  2595.           unique connection number assigned by GDB, and the protocol

  2596.           used by the connection.

  2597. 

  2598.        4. the name of the executable the inferior is running.

  2599. 

  2600.      An asterisk '*' preceding the GDB inferior number indicates the

  2601.      current inferior.

  2602. 

  2603.      For example,

  2604. 

  2605.      (gdb) info inferiors

  2606.        Num  Description       Connection                      Executable

  2607.      * 1    process 3401      1 (native)                      goodbye

  2608.        2    process 2307      2 (extended-remote host:10000)  hello

  2609. 

  2610.    To find out what open target connections exist at any moment, use

  2611. 'info connections':

  2612. 

  2613. 'info connections'

  2614.      Print a list of all open target connections currently being managed

  2615.      by GDB.  By default all connections are printed, but the argument

  2616.      ID... - a space separated list of connections numbers - can be used

  2617.      to limit the display to just the requested connections.

  2618. 

  2619.      GDB displays for each connection (in this order):

  2620. 

  2621.        1. the connection number assigned by GDB.

  2622. 

  2623.        2. the protocol used by the connection.

  2624. 

  2625.        3. a textual description of the protocol used by the connection.

  2626. 

  2627.      An asterisk '*' preceding the connection number indicates the

  2628.      connection of the current inferior.

  2629. 

  2630.      For example,

  2631. 

  2632.      (gdb) info connections

  2633.        Num  What                        Description

  2634.      * 1    extended-remote host:10000  Extended remote serial target in gdb-specific protocol

  2635.        2    native                      Native process

  2636.        3    core                        Local core dump file

  2637. 

  2638.    To switch focus between inferiors, use the 'inferior' command:

  2639. 

  2640. 'inferior INFNO'

  2641.      Make inferior number INFNO the current inferior.  The argument

  2642.      INFNO is the inferior number assigned by GDB, as shown in the first

  2643.      field of the 'info inferiors' display.

  2644. 

  2645.    The debugger convenience variable '$_inferior' contains the number of

  2646. the current inferior.  You may find this useful in writing breakpoint

  2647. conditional expressions, command scripts, and so forth.  *Note

  2648. Convenience Variables: Convenience Vars, for general information on

  2649. convenience variables.

  2650. 

  2651.    You can get multiple executables into a debugging session via the

  2652. 'add-inferior' and 'clone-inferior' commands.  On some systems GDB can

  2653. add inferiors to the debug session automatically by following calls to

  2654. 'fork' and 'exec'.  To remove inferiors from the debugging session use

  2655. the 'remove-inferiors' command.

  2656. 

  2657. 'add-inferior [ -copies N ] [ -exec EXECUTABLE ] [-no-connection ]'

  2658.      Adds N inferiors to be run using EXECUTABLE as the executable; N

  2659.      defaults to 1.  If no executable is specified, the inferiors begins

  2660.      empty, with no program.  You can still assign or change the program

  2661.      assigned to the inferior at any time by using the 'file' command

  2662.      with the executable name as its argument.

  2663. 

  2664.      By default, the new inferior begins connected to the same target

  2665.      connection as the current inferior.  For example, if the current

  2666.      inferior was connected to 'gdbserver' with 'target remote', then

  2667.      the new inferior will be connected to the same 'gdbserver'

  2668.      instance.  The '-no-connection' option starts the new inferior with

  2669.      no connection yet.  You can then for example use the 'target

  2670.      remote' command to connect to some other 'gdbserver' instance, use

  2671.      'run' to spawn a local program, etc.

  2672. 

  2673. 'clone-inferior [ -copies N ] [ INFNO ]'

  2674.      Adds N inferiors ready to execute the same program as inferior

  2675.      INFNO; N defaults to 1, and INFNO defaults to the number of the

  2676.      current inferior.  This is a convenient command when you want to

  2677.      run another instance of the inferior you are debugging.

  2678. 

  2679.           (gdb) info inferiors

  2680.             Num  Description       Connection   Executable

  2681.           * 1    process 29964     1 (native)   helloworld

  2682.           (gdb) clone-inferior

  2683.           Added inferior 2.

  2684.           1 inferiors added.

  2685.           (gdb) info inferiors

  2686.             Num  Description       Connection   Executable

  2687.           * 1    process 29964     1 (native)   helloworld

  2688.             2    <null>            1 (native)   helloworld

  2689. 

  2690.      You can now simply switch focus to inferior 2 and run it.

  2691. 

  2692. 'remove-inferiors INFNO...'

  2693.      Removes the inferior or inferiors INFNO....  It is not possible to

  2694.      remove an inferior that is running with this command.  For those,

  2695.      use the 'kill' or 'detach' command first.

  2696. 

  2697.    To quit debugging one of the running inferiors that is not the

  2698. current inferior, you can either detach from it by using the

  2699. 'detach inferior' command (allowing it to run independently), or kill it

  2700. using the 'kill inferiors' command:

  2701. 

  2702. 'detach inferior INFNO...'

  2703.      Detach from the inferior or inferiors identified by GDB inferior

  2704.      number(s) INFNO....  Note that the inferior's entry still stays on

  2705.      the list of inferiors shown by 'info inferiors', but its

  2706.      Description will show '<null>'.

  2707. 

  2708. 'kill inferiors INFNO...'

  2709.      Kill the inferior or inferiors identified by GDB inferior number(s)

  2710.      INFNO....  Note that the inferior's entry still stays on the list

  2711.      of inferiors shown by 'info inferiors', but its Description will

  2712.      show '<null>'.

  2713. 

  2714.    After the successful completion of a command such as 'detach',

  2715. 'detach inferiors', 'kill' or 'kill inferiors', or after a normal

  2716. process exit, the inferior is still valid and listed with 'info

  2717. inferiors', ready to be restarted.

  2718. 

  2719.    To be notified when inferiors are started or exit under GDB's control

  2720. use 'set print inferior-events':

  2721. 

  2722. 'set print inferior-events'

  2723. 'set print inferior-events on'

  2724. 'set print inferior-events off'

  2725.      The 'set print inferior-events' command allows you to enable or

  2726.      disable printing of messages when GDB notices that new inferiors

  2727.      have started or that inferiors have exited or have been detached.

  2728.      By default, these messages will not be printed.

  2729. 

  2730. 'show print inferior-events'

  2731.      Show whether messages will be printed when GDB detects that

  2732.      inferiors have started, exited or have been detached.

  2733. 

  2734.    Many commands will work the same with multiple programs as with a

  2735. single program: e.g., 'print myglobal' will simply display the value of

  2736. 'myglobal' in the current inferior.

  2737. 

  2738.    Occasionally, when debugging GDB itself, it may be useful to get more

  2739. info about the relationship of inferiors, programs, address spaces in a

  2740. debug session.  You can do that with the 'maint info program-spaces'

  2741. command.

  2742. 

  2743. 'maint info program-spaces'

  2744.      Print a list of all program spaces currently being managed by GDB.

  2745. 

  2746.      GDB displays for each program space (in this order):

  2747. 

  2748.        1. the program space number assigned by GDB

  2749. 

  2750.        2. the name of the executable loaded into the program space, with

  2751.           e.g., the 'file' command.

  2752. 

  2753.      An asterisk '*' preceding the GDB program space number indicates

  2754.      the current program space.

  2755. 

  2756.      In addition, below each program space line, GDB prints extra

  2757.      information that isn't suitable to display in tabular form.  For

  2758.      example, the list of inferiors bound to the program space.

  2759. 

  2760.           (gdb) maint info program-spaces

  2761.             Id   Executable

  2762.           * 1    hello

  2763.             2    goodbye

  2764.                   Bound inferiors: ID 1 (process 21561)

  2765. 

  2766.      Here we can see that no inferior is running the program 'hello',

  2767.      while 'process 21561' is running the program 'goodbye'.  On some

  2768.      targets, it is possible that multiple inferiors are bound to the

  2769.      same program space.  The most common example is that of debugging

  2770.      both the parent and child processes of a 'vfork' call.  For

  2771.      example,

  2772. 

  2773.           (gdb) maint info program-spaces

  2774.             Id   Executable

  2775.           * 1    vfork-test

  2776.                   Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)

  2777. 

  2778.      Here, both inferior 2 and inferior 1 are running in the same

  2779.      program space as a result of inferior 1 having executed a 'vfork'

  2780.      call.

  2781. 

  2782. 

  2783. File: gdb.info,  Node: Threads,  Next: Forks,  Prev: Inferiors Connections and Programs,  Up: Running

  2784. 

  2785. 4.10 Debugging Programs with Multiple Threads

  2786. =============================================

  2787. 

  2788. In some operating systems, such as GNU/Linux and Solaris, a single

  2789. program may have more than one "thread" of execution.  The precise

  2790. semantics of threads differ from one operating system to another, but in

  2791. general the threads of a single program are akin to multiple

  2792. processes--except that they share one address space (that is, they can

  2793. all examine and modify the same variables).  On the other hand, each

  2794. thread has its own registers and execution stack, and perhaps private

  2795. memory.

  2796. 

  2797.    GDB provides these facilities for debugging multi-thread programs:

  2798. 

  2799.    * automatic notification of new threads

  2800.    * 'thread THREAD-ID', a command to switch among threads

  2801.    * 'info threads', a command to inquire about existing threads

  2802.    * 'thread apply [THREAD-ID-LIST | all] ARGS', a command to apply a

  2803.      command to a list of threads

  2804.    * thread-specific breakpoints

  2805.    * 'set print thread-events', which controls printing of messages on

  2806.      thread start and exit.

  2807.    * 'set libthread-db-search-path PATH', which lets the user specify

  2808.      which 'libthread_db' to use if the default choice isn't compatible

  2809.      with the program.

  2810. 

  2811.    The GDB thread debugging facility allows you to observe all threads

  2812. while your program runs--but whenever GDB takes control, one thread in

  2813. particular is always the focus of debugging.  This thread is called the

  2814. "current thread".  Debugging commands show program information from the

  2815. perspective of the current thread.

  2816. 

  2817.    Whenever GDB detects a new thread in your program, it displays the

  2818. target system's identification for the thread with a message in the form

  2819. '[New SYSTAG]', where SYSTAG is a thread identifier whose form varies

  2820. depending on the particular system.  For example, on GNU/Linux, you

  2821. might see

  2822. 

  2823.      [New Thread 0x41e02940 (LWP 25582)]

  2824. 

  2825. when GDB notices a new thread.  In contrast, on other systems, the

  2826. SYSTAG is simply something like 'process 368', with no further

  2827. qualifier.

  2828. 

  2829.    For debugging purposes, GDB associates its own thread number --always

  2830. a single integer--with each thread of an inferior.  This number is

  2831. unique between all threads of an inferior, but not unique between

  2832. threads of different inferiors.

  2833. 

  2834.    You can refer to a given thread in an inferior using the qualified

  2835. INFERIOR-NUM.THREAD-NUM syntax, also known as "qualified thread ID",

  2836. with INFERIOR-NUM being the inferior number and THREAD-NUM being the

  2837. thread number of the given inferior.  For example, thread '2.3' refers

  2838. to thread number 3 of inferior 2.  If you omit INFERIOR-NUM (e.g.,

  2839. 'thread 3'), then GDB infers you're referring to a thread of the current

  2840. inferior.

  2841. 

  2842.    Until you create a second inferior, GDB does not show the

  2843. INFERIOR-NUM part of thread IDs, even though you can always use the full

  2844. INFERIOR-NUM.THREAD-NUM form to refer to threads of inferior 1, the

  2845. initial inferior.

  2846. 

  2847.    Some commands accept a space-separated "thread ID list" as argument.

  2848. A list element can be:

  2849. 

  2850.   1. A thread ID as shown in the first field of the 'info threads'

  2851.      display, with or without an inferior qualifier.  E.g., '2.1' or

  2852.      '1'.

  2853. 

  2854.   2. A range of thread numbers, again with or without an inferior

  2855.      qualifier, as in INF.THR1-THR2 or THR1-THR2.  E.g., '1.2-4' or

  2856.      '2-4'.

  2857. 

  2858.   3. All threads of an inferior, specified with a star wildcard, with or

  2859.      without an inferior qualifier, as in INF.'*' (e.g., '1.*') or '*'.

  2860.      The former refers to all threads of the given inferior, and the

  2861.      latter form without an inferior qualifier refers to all threads of

  2862.      the current inferior.

  2863. 

  2864.    For example, if the current inferior is 1, and inferior 7 has one

  2865. thread with ID 7.1, the thread list '1 2-3 4.5 6.7-9 7.*' includes

  2866. threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 7 to 9 of

  2867. inferior 6 and all threads of inferior 7.  That is, in expanded

  2868. qualified form, the same as '1.1 1.2 1.3 4.5 6.7 6.8 6.9 7.1'.

  2869. 

  2870.    In addition to a _per-inferior_ number, each thread is also assigned

  2871. a unique _global_ number, also known as "global thread ID", a single

  2872. integer.  Unlike the thread number component of the thread ID, no two

  2873. threads have the same global ID, even when you're debugging multiple

  2874. inferiors.

  2875. 

  2876.    From GDB's perspective, a process always has at least one thread.  In

  2877. other words, GDB assigns a thread number to the program's "main thread"

  2878. even if the program is not multi-threaded.

  2879. 

  2880.    The debugger convenience variables '$_thread' and '$_gthread'

  2881. contain, respectively, the per-inferior thread number and the global

  2882. thread number of the current thread.  You may find this useful in

  2883. writing breakpoint conditional expressions, command scripts, and so

  2884. forth.  *Note Convenience Variables: Convenience Vars, for general

  2885. information on convenience variables.

  2886. 

  2887.    If GDB detects the program is multi-threaded, it augments the usual

  2888. message about stopping at a breakpoint with the ID and name of the

  2889. thread that hit the breakpoint.

  2890. 

  2891.      Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68

  2892. 

  2893.    Likewise when the program receives a signal:

  2894. 

  2895.      Thread 1 "main" received signal SIGINT, Interrupt.

  2896. 

  2897. 'info threads [THREAD-ID-LIST]'

  2898. 

  2899.      Display information about one or more threads.  With no arguments

  2900.      displays information about all threads.  You can specify the list

  2901.      of threads that you want to display using the thread ID list syntax

  2902.      (*note thread ID lists::).

  2903. 

  2904.      GDB displays for each thread (in this order):

  2905. 

  2906.        1. the per-inferior thread number assigned by GDB

  2907. 

  2908.        2. the global thread number assigned by GDB, if the '-gid' option

  2909.           was specified

  2910. 

  2911.        3. the target system's thread identifier (SYSTAG)

  2912. 

  2913.        4. the thread's name, if one is known.  A thread can either be

  2914.           named by the user (see 'thread name', below), or, in some

  2915.           cases, by the program itself.

  2916. 

  2917.        5. the current stack frame summary for that thread

  2918. 

  2919.      An asterisk '*' to the left of the GDB thread number indicates the

  2920.      current thread.

  2921. 

  2922.      For example,

  2923. 

  2924.      (gdb) info threads

  2925.        Id   Target Id             Frame

  2926.      * 1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)

  2927.        2    process 35 thread 23  0x34e5 in sigpause ()

  2928.        3    process 35 thread 27  0x34e5 in sigpause ()

  2929.          at threadtest.c:68

  2930. 

  2931.    If you're debugging multiple inferiors, GDB displays thread IDs using

  2932. the qualified INFERIOR-NUM.THREAD-NUM format.  Otherwise, only

  2933. THREAD-NUM is shown.

  2934. 

  2935.    If you specify the '-gid' option, GDB displays a column indicating

  2936. each thread's global thread ID:

  2937. 

  2938.      (gdb) info threads

  2939.        Id   GId  Target Id             Frame

  2940.        1.1  1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)

  2941.        1.2  3    process 35 thread 23  0x34e5 in sigpause ()

  2942.        1.3  4    process 35 thread 27  0x34e5 in sigpause ()

  2943.      * 2.1  2    process 65 thread 1   main (argc=1, argv=0x7ffffff8)

  2944. 

  2945.    On Solaris, you can display more information about user threads with

  2946. a Solaris-specific command:

  2947. 

  2948. 'maint info sol-threads'

  2949.      Display info on Solaris user threads.

  2950. 

  2951. 'thread THREAD-ID'

  2952.      Make thread ID THREAD-ID the current thread.  The command argument

  2953.      THREAD-ID is the GDB thread ID, as shown in the first field of the

  2954.      'info threads' display, with or without an inferior qualifier

  2955.      (e.g., '2.1' or '1').

  2956. 

  2957.      GDB responds by displaying the system identifier of the thread you

  2958.      selected, and its current stack frame summary:

  2959. 

  2960.           (gdb) thread 2

  2961.           [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]

  2962.           #0  some_function (ignore=0x0) at example.c:8

  2963.           8	    printf ("hello\n");

  2964. 

  2965.      As with the '[New ...]' message, the form of the text after

  2966.      'Switching to' depends on your system's conventions for identifying

  2967.      threads.

  2968. 

  2969. 'thread apply [THREAD-ID-LIST | all [-ascending]] [FLAG]... COMMAND'

  2970.      The 'thread apply' command allows you to apply the named COMMAND to

  2971.      one or more threads.  Specify the threads that you want affected

  2972.      using the thread ID list syntax (*note thread ID lists::), or

  2973.      specify 'all' to apply to all threads.  To apply a command to all

  2974.      threads in descending order, type 'thread apply all COMMAND'.  To

  2975.      apply a command to all threads in ascending order, type 'thread

  2976.      apply all -ascending COMMAND'.

  2977. 

  2978.      The FLAG arguments control what output to produce and how to handle

  2979.      errors raised when applying COMMAND to a thread.  FLAG must start

  2980.      with a '-' directly followed by one letter in 'qcs'.  If several

  2981.      flags are provided, they must be given individually, such as '-c

  2982.      -q'.

  2983. 

  2984.      By default, GDB displays some thread information before the output

  2985.      produced by COMMAND, and an error raised during the execution of a

  2986.      COMMAND will abort 'thread apply'.  The following flags can be used

  2987.      to fine-tune this behavior:

  2988. 

  2989.      '-c'

  2990.           The flag '-c', which stands for 'continue', causes any errors

  2991.           in COMMAND to be displayed, and the execution of 'thread

  2992.           apply' then continues.

  2993.      '-s'

  2994.           The flag '-s', which stands for 'silent', causes any errors or

  2995.           empty output produced by a COMMAND to be silently ignored.

  2996.           That is, the execution continues, but the thread information

  2997.           and errors are not printed.

  2998.      '-q'

  2999.           The flag '-q' ('quiet') disables printing the thread

  3000.           information.

  3001. 

  3002.      Flags '-c' and '-s' cannot be used together.

  3003. 

  3004. 'taas [OPTION]... COMMAND'

  3005.      Shortcut for 'thread apply all -s [OPTION]... COMMAND'.  Applies

  3006.      COMMAND on all threads, ignoring errors and empty output.

  3007. 

  3008.      The 'taas' command accepts the same options as the 'thread apply

  3009.      all' command.  *Note thread apply all::.

  3010. 

  3011. 'tfaas [OPTION]... COMMAND'

  3012.      Shortcut for 'thread apply all -s -- frame apply all -s [OPTION]...

  3013.      COMMAND'.  Applies COMMAND on all frames of all threads, ignoring

  3014.      errors and empty output.  Note that the flag '-s' is specified

  3015.      twice: The first '-s' ensures that 'thread apply' only shows the

  3016.      thread information of the threads for which 'frame apply' produces

  3017.      some output.  The second '-s' is needed to ensure that 'frame

  3018.      apply' shows the frame information of a frame only if the COMMAND

  3019.      successfully produced some output.

  3020. 

  3021.      It can for example be used to print a local variable or a function

  3022.      argument without knowing the thread or frame where this variable or

  3023.      argument is, using:

  3024.           (gdb) tfaas p some_local_var_i_do_not_remember_where_it_is

  3025. 

  3026.      The 'tfaas' command accepts the same options as the 'frame apply'

  3027.      command.  *Note frame apply: Frame Apply.

  3028. 

  3029. 'thread name [NAME]'

  3030.      This command assigns a name to the current thread.  If no argument

  3031.      is given, any existing user-specified name is removed.  The thread

  3032.      name appears in the 'info threads' display.

  3033. 

  3034.      On some systems, such as GNU/Linux, GDB is able to determine the

  3035.      name of the thread as given by the OS. On these systems, a name

  3036.      specified with 'thread name' will override the system-give name,

  3037.      and removing the user-specified name will cause GDB to once again

  3038.      display the system-specified name.

  3039. 

  3040. 'thread find [REGEXP]'

  3041.      Search for and display thread ids whose name or SYSTAG matches the

  3042.      supplied regular expression.

  3043. 

  3044.      As well as being the complement to the 'thread name' command, this

  3045.      command also allows you to identify a thread by its target SYSTAG.

  3046.      For instance, on GNU/Linux, the target SYSTAG is the LWP id.

  3047. 

  3048.           (GDB) thread find 26688

  3049.           Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'

  3050.           (GDB) info thread 4

  3051.             Id   Target Id         Frame

  3052.             4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()

  3053. 

  3054. 'set print thread-events'

  3055. 'set print thread-events on'

  3056. 'set print thread-events off'

  3057.      The 'set print thread-events' command allows you to enable or

  3058.      disable printing of messages when GDB notices that new threads have

  3059.      started or that threads have exited.  By default, these messages

  3060.      will be printed if detection of these events is supported by the

  3061.      target.  Note that these messages cannot be disabled on all

  3062.      targets.

  3063. 

  3064. 'show print thread-events'

  3065.      Show whether messages will be printed when GDB detects that threads

  3066.      have started and exited.

  3067. 

  3068.    *Note Stopping and Starting Multi-thread Programs: Thread Stops, for

  3069. more information about how GDB behaves when you stop and start programs

  3070. with multiple threads.

  3071. 

  3072.    *Note Setting Watchpoints: Set Watchpoints, for information about

  3073. watchpoints in programs with multiple threads.

  3074. 

  3075. 'set libthread-db-search-path [PATH]'

  3076.      If this variable is set, PATH is a colon-separated list of

  3077.      directories GDB will use to search for 'libthread_db'.  If you omit

  3078.      PATH, 'libthread-db-search-path' will be reset to its default value

  3079.      ('$sdir:$pdir' on GNU/Linux and Solaris systems).  Internally, the

  3080.      default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro.

  3081. 

  3082.      On GNU/Linux and Solaris systems, GDB uses a "helper"

  3083.      'libthread_db' library to obtain information about threads in the

  3084.      inferior process.  GDB will use 'libthread-db-search-path' to find

  3085.      'libthread_db'.  GDB also consults first if inferior specific

  3086.      thread debugging library loading is enabled by 'set auto-load

  3087.      libthread-db' (*note libthread_db.so.1 file::).

  3088. 

  3089.      A special entry '$sdir' for 'libthread-db-search-path' refers to

  3090.      the default system directories that are normally searched for

  3091.      loading shared libraries.  The '$sdir' entry is the only kind not

  3092.      needing to be enabled by 'set auto-load libthread-db' (*note

  3093.      libthread_db.so.1 file::).

  3094. 

  3095.      A special entry '$pdir' for 'libthread-db-search-path' refers to

  3096.      the directory from which 'libpthread' was loaded in the inferior

  3097.      process.

  3098. 

  3099.      For any 'libthread_db' library GDB finds in above directories, GDB

  3100.      attempts to initialize it with the current inferior process.  If

  3101.      this initialization fails (which could happen because of a version

  3102.      mismatch between 'libthread_db' and 'libpthread'), GDB will unload

  3103.      'libthread_db', and continue with the next directory.  If none of

  3104.      'libthread_db' libraries initialize successfully, GDB will issue a

  3105.      warning and thread debugging will be disabled.

  3106. 

  3107.      Setting 'libthread-db-search-path' is currently implemented only on

  3108.      some platforms.

  3109. 

  3110. 'show libthread-db-search-path'

  3111.      Display current libthread_db search path.

  3112. 

  3113. 'set debug libthread-db'

  3114. 'show debug libthread-db'

  3115.      Turns on or off display of 'libthread_db'-related events.  Use '1'

  3116.      to enable, '0' to disable.

  3117. 

  3118. 

  3119. File: gdb.info,  Node: Forks,  Next: Checkpoint/Restart,  Prev: Threads,  Up: Running

  3120. 

  3121. 4.11 Debugging Forks

  3122. ====================

  3123. 

  3124. On most systems, GDB has no special support for debugging programs which

  3125. create additional processes using the 'fork' function.  When a program

  3126. forks, GDB will continue to debug the parent process and the child

  3127. process will run unimpeded.  If you have set a breakpoint in any code

  3128. which the child then executes, the child will get a 'SIGTRAP' signal

  3129. which (unless it catches the signal) will cause it to terminate.

  3130. 

  3131.    However, if you want to debug the child process there is a workaround

  3132. which isn't too painful.  Put a call to 'sleep' in the code which the

  3133. child process executes after the fork.  It may be useful to sleep only

  3134. if a certain environment variable is set, or a certain file exists, so

  3135. that the delay need not occur when you don't want to run GDB on the

  3136. child.  While the child is sleeping, use the 'ps' program to get its

  3137. process ID. Then tell GDB (a new invocation of GDB if you are also

  3138. debugging the parent process) to attach to the child process (*note

  3139. Attach::).  From that point on you can debug the child process just like

  3140. any other process which you attached to.

  3141. 

  3142.    On some systems, GDB provides support for debugging programs that

  3143. create additional processes using the 'fork' or 'vfork' functions.  On

  3144. GNU/Linux platforms, this feature is supported with kernel version

  3145. 2.5.46 and later.

  3146. 

  3147.    The fork debugging commands are supported in native mode and when

  3148. connected to 'gdbserver' in either 'target remote' mode or 'target

  3149. extended-remote' mode.

  3150. 

  3151.    By default, when a program forks, GDB will continue to debug the

  3152. parent process and the child process will run unimpeded.

  3153. 

  3154.    If you want to follow the child process instead of the parent

  3155. process, use the command 'set follow-fork-mode'.

  3156. 

  3157. 'set follow-fork-mode MODE'

  3158.      Set the debugger response to a program call of 'fork' or 'vfork'.

  3159.      A call to 'fork' or 'vfork' creates a new process.  The MODE

  3160.      argument can be:

  3161. 

  3162.      'parent'

  3163.           The original process is debugged after a fork.  The child

  3164.           process runs unimpeded.  This is the default.

  3165. 

  3166.      'child'

  3167.           The new process is debugged after a fork.  The parent process

  3168.           runs unimpeded.

  3169. 

  3170. 'show follow-fork-mode'

  3171.      Display the current debugger response to a 'fork' or 'vfork' call.

  3172. 

  3173.    On Linux, if you want to debug both the parent and child processes,

  3174. use the command 'set detach-on-fork'.

  3175. 

  3176. 'set detach-on-fork MODE'

  3177.      Tells gdb whether to detach one of the processes after a fork, or

  3178.      retain debugger control over them both.

  3179. 

  3180.      'on'

  3181.           The child process (or parent process, depending on the value

  3182.           of 'follow-fork-mode') will be detached and allowed to run

  3183.           independently.  This is the default.

  3184. 

  3185.      'off'

  3186.           Both processes will be held under the control of GDB.  One

  3187.           process (child or parent, depending on the value of

  3188.           'follow-fork-mode') is debugged as usual, while the other is

  3189.           held suspended.

  3190. 

  3191. 'show detach-on-fork'

  3192.      Show whether detach-on-fork mode is on/off.

  3193. 

  3194.    If you choose to set 'detach-on-fork' mode off, then GDB will retain

  3195. control of all forked processes (including nested forks).  You can list

  3196. the forked processes under the control of GDB by using the

  3197. 'info inferiors' command, and switch from one fork to another by using

  3198. the 'inferior' command (*note Debugging Multiple Inferiors Connections

  3199. and Programs: Inferiors Connections and Programs.).

  3200. 

  3201.    To quit debugging one of the forked processes, you can either detach

  3202. from it by using the 'detach inferiors' command (allowing it to run

  3203. independently), or kill it using the 'kill inferiors' command.  *Note

  3204. Debugging Multiple Inferiors Connections and Programs: Inferiors

  3205. Connections and Programs.

  3206. 

  3207.    If you ask to debug a child process and a 'vfork' is followed by an

  3208. 'exec', GDB executes the new target up to the first breakpoint in the

  3209. new target.  If you have a breakpoint set on 'main' in your original

  3210. program, the breakpoint will also be set on the child process's 'main'.

  3211. 

  3212.    On some systems, when a child process is spawned by 'vfork', you

  3213. cannot debug the child or parent until an 'exec' call completes.

  3214. 

  3215.    If you issue a 'run' command to GDB after an 'exec' call executes,

  3216. the new target restarts.  To restart the parent process, use the 'file'

  3217. command with the parent executable name as its argument.  By default,

  3218. after an 'exec' call executes, GDB discards the symbols of the previous

  3219. executable image.  You can change this behaviour with the

  3220. 'set follow-exec-mode' command.

  3221. 

  3222. 'set follow-exec-mode MODE'

  3223. 

  3224.      Set debugger response to a program call of 'exec'.  An 'exec' call

  3225.      replaces the program image of a process.

  3226. 

  3227.      'follow-exec-mode' can be:

  3228. 

  3229.      'new'

  3230.           GDB creates a new inferior and rebinds the process to this new

  3231.           inferior.  The program the process was running before the

  3232.           'exec' call can be restarted afterwards by restarting the

  3233.           original inferior.

  3234. 

  3235.           For example:

  3236. 

  3237.                (gdb) info inferiors

  3238.                (gdb) info inferior

  3239.                  Id   Description   Executable

  3240.                * 1    <null>        prog1

  3241.                (gdb) run

  3242.                process 12020 is executing new program: prog2

  3243.                Program exited normally.

  3244.                (gdb) info inferiors

  3245.                  Id   Description   Executable

  3246.                  1    <null>        prog1

  3247.                * 2    <null>        prog2

  3248. 

  3249.      'same'

  3250.           GDB keeps the process bound to the same inferior.  The new

  3251.           executable image replaces the previous executable loaded in

  3252.           the inferior.  Restarting the inferior after the 'exec' call,

  3253.           with e.g., the 'run' command, restarts the executable the

  3254.           process was running after the 'exec' call.  This is the

  3255.           default mode.

  3256. 

  3257.           For example:

  3258. 

  3259.                (gdb) info inferiors

  3260.                  Id   Description   Executable

  3261.                * 1    <null>        prog1

  3262.                (gdb) run

  3263.                process 12020 is executing new program: prog2

  3264.                Program exited normally.

  3265.                (gdb) info inferiors

  3266.                  Id   Description   Executable

  3267.                * 1    <null>        prog2

  3268. 

  3269.    'follow-exec-mode' is supported in native mode and 'target

  3270. extended-remote' mode.

  3271. 

  3272.    You can use the 'catch' command to make GDB stop whenever a 'fork',

  3273. 'vfork', or 'exec' call is made.  *Note Setting Catchpoints: Set

  3274. Catchpoints.

  3275. 

  3276. 

  3277. File: gdb.info,  Node: Checkpoint/Restart,  Prev: Forks,  Up: Running

  3278. 

  3279. 4.12 Setting a _Bookmark_ to Return to Later

  3280. ============================================

  3281. 

  3282. On certain operating systems(1), GDB is able to save a "snapshot" of a

  3283. program's state, called a "checkpoint", and come back to it later.

  3284. 

  3285.    Returning to a checkpoint effectively undoes everything that has

  3286. happened in the program since the 'checkpoint' was saved.  This includes

  3287. changes in memory, registers, and even (within some limits) system

  3288. state.  Effectively, it is like going back in time to the moment when

  3289. the checkpoint was saved.

  3290. 

  3291.    Thus, if you're stepping thru a program and you think you're getting

  3292. close to the point where things go wrong, you can save a checkpoint.

  3293. Then, if you accidentally go too far and miss the critical statement,

  3294. instead of having to restart your program from the beginning, you can

  3295. just go back to the checkpoint and start again from there.

  3296. 

  3297.    This can be especially useful if it takes a lot of time or steps to

  3298. reach the point where you think the bug occurs.

  3299. 

  3300.    To use the 'checkpoint'/'restart' method of debugging:

  3301. 

  3302. 'checkpoint'

  3303.      Save a snapshot of the debugged program's current execution state.

  3304.      The 'checkpoint' command takes no arguments, but each checkpoint is

  3305.      assigned a small integer id, similar to a breakpoint id.

  3306. 

  3307. 'info checkpoints'

  3308.      List the checkpoints that have been saved in the current debugging

  3309.      session.  For each checkpoint, the following information will be

  3310.      listed:

  3311. 

  3312.      'Checkpoint ID'

  3313.      'Process ID'

  3314.      'Code Address'

  3315.      'Source line, or label'

  3316. 

  3317. 'restart CHECKPOINT-ID'

  3318.      Restore the program state that was saved as checkpoint number

  3319.      CHECKPOINT-ID.  All program variables, registers, stack frames etc.

  3320.      will be returned to the values that they had when the checkpoint

  3321.      was saved.  In essence, gdb will "wind back the clock" to the point

  3322.      in time when the checkpoint was saved.

  3323. 

  3324.      Note that breakpoints, GDB variables, command history etc.  are not

  3325.      affected by restoring a checkpoint.  In general, a checkpoint only

  3326.      restores things that reside in the program being debugged, not in

  3327.      the debugger.

  3328. 

  3329. 'delete checkpoint CHECKPOINT-ID'

  3330.      Delete the previously-saved checkpoint identified by CHECKPOINT-ID.

  3331. 

  3332.    Returning to a previously saved checkpoint will restore the user

  3333. state of the program being debugged, plus a significant subset of the

  3334. system (OS) state, including file pointers.  It won't "un-write" data

  3335. from a file, but it will rewind the file pointer to the previous

  3336. location, so that the previously written data can be overwritten.  For

  3337. files opened in read mode, the pointer will also be restored so that the

  3338. previously read data can be read again.

  3339. 

  3340.    Of course, characters that have been sent to a printer (or other

  3341. external device) cannot be "snatched back", and characters received from

  3342. eg. a serial device can be removed from internal program buffers, but

  3343. they cannot be "pushed back" into the serial pipeline, ready to be

  3344. received again.  Similarly, the actual contents of files that have been

  3345. changed cannot be restored (at this time).

  3346. 

  3347.    However, within those constraints, you actually can "rewind" your

  3348. program to a previously saved point in time, and begin debugging it

  3349. again -- and you can change the course of events so as to debug a

  3350. different execution path this time.

  3351. 

  3352.    Finally, there is one bit of internal program state that will be

  3353. different when you return to a checkpoint -- the program's process id.

  3354. Each checkpoint will have a unique process id (or PID), and each will be

  3355. different from the program's original PID.  If your program has saved a

  3356. local copy of its process id, this could potentially pose a problem.

  3357. 

  3358. 4.12.1 A Non-obvious Benefit of Using Checkpoints

  3359. -------------------------------------------------

  3360. 

  3361. On some systems such as GNU/Linux, address space randomization is

  3362. performed on new processes for security reasons.  This makes it

  3363. difficult or impossible to set a breakpoint, or watchpoint, on an

  3364. absolute address if you have to restart the program, since the absolute

  3365. location of a symbol will change from one execution to the next.

  3366. 

  3367.    A checkpoint, however, is an _identical_ copy of a process.

  3368. Therefore if you create a checkpoint at (eg.) the start of main, and

  3369. simply return to that checkpoint instead of restarting the process, you

  3370. can avoid the effects of address randomization and your symbols will all

  3371. stay in the same place.

  3372. 

  3373.    ---------- Footnotes ----------

  3374. 

  3375.    (1) Currently, only GNU/Linux.

  3376. 

  3377. 

  3378. File: gdb.info,  Node: Stopping,  Next: Reverse Execution,  Prev: Running,  Up: Top

  3379. 

  3380. 5 Stopping and Continuing

  3381. *************************

  3382. 

  3383. The principal purposes of using a debugger are so that you can stop your

  3384. program before it terminates; or so that, if your program runs into

  3385. trouble, you can investigate and find out why.

  3386. 

  3387.    Inside GDB, your program may stop for any of several reasons, such as

  3388. a signal, a breakpoint, or reaching a new line after a GDB command such

  3389. as 'step'.  You may then examine and change variables, set new

  3390. breakpoints or remove old ones, and then continue execution.  Usually,

  3391. the messages shown by GDB provide ample explanation of the status of

  3392. your program--but you can also explicitly request this information at

  3393. any time.

  3394. 

  3395. 'info program'

  3396.      Display information about the status of your program: whether it is

  3397.      running or not, what process it is, and why it stopped.

  3398. 

  3399. * Menu:

  3400. 

  3401. * Breakpoints::                 Breakpoints, watchpoints, and catchpoints

  3402. * Continuing and Stepping::     Resuming execution

  3403. * Skipping Over Functions and Files::

  3404.                                 Skipping over functions and files

  3405. * Signals::                     Signals

  3406. * Thread Stops::                Stopping and starting multi-thread programs

  3407. 

  3408. 

  3409. File: gdb.info,  Node: Breakpoints,  Next: Continuing and Stepping,  Up: Stopping

  3410. 

  3411. 5.1 Breakpoints, Watchpoints, and Catchpoints

  3412. =============================================

  3413. 

  3414. A "breakpoint" makes your program stop whenever a certain point in the

  3415. program is reached.  For each breakpoint, you can add conditions to

  3416. control in finer detail whether your program stops.  You can set

  3417. breakpoints with the 'break' command and its variants (*note Setting

  3418. Breakpoints: Set Breaks.), to specify the place where your program

  3419. should stop by line number, function name or exact address in the

  3420. program.

  3421. 

  3422.    On some systems, you can set breakpoints in shared libraries before

  3423. the executable is run.

  3424. 

  3425.    A "watchpoint" is a special breakpoint that stops your program when

  3426. the value of an expression changes.  The expression may be a value of a

  3427. variable, or it could involve values of one or more variables combined

  3428. by operators, such as 'a + b'.  This is sometimes called "data

  3429. breakpoints".  You must use a different command to set watchpoints

  3430. (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you

  3431. can manage a watchpoint like any other breakpoint: you enable, disable,

  3432. and delete both breakpoints and watchpoints using the same commands.

  3433. 

  3434.    You can arrange to have values from your program displayed

  3435. automatically whenever GDB stops at a breakpoint.  *Note Automatic

  3436. Display: Auto Display.

  3437. 

  3438.    A "catchpoint" is another special breakpoint that stops your program

  3439. when a certain kind of event occurs, such as the throwing of a C++

  3440. exception or the loading of a library.  As with watchpoints, you use a

  3441. different command to set a catchpoint (*note Setting Catchpoints: Set

  3442. Catchpoints.), but aside from that, you can manage a catchpoint like any

  3443. other breakpoint.  (To stop when your program receives a signal, use the

  3444. 'handle' command; see *note Signals: Signals.)

  3445. 

  3446.    GDB assigns a number to each breakpoint, watchpoint, or catchpoint

  3447. when you create it; these numbers are successive integers starting with

  3448. one.  In many of the commands for controlling various features of

  3449. breakpoints you use the breakpoint number to say which breakpoint you

  3450. want to change.  Each breakpoint may be "enabled" or "disabled"; if

  3451. disabled, it has no effect on your program until you enable it again.

  3452. 

  3453.    Some GDB commands accept a space-separated list of breakpoints on

  3454. which to operate.  A list element can be either a single breakpoint

  3455. number, like '5', or a range of such numbers, like '5-7'.  When a

  3456. breakpoint list is given to a command, all breakpoints in that list are

  3457. operated on.

  3458. 

  3459. * Menu:

  3460. 

  3461. * Set Breaks::                  Setting breakpoints

  3462. * Set Watchpoints::             Setting watchpoints

  3463. * Set Catchpoints::             Setting catchpoints

  3464. * Delete Breaks::               Deleting breakpoints

  3465. * Disabling::                   Disabling breakpoints

  3466. * Conditions::                  Break conditions

  3467. * Break Commands::              Breakpoint command lists

  3468. * Dynamic Printf::              Dynamic printf

  3469. * Save Breakpoints::            How to save breakpoints in a file

  3470. * Static Probe Points::         Listing static probe points

  3471. * Error in Breakpoints::        "Cannot insert breakpoints"

  3472. * Breakpoint-related Warnings:: "Breakpoint address adjusted..."

  3473. 

  3474. 

  3475. File: gdb.info,  Node: Set Breaks,  Next: Set Watchpoints,  Up: Breakpoints

  3476. 

  3477. 5.1.1 Setting Breakpoints

  3478. -------------------------

  3479. 

  3480. Breakpoints are set with the 'break' command (abbreviated 'b').  The

  3481. debugger convenience variable '$bpnum' records the number of the

  3482. breakpoint you've set most recently; see *note Convenience Variables:

  3483. Convenience Vars, for a discussion of what you can do with convenience

  3484. variables.

  3485. 

  3486. 'break LOCATION'

  3487.      Set a breakpoint at the given LOCATION, which can specify a

  3488.      function name, a line number, or an address of an instruction.

  3489.      (*Note Specify Location::, for a list of all the possible ways to

  3490.      specify a LOCATION.)  The breakpoint will stop your program just

  3491.      before it executes any of the code in the specified LOCATION.

  3492. 

  3493.      When using source languages that permit overloading of symbols,

  3494.      such as C++, a function name may refer to more than one possible

  3495.      place to break.  *Note Ambiguous Expressions: Ambiguous

  3496.      Expressions, for a discussion of that situation.

  3497. 

  3498.      It is also possible to insert a breakpoint that will stop the

  3499.      program only if a specific thread (*note Thread-Specific

  3500.      Breakpoints::) or a specific task (*note Ada Tasks::) hits that

  3501.      breakpoint.

  3502. 

  3503. 'break'

  3504.      When called without any arguments, 'break' sets a breakpoint at the

  3505.      next instruction to be executed in the selected stack frame (*note

  3506.      Examining the Stack: Stack.).  In any selected frame but the

  3507.      innermost, this makes your program stop as soon as control returns

  3508.      to that frame.  This is similar to the effect of a 'finish' command

  3509.      in the frame inside the selected frame--except that 'finish' does

  3510.      not leave an active breakpoint.  If you use 'break' without an

  3511.      argument in the innermost frame, GDB stops the next time it reaches

  3512.      the current location; this may be useful inside loops.

  3513. 

  3514.      GDB normally ignores breakpoints when it resumes execution, until

  3515.      at least one instruction has been executed.  If it did not do this,

  3516.      you would be unable to proceed past a breakpoint without first

  3517.      disabling the breakpoint.  This rule applies whether or not the

  3518.      breakpoint already existed when your program stopped.

  3519. 

  3520. 'break ... if COND'

  3521.      Set a breakpoint with condition COND; evaluate the expression COND

  3522.      each time the breakpoint is reached, and stop only if the value is

  3523.      nonzero--that is, if COND evaluates as true.  '...' stands for one

  3524.      of the possible arguments described above (or no argument)

  3525.      specifying where to break.  *Note Break Conditions: Conditions, for

  3526.      more information on breakpoint conditions.

  3527. 

  3528. 'tbreak ARGS'

  3529.      Set a breakpoint enabled only for one stop.  The ARGS are the same

  3530.      as for the 'break' command, and the breakpoint is set in the same

  3531.      way, but the breakpoint is automatically deleted after the first

  3532.      time your program stops there.  *Note Disabling Breakpoints:

  3533.      Disabling.

  3534. 

  3535. 'hbreak ARGS'

  3536.      Set a hardware-assisted breakpoint.  The ARGS are the same as for

  3537.      the 'break' command and the breakpoint is set in the same way, but

  3538.      the breakpoint requires hardware support and some target hardware

  3539.      may not have this support.  The main purpose of this is EPROM/ROM

  3540.      code debugging, so you can set a breakpoint at an instruction

  3541.      without changing the instruction.  This can be used with the new

  3542.      trap-generation provided by SPARClite DSU and most x86-based

  3543.      targets.  These targets will generate traps when a program accesses

  3544.      some data or instruction address that is assigned to the debug

  3545.      registers.  However the hardware breakpoint registers can take a

  3546.      limited number of breakpoints.  For example, on the DSU, only two

  3547.      data breakpoints can be set at a time, and GDB will reject this

  3548.      command if more than two are used.  Delete or disable unused

  3549.      hardware breakpoints before setting new ones (*note Disabling

  3550.      Breakpoints: Disabling.).  *Note Break Conditions: Conditions.  For

  3551.      remote targets, you can restrict the number of hardware breakpoints

  3552.      GDB will use, see *note set remote hardware-breakpoint-limit::.

  3553. 

  3554. 'thbreak ARGS'

  3555.      Set a hardware-assisted breakpoint enabled only for one stop.  The

  3556.      ARGS are the same as for the 'hbreak' command and the breakpoint is

  3557.      set in the same way.  However, like the 'tbreak' command, the

  3558.      breakpoint is automatically deleted after the first time your

  3559.      program stops there.  Also, like the 'hbreak' command, the

  3560.      breakpoint requires hardware support and some target hardware may

  3561.      not have this support.  *Note Disabling Breakpoints: Disabling.

  3562.      See also *note Break Conditions: Conditions.

  3563. 

  3564. 'rbreak REGEX'

  3565.      Set breakpoints on all functions matching the regular expression

  3566.      REGEX.  This command sets an unconditional breakpoint on all

  3567.      matches, printing a list of all breakpoints it set.  Once these

  3568.      breakpoints are set, they are treated just like the breakpoints set

  3569.      with the 'break' command.  You can delete them, disable them, or

  3570.      make them conditional the same way as any other breakpoint.

  3571. 

  3572.      In programs using different languages, GDB chooses the syntax to

  3573.      print the list of all breakpoints it sets according to the 'set

  3574.      language' value: using 'set language auto' (see *note Set Language

  3575.      Automatically: Automatically.) means to use the language of the

  3576.      breakpoint's function, other values mean to use the manually

  3577.      specified language (see *note Set Language Manually: Manually.).

  3578. 

  3579.      The syntax of the regular expression is the standard one used with

  3580.      tools like 'grep'.  Note that this is different from the syntax

  3581.      used by shells, so for instance 'foo*' matches all functions that

  3582.      include an 'fo' followed by zero or more 'o's.  There is an

  3583.      implicit '.*' leading and trailing the regular expression you

  3584.      supply, so to match only functions that begin with 'foo', use

  3585.      '^foo'.

  3586. 

  3587.      When debugging C++ programs, 'rbreak' is useful for setting

  3588.      breakpoints on overloaded functions that are not members of any

  3589.      special classes.

  3590. 

  3591.      The 'rbreak' command can be used to set breakpoints in *all* the

  3592.      functions in a program, like this:

  3593. 

  3594.           (gdb) rbreak .

  3595. 

  3596. 'rbreak FILE:REGEX'

  3597.      If 'rbreak' is called with a filename qualification, it limits the

  3598.      search for functions matching the given regular expression to the

  3599.      specified FILE.  This can be used, for example, to set breakpoints

  3600.      on every function in a given file:

  3601. 

  3602.           (gdb) rbreak file.c:.

  3603. 

  3604.      The colon separating the filename qualifier from the regex may

  3605.      optionally be surrounded by spaces.

  3606. 

  3607. 'info breakpoints [LIST...]'

  3608. 'info break [LIST...]'

  3609.      Print a table of all breakpoints, watchpoints, and catchpoints set

  3610.      and not deleted.  Optional argument N means print information only

  3611.      about the specified breakpoint(s) (or watchpoint(s) or

  3612.      catchpoint(s)).  For each breakpoint, following columns are

  3613.      printed:

  3614. 

  3615.      _Breakpoint Numbers_

  3616.      _Type_

  3617.           Breakpoint, watchpoint, or catchpoint.

  3618.      _Disposition_

  3619.           Whether the breakpoint is marked to be disabled or deleted

  3620.           when hit.

  3621.      _Enabled or Disabled_

  3622.           Enabled breakpoints are marked with 'y'.  'n' marks

  3623.           breakpoints that are not enabled.

  3624.      _Address_

  3625.           Where the breakpoint is in your program, as a memory address.

  3626.           For a pending breakpoint whose address is not yet known, this

  3627.           field will contain '<PENDING>'.  Such breakpoint won't fire

  3628.           until a shared library that has the symbol or line referred by

  3629.           breakpoint is loaded.  See below for details.  A breakpoint

  3630.           with several locations will have '<MULTIPLE>' in this

  3631.           field--see below for details.

  3632.      _What_

  3633.           Where the breakpoint is in the source for your program, as a

  3634.           file and line number.  For a pending breakpoint, the original

  3635.           string passed to the breakpoint command will be listed as it

  3636.           cannot be resolved until the appropriate shared library is

  3637.           loaded in the future.

  3638. 

  3639.      If a breakpoint is conditional, there are two evaluation modes:

  3640.      "host" and "target".  If mode is "host", breakpoint condition

  3641.      evaluation is done by GDB on the host's side.  If it is "target",

  3642.      then the condition is evaluated by the target.  The 'info break'

  3643.      command shows the condition on the line following the affected

  3644.      breakpoint, together with its condition evaluation mode in between

  3645.      parentheses.

  3646. 

  3647.      Breakpoint commands, if any, are listed after that.  A pending

  3648.      breakpoint is allowed to have a condition specified for it.  The

  3649.      condition is not parsed for validity until a shared library is

  3650.      loaded that allows the pending breakpoint to resolve to a valid

  3651.      location.

  3652. 

  3653.      'info break' with a breakpoint number N as argument lists only that

  3654.      breakpoint.  The convenience variable '$_' and the default

  3655.      examining-address for the 'x' command are set to the address of the

  3656.      last breakpoint listed (*note Examining Memory: Memory.).

  3657. 

  3658.      'info break' displays a count of the number of times the breakpoint

  3659.      has been hit.  This is especially useful in conjunction with the

  3660.      'ignore' command.  You can ignore a large number of breakpoint

  3661.      hits, look at the breakpoint info to see how many times the

  3662.      breakpoint was hit, and then run again, ignoring one less than that

  3663.      number.  This will get you quickly to the last hit of that

  3664.      breakpoint.

  3665. 

  3666.      For a breakpoints with an enable count (xref) greater than 1, 'info

  3667.      break' also displays that count.

  3668. 

  3669.    GDB allows you to set any number of breakpoints at the same place in

  3670. your program.  There is nothing silly or meaningless about this.  When

  3671. the breakpoints are conditional, this is even useful (*note Break

  3672. Conditions: Conditions.).

  3673. 

  3674.    It is possible that a breakpoint corresponds to several locations in

  3675. your program.  Examples of this situation are:

  3676. 

  3677.    * Multiple functions in the program may have the same name.

  3678. 

  3679.    * For a C++ constructor, the GCC compiler generates several instances

  3680.      of the function body, used in different cases.

  3681. 

  3682.    * For a C++ template function, a given line in the function can

  3683.      correspond to any number of instantiations.

  3684. 

  3685.    * For an inlined function, a given source line can correspond to

  3686.      several places where that function is inlined.

  3687. 

  3688.    In all those cases, GDB will insert a breakpoint at all the relevant

  3689. locations.

  3690. 

  3691.    A breakpoint with multiple locations is displayed in the breakpoint

  3692. table using several rows--one header row, followed by one row for each

  3693. breakpoint location.  The header row has '<MULTIPLE>' in the address

  3694. column.  The rows for individual locations contain the actual addresses

  3695. for locations, and show the functions to which those locations belong.

  3696. The number column for a location is of the form

  3697. BREAKPOINT-NUMBER.LOCATION-NUMBER.

  3698. 

  3699.    For example:

  3700. 

  3701.      Num     Type           Disp Enb  Address    What

  3702.      1       breakpoint     keep y    <MULTIPLE>

  3703.              stop only if i==1

  3704.              breakpoint already hit 1 time

  3705.      1.1                         y    0x080486a2 in void foo<int>() at t.cc:8

  3706.      1.2                         y    0x080486ca in void foo<double>() at t.cc:8

  3707. 

  3708.    You cannot delete the individual locations from a breakpoint.

  3709. However, each location can be individually enabled or disabled by

  3710. passing BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable'

  3711. and 'disable' commands.  It's also possible to 'enable' and 'disable' a

  3712. range of LOCATION-NUMBER locations using a BREAKPOINT-NUMBER and two

  3713. LOCATION-NUMBERs, in increasing order, separated by a hyphen, like

  3714. 'BREAKPOINT-NUMBER.LOCATION-NUMBER1-LOCATION-NUMBER2', in which case GDB

  3715. acts on all the locations in the range (inclusive).  Disabling or

  3716. enabling the parent breakpoint (*note Disabling::) affects all of the

  3717. locations that belong to that breakpoint.

  3718. 

  3719.    It's quite common to have a breakpoint inside a shared library.

  3720. Shared libraries can be loaded and unloaded explicitly, and possibly

  3721. repeatedly, as the program is executed.  To support this use case, GDB

  3722. updates breakpoint locations whenever any shared library is loaded or

  3723. unloaded.  Typically, you would set a breakpoint in a shared library at

  3724. the beginning of your debugging session, when the library is not loaded,

  3725. and when the symbols from the library are not available.  When you try

  3726. to set breakpoint, GDB will ask you if you want to set a so called

  3727. "pending breakpoint"--breakpoint whose address is not yet resolved.

  3728. 

  3729.    After the program is run, whenever a new shared library is loaded,

  3730. GDB reevaluates all the breakpoints.  When a newly loaded shared library

  3731. contains the symbol or line referred to by some pending breakpoint, that

  3732. breakpoint is resolved and becomes an ordinary breakpoint.  When a

  3733. library is unloaded, all breakpoints that refer to its symbols or source

  3734. lines become pending again.

  3735. 

  3736.    This logic works for breakpoints with multiple locations, too.  For

  3737. example, if you have a breakpoint in a C++ template function, and a

  3738. newly loaded shared library has an instantiation of that template, a new

  3739. location is added to the list of locations for the breakpoint.

  3740. 

  3741.    Except for having unresolved address, pending breakpoints do not

  3742. differ from regular breakpoints.  You can set conditions or commands,

  3743. enable and disable them and perform other breakpoint operations.

  3744. 

  3745.    GDB provides some additional commands for controlling what happens

  3746. when the 'break' command cannot resolve breakpoint address specification

  3747. to an address:

  3748. 

  3749. 'set breakpoint pending auto'

  3750.      This is the default behavior.  When GDB cannot find the breakpoint

  3751.      location, it queries you whether a pending breakpoint should be

  3752.      created.

  3753. 

  3754. 'set breakpoint pending on'

  3755.      This indicates that an unrecognized breakpoint location should

  3756.      automatically result in a pending breakpoint being created.

  3757. 

  3758. 'set breakpoint pending off'

  3759.      This indicates that pending breakpoints are not to be created.  Any

  3760.      unrecognized breakpoint location results in an error.  This setting

  3761.      does not affect any pending breakpoints previously created.

  3762. 

  3763. 'show breakpoint pending'

  3764.      Show the current behavior setting for creating pending breakpoints.

  3765. 

  3766.    The settings above only affect the 'break' command and its variants.

  3767. Once breakpoint is set, it will be automatically updated as shared

  3768. libraries are loaded and unloaded.

  3769. 

  3770.    For some targets, GDB can automatically decide if hardware or

  3771. software breakpoints should be used, depending on whether the breakpoint

  3772. address is read-only or read-write.  This applies to breakpoints set

  3773. with the 'break' command as well as to internal breakpoints set by

  3774. commands like 'next' and 'finish'.  For breakpoints set with 'hbreak',

  3775. GDB will always use hardware breakpoints.

  3776. 

  3777.    You can control this automatic behaviour with the following commands:

  3778. 

  3779. 'set breakpoint auto-hw on'

  3780.      This is the default behavior.  When GDB sets a breakpoint, it will

  3781.      try to use the target memory map to decide if software or hardware

  3782.      breakpoint must be used.

  3783. 

  3784. 'set breakpoint auto-hw off'

  3785.      This indicates GDB should not automatically select breakpoint type.

  3786.      If the target provides a memory map, GDB will warn when trying to

  3787.      set software breakpoint at a read-only address.

  3788. 

  3789.    GDB normally implements breakpoints by replacing the program code at

  3790. the breakpoint address with a special instruction, which, when executed,

  3791. given control to the debugger.  By default, the program code is so

  3792. modified only when the program is resumed.  As soon as the program

  3793. stops, GDB restores the original instructions.  This behaviour guards

  3794. against leaving breakpoints inserted in the target should gdb abrubptly

  3795. disconnect.  However, with slow remote targets, inserting and removing

  3796. breakpoint can reduce the performance.  This behavior can be controlled

  3797. with the following commands::

  3798. 

  3799. 'set breakpoint always-inserted off'

  3800.      All breakpoints, including newly added by the user, are inserted in

  3801.      the target only when the target is resumed.  All breakpoints are

  3802.      removed from the target when it stops.  This is the default mode.

  3803. 

  3804. 'set breakpoint always-inserted on'

  3805.      Causes all breakpoints to be inserted in the target at all times.

  3806.      If the user adds a new breakpoint, or changes an existing

  3807.      breakpoint, the breakpoints in the target are updated immediately.

  3808.      A breakpoint is removed from the target only when breakpoint itself

  3809.      is deleted.

  3810. 

  3811.    GDB handles conditional breakpoints by evaluating these conditions

  3812. when a breakpoint breaks.  If the condition is true, then the process

  3813. being debugged stops, otherwise the process is resumed.

  3814. 

  3815.    If the target supports evaluating conditions on its end, GDB may

  3816. download the breakpoint, together with its conditions, to it.

  3817. 

  3818.    This feature can be controlled via the following commands:

  3819. 

  3820. 'set breakpoint condition-evaluation host'

  3821.      This option commands GDB to evaluate the breakpoint conditions on

  3822.      the host's side.  Unconditional breakpoints are sent to the target

  3823.      which in turn receives the triggers and reports them back to GDB

  3824.      for condition evaluation.  This is the standard evaluation mode.

  3825. 

  3826. 'set breakpoint condition-evaluation target'

  3827.      This option commands GDB to download breakpoint conditions to the

  3828.      target at the moment of their insertion.  The target is responsible

  3829.      for evaluating the conditional expression and reporting breakpoint

  3830.      stop events back to GDB whenever the condition is true.  Due to

  3831.      limitations of target-side evaluation, some conditions cannot be

  3832.      evaluated there, e.g., conditions that depend on local data that is

  3833.      only known to the host.  Examples include conditional expressions

  3834.      involving convenience variables, complex types that cannot be

  3835.      handled by the agent expression parser and expressions that are too

  3836.      long to be sent over to the target, specially when the target is a

  3837.      remote system.  In these cases, the conditions will be evaluated by

  3838.      GDB.

  3839. 

  3840. 'set breakpoint condition-evaluation auto'

  3841.      This is the default mode.  If the target supports evaluating

  3842.      breakpoint conditions on its end, GDB will download breakpoint

  3843.      conditions to the target (limitations mentioned previously apply).

  3844.      If the target does not support breakpoint condition evaluation,

  3845.      then GDB will fallback to evaluating all these conditions on the

  3846.      host's side.

  3847. 

  3848.    GDB itself sometimes sets breakpoints in your program for special

  3849. purposes, such as proper handling of 'longjmp' (in C programs).  These

  3850. internal breakpoints are assigned negative numbers, starting with '-1';

  3851. 'info breakpoints' does not display them.  You can see these breakpoints

  3852. with the GDB maintenance command 'maint info breakpoints' (*note maint

  3853. info breakpoints::).

  3854. 

  3855. 

  3856. File: gdb.info,  Node: Set Watchpoints,  Next: Set Catchpoints,  Prev: Set Breaks,  Up: Breakpoints

  3857. 

  3858. 5.1.2 Setting Watchpoints

  3859. -------------------------

  3860. 

  3861. You can use a watchpoint to stop execution whenever the value of an

  3862. expression changes, without having to predict a particular place where

  3863. this may happen.  (This is sometimes called a "data breakpoint".)  The

  3864. expression may be as simple as the value of a single variable, or as

  3865. complex as many variables combined by operators.  Examples include:

  3866. 

  3867.    * A reference to the value of a single variable.

  3868. 

  3869.    * An address cast to an appropriate data type.  For example, '*(int

  3870.      *)0x12345678' will watch a 4-byte region at the specified address

  3871.      (assuming an 'int' occupies 4 bytes).

  3872. 

  3873.    * An arbitrarily complex expression, such as 'a*b + c/d'.  The

  3874.      expression can use any operators valid in the program's native

  3875.      language (*note Languages::).

  3876. 

  3877.    You can set a watchpoint on an expression even if the expression can

  3878. not be evaluated yet.  For instance, you can set a watchpoint on

  3879. '*global_ptr' before 'global_ptr' is initialized.  GDB will stop when

  3880. your program sets 'global_ptr' and the expression produces a valid

  3881. value.  If the expression becomes valid in some other way than changing

  3882. a variable (e.g. if the memory pointed to by '*global_ptr' becomes

  3883. readable as the result of a 'malloc' call), GDB may not stop until the

  3884. next time the expression changes.

  3885. 

  3886.    Depending on your system, watchpoints may be implemented in software

  3887. or hardware.  GDB does software watchpointing by single-stepping your

  3888. program and testing the variable's value each time, which is hundreds of

  3889. times slower than normal execution.  (But this may still be worth it, to

  3890. catch errors where you have no clue what part of your program is the

  3891. culprit.)

  3892. 

  3893.    On some systems, such as most PowerPC or x86-based targets, GDB

  3894. includes support for hardware watchpoints, which do not slow down the

  3895. running of your program.

  3896. 

  3897. 'watch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]'

  3898.      Set a watchpoint for an expression.  GDB will break when the

  3899.      expression EXPR is written into by the program and its value

  3900.      changes.  The simplest (and the most popular) use of this command

  3901.      is to watch the value of a single variable:

  3902. 

  3903.           (gdb) watch foo

  3904. 

  3905.      If the command includes a '[thread THREAD-ID]' argument, GDB breaks

  3906.      only when the thread identified by THREAD-ID changes the value of

  3907.      EXPR.  If any other threads change the value of EXPR, GDB will not

  3908.      break.  Note that watchpoints restricted to a single thread in this

  3909.      way only work with Hardware Watchpoints.

  3910. 

  3911.      Ordinarily a watchpoint respects the scope of variables in EXPR

  3912.      (see below).  The '-location' argument tells GDB to instead watch

  3913.      the memory referred to by EXPR.  In this case, GDB will evaluate

  3914.      EXPR, take the address of the result, and watch the memory at that

  3915.      address.  The type of the result is used to determine the size of

  3916.      the watched memory.  If the expression's result does not have an

  3917.      address, then GDB will print an error.

  3918. 

  3919.      The '[mask MASKVALUE]' argument allows creation of masked

  3920.      watchpoints, if the current architecture supports this feature

  3921.      (e.g., PowerPC Embedded architecture, see *note PowerPC

  3922.      Embedded::.)  A "masked watchpoint" specifies a mask in addition to

  3923.      an address to watch.  The mask specifies that some bits of an

  3924.      address (the bits which are reset in the mask) should be ignored

  3925.      when matching the address accessed by the inferior against the

  3926.      watchpoint address.  Thus, a masked watchpoint watches many

  3927.      addresses simultaneously--those addresses whose unmasked bits are

  3928.      identical to the unmasked bits in the watchpoint address.  The

  3929.      'mask' argument implies '-location'.  Examples:

  3930. 

  3931.           (gdb) watch foo mask 0xffff00ff

  3932.           (gdb) watch *0xdeadbeef mask 0xffffff00

  3933. 

  3934. 'rwatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]'

  3935.      Set a watchpoint that will break when the value of EXPR is read by

  3936.      the program.

  3937. 

  3938. 'awatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]'

  3939.      Set a watchpoint that will break when EXPR is either read from or

  3940.      written into by the program.

  3941. 

  3942. 'info watchpoints [LIST...]'

  3943.      This command prints a list of watchpoints, using the same format as

  3944.      'info break' (*note Set Breaks::).

  3945. 

  3946.    If you watch for a change in a numerically entered address you need

  3947. to dereference it, as the address itself is just a constant number which

  3948. will never change.  GDB refuses to create a watchpoint that watches a

  3949. never-changing value:

  3950. 

  3951.      (gdb) watch 0x600850

  3952.      Cannot watch constant value 0x600850.

  3953.      (gdb) watch *(int *) 0x600850

  3954.      Watchpoint 1: *(int *) 6293584

  3955. 

  3956.    GDB sets a "hardware watchpoint" if possible.  Hardware watchpoints

  3957. execute very quickly, and the debugger reports a change in value at the

  3958. exact instruction where the change occurs.  If GDB cannot set a hardware

  3959. watchpoint, it sets a software watchpoint, which executes more slowly

  3960. and reports the change in value at the next _statement_, not the

  3961. instruction, after the change occurs.

  3962. 

  3963.    You can force GDB to use only software watchpoints with the 'set

  3964. can-use-hw-watchpoints 0' command.  With this variable set to zero, GDB

  3965. will never try to use hardware watchpoints, even if the underlying

  3966. system supports them.  (Note that hardware-assisted watchpoints that

  3967. were set _before_ setting 'can-use-hw-watchpoints' to zero will still

  3968. use the hardware mechanism of watching expression values.)

  3969. 

  3970. 'set can-use-hw-watchpoints'

  3971.      Set whether or not to use hardware watchpoints.

  3972. 

  3973. 'show can-use-hw-watchpoints'

  3974.      Show the current mode of using hardware watchpoints.

  3975. 

  3976.    For remote targets, you can restrict the number of hardware

  3977. watchpoints GDB will use, see *note set remote

  3978. hardware-breakpoint-limit::.

  3979. 

  3980.    When you issue the 'watch' command, GDB reports

  3981. 

  3982.      Hardware watchpoint NUM: EXPR

  3983. 

  3984. if it was able to set a hardware watchpoint.

  3985. 

  3986.    Currently, the 'awatch' and 'rwatch' commands can only set hardware

  3987. watchpoints, because accesses to data that don't change the value of the

  3988. watched expression cannot be detected without examining every

  3989. instruction as it is being executed, and GDB does not do that currently.

  3990. If GDB finds that it is unable to set a hardware breakpoint with the

  3991. 'awatch' or 'rwatch' command, it will print a message like this:

  3992. 

  3993.      Expression cannot be implemented with read/access watchpoint.

  3994. 

  3995.    Sometimes, GDB cannot set a hardware watchpoint because the data type

  3996. of the watched expression is wider than what a hardware watchpoint on

  3997. the target machine can handle.  For example, some systems can only watch

  3998. regions that are up to 4 bytes wide; on such systems you cannot set

  3999. hardware watchpoints for an expression that yields a double-precision

  4000. floating-point number (which is typically 8 bytes wide).  As a

  4001. work-around, it might be possible to break the large region into a

  4002. series of smaller ones and watch them with separate watchpoints.

  4003. 

  4004.    If you set too many hardware watchpoints, GDB might be unable to

  4005. insert all of them when you resume the execution of your program.  Since

  4006. the precise number of active watchpoints is unknown until such time as

  4007. the program is about to be resumed, GDB might not be able to warn you

  4008. about this when you set the watchpoints, and the warning will be printed

  4009. only when the program is resumed:

  4010. 

  4011.      Hardware watchpoint NUM: Could not insert watchpoint

  4012. 

  4013. If this happens, delete or disable some of the watchpoints.

  4014. 

  4015.    Watching complex expressions that reference many variables can also

  4016. exhaust the resources available for hardware-assisted watchpoints.

  4017. That's because GDB needs to watch every variable in the expression with

  4018. separately allocated resources.

  4019. 

  4020.    If you call a function interactively using 'print' or 'call', any

  4021. watchpoints you have set will be inactive until GDB reaches another kind

  4022. of breakpoint or the call completes.

  4023. 

  4024.    GDB automatically deletes watchpoints that watch local (automatic)

  4025. variables, or expressions that involve such variables, when they go out

  4026. of scope, that is, when the execution leaves the block in which these

  4027. variables were defined.  In particular, when the program being debugged

  4028. terminates, _all_ local variables go out of scope, and so only

  4029. watchpoints that watch global variables remain set.  If you rerun the

  4030. program, you will need to set all such watchpoints again.  One way of

  4031. doing that would be to set a code breakpoint at the entry to the 'main'

  4032. function and when it breaks, set all the watchpoints.

  4033. 

  4034.    In multi-threaded programs, watchpoints will detect changes to the

  4035. watched expression from every thread.

  4036. 

  4037.      _Warning:_ In multi-threaded programs, software watchpoints have

  4038.      only limited usefulness.  If GDB creates a software watchpoint, it

  4039.      can only watch the value of an expression _in a single thread_.  If

  4040.      you are confident that the expression can only change due to the

  4041.      current thread's activity (and if you are also confident that no

  4042.      other thread can become current), then you can use software

  4043.      watchpoints as usual.  However, GDB may not notice when a

  4044.      non-current thread's activity changes the expression.  (Hardware

  4045.      watchpoints, in contrast, watch an expression in all threads.)

  4046. 

  4047.    *Note set remote hardware-watchpoint-limit::.

  4048. 

  4049. 

  4050. File: gdb.info,  Node: Set Catchpoints,  Next: Delete Breaks,  Prev: Set Watchpoints,  Up: Breakpoints

  4051. 

  4052. 5.1.3 Setting Catchpoints

  4053. -------------------------

  4054. 

  4055. You can use "catchpoints" to cause the debugger to stop for certain

  4056. kinds of program events, such as C++ exceptions or the loading of a

  4057. shared library.  Use the 'catch' command to set a catchpoint.

  4058. 

  4059. 'catch EVENT'

  4060.      Stop when EVENT occurs.  The EVENT can be any of the following:

  4061. 

  4062.      'throw [REGEXP]'

  4063.      'rethrow [REGEXP]'

  4064.      'catch [REGEXP]'

  4065.           The throwing, re-throwing, or catching of a C++ exception.

  4066. 

  4067.           If REGEXP is given, then only exceptions whose type matches

  4068.           the regular expression will be caught.

  4069. 

  4070.           The convenience variable '$_exception' is available at an

  4071.           exception-related catchpoint, on some systems.  This holds the

  4072.           exception being thrown.

  4073. 

  4074.           There are currently some limitations to C++ exception handling

  4075.           in GDB:

  4076. 

  4077.              * The support for these commands is system-dependent.

  4078.                Currently, only systems using the 'gnu-v3' C++ ABI (*note

  4079.                ABI::) are supported.

  4080. 

  4081.              * The regular expression feature and the '$_exception'

  4082.                convenience variable rely on the presence of some SDT

  4083.                probes in 'libstdc++'.  If these probes are not present,

  4084.                then these features cannot be used.  These probes were

  4085.                first available in the GCC 4.8 release, but whether or

  4086.                not they are available in your GCC also depends on how it

  4087.                was built.

  4088. 

  4089.              * The '$_exception' convenience variable is only valid at

  4090.                the instruction at which an exception-related catchpoint

  4091.                is set.

  4092. 

  4093.              * When an exception-related catchpoint is hit, GDB stops at

  4094.                a location in the system library which implements runtime

  4095.                exception support for C++, usually 'libstdc++'.  You can

  4096.                use 'up' (*note Selection::) to get to your code.

  4097. 

  4098.              * If you call a function interactively, GDB normally

  4099.                returns control to you when the function has finished

  4100.                executing.  If the call raises an exception, however, the

  4101.                call may bypass the mechanism that returns control to you

  4102.                and cause your program either to abort or to simply

  4103.                continue running until it hits a breakpoint, catches a

  4104.                signal that GDB is listening for, or exits.  This is the

  4105.                case even if you set a catchpoint for the exception;

  4106.                catchpoints on exceptions are disabled within interactive

  4107.                calls.  *Note Calling::, for information on controlling

  4108.                this with 'set unwind-on-terminating-exception'.

  4109. 

  4110.              * You cannot raise an exception interactively.

  4111. 

  4112.              * You cannot install an exception handler interactively.

  4113. 

  4114.      'exception [NAME]'

  4115.           An Ada exception being raised.  If an exception name is

  4116.           specified at the end of the command (eg 'catch exception

  4117.           Program_Error'), the debugger will stop only when this

  4118.           specific exception is raised.  Otherwise, the debugger stops

  4119.           execution when any Ada exception is raised.

  4120. 

  4121.           When inserting an exception catchpoint on a user-defined

  4122.           exception whose name is identical to one of the exceptions

  4123.           defined by the language, the fully qualified name must be used

  4124.           as the exception name.  Otherwise, GDB will assume that it

  4125.           should stop on the pre-defined exception rather than the

  4126.           user-defined one.  For instance, assuming an exception called

  4127.           'Constraint_Error' is defined in package 'Pck', then the

  4128.           command to use to catch such exceptions is 'catch exception

  4129.           Pck.Constraint_Error'.

  4130. 

  4131.           The convenience variable '$_ada_exception' holds the address

  4132.           of the exception being thrown.  This can be useful when

  4133.           setting a condition for such a catchpoint.

  4134. 

  4135.      'exception unhandled'

  4136.           An exception that was raised but is not handled by the

  4137.           program.  The convenience variable '$_ada_exception' is set as

  4138.           for 'catch exception'.

  4139. 

  4140.      'handlers [NAME]'

  4141.           An Ada exception being handled.  If an exception name is

  4142.           specified at the end of the command (eg 'catch handlers

  4143.           Program_Error'), the debugger will stop only when this

  4144.           specific exception is handled.  Otherwise, the debugger stops

  4145.           execution when any Ada exception is handled.

  4146. 

  4147.           When inserting a handlers catchpoint on a user-defined

  4148.           exception whose name is identical to one of the exceptions

  4149.           defined by the language, the fully qualified name must be used

  4150.           as the exception name.  Otherwise, GDB will assume that it

  4151.           should stop on the pre-defined exception rather than the

  4152.           user-defined one.  For instance, assuming an exception called

  4153.           'Constraint_Error' is defined in package 'Pck', then the

  4154.           command to use to catch such exceptions handling is 'catch

  4155.           handlers Pck.Constraint_Error'.

  4156. 

  4157.           The convenience variable '$_ada_exception' is set as for

  4158.           'catch exception'.

  4159. 

  4160.      'assert'

  4161.           A failed Ada assertion.  Note that the convenience variable

  4162.           '$_ada_exception' is _not_ set by this catchpoint.

  4163. 

  4164.      'exec'

  4165.           A call to 'exec'.

  4166. 

  4167.      'syscall'

  4168.      'syscall [NAME | NUMBER | group:GROUPNAME | g:GROUPNAME] ...'

  4169.           A call to or return from a system call, a.k.a. "syscall".  A

  4170.           syscall is a mechanism for application programs to request a

  4171.           service from the operating system (OS) or one of the OS system

  4172.           services.  GDB can catch some or all of the syscalls issued by

  4173.           the debuggee, and show the related information for each

  4174.           syscall.  If no argument is specified, calls to and returns

  4175.           from all system calls will be caught.

  4176. 

  4177.           NAME can be any system call name that is valid for the

  4178.           underlying OS. Just what syscalls are valid depends on the OS.

  4179.           On GNU and Unix systems, you can find the full list of valid

  4180.           syscall names on '/usr/include/asm/unistd.h'.

  4181. 

  4182.           Normally, GDB knows in advance which syscalls are valid for

  4183.           each OS, so you can use the GDB command-line completion

  4184.           facilities (*note command completion: Completion.) to list the

  4185.           available choices.

  4186. 

  4187.           You may also specify the system call numerically.  A syscall's

  4188.           number is the value passed to the OS's syscall dispatcher to

  4189.           identify the requested service.  When you specify the syscall

  4190.           by its name, GDB uses its database of syscalls to convert the

  4191.           name into the corresponding numeric code, but using the number

  4192.           directly may be useful if GDB's database does not have the

  4193.           complete list of syscalls on your system (e.g., because GDB

  4194.           lags behind the OS upgrades).

  4195. 

  4196.           You may specify a group of related syscalls to be caught at

  4197.           once using the 'group:' syntax ('g:' is a shorter equivalent).

  4198.           For instance, on some platforms GDB allows you to catch all

  4199.           network related syscalls, by passing the argument

  4200.           'group:network' to 'catch syscall'.  Note that not all syscall

  4201.           groups are available in every system.  You can use the command

  4202.           completion facilities (*note command completion: Completion.)

  4203.           to list the syscall groups available on your environment.

  4204. 

  4205.           The example below illustrates how this command works if you

  4206.           don't provide arguments to it:

  4207. 

  4208.                (gdb) catch syscall

  4209.                Catchpoint 1 (syscall)

  4210.                (gdb) r

  4211.                Starting program: /tmp/catch-syscall

  4212. 

  4213.                Catchpoint 1 (call to syscall 'close'), \

  4214.                	   0xffffe424 in __kernel_vsyscall ()

  4215.                (gdb) c

  4216.                Continuing.

  4217. 

  4218.                Catchpoint 1 (returned from syscall 'close'), \

  4219.                	0xffffe424 in __kernel_vsyscall ()

  4220.                (gdb)

  4221. 

  4222.           Here is an example of catching a system call by name:

  4223. 

  4224.                (gdb) catch syscall chroot

  4225.                Catchpoint 1 (syscall 'chroot' [61])

  4226.                (gdb) r

  4227.                Starting program: /tmp/catch-syscall

  4228. 

  4229.                Catchpoint 1 (call to syscall 'chroot'), \

  4230.                		   0xffffe424 in __kernel_vsyscall ()

  4231.                (gdb) c

  4232.                Continuing.

  4233. 

  4234.                Catchpoint 1 (returned from syscall 'chroot'), \

  4235.                	0xffffe424 in __kernel_vsyscall ()

  4236.                (gdb)

  4237. 

  4238.           An example of specifying a system call numerically.  In the

  4239.           case below, the syscall number has a corresponding entry in

  4240.           the XML file, so GDB finds its name and prints it:

  4241. 

  4242.                (gdb) catch syscall 252

  4243.                Catchpoint 1 (syscall(s) 'exit_group')

  4244.                (gdb) r

  4245.                Starting program: /tmp/catch-syscall

  4246. 

  4247.                Catchpoint 1 (call to syscall 'exit_group'), \

  4248.                		   0xffffe424 in __kernel_vsyscall ()

  4249.                (gdb) c

  4250.                Continuing.

  4251. 

  4252.                Program exited normally.

  4253.                (gdb)

  4254. 

  4255.           Here is an example of catching a syscall group:

  4256. 

  4257.                (gdb) catch syscall group:process

  4258.                Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]

  4259.                'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]

  4260.                'exit_group' [252] 'waitid' [284] 'unshare' [310])

  4261.                (gdb) r

  4262.                Starting program: /tmp/catch-syscall

  4263. 

  4264.                Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()

  4265.                   from /lib64/ld-linux-x86-64.so.2

  4266. 

  4267.                (gdb) c

  4268.                Continuing.

  4269. 

  4270.           However, there can be situations when there is no

  4271.           corresponding name in XML file for that syscall number.  In

  4272.           this case, GDB prints a warning message saying that it was not

  4273.           able to find the syscall name, but the catchpoint will be set

  4274.           anyway.  See the example below:

  4275. 

  4276.                (gdb) catch syscall 764

  4277.                warning: The number '764' does not represent a known syscall.

  4278.                Catchpoint 2 (syscall 764)

  4279.                (gdb)

  4280. 

  4281.           If you configure GDB using the '--without-expat' option, it

  4282.           will not be able to display syscall names.  Also, if your

  4283.           architecture does not have an XML file describing its system

  4284.           calls, you will not be able to see the syscall names.  It is

  4285.           important to notice that these two features are used for

  4286.           accessing the syscall name database.  In either case, you will

  4287.           see a warning like this:

  4288. 

  4289.                (gdb) catch syscall

  4290.                warning: Could not open "syscalls/i386-linux.xml"

  4291.                warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.

  4292.                GDB will not be able to display syscall names.

  4293.                Catchpoint 1 (syscall)

  4294.                (gdb)

  4295. 

  4296.           Of course, the file name will change depending on your

  4297.           architecture and system.

  4298. 

  4299.           Still using the example above, you can also try to catch a

  4300.           syscall by its number.  In this case, you would see something

  4301.           like:

  4302. 

  4303.                (gdb) catch syscall 252

  4304.                Catchpoint 1 (syscall(s) 252)

  4305. 

  4306.           Again, in this case GDB would not be able to display syscall's

  4307.           names.

  4308. 

  4309.      'fork'

  4310.           A call to 'fork'.

  4311. 

  4312.      'vfork'

  4313.           A call to 'vfork'.

  4314. 

  4315.      'load [REGEXP]'

  4316.      'unload [REGEXP]'

  4317.           The loading or unloading of a shared library.  If REGEXP is

  4318.           given, then the catchpoint will stop only if the regular

  4319.           expression matches one of the affected libraries.

  4320. 

  4321.      'signal [SIGNAL... | 'all']'

  4322.           The delivery of a signal.

  4323. 

  4324.           With no arguments, this catchpoint will catch any signal that

  4325.           is not used internally by GDB, specifically, all signals

  4326.           except 'SIGTRAP' and 'SIGINT'.

  4327. 

  4328.           With the argument 'all', all signals, including those used by

  4329.           GDB, will be caught.  This argument cannot be used with other

  4330.           signal names.

  4331. 

  4332.           Otherwise, the arguments are a list of signal names as given

  4333.           to 'handle' (*note Signals::).  Only signals specified in this

  4334.           list will be caught.

  4335. 

  4336.           One reason that 'catch signal' can be more useful than

  4337.           'handle' is that you can attach commands and conditions to the

  4338.           catchpoint.

  4339. 

  4340.           When a signal is caught by a catchpoint, the signal's 'stop'

  4341.           and 'print' settings, as specified by 'handle', are ignored.

  4342.           However, whether the signal is still delivered to the inferior

  4343.           depends on the 'pass' setting; this can be changed in the

  4344.           catchpoint's commands.

  4345. 

  4346. 'tcatch EVENT'

  4347.      Set a catchpoint that is enabled only for one stop.  The catchpoint

  4348.      is automatically deleted after the first time the event is caught.

  4349. 

  4350.    Use the 'info break' command to list the current catchpoints.

  4351. 

  4352. 

  4353. File: gdb.info,  Node: Delete Breaks,  Next: Disabling,  Prev: Set Catchpoints,  Up: Breakpoints

  4354. 

  4355. 5.1.4 Deleting Breakpoints

  4356. --------------------------

  4357. 

  4358. It is often necessary to eliminate a breakpoint, watchpoint, or

  4359. catchpoint once it has done its job and you no longer want your program

  4360. to stop there.  This is called "deleting" the breakpoint.  A breakpoint

  4361. that has been deleted no longer exists; it is forgotten.

  4362. 

  4363.    With the 'clear' command you can delete breakpoints according to

  4364. where they are in your program.  With the 'delete' command you can

  4365. delete individual breakpoints, watchpoints, or catchpoints by specifying

  4366. their breakpoint numbers.

  4367. 

  4368.    It is not necessary to delete a breakpoint to proceed past it.  GDB

  4369. automatically ignores breakpoints on the first instruction to be

  4370. executed when you continue execution without changing the execution

  4371. address.

  4372. 

  4373. 'clear'

  4374.      Delete any breakpoints at the next instruction to be executed in

  4375.      the selected stack frame (*note Selecting a Frame: Selection.).

  4376.      When the innermost frame is selected, this is a good way to delete

  4377.      a breakpoint where your program just stopped.

  4378. 

  4379. 'clear LOCATION'

  4380.      Delete any breakpoints set at the specified LOCATION.  *Note

  4381.      Specify Location::, for the various forms of LOCATION; the most

  4382.      useful ones are listed below:

  4383. 

  4384.      'clear FUNCTION'

  4385.      'clear FILENAME:FUNCTION'

  4386.           Delete any breakpoints set at entry to the named FUNCTION.

  4387. 

  4388.      'clear LINENUM'

  4389.      'clear FILENAME:LINENUM'

  4390.           Delete any breakpoints set at or within the code of the

  4391.           specified LINENUM of the specified FILENAME.

  4392. 

  4393. 'delete [breakpoints] [LIST...]'

  4394.      Delete the breakpoints, watchpoints, or catchpoints of the

  4395.      breakpoint list specified as argument.  If no argument is

  4396.      specified, delete all breakpoints (GDB asks confirmation, unless

  4397.      you have 'set confirm off').  You can abbreviate this command as

  4398.      'd'.

  4399. 

  4400. 

  4401. File: gdb.info,  Node: Disabling,  Next: Conditions,  Prev: Delete Breaks,  Up: Breakpoints

  4402. 

  4403. 5.1.5 Disabling Breakpoints

  4404. ---------------------------

  4405. 

  4406. Rather than deleting a breakpoint, watchpoint, or catchpoint, you might

  4407. prefer to "disable" it.  This makes the breakpoint inoperative as if it

  4408. had been deleted, but remembers the information on the breakpoint so

  4409. that you can "enable" it again later.

  4410. 

  4411.    You disable and enable breakpoints, watchpoints, and catchpoints with

  4412. the 'enable' and 'disable' commands, optionally specifying one or more

  4413. breakpoint numbers as arguments.  Use 'info break' to print a list of

  4414. all breakpoints, watchpoints, and catchpoints if you do not know which

  4415. numbers to use.

  4416. 

  4417.    Disabling and enabling a breakpoint that has multiple locations

  4418. affects all of its locations.

  4419. 

  4420.    A breakpoint, watchpoint, or catchpoint can have any of several

  4421. different states of enablement:

  4422. 

  4423.    * Enabled.  The breakpoint stops your program.  A breakpoint set with

  4424.      the 'break' command starts out in this state.

  4425.    * Disabled.  The breakpoint has no effect on your program.

  4426.    * Enabled once.  The breakpoint stops your program, but then becomes

  4427.      disabled.

  4428.    * Enabled for a count.  The breakpoint stops your program for the

  4429.      next N times, then becomes disabled.

  4430.    * Enabled for deletion.  The breakpoint stops your program, but

  4431.      immediately after it does so it is deleted permanently.  A

  4432.      breakpoint set with the 'tbreak' command starts out in this state.

  4433. 

  4434.    You can use the following commands to enable or disable breakpoints,

  4435. watchpoints, and catchpoints:

  4436. 

  4437. 'disable [breakpoints] [LIST...]'

  4438.      Disable the specified breakpoints--or all breakpoints, if none are

  4439.      listed.  A disabled breakpoint has no effect but is not forgotten.

  4440.      All options such as ignore-counts, conditions and commands are

  4441.      remembered in case the breakpoint is enabled again later.  You may

  4442.      abbreviate 'disable' as 'dis'.

  4443. 

  4444. 'enable [breakpoints] [LIST...]'

  4445.      Enable the specified breakpoints (or all defined breakpoints).

  4446.      They become effective once again in stopping your program.

  4447. 

  4448. 'enable [breakpoints] once LIST...'

  4449.      Enable the specified breakpoints temporarily.  GDB disables any of

  4450.      these breakpoints immediately after stopping your program.

  4451. 

  4452. 'enable [breakpoints] count COUNT LIST...'

  4453.      Enable the specified breakpoints temporarily.  GDB records COUNT

  4454.      with each of the specified breakpoints, and decrements a

  4455.      breakpoint's count when it is hit.  When any count reaches 0, GDB

  4456.      disables that breakpoint.  If a breakpoint has an ignore count

  4457.      (*note Break Conditions: Conditions.), that will be decremented to

  4458.      0 before COUNT is affected.

  4459. 

  4460. 'enable [breakpoints] delete LIST...'

  4461.      Enable the specified breakpoints to work once, then die.  GDB

  4462.      deletes any of these breakpoints as soon as your program stops

  4463.      there.  Breakpoints set by the 'tbreak' command start out in this

  4464.      state.

  4465. 

  4466.    Except for a breakpoint set with 'tbreak' (*note Setting Breakpoints:

  4467. Set Breaks.), breakpoints that you set are initially enabled;

  4468. subsequently, they become disabled or enabled only when you use one of

  4469. the commands above.  (The command 'until' can set and delete a

  4470. breakpoint of its own, but it does not change the state of your other

  4471. breakpoints; see *note Continuing and Stepping: Continuing and

  4472. Stepping.)

  4473. 

  4474. 

  4475. File: gdb.info,  Node: Conditions,  Next: Break Commands,  Prev: Disabling,  Up: Breakpoints

  4476. 

  4477. 5.1.6 Break Conditions

  4478. ----------------------

  4479. 

  4480. The simplest sort of breakpoint breaks every time your program reaches a

  4481. specified place.  You can also specify a "condition" for a breakpoint.

  4482. A condition is just a Boolean expression in your programming language

  4483. (*note Expressions: Expressions.).  A breakpoint with a condition

  4484. evaluates the expression each time your program reaches it, and your

  4485. program stops only if the condition is _true_.

  4486. 

  4487.    This is the converse of using assertions for program validation; in

  4488. that situation, you want to stop when the assertion is violated--that

  4489. is, when the condition is false.  In C, if you want to test an assertion

  4490. expressed by the condition ASSERT, you should set the condition '!

  4491. ASSERT' on the appropriate breakpoint.

  4492. 

  4493.    Conditions are also accepted for watchpoints; you may not need them,

  4494. since a watchpoint is inspecting the value of an expression anyhow--but

  4495. it might be simpler, say, to just set a watchpoint on a variable name,

  4496. and specify a condition that tests whether the new value is an

  4497. interesting one.

  4498. 

  4499.    Break conditions can have side effects, and may even call functions

  4500. in your program.  This can be useful, for example, to activate functions

  4501. that log program progress, or to use your own print functions to format

  4502. special data structures.  The effects are completely predictable unless

  4503. there is another enabled breakpoint at the same address.  (In that case,

  4504. GDB might see the other breakpoint first and stop your program without

  4505. checking the condition of this one.)  Note that breakpoint commands are

  4506. usually more convenient and flexible than break conditions for the

  4507. purpose of performing side effects when a breakpoint is reached (*note

  4508. Breakpoint Command Lists: Break Commands.).

  4509. 

  4510.    Breakpoint conditions can also be evaluated on the target's side if

  4511. the target supports it.  Instead of evaluating the conditions locally,

  4512. GDB encodes the expression into an agent expression (*note Agent

  4513. Expressions::) suitable for execution on the target, independently of

  4514. GDB.  Global variables become raw memory locations, locals become stack

  4515. accesses, and so forth.

  4516. 

  4517.    In this case, GDB will only be notified of a breakpoint trigger when

  4518. its condition evaluates to true.  This mechanism may provide faster

  4519. response times depending on the performance characteristics of the

  4520. target since it does not need to keep GDB informed about every

  4521. breakpoint trigger, even those with false conditions.

  4522. 

  4523.    Break conditions can be specified when a breakpoint is set, by using

  4524. 'if' in the arguments to the 'break' command.  *Note Setting

  4525. Breakpoints: Set Breaks.  They can also be changed at any time with the

  4526. 'condition' command.

  4527. 

  4528.    You can also use the 'if' keyword with the 'watch' command.  The

  4529. 'catch' command does not recognize the 'if' keyword; 'condition' is the

  4530. only way to impose a further condition on a catchpoint.

  4531. 

  4532. 'condition BNUM EXPRESSION'

  4533.      Specify EXPRESSION as the break condition for breakpoint,

  4534.      watchpoint, or catchpoint number BNUM.  After you set a condition,

  4535.      breakpoint BNUM stops your program only if the value of EXPRESSION

  4536.      is true (nonzero, in C). When you use 'condition', GDB checks

  4537.      EXPRESSION immediately for syntactic correctness, and to determine

  4538.      whether symbols in it have referents in the context of your

  4539.      breakpoint.  If EXPRESSION uses symbols not referenced in the

  4540.      context of the breakpoint, GDB prints an error message:

  4541. 

  4542.           No symbol "foo" in current context.

  4543. 

  4544.      GDB does not actually evaluate EXPRESSION at the time the

  4545.      'condition' command (or a command that sets a breakpoint with a

  4546.      condition, like 'break if ...') is given, however.  *Note

  4547.      Expressions: Expressions.

  4548. 

  4549. 'condition BNUM'

  4550.      Remove the condition from breakpoint number BNUM.  It becomes an

  4551.      ordinary unconditional breakpoint.

  4552. 

  4553.    A special case of a breakpoint condition is to stop only when the

  4554. breakpoint has been reached a certain number of times.  This is so

  4555. useful that there is a special way to do it, using the "ignore count" of

  4556. the breakpoint.  Every breakpoint has an ignore count, which is an

  4557. integer.  Most of the time, the ignore count is zero, and therefore has

  4558. no effect.  But if your program reaches a breakpoint whose ignore count

  4559. is positive, then instead of stopping, it just decrements the ignore

  4560. count by one and continues.  As a result, if the ignore count value is

  4561. N, the breakpoint does not stop the next N times your program reaches

  4562. it.

  4563. 

  4564. 'ignore BNUM COUNT'

  4565.      Set the ignore count of breakpoint number BNUM to COUNT.  The next

  4566.      COUNT times the breakpoint is reached, your program's execution

  4567.      does not stop; other than to decrement the ignore count, GDB takes

  4568.      no action.

  4569. 

  4570.      To make the breakpoint stop the next time it is reached, specify a

  4571.      count of zero.

  4572. 

  4573.      When you use 'continue' to resume execution of your program from a

  4574.      breakpoint, you can specify an ignore count directly as an argument

  4575.      to 'continue', rather than using 'ignore'.  *Note Continuing and

  4576.      Stepping: Continuing and Stepping.

  4577. 

  4578.      If a breakpoint has a positive ignore count and a condition, the

  4579.      condition is not checked.  Once the ignore count reaches zero, GDB

  4580.      resumes checking the condition.

  4581. 

  4582.      You could achieve the effect of the ignore count with a condition

  4583.      such as '$foo-- <= 0' using a debugger convenience variable that is

  4584.      decremented each time.  *Note Convenience Variables: Convenience

  4585.      Vars.

  4586. 

  4587.    Ignore counts apply to breakpoints, watchpoints, and catchpoints.

  4588. 

  4589. 

  4590. File: gdb.info,  Node: Break Commands,  Next: Dynamic Printf,  Prev: Conditions,  Up: Breakpoints

  4591. 

  4592. 5.1.7 Breakpoint Command Lists

  4593. ------------------------------

  4594. 

  4595. You can give any breakpoint (or watchpoint or catchpoint) a series of

  4596. commands to execute when your program stops due to that breakpoint.  For

  4597. example, you might want to print the values of certain expressions, or

  4598. enable other breakpoints.

  4599. 

  4600. 'commands [LIST...]'

  4601. '... COMMAND-LIST ...'

  4602. 'end'

  4603.      Specify a list of commands for the given breakpoints.  The commands

  4604.      themselves appear on the following lines.  Type a line containing

  4605.      just 'end' to terminate the commands.

  4606. 

  4607.      To remove all commands from a breakpoint, type 'commands' and

  4608.      follow it immediately with 'end'; that is, give no commands.

  4609. 

  4610.      With no argument, 'commands' refers to the last breakpoint,

  4611.      watchpoint, or catchpoint set (not to the breakpoint most recently

  4612.      encountered).  If the most recent breakpoints were set with a

  4613.      single command, then the 'commands' will apply to all the

  4614.      breakpoints set by that command.  This applies to breakpoints set

  4615.      by 'rbreak', and also applies when a single 'break' command creates

  4616.      multiple breakpoints (*note Ambiguous Expressions: Ambiguous

  4617.      Expressions.).

  4618. 

  4619.    Pressing <RET> as a means of repeating the last GDB command is

  4620. disabled within a COMMAND-LIST.

  4621. 

  4622.    You can use breakpoint commands to start your program up again.

  4623. Simply use the 'continue' command, or 'step', or any other command that

  4624. resumes execution.

  4625. 

  4626.    Any other commands in the command list, after a command that resumes

  4627. execution, are ignored.  This is because any time you resume execution

  4628. (even with a simple 'next' or 'step'), you may encounter another

  4629. breakpoint--which could have its own command list, leading to

  4630. ambiguities about which list to execute.

  4631. 

  4632.    If the first command you specify in a command list is 'silent', the

  4633. usual message about stopping at a breakpoint is not printed.  This may

  4634. be desirable for breakpoints that are to print a specific message and

  4635. then continue.  If none of the remaining commands print anything, you

  4636. see no sign that the breakpoint was reached.  'silent' is meaningful

  4637. only at the beginning of a breakpoint command list.

  4638. 

  4639.    The commands 'echo', 'output', and 'printf' allow you to print

  4640. precisely controlled output, and are often useful in silent breakpoints.

  4641. *Note Commands for Controlled Output: Output.

  4642. 

  4643.    For example, here is how you could use breakpoint commands to print

  4644. the value of 'x' at entry to 'foo' whenever 'x' is positive.

  4645. 

  4646.      break foo if x>0

  4647.      commands

  4648.      silent

  4649.      printf "x is %d\n",x

  4650.      cont

  4651.      end

  4652. 

  4653.    One application for breakpoint commands is to compensate for one bug

  4654. so you can test for another.  Put a breakpoint just after the erroneous

  4655. line of code, give it a condition to detect the case in which something

  4656. erroneous has been done, and give it commands to assign correct values

  4657. to any variables that need them.  End with the 'continue' command so

  4658. that your program does not stop, and start with the 'silent' command so

  4659. that no output is produced.  Here is an example:

  4660. 

  4661.      break 403

  4662.      commands

  4663.      silent

  4664.      set x = y + 4

  4665.      cont

  4666.      end

  4667. 

  4668. 

  4669. File: gdb.info,  Node: Dynamic Printf,  Next: Save Breakpoints,  Prev: Break Commands,  Up: Breakpoints

  4670. 

  4671. 5.1.8 Dynamic Printf

  4672. --------------------

  4673. 

  4674. The dynamic printf command 'dprintf' combines a breakpoint with

  4675. formatted printing of your program's data to give you the effect of

  4676. inserting 'printf' calls into your program on-the-fly, without having to

  4677. recompile it.

  4678. 

  4679.    In its most basic form, the output goes to the GDB console.  However,

  4680. you can set the variable 'dprintf-style' for alternate handling.  For

  4681. instance, you can ask to format the output by calling your program's

  4682. 'printf' function.  This has the advantage that the characters go to the

  4683. program's output device, so they can recorded in redirects to files and

  4684. so forth.

  4685. 

  4686.    If you are doing remote debugging with a stub or agent, you can also

  4687. ask to have the printf handled by the remote agent.  In addition to

  4688. ensuring that the output goes to the remote program's device along with

  4689. any other output the program might produce, you can also ask that the

  4690. dprintf remain active even after disconnecting from the remote target.

  4691. Using the stub/agent is also more efficient, as it can do everything

  4692. without needing to communicate with GDB.

  4693. 

  4694. 'dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]'

  4695.      Whenever execution reaches LOCATION, print the values of one or

  4696.      more EXPRESSIONS under the control of the string TEMPLATE.  To

  4697.      print several values, separate them with commas.

  4698. 

  4699. 'set dprintf-style STYLE'

  4700.      Set the dprintf output to be handled in one of several different

  4701.      styles enumerated below.  A change of style affects all existing

  4702.      dynamic printfs immediately.  (If you need individual control over

  4703.      the print commands, simply define normal breakpoints with

  4704.      explicitly-supplied command lists.)

  4705. 

  4706.      'gdb'

  4707.           Handle the output using the GDB 'printf' command.

  4708. 

  4709.      'call'

  4710.           Handle the output by calling a function in your program

  4711.           (normally 'printf').

  4712. 

  4713.      'agent'

  4714.           Have the remote debugging agent (such as 'gdbserver') handle

  4715.           the output itself.  This style is only available for agents

  4716.           that support running commands on the target.

  4717. 

  4718. 'set dprintf-function FUNCTION'

  4719.      Set the function to call if the dprintf style is 'call'.  By

  4720.      default its value is 'printf'.  You may set it to any expression.

  4721.      that GDB can evaluate to a function, as per the 'call' command.

  4722. 

  4723. 'set dprintf-channel CHANNEL'

  4724.      Set a "channel" for dprintf.  If set to a non-empty value, GDB will

  4725.      evaluate it as an expression and pass the result as a first

  4726.      argument to the 'dprintf-function', in the manner of 'fprintf' and

  4727.      similar functions.  Otherwise, the dprintf format string will be

  4728.      the first argument, in the manner of 'printf'.

  4729. 

  4730.      As an example, if you wanted 'dprintf' output to go to a logfile

  4731.      that is a standard I/O stream assigned to the variable 'mylog', you

  4732.      could do the following:

  4733. 

  4734.           (gdb) set dprintf-style call

  4735.           (gdb) set dprintf-function fprintf

  4736.           (gdb) set dprintf-channel mylog

  4737.           (gdb) dprintf 25,"at line 25, glob=%d\n",glob

  4738.           Dprintf 1 at 0x123456: file main.c, line 25.

  4739.           (gdb) info break

  4740.           1       dprintf        keep y   0x00123456 in main at main.c:25

  4741.                   call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)

  4742.                   continue

  4743.           (gdb)

  4744. 

  4745.      Note that the 'info break' displays the dynamic printf commands as

  4746.      normal breakpoint commands; you can thus easily see the effect of

  4747.      the variable settings.

  4748. 

  4749. 'set disconnected-dprintf on'

  4750. 'set disconnected-dprintf off'

  4751.      Choose whether 'dprintf' commands should continue to run if GDB has

  4752.      disconnected from the target.  This only applies if the

  4753.      'dprintf-style' is 'agent'.

  4754. 

  4755. 'show disconnected-dprintf off'

  4756.      Show the current choice for disconnected 'dprintf'.

  4757. 

  4758.    GDB does not check the validity of function and channel, relying on

  4759. you to supply values that are meaningful for the contexts in which they

  4760. are being used.  For instance, the function and channel may be the

  4761. values of local variables, but if that is the case, then all enabled

  4762. dynamic prints must be at locations within the scope of those locals.

  4763. If evaluation fails, GDB will report an error.

  4764. 

  4765. 

  4766. File: gdb.info,  Node: Save Breakpoints,  Next: Static Probe Points,  Prev: Dynamic Printf,  Up: Breakpoints

  4767. 

  4768. 5.1.9 How to save breakpoints to a file

  4769. ---------------------------------------

  4770. 

  4771. To save breakpoint definitions to a file use the 'save breakpoints'

  4772. command.

  4773. 

  4774. 'save breakpoints [FILENAME]'

  4775.      This command saves all current breakpoint definitions together with

  4776.      their commands and ignore counts, into a file 'FILENAME' suitable

  4777.      for use in a later debugging session.  This includes all types of

  4778.      breakpoints (breakpoints, watchpoints, catchpoints, tracepoints).

  4779.      To read the saved breakpoint definitions, use the 'source' command

  4780.      (*note Command Files::).  Note that watchpoints with expressions

  4781.      involving local variables may fail to be recreated because it may

  4782.      not be possible to access the context where the watchpoint is valid

  4783.      anymore.  Because the saved breakpoint definitions are simply a

  4784.      sequence of GDB commands that recreate the breakpoints, you can

  4785.      edit the file in your favorite editing program, and remove the

  4786.      breakpoint definitions you're not interested in, or that can no

  4787.      longer be recreated.

  4788. 

  4789. 

  4790. File: gdb.info,  Node: Static Probe Points,  Next: Error in Breakpoints,  Prev: Save Breakpoints,  Up: Breakpoints

  4791. 

  4792. 5.1.10 Static Probe Points

  4793. --------------------------

  4794. 

  4795. GDB supports "SDT" probes in the code.  SDT stands for Statically

  4796. Defined Tracing, and the probes are designed to have a tiny runtime code

  4797. and data footprint, and no dynamic relocations.

  4798. 

  4799.    Currently, the following types of probes are supported on

  4800. ELF-compatible systems:

  4801. 

  4802.    * 'SystemTap' (<http://sourceware.org/systemtap/>) SDT probes(1).

  4803.      'SystemTap' probes are usable from assembly, C and C++

  4804.      languages(2).

  4805. 

  4806.    * 'DTrace' (<http://oss.oracle.com/projects/DTrace>) USDT probes.

  4807.      'DTrace' probes are usable from C and C++ languages.

  4808. 

  4809.    Some 'SystemTap' probes have an associated semaphore variable; for

  4810. instance, this happens automatically if you defined your probe using a

  4811. DTrace-style '.d' file.  If your probe has a semaphore, GDB will

  4812. automatically enable it when you specify a breakpoint using the

  4813. '-probe-stap' notation.  But, if you put a breakpoint at a probe's

  4814. location by some other method (e.g., 'break file:line'), then GDB will

  4815. not automatically set the semaphore.  'DTrace' probes do not support

  4816. semaphores.

  4817. 

  4818.    You can examine the available static static probes using 'info

  4819. probes', with optional arguments:

  4820. 

  4821. 'info probes [TYPE] [PROVIDER [NAME [OBJFILE]]]'

  4822.      If given, TYPE is either 'stap' for listing 'SystemTap' probes or

  4823.      'dtrace' for listing 'DTrace' probes.  If omitted all probes are

  4824.      listed regardless of their types.

  4825. 

  4826.      If given, PROVIDER is a regular expression used to match against

  4827.      provider names when selecting which probes to list.  If omitted,

  4828.      probes by all probes from all providers are listed.

  4829. 

  4830.      If given, NAME is a regular expression to match against probe names

  4831.      when selecting which probes to list.  If omitted, probe names are

  4832.      not considered when deciding whether to display them.

  4833. 

  4834.      If given, OBJFILE is a regular expression used to select which

  4835.      object files (executable or shared libraries) to examine.  If not

  4836.      given, all object files are considered.

  4837. 

  4838. 'info probes all'

  4839.      List the available static probes, from all types.

  4840. 

  4841.    Some probe points can be enabled and/or disabled.  The effect of

  4842. enabling or disabling a probe depends on the type of probe being

  4843. handled.  Some 'DTrace' probes can be enabled or disabled, but

  4844. 'SystemTap' probes cannot be disabled.

  4845. 

  4846.    You can enable (or disable) one or more probes using the following

  4847. commands, with optional arguments:

  4848. 

  4849. 'enable probes [PROVIDER [NAME [OBJFILE]]]'

  4850.      If given, PROVIDER is a regular expression used to match against

  4851.      provider names when selecting which probes to enable.  If omitted,

  4852.      all probes from all providers are enabled.

  4853. 

  4854.      If given, NAME is a regular expression to match against probe names

  4855.      when selecting which probes to enable.  If omitted, probe names are

  4856.      not considered when deciding whether to enable them.

  4857. 

  4858.      If given, OBJFILE is a regular expression used to select which

  4859.      object files (executable or shared libraries) to examine.  If not

  4860.      given, all object files are considered.

  4861. 

  4862. 'disable probes [PROVIDER [NAME [OBJFILE]]]'

  4863.      See the 'enable probes' command above for a description of the

  4864.      optional arguments accepted by this command.

  4865. 

  4866.    A probe may specify up to twelve arguments.  These are available at

  4867. the point at which the probe is defined--that is, when the current PC is

  4868. at the probe's location.  The arguments are available using the

  4869. convenience variables (*note Convenience Vars::)

  4870. '$_probe_arg0'...'$_probe_arg11'.  In 'SystemTap' probes each probe

  4871. argument is an integer of the appropriate size; types are not preserved.

  4872. In 'DTrace' probes types are preserved provided that they are recognized

  4873. as such by GDB; otherwise the value of the probe argument will be a long

  4874. integer.  The convenience variable '$_probe_argc' holds the number of

  4875. arguments at the current probe point.

  4876. 

  4877.    These variables are always available, but attempts to access them at

  4878. any location other than a probe point will cause GDB to give an error

  4879. message.

  4880. 

  4881.    ---------- Footnotes ----------

  4882. 

  4883.    (1) See

  4884. <http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps> for

  4885. more information on how to add 'SystemTap' SDT probes in your

  4886. applications.

  4887. 

  4888.    (2) See

  4889. <http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation> for

  4890. a good reference on how the SDT probes are implemented.

  4891. 

  4892. 

  4893. File: gdb.info,  Node: Error in Breakpoints,  Next: Breakpoint-related Warnings,  Prev: Static Probe Points,  Up: Breakpoints

  4894. 

  4895. 5.1.11 "Cannot insert breakpoints"

  4896. ----------------------------------

  4897. 

  4898. If you request too many active hardware-assisted breakpoints and

  4899. watchpoints, you will see this error message:

  4900. 

  4901.      Stopped; cannot insert breakpoints.

  4902.      You may have requested too many hardware breakpoints and watchpoints.

  4903. 

  4904. This message is printed when you attempt to resume the program, since

  4905. only then GDB knows exactly how many hardware breakpoints and

  4906. watchpoints it needs to insert.

  4907. 

  4908.    When this message is printed, you need to disable or remove some of

  4909. the hardware-assisted breakpoints and watchpoints, and then continue.

  4910. 

  4911. 

  4912. File: gdb.info,  Node: Breakpoint-related Warnings,  Prev: Error in Breakpoints,  Up: Breakpoints

  4913. 

  4914. 5.1.12 "Breakpoint address adjusted..."

  4915. ---------------------------------------

  4916. 

  4917. Some processor architectures place constraints on the addresses at which

  4918. breakpoints may be placed.  For architectures thus constrained, GDB will

  4919. attempt to adjust the breakpoint's address to comply with the

  4920. constraints dictated by the architecture.

  4921. 

  4922.    One example of such an architecture is the Fujitsu FR-V. The FR-V is

  4923. a VLIW architecture in which a number of RISC-like instructions may be

  4924. bundled together for parallel execution.  The FR-V architecture

  4925. constrains the location of a breakpoint instruction within such a bundle

  4926. to the instruction with the lowest address.  GDB honors this constraint

  4927. by adjusting a breakpoint's address to the first in the bundle.

  4928. 

  4929.    It is not uncommon for optimized code to have bundles which contain

  4930. instructions from different source statements, thus it may happen that a

  4931. breakpoint's address will be adjusted from one source statement to

  4932. another.  Since this adjustment may significantly alter GDB's breakpoint

  4933. related behavior from what the user expects, a warning is printed when

  4934. the breakpoint is first set and also when the breakpoint is hit.

  4935. 

  4936.    A warning like the one below is printed when setting a breakpoint

  4937. that's been subject to address adjustment:

  4938. 

  4939.      warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.

  4940. 

  4941.    Such warnings are printed both for user settable and GDB's internal

  4942. breakpoints.  If you see one of these warnings, you should verify that a

  4943. breakpoint set at the adjusted address will have the desired affect.  If

  4944. not, the breakpoint in question may be removed and other breakpoints may

  4945. be set which will have the desired behavior.  E.g., it may be sufficient

  4946. to place the breakpoint at a later instruction.  A conditional

  4947. breakpoint may also be useful in some cases to prevent the breakpoint

  4948. from triggering too often.

  4949. 

  4950.    GDB will also issue a warning when stopping at one of these adjusted

  4951. breakpoints:

  4952. 

  4953.      warning: Breakpoint 1 address previously adjusted from 0x00010414

  4954.      to 0x00010410.

  4955. 

  4956.    When this warning is encountered, it may be too late to take remedial

  4957. action except in cases where the breakpoint is hit earlier or more

  4958. frequently than expected.

  4959. 

  4960. 

  4961. File: gdb.info,  Node: Continuing and Stepping,  Next: Skipping Over Functions and Files,  Prev: Breakpoints,  Up: Stopping

  4962. 

  4963. 5.2 Continuing and Stepping

  4964. ===========================

  4965. 

  4966. "Continuing" means resuming program execution until your program

  4967. completes normally.  In contrast, "stepping" means executing just one

  4968. more "step" of your program, where "step" may mean either one line of

  4969. source code, or one machine instruction (depending on what particular

  4970. command you use).  Either when continuing or when stepping, your program

  4971. may stop even sooner, due to a breakpoint or a signal.  (If it stops due

  4972. to a signal, you may want to use 'handle', or use 'signal 0' to resume

  4973. execution (*note Signals: Signals.), or you may step into the signal's

  4974. handler (*note stepping and signal handlers::).)

  4975. 

  4976. 'continue [IGNORE-COUNT]'

  4977. 'c [IGNORE-COUNT]'

  4978. 'fg [IGNORE-COUNT]'

  4979.      Resume program execution, at the address where your program last

  4980.      stopped; any breakpoints set at that address are bypassed.  The

  4981.      optional argument IGNORE-COUNT allows you to specify a further

  4982.      number of times to ignore a breakpoint at this location; its effect

  4983.      is like that of 'ignore' (*note Break Conditions: Conditions.).

  4984. 

  4985.      The argument IGNORE-COUNT is meaningful only when your program

  4986.      stopped due to a breakpoint.  At other times, the argument to

  4987.      'continue' is ignored.

  4988. 

  4989.      The synonyms 'c' and 'fg' (for "foreground", as the debugged

  4990.      program is deemed to be the foreground program) are provided purely

  4991.      for convenience, and have exactly the same behavior as 'continue'.

  4992. 

  4993.    To resume execution at a different place, you can use 'return' (*note

  4994. Returning from a Function: Returning.) to go back to the calling

  4995. function; or 'jump' (*note Continuing at a Different Address: Jumping.)

  4996. to go to an arbitrary location in your program.

  4997. 

  4998.    A typical technique for using stepping is to set a breakpoint (*note

  4999. Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the

  5000. beginning of the function or the section of your program where a problem

  5001. is believed to lie, run your program until it stops at that breakpoint,

  5002. and then step through the suspect area, examining the variables that are

  5003. interesting, until you see the problem happen.

  5004. 

  5005. 'step'

  5006.      Continue running your program until control reaches a different

  5007.      source line, then stop it and return control to GDB.  This command

  5008.      is abbreviated 's'.

  5009. 

  5010.           _Warning:_ If you use the 'step' command while control is

  5011.           within a function that was compiled without debugging

  5012.           information, execution proceeds until control reaches a

  5013.           function that does have debugging information.  Likewise, it

  5014.           will not step into a function which is compiled without

  5015.           debugging information.  To step through functions without

  5016.           debugging information, use the 'stepi' command, described

  5017.           below.

  5018. 

  5019.      The 'step' command only stops at the first instruction of a source

  5020.      line.  This prevents the multiple stops that could otherwise occur

  5021.      in 'switch' statements, 'for' loops, etc.  'step' continues to stop

  5022.      if a function that has debugging information is called within the

  5023.      line.  In other words, 'step' _steps inside_ any functions called

  5024.      within the line.

  5025. 

  5026.      Also, the 'step' command only enters a function if there is line

  5027.      number information for the function.  Otherwise it acts like the

  5028.      'next' command.  This avoids problems when using 'cc -gl' on MIPS

  5029.      machines.  Previously, 'step' entered subroutines if there was any

  5030.      debugging information about the routine.

  5031. 

  5032. 'step COUNT'

  5033.      Continue running as in 'step', but do so COUNT times.  If a

  5034.      breakpoint is reached, or a signal not related to stepping occurs

  5035.      before COUNT steps, stepping stops right away.

  5036. 

  5037. 'next [COUNT]'

  5038.      Continue to the next source line in the current (innermost) stack

  5039.      frame.  This is similar to 'step', but function calls that appear

  5040.      within the line of code are executed without stopping.  Execution

  5041.      stops when control reaches a different line of code at the original

  5042.      stack level that was executing when you gave the 'next' command.

  5043.      This command is abbreviated 'n'.

  5044. 

  5045.      An argument COUNT is a repeat count, as for 'step'.

  5046. 

  5047.      The 'next' command only stops at the first instruction of a source

  5048.      line.  This prevents multiple stops that could otherwise occur in

  5049.      'switch' statements, 'for' loops, etc.

  5050. 

  5051. 'set step-mode'

  5052. 'set step-mode on'

  5053.      The 'set step-mode on' command causes the 'step' command to stop at

  5054.      the first instruction of a function which contains no debug line

  5055.      information rather than stepping over it.

  5056. 

  5057.      This is useful in cases where you may be interested in inspecting

  5058.      the machine instructions of a function which has no symbolic info

  5059.      and do not want GDB to automatically skip over this function.

  5060. 

  5061. 'set step-mode off'

  5062.      Causes the 'step' command to step over any functions which contains

  5063.      no debug information.  This is the default.

  5064. 

  5065. 'show step-mode'

  5066.      Show whether GDB will stop in or step over functions without source

  5067.      line debug information.

  5068. 

  5069. 'finish'

  5070.      Continue running until just after function in the selected stack

  5071.      frame returns.  Print the returned value (if any).  This command

  5072.      can be abbreviated as 'fin'.

  5073. 

  5074.      Contrast this with the 'return' command (*note Returning from a

  5075.      Function: Returning.).

  5076. 

  5077. 'set print finish [on|off]'

  5078. 'show print finish'

  5079.      By default the 'finish' command will show the value that is

  5080.      returned by the function.  This can be disabled using 'set print

  5081.      finish off'.  When disabled, the value is still entered into the

  5082.      value history (*note Value History::), but not displayed.

  5083. 

  5084. 'until'

  5085. 'u'

  5086.      Continue running until a source line past the current line, in the

  5087.      current stack frame, is reached.  This command is used to avoid

  5088.      single stepping through a loop more than once.  It is like the

  5089.      'next' command, except that when 'until' encounters a jump, it

  5090.      automatically continues execution until the program counter is

  5091.      greater than the address of the jump.

  5092. 

  5093.      This means that when you reach the end of a loop after single

  5094.      stepping though it, 'until' makes your program continue execution

  5095.      until it exits the loop.  In contrast, a 'next' command at the end

  5096.      of a loop simply steps back to the beginning of the loop, which

  5097.      forces you to step through the next iteration.

  5098. 

  5099.      'until' always stops your program if it attempts to exit the

  5100.      current stack frame.

  5101. 

  5102.      'until' may produce somewhat counterintuitive results if the order

  5103.      of machine code does not match the order of the source lines.  For

  5104.      example, in the following excerpt from a debugging session, the 'f'

  5105.      ('frame') command shows that execution is stopped at line '206';

  5106.      yet when we use 'until', we get to line '195':

  5107. 

  5108.           (gdb) f

  5109.           #0  main (argc=4, argv=0xf7fffae8) at m4.c:206

  5110.           206                 expand_input();

  5111.           (gdb) until

  5112.           195             for ( ; argc > 0; NEXTARG) {

  5113. 

  5114.      This happened because, for execution efficiency, the compiler had

  5115.      generated code for the loop closure test at the end, rather than

  5116.      the start, of the loop--even though the test in a C 'for'-loop is

  5117.      written before the body of the loop.  The 'until' command appeared

  5118.      to step back to the beginning of the loop when it advanced to this

  5119.      expression; however, it has not really gone to an earlier

  5120.      statement--not in terms of the actual machine code.

  5121. 

  5122.      'until' with no argument works by means of single instruction

  5123.      stepping, and hence is slower than 'until' with an argument.

  5124. 

  5125. 'until LOCATION'

  5126. 'u LOCATION'

  5127.      Continue running your program until either the specified LOCATION

  5128.      is reached, or the current stack frame returns.  The location is

  5129.      any of the forms described in *note Specify Location::.  This form

  5130.      of the command uses temporary breakpoints, and hence is quicker

  5131.      than 'until' without an argument.  The specified location is

  5132.      actually reached only if it is in the current frame.  This implies

  5133.      that 'until' can be used to skip over recursive function

  5134.      invocations.  For instance in the code below, if the current

  5135.      location is line '96', issuing 'until 99' will execute the program

  5136.      up to line '99' in the same invocation of factorial, i.e., after

  5137.      the inner invocations have returned.

  5138. 

  5139.           94	int factorial (int value)

  5140.           95	{

  5141.           96	    if (value > 1) {

  5142.           97            value *= factorial (value - 1);

  5143.           98	    }

  5144.           99	    return (value);

  5145.           100     }

  5146. 

  5147. 'advance LOCATION'

  5148.      Continue running the program up to the given LOCATION.  An argument

  5149.      is required, which should be of one of the forms described in *note

  5150.      Specify Location::.  Execution will also stop upon exit from the

  5151.      current stack frame.  This command is similar to 'until', but

  5152.      'advance' will not skip over recursive function calls, and the

  5153.      target location doesn't have to be in the same frame as the current

  5154.      one.

  5155. 

  5156. 'stepi'

  5157. 'stepi ARG'

  5158. 'si'

  5159.      Execute one machine instruction, then stop and return to the

  5160.      debugger.

  5161. 

  5162.      It is often useful to do 'display/i $pc' when stepping by machine

  5163.      instructions.  This makes GDB automatically display the next

  5164.      instruction to be executed, each time your program stops.  *Note

  5165.      Automatic Display: Auto Display.

  5166. 

  5167.      An argument is a repeat count, as in 'step'.

  5168. 

  5169. 'nexti'

  5170. 'nexti ARG'

  5171. 'ni'

  5172.      Execute one machine instruction, but if it is a function call,

  5173.      proceed until the function returns.

  5174. 

  5175.      An argument is a repeat count, as in 'next'.

  5176. 

  5177.    By default, and if available, GDB makes use of target-assisted "range

  5178. stepping".  In other words, whenever you use a stepping command (e.g.,

  5179. 'step', 'next'), GDB tells the target to step the corresponding range of

  5180. instruction addresses instead of issuing multiple single-steps.  This

  5181. speeds up line stepping, particularly for remote targets.  Ideally,

  5182. there should be no reason you would want to turn range stepping off.

  5183. However, it's possible that a bug in the debug info, a bug in the remote

  5184. stub (for remote targets), or even a bug in GDB could make line stepping

  5185. behave incorrectly when target-assisted range stepping is enabled.  You

  5186. can use the following command to turn off range stepping if necessary:

  5187. 

  5188. 'set range-stepping'

  5189. 'show range-stepping'

  5190.      Control whether range stepping is enabled.

  5191. 

  5192.      If 'on', and the target supports it, GDB tells the target to step a

  5193.      range of addresses itself, instead of issuing multiple

  5194.      single-steps.  If 'off', GDB always issues single-steps, even if

  5195.      range stepping is supported by the target.  The default is 'on'.

  5196. 

  5197. 

  5198. File: gdb.info,  Node: Skipping Over Functions and Files,  Next: Signals,  Prev: Continuing and Stepping,  Up: Stopping

  5199. 

  5200. 5.3 Skipping Over Functions and Files

  5201. =====================================

  5202. 

  5203. The program you are debugging may contain some functions which are

  5204. uninteresting to debug.  The 'skip' command lets you tell GDB to skip a

  5205. function, all functions in a file or a particular function in a

  5206. particular file when stepping.

  5207. 

  5208.    For example, consider the following C function:

  5209. 

  5210.      101     int func()

  5211.      102     {

  5212.      103         foo(boring());

  5213.      104         bar(boring());

  5214.      105     }

  5215. 

  5216. Suppose you wish to step into the functions 'foo' and 'bar', but you are

  5217. not interested in stepping through 'boring'.  If you run 'step' at line

  5218. 103, you'll enter 'boring()', but if you run 'next', you'll step over

  5219. both 'foo' and 'boring'!

  5220. 

  5221.    One solution is to 'step' into 'boring' and use the 'finish' command

  5222. to immediately exit it.  But this can become tedious if 'boring' is

  5223. called from many places.

  5224. 

  5225.    A more flexible solution is to execute 'skip boring'.  This instructs

  5226. GDB never to step into 'boring'.  Now when you execute 'step' at line

  5227. 103, you'll step over 'boring' and directly into 'foo'.

  5228. 

  5229.    Functions may be skipped by providing either a function name,

  5230. linespec (*note Specify Location::), regular expression that matches the

  5231. function's name, file name or a 'glob'-style pattern that matches the

  5232. file name.

  5233. 

  5234.    On Posix systems the form of the regular expression is "Extended

  5235. Regular Expressions".  See for example 'man 7 regex' on GNU/Linux

  5236. systems.  On non-Posix systems the form of the regular expression is

  5237. whatever is provided by the 'regcomp' function of the underlying system.

  5238. See for example 'man 7 glob' on GNU/Linux systems for a description of

  5239. 'glob'-style patterns.

  5240. 

  5241. 'skip [OPTIONS]'

  5242.      The basic form of the 'skip' command takes zero or more options

  5243.      that specify what to skip.  The OPTIONS argument is any useful

  5244.      combination of the following:

  5245. 

  5246.      '-file FILE'

  5247.      '-fi FILE'

  5248.           Functions in FILE will be skipped over when stepping.

  5249. 

  5250.      '-gfile FILE-GLOB-PATTERN'

  5251.      '-gfi FILE-GLOB-PATTERN'

  5252.           Functions in files matching FILE-GLOB-PATTERN will be skipped

  5253.           over when stepping.

  5254. 

  5255.                (gdb) skip -gfi utils/*.c

  5256. 

  5257.      '-function LINESPEC'

  5258.      '-fu LINESPEC'

  5259.           Functions named by LINESPEC or the function containing the

  5260.           line named by LINESPEC will be skipped over when stepping.

  5261.           *Note Specify Location::.

  5262. 

  5263.      '-rfunction REGEXP'

  5264.      '-rfu REGEXP'

  5265.           Functions whose name matches REGEXP will be skipped over when

  5266.           stepping.

  5267. 

  5268.           This form is useful for complex function names.  For example,

  5269.           there is generally no need to step into C++ 'std::string'

  5270.           constructors or destructors.  Plus with C++ templates it can

  5271.           be hard to write out the full name of the function, and often

  5272.           it doesn't matter what the template arguments are.  Specifying

  5273.           the function to be skipped as a regular expression makes this

  5274.           easier.

  5275. 

  5276.                (gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(

  5277. 

  5278.           If you want to skip every templated C++ constructor and

  5279.           destructor in the 'std' namespace you can do:

  5280. 

  5281.                (gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(

  5282. 

  5283.      If no options are specified, the function you're currently

  5284.      debugging will be skipped.

  5285. 

  5286. 'skip function [LINESPEC]'

  5287.      After running this command, the function named by LINESPEC or the

  5288.      function containing the line named by LINESPEC will be skipped over

  5289.      when stepping.  *Note Specify Location::.

  5290. 

  5291.      If you do not specify LINESPEC, the function you're currently

  5292.      debugging will be skipped.

  5293. 

  5294.      (If you have a function called 'file' that you want to skip, use

  5295.      'skip function file'.)

  5296. 

  5297. 'skip file [FILENAME]'

  5298.      After running this command, any function whose source lives in

  5299.      FILENAME will be skipped over when stepping.

  5300. 

  5301.           (gdb) skip file boring.c

  5302.           File boring.c will be skipped when stepping.

  5303. 

  5304.      If you do not specify FILENAME, functions whose source lives in the

  5305.      file you're currently debugging will be skipped.

  5306. 

  5307.    Skips can be listed, deleted, disabled, and enabled, much like

  5308. breakpoints.  These are the commands for managing your list of skips:

  5309. 

  5310. 'info skip [RANGE]'

  5311.      Print details about the specified skip(s).  If RANGE is not

  5312.      specified, print a table with details about all functions and files

  5313.      marked for skipping.  'info skip' prints the following information

  5314.      about each skip:

  5315. 

  5316.      _Identifier_

  5317.           A number identifying this skip.

  5318.      _Enabled or Disabled_

  5319.           Enabled skips are marked with 'y'.  Disabled skips are marked

  5320.           with 'n'.

  5321.      _Glob_

  5322.           If the file name is a 'glob' pattern this is 'y'.  Otherwise

  5323.           it is 'n'.

  5324.      _File_

  5325.           The name or 'glob' pattern of the file to be skipped.  If no

  5326.           file is specified this is '<none>'.

  5327.      _RE_

  5328.           If the function name is a 'regular expression' this is 'y'.

  5329.           Otherwise it is 'n'.

  5330.      _Function_

  5331.           The name or regular expression of the function to skip.  If no

  5332.           function is specified this is '<none>'.

  5333. 

  5334. 'skip delete [RANGE]'

  5335.      Delete the specified skip(s).  If RANGE is not specified, delete

  5336.      all skips.

  5337. 

  5338. 'skip enable [RANGE]'

  5339.      Enable the specified skip(s).  If RANGE is not specified, enable

  5340.      all skips.

  5341. 

  5342. 'skip disable [RANGE]'

  5343.      Disable the specified skip(s).  If RANGE is not specified, disable

  5344.      all skips.

  5345. 

  5346. 'set debug skip [on|off]'

  5347.      Set whether to print the debug output about skipping files and

  5348.      functions.

  5349. 

  5350. 'show debug skip'

  5351.      Show whether the debug output about skipping files and functions is

  5352.      printed.

  5353. 

  5354. 

  5355. File: gdb.info,  Node: Signals,  Next: Thread Stops,  Prev: Skipping Over Functions and Files,  Up: Stopping

  5356. 

  5357. 5.4 Signals

  5358. ===========

  5359. 

  5360. A signal is an asynchronous event that can happen in a program.  The

  5361. operating system defines the possible kinds of signals, and gives each

  5362. kind a name and a number.  For example, in Unix 'SIGINT' is the signal a

  5363. program gets when you type an interrupt character (often 'Ctrl-c');

  5364. 'SIGSEGV' is the signal a program gets from referencing a place in

  5365. memory far away from all the areas in use; 'SIGALRM' occurs when the

  5366. alarm clock timer goes off (which happens only if your program has

  5367. requested an alarm).

  5368. 

  5369.    Some signals, including 'SIGALRM', are a normal part of the

  5370. functioning of your program.  Others, such as 'SIGSEGV', indicate

  5371. errors; these signals are "fatal" (they kill your program immediately)

  5372. if the program has not specified in advance some other way to handle the

  5373. signal.  'SIGINT' does not indicate an error in your program, but it is

  5374. normally fatal so it can carry out the purpose of the interrupt: to kill

  5375. the program.

  5376. 

  5377.    GDB has the ability to detect any occurrence of a signal in your

  5378. program.  You can tell GDB in advance what to do for each kind of

  5379. signal.

  5380. 

  5381.    Normally, GDB is set up to let the non-erroneous signals like

  5382. 'SIGALRM' be silently passed to your program (so as not to interfere

  5383. with their role in the program's functioning) but to stop your program

  5384. immediately whenever an error signal happens.  You can change these

  5385. settings with the 'handle' command.

  5386. 

  5387. 'info signals'

  5388. 'info handle'

  5389.      Print a table of all the kinds of signals and how GDB has been told

  5390.      to handle each one.  You can use this to see the signal numbers of

  5391.      all the defined types of signals.

  5392. 

  5393. 'info signals SIG'

  5394.      Similar, but print information only about the specified signal

  5395.      number.

  5396. 

  5397.      'info handle' is an alias for 'info signals'.

  5398. 

  5399. 'catch signal [SIGNAL... | 'all']'

  5400.      Set a catchpoint for the indicated signals.  *Note Set

  5401.      Catchpoints::, for details about this command.

  5402. 

  5403. 'handle SIGNAL [KEYWORDS...]'

  5404.      Change the way GDB handles signal SIGNAL.  The SIGNAL can be the

  5405.      number of a signal or its name (with or without the 'SIG' at the

  5406.      beginning); a list of signal numbers of the form 'LOW-HIGH'; or the

  5407.      word 'all', meaning all the known signals.  Optional arguments

  5408.      KEYWORDS, described below, say what change to make.

  5409. 

  5410.    The keywords allowed by the 'handle' command can be abbreviated.

  5411. Their full names are:

  5412. 

  5413. 'nostop'

  5414.      GDB should not stop your program when this signal happens.  It may

  5415.      still print a message telling you that the signal has come in.

  5416. 

  5417. 'stop'

  5418.      GDB should stop your program when this signal happens.  This

  5419.      implies the 'print' keyword as well.

  5420. 

  5421. 'print'

  5422.      GDB should print a message when this signal happens.

  5423. 

  5424. 'noprint'

  5425.      GDB should not mention the occurrence of the signal at all.  This

  5426.      implies the 'nostop' keyword as well.

  5427. 

  5428. 'pass'

  5429. 'noignore'

  5430.      GDB should allow your program to see this signal; your program can

  5431.      handle the signal, or else it may terminate if the signal is fatal

  5432.      and not handled.  'pass' and 'noignore' are synonyms.

  5433. 

  5434. 'nopass'

  5435. 'ignore'

  5436.      GDB should not allow your program to see this signal.  'nopass' and

  5437.      'ignore' are synonyms.

  5438. 

  5439.    When a signal stops your program, the signal is not visible to the

  5440. program until you continue.  Your program sees the signal then, if

  5441. 'pass' is in effect for the signal in question _at that time_.  In other

  5442. words, after GDB reports a signal, you can use the 'handle' command with

  5443. 'pass' or 'nopass' to control whether your program sees that signal when

  5444. you continue.

  5445. 

  5446.    The default is set to 'nostop', 'noprint', 'pass' for non-erroneous

  5447. signals such as 'SIGALRM', 'SIGWINCH' and 'SIGCHLD', and to 'stop',

  5448. 'print', 'pass' for the erroneous signals.

  5449. 

  5450.    You can also use the 'signal' command to prevent your program from

  5451. seeing a signal, or cause it to see a signal it normally would not see,

  5452. or to give it any signal at any time.  For example, if your program

  5453. stopped due to some sort of memory reference error, you might store

  5454. correct values into the erroneous variables and continue, hoping to see

  5455. more execution; but your program would probably terminate immediately as

  5456. a result of the fatal signal once it saw the signal.  To prevent this,

  5457. you can continue with 'signal 0'.  *Note Giving your Program a Signal:

  5458. Signaling.

  5459. 

  5460.    GDB optimizes for stepping the mainline code.  If a signal that has

  5461. 'handle nostop' and 'handle pass' set arrives while a stepping command

  5462. (e.g., 'stepi', 'step', 'next') is in progress, GDB lets the signal

  5463. handler run and then resumes stepping the mainline code once the signal

  5464. handler returns.  In other words, GDB steps over the signal handler.

  5465. This prevents signals that you've specified as not interesting (with

  5466. 'handle nostop') from changing the focus of debugging unexpectedly.

  5467. Note that the signal handler itself may still hit a breakpoint, stop for

  5468. another signal that has 'handle stop' in effect, or for any other event

  5469. that normally results in stopping the stepping command sooner.  Also

  5470. note that GDB still informs you that the program received a signal if

  5471. 'handle print' is set.

  5472. 

  5473.    If you set 'handle pass' for a signal, and your program sets up a

  5474. handler for it, then issuing a stepping command, such as 'step' or

  5475. 'stepi', when your program is stopped due to the signal will step _into_

  5476. the signal handler (if the target supports that).

  5477. 

  5478.    Likewise, if you use the 'queue-signal' command to queue a signal to

  5479. be delivered to the current thread when execution of the thread resumes

  5480. (*note Giving your Program a Signal: Signaling.), then a stepping

  5481. command will step into the signal handler.

  5482. 

  5483.    Here's an example, using 'stepi' to step to the first instruction of

  5484. 'SIGUSR1''s handler:

  5485. 

  5486.      (gdb) handle SIGUSR1

  5487.      Signal        Stop      Print   Pass to program Description

  5488.      SIGUSR1       Yes       Yes     Yes             User defined signal 1

  5489.      (gdb) c

  5490.      Continuing.

  5491. 

  5492.      Program received signal SIGUSR1, User defined signal 1.

  5493.      main () sigusr1.c:28

  5494.      28        p = 0;

  5495.      (gdb) si

  5496.      sigusr1_handler () at sigusr1.c:9

  5497.      9       {

  5498. 

  5499.    The same, but using 'queue-signal' instead of waiting for the program

  5500. to receive the signal first:

  5501. 

  5502.      (gdb) n

  5503.      28        p = 0;

  5504.      (gdb) queue-signal SIGUSR1

  5505.      (gdb) si

  5506.      sigusr1_handler () at sigusr1.c:9

  5507.      9       {

  5508.      (gdb)

  5509. 

  5510.    On some targets, GDB can inspect extra signal information associated

  5511. with the intercepted signal, before it is actually delivered to the

  5512. program being debugged.  This information is exported by the convenience

  5513. variable '$_siginfo', and consists of data that is passed by the kernel

  5514. to the signal handler at the time of the receipt of a signal.  The data

  5515. type of the information itself is target dependent.  You can see the

  5516. data type using the 'ptype $_siginfo' command.  On Unix systems, it

  5517. typically corresponds to the standard 'siginfo_t' type, as defined in

  5518. the 'signal.h' system header.

  5519. 

  5520.    Here's an example, on a GNU/Linux system, printing the stray

  5521. referenced address that raised a segmentation fault.

  5522. 

  5523.      (gdb) continue

  5524.      Program received signal SIGSEGV, Segmentation fault.

  5525.      0x0000000000400766 in main ()

  5526.      69        *(int *)p = 0;

  5527.      (gdb) ptype $_siginfo

  5528.      type = struct {

  5529.          int si_signo;

  5530.          int si_errno;

  5531.          int si_code;

  5532.          union {

  5533.              int _pad[28];

  5534.              struct {...} _kill;

  5535.              struct {...} _timer;

  5536.              struct {...} _rt;

  5537.              struct {...} _sigchld;

  5538.              struct {...} _sigfault;

  5539.              struct {...} _sigpoll;

  5540.          } _sifields;

  5541.      }

  5542.      (gdb) ptype $_siginfo._sifields._sigfault

  5543.      type = struct {

  5544.          void *si_addr;

  5545.      }

  5546.      (gdb) p $_siginfo._sifields._sigfault.si_addr

  5547.      $1 = (void *) 0x7ffff7ff7000

  5548. 

  5549.    Depending on target support, '$_siginfo' may also be writable.

  5550. 

  5551.    On some targets, a 'SIGSEGV' can be caused by a boundary violation,

  5552. i.e., accessing an address outside of the allowed range.  In those cases

  5553. GDB may displays additional information, depending on how GDB has been

  5554. told to handle the signal.  With 'handle stop SIGSEGV', GDB displays the

  5555. violation kind: "Upper" or "Lower", the memory address accessed and the

  5556. bounds, while with 'handle nostop SIGSEGV' no additional information is

  5557. displayed.

  5558. 

  5559.    The usual output of a segfault is:

  5560.      Program received signal SIGSEGV, Segmentation fault

  5561.      0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68

  5562.      68        value = *(p + len);

  5563. 

  5564.    While a bound violation is presented as:

  5565.      Program received signal SIGSEGV, Segmentation fault

  5566.      Upper bound violation while accessing address 0x7fffffffc3b3

  5567.      Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]

  5568.      0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68

  5569.      68        value = *(p + len);

  5570. 

  5571. 

  5572. File: gdb.info,  Node: Thread Stops,  Prev: Signals,  Up: Stopping

  5573. 

  5574. 5.5 Stopping and Starting Multi-thread Programs

  5575. ===============================================

  5576. 

  5577. GDB supports debugging programs with multiple threads (*note Debugging

  5578. Programs with Multiple Threads: Threads.).  There are two modes of

  5579. controlling execution of your program within the debugger.  In the

  5580. default mode, referred to as "all-stop mode", when any thread in your

  5581. program stops (for example, at a breakpoint or while being stepped), all

  5582. other threads in the program are also stopped by GDB.  On some targets,

  5583. GDB also supports "non-stop mode", in which other threads can continue

  5584. to run freely while you examine the stopped thread in the debugger.

  5585. 

  5586. * Menu:

  5587. 

  5588. * All-Stop Mode::		All threads stop when GDB takes control

  5589. * Non-Stop Mode::		Other threads continue to execute

  5590. * Background Execution::	Running your program asynchronously

  5591. * Thread-Specific Breakpoints::	Controlling breakpoints

  5592. * Interrupted System Calls::	GDB may interfere with system calls

  5593. * Observer Mode::               GDB does not alter program behavior

  5594. 

  5595. 

  5596. File: gdb.info,  Node: All-Stop Mode,  Next: Non-Stop Mode,  Up: Thread Stops

  5597. 

  5598. 5.5.1 All-Stop Mode

  5599. -------------------

  5600. 

  5601. In all-stop mode, whenever your program stops under GDB for any reason,

  5602. _all_ threads of execution stop, not just the current thread.  This

  5603. allows you to examine the overall state of the program, including

  5604. switching between threads, without worrying that things may change

  5605. underfoot.

  5606. 

  5607.    Conversely, whenever you restart the program, _all_ threads start

  5608. executing.  _This is true even when single-stepping_ with commands like

  5609. 'step' or 'next'.

  5610. 

  5611.    In particular, GDB cannot single-step all threads in lockstep.  Since

  5612. thread scheduling is up to your debugging target's operating system (not

  5613. controlled by GDB), other threads may execute more than one statement

  5614. while the current thread completes a single step.  Moreover, in general

  5615. other threads stop in the middle of a statement, rather than at a clean

  5616. statement boundary, when the program stops.

  5617. 

  5618.    You might even find your program stopped in another thread after

  5619. continuing or even single-stepping.  This happens whenever some other

  5620. thread runs into a breakpoint, a signal, or an exception before the

  5621. first thread completes whatever you requested.

  5622. 

  5623.    Whenever GDB stops your program, due to a breakpoint or a signal, it

  5624. automatically selects the thread where that breakpoint or signal

  5625. happened.  GDB alerts you to the context switch with a message such as

  5626. '[Switching to Thread N]' to identify the thread.

  5627. 

  5628.    On some OSes, you can modify GDB's default behavior by locking the OS

  5629. scheduler to allow only a single thread to run.

  5630. 

  5631. 'set scheduler-locking MODE'

  5632.      Set the scheduler locking mode.  It applies to normal execution,

  5633.      record mode, and replay mode.  If it is 'off', then there is no

  5634.      locking and any thread may run at any time.  If 'on', then only the

  5635.      current thread may run when the inferior is resumed.  The 'step'

  5636.      mode optimizes for single-stepping; it prevents other threads from

  5637.      preempting the current thread while you are stepping, so that the

  5638.      focus of debugging does not change unexpectedly.  Other threads

  5639.      never get a chance to run when you step, and they are completely

  5640.      free to run when you use commands like 'continue', 'until', or

  5641.      'finish'.  However, unless another thread hits a breakpoint during

  5642.      its timeslice, GDB does not change the current thread away from the

  5643.      thread that you are debugging.  The 'replay' mode behaves like

  5644.      'off' in record mode and like 'on' in replay mode.

  5645. 

  5646. 'show scheduler-locking'

  5647.      Display the current scheduler locking mode.

  5648. 

  5649.    By default, when you issue one of the execution commands such as

  5650. 'continue', 'next' or 'step', GDB allows only threads of the current

  5651. inferior to run.  For example, if GDB is attached to two inferiors, each

  5652. with two threads, the 'continue' command resumes only the two threads of

  5653. the current inferior.  This is useful, for example, when you debug a

  5654. program that forks and you want to hold the parent stopped (so that, for

  5655. instance, it doesn't run to exit), while you debug the child.  In other

  5656. situations, you may not be interested in inspecting the current state of

  5657. any of the processes GDB is attached to, and you may want to resume them

  5658. all until some breakpoint is hit.  In the latter case, you can instruct

  5659. GDB to allow all threads of all the inferiors to run with the

  5660. 'set schedule-multiple' command.

  5661. 

  5662. 'set schedule-multiple'

  5663.      Set the mode for allowing threads of multiple processes to be

  5664.      resumed when an execution command is issued.  When 'on', all

  5665.      threads of all processes are allowed to run.  When 'off', only the

  5666.      threads of the current process are resumed.  The default is 'off'.

  5667.      The 'scheduler-locking' mode takes precedence when set to 'on', or

  5668.      while you are stepping and set to 'step'.

  5669. 

  5670. 'show schedule-multiple'

  5671.      Display the current mode for resuming the execution of threads of

  5672.      multiple processes.

  5673. 

  5674. 

  5675. File: gdb.info,  Node: Non-Stop Mode,  Next: Background Execution,  Prev: All-Stop Mode,  Up: Thread Stops

  5676. 

  5677. 5.5.2 Non-Stop Mode

  5678. -------------------

  5679. 

  5680. For some multi-threaded targets, GDB supports an optional mode of

  5681. operation in which you can examine stopped program threads in the

  5682. debugger while other threads continue to execute freely.  This minimizes

  5683. intrusion when debugging live systems, such as programs where some

  5684. threads have real-time constraints or must continue to respond to

  5685. external events.  This is referred to as "non-stop" mode.

  5686. 

  5687.    In non-stop mode, when a thread stops to report a debugging event,

  5688. _only_ that thread is stopped; GDB does not stop other threads as well,

  5689. in contrast to the all-stop mode behavior.  Additionally, execution

  5690. commands such as 'continue' and 'step' apply by default only to the

  5691. current thread in non-stop mode, rather than all threads as in all-stop

  5692. mode.  This allows you to control threads explicitly in ways that are

  5693. not possible in all-stop mode -- for example, stepping one thread while

  5694. allowing others to run freely, stepping one thread while holding all

  5695. others stopped, or stepping several threads independently and

  5696. simultaneously.

  5697. 

  5698.    To enter non-stop mode, use this sequence of commands before you run

  5699. or attach to your program:

  5700. 

  5701.      # If using the CLI, pagination breaks non-stop.

  5702.      set pagination off

  5703. 

  5704.      # Finally, turn it on!

  5705.      set non-stop on

  5706. 

  5707.    You can use these commands to manipulate the non-stop mode setting:

  5708. 

  5709. 'set non-stop on'

  5710.      Enable selection of non-stop mode.

  5711. 'set non-stop off'

  5712.      Disable selection of non-stop mode.

  5713. 'show non-stop'

  5714.      Show the current non-stop enablement setting.

  5715. 

  5716.    Note these commands only reflect whether non-stop mode is enabled,

  5717. not whether the currently-executing program is being run in non-stop

  5718. mode.  In particular, the 'set non-stop' preference is only consulted

  5719. when GDB starts or connects to the target program, and it is generally

  5720. not possible to switch modes once debugging has started.  Furthermore,

  5721. since not all targets support non-stop mode, even when you have enabled

  5722. non-stop mode, GDB may still fall back to all-stop operation by default.

  5723. 

  5724.    In non-stop mode, all execution commands apply only to the current

  5725. thread by default.  That is, 'continue' only continues one thread.  To

  5726. continue all threads, issue 'continue -a' or 'c -a'.

  5727. 

  5728.    You can use GDB's background execution commands (*note Background

  5729. Execution::) to run some threads in the background while you continue to

  5730. examine or step others from GDB.  The MI execution commands (*note

  5731. GDB/MI Program Execution::) are always executed asynchronously in

  5732. non-stop mode.

  5733. 

  5734.    Suspending execution is done with the 'interrupt' command when

  5735. running in the background, or 'Ctrl-c' during foreground execution.  In

  5736. all-stop mode, this stops the whole process; but in non-stop mode the

  5737. interrupt applies only to the current thread.  To stop the whole

  5738. program, use 'interrupt -a'.

  5739. 

  5740.    Other execution commands do not currently support the '-a' option.

  5741. 

  5742.    In non-stop mode, when a thread stops, GDB doesn't automatically make

  5743. that thread current, as it does in all-stop mode.  This is because the

  5744. thread stop notifications are asynchronous with respect to GDB's command

  5745. interpreter, and it would be confusing if GDB unexpectedly changed to a

  5746. different thread just as you entered a command to operate on the

  5747. previously current thread.

  5748. 

  5749. 

  5750. File: gdb.info,  Node: Background Execution,  Next: Thread-Specific Breakpoints,  Prev: Non-Stop Mode,  Up: Thread Stops

  5751. 

  5752. 5.5.3 Background Execution

  5753. --------------------------

  5754. 

  5755. GDB's execution commands have two variants: the normal foreground

  5756. (synchronous) behavior, and a background (asynchronous) behavior.  In

  5757. foreground execution, GDB waits for the program to report that some

  5758. thread has stopped before prompting for another command.  In background

  5759. execution, GDB immediately gives a command prompt so that you can issue

  5760. other commands while your program runs.

  5761. 

  5762.    If the target doesn't support async mode, GDB issues an error message

  5763. if you attempt to use the background execution commands.

  5764. 

  5765.    To specify background execution, add a '&' to the command.  For

  5766. example, the background form of the 'continue' command is 'continue&',

  5767. or just 'c&'.  The execution commands that accept background execution

  5768. are:

  5769. 

  5770. 'run'

  5771.      *Note Starting your Program: Starting.

  5772. 

  5773. 'attach'

  5774.      *Note Debugging an Already-running Process: Attach.

  5775. 

  5776. 'step'

  5777.      *Note step: Continuing and Stepping.

  5778. 

  5779. 'stepi'

  5780.      *Note stepi: Continuing and Stepping.

  5781. 

  5782. 'next'

  5783.      *Note next: Continuing and Stepping.

  5784. 

  5785. 'nexti'

  5786.      *Note nexti: Continuing and Stepping.

  5787. 

  5788. 'continue'

  5789.      *Note continue: Continuing and Stepping.

  5790. 

  5791. 'finish'

  5792.      *Note finish: Continuing and Stepping.

  5793. 

  5794. 'until'

  5795.      *Note until: Continuing and Stepping.

  5796. 

  5797.    Background execution is especially useful in conjunction with

  5798. non-stop mode for debugging programs with multiple threads; see *note

  5799. Non-Stop Mode::.  However, you can also use these commands in the normal

  5800. all-stop mode with the restriction that you cannot issue another

  5801. execution command until the previous one finishes.  Examples of commands

  5802. that are valid in all-stop mode while the program is running include

  5803. 'help' and 'info break'.

  5804. 

  5805.    You can interrupt your program while it is running in the background

  5806. by using the 'interrupt' command.

  5807. 

  5808. 'interrupt'

  5809. 'interrupt -a'

  5810. 

  5811.      Suspend execution of the running program.  In all-stop mode,

  5812.      'interrupt' stops the whole process, but in non-stop mode, it stops

  5813.      only the current thread.  To stop the whole program in non-stop

  5814.      mode, use 'interrupt -a'.

  5815. 

  5816. 

  5817. File: gdb.info,  Node: Thread-Specific Breakpoints,  Next: Interrupted System Calls,  Prev: Background Execution,  Up: Thread Stops

  5818. 

  5819. 5.5.4 Thread-Specific Breakpoints

  5820. ---------------------------------

  5821. 

  5822. When your program has multiple threads (*note Debugging Programs with

  5823. Multiple Threads: Threads.), you can choose whether to set breakpoints

  5824. on all threads, or on a particular thread.

  5825. 

  5826. 'break LOCATION thread THREAD-ID'

  5827. 'break LOCATION thread THREAD-ID if ...'

  5828.      LOCATION specifies source lines; there are several ways of writing

  5829.      them (*note Specify Location::), but the effect is always to

  5830.      specify some source line.

  5831. 

  5832.      Use the qualifier 'thread THREAD-ID' with a breakpoint command to

  5833.      specify that you only want GDB to stop the program when a

  5834.      particular thread reaches this breakpoint.  The THREAD-ID specifier

  5835.      is one of the thread identifiers assigned by GDB, shown in the

  5836.      first column of the 'info threads' display.

  5837. 

  5838.      If you do not specify 'thread THREAD-ID' when you set a breakpoint,

  5839.      the breakpoint applies to _all_ threads of your program.

  5840. 

  5841.      You can use the 'thread' qualifier on conditional breakpoints as

  5842.      well; in this case, place 'thread THREAD-ID' before or after the

  5843.      breakpoint condition, like this:

  5844. 

  5845.           (gdb) break frik.c:13 thread 28 if bartab > lim

  5846. 

  5847.    Thread-specific breakpoints are automatically deleted when GDB

  5848. detects the corresponding thread is no longer in the thread list.  For

  5849. example:

  5850. 

  5851.      (gdb) c

  5852.      Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.

  5853. 

  5854.    There are several ways for a thread to disappear, such as a regular

  5855. thread exit, but also when you detach from the process with the 'detach'

  5856. command (*note Debugging an Already-running Process: Attach.), or if GDB

  5857. loses the remote connection (*note Remote Debugging::), etc.  Note that

  5858. with some targets, GDB is only able to detect a thread has exited when

  5859. the user explictly asks for the thread list with the 'info threads'

  5860. command.

  5861. 

  5862. 

  5863. File: gdb.info,  Node: Interrupted System Calls,  Next: Observer Mode,  Prev: Thread-Specific Breakpoints,  Up: Thread Stops

  5864. 

  5865. 5.5.5 Interrupted System Calls

  5866. ------------------------------

  5867. 

  5868. There is an unfortunate side effect when using GDB to debug

  5869. multi-threaded programs.  If one thread stops for a breakpoint, or for

  5870. some other reason, and another thread is blocked in a system call, then

  5871. the system call may return prematurely.  This is a consequence of the

  5872. interaction between multiple threads and the signals that GDB uses to

  5873. implement breakpoints and other events that stop execution.

  5874. 

  5875.    To handle this problem, your program should check the return value of

  5876. each system call and react appropriately.  This is good programming

  5877. style anyways.

  5878. 

  5879.    For example, do not write code like this:

  5880. 

  5881.        sleep (10);

  5882. 

  5883.    The call to 'sleep' will return early if a different thread stops at

  5884. a breakpoint or for some other reason.

  5885. 

  5886.    Instead, write this:

  5887. 

  5888.        int unslept = 10;

  5889.        while (unslept > 0)

  5890.          unslept = sleep (unslept);

  5891. 

  5892.    A system call is allowed to return early, so the system is still

  5893. conforming to its specification.  But GDB does cause your multi-threaded

  5894. program to behave differently than it would without GDB.

  5895. 

  5896.    Also, GDB uses internal breakpoints in the thread library to monitor

  5897. certain events such as thread creation and thread destruction.  When

  5898. such an event happens, a system call in another thread may return

  5899. prematurely, even though your program does not appear to stop.

  5900. 

  5901. 

  5902. File: gdb.info,  Node: Observer Mode,  Prev: Interrupted System Calls,  Up: Thread Stops

  5903. 

  5904. 5.5.6 Observer Mode

  5905. -------------------

  5906. 

  5907. If you want to build on non-stop mode and observe program behavior

  5908. without any chance of disruption by GDB, you can set variables to

  5909. disable all of the debugger's attempts to modify state, whether by

  5910. writing memory, inserting breakpoints, etc.  These operate at a low

  5911. level, intercepting operations from all commands.

  5912. 

  5913.    When all of these are set to 'off', then GDB is said to be "observer

  5914. mode".  As a convenience, the variable 'observer' can be set to disable

  5915. these, plus enable non-stop mode.

  5916. 

  5917.    Note that GDB will not prevent you from making nonsensical

  5918. combinations of these settings.  For instance, if you have enabled

  5919. 'may-insert-breakpoints' but disabled 'may-write-memory', then

  5920. breakpoints that work by writing trap instructions into the code stream

  5921. will still not be able to be placed.

  5922. 

  5923. 'set observer on'

  5924. 'set observer off'

  5925.      When set to 'on', this disables all the permission variables below

  5926.      (except for 'insert-fast-tracepoints'), plus enables non-stop

  5927.      debugging.  Setting this to 'off' switches back to normal

  5928.      debugging, though remaining in non-stop mode.

  5929. 

  5930. 'show observer'

  5931.      Show whether observer mode is on or off.

  5932. 

  5933. 'set may-write-registers on'

  5934. 'set may-write-registers off'

  5935.      This controls whether GDB will attempt to alter the values of

  5936.      registers, such as with assignment expressions in 'print', or the

  5937.      'jump' command.  It defaults to 'on'.

  5938. 

  5939. 'show may-write-registers'

  5940.      Show the current permission to write registers.

  5941. 

  5942. 'set may-write-memory on'

  5943. 'set may-write-memory off'

  5944.      This controls whether GDB will attempt to alter the contents of

  5945.      memory, such as with assignment expressions in 'print'.  It

  5946.      defaults to 'on'.

  5947. 

  5948. 'show may-write-memory'

  5949.      Show the current permission to write memory.

  5950. 

  5951. 'set may-insert-breakpoints on'

  5952. 'set may-insert-breakpoints off'

  5953.      This controls whether GDB will attempt to insert breakpoints.  This

  5954.      affects all breakpoints, including internal breakpoints defined by

  5955.      GDB.  It defaults to 'on'.

  5956. 

  5957. 'show may-insert-breakpoints'

  5958.      Show the current permission to insert breakpoints.

  5959. 

  5960. 'set may-insert-tracepoints on'

  5961. 'set may-insert-tracepoints off'

  5962.      This controls whether GDB will attempt to insert (regular)

  5963.      tracepoints at the beginning of a tracing experiment.  It affects

  5964.      only non-fast tracepoints, fast tracepoints being under the control

  5965.      of 'may-insert-fast-tracepoints'.  It defaults to 'on'.

  5966. 

  5967. 'show may-insert-tracepoints'

  5968.      Show the current permission to insert tracepoints.

  5969. 

  5970. 'set may-insert-fast-tracepoints on'

  5971. 'set may-insert-fast-tracepoints off'

  5972.      This controls whether GDB will attempt to insert fast tracepoints

  5973.      at the beginning of a tracing experiment.  It affects only fast

  5974.      tracepoints, regular (non-fast) tracepoints being under the control

  5975.      of 'may-insert-tracepoints'.  It defaults to 'on'.

  5976. 

  5977. 'show may-insert-fast-tracepoints'

  5978.      Show the current permission to insert fast tracepoints.

  5979. 

  5980. 'set may-interrupt on'

  5981. 'set may-interrupt off'

  5982.      This controls whether GDB will attempt to interrupt or stop program

  5983.      execution.  When this variable is 'off', the 'interrupt' command

  5984.      will have no effect, nor will 'Ctrl-c'.  It defaults to 'on'.

  5985. 

  5986. 'show may-interrupt'

  5987.      Show the current permission to interrupt or stop the program.

  5988. 

  5989. 

  5990. File: gdb.info,  Node: Reverse Execution,  Next: Process Record and Replay,  Prev: Stopping,  Up: Top

  5991. 

  5992. 6 Running programs backward

  5993. ***************************

  5994. 

  5995. When you are debugging a program, it is not unusual to realize that you

  5996. have gone too far, and some event of interest has already happened.  If

  5997. the target environment supports it, GDB can allow you to "rewind" the

  5998. program by running it backward.

  5999. 

  6000.    A target environment that supports reverse execution should be able

  6001. to "undo" the changes in machine state that have taken place as the

  6002. program was executing normally.  Variables, registers etc. should revert

  6003. to their previous values.  Obviously this requires a great deal of

  6004. sophistication on the part of the target environment; not all target

  6005. environments can support reverse execution.

  6006. 

  6007.    When a program is executed in reverse, the instructions that have

  6008. most recently been executed are "un-executed", in reverse order.  The

  6009. program counter runs backward, following the previous thread of

  6010. execution in reverse.  As each instruction is "un-executed", the values

  6011. of memory and/or registers that were changed by that instruction are

  6012. reverted to their previous states.  After executing a piece of source

  6013. code in reverse, all side effects of that code should be "undone", and

  6014. all variables should be returned to their prior values(1).

  6015. 

  6016.    On some platforms, GDB has built-in support for reverse execution,

  6017. activated with the 'record' or 'record btrace' commands.  *Note Process

  6018. Record and Replay::.  Some remote targets, typically full system

  6019. emulators, support reverse execution directly without requiring any

  6020. special command.

  6021. 

  6022.    If you are debugging in a target environment that supports reverse

  6023. execution, GDB provides the following commands.

  6024. 

  6025. 'reverse-continue [IGNORE-COUNT]'

  6026. 'rc [IGNORE-COUNT]'

  6027.      Beginning at the point where your program last stopped, start

  6028.      executing in reverse.  Reverse execution will stop for breakpoints

  6029.      and synchronous exceptions (signals), just like normal execution.

  6030.      Behavior of asynchronous signals depends on the target environment.

  6031. 

  6032. 'reverse-step [COUNT]'

  6033.      Run the program backward until control reaches the start of a

  6034.      different source line; then stop it, and return control to GDB.

  6035. 

  6036.      Like the 'step' command, 'reverse-step' will only stop at the

  6037.      beginning of a source line.  It "un-executes" the previously

  6038.      executed source line.  If the previous source line included calls

  6039.      to debuggable functions, 'reverse-step' will step (backward) into

  6040.      the called function, stopping at the beginning of the _last_

  6041.      statement in the called function (typically a return statement).

  6042. 

  6043.      Also, as with the 'step' command, if non-debuggable functions are

  6044.      called, 'reverse-step' will run thru them backward without

  6045.      stopping.

  6046. 

  6047. 'reverse-stepi [COUNT]'

  6048.      Reverse-execute one machine instruction.  Note that the instruction

  6049.      to be reverse-executed is _not_ the one pointed to by the program

  6050.      counter, but the instruction executed prior to that one.  For

  6051.      instance, if the last instruction was a jump, 'reverse-stepi' will

  6052.      take you back from the destination of the jump to the jump

  6053.      instruction itself.

  6054. 

  6055. 'reverse-next [COUNT]'

  6056.      Run backward to the beginning of the previous line executed in the

  6057.      current (innermost) stack frame.  If the line contains function

  6058.      calls, they will be "un-executed" without stopping.  Starting from

  6059.      the first line of a function, 'reverse-next' will take you back to

  6060.      the caller of that function, _before_ the function was called, just

  6061.      as the normal 'next' command would take you from the last line of a

  6062.      function back to its return to its caller (2).

  6063. 

  6064. 'reverse-nexti [COUNT]'

  6065.      Like 'nexti', 'reverse-nexti' executes a single instruction in

  6066.      reverse, except that called functions are "un-executed" atomically.

  6067.      That is, if the previously executed instruction was a return from

  6068.      another function, 'reverse-nexti' will continue to execute in

  6069.      reverse until the call to that function (from the current stack

  6070.      frame) is reached.

  6071. 

  6072. 'reverse-finish'

  6073.      Just as the 'finish' command takes you to the point where the

  6074.      current function returns, 'reverse-finish' takes you to the point

  6075.      where it was called.  Instead of ending up at the end of the

  6076.      current function invocation, you end up at the beginning.

  6077. 

  6078. 'set exec-direction'

  6079.      Set the direction of target execution.

  6080. 'set exec-direction reverse'

  6081.      GDB will perform all execution commands in reverse, until the

  6082.      exec-direction mode is changed to "forward".  Affected commands

  6083.      include 'step, stepi, next, nexti, continue, and finish'.  The

  6084.      'return' command cannot be used in reverse mode.

  6085. 'set exec-direction forward'

  6086.      GDB will perform all execution commands in the normal fashion.

  6087.      This is the default.

  6088. 

  6089.    ---------- Footnotes ----------

  6090. 

  6091.    (1) Note that some side effects are easier to undo than others.  For

  6092. instance, memory and registers are relatively easy, but device I/O is

  6093. hard.  Some targets may be able undo things like device I/O, and some

  6094. may not.

  6095. 

  6096.    The contract between GDB and the reverse executing target requires

  6097. only that the target do something reasonable when GDB tells it to

  6098. execute backwards, and then report the results back to GDB.  Whatever

  6099. the target reports back to GDB, GDB will report back to the user.  GDB

  6100. assumes that the memory and registers that the target reports are in a

  6101. consistent state, but GDB accepts whatever it is given.

  6102. 

  6103.    (2) Unless the code is too heavily optimized.

  6104. 

  6105. 

  6106. File: gdb.info,  Node: Process Record and Replay,  Next: Stack,  Prev: Reverse Execution,  Up: Top

  6107. 

  6108. 7 Recording Inferior's Execution and Replaying It

  6109. *************************************************

  6110. 

  6111. On some platforms, GDB provides a special "process record and replay"

  6112. target that can record a log of the process execution, and replay it

  6113. later with both forward and reverse execution commands.

  6114. 

  6115.    When this target is in use, if the execution log includes the record

  6116. for the next instruction, GDB will debug in "replay mode".  In the

  6117. replay mode, the inferior does not really execute code instructions.

  6118. Instead, all the events that normally happen during code execution are

  6119. taken from the execution log.  While code is not really executed in

  6120. replay mode, the values of registers (including the program counter

  6121. register) and the memory of the inferior are still changed as they

  6122. normally would.  Their contents are taken from the execution log.

  6123. 

  6124.    If the record for the next instruction is not in the execution log,

  6125. GDB will debug in "record mode".  In this mode, the inferior executes

  6126. normally, and GDB records the execution log for future replay.

  6127. 

  6128.    The process record and replay target supports reverse execution

  6129. (*note Reverse Execution::), even if the platform on which the inferior

  6130. runs does not.  However, the reverse execution is limited in this case

  6131. by the range of the instructions recorded in the execution log.  In

  6132. other words, reverse execution on platforms that don't support it

  6133. directly can only be done in the replay mode.

  6134. 

  6135.    When debugging in the reverse direction, GDB will work in replay mode

  6136. as long as the execution log includes the record for the previous

  6137. instruction; otherwise, it will work in record mode, if the platform

  6138. supports reverse execution, or stop if not.

  6139. 

  6140.    Currently, process record and replay is supported on ARM, Aarch64,

  6141. Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running

  6142. GNU/Linux.  Process record and replay can be used both when native

  6143. debugging, and when remote debugging via 'gdbserver'.

  6144. 

  6145.    For architecture environments that support process record and replay,

  6146. GDB provides the following commands:

  6147. 

  6148. 'record METHOD'

  6149.      This command starts the process record and replay target.  The

  6150.      recording method can be specified as parameter.  Without a

  6151.      parameter the command uses the 'full' recording method.  The

  6152.      following recording methods are available:

  6153. 

  6154.      'full'

  6155.           Full record/replay recording using GDB's software record and

  6156.           replay implementation.  This method allows replaying and

  6157.           reverse execution.

  6158. 

  6159.      'btrace FORMAT'

  6160.           Hardware-supported instruction recording, supported on Intel

  6161.           processors.  This method does not record data.  Further, the

  6162.           data is collected in a ring buffer so old data will be

  6163.           overwritten when the buffer is full.  It allows limited

  6164.           reverse execution.  Variables and registers are not available

  6165.           during reverse execution.  In remote debugging, recording

  6166.           continues on disconnect.  Recorded data can be inspected after

  6167.           reconnecting.  The recording may be stopped using 'record

  6168.           stop'.

  6169. 

  6170.           The recording format can be specified as parameter.  Without a

  6171.           parameter the command chooses the recording format.  The

  6172.           following recording formats are available:

  6173. 

  6174.           'bts'

  6175.                Use the "Branch Trace Store" (BTS) recording format.  In

  6176.                this format, the processor stores a from/to record for

  6177.                each executed branch in the btrace ring buffer.

  6178. 

  6179.           'pt'

  6180.                Use the "Intel Processor Trace" recording format.  In

  6181.                this format, the processor stores the execution trace in

  6182.                a compressed form that is afterwards decoded by GDB.

  6183. 

  6184.                The trace can be recorded with very low overhead.  The

  6185.                compressed trace format also allows small trace buffers

  6186.                to already contain a big number of instructions compared

  6187.                to BTS.

  6188. 

  6189.                Decoding the recorded execution trace, on the other hand,

  6190.                is more expensive than decoding BTS trace.  This is

  6191.                mostly due to the increased number of instructions to

  6192.                process.  You should increase the buffer-size with care.

  6193. 

  6194.           Not all recording formats may be available on all processors.

  6195. 

  6196.      The process record and replay target can only debug a process that

  6197.      is already running.  Therefore, you need first to start the process

  6198.      with the 'run' or 'start' commands, and then start the recording

  6199.      with the 'record METHOD' command.

  6200. 

  6201.      Displaced stepping (*note displaced stepping: Maintenance

  6202.      Commands.) will be automatically disabled when process record and

  6203.      replay target is started.  That's because the process record and

  6204.      replay target doesn't support displaced stepping.

  6205. 

  6206.      If the inferior is in the non-stop mode (*note Non-Stop Mode::) or

  6207.      in the asynchronous execution mode (*note Background Execution::),

  6208.      not all recording methods are available.  The 'full' recording

  6209.      method does not support these two modes.

  6210. 

  6211. 'record stop'

  6212.      Stop the process record and replay target.  When process record and

  6213.      replay target stops, the entire execution log will be deleted and

  6214.      the inferior will either be terminated, or will remain in its final

  6215.      state.

  6216. 

  6217.      When you stop the process record and replay target in record mode

  6218.      (at the end of the execution log), the inferior will be stopped at

  6219.      the next instruction that would have been recorded.  In other

  6220.      words, if you record for a while and then stop recording, the

  6221.      inferior process will be left in the same state as if the recording

  6222.      never happened.

  6223. 

  6224.      On the other hand, if the process record and replay target is

  6225.      stopped while in replay mode (that is, not at the end of the

  6226.      execution log, but at some earlier point), the inferior process

  6227.      will become "live" at that earlier state, and it will then be

  6228.      possible to continue the usual "live" debugging of the process from

  6229.      that state.

  6230. 

  6231.      When the inferior process exits, or GDB detaches from it, process

  6232.      record and replay target will automatically stop itself.

  6233. 

  6234. 'record goto'

  6235.      Go to a specific location in the execution log.  There are several

  6236.      ways to specify the location to go to:

  6237. 

  6238.      'record goto begin'

  6239.      'record goto start'

  6240.           Go to the beginning of the execution log.

  6241. 

  6242.      'record goto end'

  6243.           Go to the end of the execution log.

  6244. 

  6245.      'record goto N'

  6246.           Go to instruction number N in the execution log.

  6247. 

  6248. 'record save FILENAME'

  6249.      Save the execution log to a file 'FILENAME'.  Default filename is

  6250.      'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the

  6251.      inferior.

  6252. 

  6253.      This command may not be available for all recording methods.

  6254. 

  6255. 'record restore FILENAME'

  6256.      Restore the execution log from a file 'FILENAME'.  File must have

  6257.      been created with 'record save'.

  6258. 

  6259. 'set record full insn-number-max LIMIT'

  6260. 'set record full insn-number-max unlimited'

  6261.      Set the limit of instructions to be recorded for the 'full'

  6262.      recording method.  Default value is 200000.

  6263. 

  6264.      If LIMIT is a positive number, then GDB will start deleting

  6265.      instructions from the log once the number of the record

  6266.      instructions becomes greater than LIMIT.  For every new recorded

  6267.      instruction, GDB will delete the earliest recorded instruction to

  6268.      keep the number of recorded instructions at the limit.  (Since

  6269.      deleting recorded instructions loses information, GDB lets you

  6270.      control what happens when the limit is reached, by means of the

  6271.      'stop-at-limit' option, described below.)

  6272. 

  6273.      If LIMIT is 'unlimited' or zero, GDB will never delete recorded

  6274.      instructions from the execution log.  The number of recorded

  6275.      instructions is limited only by the available memory.

  6276. 

  6277. 'show record full insn-number-max'

  6278.      Show the limit of instructions to be recorded with the 'full'

  6279.      recording method.

  6280. 

  6281. 'set record full stop-at-limit'

  6282.      Control the behavior of the 'full' recording method when the number

  6283.      of recorded instructions reaches the limit.  If ON (the default),

  6284.      GDB will stop when the limit is reached for the first time and ask

  6285.      you whether you want to stop the inferior or continue running it

  6286.      and recording the execution log.  If you decide to continue

  6287.      recording, each new recorded instruction will cause the oldest one

  6288.      to be deleted.

  6289. 

  6290.      If this option is OFF, GDB will automatically delete the oldest

  6291.      record to make room for each new one, without asking.

  6292. 

  6293. 'show record full stop-at-limit'

  6294.      Show the current setting of 'stop-at-limit'.

  6295. 

  6296. 'set record full memory-query'

  6297.      Control the behavior when GDB is unable to record memory changes

  6298.      caused by an instruction for the 'full' recording method.  If ON,

  6299.      GDB will query whether to stop the inferior in that case.

  6300. 

  6301.      If this option is OFF (the default), GDB will automatically ignore

  6302.      the effect of such instructions on memory.  Later, when GDB replays

  6303.      this execution log, it will mark the log of this instruction as not

  6304.      accessible, and it will not affect the replay results.

  6305. 

  6306. 'show record full memory-query'

  6307.      Show the current setting of 'memory-query'.

  6308. 

  6309.      The 'btrace' record target does not trace data.  As a convenience,

  6310.      when replaying, GDB reads read-only memory off the live program

  6311.      directly, assuming that the addresses of the read-only areas don't

  6312.      change.  This for example makes it possible to disassemble code

  6313.      while replaying, but not to print variables.  In some cases, being

  6314.      able to inspect variables might be useful.  You can use the

  6315.      following command for that:

  6316. 

  6317. 'set record btrace replay-memory-access'

  6318.      Control the behavior of the 'btrace' recording method when

  6319.      accessing memory during replay.  If 'read-only' (the default), GDB

  6320.      will only allow accesses to read-only memory.  If 'read-write', GDB

  6321.      will allow accesses to read-only and to read-write memory.  Beware

  6322.      that the accessed memory corresponds to the live target and not

  6323.      necessarily to the current replay position.

  6324. 

  6325. 'set record btrace cpu IDENTIFIER'

  6326.      Set the processor to be used for enabling workarounds for processor

  6327.      errata when decoding the trace.

  6328. 

  6329.      Processor errata are defects in processor operation, caused by its

  6330.      design or manufacture.  They can cause a trace not to match the

  6331.      specification.  This, in turn, may cause trace decode to fail.  GDB

  6332.      can detect erroneous trace packets and correct them, thus avoiding

  6333.      the decoding failures.  These corrections are known as "errata

  6334.      workarounds", and are enabled based on the processor on which the

  6335.      trace was recorded.

  6336. 

  6337.      By default, GDB attempts to detect the processor automatically, and

  6338.      apply the necessary workarounds for it.  However, you may need to

  6339.      specify the processor if GDB does not yet support it.  This command

  6340.      allows you to do that, and also allows to disable the workarounds.

  6341. 

  6342.      The argument IDENTIFIER identifies the CPU and is of the form:

  6343.      'VENDOR:PROCESSOR IDENTIFIER'.  In addition, there are two special

  6344.      identifiers, 'none' and 'auto' (default).

  6345. 

  6346.      The following vendor identifiers and corresponding processor

  6347.      identifiers are currently supported:

  6348. 

  6349.      'intel' FAMILY/MODEL[/STEPPING]

  6350.              

  6351. 

  6352.      On GNU/Linux systems, the processor FAMILY, MODEL, and STEPPING can

  6353.      be obtained from '/proc/cpuinfo'.

  6354. 

  6355.      If IDENTIFIER is 'auto', enable errata workarounds for the

  6356.      processor on which the trace was recorded.  If IDENTIFIER is

  6357.      'none', errata workarounds are disabled.

  6358. 

  6359.      For example, when using an old GDB on a new system, decode may fail

  6360.      because GDB does not support the new processor.  It often suffices

  6361.      to specify an older processor that GDB supports.

  6362. 

  6363.           (gdb) info record

  6364.           Active record target: record-btrace

  6365.           Recording format: Intel Processor Trace.

  6366.           Buffer size: 16kB.

  6367.           Failed to configure the Intel Processor Trace decoder: unknown cpu.

  6368.           (gdb) set record btrace cpu intel:6/158

  6369.           (gdb) info record

  6370.           Active record target: record-btrace

  6371.           Recording format: Intel Processor Trace.

  6372.           Buffer size: 16kB.

  6373.           Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...).

  6374. 

  6375. 'show record btrace replay-memory-access'

  6376.      Show the current setting of 'replay-memory-access'.

  6377. 

  6378. 'show record btrace cpu'

  6379.      Show the processor to be used for enabling trace decode errata

  6380.      workarounds.

  6381. 

  6382. 'set record btrace bts buffer-size SIZE'

  6383. 'set record btrace bts buffer-size unlimited'

  6384.      Set the requested ring buffer size for branch tracing in BTS

  6385.      format.  Default is 64KB.

  6386. 

  6387.      If SIZE is a positive number, then GDB will try to allocate a

  6388.      buffer of at least SIZE bytes for each new thread that uses the

  6389.      btrace recording method and the BTS format.  The actually obtained

  6390.      buffer size may differ from the requested SIZE.  Use the 'info

  6391.      record' command to see the actual buffer size for each thread that

  6392.      uses the btrace recording method and the BTS format.

  6393. 

  6394.      If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer

  6395.      of 4MB.

  6396. 

  6397.      Bigger buffers mean longer traces.  On the other hand, GDB will

  6398.      also need longer to process the branch trace data before it can be

  6399.      used.

  6400. 

  6401. 'show record btrace bts buffer-size SIZE'

  6402.      Show the current setting of the requested ring buffer size for

  6403.      branch tracing in BTS format.

  6404. 

  6405. 'set record btrace pt buffer-size SIZE'

  6406. 'set record btrace pt buffer-size unlimited'

  6407.      Set the requested ring buffer size for branch tracing in Intel

  6408.      Processor Trace format.  Default is 16KB.

  6409. 

  6410.      If SIZE is a positive number, then GDB will try to allocate a

  6411.      buffer of at least SIZE bytes for each new thread that uses the

  6412.      btrace recording method and the Intel Processor Trace format.  The

  6413.      actually obtained buffer size may differ from the requested SIZE.

  6414.      Use the 'info record' command to see the actual buffer size for

  6415.      each thread.

  6416. 

  6417.      If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer

  6418.      of 4MB.

  6419. 

  6420.      Bigger buffers mean longer traces.  On the other hand, GDB will

  6421.      also need longer to process the branch trace data before it can be

  6422.      used.

  6423. 

  6424. 'show record btrace pt buffer-size SIZE'

  6425.      Show the current setting of the requested ring buffer size for

  6426.      branch tracing in Intel Processor Trace format.

  6427. 

  6428. 'info record'

  6429.      Show various statistics about the recording depending on the

  6430.      recording method:

  6431. 

  6432.      'full'

  6433.           For the 'full' recording method, it shows the state of process

  6434.           record and its in-memory execution log buffer, including:

  6435. 

  6436.              * Whether in record mode or replay mode.

  6437.              * Lowest recorded instruction number (counting from when

  6438.                the current execution log started recording

  6439.                instructions).

  6440.              * Highest recorded instruction number.

  6441.              * Current instruction about to be replayed (if in replay

  6442.                mode).

  6443.              * Number of instructions contained in the execution log.

  6444.              * Maximum number of instructions that may be contained in

  6445.                the execution log.

  6446. 

  6447.      'btrace'

  6448.           For the 'btrace' recording method, it shows:

  6449. 

  6450.              * Recording format.

  6451.              * Number of instructions that have been recorded.

  6452.              * Number of blocks of sequential control-flow formed by the

  6453.                recorded instructions.

  6454.              * Whether in record mode or replay mode.

  6455. 

  6456.           For the 'bts' recording format, it also shows:

  6457.              * Size of the perf ring buffer.

  6458. 

  6459.           For the 'pt' recording format, it also shows:

  6460.              * Size of the perf ring buffer.

  6461. 

  6462. 'record delete'

  6463.      When record target runs in replay mode ("in the past"), delete the

  6464.      subsequent execution log and begin to record a new execution log

  6465.      starting from the current address.  This means you will abandon the

  6466.      previously recorded "future" and begin recording a new "future".

  6467. 

  6468. 'record instruction-history'

  6469.      Disassembles instructions from the recorded execution log.  By

  6470.      default, ten instructions are disassembled.  This can be changed

  6471.      using the 'set record instruction-history-size' command.

  6472.      Instructions are printed in execution order.

  6473. 

  6474.      It can also print mixed source+disassembly if you specify the the

  6475.      '/m' or '/s' modifier, and print the raw instructions in hex as

  6476.      well as in symbolic form by specifying the '/r' modifier.

  6477. 

  6478.      The current position marker is printed for the instruction at the

  6479.      current program counter value.  This instruction can appear

  6480.      multiple times in the trace and the current position marker will be

  6481.      printed every time.  To omit the current position marker, specify

  6482.      the '/p' modifier.

  6483. 

  6484.      To better align the printed instructions when the trace contains

  6485.      instructions from more than one function, the function name may be

  6486.      omitted by specifying the '/f' modifier.

  6487. 

  6488.      Speculatively executed instructions are prefixed with '?'.  This

  6489.      feature is not available for all recording formats.

  6490. 

  6491.      There are several ways to specify what part of the execution log to

  6492.      disassemble:

  6493. 

  6494.      'record instruction-history INSN'

  6495.           Disassembles ten instructions starting from instruction number

  6496.           INSN.

  6497. 

  6498.      'record instruction-history INSN, +/-N'

  6499.           Disassembles N instructions around instruction number INSN.

  6500.           If N is preceded with '+', disassembles N instructions after

  6501.           instruction number INSN.  If N is preceded with '-',

  6502.           disassembles N instructions before instruction number INSN.

  6503. 

  6504.      'record instruction-history'

  6505.           Disassembles ten more instructions after the last disassembly.

  6506. 

  6507.      'record instruction-history -'

  6508.           Disassembles ten more instructions before the last

  6509.           disassembly.

  6510. 

  6511.      'record instruction-history BEGIN, END'

  6512.           Disassembles instructions beginning with instruction number

  6513.           BEGIN until instruction number END.  The instruction number

  6514.           END is included.

  6515. 

  6516.      This command may not be available for all recording methods.

  6517. 

  6518. 'set record instruction-history-size SIZE'

  6519. 'set record instruction-history-size unlimited'

  6520.      Define how many instructions to disassemble in the 'record

  6521.      instruction-history' command.  The default value is 10.  A SIZE of

  6522.      'unlimited' means unlimited instructions.

  6523. 

  6524. 'show record instruction-history-size'

  6525.      Show how many instructions to disassemble in the 'record

  6526.      instruction-history' command.

  6527. 

  6528. 'record function-call-history'

  6529.      Prints the execution history at function granularity.  It prints

  6530.      one line for each sequence of instructions that belong to the same

  6531.      function giving the name of that function, the source lines for

  6532.      this instruction sequence (if the '/l' modifier is specified), and

  6533.      the instructions numbers that form the sequence (if the '/i'

  6534.      modifier is specified).  The function names are indented to reflect

  6535.      the call stack depth if the '/c' modifier is specified.  The '/l',

  6536.      '/i', and '/c' modifiers can be given together.

  6537. 

  6538.           (gdb) list 1, 10

  6539.           1   void foo (void)

  6540.           2   {

  6541.           3   }

  6542.           4

  6543.           5   void bar (void)

  6544.           6   {

  6545.           7     ...

  6546.           8     foo ();

  6547.           9     ...

  6548.           10  }

  6549.           (gdb) record function-call-history /ilc

  6550.           1  bar     inst 1,4     at foo.c:6,8

  6551.           2    foo   inst 5,10    at foo.c:2,3

  6552.           3  bar     inst 11,13   at foo.c:9,10

  6553. 

  6554.      By default, ten lines are printed.  This can be changed using the

  6555.      'set record function-call-history-size' command.  Functions are

  6556.      printed in execution order.  There are several ways to specify what

  6557.      to print:

  6558. 

  6559.      'record function-call-history FUNC'

  6560.           Prints ten functions starting from function number FUNC.

  6561. 

  6562.      'record function-call-history FUNC, +/-N'

  6563.           Prints N functions around function number FUNC.  If N is

  6564.           preceded with '+', prints N functions after function number

  6565.           FUNC.  If N is preceded with '-', prints N functions before

  6566.           function number FUNC.

  6567. 

  6568.      'record function-call-history'

  6569.           Prints ten more functions after the last ten-line print.

  6570. 

  6571.      'record function-call-history -'

  6572.           Prints ten more functions before the last ten-line print.

  6573. 

  6574.      'record function-call-history BEGIN, END'

  6575.           Prints functions beginning with function number BEGIN until

  6576.           function number END.  The function number END is included.

  6577. 

  6578.      This command may not be available for all recording methods.

  6579. 

  6580. 'set record function-call-history-size SIZE'

  6581. 'set record function-call-history-size unlimited'

  6582.      Define how many lines to print in the 'record

  6583.      function-call-history' command.  The default value is 10.  A size

  6584.      of 'unlimited' means unlimited lines.

  6585. 

  6586. 'show record function-call-history-size'

  6587.      Show how many lines to print in the 'record function-call-history'

  6588.      command.

  6589. 

  6590. 

  6591. File: gdb.info,  Node: Stack,  Next: Source,  Prev: Process Record and Replay,  Up: Top

  6592. 

  6593. 8 Examining the Stack

  6594. *********************

  6595. 

  6596. When your program has stopped, the first thing you need to know is where

  6597. it stopped and how it got there.

  6598. 

  6599.    Each time your program performs a function call, information about

  6600. the call is generated.  That information includes the location of the

  6601. call in your program, the arguments of the call, and the local variables

  6602. of the function being called.  The information is saved in a block of

  6603. data called a "stack frame".  The stack frames are allocated in a region

  6604. of memory called the "call stack".

  6605. 

  6606.    When your program stops, the GDB commands for examining the stack

  6607. allow you to see all of this information.

  6608. 

  6609.    One of the stack frames is "selected" by GDB and many GDB commands

  6610. refer implicitly to the selected frame.  In particular, whenever you ask

  6611. GDB for the value of a variable in your program, the value is found in

  6612. the selected frame.  There are special GDB commands to select whichever

  6613. frame you are interested in.  *Note Selecting a Frame: Selection.

  6614. 

  6615.    When your program stops, GDB automatically selects the currently

  6616. executing frame and describes it briefly, similar to the 'frame' command

  6617. (*note Information about a Frame: Frame Info.).

  6618. 

  6619. * Menu:

  6620. 

  6621. * Frames::                      Stack frames

  6622. * Backtrace::                   Backtraces

  6623. * Selection::                   Selecting a frame

  6624. * Frame Info::                  Information on a frame

  6625. * Frame Apply::                 Applying a command to several frames

  6626. * Frame Filter Management::     Managing frame filters

  6627. 

  6628. 

  6629. File: gdb.info,  Node: Frames,  Next: Backtrace,  Up: Stack

  6630. 

  6631. 8.1 Stack Frames

  6632. ================

  6633. 

  6634. The call stack is divided up into contiguous pieces called "stack

  6635. frames", or "frames" for short; each frame is the data associated with

  6636. one call to one function.  The frame contains the arguments given to the

  6637. function, the function's local variables, and the address at which the

  6638. function is executing.

  6639. 

  6640.    When your program is started, the stack has only one frame, that of

  6641. the function 'main'.  This is called the "initial" frame or the

  6642. "outermost" frame.  Each time a function is called, a new frame is made.

  6643. Each time a function returns, the frame for that function invocation is

  6644. eliminated.  If a function is recursive, there can be many frames for

  6645. the same function.  The frame for the function in which execution is

  6646. actually occurring is called the "innermost" frame.  This is the most

  6647. recently created of all the stack frames that still exist.

  6648. 

  6649.    Inside your program, stack frames are identified by their addresses.

  6650. A stack frame consists of many bytes, each of which has its own address;

  6651. each kind of computer has a convention for choosing one byte whose

  6652. address serves as the address of the frame.  Usually this address is

  6653. kept in a register called the "frame pointer register" (*note $fp:

  6654. Registers.) while execution is going on in that frame.

  6655. 

  6656.    GDB labels each existing stack frame with a "level", a number that is

  6657. zero for the innermost frame, one for the frame that called it, and so

  6658. on upward.  These level numbers give you a way of designating stack

  6659. frames in GDB commands.  The terms "frame number" and "frame level" can

  6660. be used interchangeably to describe this number.

  6661. 

  6662.    Some compilers provide a way to compile functions so that they

  6663. operate without stack frames.  (For example, the GCC option

  6664.      '-fomit-frame-pointer'

  6665.    generates functions without a frame.)  This is occasionally done with

  6666. heavily used library functions to save the frame setup time.  GDB has

  6667. limited facilities for dealing with these function invocations.  If the

  6668. innermost function invocation has no stack frame, GDB nevertheless

  6669. regards it as though it had a separate frame, which is numbered zero as

  6670. usual, allowing correct tracing of the function call chain.  However,

  6671. GDB has no provision for frameless functions elsewhere in the stack.

  6672. 

  6673. 

  6674. File: gdb.info,  Node: Backtrace,  Next: Selection,  Prev: Frames,  Up: Stack

  6675. 

  6676. 8.2 Backtraces

  6677. ==============

  6678. 

  6679. A backtrace is a summary of how your program got where it is.  It shows

  6680. one line per frame, for many frames, starting with the currently

  6681. executing frame (frame zero), followed by its caller (frame one), and on

  6682. up the stack.

  6683. 

  6684.    To print a backtrace of the entire stack, use the 'backtrace'

  6685. command, or its alias 'bt'.  This command will print one line per frame

  6686. for frames in the stack.  By default, all stack frames are printed.  You

  6687. can stop the backtrace at any time by typing the system interrupt

  6688. character, normally 'Ctrl-c'.

  6689. 

  6690. 'backtrace [OPTION]... [QUALIFIER]... [COUNT]'

  6691. 'bt [OPTION]... [QUALIFIER]... [COUNT]'

  6692.      Print the backtrace of the entire stack.

  6693. 

  6694.      The optional COUNT can be one of the following:

  6695. 

  6696.      'N'

  6697.      'N'

  6698.           Print only the innermost N frames, where N is a positive

  6699.           number.

  6700. 

  6701.      '-N'

  6702.      '-N'

  6703.           Print only the outermost N frames, where N is a positive

  6704.           number.

  6705. 

  6706.      Options:

  6707. 

  6708.      '-full'

  6709.           Print the values of the local variables also.  This can be

  6710.           combined with the optional COUNT to limit the number of frames

  6711.           shown.

  6712. 

  6713.      '-no-filters'

  6714.           Do not run Python frame filters on this backtrace.  *Note

  6715.           Frame Filter API::, for more information.  Additionally use

  6716.           *note disable frame-filter all:: to turn off all frame

  6717.           filters.  This is only relevant when GDB has been configured

  6718.           with 'Python' support.

  6719. 

  6720.      '-hide'

  6721.           A Python frame filter might decide to "elide" some frames.

  6722.           Normally such elided frames are still printed, but they are

  6723.           indented relative to the filtered frames that cause them to be

  6724.           elided.  The '-hide' option causes elided frames to not be

  6725.           printed at all.

  6726. 

  6727.      The 'backtrace' command also supports a number of options that

  6728.      allow overriding relevant global print settings as set by 'set

  6729.      backtrace' and 'set print' subcommands:

  6730. 

  6731.      '-past-main [on|off]'

  6732.           Set whether backtraces should continue past 'main'.  Related

  6733.           setting: *note set backtrace past-main::.

  6734. 

  6735.      '-past-entry [on|off]'

  6736.           Set whether backtraces should continue past the entry point of

  6737.           a program.  Related setting: *note set backtrace past-entry::.

  6738. 

  6739.      '-entry-values no|only|preferred|if-needed|both|compact|default'

  6740.           Set printing of function arguments at function entry.  Related

  6741.           setting: *note set print entry-values::.

  6742. 

  6743.      '-frame-arguments all|scalars|none'

  6744.           Set printing of non-scalar frame arguments.  Related setting:

  6745.           *note set print frame-arguments::.

  6746. 

  6747.      '-raw-frame-arguments [on|off]'

  6748.           Set whether to print frame arguments in raw form.  Related

  6749.           setting: *note set print raw-frame-arguments::.

  6750. 

  6751.      '-frame-info auto|source-line|location|source-and-location|location-and-address|short-location'

  6752.           Set printing of frame information.  Related setting: *note set

  6753.           print frame-info::.

  6754. 

  6755.      The optional QUALIFIER is maintained for backward compatibility.

  6756.      It can be one of the following:

  6757. 

  6758.      'full'

  6759.           Equivalent to the '-full' option.

  6760. 

  6761.      'no-filters'

  6762.           Equivalent to the '-no-filters' option.

  6763. 

  6764.      'hide'

  6765.           Equivalent to the '-hide' option.

  6766. 

  6767.    The names 'where' and 'info stack' (abbreviated 'info s') are

  6768. additional aliases for 'backtrace'.

  6769. 

  6770.    In a multi-threaded program, GDB by default shows the backtrace only

  6771. for the current thread.  To display the backtrace for several or all of

  6772. the threads, use the command 'thread apply' (*note thread apply:

  6773. Threads.).  For example, if you type 'thread apply all backtrace', GDB

  6774. will display the backtrace for all the threads; this is handy when you

  6775. debug a core dump of a multi-threaded program.

  6776. 

  6777.    Each line in the backtrace shows the frame number and the function

  6778. name.  The program counter value is also shown--unless you use 'set

  6779. print address off'.  The backtrace also shows the source file name and

  6780. line number, as well as the arguments to the function.  The program

  6781. counter value is omitted if it is at the beginning of the code for that

  6782. line number.

  6783. 

  6784.    Here is an example of a backtrace.  It was made with the command 'bt

  6785. 3', so it shows the innermost three frames.

  6786. 

  6787.      #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)

  6788.          at builtin.c:993

  6789.      #1  0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242

  6790.      #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)

  6791.          at macro.c:71

  6792.      (More stack frames follow...)

  6793. 

  6794. The display for frame zero does not begin with a program counter value,

  6795. indicating that your program has stopped at the beginning of the code

  6796. for line '993' of 'builtin.c'.

  6797. 

  6798. The value of parameter 'data' in frame 1 has been replaced by '...'.  By

  6799. default, GDB prints the value of a parameter only if it is a scalar

  6800. (integer, pointer, enumeration, etc).  See command 'set print

  6801. frame-arguments' in *note Print Settings:: for more details on how to

  6802. configure the way function parameter values are printed.  The command

  6803. 'set print frame-info' (*note Print Settings::) controls what frame

  6804. information is printed.

  6805. 

  6806.    If your program was compiled with optimizations, some compilers will

  6807. optimize away arguments passed to functions if those arguments are never

  6808. used after the call.  Such optimizations generate code that passes

  6809. arguments through registers, but doesn't store those arguments in the

  6810. stack frame.  GDB has no way of displaying such arguments in stack

  6811. frames other than the innermost one.  Here's what such a backtrace might

  6812. look like:

  6813. 

  6814.      #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)

  6815.          at builtin.c:993

  6816.      #1  0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242

  6817.      #2  0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)

  6818.          at macro.c:71

  6819.      (More stack frames follow...)

  6820. 

  6821. The values of arguments that were not saved in their stack frames are

  6822. shown as '<optimized out>'.

  6823. 

  6824.    If you need to display the values of such optimized-out arguments,

  6825. either deduce that from other variables whose values depend on the one

  6826. you are interested in, or recompile without optimizations.

  6827. 

  6828.    Most programs have a standard user entry point--a place where system

  6829. libraries and startup code transition into user code.  For C this is

  6830. 'main'(1).  When GDB finds the entry function in a backtrace it will

  6831. terminate the backtrace, to avoid tracing into highly system-specific

  6832. (and generally uninteresting) code.

  6833. 

  6834.    If you need to examine the startup code, or limit the number of

  6835. levels in a backtrace, you can change this behavior:

  6836. 

  6837. 'set backtrace past-main'

  6838. 'set backtrace past-main on'

  6839.      Backtraces will continue past the user entry point.

  6840. 

  6841. 'set backtrace past-main off'

  6842.      Backtraces will stop when they encounter the user entry point.

  6843.      This is the default.

  6844. 

  6845. 'show backtrace past-main'

  6846.      Display the current user entry point backtrace policy.

  6847. 

  6848. 'set backtrace past-entry'

  6849. 'set backtrace past-entry on'

  6850.      Backtraces will continue past the internal entry point of an

  6851.      application.  This entry point is encoded by the linker when the

  6852.      application is built, and is likely before the user entry point

  6853.      'main' (or equivalent) is called.

  6854. 

  6855. 'set backtrace past-entry off'

  6856.      Backtraces will stop when they encounter the internal entry point

  6857.      of an application.  This is the default.

  6858. 

  6859. 'show backtrace past-entry'

  6860.      Display the current internal entry point backtrace policy.

  6861. 

  6862. 'set backtrace limit N'

  6863. 'set backtrace limit 0'

  6864. 'set backtrace limit unlimited'

  6865.      Limit the backtrace to N levels.  A value of 'unlimited' or zero

  6866.      means unlimited levels.

  6867. 

  6868. 'show backtrace limit'

  6869.      Display the current limit on backtrace levels.

  6870. 

  6871.    You can control how file names are displayed.

  6872. 

  6873. 'set filename-display'

  6874. 'set filename-display relative'

  6875.      Display file names relative to the compilation directory.  This is

  6876.      the default.

  6877. 

  6878. 'set filename-display basename'

  6879.      Display only basename of a filename.

  6880. 

  6881. 'set filename-display absolute'

  6882.      Display an absolute filename.

  6883. 

  6884. 'show filename-display'

  6885.      Show the current way to display filenames.

  6886. 

  6887.    ---------- Footnotes ----------

  6888. 

  6889.    (1) Note that embedded programs (the so-called "free-standing"

  6890. environment) are not required to have a 'main' function as the entry

  6891. point.  They could even have multiple entry points.

  6892. 

  6893. 

  6894. File: gdb.info,  Node: Selection,  Next: Frame Info,  Prev: Backtrace,  Up: Stack

  6895. 

  6896. 8.3 Selecting a Frame

  6897. =====================

  6898. 

  6899. Most commands for examining the stack and other data in your program

  6900. work on whichever stack frame is selected at the moment.  Here are the

  6901. commands for selecting a stack frame; all of them finish by printing a

  6902. brief description of the stack frame just selected.

  6903. 

  6904. 'frame [ FRAME-SELECTION-SPEC ]'

  6905. 'f [ FRAME-SELECTION-SPEC ]'

  6906.      The 'frame' command allows different stack frames to be selected.

  6907.      The FRAME-SELECTION-SPEC can be any of the following:

  6908. 

  6909.      'NUM'

  6910.      'level NUM'

  6911.           Select frame level NUM.  Recall that frame zero is the

  6912.           innermost (currently executing) frame, frame one is the frame

  6913.           that called the innermost one, and so on.  The highest level

  6914.           frame is usually the one for 'main'.

  6915. 

  6916.           As this is the most common method of navigating the frame

  6917.           stack, the string 'level' can be omitted.  For example, the

  6918.           following two commands are equivalent:

  6919. 

  6920.                (gdb) frame 3

  6921.                (gdb) frame level 3

  6922. 

  6923.      'address STACK-ADDRESS'

  6924.           Select the frame with stack address STACK-ADDRESS.  The

  6925.           STACK-ADDRESS for a frame can be seen in the output of 'info

  6926.           frame', for example:

  6927. 

  6928.                (gdb) info frame

  6929.                Stack level 1, frame at 0x7fffffffda30:

  6930.                 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5

  6931.                 tail call frame, caller of frame at 0x7fffffffda30

  6932.                 source language c++.

  6933.                 Arglist at unknown address.

  6934.                 Locals at unknown address, Previous frame's sp is 0x7fffffffda30

  6935. 

  6936.           The STACK-ADDRESS for this frame is '0x7fffffffda30' as

  6937.           indicated by the line:

  6938. 

  6939.                Stack level 1, frame at 0x7fffffffda30:

  6940. 

  6941.      'function FUNCTION-NAME'

  6942.           Select the stack frame for function FUNCTION-NAME.  If there

  6943.           are multiple stack frames for function FUNCTION-NAME then the

  6944.           inner most stack frame is selected.

  6945. 

  6946.      'view STACK-ADDRESS [ PC-ADDR ]'

  6947.           View a frame that is not part of GDB's backtrace.  The frame

  6948.           viewed has stack address STACK-ADDR, and optionally, a program

  6949.           counter address of PC-ADDR.

  6950. 

  6951.           This is useful mainly if the chaining of stack frames has been

  6952.           damaged by a bug, making it impossible for GDB to assign

  6953.           numbers properly to all frames.  In addition, this can be

  6954.           useful when your program has multiple stacks and switches

  6955.           between them.

  6956. 

  6957.           When viewing a frame outside the current backtrace using

  6958.           'frame view' then you can always return to the original stack

  6959.           using one of the previous stack frame selection instructions,

  6960.           for example 'frame level 0'.

  6961. 

  6962. 'up N'

  6963.      Move N frames up the stack; N defaults to 1.  For positive numbers

  6964.      N, this advances toward the outermost frame, to higher frame

  6965.      numbers, to frames that have existed longer.

  6966. 

  6967. 'down N'

  6968.      Move N frames down the stack; N defaults to 1.  For positive

  6969.      numbers N, this advances toward the innermost frame, to lower frame

  6970.      numbers, to frames that were created more recently.  You may

  6971.      abbreviate 'down' as 'do'.

  6972. 

  6973.    All of these commands end by printing two lines of output describing

  6974. the frame.  The first line shows the frame number, the function name,

  6975. the arguments, and the source file and line number of execution in that

  6976. frame.  The second line shows the text of that source line.

  6977. 

  6978.    For example:

  6979. 

  6980.      (gdb) up

  6981.      #1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)

  6982.          at env.c:10

  6983.      10              read_input_file (argv[i]);

  6984. 

  6985.    After such a printout, the 'list' command with no arguments prints

  6986. ten lines centered on the point of execution in the frame.  You can also

  6987. edit the program at the point of execution with your favorite editing

  6988. program by typing 'edit'.  *Note Printing Source Lines: List, for

  6989. details.

  6990. 

  6991. 'select-frame [ FRAME-SELECTION-SPEC ]'

  6992.      The 'select-frame' command is a variant of 'frame' that does not

  6993.      display the new frame after selecting it.  This command is intended

  6994.      primarily for use in GDB command scripts, where the output might be

  6995.      unnecessary and distracting.  The FRAME-SELECTION-SPEC is as for

  6996.      the 'frame' command described in *note Selecting a Frame:

  6997.      Selection.

  6998. 

  6999. 'up-silently N'

  7000. 'down-silently N'

  7001.      These two commands are variants of 'up' and 'down', respectively;

  7002.      they differ in that they do their work silently, without causing

  7003.      display of the new frame.  They are intended primarily for use in

  7004.      GDB command scripts, where the output might be unnecessary and

  7005.      distracting.

  7006. 

  7007. 

  7008. File: gdb.info,  Node: Frame Info,  Next: Frame Apply,  Prev: Selection,  Up: Stack

  7009. 

  7010. 8.4 Information About a Frame

  7011. =============================

  7012. 

  7013. There are several other commands to print information about the selected

  7014. stack frame.

  7015. 

  7016. 'frame'

  7017. 'f'

  7018.      When used without any argument, this command does not change which

  7019.      frame is selected, but prints a brief description of the currently

  7020.      selected stack frame.  It can be abbreviated 'f'.  With an

  7021.      argument, this command is used to select a stack frame.  *Note

  7022.      Selecting a Frame: Selection.

  7023. 

  7024. 'info frame'

  7025. 'info f'

  7026.      This command prints a verbose description of the selected stack

  7027.      frame, including:

  7028. 

  7029.         * the address of the frame

  7030.         * the address of the next frame down (called by this frame)

  7031.         * the address of the next frame up (caller of this frame)

  7032.         * the language in which the source code corresponding to this

  7033.           frame is written

  7034.         * the address of the frame's arguments

  7035.         * the address of the frame's local variables

  7036.         * the program counter saved in it (the address of execution in

  7037.           the caller frame)

  7038.         * which registers were saved in the frame

  7039. 

  7040.      The verbose description is useful when something has gone wrong

  7041.      that has made the stack format fail to fit the usual conventions.

  7042. 

  7043. 'info frame [ FRAME-SELECTION-SPEC ]'

  7044. 'info f [ FRAME-SELECTION-SPEC ]'

  7045.      Print a verbose description of the frame selected by

  7046.      FRAME-SELECTION-SPEC.  The FRAME-SELECTION-SPEC is the same as for

  7047.      the 'frame' command (*note Selecting a Frame: Selection.).  The

  7048.      selected frame remains unchanged by this command.

  7049. 

  7050. 'info args [-q]'

  7051.      Print the arguments of the selected frame, each on a separate line.

  7052. 

  7053.      The optional flag '-q', which stands for 'quiet', disables printing

  7054.      header information and messages explaining why no argument have

  7055.      been printed.

  7056. 

  7057. 'info args [-q] [-t TYPE_REGEXP] [REGEXP]'

  7058.      Like 'info args', but only print the arguments selected with the

  7059.      provided regexp(s).

  7060. 

  7061.      If REGEXP is provided, print only the arguments whose names match

  7062.      the regular expression REGEXP.

  7063. 

  7064.      If TYPE_REGEXP is provided, print only the arguments whose types,

  7065.      as printed by the 'whatis' command, match the regular expression

  7066.      TYPE_REGEXP.  If TYPE_REGEXP contains space(s), it should be

  7067.      enclosed in quote characters.  If needed, use backslash to escape

  7068.      the meaning of special characters or quotes.

  7069. 

  7070.      If both REGEXP and TYPE_REGEXP are provided, an argument is printed

  7071.      only if its name matches REGEXP and its type matches TYPE_REGEXP.

  7072. 

  7073. 'info locals [-q]'

  7074.      Print the local variables of the selected frame, each on a separate

  7075.      line.  These are all variables (declared either static or

  7076.      automatic) accessible at the point of execution of the selected

  7077.      frame.

  7078. 

  7079.      The optional flag '-q', which stands for 'quiet', disables printing

  7080.      header information and messages explaining why no local variables

  7081.      have been printed.

  7082. 

  7083. 'info locals [-q] [-t TYPE_REGEXP] [REGEXP]'

  7084.      Like 'info locals', but only print the local variables selected

  7085.      with the provided regexp(s).

  7086. 

  7087.      If REGEXP is provided, print only the local variables whose names

  7088.      match the regular expression REGEXP.

  7089. 

  7090.      If TYPE_REGEXP is provided, print only the local variables whose

  7091.      types, as printed by the 'whatis' command, match the regular

  7092.      expression TYPE_REGEXP.  If TYPE_REGEXP contains space(s), it

  7093.      should be enclosed in quote characters.  If needed, use backslash

  7094.      to escape the meaning of special characters or quotes.

  7095. 

  7096.      If both REGEXP and TYPE_REGEXP are provided, a local variable is

  7097.      printed only if its name matches REGEXP and its type matches

  7098.      TYPE_REGEXP.

  7099. 

  7100.      The command 'info locals -q -t TYPE_REGEXP' can usefully be

  7101.      combined with the commands 'frame apply' and 'thread apply'.  For

  7102.      example, your program might use Resource Acquisition Is

  7103.      Initialization types (RAII) such as 'lock_something_t': each local

  7104.      variable of type 'lock_something_t' automatically places a lock

  7105.      that is destroyed when the variable goes out of scope.  You can

  7106.      then list all acquired locks in your program by doing

  7107.           thread apply all -s frame apply all -s info locals -q -t lock_something_t

  7108.      or the equivalent shorter form

  7109.           tfaas i lo -q -t lock_something_t

  7110. 

  7111. 

  7112. File: gdb.info,  Node: Frame Apply,  Next: Frame Filter Management,  Prev: Frame Info,  Up: Stack

  7113. 

  7114. 8.5 Applying a Command to Several Frames.

  7115. =========================================

  7116. 

  7117. 'frame apply [all | COUNT | -COUNT | level LEVEL...] [OPTION]... COMMAND'

  7118.      The 'frame apply' command allows you to apply the named COMMAND to

  7119.      one or more frames.

  7120. 

  7121.      'all'

  7122.           Specify 'all' to apply COMMAND to all frames.

  7123. 

  7124.      'COUNT'

  7125.           Use COUNT to apply COMMAND to the innermost COUNT frames,

  7126.           where COUNT is a positive number.

  7127. 

  7128.      '-COUNT'

  7129.           Use -COUNT to apply COMMAND to the outermost COUNT frames,

  7130.           where COUNT is a positive number.

  7131. 

  7132.      'level'

  7133.           Use 'level' to apply COMMAND to the set of frames identified

  7134.           by the LEVEL list.  LEVEL is a frame level or a range of frame

  7135.           levels as LEVEL1-LEVEL2.  The frame level is the number shown

  7136.           in the first field of the 'backtrace' command output.  E.g.,

  7137.           '2-4 6-8 3' indicates to apply COMMAND for the frames at

  7138.           levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3.

  7139. 

  7140.      Note that the frames on which 'frame apply' applies a command are

  7141.      also influenced by the 'set backtrace' settings such as 'set

  7142.      backtrace past-main' and 'set backtrace limit N'.  *Note

  7143.      Backtraces: Backtrace.

  7144. 

  7145.      The 'frame apply' command also supports a number of options that

  7146.      allow overriding relevant 'set backtrace' settings:

  7147. 

  7148.      '-past-main [on|off]'

  7149.           Whether backtraces should continue past 'main'.  Related

  7150.           setting: *note set backtrace past-main::.

  7151. 

  7152.      '-past-entry [on|off]'

  7153.           Whether backtraces should continue past the entry point of a

  7154.           program.  Related setting: *note set backtrace past-entry::.

  7155. 

  7156.      By default, GDB displays some frame information before the output

  7157.      produced by COMMAND, and an error raised during the execution of a

  7158.      COMMAND will abort 'frame apply'.  The following options can be

  7159.      used to fine-tune these behaviors:

  7160. 

  7161.      '-c'

  7162.           The flag '-c', which stands for 'continue', causes any errors

  7163.           in COMMAND to be displayed, and the execution of 'frame apply'

  7164.           then continues.

  7165.      '-s'

  7166.           The flag '-s', which stands for 'silent', causes any errors or

  7167.           empty output produced by a COMMAND to be silently ignored.

  7168.           That is, the execution continues, but the frame information

  7169.           and errors are not printed.

  7170.      '-q'

  7171.           The flag '-q' ('quiet') disables printing the frame

  7172.           information.

  7173. 

  7174.      The following example shows how the flags '-c' and '-s' are working

  7175.      when applying the command 'p j' to all frames, where variable 'j'

  7176.      can only be successfully printed in the outermost '#1 main' frame.

  7177. 

  7178.           (gdb) frame apply all p j

  7179.           #0  some_function (i=5) at fun.c:4

  7180.           No symbol "j" in current context.

  7181.           (gdb) frame apply all -c p j

  7182.           #0  some_function (i=5) at fun.c:4

  7183.           No symbol "j" in current context.

  7184.           #1  0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11

  7185.           $1 = 5

  7186.           (gdb) frame apply all -s p j

  7187.           #1  0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11

  7188.           $2 = 5

  7189.           (gdb)

  7190. 

  7191.      By default, 'frame apply', prints the frame location information

  7192.      before the command output:

  7193. 

  7194.           (gdb) frame apply all p $sp

  7195.           #0  some_function (i=5) at fun.c:4

  7196.           $4 = (void *) 0xffffd1e0

  7197.           #1  0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11

  7198.           $5 = (void *) 0xffffd1f0

  7199.           (gdb)

  7200. 

  7201.      If the flag '-q' is given, no frame information is printed:

  7202.           (gdb) frame apply all -q p $sp

  7203.           $12 = (void *) 0xffffd1e0

  7204.           $13 = (void *) 0xffffd1f0

  7205.           (gdb)

  7206. 

  7207. 'faas COMMAND'

  7208.      Shortcut for 'frame apply all -s COMMAND'.  Applies COMMAND on all

  7209.      frames, ignoring errors and empty output.

  7210. 

  7211.      It can for example be used to print a local variable or a function

  7212.      argument without knowing the frame where this variable or argument

  7213.      is, using:

  7214.           (gdb) faas p some_local_var_i_do_not_remember_where_it_is

  7215. 

  7216.      The 'faas' command accepts the same options as the 'frame apply'

  7217.      command.  *Note frame apply: Frame Apply.

  7218. 

  7219.      Note that the command 'tfaas COMMAND' applies COMMAND on all frames

  7220.      of all threads.  See *Note Threads: Threads.

  7221. 

  7222. 

  7223. File: gdb.info,  Node: Frame Filter Management,  Prev: Frame Apply,  Up: Stack

  7224. 

  7225. 8.6 Management of Frame Filters.

  7226. ================================

  7227. 

  7228. Frame filters are Python based utilities to manage and decorate the

  7229. output of frames.  *Note Frame Filter API::, for further information.

  7230. 

  7231.    Managing frame filters is performed by several commands available

  7232. within GDB, detailed here.

  7233. 

  7234. 'info frame-filter'

  7235.      Print a list of installed frame filters from all dictionaries,

  7236.      showing their name, priority and enabled status.

  7237. 

  7238. 'disable frame-filter FILTER-DICTIONARY FILTER-NAME'

  7239.      Disable a frame filter in the dictionary matching FILTER-DICTIONARY

  7240.      and FILTER-NAME.  The FILTER-DICTIONARY may be 'all', 'global',

  7241.      'progspace', or the name of the object file where the frame filter

  7242.      dictionary resides.  When 'all' is specified, all frame filters

  7243.      across all dictionaries are disabled.  The FILTER-NAME is the name

  7244.      of the frame filter and is used when 'all' is not the option for

  7245.      FILTER-DICTIONARY.  A disabled frame-filter is not deleted, it may

  7246.      be enabled again later.

  7247. 

  7248. 'enable frame-filter FILTER-DICTIONARY FILTER-NAME'

  7249.      Enable a frame filter in the dictionary matching FILTER-DICTIONARY

  7250.      and FILTER-NAME.  The FILTER-DICTIONARY may be 'all', 'global',

  7251.      'progspace' or the name of the object file where the frame filter

  7252.      dictionary resides.  When 'all' is specified, all frame filters

  7253.      across all dictionaries are enabled.  The FILTER-NAME is the name

  7254.      of the frame filter and is used when 'all' is not the option for

  7255.      FILTER-DICTIONARY.

  7256. 

  7257.      Example:

  7258. 

  7259.           (gdb) info frame-filter

  7260. 

  7261.           global frame-filters:

  7262.             Priority  Enabled  Name

  7263.             1000      No       PrimaryFunctionFilter

  7264.             100       Yes      Reverse

  7265. 

  7266.           progspace /build/test frame-filters:

  7267.             Priority  Enabled  Name

  7268.             100       Yes      ProgspaceFilter

  7269. 

  7270.           objfile /build/test frame-filters:

  7271.             Priority  Enabled  Name

  7272.             999       Yes      BuildProgramFilter

  7273. 

  7274.           (gdb) disable frame-filter /build/test BuildProgramFilter

  7275.           (gdb) info frame-filter

  7276. 

  7277.           global frame-filters:

  7278.             Priority  Enabled  Name

  7279.             1000      No       PrimaryFunctionFilter

  7280.             100       Yes      Reverse

  7281. 

  7282.           progspace /build/test frame-filters:

  7283.             Priority  Enabled  Name

  7284.             100       Yes      ProgspaceFilter

  7285. 

  7286.           objfile /build/test frame-filters:

  7287.             Priority  Enabled  Name

  7288.             999       No       BuildProgramFilter

  7289. 

  7290.           (gdb) enable frame-filter global PrimaryFunctionFilter

  7291.           (gdb) info frame-filter

  7292. 

  7293.           global frame-filters:

  7294.             Priority  Enabled  Name

  7295.             1000      Yes      PrimaryFunctionFilter

  7296.             100       Yes      Reverse

  7297. 

  7298.           progspace /build/test frame-filters:

  7299.             Priority  Enabled  Name

  7300.             100       Yes      ProgspaceFilter

  7301. 

  7302.           objfile /build/test frame-filters:

  7303.             Priority  Enabled  Name

  7304.             999       No       BuildProgramFilter

  7305. 

  7306. 'set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY'

  7307.      Set the PRIORITY of a frame filter in the dictionary matching

  7308.      FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.

  7309.      The FILTER-DICTIONARY may be 'global', 'progspace' or the name of

  7310.      the object file where the frame filter dictionary resides.  The

  7311.      PRIORITY is an integer.

  7312. 

  7313. 'show frame-filter priority FILTER-DICTIONARY FILTER-NAME'

  7314.      Show the PRIORITY of a frame filter in the dictionary matching

  7315.      FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.

  7316.      The FILTER-DICTIONARY may be 'global', 'progspace' or the name of

  7317.      the object file where the frame filter dictionary resides.

  7318. 

  7319.      Example:

  7320. 

  7321.           (gdb) info frame-filter

  7322. 

  7323.           global frame-filters:

  7324.             Priority  Enabled  Name

  7325.             1000      Yes      PrimaryFunctionFilter

  7326.             100       Yes      Reverse

  7327. 

  7328.           progspace /build/test frame-filters:

  7329.             Priority  Enabled  Name

  7330.             100       Yes      ProgspaceFilter

  7331. 

  7332.           objfile /build/test frame-filters:

  7333.             Priority  Enabled  Name

  7334.             999       No       BuildProgramFilter

  7335. 

  7336.           (gdb) set frame-filter priority global Reverse 50

  7337.           (gdb) info frame-filter

  7338. 

  7339.           global frame-filters:

  7340.             Priority  Enabled  Name

  7341.             1000      Yes      PrimaryFunctionFilter

  7342.             50        Yes      Reverse

  7343. 

  7344.           progspace /build/test frame-filters:

  7345.             Priority  Enabled  Name

  7346.             100       Yes      ProgspaceFilter

  7347. 

  7348.           objfile /build/test frame-filters:

  7349.             Priority  Enabled  Name

  7350.             999       No       BuildProgramFilter

  7351. 

  7352. 

  7353. File: gdb.info,  Node: Source,  Next: Data,  Prev: Stack,  Up: Top

  7354. 

  7355. 9 Examining Source Files

  7356. ************************

  7357. 

  7358. GDB can print parts of your program's source, since the debugging

  7359. information recorded in the program tells GDB what source files were

  7360. used to build it.  When your program stops, GDB spontaneously prints the

  7361. line where it stopped.  Likewise, when you select a stack frame (*note

  7362. Selecting a Frame: Selection.), GDB prints the line where execution in

  7363. that frame has stopped.  You can print other portions of source files by

  7364. explicit command.

  7365. 

  7366.    If you use GDB through its GNU Emacs interface, you may prefer to use

  7367. Emacs facilities to view source; see *note Using GDB under GNU Emacs:

  7368. Emacs.

  7369. 

  7370. * Menu:

  7371. 

  7372. * List::                        Printing source lines

  7373. * Specify Location::            How to specify code locations

  7374. * Edit::                        Editing source files

  7375. * Search::                      Searching source files

  7376. * Source Path::                 Specifying source directories

  7377. * Machine Code::                Source and machine code

  7378. 

  7379. 

  7380. File: gdb.info,  Node: List,  Next: Specify Location,  Up: Source

  7381. 

  7382. 9.1 Printing Source Lines

  7383. =========================

  7384. 

  7385. To print lines from a source file, use the 'list' command (abbreviated

  7386. 'l').  By default, ten lines are printed.  There are several ways to

  7387. specify what part of the file you want to print; see *note Specify

  7388. Location::, for the full list.

  7389. 

  7390.    Here are the forms of the 'list' command most commonly used:

  7391. 

  7392. 'list LINENUM'

  7393.      Print lines centered around line number LINENUM in the current

  7394.      source file.

  7395. 

  7396. 'list FUNCTION'

  7397.      Print lines centered around the beginning of function FUNCTION.

  7398. 

  7399. 'list'

  7400.      Print more lines.  If the last lines printed were printed with a

  7401.      'list' command, this prints lines following the last lines printed;

  7402.      however, if the last line printed was a solitary line printed as

  7403.      part of displaying a stack frame (*note Examining the Stack:

  7404.      Stack.), this prints lines centered around that line.

  7405. 

  7406. 'list -'

  7407.      Print lines just before the lines last printed.

  7408. 

  7409.    By default, GDB prints ten source lines with any of these forms of

  7410. the 'list' command.  You can change this using 'set listsize':

  7411. 

  7412. 'set listsize COUNT'

  7413. 'set listsize unlimited'

  7414.      Make the 'list' command display COUNT source lines (unless the

  7415.      'list' argument explicitly specifies some other number).  Setting

  7416.      COUNT to 'unlimited' or 0 means there's no limit.

  7417. 

  7418. 'show listsize'

  7419.      Display the number of lines that 'list' prints.

  7420. 

  7421.    Repeating a 'list' command with <RET> discards the argument, so it is

  7422. equivalent to typing just 'list'.  This is more useful than listing the

  7423. same lines again.  An exception is made for an argument of '-'; that

  7424. argument is preserved in repetition so that each repetition moves up in

  7425. the source file.

  7426. 

  7427.    In general, the 'list' command expects you to supply zero, one or two

  7428. "locations".  Locations specify source lines; there are several ways of

  7429. writing them (*note Specify Location::), but the effect is always to

  7430. specify some source line.

  7431. 

  7432.    Here is a complete description of the possible arguments for 'list':

  7433. 

  7434. 'list LOCATION'

  7435.      Print lines centered around the line specified by LOCATION.

  7436. 

  7437. 'list FIRST,LAST'

  7438.      Print lines from FIRST to LAST.  Both arguments are locations.

  7439.      When a 'list' command has two locations, and the source file of the

  7440.      second location is omitted, this refers to the same source file as

  7441.      the first location.

  7442. 

  7443. 'list ,LAST'

  7444.      Print lines ending with LAST.

  7445. 

  7446. 'list FIRST,'

  7447.      Print lines starting with FIRST.

  7448. 

  7449. 'list +'

  7450.      Print lines just after the lines last printed.

  7451. 

  7452. 'list -'

  7453.      Print lines just before the lines last printed.

  7454. 

  7455. 'list'

  7456.      As described in the preceding table.

  7457. 

  7458. 

  7459. File: gdb.info,  Node: Specify Location,  Next: Edit,  Prev: List,  Up: Source

  7460. 

  7461. 9.2 Specifying a Location

  7462. =========================

  7463. 

  7464. * Menu:

  7465. 

  7466. * Linespec Locations::                Linespec locations

  7467. * Explicit Locations::                Explicit locations

  7468. * Address Locations::                 Address locations

  7469. 

  7470. Several GDB commands accept arguments that specify a location of your

  7471. program's code.  Since GDB is a source-level debugger, a location

  7472. usually specifies some line in the source code.  Locations may be

  7473. specified using three different formats: linespec locations, explicit

  7474. locations, or address locations.

  7475. 

  7476. 

  7477. File: gdb.info,  Node: Linespec Locations,  Next: Explicit Locations,  Up: Specify Location

  7478. 

  7479. 9.2.1 Linespec Locations

  7480. ------------------------

  7481. 

  7482. A "linespec" is a colon-separated list of source location parameters

  7483. such as file name, function name, etc.  Here are all the different ways

  7484. of specifying a linespec:

  7485. 

  7486. 'LINENUM'

  7487.      Specifies the line number LINENUM of the current source file.

  7488. 

  7489. '-OFFSET'

  7490. '+OFFSET'

  7491.      Specifies the line OFFSET lines before or after the "current line".

  7492.      For the 'list' command, the current line is the last one printed;

  7493.      for the breakpoint commands, this is the line at which execution

  7494.      stopped in the currently selected "stack frame" (*note Frames:

  7495.      Frames, for a description of stack frames.)  When used as the

  7496.      second of the two linespecs in a 'list' command, this specifies the

  7497.      line OFFSET lines up or down from the first linespec.

  7498. 

  7499. 'FILENAME:LINENUM'

  7500.      Specifies the line LINENUM in the source file FILENAME.  If

  7501.      FILENAME is a relative file name, then it will match any source

  7502.      file name with the same trailing components.  For example, if

  7503.      FILENAME is 'gcc/expr.c', then it will match source file name of

  7504.      '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or

  7505.      '/build/trunk/gcc/x-expr.c'.

  7506. 

  7507. 'FUNCTION'

  7508.      Specifies the line that begins the body of the function FUNCTION.

  7509.      For example, in C, this is the line with the open brace.

  7510. 

  7511.      By default, in C++ and Ada, FUNCTION is interpreted as specifying

  7512.      all functions named FUNCTION in all scopes.  For C++, this means in

  7513.      all namespaces and classes.  For Ada, this means in all packages.

  7514. 

  7515.      For example, assuming a program with C++ symbols named 'A::B::func'

  7516.      and 'B::func', both commands 'break func' and 'break B::func' set a

  7517.      breakpoint on both symbols.

  7518. 

  7519.      Commands that accept a linespec let you override this with the

  7520.      '-qualified' option.  For example, 'break -qualified func' sets a

  7521.      breakpoint on a free-function named 'func' ignoring any C++ class

  7522.      methods and namespace functions called 'func'.

  7523. 

  7524.      *Note Explicit Locations::.

  7525. 

  7526. 'FUNCTION:LABEL'

  7527.      Specifies the line where LABEL appears in FUNCTION.

  7528. 

  7529. 'FILENAME:FUNCTION'

  7530.      Specifies the line that begins the body of the function FUNCTION in

  7531.      the file FILENAME.  You only need the file name with a function

  7532.      name to avoid ambiguity when there are identically named functions

  7533.      in different source files.

  7534. 

  7535. 'LABEL'

  7536.      Specifies the line at which the label named LABEL appears in the

  7537.      function corresponding to the currently selected stack frame.  If

  7538.      there is no current selected stack frame (for instance, if the

  7539.      inferior is not running), then GDB will not search for a label.

  7540. 

  7541. '-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME'

  7542.      The GNU/Linux tool 'SystemTap' provides a way for applications to

  7543.      embed static probes.  *Note Static Probe Points::, for more

  7544.      information on finding and using static probes.  This form of

  7545.      linespec specifies the location of such a static probe.

  7546. 

  7547.      If OBJFILE is given, only probes coming from that shared library or

  7548.      executable matching OBJFILE as a regular expression are considered.

  7549.      If PROVIDER is given, then only probes from that provider are

  7550.      considered.  If several probes match the spec, GDB will insert a

  7551.      breakpoint at each one of those probes.

  7552. 

  7553. 

  7554. File: gdb.info,  Node: Explicit Locations,  Next: Address Locations,  Prev: Linespec Locations,  Up: Specify Location

  7555. 

  7556. 9.2.2 Explicit Locations

  7557. ------------------------

  7558. 

  7559. "Explicit locations" allow the user to directly specify the source

  7560. location's parameters using option-value pairs.

  7561. 

  7562.    Explicit locations are useful when several functions, labels, or file

  7563. names have the same name (base name for files) in the program's sources.

  7564. In these cases, explicit locations point to the source line you meant

  7565. more accurately and unambiguously.  Also, using explicit locations might

  7566. be faster in large programs.

  7567. 

  7568.    For example, the linespec 'foo:bar' may refer to a function 'bar'

  7569. defined in the file named 'foo' or the label 'bar' in a function named

  7570. 'foo'.  GDB must search either the file system or the symbol table to

  7571. know.

  7572. 

  7573.    The list of valid explicit location options is summarized in the

  7574. following table:

  7575. 

  7576. '-source FILENAME'

  7577.      The value specifies the source file name.  To differentiate between

  7578.      files with the same base name, prepend as many directories as is

  7579.      necessary to uniquely identify the desired file, e.g.,

  7580.      'foo/bar/baz.c'.  Otherwise GDB will use the first file it finds

  7581.      with the given base name.  This option requires the use of either

  7582.      '-function' or '-line'.

  7583. 

  7584. '-function FUNCTION'

  7585.      The value specifies the name of a function.  Operations on function

  7586.      locations unmodified by other options (such as '-label' or '-line')

  7587.      refer to the line that begins the body of the function.  In C, for

  7588.      example, this is the line with the open brace.

  7589. 

  7590.      By default, in C++ and Ada, FUNCTION is interpreted as specifying

  7591.      all functions named FUNCTION in all scopes.  For C++, this means in

  7592.      all namespaces and classes.  For Ada, this means in all packages.

  7593. 

  7594.      For example, assuming a program with C++ symbols named 'A::B::func'

  7595.      and 'B::func', both commands 'break -function func' and

  7596.      'break -function B::func' set a breakpoint on both symbols.

  7597. 

  7598.      You can use the '-qualified' flag to override this (see below).

  7599. 

  7600. '-qualified'

  7601. 

  7602.      This flag makes GDB interpret a function name specified with

  7603.      '-function' as a complete fully-qualified name.

  7604. 

  7605.      For example, assuming a C++ program with symbols named 'A::B::func'

  7606.      and 'B::func', the 'break -qualified -function B::func' command

  7607.      sets a breakpoint on 'B::func', only.

  7608. 

  7609.      (Note: the '-qualified' option can precede a linespec as well

  7610.      (*note Linespec Locations::), so the particular example above could

  7611.      be simplified as 'break -qualified B::func'.)

  7612. 

  7613. '-label LABEL'

  7614.      The value specifies the name of a label.  When the function name is

  7615.      not specified, the label is searched in the function of the

  7616.      currently selected stack frame.

  7617. 

  7618. '-line NUMBER'

  7619.      The value specifies a line offset for the location.  The offset may

  7620.      either be absolute ('-line 3') or relative ('-line +3'), depending

  7621.      on the command.  When specified without any other options, the line

  7622.      offset is relative to the current line.

  7623. 

  7624.    Explicit location options may be abbreviated by omitting any

  7625. non-unique trailing characters from the option name, e.g.,

  7626. 'break -s main.c -li 3'.

  7627. 

  7628. 

  7629. File: gdb.info,  Node: Address Locations,  Prev: Explicit Locations,  Up: Specify Location

  7630. 

  7631. 9.2.3 Address Locations

  7632. -----------------------

  7633. 

  7634. "Address locations" indicate a specific program address.  They have the

  7635. generalized form *ADDRESS.

  7636. 

  7637.    For line-oriented commands, such as 'list' and 'edit', this specifies

  7638. a source line that contains ADDRESS.  For 'break' and other

  7639. breakpoint-oriented commands, this can be used to set breakpoints in

  7640. parts of your program which do not have debugging information or source

  7641. files.

  7642. 

  7643.    Here ADDRESS may be any expression valid in the current working

  7644. language (*note working language: Languages.) that specifies a code

  7645. address.  In addition, as a convenience, GDB extends the semantics of

  7646. expressions used in locations to cover several situations that

  7647. frequently occur during debugging.  Here are the various forms of

  7648. ADDRESS:

  7649. 

  7650. 'EXPRESSION'

  7651.      Any expression valid in the current working language.

  7652. 

  7653. 'FUNCADDR'

  7654.      An address of a function or procedure derived from its name.  In C,

  7655.      C++, Objective-C, Fortran, minimal, and assembly, this is simply

  7656.      the function's name FUNCTION (and actually a special case of a

  7657.      valid expression).  In Pascal and Modula-2, this is '&FUNCTION'.

  7658.      In Ada, this is 'FUNCTION'Address' (although the Pascal form also

  7659.      works).

  7660. 

  7661.      This form specifies the address of the function's first

  7662.      instruction, before the stack frame and arguments have been set up.

  7663. 

  7664. ''FILENAME':FUNCADDR'

  7665.      Like FUNCADDR above, but also specifies the name of the source file

  7666.      explicitly.  This is useful if the name of the function does not

  7667.      specify the function unambiguously, e.g., if there are several

  7668.      functions with identical names in different source files.

  7669. 

  7670. 

  7671. File: gdb.info,  Node: Edit,  Next: Search,  Prev: Specify Location,  Up: Source

  7672. 

  7673. 9.3 Editing Source Files

  7674. ========================

  7675. 

  7676. To edit the lines in a source file, use the 'edit' command.  The editing

  7677. program of your choice is invoked with the current line set to the

  7678. active line in the program.  Alternatively, there are several ways to

  7679. specify what part of the file you want to print if you want to see other

  7680. parts of the program:

  7681. 

  7682. 'edit LOCATION'

  7683.      Edit the source file specified by 'location'.  Editing starts at

  7684.      that LOCATION, e.g., at the specified source line of the specified

  7685.      file.  *Note Specify Location::, for all the possible forms of the

  7686.      LOCATION argument; here are the forms of the 'edit' command most

  7687.      commonly used:

  7688. 

  7689.      'edit NUMBER'

  7690.           Edit the current source file with NUMBER as the active line

  7691.           number.

  7692. 

  7693.      'edit FUNCTION'

  7694.           Edit the file containing FUNCTION at the beginning of its

  7695.           definition.

  7696. 

  7697. 9.3.1 Choosing your Editor

  7698. --------------------------

  7699. 

  7700. You can customize GDB to use any editor you want (1).  By default, it is

  7701. '/bin/ex', but you can change this by setting the environment variable

  7702. 'EDITOR' before using GDB.  For example, to configure GDB to use the

  7703. 'vi' editor, you could use these commands with the 'sh' shell:

  7704.      EDITOR=/usr/bin/vi

  7705.      export EDITOR

  7706.      gdb ...

  7707.    or in the 'csh' shell,

  7708.      setenv EDITOR /usr/bin/vi

  7709.      gdb ...

  7710. 

  7711.    ---------- Footnotes ----------

  7712. 

  7713.    (1) The only restriction is that your editor (say 'ex'), recognizes

  7714. the following command-line syntax:

  7715.      ex +NUMBER file

  7716.    The optional numeric value +NUMBER specifies the number of the line

  7717. in the file where to start editing.

  7718. 

  7719. 

  7720. File: gdb.info,  Node: Search,  Next: Source Path,  Prev: Edit,  Up: Source

  7721. 

  7722. 9.4 Searching Source Files

  7723. ==========================

  7724. 

  7725. There are two commands for searching through the current source file for

  7726. a regular expression.

  7727. 

  7728. 'forward-search REGEXP'

  7729. 'search REGEXP'

  7730.      The command 'forward-search REGEXP' checks each line, starting with

  7731.      the one following the last line listed, for a match for REGEXP.  It

  7732.      lists the line that is found.  You can use the synonym 'search

  7733.      REGEXP' or abbreviate the command name as 'fo'.

  7734. 

  7735. 'reverse-search REGEXP'

  7736.      The command 'reverse-search REGEXP' checks each line, starting with

  7737.      the one before the last line listed and going backward, for a match

  7738.      for REGEXP.  It lists the line that is found.  You can abbreviate

  7739.      this command as 'rev'.

  7740. 

  7741. 

  7742. File: gdb.info,  Node: Source Path,  Next: Machine Code,  Prev: Search,  Up: Source

  7743. 

  7744. 9.5 Specifying Source Directories

  7745. =================================

  7746. 

  7747. Executable programs sometimes do not record the directories of the

  7748. source files from which they were compiled, just the names.  Even when

  7749. they do, the directories could be moved between the compilation and your

  7750. debugging session.  GDB has a list of directories to search for source

  7751. files; this is called the "source path".  Each time GDB wants a source

  7752. file, it tries all the directories in the list, in the order they are

  7753. present in the list, until it finds a file with the desired name.

  7754. 

  7755.    For example, suppose an executable references the file

  7756. '/usr/src/foo-1.0/lib/foo.c', does not record a compilation directory,

  7757. and the "source path" is '/mnt/cross'.  GDB would look for the source

  7758. file in the following locations:

  7759. 

  7760.   1. '/usr/src/foo-1.0/lib/foo.c'

  7761.   2. '/mnt/cross/usr/src/foo-1.0/lib/foo.c'

  7762.   3. '/mnt/cross/foo.c'

  7763. 

  7764.    If the source file is not present at any of the above locations then

  7765. an error is printed.  GDB does not look up the parts of the source file

  7766. name, such as '/mnt/cross/src/foo-1.0/lib/foo.c'.  Likewise, the

  7767. subdirectories of the source path are not searched: if the source path

  7768. is '/mnt/cross', and the binary refers to 'foo.c', GDB would not find it

  7769. under '/mnt/cross/usr/src/foo-1.0/lib'.

  7770. 

  7771.    Plain file names, relative file names with leading directories, file

  7772. names containing dots, etc. are all treated as described above, except

  7773. that non-absolute file names are not looked up literally.  If the

  7774. "source path" is '/mnt/cross', the source file is recorded as

  7775. '../lib/foo.c', and no compilation directory is recorded, then GDB will

  7776. search in the following locations:

  7777. 

  7778.   1. '/mnt/cross/../lib/foo.c'

  7779.   2. '/mnt/cross/foo.c'

  7780. 

  7781.    The "source path" will always include two special entries '$cdir' and

  7782. '$cwd', these refer to the compilation directory (if one is recorded)

  7783. and the current working directory respectively.

  7784. 

  7785.    '$cdir' causes GDB to search within the compilation directory, if one

  7786. is recorded in the debug information.  If no compilation directory is

  7787. recorded in the debug information then '$cdir' is ignored.

  7788. 

  7789.    '$cwd' is not the same as '.'--the former tracks the current working

  7790. directory as it changes during your GDB session, while the latter is

  7791. immediately expanded to the current directory at the time you add an

  7792. entry to the source path.

  7793. 

  7794.    If a compilation directory is recorded in the debug information, and

  7795. GDB has not found the source file after the first search using "source

  7796. path", then GDB will combine the compilation directory and the filename,

  7797. and then search for the source file again using the "source path".

  7798. 

  7799.    For example, if the executable records the source file as

  7800. '/usr/src/foo-1.0/lib/foo.c', the compilation directory is recorded as

  7801. '/project/build', and the "source path" is '/mnt/cross:$cdir:$cwd' while

  7802. the current working directory of the GDB session is '/home/user', then

  7803. GDB will search for the source file in the following locations:

  7804. 

  7805.   1. '/usr/src/foo-1.0/lib/foo.c'

  7806.   2. '/mnt/cross/usr/src/foo-1.0/lib/foo.c'

  7807.   3. '/project/build/usr/src/foo-1.0/lib/foo.c'

  7808.   4. '/home/user/usr/src/foo-1.0/lib/foo.c'

  7809.   5. '/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c'

  7810.   6. '/project/build/project/build/usr/src/foo-1.0/lib/foo.c'

  7811.   7. '/home/user/project/build/usr/src/foo-1.0/lib/foo.c'

  7812.   8. '/mnt/cross/foo.c'

  7813.   9. '/project/build/foo.c'

  7814.   10. '/home/user/foo.c'

  7815. 

  7816.    If the file name in the previous example had been recorded in the

  7817. executable as a relative path rather than an absolute path, then the

  7818. first look up would not have occurred, but all of the remaining steps

  7819. would be similar.

  7820. 

  7821.    When searching for source files on MS-DOS and MS-Windows, where

  7822. absolute paths start with a drive letter (e.g.  'C:/project/foo.c'), GDB

  7823. will remove the drive letter from the file name before appending it to a

  7824. search directory from "source path"; for instance if the executable

  7825. references the source file 'C:/project/foo.c' and "source path" is set

  7826. to 'D:/mnt/cross', then GDB will search in the following locations for

  7827. the source file:

  7828. 

  7829.   1. 'C:/project/foo.c'

  7830.   2. 'D:/mnt/cross/project/foo.c'

  7831.   3. 'D:/mnt/cross/foo.c'

  7832. 

  7833.    Note that the executable search path is _not_ used to locate the

  7834. source files.

  7835. 

  7836.    Whenever you reset or rearrange the source path, GDB clears out any

  7837. information it has cached about where source files are found and where

  7838. each line is in the file.

  7839. 

  7840.    When you start GDB, its source path includes only '$cdir' and '$cwd',

  7841. in that order.  To add other directories, use the 'directory' command.

  7842. 

  7843.    The search path is used to find both program source files and GDB

  7844. script files (read using the '-command' option and 'source' command).

  7845. 

  7846.    In addition to the source path, GDB provides a set of commands that

  7847. manage a list of source path substitution rules.  A "substitution rule"

  7848. specifies how to rewrite source directories stored in the program's

  7849. debug information in case the sources were moved to a different

  7850. directory between compilation and debugging.  A rule is made of two

  7851. strings, the first specifying what needs to be rewritten in the path,

  7852. and the second specifying how it should be rewritten.  In *note set

  7853. substitute-path::, we name these two parts FROM and TO respectively.

  7854. GDB does a simple string replacement of FROM with TO at the start of the

  7855. directory part of the source file name, and uses that result instead of

  7856. the original file name to look up the sources.

  7857. 

  7858.    Using the previous example, suppose the 'foo-1.0' tree has been moved

  7859. from '/usr/src' to '/mnt/cross', then you can tell GDB to replace

  7860. '/usr/src' in all source path names with '/mnt/cross'.  The first lookup

  7861. will then be '/mnt/cross/foo-1.0/lib/foo.c' in place of the original

  7862. location of '/usr/src/foo-1.0/lib/foo.c'.  To define a source path

  7863. substitution rule, use the 'set substitute-path' command (*note set

  7864. substitute-path::).

  7865. 

  7866.    To avoid unexpected substitution results, a rule is applied only if

  7867. the FROM part of the directory name ends at a directory separator.  For

  7868. instance, a rule substituting '/usr/source' into '/mnt/cross' will be

  7869. applied to '/usr/source/foo-1.0' but not to '/usr/sourceware/foo-2.0'.

  7870. And because the substitution is applied only at the beginning of the

  7871. directory name, this rule will not be applied to

  7872. '/root/usr/source/baz.c' either.

  7873. 

  7874.    In many cases, you can achieve the same result using the 'directory'

  7875. command.  However, 'set substitute-path' can be more efficient in the

  7876. case where the sources are organized in a complex tree with multiple

  7877. subdirectories.  With the 'directory' command, you need to add each

  7878. subdirectory of your project.  If you moved the entire tree while

  7879. preserving its internal organization, then 'set substitute-path' allows

  7880. you to direct the debugger to all the sources with one single command.

  7881. 

  7882.    'set substitute-path' is also more than just a shortcut command.  The

  7883. source path is only used if the file at the original location no longer

  7884. exists.  On the other hand, 'set substitute-path' modifies the debugger

  7885. behavior to look at the rewritten location instead.  So, if for any

  7886. reason a source file that is not relevant to your executable is located

  7887. at the original location, a substitution rule is the only method

  7888. available to point GDB at the new location.

  7889. 

  7890.    You can configure a default source path substitution rule by

  7891. configuring GDB with the '--with-relocated-sources=DIR' option.  The DIR

  7892. should be the name of a directory under GDB's configured prefix (set

  7893. with '--prefix' or '--exec-prefix'), and directory names in debug

  7894. information under DIR will be adjusted automatically if the installed

  7895. GDB is moved to a new location.  This is useful if GDB, libraries or

  7896. executables with debug information and corresponding source code are

  7897. being moved together.

  7898. 

  7899. 'directory DIRNAME ...'

  7900. 'dir DIRNAME ...'

  7901.      Add directory DIRNAME to the front of the source path.  Several

  7902.      directory names may be given to this command, separated by ':' (';'

  7903.      on MS-DOS and MS-Windows, where ':' usually appears as part of

  7904.      absolute file names) or whitespace.  You may specify a directory

  7905.      that is already in the source path; this moves it forward, so GDB

  7906.      searches it sooner.

  7907. 

  7908.      The special strings '$cdir' (to refer to the compilation directory,

  7909.      if one is recorded), and '$cwd' (to refer to the current working

  7910.      directory) can also be included in the list of directories DIRNAME.

  7911.      Though these will already be in the source path they will be moved

  7912.      forward in the list so GDB searches them sooner.

  7913. 

  7914. 'directory'

  7915.      Reset the source path to its default value ('$cdir:$cwd' on Unix

  7916.      systems).  This requires confirmation.

  7917. 

  7918. 'set directories PATH-LIST'

  7919.      Set the source path to PATH-LIST.  '$cdir:$cwd' are added if

  7920.      missing.

  7921. 

  7922. 'show directories'

  7923.      Print the source path: show which directories it contains.

  7924. 

  7925. 'set substitute-path FROM TO'

  7926.      Define a source path substitution rule, and add it at the end of

  7927.      the current list of existing substitution rules.  If a rule with

  7928.      the same FROM was already defined, then the old rule is also

  7929.      deleted.

  7930. 

  7931.      For example, if the file '/foo/bar/baz.c' was moved to

  7932.      '/mnt/cross/baz.c', then the command

  7933. 

  7934.           (gdb) set substitute-path /foo/bar /mnt/cross

  7935. 

  7936.      will tell GDB to replace '/foo/bar' with '/mnt/cross', which will

  7937.      allow GDB to find the file 'baz.c' even though it was moved.

  7938. 

  7939.      In the case when more than one substitution rule have been defined,

  7940.      the rules are evaluated one by one in the order where they have

  7941.      been defined.  The first one matching, if any, is selected to

  7942.      perform the substitution.

  7943. 

  7944.      For instance, if we had entered the following commands:

  7945. 

  7946.           (gdb) set substitute-path /usr/src/include /mnt/include

  7947.           (gdb) set substitute-path /usr/src /mnt/src

  7948. 

  7949.      GDB would then rewrite '/usr/src/include/defs.h' into

  7950.      '/mnt/include/defs.h' by using the first rule.  However, it would

  7951.      use the second rule to rewrite '/usr/src/lib/foo.c' into

  7952.      '/mnt/src/lib/foo.c'.

  7953. 

  7954. 'unset substitute-path [path]'

  7955.      If a path is specified, search the current list of substitution

  7956.      rules for a rule that would rewrite that path.  Delete that rule if

  7957.      found.  A warning is emitted by the debugger if no rule could be

  7958.      found.

  7959. 

  7960.      If no path is specified, then all substitution rules are deleted.

  7961. 

  7962. 'show substitute-path [path]'

  7963.      If a path is specified, then print the source path substitution

  7964.      rule which would rewrite that path, if any.

  7965. 

  7966.      If no path is specified, then print all existing source path

  7967.      substitution rules.

  7968. 

  7969.    If your source path is cluttered with directories that are no longer

  7970. of interest, GDB may sometimes cause confusion by finding the wrong

  7971. versions of source.  You can correct the situation as follows:

  7972. 

  7973.   1. Use 'directory' with no argument to reset the source path to its

  7974.      default value.

  7975. 

  7976.   2. Use 'directory' with suitable arguments to reinstall the

  7977.      directories you want in the source path.  You can add all the

  7978.      directories in one command.

  7979. 

  7980. 

  7981. File: gdb.info,  Node: Machine Code,  Prev: Source Path,  Up: Source

  7982. 

  7983. 9.6 Source and Machine Code

  7984. ===========================

  7985. 

  7986. You can use the command 'info line' to map source lines to program

  7987. addresses (and vice versa), and the command 'disassemble' to display a

  7988. range of addresses as machine instructions.  You can use the command

  7989. 'set disassemble-next-line' to set whether to disassemble next source

  7990. line when execution stops.  When run under GNU Emacs mode, the 'info

  7991. line' command causes the arrow to point to the line specified.  Also,

  7992. 'info line' prints addresses in symbolic form as well as hex.

  7993. 

  7994. 'info line'

  7995. 'info line LOCATION'

  7996.      Print the starting and ending addresses of the compiled code for

  7997.      source line LOCATION.  You can specify source lines in any of the

  7998.      ways documented in *note Specify Location::.  With no LOCATION

  7999.      information about the current source line is printed.

  8000. 

  8001.    For example, we can use 'info line' to discover the location of the

  8002. object code for the first line of function 'm4_changequote':

  8003. 

  8004.      (gdb) info line m4_changequote

  8005.      Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \

  8006.              ends at 0x6350 <m4_changequote+4>.

  8007. 

  8008. We can also inquire (using '*ADDR' as the form for LOCATION) what source

  8009. line covers a particular address:

  8010.      (gdb) info line *0x63ff

  8011.      Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \

  8012.              ends at 0x6404 <m4_changequote+184>.

  8013. 

  8014.    After 'info line', the default address for the 'x' command is changed

  8015. to the starting address of the line, so that 'x/i' is sufficient to

  8016. begin examining the machine code (*note Examining Memory: Memory.).

  8017. Also, this address is saved as the value of the convenience variable

  8018. '$_' (*note Convenience Variables: Convenience Vars.).

  8019. 

  8020.    After 'info line', using 'info line' again without specifying a

  8021. location will display information about the next source line.

  8022. 

  8023. 'disassemble'

  8024. 'disassemble /m'

  8025. 'disassemble /s'

  8026. 'disassemble /r'

  8027.      This specialized command dumps a range of memory as machine

  8028.      instructions.  It can also print mixed source+disassembly by

  8029.      specifying the '/m' or '/s' modifier and print the raw instructions

  8030.      in hex as well as in symbolic form by specifying the '/r' modifier.

  8031.      The default memory range is the function surrounding the program

  8032.      counter of the selected frame.  A single argument to this command

  8033.      is a program counter value; GDB dumps the function surrounding this

  8034.      value.  When two arguments are given, they should be separated by a

  8035.      comma, possibly surrounded by whitespace.  The arguments specify a

  8036.      range of addresses to dump, in one of two forms:

  8037. 

  8038.      'START,END'

  8039.           the addresses from START (inclusive) to END (exclusive)

  8040.      'START,+LENGTH'

  8041.           the addresses from START (inclusive) to 'START+LENGTH'

  8042.           (exclusive).

  8043. 

  8044.      When 2 arguments are specified, the name of the function is also

  8045.      printed (since there could be several functions in the given

  8046.      range).

  8047. 

  8048.      The argument(s) can be any expression yielding a numeric value,

  8049.      such as '0x32c4', '&main+10' or '$pc - 8'.

  8050. 

  8051.      If the range of memory being disassembled contains current program

  8052.      counter, the instruction at that location is shown with a '=>'

  8053.      marker.

  8054. 

  8055.    The following example shows the disassembly of a range of addresses

  8056. of HP PA-RISC 2.0 code:

  8057. 

  8058.      (gdb) disas 0x32c4, 0x32e4

  8059.      Dump of assembler code from 0x32c4 to 0x32e4:

  8060.         0x32c4 <main+204>:      addil 0,dp

  8061.         0x32c8 <main+208>:      ldw 0x22c(sr0,r1),r26

  8062.         0x32cc <main+212>:      ldil 0x3000,r31

  8063.         0x32d0 <main+216>:      ble 0x3f8(sr4,r31)

  8064.         0x32d4 <main+220>:      ldo 0(r31),rp

  8065.         0x32d8 <main+224>:      addil -0x800,dp

  8066.         0x32dc <main+228>:      ldo 0x588(r1),r26

  8067.         0x32e0 <main+232>:      ldil 0x3000,r31

  8068.      End of assembler dump.

  8069. 

  8070.    Here is an example showing mixed source+assembly for Intel x86 with

  8071. '/m' or '/s', when the program is stopped just after function prologue

  8072. in a non-optimized function with no inline code.

  8073. 

  8074.      (gdb) disas /m main

  8075.      Dump of assembler code for function main:

  8076.      5       {

  8077.         0x08048330 <+0>:    push   %ebp

  8078.         0x08048331 <+1>:    mov    %esp,%ebp

  8079.         0x08048333 <+3>:    sub    $0x8,%esp

  8080.         0x08048336 <+6>:    and    $0xfffffff0,%esp

  8081.         0x08048339 <+9>:    sub    $0x10,%esp

  8082. 

  8083.      6         printf ("Hello.\n");

  8084.      => 0x0804833c <+12>:   movl   $0x8048440,(%esp)

  8085.         0x08048343 <+19>:   call   0x8048284 <puts@plt>

  8086. 

  8087.      7         return 0;

  8088.      8       }

  8089.         0x08048348 <+24>:   mov    $0x0,%eax

  8090.         0x0804834d <+29>:   leave

  8091.         0x0804834e <+30>:   ret

  8092. 

  8093.      End of assembler dump.

  8094. 

  8095.    The '/m' option is deprecated as its output is not useful when there

  8096. is either inlined code or re-ordered code.  The '/s' option is the

  8097. preferred choice.  Here is an example for AMD x86-64 showing the

  8098. difference between '/m' output and '/s' output.  This example has one

  8099. inline function defined in a header file, and the code is compiled with

  8100. '-O2' optimization.  Note how the '/m' output is missing the disassembly

  8101. of several instructions that are present in the '/s' output.

  8102. 

  8103.    'foo.h':

  8104. 

  8105.      int

  8106.      foo (int a)

  8107.      {

  8108.        if (a < 0)

  8109.          return a * 2;

  8110.        if (a == 0)

  8111.          return 1;

  8112.        return a + 10;

  8113.      }

  8114. 

  8115.    'foo.c':

  8116. 

  8117.      #include "foo.h"

  8118.      volatile int x, y;

  8119.      int

  8120.      main ()

  8121.      {

  8122.        x = foo (y);

  8123.        return 0;

  8124.      }

  8125. 

  8126.      (gdb) disas /m main

  8127.      Dump of assembler code for function main:

  8128.      5	{

  8129. 

  8130.      6	  x = foo (y);

  8131.         0x0000000000400400 <+0>:	mov    0x200c2e(%rip),%eax # 0x601034 <y>

  8132.         0x0000000000400417 <+23>:	mov    %eax,0x200c13(%rip) # 0x601030 <x>

  8133. 

  8134.      7	  return 0;

  8135.      8	}

  8136.         0x000000000040041d <+29>:	xor    %eax,%eax

  8137.         0x000000000040041f <+31>:	retq

  8138.         0x0000000000400420 <+32>:	add    %eax,%eax

  8139.         0x0000000000400422 <+34>:	jmp    0x400417 <main+23>

  8140. 

  8141.      End of assembler dump.

  8142.      (gdb) disas /s main

  8143.      Dump of assembler code for function main:

  8144.      foo.c:

  8145.      5	{

  8146.      6	  x = foo (y);

  8147.         0x0000000000400400 <+0>:	mov    0x200c2e(%rip),%eax # 0x601034 <y>

  8148. 

  8149.      foo.h:

  8150.      4	  if (a < 0)

  8151.         0x0000000000400406 <+6>:	test   %eax,%eax

  8152.         0x0000000000400408 <+8>:	js     0x400420 <main+32>

  8153. 

  8154.      6	  if (a == 0)

  8155.      7	    return 1;

  8156.      8	  return a + 10;

  8157.         0x000000000040040a <+10>:	lea    0xa(%rax),%edx

  8158.         0x000000000040040d <+13>:	test   %eax,%eax

  8159.         0x000000000040040f <+15>:	mov    $0x1,%eax

  8160.         0x0000000000400414 <+20>:	cmovne %edx,%eax

  8161. 

  8162.      foo.c:

  8163.      6	  x = foo (y);

  8164.         0x0000000000400417 <+23>:	mov    %eax,0x200c13(%rip) # 0x601030 <x>

  8165. 

  8166.      7	  return 0;

  8167.      8	}

  8168.         0x000000000040041d <+29>:	xor    %eax,%eax

  8169.         0x000000000040041f <+31>:	retq

  8170. 

  8171.      foo.h:

  8172.      5	    return a * 2;

  8173.         0x0000000000400420 <+32>:	add    %eax,%eax

  8174.         0x0000000000400422 <+34>:	jmp    0x400417 <main+23>

  8175.      End of assembler dump.

  8176. 

  8177.    Here is another example showing raw instructions in hex for AMD

  8178. x86-64,

  8179. 

  8180.      (gdb) disas /r 0x400281,+10

  8181.      Dump of assembler code from 0x400281 to 0x40028b:

  8182.         0x0000000000400281:  38 36  cmp    %dh,(%rsi)

  8183.         0x0000000000400283:  2d 36 34 2e 73 sub    $0x732e3436,%eax

  8184.         0x0000000000400288:  6f     outsl  %ds:(%rsi),(%dx)

  8185.         0x0000000000400289:  2e 32 00       xor    %cs:(%rax),%al

  8186.      End of assembler dump.

  8187. 

  8188.    Addresses cannot be specified as a location (*note Specify

  8189. Location::).  So, for example, if you want to disassemble function 'bar'

  8190. in file 'foo.c', you must type 'disassemble 'foo.c'::bar' and not

  8191. 'disassemble foo.c:bar'.

  8192. 

  8193.    Some architectures have more than one commonly-used set of

  8194. instruction mnemonics or other syntax.

  8195. 

  8196.    For programs that were dynamically linked and use shared libraries,

  8197. instructions that call functions or branch to locations in the shared

  8198. libraries might show a seemingly bogus location--it's actually a

  8199. location of the relocation table.  On some architectures, GDB might be

  8200. able to resolve these to actual function names.

  8201. 

  8202. 'set disassembler-options OPTION1[,OPTION2...]'

  8203.      This command controls the passing of target specific information to

  8204.      the disassembler.  For a list of valid options, please refer to the

  8205.      '-M'/'--disassembler-options' section of the 'objdump' manual

  8206.      and/or the output of 'objdump --help' (*note objdump:

  8207.      (binutils)objdump.).  The default value is the empty string.

  8208. 

  8209.      If it is necessary to specify more than one disassembler option,

  8210.      then multiple options can be placed together into a comma separated

  8211.      list.  Currently this command is only supported on targets ARM,

  8212.      MIPS, PowerPC and S/390.

  8213. 

  8214. 'show disassembler-options'

  8215.      Show the current setting of the disassembler options.

  8216. 

  8217. 'set disassembly-flavor INSTRUCTION-SET'

  8218.      Select the instruction set to use when disassembling the program

  8219.      via the 'disassemble' or 'x/i' commands.

  8220. 

  8221.      Currently this command is only defined for the Intel x86 family.

  8222.      You can set INSTRUCTION-SET to either 'intel' or 'att'.  The

  8223.      default is 'att', the AT&T flavor used by default by Unix

  8224.      assemblers for x86-based targets.

  8225. 

  8226. 'show disassembly-flavor'

  8227.      Show the current setting of the disassembly flavor.

  8228. 

  8229. 'set disassemble-next-line'

  8230. 'show disassemble-next-line'

  8231.      Control whether or not GDB will disassemble the next source line or

  8232.      instruction when execution stops.  If ON, GDB will display

  8233.      disassembly of the next source line when execution of the program

  8234.      being debugged stops.  This is _in addition_ to displaying the

  8235.      source line itself, which GDB always does if possible.  If the next

  8236.      source line cannot be displayed for some reason (e.g., if GDB

  8237.      cannot find the source file, or there's no line info in the debug

  8238.      info), GDB will display disassembly of the next _instruction_

  8239.      instead of showing the next source line.  If AUTO, GDB will display

  8240.      disassembly of next instruction only if the source line cannot be

  8241.      displayed.  This setting causes GDB to display some feedback when

  8242.      you step through a function with no line info or whose source file

  8243.      is unavailable.  The default is OFF, which means never display the

  8244.      disassembly of the next line or instruction.

  8245. 

  8246. 

  8247. File: gdb.info,  Node: Data,  Next: Optimized Code,  Prev: Source,  Up: Top

  8248. 

  8249. 10 Examining Data

  8250. *****************

  8251. 

  8252. The usual way to examine data in your program is with the 'print'

  8253. command (abbreviated 'p'), or its synonym 'inspect'.  It evaluates and

  8254. prints the value of an expression of the language your program is

  8255. written in (*note Using GDB with Different Languages: Languages.).  It

  8256. may also print the expression using a Python-based pretty-printer (*note

  8257. Pretty Printing::).

  8258. 

  8259. 'print [[OPTIONS] --] EXPR'

  8260. 'print [[OPTIONS] --] /F EXPR'

  8261.      EXPR is an expression (in the source language).  By default the

  8262.      value of EXPR is printed in a format appropriate to its data type;

  8263.      you can choose a different format by specifying '/F', where F is a

  8264.      letter specifying the format; see *note Output Formats: Output

  8265.      Formats.

  8266. 

  8267.      The 'print' command supports a number of options that allow

  8268.      overriding relevant global print settings as set by 'set print'

  8269.      subcommands:

  8270. 

  8271.      '-address [on|off]'

  8272.           Set printing of addresses.  Related setting: *note set print

  8273.           address::.

  8274. 

  8275.      '-array [on|off]'

  8276.           Pretty formatting of arrays.  Related setting: *note set print

  8277.           array::.

  8278. 

  8279.      '-array-indexes [on|off]'

  8280.           Set printing of array indexes.  Related setting: *note set

  8281.           print array-indexes::.

  8282. 

  8283.      '-elements NUMBER-OF-ELEMENTS|unlimited'

  8284.           Set limit on string chars or array elements to print.  The

  8285.           value 'unlimited' causes there to be no limit.  Related

  8286.           setting: *note set print elements::.

  8287. 

  8288.      '-max-depth DEPTH|unlimited'

  8289.           Set the threshold after which nested structures are replaced

  8290.           with ellipsis.  Related setting: *note set print max-depth::.

  8291. 

  8292.      '-null-stop [on|off]'

  8293.           Set printing of char arrays to stop at first null char.

  8294.           Related setting: *note set print null-stop::.

  8295. 

  8296.      '-object [on|off]'

  8297.           Set printing C++ virtual function tables.  Related setting:

  8298.           *note set print object::.

  8299. 

  8300.      '-pretty [on|off]'

  8301.           Set pretty formatting of structures.  Related setting: *note

  8302.           set print pretty::.

  8303. 

  8304.      '-raw-values [on|off]'

  8305.           Set whether to print values in raw form, bypassing any

  8306.           pretty-printers for that value.  Related setting: *note set

  8307.           print raw-values::.

  8308. 

  8309.      '-repeats NUMBER-OF-REPEATS|unlimited'

  8310.           Set threshold for repeated print elements.  'unlimited' causes

  8311.           all elements to be individually printed.  Related setting:

  8312.           *note set print repeats::.

  8313. 

  8314.      '-static-members [on|off]'

  8315.           Set printing C++ static members.  Related setting: *note set

  8316.           print static-members::.

  8317. 

  8318.      '-symbol [on|off]'

  8319.           Set printing of symbol names when printing pointers.  Related

  8320.           setting: *note set print symbol::.

  8321. 

  8322.      '-union [on|off]'

  8323.           Set printing of unions interior to structures.  Related

  8324.           setting: *note set print union::.

  8325. 

  8326.      '-vtbl [on|off]'

  8327.           Set printing of C++ virtual function tables.  Related setting:

  8328.           *note set print vtbl::.

  8329. 

  8330.      Because the 'print' command accepts arbitrary expressions which may

  8331.      look like options (including abbreviations), if you specify any

  8332.      command option, then you must use a double dash ('--') to mark the

  8333.      end of option processing.

  8334. 

  8335.      For example, this prints the value of the '-p' expression:

  8336. 

  8337.           (gdb) print -p

  8338. 

  8339.      While this repeats the last value in the value history (see below)

  8340.      with the '-pretty' option in effect:

  8341. 

  8342.           (gdb) print -p --

  8343. 

  8344.      Here is an example including both on option and an expression:

  8345. 

  8346.           (gdb) print -pretty -- *myptr

  8347.           $1 = {

  8348.             next = 0x0,

  8349.             flags = {

  8350.               sweet = 1,

  8351.               sour = 1

  8352.             },

  8353.             meat = 0x54 "Pork"

  8354.           }

  8355. 

  8356. 'print [OPTIONS]'

  8357. 'print [OPTIONS] /F'

  8358.      If you omit EXPR, GDB displays the last value again (from the

  8359.      "value history"; *note Value History: Value History.).  This allows

  8360.      you to conveniently inspect the same value in an alternative

  8361.      format.

  8362. 

  8363.    A more low-level way of examining data is with the 'x' command.  It

  8364. examines data in memory at a specified address and prints it in a

  8365. specified format.  *Note Examining Memory: Memory.

  8366. 

  8367.    If you are interested in information about types, or about how the

  8368. fields of a struct or a class are declared, use the 'ptype EXP' command

  8369. rather than 'print'.  *Note Examining the Symbol Table: Symbols.

  8370. 

  8371.    Another way of examining values of expressions and type information

  8372. is through the Python extension command 'explore' (available only if the

  8373. GDB build is configured with '--with-python').  It offers an interactive

  8374. way to start at the highest level (or, the most abstract level) of the

  8375. data type of an expression (or, the data type itself) and explore all

  8376. the way down to leaf scalar values/fields embedded in the higher level

  8377. data types.

  8378. 

  8379. 'explore ARG'

  8380.      ARG is either an expression (in the source language), or a type

  8381.      visible in the current context of the program being debugged.

  8382. 

  8383.    The working of the 'explore' command can be illustrated with an

  8384. example.  If a data type 'struct ComplexStruct' is defined in your C

  8385. program as

  8386. 

  8387.      struct SimpleStruct

  8388.      {

  8389.        int i;

  8390.        double d;

  8391.      };

  8392. 

  8393.      struct ComplexStruct

  8394.      {

  8395.        struct SimpleStruct *ss_p;

  8396.        int arr[10];

  8397.      };

  8398. 

  8399. followed by variable declarations as

  8400. 

  8401.      struct SimpleStruct ss = { 10, 1.11 };

  8402.      struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } };

  8403. 

  8404. then, the value of the variable 'cs' can be explored using the 'explore'

  8405. command as follows.

  8406. 

  8407.      (gdb) explore cs

  8408.      The value of `cs' is a struct/class of type `struct ComplexStruct' with

  8409.      the following fields:

  8410. 

  8411.        ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>

  8412.         arr = <Enter 1 to explore this field of type `int [10]'>

  8413. 

  8414.      Enter the field number of choice:

  8415. 

  8416. Since the fields of 'cs' are not scalar values, you are being prompted

  8417. to chose the field you want to explore.  Let's say you choose the field

  8418. 'ss_p' by entering '0'.  Then, since this field is a pointer, you will

  8419. be asked if it is pointing to a single value.  From the declaration of

  8420. 'cs' above, it is indeed pointing to a single value, hence you enter

  8421. 'y'.  If you enter 'n', then you will be asked if it were pointing to an

  8422. array of values, in which case this field will be explored as if it were

  8423. an array.

  8424. 

  8425.      `cs.ss_p' is a pointer to a value of type `struct SimpleStruct'

  8426.      Continue exploring it as a pointer to a single value [y/n]: y

  8427.      The value of `*(cs.ss_p)' is a struct/class of type `struct

  8428.      SimpleStruct' with the following fields:

  8429. 

  8430.        i = 10 .. (Value of type `int')

  8431.        d = 1.1100000000000001 .. (Value of type `double')

  8432. 

  8433.      Press enter to return to parent value:

  8434. 

  8435. If the field 'arr' of 'cs' was chosen for exploration by entering '1'

  8436. earlier, then since it is as array, you will be prompted to enter the

  8437. index of the element in the array that you want to explore.

  8438. 

  8439.      `cs.arr' is an array of `int'.

  8440.      Enter the index of the element you want to explore in `cs.arr': 5

  8441. 

  8442.      `(cs.arr)[5]' is a scalar value of type `int'.

  8443. 

  8444.      (cs.arr)[5] = 4

  8445. 

  8446.      Press enter to return to parent value:

  8447. 

  8448.    In general, at any stage of exploration, you can go deeper towards

  8449. the leaf values by responding to the prompts appropriately, or hit the

  8450. return key to return to the enclosing data structure (the higher level

  8451. data structure).

  8452. 

  8453.    Similar to exploring values, you can use the 'explore' command to

  8454. explore types.  Instead of specifying a value (which is typically a

  8455. variable name or an expression valid in the current context of the

  8456. program being debugged), you specify a type name.  If you consider the

  8457. same example as above, your can explore the type 'struct ComplexStruct'

  8458. by passing the argument 'struct ComplexStruct' to the 'explore' command.

  8459. 

  8460.      (gdb) explore struct ComplexStruct

  8461. 

  8462. By responding to the prompts appropriately in the subsequent interactive

  8463. session, you can explore the type 'struct ComplexStruct' in a manner

  8464. similar to how the value 'cs' was explored in the above example.

  8465. 

  8466.    The 'explore' command also has two sub-commands, 'explore value' and

  8467. 'explore type'.  The former sub-command is a way to explicitly specify

  8468. that value exploration of the argument is being invoked, while the

  8469. latter is a way to explicitly specify that type exploration of the

  8470. argument is being invoked.

  8471. 

  8472. 'explore value EXPR'

  8473.      This sub-command of 'explore' explores the value of the expression

  8474.      EXPR (if EXPR is an expression valid in the current context of the

  8475.      program being debugged).  The behavior of this command is identical

  8476.      to that of the behavior of the 'explore' command being passed the

  8477.      argument EXPR.

  8478. 

  8479. 'explore type ARG'

  8480.      This sub-command of 'explore' explores the type of ARG (if ARG is a

  8481.      type visible in the current context of program being debugged), or

  8482.      the type of the value/expression ARG (if ARG is an expression valid

  8483.      in the current context of the program being debugged).  If ARG is a

  8484.      type, then the behavior of this command is identical to that of the

  8485.      'explore' command being passed the argument ARG.  If ARG is an

  8486.      expression, then the behavior of this command will be identical to

  8487.      that of the 'explore' command being passed the type of ARG as the

  8488.      argument.

  8489. 

  8490. * Menu:

  8491. 

  8492. * Expressions::                 Expressions

  8493. * Ambiguous Expressions::       Ambiguous Expressions

  8494. * Variables::                   Program variables

  8495. * Arrays::                      Artificial arrays

  8496. * Output Formats::              Output formats

  8497. * Memory::                      Examining memory

  8498. * Auto Display::                Automatic display

  8499. * Print Settings::              Print settings

  8500. * Pretty Printing::             Python pretty printing

  8501. * Value History::               Value history

  8502. * Convenience Vars::            Convenience variables

  8503. * Convenience Funs::            Convenience functions

  8504. * Registers::                   Registers

  8505. * Floating Point Hardware::     Floating point hardware

  8506. * Vector Unit::                 Vector Unit

  8507. * OS Information::              Auxiliary data provided by operating system

  8508. * Memory Region Attributes::    Memory region attributes

  8509. * Dump/Restore Files::          Copy between memory and a file

  8510. * Core File Generation::        Cause a program dump its core

  8511. * Character Sets::              Debugging programs that use a different

  8512.                                 character set than GDB does

  8513. * Caching Target Data::         Data caching for targets

  8514. * Searching Memory::            Searching memory for a sequence of bytes

  8515. * Value Sizes::                 Managing memory allocated for values

  8516. 

  8517. 

  8518. File: gdb.info,  Node: Expressions,  Next: Ambiguous Expressions,  Up: Data

  8519. 

  8520. 10.1 Expressions

  8521. ================

  8522. 

  8523. 'print' and many other GDB commands accept an expression and compute its

  8524. value.  Any kind of constant, variable or operator defined by the

  8525. programming language you are using is valid in an expression in GDB.

  8526. This includes conditional expressions, function calls, casts, and string

  8527. constants.  It also includes preprocessor macros, if you compiled your

  8528. program to include this information; see *note Compilation::.

  8529. 

  8530.    GDB supports array constants in expressions input by the user.  The

  8531. syntax is {ELEMENT, ELEMENT...}.  For example, you can use the command

  8532. 'print {1, 2, 3}' to create an array of three integers.  If you pass an

  8533. array to a function or assign it to a program variable, GDB copies the

  8534. array to memory that is 'malloc'ed in the target program.

  8535. 

  8536.    Because C is so widespread, most of the expressions shown in examples

  8537. in this manual are in C. *Note Using GDB with Different Languages:

  8538. Languages, for information on how to use expressions in other languages.

  8539. 

  8540.    In this section, we discuss operators that you can use in GDB

  8541. expressions regardless of your programming language.

  8542. 

  8543.    Casts are supported in all languages, not just in C, because it is so

  8544. useful to cast a number into a pointer in order to examine a structure

  8545. at that address in memory.

  8546. 

  8547.    GDB supports these operators, in addition to those common to

  8548. programming languages:

  8549. 

  8550. '@'

  8551.      '@' is a binary operator for treating parts of memory as arrays.

  8552.      *Note Artificial Arrays: Arrays, for more information.

  8553. 

  8554. '::'

  8555.      '::' allows you to specify a variable in terms of the file or

  8556.      function where it is defined.  *Note Program Variables: Variables.

  8557. 

  8558. '{TYPE} ADDR'

  8559.      Refers to an object of type TYPE stored at address ADDR in memory.

  8560.      The address ADDR may be any expression whose value is an integer or

  8561.      pointer (but parentheses are required around binary operators, just

  8562.      as in a cast).  This construct is allowed regardless of what kind

  8563.      of data is normally supposed to reside at ADDR.

  8564. 

  8565. 

  8566. File: gdb.info,  Node: Ambiguous Expressions,  Next: Variables,  Prev: Expressions,  Up: Data

  8567. 

  8568. 10.2 Ambiguous Expressions

  8569. ==========================

  8570. 

  8571. Expressions can sometimes contain some ambiguous elements.  For

  8572. instance, some programming languages (notably Ada, C++ and Objective-C)

  8573. permit a single function name to be defined several times, for

  8574. application in different contexts.  This is called "overloading".

  8575. Another example involving Ada is generics.  A "generic package" is

  8576. similar to C++ templates and is typically instantiated several times,

  8577. resulting in the same function name being defined in different contexts.

  8578. 

  8579.    In some cases and depending on the language, it is possible to adjust

  8580. the expression to remove the ambiguity.  For instance in C++, you can

  8581. specify the signature of the function you want to break on, as in 'break

  8582. FUNCTION(TYPES)'.  In Ada, using the fully qualified name of your

  8583. function often makes the expression unambiguous as well.

  8584. 

  8585.    When an ambiguity that needs to be resolved is detected, the debugger

  8586. has the capability to display a menu of numbered choices for each

  8587. possibility, and then waits for the selection with the prompt '>'.  The

  8588. first option is always '[0] cancel', and typing '0 <RET>' aborts the

  8589. current command.  If the command in which the expression was used allows

  8590. more than one choice to be selected, the next option in the menu is '[1]

  8591. all', and typing '1 <RET>' selects all possible choices.

  8592. 

  8593.    For example, the following session excerpt shows an attempt to set a

  8594. breakpoint at the overloaded symbol 'String::after'.  We choose three

  8595. particular definitions of that function name:

  8596. 

  8597.      (gdb) b String::after

  8598.      [0] cancel

  8599.      [1] all

  8600.      [2] file:String.cc; line number:867

  8601.      [3] file:String.cc; line number:860

  8602.      [4] file:String.cc; line number:875

  8603.      [5] file:String.cc; line number:853

  8604.      [6] file:String.cc; line number:846

  8605.      [7] file:String.cc; line number:735

  8606.      > 2 4 6

  8607.      Breakpoint 1 at 0xb26c: file String.cc, line 867.

  8608.      Breakpoint 2 at 0xb344: file String.cc, line 875.

  8609.      Breakpoint 3 at 0xafcc: file String.cc, line 846.

  8610.      Multiple breakpoints were set.

  8611.      Use the "delete" command to delete unwanted

  8612.       breakpoints.

  8613.      (gdb)

  8614. 

  8615. 'set multiple-symbols MODE'

  8616. 

  8617.      This option allows you to adjust the debugger behavior when an

  8618.      expression is ambiguous.

  8619. 

  8620.      By default, MODE is set to 'all'.  If the command with which the

  8621.      expression is used allows more than one choice, then GDB

  8622.      automatically selects all possible choices.  For instance,

  8623.      inserting a breakpoint on a function using an ambiguous name

  8624.      results in a breakpoint inserted on each possible match.  However,

  8625.      if a unique choice must be made, then GDB uses the menu to help you

  8626.      disambiguate the expression.  For instance, printing the address of

  8627.      an overloaded function will result in the use of the menu.

  8628. 

  8629.      When MODE is set to 'ask', the debugger always uses the menu when

  8630.      an ambiguity is detected.

  8631. 

  8632.      Finally, when MODE is set to 'cancel', the debugger reports an

  8633.      error due to the ambiguity and the command is aborted.

  8634. 

  8635. 'show multiple-symbols'

  8636.      Show the current value of the 'multiple-symbols' setting.

  8637. 

  8638. 

  8639. File: gdb.info,  Node: Variables,  Next: Arrays,  Prev: Ambiguous Expressions,  Up: Data

  8640. 

  8641. 10.3 Program Variables

  8642. ======================

  8643. 

  8644. The most common kind of expression to use is the name of a variable in

  8645. your program.

  8646. 

  8647.    Variables in expressions are understood in the selected stack frame

  8648. (*note Selecting a Frame: Selection.); they must be either:

  8649. 

  8650.    * global (or file-static)

  8651. 

  8652. or

  8653. 

  8654.    * visible according to the scope rules of the programming language

  8655.      from the point of execution in that frame

  8656. 

  8657. This means that in the function

  8658. 

  8659.      foo (a)

  8660.           int a;

  8661.      {

  8662.        bar (a);

  8663.        {

  8664.          int b = test ();

  8665.          bar (b);

  8666.        }

  8667.      }

  8668. 

  8669. you can examine and use the variable 'a' whenever your program is

  8670. executing within the function 'foo', but you can only use or examine the

  8671. variable 'b' while your program is executing inside the block where 'b'

  8672. is declared.

  8673. 

  8674.    There is an exception: you can refer to a variable or function whose

  8675. scope is a single source file even if the current execution point is not

  8676. in this file.  But it is possible to have more than one such variable or

  8677. function with the same name (in different source files).  If that

  8678. happens, referring to that name has unpredictable effects.  If you wish,

  8679. you can specify a static variable in a particular function or file by

  8680. using the colon-colon ('::') notation:

  8681. 

  8682.      FILE::VARIABLE

  8683.      FUNCTION::VARIABLE

  8684. 

  8685. Here FILE or FUNCTION is the name of the context for the static

  8686. VARIABLE.  In the case of file names, you can use quotes to make sure

  8687. GDB parses the file name as a single word--for example, to print a

  8688. global value of 'x' defined in 'f2.c':

  8689. 

  8690.      (gdb) p 'f2.c'::x

  8691. 

  8692.    The '::' notation is normally used for referring to static variables,

  8693. since you typically disambiguate uses of local variables in functions by

  8694. selecting the appropriate frame and using the simple name of the

  8695. variable.  However, you may also use this notation to refer to local

  8696. variables in frames enclosing the selected frame:

  8697. 

  8698.      void

  8699.      foo (int a)

  8700.      {

  8701.        if (a < 10)

  8702.          bar (a);

  8703.        else

  8704.          process (a);    /* Stop here */

  8705.      }

  8706. 

  8707.      int

  8708.      bar (int a)

  8709.      {

  8710.        foo (a + 5);

  8711.      }

  8712. 

  8713. For example, if there is a breakpoint at the commented line, here is

  8714. what you might see when the program stops after executing the call

  8715. 'bar(0)':

  8716. 

  8717.      (gdb) p a

  8718.      $1 = 10

  8719.      (gdb) p bar::a

  8720.      $2 = 5

  8721.      (gdb) up 2

  8722.      #2  0x080483d0 in foo (a=5) at foobar.c:12

  8723.      (gdb) p a

  8724.      $3 = 5

  8725.      (gdb) p bar::a

  8726.      $4 = 0

  8727. 

  8728.    These uses of '::' are very rarely in conflict with the very similar

  8729. use of the same notation in C++.  When they are in conflict, the C++

  8730. meaning takes precedence; however, this can be overridden by quoting the

  8731. file or function name with single quotes.

  8732. 

  8733.    For example, suppose the program is stopped in a method of a class

  8734. that has a field named 'includefile', and there is also an include file

  8735. named 'includefile' that defines a variable, 'some_global'.

  8736. 

  8737.      (gdb) p includefile

  8738.      $1 = 23

  8739.      (gdb) p includefile::some_global

  8740.      A syntax error in expression, near `'.

  8741.      (gdb) p 'includefile'::some_global

  8742.      $2 = 27

  8743. 

  8744.      _Warning:_ Occasionally, a local variable may appear to have the

  8745.      wrong value at certain points in a function--just after entry to a

  8746.      new scope, and just before exit.

  8747.    You may see this problem when you are stepping by machine

  8748. instructions.  This is because, on most machines, it takes more than one

  8749. instruction to set up a stack frame (including local variable

  8750. definitions); if you are stepping by machine instructions, variables may

  8751. appear to have the wrong values until the stack frame is completely

  8752. built.  On exit, it usually also takes more than one machine instruction

  8753. to destroy a stack frame; after you begin stepping through that group of

  8754. instructions, local variable definitions may be gone.

  8755. 

  8756.    This may also happen when the compiler does significant

  8757. optimizations.  To be sure of always seeing accurate values, turn off

  8758. all optimization when compiling.

  8759. 

  8760.    Another possible effect of compiler optimizations is to optimize

  8761. unused variables out of existence, or assign variables to registers (as

  8762. opposed to memory addresses).  Depending on the support for such cases

  8763. offered by the debug info format used by the compiler, GDB might not be

  8764. able to display values for such local variables.  If that happens, GDB

  8765. will print a message like this:

  8766. 

  8767.      No symbol "foo" in current context.

  8768. 

  8769.    To solve such problems, either recompile without optimizations, or

  8770. use a different debug info format, if the compiler supports several such

  8771. formats.  *Note Compilation::, for more information on choosing compiler

  8772. options.  *Note C and C++: C, for more information about debug info

  8773. formats that are best suited to C++ programs.

  8774. 

  8775.    If you ask to print an object whose contents are unknown to GDB,

  8776. e.g., because its data type is not completely specified by the debug

  8777. information, GDB will say '<incomplete type>'.  *Note incomplete type:

  8778. Symbols, for more about this.

  8779. 

  8780.    If you try to examine or use the value of a (global) variable for

  8781. which GDB has no type information, e.g., because the program includes no

  8782. debug information, GDB displays an error message.  *Note unknown type:

  8783. Symbols, for more about unknown types.  If you cast the variable to its

  8784. declared type, GDB gets the variable's value using the cast-to type as

  8785. the variable's type.  For example, in a C program:

  8786. 

  8787.        (gdb) p var

  8788.        'var' has unknown type; cast it to its declared type

  8789.        (gdb) p (float) var

  8790.        $1 = 3.14

  8791. 

  8792.    If you append '@entry' string to a function parameter name you get

  8793. its value at the time the function got called.  If the value is not

  8794. available an error message is printed.  Entry values are available only

  8795. with some compilers.  Entry values are normally also printed at the

  8796. function parameter list according to *note set print entry-values::.

  8797. 

  8798.      Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29

  8799.      29	  i++;

  8800.      (gdb) next

  8801.      30	  e (i);

  8802.      (gdb) print i

  8803.      $1 = 31

  8804.      (gdb) print i@entry

  8805.      $2 = 30

  8806. 

  8807.    Strings are identified as arrays of 'char' values without specified

  8808. signedness.  Arrays of either 'signed char' or 'unsigned char' get

  8809. printed as arrays of 1 byte sized integers.  '-fsigned-char' or

  8810. '-funsigned-char' GCC options have no effect as GDB defines literal

  8811. string type '"char"' as 'char' without a sign.  For program code

  8812. 

  8813.      char var0[] = "A";

  8814.      signed char var1[] = "A";

  8815. 

  8816.    You get during debugging

  8817.      (gdb) print var0

  8818.      $1 = "A"

  8819.      (gdb) print var1

  8820.      $2 = {65 'A', 0 '\0'}

  8821. 

  8822. 

  8823. File: gdb.info,  Node: Arrays,  Next: Output Formats,  Prev: Variables,  Up: Data

  8824. 

  8825. 10.4 Artificial Arrays

  8826. ======================

  8827. 

  8828. It is often useful to print out several successive objects of the same

  8829. type in memory; a section of an array, or an array of dynamically

  8830. determined size for which only a pointer exists in the program.

  8831. 

  8832.    You can do this by referring to a contiguous span of memory as an

  8833. "artificial array", using the binary operator '@'.  The left operand of

  8834. '@' should be the first element of the desired array and be an

  8835. individual object.  The right operand should be the desired length of

  8836. the array.  The result is an array value whose elements are all of the

  8837. type of the left argument.  The first element is actually the left

  8838. argument; the second element comes from bytes of memory immediately

  8839. following those that hold the first element, and so on.  Here is an

  8840. example.  If a program says

  8841. 

  8842.      int *array = (int *) malloc (len * sizeof (int));

  8843. 

  8844. you can print the contents of 'array' with

  8845. 

  8846.      p *array@len

  8847. 

  8848.    The left operand of '@' must reside in memory.  Array values made

  8849. with '@' in this way behave just like other arrays in terms of

  8850. subscripting, and are coerced to pointers when used in expressions.

  8851. Artificial arrays most often appear in expressions via the value history

  8852. (*note Value History: Value History.), after printing one out.

  8853. 

  8854.    Another way to create an artificial array is to use a cast.  This

  8855. re-interprets a value as if it were an array.  The value need not be in

  8856. memory:

  8857.      (gdb) p/x (short[2])0x12345678

  8858.      $1 = {0x1234, 0x5678}

  8859. 

  8860.    As a convenience, if you leave the array length out (as in

  8861. '(TYPE[])VALUE') GDB calculates the size to fill the value (as

  8862. 'sizeof(VALUE)/sizeof(TYPE)':

  8863.      (gdb) p/x (short[])0x12345678

  8864.      $2 = {0x1234, 0x5678}

  8865. 

  8866.    Sometimes the artificial array mechanism is not quite enough; in

  8867. moderately complex data structures, the elements of interest may not

  8868. actually be adjacent--for example, if you are interested in the values

  8869. of pointers in an array.  One useful work-around in this situation is to

  8870. use a convenience variable (*note Convenience Variables: Convenience

  8871. Vars.) as a counter in an expression that prints the first interesting

  8872. value, and then repeat that expression via <RET>.  For instance, suppose

  8873. you have an array 'dtab' of pointers to structures, and you are

  8874. interested in the values of a field 'fv' in each structure.  Here is an

  8875. example of what you might type:

  8876. 

  8877.      set $i = 0

  8878.      p dtab[$i++]->fv

  8879.      <RET>

  8880.      <RET>

  8881.      ...

  8882. 

  8883. 

  8884. File: gdb.info,  Node: Output Formats,  Next: Memory,  Prev: Arrays,  Up: Data

  8885. 

  8886. 10.5 Output Formats

  8887. ===================

  8888. 

  8889. By default, GDB prints a value according to its data type.  Sometimes

  8890. this is not what you want.  For example, you might want to print a

  8891. number in hex, or a pointer in decimal.  Or you might want to view data

  8892. in memory at a certain address as a character string or as an

  8893. instruction.  To do these things, specify an "output format" when you

  8894. print a value.

  8895. 

  8896.    The simplest use of output formats is to say how to print a value

  8897. already computed.  This is done by starting the arguments of the 'print'

  8898. command with a slash and a format letter.  The format letters supported

  8899. are:

  8900. 

  8901. 'x'

  8902.      Regard the bits of the value as an integer, and print the integer

  8903.      in hexadecimal.

  8904. 

  8905. 'd'

  8906.      Print as integer in signed decimal.

  8907. 

  8908. 'u'

  8909.      Print as integer in unsigned decimal.

  8910. 

  8911. 'o'

  8912.      Print as integer in octal.

  8913. 

  8914. 't'

  8915.      Print as integer in binary.  The letter 't' stands for "two".  (1)

  8916. 

  8917. 'a'

  8918.      Print as an address, both absolute in hexadecimal and as an offset

  8919.      from the nearest preceding symbol.  You can use this format used to

  8920.      discover where (in what function) an unknown address is located:

  8921. 

  8922.           (gdb) p/a 0x54320

  8923.           $3 = 0x54320 <_initialize_vx+396>

  8924. 

  8925.      The command 'info symbol 0x54320' yields similar results.  *Note

  8926.      info symbol: Symbols.

  8927. 

  8928. 'c'

  8929.      Regard as an integer and print it as a character constant.  This

  8930.      prints both the numerical value and its character representation.

  8931.      The character representation is replaced with the octal escape

  8932.      '\nnn' for characters outside the 7-bit ASCII range.

  8933. 

  8934.      Without this format, GDB displays 'char', 'unsigned char', and

  8935.      'signed char' data as character constants.  Single-byte members of

  8936.      vectors are displayed as integer data.

  8937. 

  8938. 'f'

  8939.      Regard the bits of the value as a floating point number and print

  8940.      using typical floating point syntax.

  8941. 

  8942. 's'

  8943.      Regard as a string, if possible.  With this format, pointers to

  8944.      single-byte data are displayed as null-terminated strings and

  8945.      arrays of single-byte data are displayed as fixed-length strings.

  8946.      Other values are displayed in their natural types.

  8947. 

  8948.      Without this format, GDB displays pointers to and arrays of 'char',

  8949.      'unsigned char', and 'signed char' as strings.  Single-byte members

  8950.      of a vector are displayed as an integer array.

  8951. 

  8952. 'z'

  8953.      Like 'x' formatting, the value is treated as an integer and printed

  8954.      as hexadecimal, but leading zeros are printed to pad the value to

  8955.      the size of the integer type.

  8956. 

  8957. 'r'

  8958.      Print using the 'raw' formatting.  By default, GDB will use a

  8959.      Python-based pretty-printer, if one is available (*note Pretty

  8960.      Printing::).  This typically results in a higher-level display of

  8961.      the value's contents.  The 'r' format bypasses any Python

  8962.      pretty-printer which might exist.

  8963. 

  8964.    For example, to print the program counter in hex (*note Registers::),

  8965. type

  8966. 

  8967.      p/x $pc

  8968. 

  8969. Note that no space is required before the slash; this is because command

  8970. names in GDB cannot contain a slash.

  8971. 

  8972.    To reprint the last value in the value history with a different

  8973. format, you can use the 'print' command with just a format and no

  8974. expression.  For example, 'p/x' reprints the last value in hex.

  8975. 

  8976.    ---------- Footnotes ----------

  8977. 

  8978.    (1) 'b' cannot be used because these format letters are also used

  8979. with the 'x' command, where 'b' stands for "byte"; see *note Examining

  8980. Memory: Memory.

  8981. 

  8982. 

  8983. File: gdb.info,  Node: Memory,  Next: Auto Display,  Prev: Output Formats,  Up: Data

  8984. 

  8985. 10.6 Examining Memory

  8986. =====================

  8987. 

  8988. You can use the command 'x' (for "examine") to examine memory in any of

  8989. several formats, independently of your program's data types.

  8990. 

  8991. 'x/NFU ADDR'

  8992. 'x ADDR'

  8993. 'x'

  8994.      Use the 'x' command to examine memory.

  8995. 

  8996.    N, F, and U are all optional parameters that specify how much memory

  8997. to display and how to format it; ADDR is an expression giving the

  8998. address where you want to start displaying memory.  If you use defaults

  8999. for NFU, you need not type the slash '/'.  Several commands set

  9000. convenient defaults for ADDR.

  9001. 

  9002. N, the repeat count

  9003.      The repeat count is a decimal integer; the default is 1.  It

  9004.      specifies how much memory (counting by units U) to display.  If a

  9005.      negative number is specified, memory is examined backward from

  9006.      ADDR.

  9007. 

  9008. F, the display format

  9009.      The display format is one of the formats used by 'print' ('x', 'd',

  9010.      'u', 'o', 't', 'a', 'c', 'f', 's'), and in addition 'i' (for

  9011.      machine instructions).  The default is 'x' (hexadecimal) initially.

  9012.      The default changes each time you use either 'x' or 'print'.

  9013. 

  9014. U, the unit size

  9015.      The unit size is any of

  9016. 

  9017.      'b'

  9018.           Bytes.

  9019.      'h'

  9020.           Halfwords (two bytes).

  9021.      'w'

  9022.           Words (four bytes).  This is the initial default.

  9023.      'g'

  9024.           Giant words (eight bytes).

  9025. 

  9026.      Each time you specify a unit size with 'x', that size becomes the

  9027.      default unit the next time you use 'x'.  For the 'i' format, the

  9028.      unit size is ignored and is normally not written.  For the 's'

  9029.      format, the unit size defaults to 'b', unless it is explicitly

  9030.      given.  Use 'x /hs' to display 16-bit char strings and 'x /ws' to

  9031.      display 32-bit strings.  The next use of 'x /s' will again display

  9032.      8-bit strings.  Note that the results depend on the programming

  9033.      language of the current compilation unit.  If the language is C,

  9034.      the 's' modifier will use the UTF-16 encoding while 'w' will use

  9035.      UTF-32.  The encoding is set by the programming language and cannot

  9036.      be altered.

  9037. 

  9038. ADDR, starting display address

  9039.      ADDR is the address where you want GDB to begin displaying memory.

  9040.      The expression need not have a pointer value (though it may); it is

  9041.      always interpreted as an integer address of a byte of memory.

  9042.      *Note Expressions: Expressions, for more information on

  9043.      expressions.  The default for ADDR is usually just after the last

  9044.      address examined--but several other commands also set the default

  9045.      address: 'info breakpoints' (to the address of the last breakpoint

  9046.      listed), 'info line' (to the starting address of a line), and

  9047.      'print' (if you use it to display a value from memory).

  9048. 

  9049.    For example, 'x/3uh 0x54320' is a request to display three halfwords

  9050. ('h') of memory, formatted as unsigned decimal integers ('u'), starting

  9051. at address '0x54320'.  'x/4xw $sp' prints the four words ('w') of memory

  9052. above the stack pointer (here, '$sp'; *note Registers: Registers.) in

  9053. hexadecimal ('x').

  9054. 

  9055.    You can also specify a negative repeat count to examine memory

  9056. backward from the given address.  For example, 'x/-3uh 0x54320' prints

  9057. three halfwords ('h') at '0x54314', '0x54328', and '0x5431c'.

  9058. 

  9059.    Since the letters indicating unit sizes are all distinct from the

  9060. letters specifying output formats, you do not have to remember whether

  9061. unit size or format comes first; either order works.  The output

  9062. specifications '4xw' and '4wx' mean exactly the same thing.  (However,

  9063. the count N must come first; 'wx4' does not work.)

  9064. 

  9065.    Even though the unit size U is ignored for the formats 's' and 'i',

  9066. you might still want to use a count N; for example, '3i' specifies that

  9067. you want to see three machine instructions, including any operands.  For

  9068. convenience, especially when used with the 'display' command, the 'i'

  9069. format also prints branch delay slot instructions, if any, beyond the

  9070. count specified, which immediately follow the last instruction that is

  9071. within the count.  The command 'disassemble' gives an alternative way of

  9072. inspecting machine instructions; see *note Source and Machine Code:

  9073. Machine Code.

  9074. 

  9075.    If a negative repeat count is specified for the formats 's' or 'i',

  9076. the command displays null-terminated strings or instructions before the

  9077. given address as many as the absolute value of the given number.  For

  9078. the 'i' format, we use line number information in the debug info to

  9079. accurately locate instruction boundaries while disassembling backward.

  9080. If line info is not available, the command stops examining memory with

  9081. an error message.

  9082. 

  9083.    All the defaults for the arguments to 'x' are designed to make it

  9084. easy to continue scanning memory with minimal specifications each time

  9085. you use 'x'.  For example, after you have inspected three machine

  9086. instructions with 'x/3i ADDR', you can inspect the next seven with just

  9087. 'x/7'.  If you use <RET> to repeat the 'x' command, the repeat count N

  9088. is used again; the other arguments default as for successive uses of

  9089. 'x'.

  9090. 

  9091.    When examining machine instructions, the instruction at current

  9092. program counter is shown with a '=>' marker.  For example:

  9093. 

  9094.      (gdb) x/5i $pc-6

  9095.         0x804837f <main+11>: mov    %esp,%ebp

  9096.         0x8048381 <main+13>: push   %ecx

  9097.         0x8048382 <main+14>: sub    $0x4,%esp

  9098.      => 0x8048385 <main+17>: movl   $0x8048460,(%esp)

  9099.         0x804838c <main+24>: call   0x80482d4 <puts@plt>

  9100. 

  9101.    The addresses and contents printed by the 'x' command are not saved

  9102. in the value history because there is often too much of them and they

  9103. would get in the way.  Instead, GDB makes these values available for

  9104. subsequent use in expressions as values of the convenience variables

  9105. '$_' and '$__'.  After an 'x' command, the last address examined is

  9106. available for use in expressions in the convenience variable '$_'.  The

  9107. contents of that address, as examined, are available in the convenience

  9108. variable '$__'.

  9109. 

  9110.    If the 'x' command has a repeat count, the address and contents saved

  9111. are from the last memory unit printed; this is not the same as the last

  9112. address printed if several units were printed on the last line of

  9113. output.

  9114. 

  9115.    Most targets have an addressable memory unit size of 8 bits.  This

  9116. means that to each memory address are associated 8 bits of data.  Some

  9117. targets, however, have other addressable memory unit sizes.  Within GDB

  9118. and this document, the term "addressable memory unit" (or "memory unit"

  9119. for short) is used when explicitly referring to a chunk of data of that

  9120. size.  The word "byte" is used to refer to a chunk of data of 8 bits,

  9121. regardless of the addressable memory unit size of the target.  For most

  9122. systems, addressable memory unit is a synonym of byte.

  9123. 

  9124.    When you are debugging a program running on a remote target machine

  9125. (*note Remote Debugging::), you may wish to verify the program's image

  9126. in the remote machine's memory against the executable file you

  9127. downloaded to the target.  Or, on any target, you may want to check

  9128. whether the program has corrupted its own read-only sections.  The

  9129. 'compare-sections' command is provided for such situations.

  9130. 

  9131. 'compare-sections [SECTION-NAME|-r]'

  9132.      Compare the data of a loadable section SECTION-NAME in the

  9133.      executable file of the program being debugged with the same section

  9134.      in the target machine's memory, and report any mismatches.  With no

  9135.      arguments, compares all loadable sections.  With an argument of

  9136.      '-r', compares all loadable read-only sections.

  9137. 

  9138.      Note: for remote targets, this command can be accelerated if the

  9139.      target supports computing the CRC checksum of a block of memory

  9140.      (*note qCRC packet::).

  9141. 

  9142. 

  9143. File: gdb.info,  Node: Auto Display,  Next: Print Settings,  Prev: Memory,  Up: Data

  9144. 

  9145. 10.7 Automatic Display

  9146. ======================

  9147. 

  9148. If you find that you want to print the value of an expression frequently

  9149. (to see how it changes), you might want to add it to the "automatic

  9150. display list" so that GDB prints its value each time your program stops.

  9151. Each expression added to the list is given a number to identify it; to

  9152. remove an expression from the list, you specify that number.  The

  9153. automatic display looks like this:

  9154. 

  9155.      2: foo = 38

  9156.      3: bar[5] = (struct hack *) 0x3804

  9157. 

  9158. This display shows item numbers, expressions and their current values.

  9159. As with displays you request manually using 'x' or 'print', you can

  9160. specify the output format you prefer; in fact, 'display' decides whether

  9161. to use 'print' or 'x' depending your format specification--it uses 'x'

  9162. if you specify either the 'i' or 's' format, or a unit size; otherwise

  9163. it uses 'print'.

  9164. 

  9165. 'display EXPR'

  9166.      Add the expression EXPR to the list of expressions to display each

  9167.      time your program stops.  *Note Expressions: Expressions.

  9168. 

  9169.      'display' does not repeat if you press <RET> again after using it.

  9170. 

  9171. 'display/FMT EXPR'

  9172.      For FMT specifying only a display format and not a size or count,

  9173.      add the expression EXPR to the auto-display list but arrange to

  9174.      display it each time in the specified format FMT.  *Note Output

  9175.      Formats: Output Formats.

  9176. 

  9177. 'display/FMT ADDR'

  9178.      For FMT 'i' or 's', or including a unit-size or a number of units,

  9179.      add the expression ADDR as a memory address to be examined each

  9180.      time your program stops.  Examining means in effect doing 'x/FMT

  9181.      ADDR'.  *Note Examining Memory: Memory.

  9182. 

  9183.    For example, 'display/i $pc' can be helpful, to see the machine

  9184. instruction about to be executed each time execution stops ('$pc' is a

  9185. common name for the program counter; *note Registers: Registers.).

  9186. 

  9187. 'undisplay DNUMS...'

  9188. 'delete display DNUMS...'

  9189.      Remove items from the list of expressions to display.  Specify the

  9190.      numbers of the displays that you want affected with the command

  9191.      argument DNUMS.  It can be a single display number, one of the

  9192.      numbers shown in the first field of the 'info display' display; or

  9193.      it could be a range of display numbers, as in '2-4'.

  9194. 

  9195.      'undisplay' does not repeat if you press <RET> after using it.

  9196.      (Otherwise you would just get the error 'No display number ...'.)

  9197. 

  9198. 'disable display DNUMS...'

  9199.      Disable the display of item numbers DNUMS.  A disabled display item

  9200.      is not printed automatically, but is not forgotten.  It may be

  9201.      enabled again later.  Specify the numbers of the displays that you

  9202.      want affected with the command argument DNUMS.  It can be a single

  9203.      display number, one of the numbers shown in the first field of the

  9204.      'info display' display; or it could be a range of display numbers,

  9205.      as in '2-4'.

  9206. 

  9207. 'enable display DNUMS...'

  9208.      Enable display of item numbers DNUMS.  It becomes effective once

  9209.      again in auto display of its expression, until you specify

  9210.      otherwise.  Specify the numbers of the displays that you want

  9211.      affected with the command argument DNUMS.  It can be a single

  9212.      display number, one of the numbers shown in the first field of the

  9213.      'info display' display; or it could be a range of display numbers,

  9214.      as in '2-4'.

  9215. 

  9216. 'display'

  9217.      Display the current values of the expressions on the list, just as

  9218.      is done when your program stops.

  9219. 

  9220. 'info display'

  9221.      Print the list of expressions previously set up to display

  9222.      automatically, each one with its item number, but without showing

  9223.      the values.  This includes disabled expressions, which are marked

  9224.      as such.  It also includes expressions which would not be displayed

  9225.      right now because they refer to automatic variables not currently

  9226.      available.

  9227. 

  9228.    If a display expression refers to local variables, then it does not

  9229. make sense outside the lexical context for which it was set up.  Such an

  9230. expression is disabled when execution enters a context where one of its

  9231. variables is not defined.  For example, if you give the command 'display

  9232. last_char' while inside a function with an argument 'last_char', GDB

  9233. displays this argument while your program continues to stop inside that

  9234. function.  When it stops elsewhere--where there is no variable

  9235. 'last_char'--the display is disabled automatically.  The next time your

  9236. program stops where 'last_char' is meaningful, you can enable the

  9237. display expression once again.

  9238. 

  9239. 

  9240. File: gdb.info,  Node: Print Settings,  Next: Pretty Printing,  Prev: Auto Display,  Up: Data

  9241. 

  9242. 10.8 Print Settings

  9243. ===================

  9244. 

  9245. GDB provides the following ways to control how arrays, structures, and

  9246. symbols are printed.

  9247. 

  9248. These settings are useful for debugging programs in any language:

  9249. 

  9250. 'set print address'

  9251. 'set print address on'

  9252.      GDB prints memory addresses showing the location of stack traces,

  9253.      structure values, pointer values, breakpoints, and so forth, even

  9254.      when it also displays the contents of those addresses.  The default

  9255.      is 'on'.  For example, this is what a stack frame display looks

  9256.      like with 'set print address on':

  9257. 

  9258.           (gdb) f

  9259.           #0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")

  9260.               at input.c:530

  9261.           530         if (lquote != def_lquote)

  9262. 

  9263. 'set print address off'

  9264.      Do not print addresses when displaying their contents.  For

  9265.      example, this is the same stack frame displayed with 'set print

  9266.      address off':

  9267. 

  9268.           (gdb) set print addr off

  9269.           (gdb) f

  9270.           #0  set_quotes (lq="<<", rq=">>") at input.c:530

  9271.           530         if (lquote != def_lquote)

  9272. 

  9273.      You can use 'set print address off' to eliminate all machine

  9274.      dependent displays from the GDB interface.  For example, with

  9275.      'print address off', you should get the same text for backtraces on

  9276.      all machines--whether or not they involve pointer arguments.

  9277. 

  9278. 'show print address'

  9279.      Show whether or not addresses are to be printed.

  9280. 

  9281.    When GDB prints a symbolic address, it normally prints the closest

  9282. earlier symbol plus an offset.  If that symbol does not uniquely

  9283. identify the address (for example, it is a name whose scope is a single

  9284. source file), you may need to clarify.  One way to do this is with 'info

  9285. line', for example 'info line *0x4537'.  Alternately, you can set GDB to

  9286. print the source file and line number when it prints a symbolic address:

  9287. 

  9288. 'set print symbol-filename on'

  9289.      Tell GDB to print the source file name and line number of a symbol

  9290.      in the symbolic form of an address.

  9291. 

  9292. 'set print symbol-filename off'

  9293.      Do not print source file name and line number of a symbol.  This is

  9294.      the default.

  9295. 

  9296. 'show print symbol-filename'

  9297.      Show whether or not GDB will print the source file name and line

  9298.      number of a symbol in the symbolic form of an address.

  9299. 

  9300.    Another situation where it is helpful to show symbol filenames and

  9301. line numbers is when disassembling code; GDB shows you the line number

  9302. and source file that corresponds to each instruction.

  9303. 

  9304.    Also, you may wish to see the symbolic form only if the address being

  9305. printed is reasonably close to the closest earlier symbol:

  9306. 

  9307. 'set print max-symbolic-offset MAX-OFFSET'

  9308. 'set print max-symbolic-offset unlimited'

  9309.      Tell GDB to only display the symbolic form of an address if the

  9310.      offset between the closest earlier symbol and the address is less

  9311.      than MAX-OFFSET.  The default is 'unlimited', which tells GDB to

  9312.      always print the symbolic form of an address if any symbol precedes

  9313.      it.  Zero is equivalent to 'unlimited'.

  9314. 

  9315. 'show print max-symbolic-offset'

  9316.      Ask how large the maximum offset is that GDB prints in a symbolic

  9317.      address.

  9318. 

  9319.    If you have a pointer and you are not sure where it points, try 'set

  9320. print symbol-filename on'.  Then you can determine the name and source

  9321. file location of the variable where it points, using 'p/a POINTER'.

  9322. This interprets the address in symbolic form.  For example, here GDB

  9323. shows that a variable 'ptt' points at another variable 't', defined in

  9324. 'hi2.c':

  9325. 

  9326.      (gdb) set print symbol-filename on

  9327.      (gdb) p/a ptt

  9328.      $4 = 0xe008 <t in hi2.c>

  9329. 

  9330.      _Warning:_ For pointers that point to a local variable, 'p/a' does

  9331.      not show the symbol name and filename of the referent, even with

  9332.      the appropriate 'set print' options turned on.

  9333. 

  9334.    You can also enable '/a'-like formatting all the time using 'set

  9335. print symbol on':

  9336. 

  9337. 'set print symbol on'

  9338.      Tell GDB to print the symbol corresponding to an address, if one

  9339.      exists.

  9340. 

  9341. 'set print symbol off'

  9342.      Tell GDB not to print the symbol corresponding to an address.  In

  9343.      this mode, GDB will still print the symbol corresponding to

  9344.      pointers to functions.  This is the default.

  9345. 

  9346. 'show print symbol'

  9347.      Show whether GDB will display the symbol corresponding to an

  9348.      address.

  9349. 

  9350.    Other settings control how different kinds of objects are printed:

  9351. 

  9352. 'set print array'

  9353. 'set print array on'

  9354.      Pretty print arrays.  This format is more convenient to read, but

  9355.      uses more space.  The default is off.

  9356. 

  9357. 'set print array off'

  9358.      Return to compressed format for arrays.

  9359. 

  9360. 'show print array'

  9361.      Show whether compressed or pretty format is selected for displaying

  9362.      arrays.

  9363. 

  9364. 'set print array-indexes'

  9365. 'set print array-indexes on'

  9366.      Print the index of each element when displaying arrays.  May be

  9367.      more convenient to locate a given element in the array or quickly

  9368.      find the index of a given element in that printed array.  The

  9369.      default is off.

  9370. 

  9371. 'set print array-indexes off'

  9372.      Stop printing element indexes when displaying arrays.

  9373. 

  9374. 'show print array-indexes'

  9375.      Show whether the index of each element is printed when displaying

  9376.      arrays.

  9377. 

  9378. 'set print elements NUMBER-OF-ELEMENTS'

  9379. 'set print elements unlimited'

  9380.      Set a limit on how many elements of an array GDB will print.  If

  9381.      GDB is printing a large array, it stops printing after it has

  9382.      printed the number of elements set by the 'set print elements'

  9383.      command.  This limit also applies to the display of strings.  When

  9384.      GDB starts, this limit is set to 200.  Setting NUMBER-OF-ELEMENTS

  9385.      to 'unlimited' or zero means that the number of elements to print

  9386.      is unlimited.

  9387. 

  9388. 'show print elements'

  9389.      Display the number of elements of a large array that GDB will

  9390.      print.  If the number is 0, then the printing is unlimited.

  9391. 

  9392. 'set print frame-arguments VALUE'

  9393.      This command allows to control how the values of arguments are

  9394.      printed when the debugger prints a frame (*note Frames::).  The

  9395.      possible values are:

  9396. 

  9397.      'all'

  9398.           The values of all arguments are printed.

  9399. 

  9400.      'scalars'

  9401.           Print the value of an argument only if it is a scalar.  The

  9402.           value of more complex arguments such as arrays, structures,

  9403.           unions, etc, is replaced by '...'.  This is the default.  Here

  9404.           is an example where only scalar arguments are shown:

  9405. 

  9406.                #1  0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)

  9407.                  at frame-args.c:23

  9408. 

  9409.      'none'

  9410.           None of the argument values are printed.  Instead, the value

  9411.           of each argument is replaced by '...'.  In this case, the

  9412.           example above now becomes:

  9413. 

  9414.                #1  0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)

  9415.                  at frame-args.c:23

  9416. 

  9417.      'presence'

  9418.           Only the presence of arguments is indicated by '...'.  The

  9419.           '...' are not printed for function without any arguments.

  9420.           None of the argument names and values are printed.  In this

  9421.           case, the example above now becomes:

  9422. 

  9423.                #1  0x08048361 in call_me (...) at frame-args.c:23

  9424. 

  9425.      By default, only scalar arguments are printed.  This command can be

  9426.      used to configure the debugger to print the value of all arguments,

  9427.      regardless of their type.  However, it is often advantageous to not

  9428.      print the value of more complex parameters.  For instance, it

  9429.      reduces the amount of information printed in each frame, making the

  9430.      backtrace more readable.  Also, it improves performance when

  9431.      displaying Ada frames, because the computation of large arguments

  9432.      can sometimes be CPU-intensive, especially in large applications.

  9433.      Setting 'print frame-arguments' to 'scalars' (the default), 'none'

  9434.      or 'presence' avoids this computation, thus speeding up the display

  9435.      of each Ada frame.

  9436. 

  9437. 'show print frame-arguments'

  9438.      Show how the value of arguments should be displayed when printing a

  9439.      frame.

  9440. 

  9441. 'set print raw-frame-arguments on'

  9442.      Print frame arguments in raw, non pretty-printed, form.

  9443. 

  9444. 'set print raw-frame-arguments off'

  9445.      Print frame arguments in pretty-printed form, if there is a

  9446.      pretty-printer for the value (*note Pretty Printing::), otherwise

  9447.      print the value in raw form.  This is the default.

  9448. 

  9449. 'show print raw-frame-arguments'

  9450.      Show whether to print frame arguments in raw form.

  9451. 

  9452. 'set print entry-values VALUE'

  9453.      Set printing of frame argument values at function entry.  In some

  9454.      cases GDB can determine the value of function argument which was

  9455.      passed by the function caller, even if the value was modified

  9456.      inside the called function and therefore is different.  With

  9457.      optimized code, the current value could be unavailable, but the

  9458.      entry value may still be known.

  9459. 

  9460.      The default value is 'default' (see below for its description).

  9461.      Older GDB behaved as with the setting 'no'.  Compilers not

  9462.      supporting this feature will behave in the 'default' setting the

  9463.      same way as with the 'no' setting.

  9464. 

  9465.      This functionality is currently supported only by DWARF 2 debugging

  9466.      format and the compiler has to produce 'DW_TAG_call_site' tags.

  9467.      With GCC, you need to specify '-O -g' during compilation, to get

  9468.      this information.

  9469. 

  9470.      The VALUE parameter can be one of the following:

  9471. 

  9472.      'no'

  9473.           Print only actual parameter values, never print values from

  9474.           function entry point.

  9475.                #0  equal (val=5)

  9476.                #0  different (val=6)

  9477.                #0  lost (val=<optimized out>)

  9478.                #0  born (val=10)

  9479.                #0  invalid (val=<optimized out>)

  9480. 

  9481.      'only'

  9482.           Print only parameter values from function entry point.  The

  9483.           actual parameter values are never printed.

  9484.                #0  equal (val@entry=5)

  9485.                #0  different (val@entry=5)

  9486.                #0  lost (val@entry=5)

  9487.                #0  born (val@entry=<optimized out>)

  9488.                #0  invalid (val@entry=<optimized out>)

  9489. 

  9490.      'preferred'

  9491.           Print only parameter values from function entry point.  If

  9492.           value from function entry point is not known while the actual

  9493.           value is known, print the actual value for such parameter.

  9494.                #0  equal (val@entry=5)

  9495.                #0  different (val@entry=5)

  9496.                #0  lost (val@entry=5)

  9497.                #0  born (val=10)

  9498.                #0  invalid (val@entry=<optimized out>)

  9499. 

  9500.      'if-needed'

  9501.           Print actual parameter values.  If actual parameter value is

  9502.           not known while value from function entry point is known,

  9503.           print the entry point value for such parameter.

  9504.                #0  equal (val=5)

  9505.                #0  different (val=6)

  9506.                #0  lost (val@entry=5)

  9507.                #0  born (val=10)

  9508.                #0  invalid (val=<optimized out>)

  9509. 

  9510.      'both'

  9511.           Always print both the actual parameter value and its value

  9512.           from function entry point, even if values of one or both are

  9513.           not available due to compiler optimizations.

  9514.                #0  equal (val=5, val@entry=5)

  9515.                #0  different (val=6, val@entry=5)

  9516.                #0  lost (val=<optimized out>, val@entry=5)

  9517.                #0  born (val=10, val@entry=<optimized out>)

  9518.                #0  invalid (val=<optimized out>, val@entry=<optimized out>)

  9519. 

  9520.      'compact'

  9521.           Print the actual parameter value if it is known and also its

  9522.           value from function entry point if it is known.  If neither is

  9523.           known, print for the actual value '<optimized out>'.  If not

  9524.           in MI mode (*note GDB/MI::) and if both values are known and

  9525.           identical, print the shortened 'param=param@entry=VALUE'

  9526.           notation.

  9527.                #0  equal (val=val@entry=5)

  9528.                #0  different (val=6, val@entry=5)

  9529.                #0  lost (val@entry=5)

  9530.                #0  born (val=10)

  9531.                #0  invalid (val=<optimized out>)

  9532. 

  9533.      'default'

  9534.           Always print the actual parameter value.  Print also its value

  9535.           from function entry point, but only if it is known.  If not in

  9536.           MI mode (*note GDB/MI::) and if both values are known and

  9537.           identical, print the shortened 'param=param@entry=VALUE'

  9538.           notation.

  9539.                #0  equal (val=val@entry=5)

  9540.                #0  different (val=6, val@entry=5)

  9541.                #0  lost (val=<optimized out>, val@entry=5)

  9542.                #0  born (val=10)

  9543.                #0  invalid (val=<optimized out>)

  9544. 

  9545.      For analysis messages on possible failures of frame argument values

  9546.      at function entry resolution see *note set debug entry-values::.

  9547. 

  9548. 'show print entry-values'

  9549.      Show the method being used for printing of frame argument values at

  9550.      function entry.

  9551. 

  9552. 'set print frame-info VALUE'

  9553.      This command allows to control the information printed when the

  9554.      debugger prints a frame.  See *note Frames::, *note Backtrace::,

  9555.      for a general explanation about frames and frame information.  Note

  9556.      that some other settings (such as 'set print frame-arguments' and

  9557.      'set print address') are also influencing if and how some frame

  9558.      information is displayed.  In particular, the frame program counter

  9559.      is never printed if 'set print address' is off.

  9560. 

  9561.      The possible values for 'set print frame-info' are:

  9562.      'short-location'

  9563.           Print the frame level, the program counter (if not at the

  9564.           beginning of the location source line), the function, the

  9565.           function arguments.

  9566.      'location'

  9567.           Same as 'short-location' but also print the source file and

  9568.           source line number.

  9569.      'location-and-address'

  9570.           Same as 'location' but print the program counter even if

  9571.           located at the beginning of the location source line.

  9572.      'source-line'

  9573.           Print the program counter (if not at the beginning of the

  9574.           location source line), the line number and the source line.

  9575.      'source-and-location'

  9576.           Print what 'location' and 'source-line' are printing.

  9577.      'auto'

  9578.           The information printed for a frame is decided automatically

  9579.           by the GDB command that prints a frame.  For example, 'frame'

  9580.           prints the information printed by 'source-and-location' while

  9581.           'stepi' will switch between 'source-line' and

  9582.           'source-and-location' depending on the program counter.  The

  9583.           default value is 'auto'.

  9584. 

  9585. 'set print repeats NUMBER-OF-REPEATS'

  9586. 'set print repeats unlimited'

  9587.      Set the threshold for suppressing display of repeated array

  9588.      elements.  When the number of consecutive identical elements of an

  9589.      array exceeds the threshold, GDB prints the string '"<repeats N

  9590.      times>"', where N is the number of identical repetitions, instead

  9591.      of displaying the identical elements themselves.  Setting the

  9592.      threshold to 'unlimited' or zero will cause all elements to be

  9593.      individually printed.  The default threshold is 10.

  9594. 

  9595. 'show print repeats'

  9596.      Display the current threshold for printing repeated identical

  9597.      elements.

  9598. 

  9599. 'set print max-depth DEPTH'

  9600. 'set print max-depth unlimited'

  9601.      Set the threshold after which nested structures are replaced with

  9602.      ellipsis, this can make visualising deeply nested structures

  9603.      easier.

  9604. 

  9605.      For example, given this C code

  9606. 

  9607.           typedef struct s1 { int a; } s1;

  9608.           typedef struct s2 { s1 b; } s2;

  9609.           typedef struct s3 { s2 c; } s3;

  9610.           typedef struct s4 { s3 d; } s4;

  9611. 

  9612.           s4 var = { { { { 3 } } } };

  9613. 

  9614.      The following table shows how different values of DEPTH will effect

  9615.      how 'var' is printed by GDB:

  9616. 

  9617.      DEPTH setting          Result of 'p var'

  9618.      --------------------------------------------------------------------------

  9619.      unlimited              '$1 = {d = {c = {b = {a = 3}}}}'

  9620.      '0'                    '$1 = {...}'

  9621.      '1'                    '$1 = {d = {...}}'

  9622.      '2'                    '$1 = {d = {c = {...}}}'

  9623.      '3'                    '$1 = {d = {c = {b = {...}}}}'

  9624.      '4'                    '$1 = {d = {c = {b = {a = 3}}}}'

  9625. 

  9626.      To see the contents of structures that have been hidden the user

  9627.      can either increase the print max-depth, or they can print the

  9628.      elements of the structure that are visible, for example

  9629. 

  9630.           (gdb) set print max-depth 2

  9631.           (gdb) p var

  9632.           $1 = {d = {c = {...}}}

  9633.           (gdb) p var.d

  9634.           $2 = {c = {b = {...}}}

  9635.           (gdb) p var.d.c

  9636.           $3 = {b = {a = 3}}

  9637. 

  9638.      The pattern used to replace nested structures varies based on

  9639.      language, for most languages '{...}' is used, but Fortran uses

  9640.      '(...)'.

  9641. 

  9642. 'show print max-depth'

  9643.      Display the current threshold after which nested structures are

  9644.      replaces with ellipsis.

  9645. 

  9646. 'set print null-stop'

  9647.      Cause GDB to stop printing the characters of an array when the

  9648.      first NULL is encountered.  This is useful when large arrays

  9649.      actually contain only short strings.  The default is off.

  9650. 

  9651. 'show print null-stop'

  9652.      Show whether GDB stops printing an array on the first NULL

  9653.      character.

  9654. 

  9655. 'set print pretty on'

  9656.      Cause GDB to print structures in an indented format with one member

  9657.      per line, like this:

  9658. 

  9659.           $1 = {

  9660.             next = 0x0,

  9661.             flags = {

  9662.               sweet = 1,

  9663.               sour = 1

  9664.             },

  9665.             meat = 0x54 "Pork"

  9666.           }

  9667. 

  9668. 'set print pretty off'

  9669.      Cause GDB to print structures in a compact format, like this:

  9670. 

  9671.           $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \

  9672.           meat = 0x54 "Pork"}

  9673. 

  9674.      This is the default format.

  9675. 

  9676. 'show print pretty'

  9677.      Show which format GDB is using to print structures.

  9678. 

  9679. 'set print raw-values on'

  9680.      Print values in raw form, without applying the pretty printers for

  9681.      the value.

  9682. 

  9683. 'set print raw-values off'

  9684.      Print values in pretty-printed form, if there is a pretty-printer

  9685.      for the value (*note Pretty Printing::), otherwise print the value

  9686.      in raw form.

  9687. 

  9688.      The default setting is "off".

  9689. 

  9690. 'show print raw-values'

  9691.      Show whether to print values in raw form.

  9692. 

  9693. 'set print sevenbit-strings on'

  9694.      Print using only seven-bit characters; if this option is set, GDB

  9695.      displays any eight-bit characters (in strings or character values)

  9696.      using the notation '\'NNN.  This setting is best if you are working

  9697.      in English (ASCII) and you use the high-order bit of characters as

  9698.      a marker or "meta" bit.

  9699. 

  9700. 'set print sevenbit-strings off'

  9701.      Print full eight-bit characters.  This allows the use of more

  9702.      international character sets, and is the default.

  9703. 

  9704. 'show print sevenbit-strings'

  9705.      Show whether or not GDB is printing only seven-bit characters.

  9706. 

  9707. 'set print union on'

  9708.      Tell GDB to print unions which are contained in structures and

  9709.      other unions.  This is the default setting.

  9710. 

  9711. 'set print union off'

  9712.      Tell GDB not to print unions which are contained in structures and

  9713.      other unions.  GDB will print '"{...}"' instead.

  9714. 

  9715. 'show print union'

  9716.      Ask GDB whether or not it will print unions which are contained in

  9717.      structures and other unions.

  9718. 

  9719.      For example, given the declarations

  9720. 

  9721.           typedef enum {Tree, Bug} Species;

  9722.           typedef enum {Big_tree, Acorn, Seedling} Tree_forms;

  9723.           typedef enum {Caterpillar, Cocoon, Butterfly}

  9724.                         Bug_forms;

  9725. 

  9726.           struct thing {

  9727.             Species it;

  9728.             union {

  9729.               Tree_forms tree;

  9730.               Bug_forms bug;

  9731.             } form;

  9732.           };

  9733. 

  9734.           struct thing foo = {Tree, {Acorn}};

  9735. 

  9736.      with 'set print union on' in effect 'p foo' would print

  9737. 

  9738.           $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}

  9739. 

  9740.      and with 'set print union off' in effect it would print

  9741. 

  9742.           $1 = {it = Tree, form = {...}}

  9743. 

  9744.      'set print union' affects programs written in C-like languages and

  9745.      in Pascal.

  9746. 

  9747. These settings are of interest when debugging C++ programs:

  9748. 

  9749. 'set print demangle'

  9750. 'set print demangle on'

  9751.      Print C++ names in their source form rather than in the encoded

  9752.      ("mangled") form passed to the assembler and linker for type-safe

  9753.      linkage.  The default is on.

  9754. 

  9755. 'show print demangle'

  9756.      Show whether C++ names are printed in mangled or demangled form.

  9757. 

  9758. 'set print asm-demangle'

  9759. 'set print asm-demangle on'

  9760.      Print C++ names in their source form rather than their mangled

  9761.      form, even in assembler code printouts such as instruction

  9762.      disassemblies.  The default is off.

  9763. 

  9764. 'show print asm-demangle'

  9765.      Show whether C++ names in assembly listings are printed in mangled

  9766.      or demangled form.

  9767. 

  9768. 'set demangle-style STYLE'

  9769.      Choose among several encoding schemes used by different compilers

  9770.      to represent C++ names.  If you omit STYLE, you will see a list of

  9771.      possible formats.  The default value is AUTO, which lets GDB choose

  9772.      a decoding style by inspecting your program.

  9773. 

  9774. 'show demangle-style'

  9775.      Display the encoding style currently in use for decoding C++

  9776.      symbols.

  9777. 

  9778. 'set print object'

  9779. 'set print object on'

  9780.      When displaying a pointer to an object, identify the _actual_

  9781.      (derived) type of the object rather than the _declared_ type, using

  9782.      the virtual function table.  Note that the virtual function table

  9783.      is required--this feature can only work for objects that have

  9784.      run-time type identification; a single virtual method in the

  9785.      object's declared type is sufficient.  Note that this setting is

  9786.      also taken into account when working with variable objects via MI

  9787.      (*note GDB/MI::).

  9788. 

  9789. 'set print object off'

  9790.      Display only the declared type of objects, without reference to the

  9791.      virtual function table.  This is the default setting.

  9792. 

  9793. 'show print object'

  9794.      Show whether actual, or declared, object types are displayed.

  9795. 

  9796. 'set print static-members'

  9797. 'set print static-members on'

  9798.      Print static members when displaying a C++ object.  The default is

  9799.      on.

  9800. 

  9801. 'set print static-members off'

  9802.      Do not print static members when displaying a C++ object.

  9803. 

  9804. 'show print static-members'

  9805.      Show whether C++ static members are printed or not.

  9806. 

  9807. 'set print pascal_static-members'

  9808. 'set print pascal_static-members on'

  9809.      Print static members when displaying a Pascal object.  The default

  9810.      is on.

  9811. 

  9812. 'set print pascal_static-members off'

  9813.      Do not print static members when displaying a Pascal object.

  9814. 

  9815. 'show print pascal_static-members'

  9816.      Show whether Pascal static members are printed or not.

  9817. 

  9818. 'set print vtbl'

  9819. 'set print vtbl on'

  9820.      Pretty print C++ virtual function tables.  The default is off.

  9821.      (The 'vtbl' commands do not work on programs compiled with the HP

  9822.      ANSI C++ compiler ('aCC').)

  9823. 

  9824. 'set print vtbl off'

  9825.      Do not pretty print C++ virtual function tables.

  9826. 

  9827. 'show print vtbl'

  9828.      Show whether C++ virtual function tables are pretty printed, or

  9829.      not.

  9830. 

  9831. 

  9832. File: gdb.info,  Node: Pretty Printing,  Next: Value History,  Prev: Print Settings,  Up: Data

  9833. 

  9834. 10.9 Pretty Printing

  9835. ====================

  9836. 

  9837. GDB provides a mechanism to allow pretty-printing of values using Python

  9838. code.  It greatly simplifies the display of complex objects.  This

  9839. mechanism works for both MI and the CLI.

  9840. 

  9841. * Menu:

  9842. 

  9843. * Pretty-Printer Introduction::  Introduction to pretty-printers

  9844. * Pretty-Printer Example::       An example pretty-printer

  9845. * Pretty-Printer Commands::      Pretty-printer commands

  9846. 

  9847. 

  9848. File: gdb.info,  Node: Pretty-Printer Introduction,  Next: Pretty-Printer Example,  Up: Pretty Printing

  9849. 

  9850. 10.9.1 Pretty-Printer Introduction

  9851. ----------------------------------

  9852. 

  9853. When GDB prints a value, it first sees if there is a pretty-printer

  9854. registered for the value.  If there is then GDB invokes the

  9855. pretty-printer to print the value.  Otherwise the value is printed

  9856. normally.

  9857. 

  9858.    Pretty-printers are normally named.  This makes them easy to manage.

  9859. The 'info pretty-printer' command will list all the installed

  9860. pretty-printers with their names.  If a pretty-printer can handle

  9861. multiple data types, then its "subprinters" are the printers for the

  9862. individual data types.  Each such subprinter has its own name.  The

  9863. format of the name is PRINTER-NAME;SUBPRINTER-NAME.

  9864. 

  9865.    Pretty-printers are installed by "registering" them with GDB.

  9866. Typically they are automatically loaded and registered when the

  9867. corresponding debug information is loaded, thus making them available

  9868. without having to do anything special.

  9869. 

  9870.    There are three places where a pretty-printer can be registered.

  9871. 

  9872.    * Pretty-printers registered globally are available when debugging

  9873.      all inferiors.

  9874. 

  9875.    * Pretty-printers registered with a program space are available only

  9876.      when debugging that program.  *Note Progspaces In Python::, for

  9877.      more details on program spaces in Python.

  9878. 

  9879.    * Pretty-printers registered with an objfile are loaded and unloaded

  9880.      with the corresponding objfile (e.g., shared library).  *Note

  9881.      Objfiles In Python::, for more details on objfiles in Python.

  9882. 

  9883.    *Note Selecting Pretty-Printers::, for further information on how

  9884. pretty-printers are selected,

  9885. 

  9886.    *Note Writing a Pretty-Printer::, for implementing pretty printers

  9887. for new types.

  9888. 

  9889. 

  9890. File: gdb.info,  Node: Pretty-Printer Example,  Next: Pretty-Printer Commands,  Prev: Pretty-Printer Introduction,  Up: Pretty Printing

  9891. 

  9892. 10.9.2 Pretty-Printer Example

  9893. -----------------------------

  9894. 

  9895. Here is how a C++ 'std::string' looks without a pretty-printer:

  9896. 

  9897.      (gdb) print s

  9898.      $1 = {

  9899.        static npos = 4294967295,

  9900.        _M_dataplus = {

  9901.          <std::allocator<char>> = {

  9902.            <__gnu_cxx::new_allocator<char>> = {

  9903.              <No data fields>}, <No data fields>

  9904.            },

  9905.          members of std::basic_string<char, std::char_traits<char>,

  9906.            std::allocator<char> >::_Alloc_hider:

  9907.          _M_p = 0x804a014 "abcd"

  9908.        }

  9909.      }

  9910. 

  9911.    With a pretty-printer for 'std::string' only the contents are

  9912. printed:

  9913. 

  9914.      (gdb) print s

  9915.      $2 = "abcd"

  9916. 

  9917. 

  9918. File: gdb.info,  Node: Pretty-Printer Commands,  Prev: Pretty-Printer Example,  Up: Pretty Printing

  9919. 

  9920. 10.9.3 Pretty-Printer Commands

  9921. ------------------------------

  9922. 

  9923. 'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'

  9924.      Print the list of installed pretty-printers.  This includes

  9925.      disabled pretty-printers, which are marked as such.

  9926. 

  9927.      OBJECT-REGEXP is a regular expression matching the objects whose

  9928.      pretty-printers to list.  Objects can be 'global', the program

  9929.      space's file (*note Progspaces In Python::), and the object files

  9930.      within that program space (*note Objfiles In Python::).  *Note

  9931.      Selecting Pretty-Printers::, for details on how GDB looks up a

  9932.      printer from these three objects.

  9933. 

  9934.      NAME-REGEXP is a regular expression matching the name of the

  9935.      printers to list.

  9936. 

  9937. 'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'

  9938.      Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP.  A

  9939.      disabled pretty-printer is not forgotten, it may be enabled again

  9940.      later.

  9941. 

  9942. 'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'

  9943.      Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP.

  9944. 

  9945.    Example:

  9946. 

  9947.    Suppose we have three pretty-printers installed: one from library1.so

  9948. named 'foo' that prints objects of type 'foo', and another from

  9949. library2.so named 'bar' that prints two types of objects, 'bar1' and

  9950. 'bar2'.

  9951. 

  9952.      (gdb) info pretty-printer

  9953.      library1.so:

  9954.        foo

  9955.      library2.so:

  9956.        bar

  9957.          bar1

  9958.          bar2

  9959.      (gdb) info pretty-printer library2

  9960.      library2.so:

  9961.        bar

  9962.          bar1

  9963.          bar2

  9964.      (gdb) disable pretty-printer library1

  9965.      1 printer disabled

  9966.      2 of 3 printers enabled

  9967.      (gdb) info pretty-printer

  9968.      library1.so:

  9969.        foo [disabled]

  9970.      library2.so:

  9971.        bar

  9972.          bar1

  9973.          bar2

  9974.      (gdb) disable pretty-printer library2 bar;bar1

  9975.      1 printer disabled

  9976.      1 of 3 printers enabled

  9977.      (gdb) info pretty-printer library2

  9978.      library1.so:

  9979.        foo [disabled]

  9980.      library2.so:

  9981.        bar

  9982.          bar1 [disabled]

  9983.          bar2

  9984.      (gdb) disable pretty-printer library2 bar

  9985.      1 printer disabled

  9986.      0 of 3 printers enabled

  9987.      (gdb) info pretty-printer library2

  9988.      library1.so:

  9989.        foo [disabled]

  9990.      library2.so:

  9991.        bar [disabled]

  9992.          bar1 [disabled]

  9993.          bar2

  9994. 

  9995.    Note that for 'bar' the entire printer can be disabled, as can each

  9996. individual subprinter.

  9997. 

  9998.    Printing values and frame arguments is done by default using the

  9999. enabled pretty printers.

  10000. 

  10001.    The print option '-raw-values' and GDB setting 'set print raw-values'

  10002. (*note set print raw-values::) can be used to print values without

  10003. applying the enabled pretty printers.

  10004. 

  10005.    Similarly, the backtrace option '-raw-frame-arguments' and GDB

  10006. setting 'set print raw-frame-arguments' (*note set print

  10007. raw-frame-arguments::) can be used to ignore the enabled pretty printers

  10008. when printing frame argument values.

  10009. 

  10010. 

  10011. File: gdb.info,  Node: Value History,  Next: Convenience Vars,  Prev: Pretty Printing,  Up: Data

  10012. 

  10013. 10.10 Value History

  10014. ===================

  10015. 

  10016. Values printed by the 'print' command are saved in the GDB "value

  10017. history".  This allows you to refer to them in other expressions.

  10018. Values are kept until the symbol table is re-read or discarded (for

  10019. example with the 'file' or 'symbol-file' commands).  When the symbol

  10020. table changes, the value history is discarded, since the values may

  10021. contain pointers back to the types defined in the symbol table.

  10022. 

  10023.    The values printed are given "history numbers" by which you can refer

  10024. to them.  These are successive integers starting with one.  'print'

  10025. shows you the history number assigned to a value by printing '$NUM = '

  10026. before the value; here NUM is the history number.

  10027. 

  10028.    To refer to any previous value, use '$' followed by the value's

  10029. history number.  The way 'print' labels its output is designed to remind

  10030. you of this.  Just '$' refers to the most recent value in the history,

  10031. and '$$' refers to the value before that.  '$$N' refers to the Nth value

  10032. from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent

  10033. to '$$', and '$$0' is equivalent to '$'.

  10034. 

  10035.    For example, suppose you have just printed a pointer to a structure

  10036. and want to see the contents of the structure.  It suffices to type

  10037. 

  10038.      p *$

  10039. 

  10040.    If you have a chain of structures where the component 'next' points

  10041. to the next one, you can print the contents of the next one with this:

  10042. 

  10043.      p *$.next

  10044. 

  10045. You can print successive links in the chain by repeating this

  10046. command--which you can do by just typing <RET>.

  10047. 

  10048.    Note that the history records values, not expressions.  If the value

  10049. of 'x' is 4 and you type these commands:

  10050. 

  10051.      print x

  10052.      set x=5

  10053. 

  10054. then the value recorded in the value history by the 'print' command

  10055. remains 4 even though the value of 'x' has changed.

  10056. 

  10057. 'show values'

  10058.      Print the last ten values in the value history, with their item

  10059.      numbers.  This is like 'p $$9' repeated ten times, except that

  10060.      'show values' does not change the history.

  10061. 

  10062. 'show values N'

  10063.      Print ten history values centered on history item number N.

  10064. 

  10065. 'show values +'

  10066.      Print ten history values just after the values last printed.  If no

  10067.      more values are available, 'show values +' produces no display.

  10068. 

  10069.    Pressing <RET> to repeat 'show values N' has exactly the same effect

  10070. as 'show values +'.

  10071. 

  10072. 

  10073. File: gdb.info,  Node: Convenience Vars,  Next: Convenience Funs,  Prev: Value History,  Up: Data

  10074. 

  10075. 10.11 Convenience Variables

  10076. ===========================

  10077. 

  10078. GDB provides "convenience variables" that you can use within GDB to hold

  10079. on to a value and refer to it later.  These variables exist entirely

  10080. within GDB; they are not part of your program, and setting a convenience

  10081. variable has no direct effect on further execution of your program.

  10082. That is why you can use them freely.

  10083. 

  10084.    Convenience variables are prefixed with '$'.  Any name preceded by

  10085. '$' can be used for a convenience variable, unless it is one of the

  10086. predefined machine-specific register names (*note Registers:

  10087. Registers.).  (Value history references, in contrast, are _numbers_

  10088. preceded by '$'.  *Note Value History: Value History.)

  10089. 

  10090.    You can save a value in a convenience variable with an assignment

  10091. expression, just as you would set a variable in your program.  For

  10092. example:

  10093. 

  10094.      set $foo = *object_ptr

  10095. 

  10096. would save in '$foo' the value contained in the object pointed to by

  10097. 'object_ptr'.

  10098. 

  10099.    Using a convenience variable for the first time creates it, but its

  10100. value is 'void' until you assign a new value.  You can alter the value

  10101. with another assignment at any time.

  10102. 

  10103.    Convenience variables have no fixed types.  You can assign a

  10104. convenience variable any type of value, including structures and arrays,

  10105. even if that variable already has a value of a different type.  The

  10106. convenience variable, when used as an expression, has the type of its

  10107. current value.

  10108. 

  10109. 'show convenience'

  10110.      Print a list of convenience variables used so far, and their

  10111.      values, as well as a list of the convenience functions.

  10112.      Abbreviated 'show conv'.

  10113. 

  10114. 'init-if-undefined $VARIABLE = EXPRESSION'

  10115.      Set a convenience variable if it has not already been set.  This is

  10116.      useful for user-defined commands that keep some state.  It is

  10117.      similar, in concept, to using local static variables with

  10118.      initializers in C (except that convenience variables are global).

  10119.      It can also be used to allow users to override default values used

  10120.      in a command script.

  10121. 

  10122.      If the variable is already defined then the expression is not

  10123.      evaluated so any side-effects do not occur.

  10124. 

  10125.    One of the ways to use a convenience variable is as a counter to be

  10126. incremented or a pointer to be advanced.  For example, to print a field

  10127. from successive elements of an array of structures:

  10128. 

  10129.      set $i = 0

  10130.      print bar[$i++]->contents

  10131. 

  10132. Repeat that command by typing <RET>.

  10133. 

  10134.    Some convenience variables are created automatically by GDB and given

  10135. values likely to be useful.

  10136. 

  10137. '$_'

  10138.      The variable '$_' is automatically set by the 'x' command to the

  10139.      last address examined (*note Examining Memory: Memory.).  Other

  10140.      commands which provide a default address for 'x' to examine also

  10141.      set '$_' to that address; these commands include 'info line' and

  10142.      'info breakpoint'.  The type of '$_' is 'void *' except when set by

  10143.      the 'x' command, in which case it is a pointer to the type of

  10144.      '$__'.

  10145. 

  10146. '$__'

  10147.      The variable '$__' is automatically set by the 'x' command to the

  10148.      value found in the last address examined.  Its type is chosen to

  10149.      match the format in which the data was printed.

  10150. 

  10151. '$_exitcode'

  10152.      When the program being debugged terminates normally, GDB

  10153.      automatically sets this variable to the exit code of the program,

  10154.      and resets '$_exitsignal' to 'void'.

  10155. 

  10156. '$_exitsignal'

  10157.      When the program being debugged dies due to an uncaught signal, GDB

  10158.      automatically sets this variable to that signal's number, and

  10159.      resets '$_exitcode' to 'void'.

  10160. 

  10161.      To distinguish between whether the program being debugged has

  10162.      exited (i.e., '$_exitcode' is not 'void') or signalled (i.e.,

  10163.      '$_exitsignal' is not 'void'), the convenience function '$_isvoid'

  10164.      can be used (*note Convenience Functions: Convenience Funs.).  For

  10165.      example, considering the following source code:

  10166. 

  10167.           #include <signal.h>

  10168. 

  10169.           int

  10170.           main (int argc, char *argv[])

  10171.           {

  10172.             raise (SIGALRM);

  10173.             return 0;

  10174.           }

  10175. 

  10176.      A valid way of telling whether the program being debugged has

  10177.      exited or signalled would be:

  10178. 

  10179.           (gdb) define has_exited_or_signalled

  10180.           Type commands for definition of ``has_exited_or_signalled''.

  10181.           End with a line saying just ``end''.

  10182.           >if $_isvoid ($_exitsignal)

  10183.            >echo The program has exited\n

  10184.            >else

  10185.            >echo The program has signalled\n

  10186.            >end

  10187.           >end

  10188.           (gdb) run

  10189.           Starting program:

  10190. 

  10191.           Program terminated with signal SIGALRM, Alarm clock.

  10192.           The program no longer exists.

  10193.           (gdb) has_exited_or_signalled

  10194.           The program has signalled

  10195. 

  10196.      As can be seen, GDB correctly informs that the program being

  10197.      debugged has signalled, since it calls 'raise' and raises a

  10198.      'SIGALRM' signal.  If the program being debugged had not called

  10199.      'raise', then GDB would report a normal exit:

  10200. 

  10201.           (gdb) has_exited_or_signalled

  10202.           The program has exited

  10203. 

  10204. '$_exception'

  10205.      The variable '$_exception' is set to the exception object being

  10206.      thrown at an exception-related catchpoint.  *Note Set

  10207.      Catchpoints::.

  10208. 

  10209. '$_ada_exception'

  10210.      The variable '$_ada_exception' is set to the address of the

  10211.      exception being caught or thrown at an Ada exception-related

  10212.      catchpoint.  *Note Set Catchpoints::.

  10213. 

  10214. '$_probe_argc'

  10215. '$_probe_arg0...$_probe_arg11'

  10216.      Arguments to a static probe.  *Note Static Probe Points::.

  10217. 

  10218. '$_sdata'

  10219.      The variable '$_sdata' contains extra collected static tracepoint

  10220.      data.  *Note Tracepoint Action Lists: Tracepoint Actions.  Note

  10221.      that '$_sdata' could be empty, if not inspecting a trace buffer, or

  10222.      if extra static tracepoint data has not been collected.

  10223. 

  10224. '$_siginfo'

  10225.      The variable '$_siginfo' contains extra signal information (*note

  10226.      extra signal information::).  Note that '$_siginfo' could be empty,

  10227.      if the application has not yet received any signals.  For example,

  10228.      it will be empty before you execute the 'run' command.

  10229. 

  10230. '$_tlb'

  10231.      The variable '$_tlb' is automatically set when debugging

  10232.      applications running on MS-Windows in native mode or connected to

  10233.      gdbserver that supports the 'qGetTIBAddr' request.  *Note General

  10234.      Query Packets::.  This variable contains the address of the thread

  10235.      information block.

  10236. 

  10237. '$_inferior'

  10238.      The number of the current inferior.  *Note Debugging Multiple

  10239.      Inferiors Connections and Programs: Inferiors Connections and

  10240.      Programs.

  10241. 

  10242. '$_thread'

  10243.      The thread number of the current thread.  *Note thread numbers::.

  10244. 

  10245. '$_gthread'

  10246.      The global number of the current thread.  *Note global thread

  10247.      numbers::.

  10248. 

  10249. '$_gdb_major'

  10250. '$_gdb_minor'

  10251.      The major and minor version numbers of the running GDB.

  10252.      Development snapshots and pretest versions have their minor version

  10253.      incremented by one; thus, GDB pretest 9.11.90 will produce the

  10254.      value 12 for '$_gdb_minor'.  These variables allow you to write

  10255.      scripts that work with different versions of GDB without errors

  10256.      caused by features unavailable in some of those versions.

  10257. 

  10258. '$_shell_exitcode'

  10259. '$_shell_exitsignal'

  10260.      GDB commands such as 'shell' and '|' are launching shell commands.

  10261.      When a launched command terminates, GDB automatically maintains the

  10262.      variables '$_shell_exitcode' and '$_shell_exitsignal' according to

  10263.      the exit status of the last launched command.  These variables are

  10264.      set and used similarly to the variables '$_exitcode' and

  10265.      '$_exitsignal'.

  10266. 

  10267. 

  10268. File: gdb.info,  Node: Convenience Funs,  Next: Registers,  Prev: Convenience Vars,  Up: Data

  10269. 

  10270. 10.12 Convenience Functions

  10271. ===========================

  10272. 

  10273. GDB also supplies some "convenience functions".  These have a syntax

  10274. similar to convenience variables.  A convenience function can be used in

  10275. an expression just like an ordinary function; however, a convenience

  10276. function is implemented internally to GDB.

  10277. 

  10278.    These functions do not require GDB to be configured with 'Python'

  10279. support, which means that they are always available.

  10280. 

  10281. '$_isvoid (EXPR)'

  10282.      Return one if the expression EXPR is 'void'.  Otherwise it returns

  10283.      zero.

  10284. 

  10285.      A 'void' expression is an expression where the type of the result

  10286.      is 'void'.  For example, you can examine a convenience variable

  10287.      (see *note Convenience Variables: Convenience Vars.) to check

  10288.      whether it is 'void':

  10289. 

  10290.           (gdb) print $_exitcode

  10291.           $1 = void

  10292.           (gdb) print $_isvoid ($_exitcode)

  10293.           $2 = 1

  10294.           (gdb) run

  10295.           Starting program: ./a.out

  10296.           [Inferior 1 (process 29572) exited normally]

  10297.           (gdb) print $_exitcode

  10298.           $3 = 0

  10299.           (gdb) print $_isvoid ($_exitcode)

  10300.           $4 = 0

  10301. 

  10302.      In the example above, we used '$_isvoid' to check whether

  10303.      '$_exitcode' is 'void' before and after the execution of the

  10304.      program being debugged.  Before the execution there is no exit code

  10305.      to be examined, therefore '$_exitcode' is 'void'.  After the

  10306.      execution the program being debugged returned zero, therefore

  10307.      '$_exitcode' is zero, which means that it is not 'void' anymore.

  10308. 

  10309.      The 'void' expression can also be a call of a function from the

  10310.      program being debugged.  For example, given the following function:

  10311. 

  10312.           void

  10313.           foo (void)

  10314.           {

  10315.           }

  10316. 

  10317.      The result of calling it inside GDB is 'void':

  10318. 

  10319.           (gdb) print foo ()

  10320.           $1 = void

  10321.           (gdb) print $_isvoid (foo ())

  10322.           $2 = 1

  10323.           (gdb) set $v = foo ()

  10324.           (gdb) print $v

  10325.           $3 = void

  10326.           (gdb) print $_isvoid ($v)

  10327.           $4 = 1

  10328. 

  10329. '$_gdb_setting_str (SETTING)'

  10330.      Return the value of the GDB SETTING as a string.  SETTING is any

  10331.      setting that can be used in a 'set' or 'show' command (*note

  10332.      Controlling GDB::).

  10333. 

  10334.           (gdb) show print frame-arguments

  10335.           Printing of non-scalar frame arguments is "scalars".

  10336.           (gdb) p $_gdb_setting_str("print frame-arguments")

  10337.           $1 = "scalars"

  10338.           (gdb) p $_gdb_setting_str("height")

  10339.           $2 = "30"

  10340.           (gdb)

  10341. 

  10342. '$_gdb_setting (SETTING)'

  10343.      Return the value of the GDB SETTING.  The type of the returned

  10344.      value depends on the setting.

  10345. 

  10346.      The value type for boolean and auto boolean settings is 'int'.  The

  10347.      boolean values 'off' and 'on' are converted to the integer values

  10348.      '0' and '1'.  The value 'auto' is converted to the value '-1'.

  10349. 

  10350.      The value type for integer settings is either 'unsigned int' or

  10351.      'int', depending on the setting.

  10352. 

  10353.      Some integer settings accept an 'unlimited' value.  Depending on

  10354.      the setting, the 'set' command also accepts the value '0' or the

  10355.      value '-1' as a synonym for 'unlimited'.  For example, 'set height

  10356.      unlimited' is equivalent to 'set height 0'.

  10357. 

  10358.      Some other settings that accept the 'unlimited' value use the value

  10359.      '0' to literally mean zero.  For example, 'set history size 0'

  10360.      indicates to not record any GDB commands in the command history.

  10361.      For such settings, '-1' is the synonym for 'unlimited'.

  10362. 

  10363.      See the documentation of the corresponding 'set' command for the

  10364.      numerical value equivalent to 'unlimited'.

  10365. 

  10366.      The '$_gdb_setting' function converts the unlimited value to a '0'

  10367.      or a '-1' value according to what the 'set' command uses.

  10368. 

  10369.           (gdb) p $_gdb_setting_str("height")

  10370.           $1 = "30"

  10371.           (gdb) p $_gdb_setting("height")

  10372.           $2 = 30

  10373.           (gdb) set height unlimited

  10374.           (gdb) p $_gdb_setting_str("height")

  10375.           $3 = "unlimited"

  10376.           (gdb) p $_gdb_setting("height")

  10377.           $4 = 0

  10378.           (gdb) p $_gdb_setting_str("history size")

  10379.           $5 = "unlimited"

  10380.           (gdb) p $_gdb_setting("history size")

  10381.           $6 = -1

  10382.           (gdb) p $_gdb_setting_str("disassemble-next-line")

  10383.           $7 = "auto"

  10384.           (gdb) p $_gdb_setting("disassemble-next-line")

  10385.           $8 = -1

  10386.           (gdb)

  10387. 

  10388.      Other setting types (enum, filename, optional filename, string,

  10389.      string noescape) are returned as string values.

  10390. 

  10391. '$_gdb_maint_setting_str (SETTING)'

  10392.      Like the '$_gdb_setting_str' function, but works with 'maintenance

  10393.      set' variables.

  10394. 

  10395. '$_gdb_maint_setting (SETTING)'

  10396.      Like the '$_gdb_setting' function, but works with 'maintenance set'

  10397.      variables.

  10398. 

  10399.    The following functions require GDB to be configured with 'Python'

  10400. support.

  10401. 

  10402. '$_memeq(BUF1, BUF2, LENGTH)'

  10403.      Returns one if the LENGTH bytes at the addresses given by BUF1 and

  10404.      BUF2 are equal.  Otherwise it returns zero.

  10405. 

  10406. '$_regex(STR, REGEX)'

  10407.      Returns one if the string STR matches the regular expression REGEX.

  10408.      Otherwise it returns zero.  The syntax of the regular expression is

  10409.      that specified by 'Python''s regular expression support.

  10410. 

  10411. '$_streq(STR1, STR2)'

  10412.      Returns one if the strings STR1 and STR2 are equal.  Otherwise it

  10413.      returns zero.

  10414. 

  10415. '$_strlen(STR)'

  10416.      Returns the length of string STR.

  10417. 

  10418. '$_caller_is(NAME[, NUMBER_OF_FRAMES])'

  10419.      Returns one if the calling function's name is equal to NAME.

  10420.      Otherwise it returns zero.

  10421. 

  10422.      If the optional argument NUMBER_OF_FRAMES is provided, it is the

  10423.      number of frames up in the stack to look.  The default is 1.

  10424. 

  10425.      Example:

  10426. 

  10427.           (gdb) backtrace

  10428.           #0  bottom_func ()

  10429.               at testsuite/gdb.python/py-caller-is.c:21

  10430.           #1  0x00000000004005a0 in middle_func ()

  10431.               at testsuite/gdb.python/py-caller-is.c:27

  10432.           #2  0x00000000004005ab in top_func ()

  10433.               at testsuite/gdb.python/py-caller-is.c:33

  10434.           #3  0x00000000004005b6 in main ()

  10435.               at testsuite/gdb.python/py-caller-is.c:39

  10436.           (gdb) print $_caller_is ("middle_func")

  10437.           $1 = 1

  10438.           (gdb) print $_caller_is ("top_func", 2)

  10439.           $1 = 1

  10440. 

  10441. '$_caller_matches(REGEXP[, NUMBER_OF_FRAMES])'

  10442.      Returns one if the calling function's name matches the regular

  10443.      expression REGEXP.  Otherwise it returns zero.

  10444. 

  10445.      If the optional argument NUMBER_OF_FRAMES is provided, it is the

  10446.      number of frames up in the stack to look.  The default is 1.

  10447. 

  10448. '$_any_caller_is(NAME[, NUMBER_OF_FRAMES])'

  10449.      Returns one if any calling function's name is equal to NAME.

  10450.      Otherwise it returns zero.

  10451. 

  10452.      If the optional argument NUMBER_OF_FRAMES is provided, it is the

  10453.      number of frames up in the stack to look.  The default is 1.

  10454. 

  10455.      This function differs from '$_caller_is' in that this function

  10456.      checks all stack frames from the immediate caller to the frame

  10457.      specified by NUMBER_OF_FRAMES, whereas '$_caller_is' only checks

  10458.      the frame specified by NUMBER_OF_FRAMES.

  10459. 

  10460. '$_any_caller_matches(REGEXP[, NUMBER_OF_FRAMES])'

  10461.      Returns one if any calling function's name matches the regular

  10462.      expression REGEXP.  Otherwise it returns zero.

  10463. 

  10464.      If the optional argument NUMBER_OF_FRAMES is provided, it is the

  10465.      number of frames up in the stack to look.  The default is 1.

  10466. 

  10467.      This function differs from '$_caller_matches' in that this function

  10468.      checks all stack frames from the immediate caller to the frame

  10469.      specified by NUMBER_OF_FRAMES, whereas '$_caller_matches' only

  10470.      checks the frame specified by NUMBER_OF_FRAMES.

  10471. 

  10472. '$_as_string(VALUE)'

  10473.      Return the string representation of VALUE.

  10474. 

  10475.      This function is useful to obtain the textual label (enumerator) of

  10476.      an enumeration value.  For example, assuming the variable NODE is

  10477.      of an enumerated type:

  10478. 

  10479.           (gdb) printf "Visiting node of type %s\n", $_as_string(node)

  10480.           Visiting node of type NODE_INTEGER

  10481. 

  10482. '$_cimag(VALUE)'

  10483. '$_creal(VALUE)'

  10484.      Return the imaginary ('$_cimag') or real ('$_creal') part of the

  10485.      complex number VALUE.

  10486. 

  10487.      The type of the imaginary or real part depends on the type of the

  10488.      complex number, e.g., using '$_cimag' on a 'float complex' will

  10489.      return an imaginary part of type 'float'.

  10490. 

  10491.    GDB provides the ability to list and get help on convenience

  10492. functions.

  10493. 

  10494. 'help function'

  10495.      Print a list of all convenience functions.

  10496. 

  10497. 

  10498. File: gdb.info,  Node: Registers,  Next: Floating Point Hardware,  Prev: Convenience Funs,  Up: Data

  10499. 

  10500. 10.13 Registers

  10501. ===============

  10502. 

  10503. You can refer to machine register contents, in expressions, as variables

  10504. with names starting with '$'.  The names of registers are different for

  10505. each machine; use 'info registers' to see the names used on your

  10506. machine.

  10507. 

  10508. 'info registers'

  10509.      Print the names and values of all registers except floating-point

  10510.      and vector registers (in the selected stack frame).

  10511. 

  10512. 'info all-registers'

  10513.      Print the names and values of all registers, including

  10514.      floating-point and vector registers (in the selected stack frame).

  10515. 

  10516. 'info registers REGGROUP ...'

  10517.      Print the name and value of the registers in each of the specified

  10518.      REGGROUPs.  The REGGROUP can be any of those returned by 'maint

  10519.      print reggroups' (*note Maintenance Commands::).

  10520. 

  10521. 'info registers REGNAME ...'

  10522.      Print the "relativized" value of each specified register REGNAME.

  10523.      As discussed in detail below, register values are normally relative

  10524.      to the selected stack frame.  The REGNAME may be any register name

  10525.      valid on the machine you are using, with or without the initial

  10526.      '$'.

  10527. 

  10528.    GDB has four "standard" register names that are available (in

  10529. expressions) on most machines--whenever they do not conflict with an

  10530. architecture's canonical mnemonics for registers.  The register names

  10531. '$pc' and '$sp' are used for the program counter register and the stack

  10532. pointer.  '$fp' is used for a register that contains a pointer to the

  10533. current stack frame, and '$ps' is used for a register that contains the

  10534. processor status.  For example, you could print the program counter in

  10535. hex with

  10536. 

  10537.      p/x $pc

  10538. 

  10539. or print the instruction to be executed next with

  10540. 

  10541.      x/i $pc

  10542. 

  10543. or add four to the stack pointer(1) with

  10544. 

  10545.      set $sp += 4

  10546. 

  10547.    Whenever possible, these four standard register names are available

  10548. on your machine even though the machine has different canonical

  10549. mnemonics, so long as there is no conflict.  The 'info registers'

  10550. command shows the canonical names.  For example, on the SPARC, 'info

  10551. registers' displays the processor status register as '$psr' but you can

  10552. also refer to it as '$ps'; and on x86-based machines '$ps' is an alias

  10553. for the EFLAGS register.

  10554. 

  10555.    GDB always considers the contents of an ordinary register as an

  10556. integer when the register is examined in this way.  Some machines have

  10557. special registers which can hold nothing but floating point; these

  10558. registers are considered to have floating point values.  There is no way

  10559. to refer to the contents of an ordinary register as floating point value

  10560. (although you can _print_ it as a floating point value with 'print/f

  10561. $REGNAME').

  10562. 

  10563.    Some registers have distinct "raw" and "virtual" data formats.  This

  10564. means that the data format in which the register contents are saved by

  10565. the operating system is not the same one that your program normally

  10566. sees.  For example, the registers of the 68881 floating point

  10567. coprocessor are always saved in "extended" (raw) format, but all C

  10568. programs expect to work with "double" (virtual) format.  In such cases,

  10569. GDB normally works with the virtual format only (the format that makes

  10570. sense for your program), but the 'info registers' command prints the

  10571. data in both formats.

  10572. 

  10573.    Some machines have special registers whose contents can be

  10574. interpreted in several different ways.  For example, modern x86-based

  10575. machines have SSE and MMX registers that can hold several values packed

  10576. together in several different formats.  GDB refers to such registers in

  10577. 'struct' notation:

  10578. 

  10579.      (gdb) print $xmm1

  10580.      $1 = {

  10581.        v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044},

  10582.        v2_double = {9.92129282474342e-303, 2.7585945287983262e-313},

  10583.        v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",

  10584.        v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0},

  10585.        v4_int32 = {0, 20657912, 11, 13},

  10586.        v2_int64 = {88725056443645952, 55834574859},

  10587.        uint128 = 0x0000000d0000000b013b36f800000000

  10588.      }

  10589. 

  10590. To set values of such registers, you need to tell GDB which view of the

  10591. register you wish to change, as if you were assigning value to a

  10592. 'struct' member:

  10593. 

  10594.       (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF

  10595. 

  10596.    Normally, register values are relative to the selected stack frame

  10597. (*note Selecting a Frame: Selection.).  This means that you get the

  10598. value that the register would contain if all stack frames farther in

  10599. were exited and their saved registers restored.  In order to see the

  10600. true contents of hardware registers, you must select the innermost frame

  10601. (with 'frame 0').

  10602. 

  10603.    Usually ABIs reserve some registers as not needed to be saved by the

  10604. callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile"

  10605. registers).  It may therefore not be possible for GDB to know the value

  10606. a register had before the call (in other words, in the outer frame), if

  10607. the register value has since been changed by the callee.  GDB tries to

  10608. deduce where the inner frame saved ("callee-saved") registers, from the

  10609. debug info, unwind info, or the machine code generated by your compiler.

  10610. If some register is not saved, and GDB knows the register is

  10611. "caller-saved" (via its own knowledge of the ABI, or because the

  10612. debug/unwind info explicitly says the register's value is undefined),

  10613. GDB displays '<not saved>' as the register's value.  With targets that

  10614. GDB has no knowledge of the register saving convention, if a register

  10615. was not saved by the callee, then its value and location in the outer

  10616. frame are assumed to be the same of the inner frame.  This is usually

  10617. harmless, because if the register is call-clobbered, the caller either

  10618. does not care what is in the register after the call, or has code to

  10619. restore the value that it does care about.  Note, however, that if you

  10620. change such a register in the outer frame, you may also be affecting the

  10621. inner frame.  Also, the more "outer" the frame is you're looking at, the

  10622. more likely a call-clobbered register's value is to be wrong, in the

  10623. sense that it doesn't actually represent the value the register had just

  10624. before the call.

  10625. 

  10626.    ---------- Footnotes ----------

  10627. 

  10628.    (1) This is a way of removing one word from the stack, on machines

  10629. where stacks grow downward in memory (most machines, nowadays).  This

  10630. assumes that the innermost stack frame is selected; setting '$sp' is not

  10631. allowed when other stack frames are selected.  To pop entire frames off

  10632. the stack, regardless of machine architecture, use 'return'; see *note

  10633. Returning from a Function: Returning.

  10634. 

  10635. 

  10636. File: gdb.info,  Node: Floating Point Hardware,  Next: Vector Unit,  Prev: Registers,  Up: Data

  10637. 

  10638. 10.14 Floating Point Hardware

  10639. =============================

  10640. 

  10641. Depending on the configuration, GDB may be able to give you more

  10642. information about the status of the floating point hardware.

  10643. 

  10644. 'info float'

  10645.      Display hardware-dependent information about the floating point

  10646.      unit.  The exact contents and layout vary depending on the floating

  10647.      point chip.  Currently, 'info float' is supported on the ARM and

  10648.      x86 machines.

  10649. 

  10650. 

  10651. File: gdb.info,  Node: Vector Unit,  Next: OS Information,  Prev: Floating Point Hardware,  Up: Data

  10652. 

  10653. 10.15 Vector Unit

  10654. =================

  10655. 

  10656. Depending on the configuration, GDB may be able to give you more

  10657. information about the status of the vector unit.

  10658. 

  10659. 'info vector'

  10660.      Display information about the vector unit.  The exact contents and

  10661.      layout vary depending on the hardware.

  10662. 

  10663. 

  10664. File: gdb.info,  Node: OS Information,  Next: Memory Region Attributes,  Prev: Vector Unit,  Up: Data

  10665. 

  10666. 10.16 Operating System Auxiliary Information

  10667. ============================================

  10668. 

  10669. GDB provides interfaces to useful OS facilities that can help you debug

  10670. your program.

  10671. 

  10672.    Some operating systems supply an "auxiliary vector" to programs at

  10673. startup.  This is akin to the arguments and environment that you specify

  10674. for a program, but contains a system-dependent variety of binary values

  10675. that tell system libraries important details about the hardware,

  10676. operating system, and process.  Each value's purpose is identified by an

  10677. integer tag; the meanings are well-known but system-specific.  Depending

  10678. on the configuration and operating system facilities, GDB may be able to

  10679. show you this information.  For remote targets, this functionality may

  10680. further depend on the remote stub's support of the 'qXfer:auxv:read'

  10681. packet, see *note qXfer auxiliary vector read::.

  10682. 

  10683. 'info auxv'

  10684.      Display the auxiliary vector of the inferior, which can be either a

  10685.      live process or a core dump file.  GDB prints each tag value

  10686.      numerically, and also shows names and text descriptions for

  10687.      recognized tags.  Some values in the vector are numbers, some bit

  10688.      masks, and some pointers to strings or other data.  GDB displays

  10689.      each value in the most appropriate form for a recognized tag, and

  10690.      in hexadecimal for an unrecognized tag.

  10691. 

  10692.    On some targets, GDB can access operating system-specific information

  10693. and show it to you.  The types of information available will differ

  10694. depending on the type of operating system running on the target.  The

  10695. mechanism used to fetch the data is described in *note Operating System

  10696. Information::.  For remote targets, this functionality depends on the

  10697. remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer

  10698. osdata read::.

  10699. 

  10700. 'info os INFOTYPE'

  10701. 

  10702.      Display OS information of the requested type.

  10703. 

  10704.      On GNU/Linux, the following values of INFOTYPE are valid:

  10705. 

  10706.      'cpus'

  10707.           Display the list of all CPUs/cores.  For each CPU/core, GDB

  10708.           prints the available fields from /proc/cpuinfo.  For each

  10709.           supported architecture different fields are available.  Two

  10710.           common entries are processor which gives CPU number and

  10711.           bogomips; a system constant that is calculated during kernel

  10712.           initialization.

  10713. 

  10714.      'files'

  10715.           Display the list of open file descriptors on the target.  For

  10716.           each file descriptor, GDB prints the identifier of the process

  10717.           owning the descriptor, the command of the owning process, the

  10718.           value of the descriptor, and the target of the descriptor.

  10719. 

  10720.      'modules'

  10721.           Display the list of all loaded kernel modules on the target.

  10722.           For each module, GDB prints the module name, the size of the

  10723.           module in bytes, the number of times the module is used, the

  10724.           dependencies of the module, the status of the module, and the

  10725.           address of the loaded module in memory.

  10726. 

  10727.      'msg'

  10728.           Display the list of all System V message queues on the target.

  10729.           For each message queue, GDB prints the message queue key, the

  10730.           message queue identifier, the access permissions, the current

  10731.           number of bytes on the queue, the current number of messages

  10732.           on the queue, the processes that last sent and received a

  10733.           message on the queue, the user and group of the owner and

  10734.           creator of the message queue, the times at which a message was

  10735.           last sent and received on the queue, and the time at which the

  10736.           message queue was last changed.

  10737. 

  10738.      'processes'

  10739.           Display the list of processes on the target.  For each

  10740.           process, GDB prints the process identifier, the name of the

  10741.           user, the command corresponding to the process, and the list

  10742.           of processor cores that the process is currently running on.

  10743.           (To understand what these properties mean, for this and the

  10744.           following info types, please consult the general GNU/Linux

  10745.           documentation.)

  10746. 

  10747.      'procgroups'

  10748.           Display the list of process groups on the target.  For each

  10749.           process, GDB prints the identifier of the process group that

  10750.           it belongs to, the command corresponding to the process group

  10751.           leader, the process identifier, and the command line of the

  10752.           process.  The list is sorted first by the process group

  10753.           identifier, then by the process identifier, so that processes

  10754.           belonging to the same process group are grouped together and

  10755.           the process group leader is listed first.

  10756. 

  10757.      'semaphores'

  10758.           Display the list of all System V semaphore sets on the target.

  10759.           For each semaphore set, GDB prints the semaphore set key, the

  10760.           semaphore set identifier, the access permissions, the number

  10761.           of semaphores in the set, the user and group of the owner and

  10762.           creator of the semaphore set, and the times at which the

  10763.           semaphore set was operated upon and changed.

  10764. 

  10765.      'shm'

  10766.           Display the list of all System V shared-memory regions on the

  10767.           target.  For each shared-memory region, GDB prints the region

  10768.           key, the shared-memory identifier, the access permissions, the

  10769.           size of the region, the process that created the region, the

  10770.           process that last attached to or detached from the region, the

  10771.           current number of live attaches to the region, and the times

  10772.           at which the region was last attached to, detach from, and

  10773.           changed.

  10774. 

  10775.      'sockets'

  10776.           Display the list of Internet-domain sockets on the target.

  10777.           For each socket, GDB prints the address and port of the local

  10778.           and remote endpoints, the current state of the connection, the

  10779.           creator of the socket, the IP address family of the socket,

  10780.           and the type of the connection.

  10781. 

  10782.      'threads'

  10783.           Display the list of threads running on the target.  For each

  10784.           thread, GDB prints the identifier of the process that the

  10785.           thread belongs to, the command of the process, the thread

  10786.           identifier, and the processor core that it is currently

  10787.           running on.  The main thread of a process is not listed.

  10788. 

  10789. 'info os'

  10790.      If INFOTYPE is omitted, then list the possible values for INFOTYPE

  10791.      and the kind of OS information available for each INFOTYPE.  If the

  10792.      target does not return a list of possible types, this command will

  10793.      report an error.

  10794. 

  10795. 

  10796. File: gdb.info,  Node: Memory Region Attributes,  Next: Dump/Restore Files,  Prev: OS Information,  Up: Data

  10797. 

  10798. 10.17 Memory Region Attributes

  10799. ==============================

  10800. 

  10801. "Memory region attributes" allow you to describe special handling

  10802. required by regions of your target's memory.  GDB uses attributes to

  10803. determine whether to allow certain types of memory accesses; whether to

  10804. use specific width accesses; and whether to cache target memory.  By

  10805. default the description of memory regions is fetched from the target (if

  10806. the current target supports this), but the user can override the fetched

  10807. regions.

  10808. 

  10809.    Defined memory regions can be individually enabled and disabled.

  10810. When a memory region is disabled, GDB uses the default attributes when

  10811. accessing memory in that region.  Similarly, if no memory regions have

  10812. been defined, GDB uses the default attributes when accessing all memory.

  10813. 

  10814.    When a memory region is defined, it is given a number to identify it;

  10815. to enable, disable, or remove a memory region, you specify that number.

  10816. 

  10817. 'mem LOWER UPPER ATTRIBUTES...'

  10818.      Define a memory region bounded by LOWER and UPPER with attributes

  10819.      ATTRIBUTES..., and add it to the list of regions monitored by GDB.

  10820.      Note that UPPER == 0 is a special case: it is treated as the

  10821.      target's maximum memory address.  (0xffff on 16 bit targets,

  10822.      0xffffffff on 32 bit targets, etc.)

  10823. 

  10824. 'mem auto'

  10825.      Discard any user changes to the memory regions and use

  10826.      target-supplied regions, if available, or no regions if the target

  10827.      does not support.

  10828. 

  10829. 'delete mem NUMS...'

  10830.      Remove memory regions NUMS... from the list of regions monitored by

  10831.      GDB.

  10832. 

  10833. 'disable mem NUMS...'

  10834.      Disable monitoring of memory regions NUMS....  A disabled memory

  10835.      region is not forgotten.  It may be enabled again later.

  10836. 

  10837. 'enable mem NUMS...'

  10838.      Enable monitoring of memory regions NUMS....

  10839. 

  10840. 'info mem'

  10841.      Print a table of all defined memory regions, with the following

  10842.      columns for each region:

  10843. 

  10844.      _Memory Region Number_

  10845.      _Enabled or Disabled._

  10846.           Enabled memory regions are marked with 'y'.  Disabled memory

  10847.           regions are marked with 'n'.

  10848. 

  10849.      _Lo Address_

  10850.           The address defining the inclusive lower bound of the memory

  10851.           region.

  10852. 

  10853.      _Hi Address_

  10854.           The address defining the exclusive upper bound of the memory

  10855.           region.

  10856. 

  10857.      _Attributes_

  10858.           The list of attributes set for this memory region.

  10859. 

  10860. 10.17.1 Attributes

  10861. ------------------

  10862. 

  10863. 10.17.1.1 Memory Access Mode

  10864. ............................

  10865. 

  10866. The access mode attributes set whether GDB may make read or write

  10867. accesses to a memory region.

  10868. 

  10869.    While these attributes prevent GDB from performing invalid memory

  10870. accesses, they do nothing to prevent the target system, I/O DMA, etc.

  10871. from accessing memory.

  10872. 

  10873. 'ro'

  10874.      Memory is read only.

  10875. 'wo'

  10876.      Memory is write only.

  10877. 'rw'

  10878.      Memory is read/write.  This is the default.

  10879. 

  10880. 10.17.1.2 Memory Access Size

  10881. ............................

  10882. 

  10883. The access size attribute tells GDB to use specific sized accesses in

  10884. the memory region.  Often memory mapped device registers require

  10885. specific sized accesses.  If no access size attribute is specified, GDB

  10886. may use accesses of any size.

  10887. 

  10888. '8'

  10889.      Use 8 bit memory accesses.

  10890. '16'

  10891.      Use 16 bit memory accesses.

  10892. '32'

  10893.      Use 32 bit memory accesses.

  10894. '64'

  10895.      Use 64 bit memory accesses.

  10896. 

  10897. 10.17.1.3 Data Cache

  10898. ....................

  10899. 

  10900. The data cache attributes set whether GDB will cache target memory.

  10901. While this generally improves performance by reducing debug protocol

  10902. overhead, it can lead to incorrect results because GDB does not know

  10903. about volatile variables or memory mapped device registers.

  10904. 

  10905. 'cache'

  10906.      Enable GDB to cache target memory.

  10907. 'nocache'

  10908.      Disable GDB from caching target memory.  This is the default.

  10909. 

  10910. 10.17.2 Memory Access Checking

  10911. ------------------------------

  10912. 

  10913. GDB can be instructed to refuse accesses to memory that is not

  10914. explicitly described.  This can be useful if accessing such regions has

  10915. undesired effects for a specific target, or to provide better error

  10916. checking.  The following commands control this behaviour.

  10917. 

  10918. 'set mem inaccessible-by-default [on|off]'

  10919.      If 'on' is specified, make GDB treat memory not explicitly

  10920.      described by the memory ranges as non-existent and refuse accesses

  10921.      to such memory.  The checks are only performed if there's at least

  10922.      one memory range defined.  If 'off' is specified, make GDB treat

  10923.      the memory not explicitly described by the memory ranges as RAM.

  10924.      The default value is 'on'.

  10925. 'show mem inaccessible-by-default'

  10926.      Show the current handling of accesses to unknown memory.

  10927. 

  10928. 

  10929. File: gdb.info,  Node: Dump/Restore Files,  Next: Core File Generation,  Prev: Memory Region Attributes,  Up: Data

  10930. 

  10931. 10.18 Copy Between Memory and a File

  10932. ====================================

  10933. 

  10934. You can use the commands 'dump', 'append', and 'restore' to copy data

  10935. between target memory and a file.  The 'dump' and 'append' commands

  10936. write data to a file, and the 'restore' command reads data from a file

  10937. back into the inferior's memory.  Files may be in binary, Motorola

  10938. S-record, Intel hex, Tektronix Hex, or Verilog Hex format; however, GDB

  10939. can only append to binary files, and cannot read from Verilog Hex files.

  10940. 

  10941. 'dump [FORMAT] memory FILENAME START_ADDR END_ADDR'

  10942. 'dump [FORMAT] value FILENAME EXPR'

  10943.      Dump the contents of memory from START_ADDR to END_ADDR, or the

  10944.      value of EXPR, to FILENAME in the given format.

  10945. 

  10946.      The FORMAT parameter may be any one of:

  10947.      'binary'

  10948.           Raw binary form.

  10949.      'ihex'

  10950.           Intel hex format.

  10951.      'srec'

  10952.           Motorola S-record format.

  10953.      'tekhex'

  10954.           Tektronix Hex format.

  10955.      'verilog'

  10956.           Verilog Hex format.

  10957. 

  10958.      GDB uses the same definitions of these formats as the GNU binary

  10959.      utilities, like 'objdump' and 'objcopy'.  If FORMAT is omitted, GDB

  10960.      dumps the data in raw binary form.

  10961. 

  10962. 'append [binary] memory FILENAME START_ADDR END_ADDR'

  10963. 'append [binary] value FILENAME EXPR'

  10964.      Append the contents of memory from START_ADDR to END_ADDR, or the

  10965.      value of EXPR, to the file FILENAME, in raw binary form.  (GDB can

  10966.      only append data to files in raw binary form.)

  10967. 

  10968. 'restore FILENAME [binary] BIAS START END'

  10969.      Restore the contents of file FILENAME into memory.  The 'restore'

  10970.      command can automatically recognize any known BFD file format,

  10971.      except for raw binary.  To restore a raw binary file you must

  10972.      specify the optional keyword 'binary' after the filename.

  10973. 

  10974.      If BIAS is non-zero, its value will be added to the addresses

  10975.      contained in the file.  Binary files always start at address zero,

  10976.      so they will be restored at address BIAS.  Other bfd files have a

  10977.      built-in location; they will be restored at offset BIAS from that

  10978.      location.

  10979. 

  10980.      If START and/or END are non-zero, then only data between file

  10981.      offset START and file offset END will be restored.  These offsets

  10982.      are relative to the addresses in the file, before the BIAS argument

  10983.      is applied.

  10984. 

  10985. 

  10986. File: gdb.info,  Node: Core File Generation,  Next: Character Sets,  Prev: Dump/Restore Files,  Up: Data

  10987. 

  10988. 10.19 How to Produce a Core File from Your Program

  10989. ==================================================

  10990. 

  10991. A "core file" or "core dump" is a file that records the memory image of

  10992. a running process and its process status (register values etc.).  Its

  10993. primary use is post-mortem debugging of a program that crashed while it

  10994. ran outside a debugger.  A program that crashes automatically produces a

  10995. core file, unless this feature is disabled by the user.  *Note Files::,

  10996. for information on invoking GDB in the post-mortem debugging mode.

  10997. 

  10998.    Occasionally, you may wish to produce a core file of the program you

  10999. are debugging in order to preserve a snapshot of its state.  GDB has a

  11000. special command for that.

  11001. 

  11002. 'generate-core-file [FILE]'

  11003. 'gcore [FILE]'

  11004.      Produce a core dump of the inferior process.  The optional argument

  11005.      FILE specifies the file name where to put the core dump.  If not

  11006.      specified, the file name defaults to 'core.PID', where PID is the

  11007.      inferior process ID.

  11008. 

  11009.      Note that this command is implemented only for some systems (as of

  11010.      this writing, GNU/Linux, FreeBSD, Solaris, and S390).

  11011. 

  11012.      On GNU/Linux, this command can take into account the value of the

  11013.      file '/proc/PID/coredump_filter' when generating the core dump

  11014.      (*note set use-coredump-filter::), and by default honors the

  11015.      'VM_DONTDUMP' flag for mappings where it is present in the file

  11016.      '/proc/PID/smaps' (*note set dump-excluded-mappings::).

  11017. 

  11018. 'set use-coredump-filter on'

  11019. 'set use-coredump-filter off'

  11020.      Enable or disable the use of the file '/proc/PID/coredump_filter'

  11021.      when generating core dump files.  This file is used by the Linux

  11022.      kernel to decide what types of memory mappings will be dumped or

  11023.      ignored when generating a core dump file.  PID is the process ID of

  11024.      a currently running process.

  11025. 

  11026.      To make use of this feature, you have to write in the

  11027.      '/proc/PID/coredump_filter' file a value, in hexadecimal, which is

  11028.      a bit mask representing the memory mapping types.  If a bit is set

  11029.      in the bit mask, then the memory mappings of the corresponding

  11030.      types will be dumped; otherwise, they will be ignored.  This

  11031.      configuration is inherited by child processes.  For more

  11032.      information about the bits that can be set in the

  11033.      '/proc/PID/coredump_filter' file, please refer to the manpage of

  11034.      'core(5)'.

  11035. 

  11036.      By default, this option is 'on'.  If this option is turned 'off',

  11037.      GDB does not read the 'coredump_filter' file and instead uses the

  11038.      same default value as the Linux kernel in order to decide which

  11039.      pages will be dumped in the core dump file.  This value is

  11040.      currently '0x33', which means that bits '0' (anonymous private

  11041.      mappings), '1' (anonymous shared mappings), '4' (ELF headers) and

  11042.      '5' (private huge pages) are active.  This will cause these memory

  11043.      mappings to be dumped automatically.

  11044. 

  11045. 'set dump-excluded-mappings on'

  11046. 'set dump-excluded-mappings off'

  11047.      If 'on' is specified, GDB will dump memory mappings marked with the

  11048.      'VM_DONTDUMP' flag.  This flag is represented in the file

  11049.      '/proc/PID/smaps' with the acronym 'dd'.

  11050. 

  11051.      The default value is 'off'.

  11052. 

  11053. 

  11054. File: gdb.info,  Node: Character Sets,  Next: Caching Target Data,  Prev: Core File Generation,  Up: Data

  11055. 

  11056. 10.20 Character Sets

  11057. ====================

  11058. 

  11059. If the program you are debugging uses a different character set to

  11060. represent characters and strings than the one GDB uses itself, GDB can

  11061. automatically translate between the character sets for you.  The

  11062. character set GDB uses we call the "host character set"; the one the

  11063. inferior program uses we call the "target character set".

  11064. 

  11065.    For example, if you are running GDB on a GNU/Linux system, which uses

  11066. the ISO Latin 1 character set, but you are using GDB's remote protocol

  11067. (*note Remote Debugging::) to debug a program running on an IBM

  11068. mainframe, which uses the EBCDIC character set, then the host character

  11069. set is Latin-1, and the target character set is EBCDIC.  If you give GDB

  11070. the command 'set target-charset EBCDIC-US', then GDB translates between

  11071. EBCDIC and Latin 1 as you print character or string values, or use

  11072. character and string literals in expressions.

  11073. 

  11074.    GDB has no way to automatically recognize which character set the

  11075. inferior program uses; you must tell it, using the 'set target-charset'

  11076. command, described below.

  11077. 

  11078.    Here are the commands for controlling GDB's character set support:

  11079. 

  11080. 'set target-charset CHARSET'

  11081.      Set the current target character set to CHARSET.  To display the

  11082.      list of supported target character sets, type

  11083.      'set target-charset <TAB><TAB>'.

  11084. 

  11085. 'set host-charset CHARSET'

  11086.      Set the current host character set to CHARSET.

  11087. 

  11088.      By default, GDB uses a host character set appropriate to the system

  11089.      it is running on; you can override that default using the 'set

  11090.      host-charset' command.  On some systems, GDB cannot automatically

  11091.      determine the appropriate host character set.  In this case, GDB

  11092.      uses 'UTF-8'.

  11093. 

  11094.      GDB can only use certain character sets as its host character set.

  11095.      If you type 'set host-charset <TAB><TAB>', GDB will list the host

  11096.      character sets it supports.

  11097. 

  11098. 'set charset CHARSET'

  11099.      Set the current host and target character sets to CHARSET.  As

  11100.      above, if you type 'set charset <TAB><TAB>', GDB will list the

  11101.      names of the character sets that can be used for both host and

  11102.      target.

  11103. 

  11104. 'show charset'

  11105.      Show the names of the current host and target character sets.

  11106. 

  11107. 'show host-charset'

  11108.      Show the name of the current host character set.

  11109. 

  11110. 'show target-charset'

  11111.      Show the name of the current target character set.

  11112. 

  11113. 'set target-wide-charset CHARSET'

  11114.      Set the current target's wide character set to CHARSET.  This is

  11115.      the character set used by the target's 'wchar_t' type.  To display

  11116.      the list of supported wide character sets, type

  11117.      'set target-wide-charset <TAB><TAB>'.

  11118. 

  11119. 'show target-wide-charset'

  11120.      Show the name of the current target's wide character set.

  11121. 

  11122.    Here is an example of GDB's character set support in action.  Assume

  11123. that the following source code has been placed in the file

  11124. 'charset-test.c':

  11125. 

  11126.      #include <stdio.h>

  11127. 

  11128.      char ascii_hello[]

  11129.        = {72, 101, 108, 108, 111, 44, 32, 119,

  11130.           111, 114, 108, 100, 33, 10, 0};

  11131.      char ibm1047_hello[]

  11132.        = {200, 133, 147, 147, 150, 107, 64, 166,

  11133.           150, 153, 147, 132, 90, 37, 0};

  11134. 

  11135.      main ()

  11136.      {

  11137.        printf ("Hello, world!\n");

  11138.      }

  11139. 

  11140.    In this program, 'ascii_hello' and 'ibm1047_hello' are arrays

  11141. containing the string 'Hello, world!' followed by a newline, encoded in

  11142. the ASCII and IBM1047 character sets.

  11143. 

  11144.    We compile the program, and invoke the debugger on it:

  11145. 

  11146.      $ gcc -g charset-test.c -o charset-test

  11147.      $ gdb -nw charset-test

  11148.      GNU gdb 2001-12-19-cvs

  11149.      Copyright 2001 Free Software Foundation, Inc.

  11150.      ...

  11151.      (gdb)

  11152. 

  11153.    We can use the 'show charset' command to see what character sets GDB

  11154. is currently using to interpret and display characters and strings:

  11155. 

  11156.      (gdb) show charset

  11157.      The current host and target character set is `ISO-8859-1'.

  11158.      (gdb)

  11159. 

  11160.    For the sake of printing this manual, let's use ASCII as our initial

  11161. character set:

  11162.      (gdb) set charset ASCII

  11163.      (gdb) show charset

  11164.      The current host and target character set is `ASCII'.

  11165.      (gdb)

  11166. 

  11167.    Let's assume that ASCII is indeed the correct character set for our

  11168. host system -- in other words, let's assume that if GDB prints

  11169. characters using the ASCII character set, our terminal will display them

  11170. properly.  Since our current target character set is also ASCII, the

  11171. contents of 'ascii_hello' print legibly:

  11172. 

  11173.      (gdb) print ascii_hello

  11174.      $1 = 0x401698 "Hello, world!\n"

  11175.      (gdb) print ascii_hello[0]

  11176.      $2 = 72 'H'

  11177.      (gdb)

  11178. 

  11179.    GDB uses the target character set for character and string literals

  11180. you use in expressions:

  11181. 

  11182.      (gdb) print '+'

  11183.      $3 = 43 '+'

  11184.      (gdb)

  11185. 

  11186.    The ASCII character set uses the number 43 to encode the '+'

  11187. character.

  11188. 

  11189.    GDB relies on the user to tell it which character set the target

  11190. program uses.  If we print 'ibm1047_hello' while our target character

  11191. set is still ASCII, we get jibberish:

  11192. 

  11193.      (gdb) print ibm1047_hello

  11194.      $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"

  11195.      (gdb) print ibm1047_hello[0]

  11196.      $5 = 200 '\310'

  11197.      (gdb)

  11198. 

  11199.    If we invoke the 'set target-charset' followed by <TAB><TAB>, GDB

  11200. tells us the character sets it supports:

  11201. 

  11202.      (gdb) set target-charset

  11203.      ASCII       EBCDIC-US   IBM1047     ISO-8859-1

  11204.      (gdb) set target-charset

  11205. 

  11206.    We can select IBM1047 as our target character set, and examine the

  11207. program's strings again.  Now the ASCII string is wrong, but GDB

  11208. translates the contents of 'ibm1047_hello' from the target character

  11209. set, IBM1047, to the host character set, ASCII, and they display

  11210. correctly:

  11211. 

  11212.      (gdb) set target-charset IBM1047

  11213.      (gdb) show charset

  11214.      The current host character set is `ASCII'.

  11215.      The current target character set is `IBM1047'.

  11216.      (gdb) print ascii_hello

  11217.      $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"

  11218.      (gdb) print ascii_hello[0]

  11219.      $7 = 72 '\110'

  11220.      (gdb) print ibm1047_hello

  11221.      $8 = 0x4016a8 "Hello, world!\n"

  11222.      (gdb) print ibm1047_hello[0]

  11223.      $9 = 200 'H'

  11224.      (gdb)

  11225. 

  11226.    As above, GDB uses the target character set for character and string

  11227. literals you use in expressions:

  11228. 

  11229.      (gdb) print '+'

  11230.      $10 = 78 '+'

  11231.      (gdb)

  11232. 

  11233.    The IBM1047 character set uses the number 78 to encode the '+'

  11234. character.

  11235. 

  11236. 

  11237. File: gdb.info,  Node: Caching Target Data,  Next: Searching Memory,  Prev: Character Sets,  Up: Data

  11238. 

  11239. 10.21 Caching Data of Targets

  11240. =============================

  11241. 

  11242. GDB caches data exchanged between the debugger and a target.  Each cache

  11243. is associated with the address space of the inferior.  *Note Inferiors

  11244. Connections and Programs::, about inferior and address space.  Such

  11245. caching generally improves performance in remote debugging (*note Remote

  11246. Debugging::), because it reduces the overhead of the remote protocol by

  11247. bundling memory reads and writes into large chunks.  Unfortunately,

  11248. simply caching everything would lead to incorrect results, since GDB

  11249. does not necessarily know anything about volatile values, memory-mapped

  11250. I/O addresses, etc.  Furthermore, in non-stop mode (*note Non-Stop

  11251. Mode::) memory can be changed _while_ a gdb command is executing.

  11252. Therefore, by default, GDB only caches data known to be on the stack(1)

  11253. or in the code segment.  Other regions of memory can be explicitly

  11254. marked as cacheable; *note Memory Region Attributes::.

  11255. 

  11256. 'set remotecache on'

  11257. 'set remotecache off'

  11258.      This option no longer does anything; it exists for compatibility

  11259.      with old scripts.

  11260. 

  11261. 'show remotecache'

  11262.      Show the current state of the obsolete remotecache flag.

  11263. 

  11264. 'set stack-cache on'

  11265. 'set stack-cache off'

  11266.      Enable or disable caching of stack accesses.  When 'on', use

  11267.      caching.  By default, this option is 'on'.

  11268. 

  11269. 'show stack-cache'

  11270.      Show the current state of data caching for memory accesses.

  11271. 

  11272. 'set code-cache on'

  11273. 'set code-cache off'

  11274.      Enable or disable caching of code segment accesses.  When 'on', use

  11275.      caching.  By default, this option is 'on'.  This improves

  11276.      performance of disassembly in remote debugging.

  11277. 

  11278. 'show code-cache'

  11279.      Show the current state of target memory cache for code segment

  11280.      accesses.

  11281. 

  11282. 'info dcache [line]'

  11283.      Print the information about the performance of data cache of the

  11284.      current inferior's address space.  The information displayed

  11285.      includes the dcache width and depth, and for each cache line, its

  11286.      number, address, and how many times it was referenced.  This

  11287.      command is useful for debugging the data cache operation.

  11288. 

  11289.      If a line number is specified, the contents of that line will be

  11290.      printed in hex.

  11291. 

  11292. 'set dcache size SIZE'

  11293.      Set maximum number of entries in dcache (dcache depth above).

  11294. 

  11295. 'set dcache line-size LINE-SIZE'

  11296.      Set number of bytes each dcache entry caches (dcache width above).

  11297.      Must be a power of 2.

  11298. 

  11299. 'show dcache size'

  11300.      Show maximum number of dcache entries.  *Note info dcache: Caching

  11301.      Target Data.

  11302. 

  11303. 'show dcache line-size'

  11304.      Show default size of dcache lines.

  11305. 

  11306.    ---------- Footnotes ----------

  11307. 

  11308.    (1) In non-stop mode, it is moderately rare for a running thread to

  11309. modify the stack of a stopped thread in a way that would interfere with

  11310. a backtrace, and caching of stack reads provides a significant speed up

  11311. of remote backtraces.

  11312. 

  11313. 

  11314. File: gdb.info,  Node: Searching Memory,  Next: Value Sizes,  Prev: Caching Target Data,  Up: Data

  11315. 

  11316. 10.22 Search Memory

  11317. ===================

  11318. 

  11319. Memory can be searched for a particular sequence of bytes with the

  11320. 'find' command.

  11321. 

  11322. 'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'

  11323. 'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'

  11324.      Search memory for the sequence of bytes specified by VAL1, VAL2,

  11325.      etc.  The search begins at address START_ADDR and continues for

  11326.      either LEN bytes or through to END_ADDR inclusive.

  11327. 

  11328.    S and N are optional parameters.  They may be specified in either

  11329. order, apart or together.

  11330. 

  11331. S, search query size

  11332.      The size of each search query value.

  11333. 

  11334.      'b'

  11335.           bytes

  11336.      'h'

  11337.           halfwords (two bytes)

  11338.      'w'

  11339.           words (four bytes)

  11340.      'g'

  11341.           giant words (eight bytes)

  11342. 

  11343.      All values are interpreted in the current language.  This means,

  11344.      for example, that if the current source language is C/C++ then

  11345.      searching for the string "hello" includes the trailing '\0'.  The

  11346.      null terminator can be removed from searching by using casts, e.g.:

  11347.      '{char[5]}"hello"'.

  11348. 

  11349.      If the value size is not specified, it is taken from the value's

  11350.      type in the current language.  This is useful when one wants to

  11351.      specify the search pattern as a mixture of types.  Note that this

  11352.      means, for example, that in the case of C-like languages a search

  11353.      for an untyped 0x42 will search for '(int) 0x42' which is typically

  11354.      four bytes.

  11355. 

  11356. N, maximum number of finds

  11357.      The maximum number of matches to print.  The default is to print

  11358.      all finds.

  11359. 

  11360.    You can use strings as search values.  Quote them with double-quotes

  11361. ('"').  The string value is copied into the search pattern byte by byte,

  11362. regardless of the endianness of the target and the size specification.

  11363. 

  11364.    The address of each match found is printed as well as a count of the

  11365. number of matches found.

  11366. 

  11367.    The address of the last value found is stored in convenience variable

  11368. '$_'.  A count of the number of matches is stored in '$numfound'.

  11369. 

  11370.    For example, if stopped at the 'printf' in this function:

  11371. 

  11372.      void

  11373.      hello ()

  11374.      {

  11375.        static char hello[] = "hello-hello";

  11376.        static struct { char c; short s; int i; }

  11377.          __attribute__ ((packed)) mixed

  11378.          = { 'c', 0x1234, 0x87654321 };

  11379.        printf ("%s\n", hello);

  11380.      }

  11381. 

  11382. you get during debugging:

  11383. 

  11384.      (gdb) find &hello[0], +sizeof(hello), "hello"

  11385.      0x804956d <hello.1620+6>

  11386.      1 pattern found

  11387.      (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'

  11388.      0x8049567 <hello.1620>

  11389.      0x804956d <hello.1620+6>

  11390.      2 patterns found.

  11391.      (gdb) find &hello[0], +sizeof(hello), {char[5]}"hello"

  11392.      0x8049567 <hello.1620>

  11393.      0x804956d <hello.1620+6>

  11394.      2 patterns found.

  11395.      (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'

  11396.      0x8049567 <hello.1620>

  11397.      1 pattern found

  11398.      (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321

  11399.      0x8049560 <mixed.1625>

  11400.      1 pattern found

  11401.      (gdb) print $numfound

  11402.      $1 = 1

  11403.      (gdb) print $_

  11404.      $2 = (void *) 0x8049560

  11405. 

  11406. 

  11407. File: gdb.info,  Node: Value Sizes,  Prev: Searching Memory,  Up: Data

  11408. 

  11409. 10.23 Value Sizes

  11410. =================

  11411. 

  11412. Whenever GDB prints a value memory will be allocated within GDB to hold

  11413. the contents of the value.  It is possible in some languages with

  11414. dynamic typing systems, that an invalid program may indicate a value

  11415. that is incorrectly large, this in turn may cause GDB to try and

  11416. allocate an overly large amount of memory.

  11417. 

  11418. 'set max-value-size BYTES'

  11419. 'set max-value-size unlimited'

  11420.      Set the maximum size of memory that GDB will allocate for the

  11421.      contents of a value to BYTES, trying to display a value that

  11422.      requires more memory than that will result in an error.

  11423. 

  11424.      Setting this variable does not effect values that have already been

  11425.      allocated within GDB, only future allocations.

  11426. 

  11427.      There's a minimum size that 'max-value-size' can be set to in order

  11428.      that GDB can still operate correctly, this minimum is currently 16

  11429.      bytes.

  11430. 

  11431.      The limit applies to the results of some subexpressions as well as

  11432.      to complete expressions.  For example, an expression denoting a

  11433.      simple integer component, such as 'x.y.z', may fail if the size of

  11434.      X.Y is dynamic and exceeds BYTES.  On the other hand, GDB is

  11435.      sometimes clever; the expression 'A[i]', where A is an array

  11436.      variable with non-constant size, will generally succeed regardless

  11437.      of the bounds on A, as long as the component size is less than

  11438.      BYTES.

  11439. 

  11440.      The default value of 'max-value-size' is currently 64k.

  11441. 

  11442. 'show max-value-size'

  11443.      Show the maximum size of memory, in bytes, that GDB will allocate

  11444.      for the contents of a value.

  11445. 

  11446. 

  11447. File: gdb.info,  Node: Optimized Code,  Next: Macros,  Prev: Data,  Up: Top

  11448. 

  11449. 11 Debugging Optimized Code

  11450. ***************************

  11451. 

  11452. Almost all compilers support optimization.  With optimization disabled,

  11453. the compiler generates assembly code that corresponds directly to your

  11454. source code, in a simplistic way.  As the compiler applies more powerful

  11455. optimizations, the generated assembly code diverges from your original

  11456. source code.  With help from debugging information generated by the

  11457. compiler, GDB can map from the running program back to constructs from

  11458. your original source.

  11459. 

  11460.    GDB is more accurate with optimization disabled.  If you can

  11461. recompile without optimization, it is easier to follow the progress of

  11462. your program during debugging.  But, there are many cases where you may

  11463. need to debug an optimized version.

  11464. 

  11465.    When you debug a program compiled with '-g -O', remember that the

  11466. optimizer has rearranged your code; the debugger shows you what is

  11467. really there.  Do not be too surprised when the execution path does not

  11468. exactly match your source file!  An extreme example: if you define a

  11469. variable, but never use it, GDB never sees that variable--because the

  11470. compiler optimizes it out of existence.

  11471. 

  11472.    Some things do not work as well with '-g -O' as with just '-g',

  11473. particularly on machines with instruction scheduling.  If in doubt,

  11474. recompile with '-g' alone, and if this fixes the problem, please report

  11475. it to us as a bug (including a test case!).  *Note Variables::, for more

  11476. information about debugging optimized code.

  11477. 

  11478. * Menu:

  11479. 

  11480. * Inline Functions::            How GDB presents inlining

  11481. * Tail Call Frames::            GDB analysis of jumps to functions

  11482. 

  11483. 

  11484. File: gdb.info,  Node: Inline Functions,  Next: Tail Call Frames,  Up: Optimized Code

  11485. 

  11486. 11.1 Inline Functions

  11487. =====================

  11488. 

  11489. "Inlining" is an optimization that inserts a copy of the function body

  11490. directly at each call site, instead of jumping to a shared routine.  GDB

  11491. displays inlined functions just like non-inlined functions.  They appear

  11492. in backtraces.  You can view their arguments and local variables, step

  11493. into them with 'step', skip them with 'next', and escape from them with

  11494. 'finish'.  You can check whether a function was inlined by using the

  11495. 'info frame' command.

  11496. 

  11497.    For GDB to support inlined functions, the compiler must record

  11498. information about inlining in the debug information -- GCC using the

  11499. DWARF 2 format does this, and several other compilers do also.  GDB only

  11500. supports inlined functions when using DWARF 2.  Versions of GCC before

  11501. 4.1 do not emit two required attributes ('DW_AT_call_file' and

  11502. 'DW_AT_call_line'); GDB does not display inlined function calls with

  11503. earlier versions of GCC.  It instead displays the arguments and local

  11504. variables of inlined functions as local variables in the caller.

  11505. 

  11506.    The body of an inlined function is directly included at its call

  11507. site; unlike a non-inlined function, there are no instructions devoted

  11508. to the call.  GDB still pretends that the call site and the start of the

  11509. inlined function are different instructions.  Stepping to the call site

  11510. shows the call site, and then stepping again shows the first line of the

  11511. inlined function, even though no additional instructions are executed.

  11512. 

  11513.    This makes source-level debugging much clearer; you can see both the

  11514. context of the call and then the effect of the call.  Only stepping by a

  11515. single instruction using 'stepi' or 'nexti' does not do this; single

  11516. instruction steps always show the inlined body.

  11517. 

  11518.    There are some ways that GDB does not pretend that inlined function

  11519. calls are the same as normal calls:

  11520. 

  11521.    * Setting breakpoints at the call site of an inlined function may not

  11522.      work, because the call site does not contain any code.  GDB may

  11523.      incorrectly move the breakpoint to the next line of the enclosing

  11524.      function, after the call.  This limitation will be removed in a

  11525.      future version of GDB; until then, set a breakpoint on an earlier

  11526.      line or inside the inlined function instead.

  11527. 

  11528.    * GDB cannot locate the return value of inlined calls after using the

  11529.      'finish' command.  This is a limitation of compiler-generated

  11530.      debugging information; after 'finish', you can step to the next

  11531.      line and print a variable where your program stored the return

  11532.      value.

  11533. 

  11534. 

  11535. File: gdb.info,  Node: Tail Call Frames,  Prev: Inline Functions,  Up: Optimized Code

  11536. 

  11537. 11.2 Tail Call Frames

  11538. =====================

  11539. 

  11540. Function 'B' can call function 'C' in its very last statement.  In

  11541. unoptimized compilation the call of 'C' is immediately followed by

  11542. return instruction at the end of 'B' code.  Optimizing compiler may

  11543. replace the call and return in function 'B' into one jump to function

  11544. 'C' instead.  Such use of a jump instruction is called "tail call".

  11545. 

  11546.    During execution of function 'C', there will be no indication in the

  11547. function call stack frames that it was tail-called from 'B'.  If

  11548. function 'A' regularly calls function 'B' which tail-calls function 'C',

  11549. then GDB will see 'A' as the caller of 'C'.  However, in some cases GDB

  11550. can determine that 'C' was tail-called from 'B', and it will then create

  11551. fictitious call frame for that, with the return address set up as if 'B'

  11552. called 'C' normally.

  11553. 

  11554.    This functionality is currently supported only by DWARF 2 debugging

  11555. format and the compiler has to produce 'DW_TAG_call_site' tags.  With

  11556. GCC, you need to specify '-O -g' during compilation, to get this

  11557. information.

  11558. 

  11559.    'info frame' command (*note Frame Info::) will indicate the tail call

  11560. frame kind by text 'tail call frame' such as in this sample GDB output:

  11561. 

  11562.      (gdb) x/i $pc - 2

  11563.         0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>

  11564.      (gdb) info frame

  11565.      Stack level 1, frame at 0x7fffffffda30:

  11566.       rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5

  11567.       tail call frame, caller of frame at 0x7fffffffda30

  11568.       source language c++.

  11569.       Arglist at unknown address.

  11570.       Locals at unknown address, Previous frame's sp is 0x7fffffffda30

  11571. 

  11572.    The detection of all the possible code path executions can find them

  11573. ambiguous.  There is no execution history stored (possible *note Reverse

  11574. Execution:: is never used for this purpose) and the last known caller

  11575. could have reached the known callee by multiple different jump

  11576. sequences.  In such case GDB still tries to show at least all the

  11577. unambiguous top tail callers and all the unambiguous bottom tail calees,

  11578. if any.

  11579. 

  11580. 'set debug entry-values'

  11581.      When set to on, enables printing of analysis messages for both

  11582.      frame argument values at function entry and tail calls.  It will

  11583.      show all the possible valid tail calls code paths it has

  11584.      considered.  It will also print the intersection of them with the

  11585.      final unambiguous (possibly partial or even empty) code path

  11586.      result.

  11587. 

  11588. 'show debug entry-values'

  11589.      Show the current state of analysis messages printing for both frame

  11590.      argument values at function entry and tail calls.

  11591. 

  11592.    The analysis messages for tail calls can for example show why the

  11593. virtual tail call frame for function 'c' has not been recognized (due to

  11594. the indirect reference by variable 'x'):

  11595. 

  11596.      static void __attribute__((noinline, noclone)) c (void);

  11597.      void (*x) (void) = c;

  11598.      static void __attribute__((noinline, noclone)) a (void) { x++; }

  11599.      static void __attribute__((noinline, noclone)) c (void) { a (); }

  11600.      int main (void) { x (); return 0; }

  11601. 

  11602.      Breakpoint 1, DW_OP_entry_value resolving cannot find

  11603.      DW_TAG_call_site 0x40039a in main

  11604.      a () at t.c:3

  11605.      3	static void __attribute__((noinline, noclone)) a (void) { x++; }

  11606.      (gdb) bt

  11607.      #0  a () at t.c:3

  11608.      #1  0x000000000040039a in main () at t.c:5

  11609. 

  11610.    Another possibility is an ambiguous virtual tail call frames

  11611. resolution:

  11612. 

  11613.      int i;

  11614.      static void __attribute__((noinline, noclone)) f (void) { i++; }

  11615.      static void __attribute__((noinline, noclone)) e (void) { f (); }

  11616.      static void __attribute__((noinline, noclone)) d (void) { f (); }

  11617.      static void __attribute__((noinline, noclone)) c (void) { d (); }

  11618.      static void __attribute__((noinline, noclone)) b (void)

  11619.      { if (i) c (); else e (); }

  11620.      static void __attribute__((noinline, noclone)) a (void) { b (); }

  11621.      int main (void) { a (); return 0; }

  11622. 

  11623.      tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)

  11624.      tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)

  11625.      tailcall: reduced: 0x4004d2(a) |

  11626.      (gdb) bt

  11627.      #0  f () at t.c:2

  11628.      #1  0x00000000004004d2 in a () at t.c:8

  11629.      #2  0x0000000000400395 in main () at t.c:9

  11630. 

  11631.    Frames #0 and #2 are real, #1 is a virtual tail call frame.  The code

  11632. can have possible execution paths 'main->a->b->c->d->f' or

  11633. 'main->a->b->e->f', GDB cannot find which one from the inferior state.

  11634. 

  11635.    'initial:' state shows some random possible calling sequence GDB has

  11636. found.  It then finds another possible calling sequence - that one is

  11637. prefixed by 'compare:'.  The non-ambiguous intersection of these two is

  11638. printed as the 'reduced:' calling sequence.  That one could have many

  11639. further 'compare:' and 'reduced:' statements as long as there remain any

  11640. non-ambiguous sequence entries.

  11641. 

  11642.    For the frame of function 'b' in both cases there are different

  11643. possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame

  11644. is also ambiguous.  The only non-ambiguous frame is the one for function

  11645. 'a', therefore this one is displayed to the user while the ambiguous

  11646. frames are omitted.

  11647. 

  11648.    There can be also reasons why printing of frame argument values at

  11649. function entry may fail:

  11650. 

  11651.      int v;

  11652.      static void __attribute__((noinline, noclone)) c (int i) { v++; }

  11653.      static void __attribute__((noinline, noclone)) a (int i);

  11654.      static void __attribute__((noinline, noclone)) b (int i) { a (i); }

  11655.      static void __attribute__((noinline, noclone)) a (int i)

  11656.      { if (i) b (i - 1); else c (0); }

  11657.      int main (void) { a (5); return 0; }

  11658. 

  11659.      (gdb) bt

  11660.      #0  c (i=i@entry=0) at t.c:2

  11661.      #1  0x0000000000400428 in a (DW_OP_entry_value resolving has found

  11662.      function "a" at 0x400420 can call itself via tail calls

  11663.      i=<optimized out>) at t.c:6

  11664.      #2  0x000000000040036e in main () at t.c:7

  11665. 

  11666.    GDB cannot find out from the inferior state if and how many times did

  11667. function 'a' call itself (via function 'b') as these calls would be tail

  11668. calls.  Such tail calls would modify the 'i' variable, therefore GDB

  11669. cannot be sure the value it knows would be right - GDB prints

  11670. '<optimized out>' instead.

  11671. 

  11672. 

  11673. File: gdb.info,  Node: Macros,  Next: Tracepoints,  Prev: Optimized Code,  Up: Top

  11674. 

  11675. 12 C Preprocessor Macros

  11676. ************************

  11677. 

  11678. Some languages, such as C and C++, provide a way to define and invoke

  11679. "preprocessor macros" which expand into strings of tokens.  GDB can

  11680. evaluate expressions containing macro invocations, show the result of

  11681. macro expansion, and show a macro's definition, including where it was

  11682. defined.

  11683. 

  11684.    You may need to compile your program specially to provide GDB with

  11685. information about preprocessor macros.  Most compilers do not include

  11686. macros in their debugging information, even when you compile with the

  11687. '-g' flag.  *Note Compilation::.

  11688. 

  11689.    A program may define a macro at one point, remove that definition

  11690. later, and then provide a different definition after that.  Thus, at

  11691. different points in the program, a macro may have different definitions,

  11692. or have no definition at all.  If there is a current stack frame, GDB

  11693. uses the macros in scope at that frame's source code line.  Otherwise,

  11694. GDB uses the macros in scope at the current listing location; see *note

  11695. List::.

  11696. 

  11697.    Whenever GDB evaluates an expression, it always expands any macro

  11698. invocations present in the expression.  GDB also provides the following

  11699. commands for working with macros explicitly.

  11700. 

  11701. 'macro expand EXPRESSION'

  11702. 'macro exp EXPRESSION'

  11703.      Show the results of expanding all preprocessor macro invocations in

  11704.      EXPRESSION.  Since GDB simply expands macros, but does not parse

  11705.      the result, EXPRESSION need not be a valid expression; it can be

  11706.      any string of tokens.

  11707. 

  11708. 'macro expand-once EXPRESSION'

  11709. 'macro exp1 EXPRESSION'

  11710.      (This command is not yet implemented.)  Show the results of

  11711.      expanding those preprocessor macro invocations that appear

  11712.      explicitly in EXPRESSION.  Macro invocations appearing in that

  11713.      expansion are left unchanged.  This command allows you to see the

  11714.      effect of a particular macro more clearly, without being confused

  11715.      by further expansions.  Since GDB simply expands macros, but does

  11716.      not parse the result, EXPRESSION need not be a valid expression; it

  11717.      can be any string of tokens.

  11718. 

  11719. 'info macro [-a|-all] [--] MACRO'

  11720.      Show the current definition or all definitions of the named MACRO,

  11721.      and describe the source location or compiler command-line where

  11722.      that definition was established.  The optional double dash is to

  11723.      signify the end of argument processing and the beginning of MACRO

  11724.      for non C-like macros where the macro may begin with a hyphen.

  11725. 

  11726. 'info macros LOCATION'

  11727.      Show all macro definitions that are in effect at the location

  11728.      specified by LOCATION, and describe the source location or compiler

  11729.      command-line where those definitions were established.

  11730. 

  11731. 'macro define MACRO REPLACEMENT-LIST'

  11732. 'macro define MACRO(ARGLIST) REPLACEMENT-LIST'

  11733.      Introduce a definition for a preprocessor macro named MACRO,

  11734.      invocations of which are replaced by the tokens given in

  11735.      REPLACEMENT-LIST.  The first form of this command defines an

  11736.      "object-like" macro, which takes no arguments; the second form

  11737.      defines a "function-like" macro, which takes the arguments given in

  11738.      ARGLIST.

  11739. 

  11740.      A definition introduced by this command is in scope in every

  11741.      expression evaluated in GDB, until it is removed with the 'macro

  11742.      undef' command, described below.  The definition overrides all

  11743.      definitions for MACRO present in the program being debugged, as

  11744.      well as any previous user-supplied definition.

  11745. 

  11746. 'macro undef MACRO'

  11747.      Remove any user-supplied definition for the macro named MACRO.

  11748.      This command only affects definitions provided with the 'macro

  11749.      define' command, described above; it cannot remove definitions

  11750.      present in the program being debugged.

  11751. 

  11752. 'macro list'

  11753.      List all the macros defined using the 'macro define' command.

  11754. 

  11755.    Here is a transcript showing the above commands in action.  First, we

  11756. show our source files:

  11757. 

  11758.      $ cat sample.c

  11759.      #include <stdio.h>

  11760.      #include "sample.h"

  11761. 

  11762.      #define M 42

  11763.      #define ADD(x) (M + x)

  11764. 

  11765.      main ()

  11766.      {

  11767.      #define N 28

  11768.        printf ("Hello, world!\n");

  11769.      #undef N

  11770.        printf ("We're so creative.\n");

  11771.      #define N 1729

  11772.        printf ("Goodbye, world!\n");

  11773.      }

  11774.      $ cat sample.h

  11775.      #define Q <

  11776.      $

  11777. 

  11778.    Now, we compile the program using the GNU C compiler, GCC.  We pass

  11779. the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes

  11780. information about preprocessor macros in the debugging information.

  11781. 

  11782.      $ gcc -gdwarf-2 -g3 sample.c -o sample

  11783.      $

  11784. 

  11785.    Now, we start GDB on our sample program:

  11786. 

  11787.      $ gdb -nw sample

  11788.      GNU gdb 2002-05-06-cvs

  11789.      Copyright 2002 Free Software Foundation, Inc.

  11790.      GDB is free software, ...

  11791.      (gdb)

  11792. 

  11793.    We can expand macros and examine their definitions, even when the

  11794. program is not running.  GDB uses the current listing position to decide

  11795. which macro definitions are in scope:

  11796. 

  11797.      (gdb) list main

  11798.      3

  11799.      4       #define M 42

  11800.      5       #define ADD(x) (M + x)

  11801.      6

  11802.      7       main ()

  11803.      8       {

  11804.      9       #define N 28

  11805.      10        printf ("Hello, world!\n");

  11806.      11      #undef N

  11807.      12        printf ("We're so creative.\n");

  11808.      (gdb) info macro ADD

  11809.      Defined at /home/jimb/gdb/macros/play/sample.c:5

  11810.      #define ADD(x) (M + x)

  11811.      (gdb) info macro Q

  11812.      Defined at /home/jimb/gdb/macros/play/sample.h:1

  11813.        included at /home/jimb/gdb/macros/play/sample.c:2

  11814.      #define Q <

  11815.      (gdb) macro expand ADD(1)

  11816.      expands to: (42 + 1)

  11817.      (gdb) macro expand-once ADD(1)

  11818.      expands to: once (M + 1)

  11819.      (gdb)

  11820. 

  11821.    In the example above, note that 'macro expand-once' expands only the

  11822. macro invocation explicit in the original text -- the invocation of

  11823. 'ADD' -- but does not expand the invocation of the macro 'M', which was

  11824. introduced by 'ADD'.

  11825. 

  11826.    Once the program is running, GDB uses the macro definitions in force

  11827. at the source line of the current stack frame:

  11828. 

  11829.      (gdb) break main

  11830.      Breakpoint 1 at 0x8048370: file sample.c, line 10.

  11831.      (gdb) run

  11832.      Starting program: /home/jimb/gdb/macros/play/sample

  11833. 

  11834.      Breakpoint 1, main () at sample.c:10

  11835.      10        printf ("Hello, world!\n");

  11836.      (gdb)

  11837. 

  11838.    At line 10, the definition of the macro 'N' at line 9 is in force:

  11839. 

  11840.      (gdb) info macro N

  11841.      Defined at /home/jimb/gdb/macros/play/sample.c:9

  11842.      #define N 28

  11843.      (gdb) macro expand N Q M

  11844.      expands to: 28 < 42

  11845.      (gdb) print N Q M

  11846.      $1 = 1

  11847.      (gdb)

  11848. 

  11849.    As we step over directives that remove 'N''s definition, and then

  11850. give it a new definition, GDB finds the definition (or lack thereof) in

  11851. force at each point:

  11852. 

  11853.      (gdb) next

  11854.      Hello, world!

  11855.      12        printf ("We're so creative.\n");

  11856.      (gdb) info macro N

  11857.      The symbol `N' has no definition as a C/C++ preprocessor macro

  11858.      at /home/jimb/gdb/macros/play/sample.c:12

  11859.      (gdb) next

  11860.      We're so creative.

  11861.      14        printf ("Goodbye, world!\n");

  11862.      (gdb) info macro N

  11863.      Defined at /home/jimb/gdb/macros/play/sample.c:13

  11864.      #define N 1729

  11865.      (gdb) macro expand N Q M

  11866.      expands to: 1729 < 42

  11867.      (gdb) print N Q M

  11868.      $2 = 0

  11869.      (gdb)

  11870. 

  11871.    In addition to source files, macros can be defined on the compilation

  11872. command line using the '-DNAME=VALUE' syntax.  For macros defined in

  11873. such a way, GDB displays the location of their definition as line zero

  11874. of the source file submitted to the compiler.

  11875. 

  11876.      (gdb) info macro __STDC__

  11877.      Defined at /home/jimb/gdb/macros/play/sample.c:0

  11878.      -D__STDC__=1

  11879.      (gdb)

  11880. 

  11881.    ---------- Footnotes ----------

  11882. 

  11883.    (1) This is the minimum.  Recent versions of GCC support '-gdwarf-3'

  11884. and '-gdwarf-4'; we recommend always choosing the most recent version of

  11885. DWARF.

  11886. 

  11887. 

  11888. File: gdb.info,  Node: Tracepoints,  Next: Overlays,  Prev: Macros,  Up: Top

  11889. 

  11890. 13 Tracepoints

  11891. **************

  11892. 

  11893. In some applications, it is not feasible for the debugger to interrupt

  11894. the program's execution long enough for the developer to learn anything

  11895. helpful about its behavior.  If the program's correctness depends on its

  11896. real-time behavior, delays introduced by a debugger might cause the

  11897. program to change its behavior drastically, or perhaps fail, even when

  11898. the code itself is correct.  It is useful to be able to observe the

  11899. program's behavior without interrupting it.

  11900. 

  11901.    Using GDB's 'trace' and 'collect' commands, you can specify locations

  11902. in the program, called "tracepoints", and arbitrary expressions to

  11903. evaluate when those tracepoints are reached.  Later, using the 'tfind'

  11904. command, you can examine the values those expressions had when the

  11905. program hit the tracepoints.  The expressions may also denote objects in

  11906. memory--structures or arrays, for example--whose values GDB should

  11907. record; while visiting a particular tracepoint, you may inspect those

  11908. objects as if they were in memory at that moment.  However, because GDB

  11909. records these values without interacting with you, it can do so quickly

  11910. and unobtrusively, hopefully not disturbing the program's behavior.

  11911. 

  11912.    The tracepoint facility is currently available only for remote

  11913. targets.  *Note Targets::.  In addition, your remote target must know

  11914. how to collect trace data.  This functionality is implemented in the

  11915. remote stub; however, none of the stubs distributed with GDB support

  11916. tracepoints as of this writing.  The format of the remote packets used

  11917. to implement tracepoints are described in *note Tracepoint Packets::.

  11918. 

  11919.    It is also possible to get trace data from a file, in a manner

  11920. reminiscent of corefiles; you specify the filename, and use 'tfind' to

  11921. search through the file.  *Note Trace Files::, for more details.

  11922. 

  11923.    This chapter describes the tracepoint commands and features.

  11924. 

  11925. * Menu:

  11926. 

  11927. * Set Tracepoints::

  11928. * Analyze Collected Data::

  11929. * Tracepoint Variables::

  11930. * Trace Files::

  11931. 

  11932. 

  11933. File: gdb.info,  Node: Set Tracepoints,  Next: Analyze Collected Data,  Up: Tracepoints

  11934. 

  11935. 13.1 Commands to Set Tracepoints

  11936. ================================

  11937. 

  11938. Before running such a "trace experiment", an arbitrary number of

  11939. tracepoints can be set.  A tracepoint is actually a special type of

  11940. breakpoint (*note Set Breaks::), so you can manipulate it using standard

  11941. breakpoint commands.  For instance, as with breakpoints, tracepoint

  11942. numbers are successive integers starting from one, and many of the

  11943. commands associated with tracepoints take the tracepoint number as their

  11944. argument, to identify which tracepoint to work on.

  11945. 

  11946.    For each tracepoint, you can specify, in advance, some arbitrary set

  11947. of data that you want the target to collect in the trace buffer when it

  11948. hits that tracepoint.  The collected data can include registers, local

  11949. variables, or global data.  Later, you can use GDB commands to examine

  11950. the values these data had at the time the tracepoint was hit.

  11951. 

  11952.    Tracepoints do not support every breakpoint feature.  Ignore counts

  11953. on tracepoints have no effect, and tracepoints cannot run GDB commands

  11954. when they are hit.  Tracepoints may not be thread-specific either.

  11955. 

  11956.    Some targets may support "fast tracepoints", which are inserted in a

  11957. different way (such as with a jump instead of a trap), that is faster

  11958. but possibly restricted in where they may be installed.

  11959. 

  11960.    Regular and fast tracepoints are dynamic tracing facilities, meaning

  11961. that they can be used to insert tracepoints at (almost) any location in

  11962. the target.  Some targets may also support controlling "static

  11963. tracepoints" from GDB.  With static tracing, a set of instrumentation

  11964. points, also known as "markers", are embedded in the target program, and

  11965. can be activated or deactivated by name or address.  These are usually

  11966. placed at locations which facilitate investigating what the target is

  11967. actually doing.  GDB's support for static tracing includes being able to

  11968. list instrumentation points, and attach them with GDB defined high level

  11969. tracepoints that expose the whole range of convenience of GDB's

  11970. tracepoints support.  Namely, support for collecting registers values

  11971. and values of global or local (to the instrumentation point) variables;

  11972. tracepoint conditions and trace state variables.  The act of installing

  11973. a GDB static tracepoint on an instrumentation point, or marker, is

  11974. referred to as "probing" a static tracepoint marker.

  11975. 

  11976.    'gdbserver' supports tracepoints on some target systems.  *Note

  11977. Tracepoints support in 'gdbserver': Server.

  11978. 

  11979.    This section describes commands to set tracepoints and associated

  11980. conditions and actions.

  11981. 

  11982. * Menu:

  11983. 

  11984. * Create and Delete Tracepoints::

  11985. * Enable and Disable Tracepoints::

  11986. * Tracepoint Passcounts::

  11987. * Tracepoint Conditions::

  11988. * Trace State Variables::

  11989. * Tracepoint Actions::

  11990. * Listing Tracepoints::

  11991. * Listing Static Tracepoint Markers::

  11992. * Starting and Stopping Trace Experiments::

  11993. * Tracepoint Restrictions::

  11994. 

  11995. 

  11996. File: gdb.info,  Node: Create and Delete Tracepoints,  Next: Enable and Disable Tracepoints,  Up: Set Tracepoints

  11997. 

  11998. 13.1.1 Create and Delete Tracepoints

  11999. ------------------------------------

  12000. 

  12001. 'trace LOCATION'

  12002.      The 'trace' command is very similar to the 'break' command.  Its

  12003.      argument LOCATION can be any valid location.  *Note Specify

  12004.      Location::.  The 'trace' command defines a tracepoint, which is a

  12005.      point in the target program where the debugger will briefly stop,

  12006.      collect some data, and then allow the program to continue.  Setting

  12007.      a tracepoint or changing its actions takes effect immediately if

  12008.      the remote stub supports the 'InstallInTrace' feature (*note

  12009.      install tracepoint in tracing::).  If remote stub doesn't support

  12010.      the 'InstallInTrace' feature, all these changes don't take effect

  12011.      until the next 'tstart' command, and once a trace experiment is

  12012.      running, further changes will not have any effect until the next

  12013.      trace experiment starts.  In addition, GDB supports "pending

  12014.      tracepoints"--tracepoints whose address is not yet resolved.  (This

  12015.      is similar to pending breakpoints.)  Pending tracepoints are not

  12016.      downloaded to the target and not installed until they are resolved.

  12017.      The resolution of pending tracepoints requires GDB support--when

  12018.      debugging with the remote target, and GDB disconnects from the

  12019.      remote stub (*note disconnected tracing::), pending tracepoints can

  12020.      not be resolved (and downloaded to the remote stub) while GDB is

  12021.      disconnected.

  12022. 

  12023.      Here are some examples of using the 'trace' command:

  12024. 

  12025.           (gdb) trace foo.c:121    // a source file and line number

  12026. 

  12027.           (gdb) trace +2           // 2 lines forward

  12028. 

  12029.           (gdb) trace my_function  // first source line of function

  12030. 

  12031.           (gdb) trace *my_function // EXACT start address of function

  12032. 

  12033.           (gdb) trace *0x2117c4    // an address

  12034. 

  12035.      You can abbreviate 'trace' as 'tr'.

  12036. 

  12037. 'trace LOCATION if COND'

  12038.      Set a tracepoint with condition COND; evaluate the expression COND

  12039.      each time the tracepoint is reached, and collect data only if the

  12040.      value is nonzero--that is, if COND evaluates as true.  *Note

  12041.      Tracepoint Conditions: Tracepoint Conditions, for more information

  12042.      on tracepoint conditions.

  12043. 

  12044. 'ftrace LOCATION [ if COND ]'

  12045.      The 'ftrace' command sets a fast tracepoint.  For targets that

  12046.      support them, fast tracepoints will use a more efficient but

  12047.      possibly less general technique to trigger data collection, such as

  12048.      a jump instruction instead of a trap, or some sort of hardware

  12049.      support.  It may not be possible to create a fast tracepoint at the

  12050.      desired location, in which case the command will exit with an

  12051.      explanatory message.

  12052. 

  12053.      GDB handles arguments to 'ftrace' exactly as for 'trace'.

  12054. 

  12055.      On 32-bit x86-architecture systems, fast tracepoints normally need

  12056.      to be placed at an instruction that is 5 bytes or longer, but can

  12057.      be placed at 4-byte instructions if the low 64K of memory of the

  12058.      target program is available to install trampolines.  Some Unix-type

  12059.      systems, such as GNU/Linux, exclude low addresses from the

  12060.      program's address space; but for instance with the Linux kernel it

  12061.      is possible to let GDB use this area by doing a 'sysctl' command to

  12062.      set the 'mmap_min_addr' kernel parameter, as in

  12063. 

  12064.           sudo sysctl -w vm.mmap_min_addr=32768

  12065. 

  12066.      which sets the low address to 32K, which leaves plenty of room for

  12067.      trampolines.  The minimum address should be set to a page boundary.

  12068. 

  12069. 'strace LOCATION [ if COND ]'

  12070.      The 'strace' command sets a static tracepoint.  For targets that

  12071.      support it, setting a static tracepoint probes a static

  12072.      instrumentation point, or marker, found at LOCATION.  It may not be

  12073.      possible to set a static tracepoint at the desired location, in

  12074.      which case the command will exit with an explanatory message.

  12075. 

  12076.      GDB handles arguments to 'strace' exactly as for 'trace', with the

  12077.      addition that the user can also specify '-m MARKER' as LOCATION.

  12078.      This probes the marker identified by the MARKER string identifier.

  12079.      This identifier depends on the static tracepoint backend library

  12080.      your program is using.  You can find all the marker identifiers in

  12081.      the 'ID' field of the 'info static-tracepoint-markers' command

  12082.      output.  *Note Listing Static Tracepoint Markers: Listing Static

  12083.      Tracepoint Markers.  For example, in the following small program

  12084.      using the UST tracing engine:

  12085. 

  12086.           main ()

  12087.           {

  12088.             trace_mark(ust, bar33, "str %s", "FOOBAZ");

  12089.           }

  12090. 

  12091.      the marker id is composed of joining the first two arguments to the

  12092.      'trace_mark' call with a slash, which translates to:

  12093. 

  12094.           (gdb) info static-tracepoint-markers

  12095.           Cnt Enb ID         Address            What

  12096.           1   n   ust/bar33  0x0000000000400ddc in main at stexample.c:22

  12097.                    Data: "str %s"

  12098.           [etc...]

  12099. 

  12100.      so you may probe the marker above with:

  12101. 

  12102.           (gdb) strace -m ust/bar33

  12103. 

  12104.      Static tracepoints accept an extra collect action -- 'collect

  12105.      $_sdata'.  This collects arbitrary user data passed in the probe

  12106.      point call to the tracing library.  In the UST example above,

  12107.      you'll see that the third argument to 'trace_mark' is a printf-like

  12108.      format string.  The user data is then the result of running that

  12109.      formatting string against the following arguments.  Note that 'info

  12110.      static-tracepoint-markers' command output lists that format string

  12111.      in the 'Data:' field.

  12112. 

  12113.      You can inspect this data when analyzing the trace buffer, by

  12114.      printing the $_sdata variable like any other variable available to

  12115.      GDB.  *Note Tracepoint Action Lists: Tracepoint Actions.

  12116. 

  12117.      The convenience variable '$tpnum' records the tracepoint number of

  12118.      the most recently set tracepoint.

  12119. 

  12120. 'delete tracepoint [NUM]'

  12121.      Permanently delete one or more tracepoints.  With no argument, the

  12122.      default is to delete all tracepoints.  Note that the regular

  12123.      'delete' command can remove tracepoints also.

  12124. 

  12125.      Examples:

  12126. 

  12127.           (gdb) delete trace 1 2 3 // remove three tracepoints

  12128. 

  12129.           (gdb) delete trace       // remove all tracepoints

  12130. 

  12131.      You can abbreviate this command as 'del tr'.

  12132. 

  12133. 

  12134. File: gdb.info,  Node: Enable and Disable Tracepoints,  Next: Tracepoint Passcounts,  Prev: Create and Delete Tracepoints,  Up: Set Tracepoints

  12135. 

  12136. 13.1.2 Enable and Disable Tracepoints

  12137. -------------------------------------

  12138. 

  12139. These commands are deprecated; they are equivalent to plain 'disable'

  12140. and 'enable'.

  12141. 

  12142. 'disable tracepoint [NUM]'

  12143.      Disable tracepoint NUM, or all tracepoints if no argument NUM is

  12144.      given.  A disabled tracepoint will have no effect during a trace

  12145.      experiment, but it is not forgotten.  You can re-enable a disabled

  12146.      tracepoint using the 'enable tracepoint' command.  If the command

  12147.      is issued during a trace experiment and the debug target has

  12148.      support for disabling tracepoints during a trace experiment, then

  12149.      the change will be effective immediately.  Otherwise, it will be

  12150.      applied to the next trace experiment.

  12151. 

  12152. 'enable tracepoint [NUM]'

  12153.      Enable tracepoint NUM, or all tracepoints.  If this command is

  12154.      issued during a trace experiment and the debug target supports

  12155.      enabling tracepoints during a trace experiment, then the enabled

  12156.      tracepoints will become effective immediately.  Otherwise, they

  12157.      will become effective the next time a trace experiment is run.

  12158. 

  12159. 

  12160. File: gdb.info,  Node: Tracepoint Passcounts,  Next: Tracepoint Conditions,  Prev: Enable and Disable Tracepoints,  Up: Set Tracepoints

  12161. 

  12162. 13.1.3 Tracepoint Passcounts

  12163. ----------------------------

  12164. 

  12165. 'passcount [N [NUM]]'

  12166.      Set the "passcount" of a tracepoint.  The passcount is a way to

  12167.      automatically stop a trace experiment.  If a tracepoint's passcount

  12168.      is N, then the trace experiment will be automatically stopped on

  12169.      the N'th time that tracepoint is hit.  If the tracepoint number NUM

  12170.      is not specified, the 'passcount' command sets the passcount of the

  12171.      most recently defined tracepoint.  If no passcount is given, the

  12172.      trace experiment will run until stopped explicitly by the user.

  12173. 

  12174.      Examples:

  12175. 

  12176.           (gdb) passcount 5 2 // Stop on the 5th execution of

  12177.                                         // tracepoint 2

  12178. 

  12179.           (gdb) passcount 12  // Stop on the 12th execution of the

  12180.                                         // most recently defined tracepoint.

  12181.           (gdb) trace foo

  12182.           (gdb) pass 3

  12183.           (gdb) trace bar

  12184.           (gdb) pass 2

  12185.           (gdb) trace baz

  12186.           (gdb) pass 1        // Stop tracing when foo has been

  12187.                                          // executed 3 times OR when bar has

  12188.                                          // been executed 2 times

  12189.                                          // OR when baz has been executed 1 time.

  12190. 

  12191. 

  12192. File: gdb.info,  Node: Tracepoint Conditions,  Next: Trace State Variables,  Prev: Tracepoint Passcounts,  Up: Set Tracepoints

  12193. 

  12194. 13.1.4 Tracepoint Conditions

  12195. ----------------------------

  12196. 

  12197. The simplest sort of tracepoint collects data every time your program

  12198. reaches a specified place.  You can also specify a "condition" for a

  12199. tracepoint.  A condition is just a Boolean expression in your

  12200. programming language (*note Expressions: Expressions.).  A tracepoint

  12201. with a condition evaluates the expression each time your program reaches

  12202. it, and data collection happens only if the condition is true.

  12203. 

  12204.    Tracepoint conditions can be specified when a tracepoint is set, by

  12205. using 'if' in the arguments to the 'trace' command.  *Note Setting

  12206. Tracepoints: Create and Delete Tracepoints.  They can also be set or

  12207. changed at any time with the 'condition' command, just as with

  12208. breakpoints.

  12209. 

  12210.    Unlike breakpoint conditions, GDB does not actually evaluate the

  12211. conditional expression itself.  Instead, GDB encodes the expression into

  12212. an agent expression (*note Agent Expressions::) suitable for execution

  12213. on the target, independently of GDB.  Global variables become raw memory

  12214. locations, locals become stack accesses, and so forth.

  12215. 

  12216.    For instance, suppose you have a function that is usually called

  12217. frequently, but should not be called after an error has occurred.  You

  12218. could use the following tracepoint command to collect data about calls

  12219. of that function that happen while the error code is propagating through

  12220. the program; an unconditional tracepoint could end up collecting

  12221. thousands of useless trace frames that you would have to search through.

  12222. 

  12223.      (gdb) trace normal_operation if errcode > 0

  12224. 

  12225. 

  12226. File: gdb.info,  Node: Trace State Variables,  Next: Tracepoint Actions,  Prev: Tracepoint Conditions,  Up: Set Tracepoints

  12227. 

  12228. 13.1.5 Trace State Variables

  12229. ----------------------------

  12230. 

  12231. A "trace state variable" is a special type of variable that is created

  12232. and managed by target-side code.  The syntax is the same as that for

  12233. GDB's convenience variables (a string prefixed with "$"), but they are

  12234. stored on the target.  They must be created explicitly, using a

  12235. 'tvariable' command.  They are always 64-bit signed integers.

  12236. 

  12237.    Trace state variables are remembered by GDB, and downloaded to the

  12238. target along with tracepoint information when the trace experiment

  12239. starts.  There are no intrinsic limits on the number of trace state

  12240. variables, beyond memory limitations of the target.

  12241. 

  12242.    Although trace state variables are managed by the target, you can use

  12243. them in print commands and expressions as if they were convenience

  12244. variables; GDB will get the current value from the target while the

  12245. trace experiment is running.  Trace state variables share the same

  12246. namespace as other "$" variables, which means that you cannot have trace

  12247. state variables with names like '$23' or '$pc', nor can you have a trace

  12248. state variable and a convenience variable with the same name.

  12249. 

  12250. 'tvariable $NAME [ = EXPRESSION ]'

  12251.      The 'tvariable' command creates a new trace state variable named

  12252.      '$NAME', and optionally gives it an initial value of EXPRESSION.

  12253.      The EXPRESSION is evaluated when this command is entered; the

  12254.      result will be converted to an integer if possible, otherwise GDB

  12255.      will report an error.  A subsequent 'tvariable' command specifying

  12256.      the same name does not create a variable, but instead assigns the

  12257.      supplied initial value to the existing variable of that name,

  12258.      overwriting any previous initial value.  The default initial value

  12259.      is 0.

  12260. 

  12261. 'info tvariables'

  12262.      List all the trace state variables along with their initial values.

  12263.      Their current values may also be displayed, if the trace experiment

  12264.      is currently running.

  12265. 

  12266. 'delete tvariable [ $NAME ... ]'

  12267.      Delete the given trace state variables, or all of them if no

  12268.      arguments are specified.

  12269. 

  12270. 

  12271. File: gdb.info,  Node: Tracepoint Actions,  Next: Listing Tracepoints,  Prev: Trace State Variables,  Up: Set Tracepoints

  12272. 

  12273. 13.1.6 Tracepoint Action Lists

  12274. ------------------------------

  12275. 

  12276. 'actions [NUM]'

  12277.      This command will prompt for a list of actions to be taken when the

  12278.      tracepoint is hit.  If the tracepoint number NUM is not specified,

  12279.      this command sets the actions for the one that was most recently

  12280.      defined (so that you can define a tracepoint and then say 'actions'

  12281.      without bothering about its number).  You specify the actions

  12282.      themselves on the following lines, one action at a time, and

  12283.      terminate the actions list with a line containing just 'end'.  So

  12284.      far, the only defined actions are 'collect', 'teval', and

  12285.      'while-stepping'.

  12286. 

  12287.      'actions' is actually equivalent to 'commands' (*note Breakpoint

  12288.      Command Lists: Break Commands.), except that only the defined

  12289.      actions are allowed; any other GDB command is rejected.

  12290. 

  12291.      To remove all actions from a tracepoint, type 'actions NUM' and

  12292.      follow it immediately with 'end'.

  12293. 

  12294.           (gdb) collect DATA // collect some data

  12295. 

  12296.           (gdb) while-stepping 5 // single-step 5 times, collect data

  12297. 

  12298.           (gdb) end              // signals the end of actions.

  12299. 

  12300.      In the following example, the action list begins with 'collect'

  12301.      commands indicating the things to be collected when the tracepoint

  12302.      is hit.  Then, in order to single-step and collect additional data

  12303.      following the tracepoint, a 'while-stepping' command is used,

  12304.      followed by the list of things to be collected after each step in a

  12305.      sequence of single steps.  The 'while-stepping' command is

  12306.      terminated by its own separate 'end' command.  Lastly, the action

  12307.      list is terminated by an 'end' command.

  12308. 

  12309.           (gdb) trace foo

  12310.           (gdb) actions

  12311.           Enter actions for tracepoint 1, one per line:

  12312.           > collect bar,baz

  12313.           > collect $regs

  12314.           > while-stepping 12

  12315.             > collect $pc, arr[i]

  12316.             > end

  12317.           end

  12318. 

  12319. 'collect[/MODS] EXPR1, EXPR2, ...'

  12320.      Collect values of the given expressions when the tracepoint is hit.

  12321.      This command accepts a comma-separated list of any valid

  12322.      expressions.  In addition to global, static, or local variables,

  12323.      the following special arguments are supported:

  12324. 

  12325.      '$regs'

  12326.           Collect all registers.

  12327. 

  12328.      '$args'

  12329.           Collect all function arguments.

  12330. 

  12331.      '$locals'

  12332.           Collect all local variables.

  12333. 

  12334.      '$_ret'

  12335.           Collect the return address.  This is helpful if you want to

  12336.           see more of a backtrace.

  12337. 

  12338.           _Note:_ The return address location can not always be reliably

  12339.           determined up front, and the wrong address / registers may end

  12340.           up collected instead.  On some architectures the reliability

  12341.           is higher for tracepoints at function entry, while on others

  12342.           it's the opposite.  When this happens, backtracing will stop

  12343.           because the return address is found unavailable (unless

  12344.           another collect rule happened to match it).

  12345. 

  12346.      '$_probe_argc'

  12347.           Collects the number of arguments from the static probe at

  12348.           which the tracepoint is located.  *Note Static Probe Points::.

  12349. 

  12350.      '$_probe_argN'

  12351.           N is an integer between 0 and 11.  Collects the Nth argument

  12352.           from the static probe at which the tracepoint is located.

  12353.           *Note Static Probe Points::.

  12354. 

  12355.      '$_sdata'

  12356.           Collect static tracepoint marker specific data.  Only

  12357.           available for static tracepoints.  *Note Tracepoint Action

  12358.           Lists: Tracepoint Actions.  On the UST static tracepoints

  12359.           library backend, an instrumentation point resembles a 'printf'

  12360.           function call.  The tracing library is able to collect user

  12361.           specified data formatted to a character string using the

  12362.           format provided by the programmer that instrumented the

  12363.           program.  Other backends have similar mechanisms.  Here's an

  12364.           example of a UST marker call:

  12365. 

  12366.                 const char master_name[] = "$your_name";

  12367.                 trace_mark(channel1, marker1, "hello %s", master_name)

  12368. 

  12369.           In this case, collecting '$_sdata' collects the string 'hello

  12370.           $yourname'.  When analyzing the trace buffer, you can inspect

  12371.           '$_sdata' like any other variable available to GDB.

  12372. 

  12373.      You can give several consecutive 'collect' commands, each one with

  12374.      a single argument, or one 'collect' command with several arguments

  12375.      separated by commas; the effect is the same.

  12376. 

  12377.      The optional MODS changes the usual handling of the arguments.  's'

  12378.      requests that pointers to chars be handled as strings, in

  12379.      particular collecting the contents of the memory being pointed at,

  12380.      up to the first zero.  The upper bound is by default the value of

  12381.      the 'print elements' variable; if 's' is followed by a decimal

  12382.      number, that is the upper bound instead.  So for instance

  12383.      'collect/s25 mystr' collects as many as 25 characters at 'mystr'.

  12384. 

  12385.      The command 'info scope' (*note info scope: Symbols.) is

  12386.      particularly useful for figuring out what data to collect.

  12387. 

  12388. 'teval EXPR1, EXPR2, ...'

  12389.      Evaluate the given expressions when the tracepoint is hit.  This

  12390.      command accepts a comma-separated list of expressions.  The results

  12391.      are discarded, so this is mainly useful for assigning values to

  12392.      trace state variables (*note Trace State Variables::) without

  12393.      adding those values to the trace buffer, as would be the case if

  12394.      the 'collect' action were used.

  12395. 

  12396. 'while-stepping N'

  12397.      Perform N single-step instruction traces after the tracepoint,

  12398.      collecting new data after each step.  The 'while-stepping' command

  12399.      is followed by the list of what to collect while stepping (followed

  12400.      by its own 'end' command):

  12401. 

  12402.           > while-stepping 12

  12403.             > collect $regs, myglobal

  12404.             > end

  12405.           >

  12406. 

  12407.      Note that '$pc' is not automatically collected by 'while-stepping';

  12408.      you need to explicitly collect that register if you need it.  You

  12409.      may abbreviate 'while-stepping' as 'ws' or 'stepping'.

  12410. 

  12411. 'set default-collect EXPR1, EXPR2, ...'

  12412.      This variable is a list of expressions to collect at each

  12413.      tracepoint hit.  It is effectively an additional 'collect' action

  12414.      prepended to every tracepoint action list.  The expressions are

  12415.      parsed individually for each tracepoint, so for instance a variable

  12416.      named 'xyz' may be interpreted as a global for one tracepoint, and

  12417.      a local for another, as appropriate to the tracepoint's location.

  12418. 

  12419. 'show default-collect'

  12420.      Show the list of expressions that are collected by default at each

  12421.      tracepoint hit.

  12422. 

  12423. 

  12424. File: gdb.info,  Node: Listing Tracepoints,  Next: Listing Static Tracepoint Markers,  Prev: Tracepoint Actions,  Up: Set Tracepoints

  12425. 

  12426. 13.1.7 Listing Tracepoints

  12427. --------------------------

  12428. 

  12429. 'info tracepoints [NUM...]'

  12430.      Display information about the tracepoint NUM.  If you don't specify

  12431.      a tracepoint number, displays information about all the tracepoints

  12432.      defined so far.  The format is similar to that used for 'info

  12433.      breakpoints'; in fact, 'info tracepoints' is the same command,

  12434.      simply restricting itself to tracepoints.

  12435. 

  12436.      A tracepoint's listing may include additional information specific

  12437.      to tracing:

  12438. 

  12439.         * its passcount as given by the 'passcount N' command

  12440. 

  12441.         * the state about installed on target of each location

  12442. 

  12443.           (gdb) info trace

  12444.           Num     Type           Disp Enb Address    What

  12445.           1       tracepoint     keep y   0x0804ab57 in foo() at main.cxx:7

  12446.                   while-stepping 20

  12447.                     collect globfoo, $regs

  12448.                   end

  12449.                   collect globfoo2

  12450.                   end

  12451.                   pass count 1200

  12452.           2       tracepoint     keep y   <MULTIPLE>

  12453.                   collect $eip

  12454.           2.1                         y     0x0804859c in func4 at change-loc.h:35

  12455.                   installed on target

  12456.           2.2                         y     0xb7ffc480 in func4 at change-loc.h:35

  12457.                   installed on target

  12458.           2.3                         y     <PENDING>  set_tracepoint

  12459.           3       tracepoint     keep y   0x080485b1 in foo at change-loc.c:29

  12460.                   not installed on target

  12461.           (gdb)

  12462. 

  12463.      This command can be abbreviated 'info tp'.

  12464. 

  12465. 

  12466. File: gdb.info,  Node: Listing Static Tracepoint Markers,  Next: Starting and Stopping Trace Experiments,  Prev: Listing Tracepoints,  Up: Set Tracepoints

  12467. 

  12468. 13.1.8 Listing Static Tracepoint Markers

  12469. ----------------------------------------

  12470. 

  12471. 'info static-tracepoint-markers'

  12472.      Display information about all static tracepoint markers defined in

  12473.      the program.

  12474. 

  12475.      For each marker, the following columns are printed:

  12476. 

  12477.      _Count_

  12478.           An incrementing counter, output to help readability.  This is

  12479.           not a stable identifier.

  12480.      _ID_

  12481.           The marker ID, as reported by the target.

  12482.      _Enabled or Disabled_

  12483.           Probed markers are tagged with 'y'.  'n' identifies marks that

  12484.           are not enabled.

  12485.      _Address_

  12486.           Where the marker is in your program, as a memory address.

  12487.      _What_

  12488.           Where the marker is in the source for your program, as a file

  12489.           and line number.  If the debug information included in the

  12490.           program does not allow GDB to locate the source of the marker,

  12491.           this column will be left blank.

  12492. 

  12493.      In addition, the following information may be printed for each

  12494.      marker:

  12495. 

  12496.      _Data_

  12497.           User data passed to the tracing library by the marker call.

  12498.           In the UST backend, this is the format string passed as

  12499.           argument to the marker call.

  12500.      _Static tracepoints probing the marker_

  12501.           The list of static tracepoints attached to the marker.

  12502. 

  12503.           (gdb) info static-tracepoint-markers

  12504.           Cnt ID         Enb Address            What

  12505.           1   ust/bar2   y   0x0000000000400e1a in main at stexample.c:25

  12506.                Data: number1 %d number2 %d

  12507.                Probed by static tracepoints: #2

  12508.           2   ust/bar33  n   0x0000000000400c87 in main at stexample.c:24

  12509.                Data: str %s

  12510.           (gdb)

  12511. 

  12512. 

  12513. File: gdb.info,  Node: Starting and Stopping Trace Experiments,  Next: Tracepoint Restrictions,  Prev: Listing Static Tracepoint Markers,  Up: Set Tracepoints

  12514. 

  12515. 13.1.9 Starting and Stopping Trace Experiments

  12516. ----------------------------------------------

  12517. 

  12518. 'tstart'

  12519.      This command starts the trace experiment, and begins collecting

  12520.      data.  It has the side effect of discarding all the data collected

  12521.      in the trace buffer during the previous trace experiment.  If any

  12522.      arguments are supplied, they are taken as a note and stored with

  12523.      the trace experiment's state.  The notes may be arbitrary text, and

  12524.      are especially useful with disconnected tracing in a multi-user

  12525.      context; the notes can explain what the trace is doing, supply user

  12526.      contact information, and so forth.

  12527. 

  12528. 'tstop'

  12529.      This command stops the trace experiment.  If any arguments are

  12530.      supplied, they are recorded with the experiment as a note.  This is

  12531.      useful if you are stopping a trace started by someone else, for

  12532.      instance if the trace is interfering with the system's behavior and

  12533.      needs to be stopped quickly.

  12534. 

  12535.      *Note*: a trace experiment and data collection may stop

  12536.      automatically if any tracepoint's passcount is reached (*note

  12537.      Tracepoint Passcounts::), or if the trace buffer becomes full.

  12538. 

  12539. 'tstatus'

  12540.      This command displays the status of the current trace data

  12541.      collection.

  12542. 

  12543.    Here is an example of the commands we described so far:

  12544. 

  12545.      (gdb) trace gdb_c_test

  12546.      (gdb) actions

  12547.      Enter actions for tracepoint #1, one per line.

  12548.      > collect $regs,$locals,$args

  12549.      > while-stepping 11

  12550.        > collect $regs

  12551.        > end

  12552.      > end

  12553.      (gdb) tstart

  12554.      	[time passes ...]

  12555.      (gdb) tstop

  12556. 

  12557.    You can choose to continue running the trace experiment even if GDB

  12558. disconnects from the target, voluntarily or involuntarily.  For commands

  12559. such as 'detach', the debugger will ask what you want to do with the

  12560. trace.  But for unexpected terminations (GDB crash, network outage), it

  12561. would be unfortunate to lose hard-won trace data, so the variable

  12562. 'disconnected-tracing' lets you decide whether the trace should continue

  12563. running without GDB.

  12564. 

  12565. 'set disconnected-tracing on'

  12566. 'set disconnected-tracing off'

  12567.      Choose whether a tracing run should continue to run if GDB has

  12568.      disconnected from the target.  Note that 'detach' or 'quit' will

  12569.      ask you directly what to do about a running trace no matter what

  12570.      this variable's setting, so the variable is mainly useful for

  12571.      handling unexpected situations, such as loss of the network.

  12572. 

  12573. 'show disconnected-tracing'

  12574.      Show the current choice for disconnected tracing.

  12575. 

  12576.    When you reconnect to the target, the trace experiment may or may not

  12577. still be running; it might have filled the trace buffer in the meantime,

  12578. or stopped for one of the other reasons.  If it is running, it will

  12579. continue after reconnection.

  12580. 

  12581.    Upon reconnection, the target will upload information about the

  12582. tracepoints in effect.  GDB will then compare that information to the

  12583. set of tracepoints currently defined, and attempt to match them up,

  12584. allowing for the possibility that the numbers may have changed due to

  12585. creation and deletion in the meantime.  If one of the target's

  12586. tracepoints does not match any in GDB, the debugger will create a new

  12587. tracepoint, so that you have a number with which to specify that

  12588. tracepoint.  This matching-up process is necessarily heuristic, and it

  12589. may result in useless tracepoints being created; you may simply delete

  12590. them if they are of no use.

  12591. 

  12592.    If your target agent supports a "circular trace buffer", then you can

  12593. run a trace experiment indefinitely without filling the trace buffer;

  12594. when space runs out, the agent deletes already-collected trace frames,

  12595. oldest first, until there is enough room to continue collecting.  This

  12596. is especially useful if your tracepoints are being hit too often, and

  12597. your trace gets terminated prematurely because the buffer is full.  To

  12598. ask for a circular trace buffer, simply set 'circular-trace-buffer' to

  12599. on.  You can set this at any time, including during tracing; if the

  12600. agent can do it, it will change buffer handling on the fly, otherwise it

  12601. will not take effect until the next run.

  12602. 

  12603. 'set circular-trace-buffer on'

  12604. 'set circular-trace-buffer off'

  12605.      Choose whether a tracing run should use a linear or circular buffer

  12606.      for trace data.  A linear buffer will not lose any trace data, but

  12607.      may fill up prematurely, while a circular buffer will discard old

  12608.      trace data, but it will have always room for the latest tracepoint

  12609.      hits.

  12610. 

  12611. 'show circular-trace-buffer'

  12612.      Show the current choice for the trace buffer.  Note that this may

  12613.      not match the agent's current buffer handling, nor is it guaranteed

  12614.      to match the setting that might have been in effect during a past

  12615.      run, for instance if you are looking at frames from a trace file.

  12616. 

  12617. 'set trace-buffer-size N'

  12618. 'set trace-buffer-size unlimited'

  12619.      Request that the target use a trace buffer of N bytes.  Not all

  12620.      targets will honor the request; they may have a compiled-in size

  12621.      for the trace buffer, or some other limitation.  Set to a value of

  12622.      'unlimited' or '-1' to let the target use whatever size it likes.

  12623.      This is also the default.

  12624. 

  12625. 'show trace-buffer-size'

  12626.      Show the current requested size for the trace buffer.  Note that

  12627.      this will only match the actual size if the target supports

  12628.      size-setting, and was able to handle the requested size.  For

  12629.      instance, if the target can only change buffer size between runs,

  12630.      this variable will not reflect the change until the next run

  12631.      starts.  Use 'tstatus' to get a report of the actual buffer size.

  12632. 

  12633. 'set trace-user TEXT'

  12634. 

  12635. 'show trace-user'

  12636. 

  12637. 'set trace-notes TEXT'

  12638.      Set the trace run's notes.

  12639. 

  12640. 'show trace-notes'

  12641.      Show the trace run's notes.

  12642. 

  12643. 'set trace-stop-notes TEXT'

  12644.      Set the trace run's stop notes.  The handling of the note is as for

  12645.      'tstop' arguments; the set command is convenient way to fix a stop

  12646.      note that is mistaken or incomplete.

  12647. 

  12648. 'show trace-stop-notes'

  12649.      Show the trace run's stop notes.

  12650. 

  12651. 

  12652. File: gdb.info,  Node: Tracepoint Restrictions,  Prev: Starting and Stopping Trace Experiments,  Up: Set Tracepoints

  12653. 

  12654. 13.1.10 Tracepoint Restrictions

  12655. -------------------------------

  12656. 

  12657. There are a number of restrictions on the use of tracepoints.  As

  12658. described above, tracepoint data gathering occurs on the target without

  12659. interaction from GDB.  Thus the full capabilities of the debugger are

  12660. not available during data gathering, and then at data examination time,

  12661. you will be limited by only having what was collected.  The following

  12662. items describe some common problems, but it is not exhaustive, and you

  12663. may run into additional difficulties not mentioned here.

  12664. 

  12665.    * Tracepoint expressions are intended to gather objects (lvalues).

  12666.      Thus the full flexibility of GDB's expression evaluator is not

  12667.      available.  You cannot call functions, cast objects to aggregate

  12668.      types, access convenience variables or modify values (except by

  12669.      assignment to trace state variables).  Some language features may

  12670.      implicitly call functions (for instance Objective-C fields with

  12671.      accessors), and therefore cannot be collected either.

  12672. 

  12673.    * Collection of local variables, either individually or in bulk with

  12674.      '$locals' or '$args', during 'while-stepping' may behave

  12675.      erratically.  The stepping action may enter a new scope (for

  12676.      instance by stepping into a function), or the location of the

  12677.      variable may change (for instance it is loaded into a register).

  12678.      The tracepoint data recorded uses the location information for the

  12679.      variables that is correct for the tracepoint location.  When the

  12680.      tracepoint is created, it is not possible, in general, to determine

  12681.      where the steps of a 'while-stepping' sequence will advance the

  12682.      program--particularly if a conditional branch is stepped.

  12683. 

  12684.    * Collection of an incompletely-initialized or partially-destroyed

  12685.      object may result in something that GDB cannot display, or displays

  12686.      in a misleading way.

  12687. 

  12688.    * When GDB displays a pointer to character it automatically

  12689.      dereferences the pointer to also display characters of the string

  12690.      being pointed to.  However, collecting the pointer during tracing

  12691.      does not automatically collect the string.  You need to explicitly

  12692.      dereference the pointer and provide size information if you want to

  12693.      collect not only the pointer, but the memory pointed to.  For

  12694.      example, '*ptr@50' can be used to collect the 50 element array

  12695.      pointed to by 'ptr'.

  12696. 

  12697.    * It is not possible to collect a complete stack backtrace at a

  12698.      tracepoint.  Instead, you may collect the registers and a few

  12699.      hundred bytes from the stack pointer with something like

  12700.      '*(unsigned char *)$esp@300' (adjust to use the name of the actual

  12701.      stack pointer register on your target architecture, and the amount

  12702.      of stack you wish to capture).  Then the 'backtrace' command will

  12703.      show a partial backtrace when using a trace frame.  The number of

  12704.      stack frames that can be examined depends on the sizes of the

  12705.      frames in the collected stack.  Note that if you ask for a block so

  12706.      large that it goes past the bottom of the stack, the target agent

  12707.      may report an error trying to read from an invalid address.

  12708. 

  12709.    * If you do not collect registers at a tracepoint, GDB can infer that

  12710.      the value of '$pc' must be the same as the address of the

  12711.      tracepoint and use that when you are looking at a trace frame for

  12712.      that tracepoint.  However, this cannot work if the tracepoint has

  12713.      multiple locations (for instance if it was set in a function that

  12714.      was inlined), or if it has a 'while-stepping' loop.  In those cases

  12715.      GDB will warn you that it can't infer '$pc', and default it to

  12716.      zero.

  12717. 

  12718. 

  12719. File: gdb.info,  Node: Analyze Collected Data,  Next: Tracepoint Variables,  Prev: Set Tracepoints,  Up: Tracepoints

  12720. 

  12721. 13.2 Using the Collected Data

  12722. =============================

  12723. 

  12724. After the tracepoint experiment ends, you use GDB commands for examining

  12725. the trace data.  The basic idea is that each tracepoint collects a trace

  12726. "snapshot" every time it is hit and another snapshot every time it

  12727. single-steps.  All these snapshots are consecutively numbered from zero

  12728. and go into a buffer, and you can examine them later.  The way you

  12729. examine them is to "focus" on a specific trace snapshot.  When the

  12730. remote stub is focused on a trace snapshot, it will respond to all GDB

  12731. requests for memory and registers by reading from the buffer which

  12732. belongs to that snapshot, rather than from _real_ memory or registers of

  12733. the program being debugged.  This means that *all* GDB commands

  12734. ('print', 'info registers', 'backtrace', etc.)  will behave as if we

  12735. were currently debugging the program state as it was when the tracepoint

  12736. occurred.  Any requests for data that are not in the buffer will fail.

  12737. 

  12738. * Menu:

  12739. 

  12740. * tfind::                       How to select a trace snapshot

  12741. * tdump::                       How to display all data for a snapshot

  12742. * save tracepoints::            How to save tracepoints for a future run

  12743. 

  12744. 

  12745. File: gdb.info,  Node: tfind,  Next: tdump,  Up: Analyze Collected Data

  12746. 

  12747. 13.2.1 'tfind N'

  12748. ----------------

  12749. 

  12750. The basic command for selecting a trace snapshot from the buffer is

  12751. 'tfind N', which finds trace snapshot number N, counting from zero.  If

  12752. no argument N is given, the next snapshot is selected.

  12753. 

  12754.    Here are the various forms of using the 'tfind' command.

  12755. 

  12756. 'tfind start'

  12757.      Find the first snapshot in the buffer.  This is a synonym for

  12758.      'tfind 0' (since 0 is the number of the first snapshot).

  12759. 

  12760. 'tfind none'

  12761.      Stop debugging trace snapshots, resume _live_ debugging.

  12762. 

  12763. 'tfind end'

  12764.      Same as 'tfind none'.

  12765. 

  12766. 'tfind'

  12767.      No argument means find the next trace snapshot or find the first

  12768.      one if no trace snapshot is selected.

  12769. 

  12770. 'tfind -'

  12771.      Find the previous trace snapshot before the current one.  This

  12772.      permits retracing earlier steps.

  12773. 

  12774. 'tfind tracepoint NUM'

  12775.      Find the next snapshot associated with tracepoint NUM.  Search

  12776.      proceeds forward from the last examined trace snapshot.  If no

  12777.      argument NUM is given, it means find the next snapshot collected

  12778.      for the same tracepoint as the current snapshot.

  12779. 

  12780. 'tfind pc ADDR'

  12781.      Find the next snapshot associated with the value ADDR of the

  12782.      program counter.  Search proceeds forward from the last examined

  12783.      trace snapshot.  If no argument ADDR is given, it means find the

  12784.      next snapshot with the same value of PC as the current snapshot.

  12785. 

  12786. 'tfind outside ADDR1, ADDR2'

  12787.      Find the next snapshot whose PC is outside the given range of

  12788.      addresses (exclusive).

  12789. 

  12790. 'tfind range ADDR1, ADDR2'

  12791.      Find the next snapshot whose PC is between ADDR1 and ADDR2

  12792.      (inclusive).

  12793. 

  12794. 'tfind line [FILE:]N'

  12795.      Find the next snapshot associated with the source line N.  If the

  12796.      optional argument FILE is given, refer to line N in that source

  12797.      file.  Search proceeds forward from the last examined trace

  12798.      snapshot.  If no argument N is given, it means find the next line

  12799.      other than the one currently being examined; thus saying 'tfind

  12800.      line' repeatedly can appear to have the same effect as stepping

  12801.      from line to line in a _live_ debugging session.

  12802. 

  12803.    The default arguments for the 'tfind' commands are specifically

  12804. designed to make it easy to scan through the trace buffer.  For

  12805. instance, 'tfind' with no argument selects the next trace snapshot, and

  12806. 'tfind -' with no argument selects the previous trace snapshot.  So, by

  12807. giving one 'tfind' command, and then simply hitting <RET> repeatedly you

  12808. can examine all the trace snapshots in order.  Or, by saying 'tfind -'

  12809. and then hitting <RET> repeatedly you can examine the snapshots in

  12810. reverse order.  The 'tfind line' command with no argument selects the

  12811. snapshot for the next source line executed.  The 'tfind pc' command with

  12812. no argument selects the next snapshot with the same program counter (PC)

  12813. as the current frame.  The 'tfind tracepoint' command with no argument

  12814. selects the next trace snapshot collected by the same tracepoint as the

  12815. current one.

  12816. 

  12817.    In addition to letting you scan through the trace buffer manually,

  12818. these commands make it easy to construct GDB scripts that scan through

  12819. the trace buffer and print out whatever collected data you are

  12820. interested in.  Thus, if we want to examine the PC, FP, and SP registers

  12821. from each trace frame in the buffer, we can say this:

  12822. 

  12823.      (gdb) tfind start

  12824.      (gdb) while ($trace_frame != -1)

  12825.      > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \

  12826.                $trace_frame, $pc, $sp, $fp

  12827.      > tfind

  12828.      > end

  12829. 

  12830.      Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44

  12831.      Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44

  12832.      Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44

  12833.      Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44

  12834.      Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44

  12835.      Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44

  12836.      Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44

  12837.      Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44

  12838.      Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44

  12839.      Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44

  12840.      Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14

  12841. 

  12842.    Or, if we want to examine the variable 'X' at each source line in the

  12843. buffer:

  12844. 

  12845.      (gdb) tfind start

  12846.      (gdb) while ($trace_frame != -1)

  12847.      > printf "Frame %d, X == %d\n", $trace_frame, X

  12848.      > tfind line

  12849.      > end

  12850. 

  12851.      Frame 0, X = 1

  12852.      Frame 7, X = 2

  12853.      Frame 13, X = 255

  12854. 

  12855. 

  12856. File: gdb.info,  Node: tdump,  Next: save tracepoints,  Prev: tfind,  Up: Analyze Collected Data

  12857. 

  12858. 13.2.2 'tdump'

  12859. --------------

  12860. 

  12861. This command takes no arguments.  It prints all the data collected at

  12862. the current trace snapshot.

  12863. 

  12864.      (gdb) trace 444

  12865.      (gdb) actions

  12866.      Enter actions for tracepoint #2, one per line:

  12867.      > collect $regs, $locals, $args, gdb_long_test

  12868.      > end

  12869. 

  12870.      (gdb) tstart

  12871. 

  12872.      (gdb) tfind line 444

  12873.      #0  gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)

  12874.      at gdb_test.c:444

  12875.      444        printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )

  12876. 

  12877.      (gdb) tdump

  12878.      Data collected at tracepoint 2, trace frame 1:

  12879.      d0             0xc4aa0085       -995491707

  12880.      d1             0x18     24

  12881.      d2             0x80     128

  12882.      d3             0x33     51

  12883.      d4             0x71aea3d        119204413

  12884.      d5             0x22     34

  12885.      d6             0xe0     224

  12886.      d7             0x380035 3670069

  12887.      a0             0x19e24a 1696330

  12888.      a1             0x3000668        50333288

  12889.      a2             0x100    256

  12890.      a3             0x322000 3284992

  12891.      a4             0x3000698        50333336

  12892.      a5             0x1ad3cc 1758156

  12893.      fp             0x30bf3c 0x30bf3c

  12894.      sp             0x30bf34 0x30bf34

  12895.      ps             0x0      0

  12896.      pc             0x20b2c8 0x20b2c8

  12897.      fpcontrol      0x0      0

  12898.      fpstatus       0x0      0

  12899.      fpiaddr        0x0      0

  12900.      p = 0x20e5b4 "gdb-test"

  12901.      p1 = (void *) 0x11

  12902.      p2 = (void *) 0x22

  12903.      p3 = (void *) 0x33

  12904.      p4 = (void *) 0x44

  12905.      p5 = (void *) 0x55

  12906.      p6 = (void *) 0x66

  12907.      gdb_long_test = 17 '\021'

  12908. 

  12909.      (gdb)

  12910. 

  12911.    'tdump' works by scanning the tracepoint's current collection actions

  12912. and printing the value of each expression listed.  So 'tdump' can fail,

  12913. if after a run, you change the tracepoint's actions to mention variables

  12914. that were not collected during the run.

  12915. 

  12916.    Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the

  12917. collected value of '$pc' to distinguish between trace frames that were

  12918. collected at the tracepoint hit, and frames that were collected while

  12919. stepping.  This allows it to correctly choose whether to display the

  12920. basic list of collections, or the collections from the body of the

  12921. while-stepping loop.  However, if '$pc' was not collected, then 'tdump'

  12922. will always attempt to dump using the basic collection list, and may

  12923. fail if a while-stepping frame does not include all the same data that

  12924. is collected at the tracepoint hit.

  12925. 

  12926. 

  12927. File: gdb.info,  Node: save tracepoints,  Prev: tdump,  Up: Analyze Collected Data

  12928. 

  12929. 13.2.3 'save tracepoints FILENAME'

  12930. ----------------------------------

  12931. 

  12932. This command saves all current tracepoint definitions together with

  12933. their actions and passcounts, into a file 'FILENAME' suitable for use in

  12934. a later debugging session.  To read the saved tracepoint definitions,

  12935. use the 'source' command (*note Command Files::).  The

  12936. 'save-tracepoints' command is a deprecated alias for 'save tracepoints'

  12937. 

  12938. 

  12939. File: gdb.info,  Node: Tracepoint Variables,  Next: Trace Files,  Prev: Analyze Collected Data,  Up: Tracepoints

  12940. 

  12941. 13.3 Convenience Variables for Tracepoints

  12942. ==========================================

  12943. 

  12944. '(int) $trace_frame'

  12945.      The current trace snapshot (a.k.a. "frame") number, or -1 if no

  12946.      snapshot is selected.

  12947. 

  12948. '(int) $tracepoint'

  12949.      The tracepoint for the current trace snapshot.

  12950. 

  12951. '(int) $trace_line'

  12952.      The line number for the current trace snapshot.

  12953. 

  12954. '(char []) $trace_file'

  12955.      The source file for the current trace snapshot.

  12956. 

  12957. '(char []) $trace_func'

  12958.      The name of the function containing '$tracepoint'.

  12959. 

  12960.    Note: '$trace_file' is not suitable for use in 'printf', use 'output'

  12961. instead.

  12962. 

  12963.    Here's a simple example of using these convenience variables for

  12964. stepping through all the trace snapshots and printing some of their

  12965. data.  Note that these are not the same as trace state variables, which

  12966. are managed by the target.

  12967. 

  12968.      (gdb) tfind start

  12969. 

  12970.      (gdb) while $trace_frame != -1

  12971.      > output $trace_file

  12972.      > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint

  12973.      > tfind

  12974.      > end

  12975. 

  12976. 

  12977. File: gdb.info,  Node: Trace Files,  Prev: Tracepoint Variables,  Up: Tracepoints

  12978. 

  12979. 13.4 Using Trace Files

  12980. ======================

  12981. 

  12982. In some situations, the target running a trace experiment may no longer

  12983. be available; perhaps it crashed, or the hardware was needed for a

  12984. different activity.  To handle these cases, you can arrange to dump the

  12985. trace data into a file, and later use that file as a source of trace

  12986. data, via the 'target tfile' command.

  12987. 

  12988. 'tsave [ -r ] FILENAME'

  12989. 'tsave [-ctf] DIRNAME'

  12990.      Save the trace data to FILENAME.  By default, this command assumes

  12991.      that FILENAME refers to the host filesystem, so if necessary GDB

  12992.      will copy raw trace data up from the target and then save it.  If

  12993.      the target supports it, you can also supply the optional argument

  12994.      '-r' ("remote") to direct the target to save the data directly into

  12995.      FILENAME in its own filesystem, which may be more efficient if the

  12996.      trace buffer is very large.  (Note, however, that 'target tfile'

  12997.      can only read from files accessible to the host.)  By default, this

  12998.      command will save trace frame in tfile format.  You can supply the

  12999.      optional argument '-ctf' to save data in CTF format.  The "Common

  13000.      Trace Format" (CTF) is proposed as a trace format that can be

  13001.      shared by multiple debugging and tracing tools.  Please go to

  13002.      'http://www.efficios.com/ctf' to get more information.

  13003. 

  13004. 'target tfile FILENAME'

  13005. 'target ctf DIRNAME'

  13006.      Use the file named FILENAME or directory named DIRNAME as a source

  13007.      of trace data.  Commands that examine data work as they do with a

  13008.      live target, but it is not possible to run any new trace

  13009.      experiments.  'tstatus' will report the state of the trace run at

  13010.      the moment the data was saved, as well as the current trace frame

  13011.      you are examining.  Both FILENAME and DIRNAME must be on a

  13012.      filesystem accessible to the host.

  13013. 

  13014.           (gdb) target ctf ctf.ctf

  13015.           (gdb) tfind

  13016.           Found trace frame 0, tracepoint 2

  13017.           39            ++a;  /* set tracepoint 1 here */

  13018.           (gdb) tdump

  13019.           Data collected at tracepoint 2, trace frame 0:

  13020.           i = 0

  13021.           a = 0

  13022.           b = 1 '\001'

  13023.           c = {"123", "456", "789", "123", "456", "789"}

  13024.           d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}}

  13025.           (gdb) p b

  13026.           $1 = 1

  13027. 

  13028. 

  13029. File: gdb.info,  Node: Overlays,  Next: Languages,  Prev: Tracepoints,  Up: Top

  13030. 

  13031. 14 Debugging Programs That Use Overlays

  13032. ***************************************

  13033. 

  13034. If your program is too large to fit completely in your target system's

  13035. memory, you can sometimes use "overlays" to work around this problem.

  13036. GDB provides some support for debugging programs that use overlays.

  13037. 

  13038. * Menu:

  13039. 

  13040. * How Overlays Work::              A general explanation of overlays.

  13041. * Overlay Commands::               Managing overlays in GDB.

  13042. * Automatic Overlay Debugging::    GDB can find out which overlays are

  13043.                                    mapped by asking the inferior.

  13044. * Overlay Sample Program::         A sample program using overlays.

  13045. 

  13046. 

  13047. File: gdb.info,  Node: How Overlays Work,  Next: Overlay Commands,  Up: Overlays

  13048. 

  13049. 14.1 How Overlays Work

  13050. ======================

  13051. 

  13052. Suppose you have a computer whose instruction address space is only 64

  13053. kilobytes long, but which has much more memory which can be accessed by

  13054. other means: special instructions, segment registers, or memory

  13055. management hardware, for example.  Suppose further that you want to

  13056. adapt a program which is larger than 64 kilobytes to run on this system.

  13057. 

  13058.    One solution is to identify modules of your program which are

  13059. relatively independent, and need not call each other directly; call

  13060. these modules "overlays".  Separate the overlays from the main program,

  13061. and place their machine code in the larger memory.  Place your main

  13062. program in instruction memory, but leave at least enough space there to

  13063. hold the largest overlay as well.

  13064. 

  13065.    Now, to call a function located in an overlay, you must first copy

  13066. that overlay's machine code from the large memory into the space set

  13067. aside for it in the instruction memory, and then jump to its entry point

  13068. there.

  13069. 

  13070.          Data             Instruction            Larger

  13071.      Address Space       Address Space        Address Space

  13072.      +-----------+       +-----------+        +-----------+

  13073.      |           |       |           |        |           |

  13074.      +-----------+       +-----------+        +-----------+<-- overlay 1

  13075.      | program   |       |   main    |   .----| overlay 1 | load address

  13076.      | variables |       |  program  |   |    +-----------+

  13077.      | and heap  |       |           |   |    |           |

  13078.      +-----------+       |           |   |    +-----------+<-- overlay 2

  13079.      |           |       +-----------+   |    |           | load address

  13080.      +-----------+       |           |   |  .-| overlay 2 |

  13081.                          |           |   |  | |           |

  13082.               mapped --->+-----------+   |  | +-----------+

  13083.               address    |           |   |  | |           |

  13084.                          |  overlay  | <-'  | |           |

  13085.                          |   area    |  <---' +-----------+<-- overlay 3

  13086.                          |           | <---.  |           | load address

  13087.                          +-----------+     `--| overlay 3 |

  13088.                          |           |        |           |

  13089.                          +-----------+        |           |

  13090.                                               +-----------+

  13091.                                               |           |

  13092.                                               +-----------+

  13093. 

  13094.                          A code overlay

  13095. 

  13096.    The diagram (*note A code overlay::) shows a system with separate

  13097. data and instruction address spaces.  To map an overlay, the program

  13098. copies its code from the larger address space to the instruction address

  13099. space.  Since the overlays shown here all use the same mapped address,

  13100. only one may be mapped at a time.  For a system with a single address

  13101. space for data and instructions, the diagram would be similar, except

  13102. that the program variables and heap would share an address space with

  13103. the main program and the overlay area.

  13104. 

  13105.    An overlay loaded into instruction memory and ready for use is called

  13106. a "mapped" overlay; its "mapped address" is its address in the

  13107. instruction memory.  An overlay not present (or only partially present)

  13108. in instruction memory is called "unmapped"; its "load address" is its

  13109. address in the larger memory.  The mapped address is also called the

  13110. "virtual memory address", or "VMA"; the load address is also called the

  13111. "load memory address", or "LMA".

  13112. 

  13113.    Unfortunately, overlays are not a completely transparent way to adapt

  13114. a program to limited instruction memory.  They introduce a new set of

  13115. global constraints you must keep in mind as you design your program:

  13116. 

  13117.    * Before calling or returning to a function in an overlay, your

  13118.      program must make sure that overlay is actually mapped.  Otherwise,

  13119.      the call or return will transfer control to the right address, but

  13120.      in the wrong overlay, and your program will probably crash.

  13121. 

  13122.    * If the process of mapping an overlay is expensive on your system,

  13123.      you will need to choose your overlays carefully to minimize their

  13124.      effect on your program's performance.

  13125. 

  13126.    * The executable file you load onto your system must contain each

  13127.      overlay's instructions, appearing at the overlay's load address,

  13128.      not its mapped address.  However, each overlay's instructions must

  13129.      be relocated and its symbols defined as if the overlay were at its

  13130.      mapped address.  You can use GNU linker scripts to specify

  13131.      different load and relocation addresses for pieces of your program;

  13132.      see *note (ld.info)Overlay Description::.

  13133. 

  13134.    * The procedure for loading executable files onto your system must be

  13135.      able to load their contents into the larger address space as well

  13136.      as the instruction and data spaces.

  13137. 

  13138.    The overlay system described above is rather simple, and could be

  13139. improved in many ways:

  13140. 

  13141.    * If your system has suitable bank switch registers or memory

  13142.      management hardware, you could use those facilities to make an

  13143.      overlay's load area contents simply appear at their mapped address

  13144.      in instruction space.  This would probably be faster than copying

  13145.      the overlay to its mapped area in the usual way.

  13146. 

  13147.    * If your overlays are small enough, you could set aside more than

  13148.      one overlay area, and have more than one overlay mapped at a time.

  13149. 

  13150.    * You can use overlays to manage data, as well as instructions.  In

  13151.      general, data overlays are even less transparent to your design

  13152.      than code overlays: whereas code overlays only require care when

  13153.      you call or return to functions, data overlays require care every

  13154.      time you access the data.  Also, if you change the contents of a

  13155.      data overlay, you must copy its contents back out to its load

  13156.      address before you can copy a different data overlay into the same

  13157.      mapped area.

  13158. 

  13159. 

  13160. File: gdb.info,  Node: Overlay Commands,  Next: Automatic Overlay Debugging,  Prev: How Overlays Work,  Up: Overlays

  13161. 

  13162. 14.2 Overlay Commands

  13163. =====================

  13164. 

  13165. To use GDB's overlay support, each overlay in your program must

  13166. correspond to a separate section of the executable file.  The section's

  13167. virtual memory address and load memory address must be the overlay's

  13168. mapped and load addresses.  Identifying overlays with sections allows

  13169. GDB to determine the appropriate address of a function or variable,

  13170. depending on whether the overlay is mapped or not.

  13171. 

  13172.    GDB's overlay commands all start with the word 'overlay'; you can

  13173. abbreviate this as 'ov' or 'ovly'.  The commands are:

  13174. 

  13175. 'overlay off'

  13176.      Disable GDB's overlay support.  When overlay support is disabled,

  13177.      GDB assumes that all functions and variables are always present at

  13178.      their mapped addresses.  By default, GDB's overlay support is

  13179.      disabled.

  13180. 

  13181. 'overlay manual'

  13182.      Enable "manual" overlay debugging.  In this mode, GDB relies on you

  13183.      to tell it which overlays are mapped, and which are not, using the

  13184.      'overlay map-overlay' and 'overlay unmap-overlay' commands

  13185.      described below.

  13186. 

  13187. 'overlay map-overlay OVERLAY'

  13188. 'overlay map OVERLAY'

  13189.      Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of

  13190.      the object file section containing the overlay.  When an overlay is

  13191.      mapped, GDB assumes it can find the overlay's functions and

  13192.      variables at their mapped addresses.  GDB assumes that any other

  13193.      overlays whose mapped ranges overlap that of OVERLAY are now

  13194.      unmapped.

  13195. 

  13196. 'overlay unmap-overlay OVERLAY'

  13197. 'overlay unmap OVERLAY'

  13198.      Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name

  13199.      of the object file section containing the overlay.  When an overlay

  13200.      is unmapped, GDB assumes it can find the overlay's functions and

  13201.      variables at their load addresses.

  13202. 

  13203. 'overlay auto'

  13204.      Enable "automatic" overlay debugging.  In this mode, GDB consults a

  13205.      data structure the overlay manager maintains in the inferior to see

  13206.      which overlays are mapped.  For details, see *note Automatic

  13207.      Overlay Debugging::.

  13208. 

  13209. 'overlay load-target'

  13210. 'overlay load'

  13211.      Re-read the overlay table from the inferior.  Normally, GDB

  13212.      re-reads the table GDB automatically each time the inferior stops,

  13213.      so this command should only be necessary if you have changed the

  13214.      overlay mapping yourself using GDB.  This command is only useful

  13215.      when using automatic overlay debugging.

  13216. 

  13217. 'overlay list-overlays'

  13218. 'overlay list'

  13219.      Display a list of the overlays currently mapped, along with their

  13220.      mapped addresses, load addresses, and sizes.

  13221. 

  13222.    Normally, when GDB prints a code address, it includes the name of the

  13223. function the address falls in:

  13224. 

  13225.      (gdb) print main

  13226.      $3 = {int ()} 0x11a0 <main>

  13227. When overlay debugging is enabled, GDB recognizes code in unmapped

  13228. overlays, and prints the names of unmapped functions with asterisks

  13229. around them.  For example, if 'foo' is a function in an unmapped

  13230. overlay, GDB prints it this way:

  13231. 

  13232.      (gdb) overlay list

  13233.      No sections are mapped.

  13234.      (gdb) print foo

  13235.      $5 = {int (int)} 0x100000 <*foo*>

  13236. When 'foo''s overlay is mapped, GDB prints the function's name normally:

  13237. 

  13238.      (gdb) overlay list

  13239.      Section .ov.foo.text, loaded at 0x100000 - 0x100034,

  13240.              mapped at 0x1016 - 0x104a

  13241.      (gdb) print foo

  13242.      $6 = {int (int)} 0x1016 <foo>

  13243. 

  13244.    When overlay debugging is enabled, GDB can find the correct address

  13245. for functions and variables in an overlay, whether or not the overlay is

  13246. mapped.  This allows most GDB commands, like 'break' and 'disassemble',

  13247. to work normally, even on unmapped code.  However, GDB's breakpoint

  13248. support has some limitations:

  13249. 

  13250.    * You can set breakpoints in functions in unmapped overlays, as long

  13251.      as GDB can write to the overlay at its load address.

  13252.    * GDB can not set hardware or simulator-based breakpoints in unmapped

  13253.      overlays.  However, if you set a breakpoint at the end of your

  13254.      overlay manager (and tell GDB which overlays are now mapped, if you

  13255.      are using manual overlay management), GDB will re-set its

  13256.      breakpoints properly.

  13257. 

  13258. 

  13259. File: gdb.info,  Node: Automatic Overlay Debugging,  Next: Overlay Sample Program,  Prev: Overlay Commands,  Up: Overlays

  13260. 

  13261. 14.3 Automatic Overlay Debugging

  13262. ================================

  13263. 

  13264. GDB can automatically track which overlays are mapped and which are not,

  13265. given some simple co-operation from the overlay manager in the inferior.

  13266. If you enable automatic overlay debugging with the 'overlay auto'

  13267. command (*note Overlay Commands::), GDB looks in the inferior's memory

  13268. for certain variables describing the current state of the overlays.

  13269. 

  13270.    Here are the variables your overlay manager must define to support

  13271. GDB's automatic overlay debugging:

  13272. 

  13273. '_ovly_table':

  13274.      This variable must be an array of the following structures:

  13275. 

  13276.           struct

  13277.           {

  13278.             /* The overlay's mapped address.  */

  13279.             unsigned long vma;

  13280. 

  13281.             /* The size of the overlay, in bytes.  */

  13282.             unsigned long size;

  13283. 

  13284.             /* The overlay's load address.  */

  13285.             unsigned long lma;

  13286. 

  13287.             /* Non-zero if the overlay is currently mapped;

  13288.                zero otherwise.  */

  13289.             unsigned long mapped;

  13290.           }

  13291. 

  13292. '_novlys':

  13293.      This variable must be a four-byte signed integer, holding the total

  13294.      number of elements in '_ovly_table'.

  13295. 

  13296.    To decide whether a particular overlay is mapped or not, GDB looks

  13297. for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the

  13298. VMA and LMA of the overlay's section in the executable file.  When GDB

  13299. finds a matching entry, it consults the entry's 'mapped' member to

  13300. determine whether the overlay is currently mapped.

  13301. 

  13302.    In addition, your overlay manager may define a function called

  13303. '_ovly_debug_event'.  If this function is defined, GDB will silently set

  13304. a breakpoint there.  If the overlay manager then calls this function

  13305. whenever it has changed the overlay table, this will enable GDB to

  13306. accurately keep track of which overlays are in program memory, and

  13307. update any breakpoints that may be set in overlays.  This will allow

  13308. breakpoints to work even if the overlays are kept in ROM or other

  13309. non-writable memory while they are not being executed.

  13310. 

  13311. 

  13312. File: gdb.info,  Node: Overlay Sample Program,  Prev: Automatic Overlay Debugging,  Up: Overlays

  13313. 

  13314. 14.4 Overlay Sample Program

  13315. ===========================

  13316. 

  13317. When linking a program which uses overlays, you must place the overlays

  13318. at their load addresses, while relocating them to run at their mapped

  13319. addresses.  To do this, you must write a linker script (*note

  13320. (ld.info)Overlay Description::).  Unfortunately, since linker scripts

  13321. are specific to a particular host system, target architecture, and

  13322. target memory layout, this manual cannot provide portable sample code

  13323. demonstrating GDB's overlay support.

  13324. 

  13325.    However, the GDB source distribution does contain an overlaid

  13326. program, with linker scripts for a few systems, as part of its test

  13327. suite.  The program consists of the following files from

  13328. 'gdb/testsuite/gdb.base':

  13329. 

  13330. 'overlays.c'

  13331.      The main program file.

  13332. 'ovlymgr.c'

  13333.      A simple overlay manager, used by 'overlays.c'.

  13334. 'foo.c'

  13335. 'bar.c'

  13336. 'baz.c'

  13337. 'grbx.c'

  13338.      Overlay modules, loaded and used by 'overlays.c'.

  13339. 'd10v.ld'

  13340. 'm32r.ld'

  13341.      Linker scripts for linking the test program on the 'd10v-elf' and

  13342.      'm32r-elf' targets.

  13343. 

  13344.    You can build the test program using the 'd10v-elf' GCC

  13345. cross-compiler like this:

  13346. 

  13347.      $ d10v-elf-gcc -g -c overlays.c

  13348.      $ d10v-elf-gcc -g -c ovlymgr.c

  13349.      $ d10v-elf-gcc -g -c foo.c

  13350.      $ d10v-elf-gcc -g -c bar.c

  13351.      $ d10v-elf-gcc -g -c baz.c

  13352.      $ d10v-elf-gcc -g -c grbx.c

  13353.      $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \

  13354.                        baz.o grbx.o -Wl,-Td10v.ld -o overlays

  13355. 

  13356.    The build process is identical for any other architecture, except

  13357. that you must substitute the appropriate compiler and linker script for

  13358. the target system for 'd10v-elf-gcc' and 'd10v.ld'.

  13359. 

  13360. 

  13361. File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Overlays,  Up: Top

  13362. 

  13363. 15 Using GDB with Different Languages

  13364. *************************************

  13365. 

  13366. Although programming languages generally have common aspects, they are

  13367. rarely expressed in the same manner.  For instance, in ANSI C,

  13368. dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it

  13369. is accomplished by 'p^'.  Values can also be represented (and displayed)

  13370. differently.  Hex numbers in C appear as '0x1ae', while in Modula-2 they

  13371. appear as '1AEH'.

  13372. 

  13373.    Language-specific information is built into GDB for some languages,

  13374. allowing you to express operations like the above in your program's

  13375. native language, and allowing GDB to output values in a manner

  13376. consistent with the syntax of your program's native language.  The

  13377. language you use to build expressions is called the "working language".

  13378. 

  13379. * Menu:

  13380. 

  13381. * Setting::                     Switching between source languages

  13382. * Show::                        Displaying the language

  13383. * Checks::                      Type and range checks

  13384. * Supported Languages::         Supported languages

  13385. * Unsupported Languages::       Unsupported languages

  13386. 

  13387. 

  13388. File: gdb.info,  Node: Setting,  Next: Show,  Up: Languages

  13389. 

  13390. 15.1 Switching Between Source Languages

  13391. =======================================

  13392. 

  13393. There are two ways to control the working language--either have GDB set

  13394. it automatically, or select it manually yourself.  You can use the 'set

  13395. language' command for either purpose.  On startup, GDB defaults to

  13396. setting the language automatically.  The working language is used to

  13397. determine how expressions you type are interpreted, how values are

  13398. printed, etc.

  13399. 

  13400.    In addition to the working language, every source file that GDB knows

  13401. about has its own working language.  For some object file formats, the

  13402. compiler might indicate which language a particular source file is in.

  13403. However, most of the time GDB infers the language from the name of the

  13404. file.  The language of a source file controls whether C++ names are

  13405. demangled--this way 'backtrace' can show each frame appropriately for

  13406. its own language.  There is no way to set the language of a source file

  13407. from within GDB, but you can set the language associated with a filename

  13408. extension.  *Note Displaying the Language: Show.

  13409. 

  13410.    This is most commonly a problem when you use a program, such as

  13411. 'cfront' or 'f2c', that generates C but is written in another language.

  13412. In that case, make the program use '#line' directives in its C output;

  13413. that way GDB will know the correct language of the source code of the

  13414. original program, and will display that source code, not the generated C

  13415. code.

  13416. 

  13417. * Menu:

  13418. 

  13419. * Filenames::                   Filename extensions and languages.

  13420. * Manually::                    Setting the working language manually

  13421. * Automatically::               Having GDB infer the source language

  13422. 

  13423. 

  13424. File: gdb.info,  Node: Filenames,  Next: Manually,  Up: Setting

  13425. 

  13426. 15.1.1 List of Filename Extensions and Languages

  13427. ------------------------------------------------

  13428. 

  13429. If a source file name ends in one of the following extensions, then GDB

  13430. infers that its language is the one indicated.

  13431. 

  13432. '.ada'

  13433. '.ads'

  13434. '.adb'

  13435. '.a'

  13436.      Ada source file.

  13437. 

  13438. '.c'

  13439.      C source file

  13440. 

  13441. '.C'

  13442. '.cc'

  13443. '.cp'

  13444. '.cpp'

  13445. '.cxx'

  13446. '.c++'

  13447.      C++ source file

  13448. 

  13449. '.d'

  13450.      D source file

  13451. 

  13452. '.m'

  13453.      Objective-C source file

  13454. 

  13455. '.f'

  13456. '.F'

  13457.      Fortran source file

  13458. 

  13459. '.mod'

  13460.      Modula-2 source file

  13461. 

  13462. '.s'

  13463. '.S'

  13464.      Assembler source file.  This actually behaves almost like C, but

  13465.      GDB does not skip over function prologues when stepping.

  13466. 

  13467.    In addition, you may set the language associated with a filename

  13468. extension.  *Note Displaying the Language: Show.

  13469. 

  13470. 

  13471. File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Filenames,  Up: Setting

  13472. 

  13473. 15.1.2 Setting the Working Language

  13474. -----------------------------------

  13475. 

  13476. If you allow GDB to set the language automatically, expressions are

  13477. interpreted the same way in your debugging session and your program.

  13478. 

  13479.    If you wish, you may set the language manually.  To do this, issue

  13480. the command 'set language LANG', where LANG is the name of a language,

  13481. such as 'c' or 'modula-2'.  For a list of the supported languages, type

  13482. 'set language'.

  13483. 

  13484.    Setting the language manually prevents GDB from updating the working

  13485. language automatically.  This can lead to confusion if you try to debug

  13486. a program when the working language is not the same as the source

  13487. language, when an expression is acceptable to both languages--but means

  13488. different things.  For instance, if the current source file were written

  13489. in C, and GDB was parsing Modula-2, a command such as:

  13490. 

  13491.      print a = b + c

  13492. 

  13493. might not have the effect you intended.  In C, this means to add 'b' and

  13494. 'c' and place the result in 'a'.  The result printed would be the value

  13495. of 'a'.  In Modula-2, this means to compare 'a' to the result of 'b+c',

  13496. yielding a 'BOOLEAN' value.

  13497. 

  13498. 

  13499. File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting

  13500. 

  13501. 15.1.3 Having GDB Infer the Source Language

  13502. -------------------------------------------

  13503. 

  13504. To have GDB set the working language automatically, use 'set language

  13505. local' or 'set language auto'.  GDB then infers the working language.

  13506. That is, when your program stops in a frame (usually by encountering a

  13507. breakpoint), GDB sets the working language to the language recorded for

  13508. the function in that frame.  If the language for a frame is unknown

  13509. (that is, if the function or block corresponding to the frame was

  13510. defined in a source file that does not have a recognized extension), the

  13511. current working language is not changed, and GDB issues a warning.

  13512. 

  13513.    This may not seem necessary for most programs, which are written

  13514. entirely in one source language.  However, program modules and libraries

  13515. written in one source language can be used by a main program written in

  13516. a different source language.  Using 'set language auto' in this case

  13517. frees you from having to set the working language manually.

  13518. 

  13519. 

  13520. File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages

  13521. 

  13522. 15.2 Displaying the Language

  13523. ============================

  13524. 

  13525. The following commands help you find out which language is the working

  13526. language, and also what language source files were written in.

  13527. 

  13528. 'show language'

  13529.      Display the current working language.  This is the language you can

  13530.      use with commands such as 'print' to build and compute expressions

  13531.      that may involve variables in your program.

  13532. 

  13533. 'info frame'

  13534.      Display the source language for this frame.  This language becomes

  13535.      the working language if you use an identifier from this frame.

  13536.      *Note Information about a Frame: Frame Info, to identify the other

  13537.      information listed here.

  13538. 

  13539. 'info source'

  13540.      Display the source language of this source file.  *Note Examining

  13541.      the Symbol Table: Symbols, to identify the other information listed

  13542.      here.

  13543. 

  13544.    In unusual circumstances, you may have source files with extensions

  13545. not in the standard list.  You can then set the extension associated

  13546. with a language explicitly:

  13547. 

  13548. 'set extension-language EXT LANGUAGE'

  13549.      Tell GDB that source files with extension EXT are to be assumed as

  13550.      written in the source language LANGUAGE.

  13551. 

  13552. 'info extensions'

  13553.      List all the filename extensions and the associated languages.

  13554. 

  13555. 

  13556. File: gdb.info,  Node: Checks,  Next: Supported Languages,  Prev: Show,  Up: Languages

  13557. 

  13558. 15.3 Type and Range Checking

  13559. ============================

  13560. 

  13561. Some languages are designed to guard you against making seemingly common

  13562. errors through a series of compile- and run-time checks.  These include

  13563. checking the type of arguments to functions and operators and making

  13564. sure mathematical overflows are caught at run time.  Checks such as

  13565. these help to ensure a program's correctness once it has been compiled

  13566. by eliminating type mismatches and providing active checks for range

  13567. errors when your program is running.

  13568. 

  13569.    By default GDB checks for these errors according to the rules of the

  13570. current source language.  Although GDB does not check the statements in

  13571. your program, it can check expressions entered directly into GDB for

  13572. evaluation via the 'print' command, for example.

  13573. 

  13574. * Menu:

  13575. 

  13576. * Type Checking::               An overview of type checking

  13577. * Range Checking::              An overview of range checking

  13578. 

  13579. 

  13580. File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Up: Checks

  13581. 

  13582. 15.3.1 An Overview of Type Checking

  13583. -----------------------------------

  13584. 

  13585. Some languages, such as C and C++, are strongly typed, meaning that the

  13586. arguments to operators and functions have to be of the correct type,

  13587. otherwise an error occurs.  These checks prevent type mismatch errors

  13588. from ever causing any run-time problems.  For example,

  13589. 

  13590.      int klass::my_method(char *b) { return  b ? 1 : 2; }

  13591. 

  13592.      (gdb) print obj.my_method (0)

  13593.      $1 = 2

  13594. but

  13595.      (gdb) print obj.my_method (0x1234)

  13596.      Cannot resolve method klass::my_method to any overloaded instance

  13597. 

  13598.    The second example fails because in C++ the integer constant '0x1234'

  13599. is not type-compatible with the pointer parameter type.

  13600. 

  13601.    For the expressions you use in GDB commands, you can tell GDB to not

  13602. enforce strict type checking or to treat any mismatches as errors and

  13603. abandon the expression; When type checking is disabled, GDB successfully

  13604. evaluates expressions like the second example above.

  13605. 

  13606.    Even if type checking is off, there may be other reasons related to

  13607. type that prevent GDB from evaluating an expression.  For instance, GDB

  13608. does not know how to add an 'int' and a 'struct foo'.  These particular

  13609. type errors have nothing to do with the language in use and usually

  13610. arise from expressions which make little sense to evaluate anyway.

  13611. 

  13612.    GDB provides some additional commands for controlling type checking:

  13613. 

  13614. 'set check type on'

  13615. 'set check type off'

  13616.      Set strict type checking on or off.  If any type mismatches occur

  13617.      in evaluating an expression while type checking is on, GDB prints a

  13618.      message and aborts evaluation of the expression.

  13619. 

  13620. 'show check type'

  13621.      Show the current setting of type checking and whether GDB is

  13622.      enforcing strict type checking rules.

  13623. 

  13624. 

  13625. File: gdb.info,  Node: Range Checking,  Prev: Type Checking,  Up: Checks

  13626. 

  13627. 15.3.2 An Overview of Range Checking

  13628. ------------------------------------

  13629. 

  13630. In some languages (such as Modula-2), it is an error to exceed the

  13631. bounds of a type; this is enforced with run-time checks.  Such range

  13632. checking is meant to ensure program correctness by making sure

  13633. computations do not overflow, or indices on an array element access do

  13634. not exceed the bounds of the array.

  13635. 

  13636.    For expressions you use in GDB commands, you can tell GDB to treat

  13637. range errors in one of three ways: ignore them, always treat them as

  13638. errors and abandon the expression, or issue warnings but evaluate the

  13639. expression anyway.

  13640. 

  13641.    A range error can result from numerical overflow, from exceeding an

  13642. array index bound, or when you type a constant that is not a member of

  13643. any type.  Some languages, however, do not treat overflows as an error.

  13644. In many implementations of C, mathematical overflow causes the result to

  13645. "wrap around" to lower values--for example, if M is the largest integer

  13646. value, and S is the smallest, then

  13647. 

  13648.      M + 1 => S

  13649. 

  13650.    This, too, is specific to individual languages, and in some cases

  13651. specific to individual compilers or machines.  *Note Supported

  13652. Languages: Supported Languages, for further details on specific

  13653. languages.

  13654. 

  13655.    GDB provides some additional commands for controlling the range

  13656. checker:

  13657. 

  13658. 'set check range auto'

  13659.      Set range checking on or off based on the current working language.

  13660.      *Note Supported Languages: Supported Languages, for the default

  13661.      settings for each language.

  13662. 

  13663. 'set check range on'

  13664. 'set check range off'

  13665.      Set range checking on or off, overriding the default setting for

  13666.      the current working language.  A warning is issued if the setting

  13667.      does not match the language default.  If a range error occurs and

  13668.      range checking is on, then a message is printed and evaluation of

  13669.      the expression is aborted.

  13670. 

  13671. 'set check range warn'

  13672.      Output messages when the GDB range checker detects a range error,

  13673.      but attempt to evaluate the expression anyway.  Evaluating the

  13674.      expression may still be impossible for other reasons, such as

  13675.      accessing memory that the process does not own (a typical example

  13676.      from many Unix systems).

  13677. 

  13678. 'show range'

  13679.      Show the current setting of the range checker, and whether or not

  13680.      it is being set automatically by GDB.

  13681. 

  13682. 

  13683. File: gdb.info,  Node: Supported Languages,  Next: Unsupported Languages,  Prev: Checks,  Up: Languages

  13684. 

  13685. 15.4 Supported Languages

  13686. ========================

  13687. 

  13688. GDB supports C, C++, D, Go, Objective-C, Fortran, OpenCL C, Pascal,

  13689. Rust, assembly, Modula-2, and Ada.  Some GDB features may be used in

  13690. expressions regardless of the language you use: the GDB '@' and '::'

  13691. operators, and the '{type}addr' construct (*note Expressions:

  13692. Expressions.) can be used with the constructs of any supported language.

  13693. 

  13694.    The following sections detail to what degree each source language is

  13695. supported by GDB.  These sections are not meant to be language tutorials

  13696. or references, but serve only as a reference guide to what the GDB

  13697. expression parser accepts, and what input and output formats should look

  13698. like for different languages.  There are many good books written on each

  13699. of these languages; please look to these for a language reference or

  13700. tutorial.

  13701. 

  13702. * Menu:

  13703. 

  13704. * C::                           C and C++

  13705. * D::                           D

  13706. * Go::                          Go

  13707. * Objective-C::                 Objective-C

  13708. * OpenCL C::                    OpenCL C

  13709. * Fortran::                     Fortran

  13710. * Pascal::                      Pascal

  13711. * Rust::                        Rust

  13712. * Modula-2::                    Modula-2

  13713. * Ada::                         Ada

  13714. 

  13715. 

  13716. File: gdb.info,  Node: C,  Next: D,  Up: Supported Languages

  13717. 

  13718. 15.4.1 C and C++

  13719. ----------------

  13720. 

  13721. Since C and C++ are so closely related, many features of GDB apply to

  13722. both languages.  Whenever this is the case, we discuss those languages

  13723. together.

  13724. 

  13725.    The C++ debugging facilities are jointly implemented by the C++

  13726. compiler and GDB.  Therefore, to debug your C++ code effectively, you

  13727. must compile your C++ programs with a supported C++ compiler, such as

  13728. GNU 'g++', or the HP ANSI C++ compiler ('aCC').

  13729. 

  13730. * Menu:

  13731. 

  13732. * C Operators::                 C and C++ operators

  13733. * C Constants::                 C and C++ constants

  13734. * C Plus Plus Expressions::     C++ expressions

  13735. * C Defaults::                  Default settings for C and C++

  13736. * C Checks::                    C and C++ type and range checks

  13737. * Debugging C::                 GDB and C

  13738. * Debugging C Plus Plus::       GDB features for C++

  13739. * Decimal Floating Point::      Numbers in Decimal Floating Point format

  13740. 

  13741. 

  13742. File: gdb.info,  Node: C Operators,  Next: C Constants,  Up: C

  13743. 

  13744. 15.4.1.1 C and C++ Operators

  13745. ............................

  13746. 

  13747. Operators must be defined on values of specific types.  For instance,

  13748. '+' is defined on numbers, but not on structures.  Operators are often

  13749. defined on groups of types.

  13750. 

  13751.    For the purposes of C and C++, the following definitions hold:

  13752. 

  13753.    * _Integral types_ include 'int' with any of its storage-class

  13754.      specifiers; 'char'; 'enum'; and, for C++, 'bool'.

  13755. 

  13756.    * _Floating-point types_ include 'float', 'double', and 'long double'

  13757.      (if supported by the target platform).

  13758. 

  13759.    * _Pointer types_ include all types defined as '(TYPE *)'.

  13760. 

  13761.    * _Scalar types_ include all of the above.

  13762. 

  13763. The following operators are supported.  They are listed here in order of

  13764. increasing precedence:

  13765. 

  13766. ','

  13767.      The comma or sequencing operator.  Expressions in a comma-separated

  13768.      list are evaluated from left to right, with the result of the

  13769.      entire expression being the last expression evaluated.

  13770. 

  13771. '='

  13772.      Assignment.  The value of an assignment expression is the value

  13773.      assigned.  Defined on scalar types.

  13774. 

  13775. 'OP='

  13776.      Used in an expression of the form 'A OP= B', and translated to

  13777.      'A = A OP B'.  'OP=' and '=' have the same precedence.  The

  13778.      operator OP is any one of the operators '|', '^', '&', '<<', '>>',

  13779.      '+', '-', '*', '/', '%'.

  13780. 

  13781. '?:'

  13782.      The ternary operator.  'A ? B : C' can be thought of as: if A then

  13783.      B else C.  The argument A should be of an integral type.

  13784. 

  13785. '||'

  13786.      Logical OR.  Defined on integral types.

  13787. 

  13788. '&&'

  13789.      Logical AND.  Defined on integral types.

  13790. 

  13791. '|'

  13792.      Bitwise OR.  Defined on integral types.

  13793. 

  13794. '^'

  13795.      Bitwise exclusive-OR.  Defined on integral types.

  13796. 

  13797. '&'

  13798.      Bitwise AND.  Defined on integral types.

  13799. 

  13800. '==, !='

  13801.      Equality and inequality.  Defined on scalar types.  The value of

  13802.      these expressions is 0 for false and non-zero for true.

  13803. 

  13804. '<, >, <=, >='

  13805.      Less than, greater than, less than or equal, greater than or equal.

  13806.      Defined on scalar types.  The value of these expressions is 0 for

  13807.      false and non-zero for true.

  13808. 

  13809. '<<, >>'

  13810.      left shift, and right shift.  Defined on integral types.

  13811. 

  13812. '@'

  13813.      The GDB "artificial array" operator (*note Expressions:

  13814.      Expressions.).

  13815. 

  13816. '+, -'

  13817.      Addition and subtraction.  Defined on integral types,

  13818.      floating-point types and pointer types.

  13819. 

  13820. '*, /, %'

  13821.      Multiplication, division, and modulus.  Multiplication and division

  13822.      are defined on integral and floating-point types.  Modulus is

  13823.      defined on integral types.

  13824. 

  13825. '++, --'

  13826.      Increment and decrement.  When appearing before a variable, the

  13827.      operation is performed before the variable is used in an

  13828.      expression; when appearing after it, the variable's value is used

  13829.      before the operation takes place.

  13830. 

  13831. '*'

  13832.      Pointer dereferencing.  Defined on pointer types.  Same precedence

  13833.      as '++'.

  13834. 

  13835. '&'

  13836.      Address operator.  Defined on variables.  Same precedence as '++'.

  13837. 

  13838.      For debugging C++, GDB implements a use of '&' beyond what is

  13839.      allowed in the C++ language itself: you can use '&(&REF)' to

  13840.      examine the address where a C++ reference variable (declared with

  13841.      '&REF') is stored.

  13842. 

  13843. '-'

  13844.      Negative.  Defined on integral and floating-point types.  Same

  13845.      precedence as '++'.

  13846. 

  13847. '!'

  13848.      Logical negation.  Defined on integral types.  Same precedence as

  13849.      '++'.

  13850. 

  13851. '~'

  13852.      Bitwise complement operator.  Defined on integral types.  Same

  13853.      precedence as '++'.

  13854. 

  13855. '., ->'

  13856.      Structure member, and pointer-to-structure member.  For

  13857.      convenience, GDB regards the two as equivalent, choosing whether to

  13858.      dereference a pointer based on the stored type information.

  13859.      Defined on 'struct' and 'union' data.

  13860. 

  13861. '.*, ->*'

  13862.      Dereferences of pointers to members.

  13863. 

  13864. '[]'

  13865.      Array indexing.  'A[I]' is defined as '*(A+I)'.  Same precedence as

  13866.      '->'.

  13867. 

  13868. '()'

  13869.      Function parameter list.  Same precedence as '->'.

  13870. 

  13871. '::'

  13872.      C++ scope resolution operator.  Defined on 'struct', 'union', and

  13873.      'class' types.

  13874. 

  13875. '::'

  13876.      Doubled colons also represent the GDB scope operator (*note

  13877.      Expressions: Expressions.).  Same precedence as '::', above.

  13878. 

  13879.    If an operator is redefined in the user code, GDB usually attempts to

  13880. invoke the redefined version instead of using the operator's predefined

  13881. meaning.

  13882. 

  13883. 

  13884. File: gdb.info,  Node: C Constants,  Next: C Plus Plus Expressions,  Prev: C Operators,  Up: C

  13885. 

  13886. 15.4.1.2 C and C++ Constants

  13887. ............................

  13888. 

  13889. GDB allows you to express the constants of C and C++ in the following

  13890. ways:

  13891. 

  13892.    * Integer constants are a sequence of digits.  Octal constants are

  13893.      specified by a leading '0' (i.e. zero), and hexadecimal constants

  13894.      by a leading '0x' or '0X'.  Constants may also end with a letter

  13895.      'l', specifying that the constant should be treated as a 'long'

  13896.      value.

  13897. 

  13898.    * Floating point constants are a sequence of digits, followed by a

  13899.      decimal point, followed by a sequence of digits, and optionally

  13900.      followed by an exponent.  An exponent is of the form:

  13901.      'e[[+]|-]NNN', where NNN is another sequence of digits.  The '+' is

  13902.      optional for positive exponents.  A floating-point constant may

  13903.      also end with a letter 'f' or 'F', specifying that the constant

  13904.      should be treated as being of the 'float' (as opposed to the

  13905.      default 'double') type; or with a letter 'l' or 'L', which

  13906.      specifies a 'long double' constant.

  13907. 

  13908.    * Enumerated constants consist of enumerated identifiers, or their

  13909.      integral equivalents.

  13910. 

  13911.    * Character constants are a single character surrounded by single

  13912.      quotes ('''), or a number--the ordinal value of the corresponding

  13913.      character (usually its ASCII value).  Within quotes, the single

  13914.      character may be represented by a letter or by "escape sequences",

  13915.      which are of the form '\NNN', where NNN is the octal representation

  13916.      of the character's ordinal value; or of the form '\X', where 'X' is

  13917.      a predefined special character--for example, '\n' for newline.

  13918. 

  13919.      Wide character constants can be written by prefixing a character

  13920.      constant with 'L', as in C. For example, 'L'x'' is the wide form of

  13921.      'x'.  The target wide character set is used when computing the

  13922.      value of this constant (*note Character Sets::).

  13923. 

  13924.    * String constants are a sequence of character constants surrounded

  13925.      by double quotes ('"').  Any valid character constant (as described

  13926.      above) may appear.  Double quotes within the string must be

  13927.      preceded by a backslash, so for instance '"a\"b'c"' is a string of

  13928.      five characters.

  13929. 

  13930.      Wide string constants can be written by prefixing a string constant

  13931.      with 'L', as in C. The target wide character set is used when

  13932.      computing the value of this constant (*note Character Sets::).

  13933. 

  13934.    * Pointer constants are an integral value.  You can also write

  13935.      pointers to constants using the C operator '&'.

  13936. 

  13937.    * Array constants are comma-separated lists surrounded by braces '{'

  13938.      and '}'; for example, '{1,2,3}' is a three-element array of

  13939.      integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and

  13940.      '{&"hi", &"there", &"fred"}' is a three-element array of pointers.

  13941. 

  13942. 

  13943. File: gdb.info,  Node: C Plus Plus Expressions,  Next: C Defaults,  Prev: C Constants,  Up: C

  13944. 

  13945. 15.4.1.3 C++ Expressions

  13946. ........................

  13947. 

  13948. GDB expression handling can interpret most C++ expressions.

  13949. 

  13950.      _Warning:_ GDB can only debug C++ code if you use the proper

  13951.      compiler and the proper debug format.  Currently, GDB works best

  13952.      when debugging C++ code that is compiled with the most recent

  13953.      version of GCC possible.  The DWARF debugging format is preferred;

  13954.      GCC defaults to this on most popular platforms.  Other compilers

  13955.      and/or debug formats are likely to work badly or not at all when

  13956.      using GDB to debug C++ code.  *Note Compilation::.

  13957. 

  13958.   1. Member function calls are allowed; you can use expressions like

  13959. 

  13960.           count = aml->GetOriginal(x, y)

  13961. 

  13962.   2. While a member function is active (in the selected stack frame),

  13963.      your expressions have the same namespace available as the member

  13964.      function; that is, GDB allows implicit references to the class

  13965.      instance pointer 'this' following the same rules as C++.  'using'

  13966.      declarations in the current scope are also respected by GDB.

  13967. 

  13968.   3. You can call overloaded functions; GDB resolves the function call

  13969.      to the right definition, with some restrictions.  GDB does not

  13970.      perform overload resolution involving user-defined type

  13971.      conversions, calls to constructors, or instantiations of templates

  13972.      that do not exist in the program.  It also cannot handle ellipsis

  13973.      argument lists or default arguments.

  13974. 

  13975.      It does perform integral conversions and promotions, floating-point

  13976.      promotions, arithmetic conversions, pointer conversions,

  13977.      conversions of class objects to base classes, and standard

  13978.      conversions such as those of functions or arrays to pointers; it

  13979.      requires an exact match on the number of function arguments.

  13980. 

  13981.      Overload resolution is always performed, unless you have specified

  13982.      'set overload-resolution off'.  *Note GDB Features for C++:

  13983.      Debugging C Plus Plus.

  13984. 

  13985.      You must specify 'set overload-resolution off' in order to use an

  13986.      explicit function signature to call an overloaded function, as in

  13987.           p 'foo(char,int)'('x', 13)

  13988. 

  13989.      The GDB command-completion facility can simplify this; see *note

  13990.      Command Completion: Completion.

  13991. 

  13992.   4. GDB understands variables declared as C++ lvalue or rvalue

  13993.      references; you can use them in expressions just as you do in C++

  13994.      source--they are automatically dereferenced.

  13995. 

  13996.      In the parameter list shown when GDB displays a frame, the values

  13997.      of reference variables are not displayed (unlike other variables);

  13998.      this avoids clutter, since references are often used for large

  13999.      structures.  The _address_ of a reference variable is always shown,

  14000.      unless you have specified 'set print address off'.

  14001. 

  14002.   5. GDB supports the C++ name resolution operator '::'--your

  14003.      expressions can use it just as expressions in your program do.

  14004.      Since one scope may be defined in another, you can use '::'

  14005.      repeatedly if necessary, for example in an expression like

  14006.      'SCOPE1::SCOPE2::NAME'.  GDB also allows resolving name scope by

  14007.      reference to source files, in both C and C++ debugging (*note

  14008.      Program Variables: Variables.).

  14009. 

  14010.   6. GDB performs argument-dependent lookup, following the C++

  14011.      specification.

  14012. 

  14013. 

  14014. File: gdb.info,  Node: C Defaults,  Next: C Checks,  Prev: C Plus Plus Expressions,  Up: C

  14015. 

  14016. 15.4.1.4 C and C++ Defaults

  14017. ...........................

  14018. 

  14019. If you allow GDB to set range checking automatically, it defaults to

  14020. 'off' whenever the working language changes to C or C++.  This happens

  14021. regardless of whether you or GDB selects the working language.

  14022. 

  14023.    If you allow GDB to set the language automatically, it recognizes

  14024. source files whose names end with '.c', '.C', or '.cc', etc, and when

  14025. GDB enters code compiled from one of these files, it sets the working

  14026. language to C or C++.  *Note Having GDB Infer the Source Language:

  14027. Automatically, for further details.

  14028. 

  14029. 

  14030. File: gdb.info,  Node: C Checks,  Next: Debugging C,  Prev: C Defaults,  Up: C

  14031. 

  14032. 15.4.1.5 C and C++ Type and Range Checks

  14033. ........................................

  14034. 

  14035. By default, when GDB parses C or C++ expressions, strict type checking

  14036. is used.  However, if you turn type checking off, GDB will allow certain

  14037. non-standard conversions, such as promoting integer constants to

  14038. pointers.

  14039. 

  14040.    Range checking, if turned on, is done on mathematical operations.

  14041. Array indices are not checked, since they are often used to index a

  14042. pointer that is not itself an array.

  14043. 

  14044. 

  14045. File: gdb.info,  Node: Debugging C,  Next: Debugging C Plus Plus,  Prev: C Checks,  Up: C

  14046. 

  14047. 15.4.1.6 GDB and C

  14048. ..................

  14049. 

  14050. The 'set print union' and 'show print union' commands apply to the

  14051. 'union' type.  When set to 'on', any 'union' that is inside a 'struct'

  14052. or 'class' is also printed.  Otherwise, it appears as '{...}'.

  14053. 

  14054.    The '@' operator aids in the debugging of dynamic arrays, formed with

  14055. pointers and a memory allocation function.  *Note Expressions:

  14056. Expressions.

  14057. 

  14058. 

  14059. File: gdb.info,  Node: Debugging C Plus Plus,  Next: Decimal Floating Point,  Prev: Debugging C,  Up: C

  14060. 

  14061. 15.4.1.7 GDB Features for C++

  14062. .............................

  14063. 

  14064. Some GDB commands are particularly useful with C++, and some are

  14065. designed specifically for use with C++.  Here is a summary:

  14066. 

  14067. 'breakpoint menus'

  14068.      When you want a breakpoint in a function whose name is overloaded,

  14069.      GDB has the capability to display a menu of possible breakpoint

  14070.      locations to help you specify which function definition you want.

  14071.      *Note Ambiguous Expressions: Ambiguous Expressions.

  14072. 

  14073. 'rbreak REGEX'

  14074.      Setting breakpoints using regular expressions is helpful for

  14075.      setting breakpoints on overloaded functions that are not members of

  14076.      any special classes.  *Note Setting Breakpoints: Set Breaks.

  14077. 

  14078. 'catch throw'

  14079. 'catch rethrow'

  14080. 'catch catch'

  14081.      Debug C++ exception handling using these commands.  *Note Setting

  14082.      Catchpoints: Set Catchpoints.

  14083. 

  14084. 'ptype TYPENAME'

  14085.      Print inheritance relationships as well as other information for

  14086.      type TYPENAME.  *Note Examining the Symbol Table: Symbols.

  14087. 

  14088. 'info vtbl EXPRESSION.'

  14089.      The 'info vtbl' command can be used to display the virtual method

  14090.      tables of the object computed by EXPRESSION.  This shows one entry

  14091.      per virtual table; there may be multiple virtual tables when

  14092.      multiple inheritance is in use.

  14093. 

  14094. 'demangle NAME'

  14095.      Demangle NAME.  *Note Symbols::, for a more complete description of

  14096.      the 'demangle' command.

  14097. 

  14098. 'set print demangle'

  14099. 'show print demangle'

  14100. 'set print asm-demangle'

  14101. 'show print asm-demangle'

  14102.      Control whether C++ symbols display in their source form, both when

  14103.      displaying code as C++ source and when displaying disassemblies.

  14104.      *Note Print Settings: Print Settings.

  14105. 

  14106. 'set print object'

  14107. 'show print object'

  14108.      Choose whether to print derived (actual) or declared types of

  14109.      objects.  *Note Print Settings: Print Settings.

  14110. 

  14111. 'set print vtbl'

  14112. 'show print vtbl'

  14113.      Control the format for printing virtual function tables.  *Note

  14114.      Print Settings: Print Settings.  (The 'vtbl' commands do not work

  14115.      on programs compiled with the HP ANSI C++ compiler ('aCC').)

  14116. 

  14117. 'set overload-resolution on'

  14118.      Enable overload resolution for C++ expression evaluation.  The

  14119.      default is on.  For overloaded functions, GDB evaluates the

  14120.      arguments and searches for a function whose signature matches the

  14121.      argument types, using the standard C++ conversion rules (see *note

  14122.      C++ Expressions: C Plus Plus Expressions, for details).  If it

  14123.      cannot find a match, it emits a message.

  14124. 

  14125. 'set overload-resolution off'

  14126.      Disable overload resolution for C++ expression evaluation.  For

  14127.      overloaded functions that are not class member functions, GDB

  14128.      chooses the first function of the specified name that it finds in

  14129.      the symbol table, whether or not its arguments are of the correct

  14130.      type.  For overloaded functions that are class member functions,

  14131.      GDB searches for a function whose signature _exactly_ matches the

  14132.      argument types.

  14133. 

  14134. 'show overload-resolution'

  14135.      Show the current setting of overload resolution.

  14136. 

  14137. 'Overloaded symbol names'

  14138.      You can specify a particular definition of an overloaded symbol,

  14139.      using the same notation that is used to declare such symbols in

  14140.      C++: type 'SYMBOL(TYPES)' rather than just SYMBOL.  You can also

  14141.      use the GDB command-line word completion facilities to list the

  14142.      available choices, or to finish the type list for you.  *Note

  14143.      Command Completion: Completion, for details on how to do this.

  14144. 

  14145. 'Breakpoints in functions with ABI tags'

  14146. 

  14147.      The GNU C++ compiler introduced the notion of ABI "tags", which

  14148.      correspond to changes in the ABI of a type, function, or variable

  14149.      that would not otherwise be reflected in a mangled name.  See

  14150.      <https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/>

  14151.      for more detail.

  14152. 

  14153.      The ABI tags are visible in C++ demangled names.  For example, a

  14154.      function that returns a std::string:

  14155. 

  14156.           std::string function(int);

  14157. 

  14158.      when compiled for the C++11 ABI is marked with the 'cxx11' ABI tag,

  14159.      and GDB displays the symbol like this:

  14160. 

  14161.           function[abi:cxx11](int)

  14162. 

  14163.      You can set a breakpoint on such functions simply as if they had no

  14164.      tag.  For example:

  14165. 

  14166.           (gdb) b function(int)

  14167.           Breakpoint 2 at 0x40060d: file main.cc, line 10.

  14168.           (gdb) info breakpoints

  14169.           Num     Type           Disp Enb Address    What

  14170.           1       breakpoint     keep y   0x0040060d in function[abi:cxx11](int)

  14171.                                                      at main.cc:10

  14172. 

  14173.      On the rare occasion you need to disambiguate between different ABI

  14174.      tags, you can do so by simply including the ABI tag in the function

  14175.      name, like:

  14176. 

  14177.           (gdb) b ambiguous[abi:other_tag](int)

  14178. 

  14179. 

  14180. File: gdb.info,  Node: Decimal Floating Point,  Prev: Debugging C Plus Plus,  Up: C

  14181. 

  14182. 15.4.1.8 Decimal Floating Point format

  14183. ......................................

  14184. 

  14185. GDB can examine, set and perform computations with numbers in decimal

  14186. floating point format, which in the C language correspond to the

  14187. '_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the

  14188. extension to support decimal floating-point arithmetic.

  14189. 

  14190.    There are two encodings in use, depending on the architecture: BID

  14191. (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed

  14192. Decimal) for PowerPC and S/390.  GDB will use the appropriate encoding

  14193. for the configured target.

  14194. 

  14195.    Because of a limitation in 'libdecnumber', the library used by GDB to

  14196. manipulate decimal floating point numbers, it is not possible to convert

  14197. (using a cast, for example) integers wider than 32-bit to decimal float.

  14198. 

  14199.    In addition, in order to imitate GDB's behaviour with binary floating

  14200. point computations, error checking in decimal float operations ignores

  14201. underflow, overflow and divide by zero exceptions.

  14202. 

  14203.    In the PowerPC architecture, GDB provides a set of pseudo-registers

  14204. to inspect '_Decimal128' values stored in floating point registers.  See

  14205. *note PowerPC: PowerPC. for more details.

  14206. 

  14207. 

  14208. File: gdb.info,  Node: D,  Next: Go,  Prev: C,  Up: Supported Languages

  14209. 

  14210. 15.4.2 D

  14211. --------

  14212. 

  14213. GDB can be used to debug programs written in D and compiled with GDC,

  14214. LDC or DMD compilers.  Currently GDB supports only one D specific

  14215. feature -- dynamic arrays.

  14216. 

  14217. 

  14218. File: gdb.info,  Node: Go,  Next: Objective-C,  Prev: D,  Up: Supported Languages

  14219. 

  14220. 15.4.3 Go

  14221. ---------

  14222. 

  14223. GDB can be used to debug programs written in Go and compiled with

  14224. 'gccgo' or '6g' compilers.

  14225. 

  14226.    Here is a summary of the Go-specific features and restrictions:

  14227. 

  14228. 'The current Go package'

  14229.      The name of the current package does not need to be specified when

  14230.      specifying global variables and functions.

  14231. 

  14232.      For example, given the program:

  14233. 

  14234.           package main

  14235.           var myglob = "Shall we?"

  14236.           func main () {

  14237.             // ...

  14238.           }

  14239. 

  14240.      When stopped inside 'main' either of these work:

  14241. 

  14242.           (gdb) p myglob

  14243.           (gdb) p main.myglob

  14244. 

  14245. 'Builtin Go types'

  14246.      The 'string' type is recognized by GDB and is printed as a string.

  14247. 

  14248. 'Builtin Go functions'

  14249.      The GDB expression parser recognizes the 'unsafe.Sizeof' function

  14250.      and handles it internally.

  14251. 

  14252. 'Restrictions on Go expressions'

  14253.      All Go operators are supported except '&^'.  The Go '_' "blank

  14254.      identifier" is not supported.  Automatic dereferencing of pointers

  14255.      is not supported.

  14256. 

  14257. 

  14258. File: gdb.info,  Node: Objective-C,  Next: OpenCL C,  Prev: Go,  Up: Supported Languages

  14259. 

  14260. 15.4.4 Objective-C

  14261. ------------------

  14262. 

  14263. This section provides information about some commands and command

  14264. options that are useful for debugging Objective-C code.  See also *note

  14265. info classes: Symbols, and *note info selectors: Symbols, for a few more

  14266. commands specific to Objective-C support.

  14267. 

  14268. * Menu:

  14269. 

  14270. * Method Names in Commands::

  14271. * The Print Command with Objective-C::

  14272. 

  14273. 

  14274. File: gdb.info,  Node: Method Names in Commands,  Next: The Print Command with Objective-C,  Up: Objective-C

  14275. 

  14276. 15.4.4.1 Method Names in Commands

  14277. .................................

  14278. 

  14279. The following commands have been extended to accept Objective-C method

  14280. names as line specifications:

  14281. 

  14282.    * 'clear'

  14283.    * 'break'

  14284.    * 'info line'

  14285.    * 'jump'

  14286.    * 'list'

  14287. 

  14288.    A fully qualified Objective-C method name is specified as

  14289. 

  14290.      -[CLASS METHODNAME]

  14291. 

  14292.    where the minus sign is used to indicate an instance method and a

  14293. plus sign (not shown) is used to indicate a class method.  The class

  14294. name CLASS and method name METHODNAME are enclosed in brackets, similar

  14295. to the way messages are specified in Objective-C source code.  For

  14296. example, to set a breakpoint at the 'create' instance method of class

  14297. 'Fruit' in the program currently being debugged, enter:

  14298. 

  14299.      break -[Fruit create]

  14300. 

  14301.    To list ten program lines around the 'initialize' class method,

  14302. enter:

  14303. 

  14304.      list +[NSText initialize]

  14305. 

  14306.    In the current version of GDB, the plus or minus sign is required.

  14307. In future versions of GDB, the plus or minus sign will be optional, but

  14308. you can use it to narrow the search.  It is also possible to specify

  14309. just a method name:

  14310. 

  14311.      break create

  14312. 

  14313.    You must specify the complete method name, including any colons.  If

  14314. your program's source files contain more than one 'create' method,

  14315. you'll be presented with a numbered list of classes that implement that

  14316. method.  Indicate your choice by number, or type '0' to exit if none

  14317. apply.

  14318. 

  14319.    As another example, to clear a breakpoint established at the

  14320. 'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter:

  14321. 

  14322.      clear -[NSWindow makeKeyAndOrderFront:]

  14323. 

  14324. 

  14325. File: gdb.info,  Node: The Print Command with Objective-C,  Prev: Method Names in Commands,  Up: Objective-C

  14326. 

  14327. 15.4.4.2 The Print Command With Objective-C

  14328. ...........................................

  14329. 

  14330. The print command has also been extended to accept methods.  For

  14331. example:

  14332. 

  14333.      print -[OBJECT hash]

  14334. 

  14335. will tell GDB to send the 'hash' message to OBJECT and print the result.

  14336. Also, an additional command has been added, 'print-object' or 'po' for

  14337. short, which is meant to print the description of an object.  However,

  14338. this command may only work with certain Objective-C libraries that have

  14339. a particular hook function, '_NSPrintForDebugger', defined.

  14340. 

  14341. 

  14342. File: gdb.info,  Node: OpenCL C,  Next: Fortran,  Prev: Objective-C,  Up: Supported Languages

  14343. 

  14344. 15.4.5 OpenCL C

  14345. ---------------

  14346. 

  14347. This section provides information about GDBs OpenCL C support.

  14348. 

  14349. * Menu:

  14350. 

  14351. * OpenCL C Datatypes::

  14352. * OpenCL C Expressions::

  14353. * OpenCL C Operators::

  14354. 

  14355. 

  14356. File: gdb.info,  Node: OpenCL C Datatypes,  Next: OpenCL C Expressions,  Up: OpenCL C

  14357. 

  14358. 15.4.5.1 OpenCL C Datatypes

  14359. ...........................

  14360. 

  14361. GDB supports the builtin scalar and vector datatypes specified by OpenCL

  14362. 1.1.  In addition the half- and double-precision floating point data

  14363. types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also

  14364. known to GDB.

  14365. 

  14366. 

  14367. File: gdb.info,  Node: OpenCL C Expressions,  Next: OpenCL C Operators,  Prev: OpenCL C Datatypes,  Up: OpenCL C

  14368. 

  14369. 15.4.5.2 OpenCL C Expressions

  14370. .............................

  14371. 

  14372. GDB supports accesses to vector components including the access as

  14373. lvalue where possible.  Since OpenCL C is based on C99 most C

  14374. expressions supported by GDB can be used as well.

  14375. 

  14376. 

  14377. File: gdb.info,  Node: OpenCL C Operators,  Prev: OpenCL C Expressions,  Up: OpenCL C

  14378. 

  14379. 15.4.5.3 OpenCL C Operators

  14380. ...........................

  14381. 

  14382. GDB supports the operators specified by OpenCL 1.1 for scalar and vector

  14383. data types.

  14384. 

  14385. 

  14386. File: gdb.info,  Node: Fortran,  Next: Pascal,  Prev: OpenCL C,  Up: Supported Languages

  14387. 

  14388. 15.4.6 Fortran

  14389. --------------

  14390. 

  14391. GDB can be used to debug programs written in Fortran, but it currently

  14392. supports only the features of Fortran 77 language.

  14393. 

  14394.    Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among

  14395. them) append an underscore to the names of variables and functions.

  14396. When you debug programs compiled by those compilers, you will need to

  14397. refer to variables and functions with a trailing underscore.

  14398. 

  14399. * Menu:

  14400. 

  14401. * Fortran Operators::           Fortran operators and expressions

  14402. * Fortran Defaults::            Default settings for Fortran

  14403. * Special Fortran Commands::    Special GDB commands for Fortran

  14404. 

  14405. 

  14406. File: gdb.info,  Node: Fortran Operators,  Next: Fortran Defaults,  Up: Fortran

  14407. 

  14408. 15.4.6.1 Fortran Operators and Expressions

  14409. ..........................................

  14410. 

  14411. Operators must be defined on values of specific types.  For instance,

  14412. '+' is defined on numbers, but not on characters or other non-

  14413. arithmetic types.  Operators are often defined on groups of types.

  14414. 

  14415. '**'

  14416.      The exponentiation operator.  It raises the first operand to the

  14417.      power of the second one.

  14418. 

  14419. ':'

  14420.      The range operator.  Normally used in the form of array(low:high)

  14421.      to represent a section of array.

  14422. 

  14423. '%'

  14424.      The access component operator.  Normally used to access elements in

  14425.      derived types.  Also suitable for unions.  As unions aren't part of

  14426.      regular Fortran, this can only happen when accessing a register

  14427.      that uses a gdbarch-defined union type.

  14428. '::'

  14429.      The scope operator.  Normally used to access variables in modules

  14430.      or to set breakpoints on subroutines nested in modules or in other

  14431.      subroutines (internal subroutines).

  14432. 

  14433. 

  14434. File: gdb.info,  Node: Fortran Defaults,  Next: Special Fortran Commands,  Prev: Fortran Operators,  Up: Fortran

  14435. 

  14436. 15.4.6.2 Fortran Defaults

  14437. .........................

  14438. 

  14439. Fortran symbols are usually case-insensitive, so GDB by default uses

  14440. case-insensitive matches for Fortran symbols.  You can change that with

  14441. the 'set case-insensitive' command, see *note Symbols::, for the

  14442. details.

  14443. 

  14444. 

  14445. File: gdb.info,  Node: Special Fortran Commands,  Prev: Fortran Defaults,  Up: Fortran

  14446. 

  14447. 15.4.6.3 Special Fortran Commands

  14448. .................................

  14449. 

  14450. GDB has some commands to support Fortran-specific features, such as

  14451. displaying common blocks.

  14452. 

  14453. 'info common [COMMON-NAME]'

  14454.      This command prints the values contained in the Fortran 'COMMON'

  14455.      block whose name is COMMON-NAME.  With no argument, the names of

  14456.      all 'COMMON' blocks visible at the current program location are

  14457.      printed.

  14458. 

  14459. 

  14460. File: gdb.info,  Node: Pascal,  Next: Rust,  Prev: Fortran,  Up: Supported Languages

  14461. 

  14462. 15.4.7 Pascal

  14463. -------------

  14464. 

  14465. Debugging Pascal programs which use sets, subranges, file variables, or

  14466. nested functions does not currently work.  GDB does not support entering

  14467. expressions, printing values, or similar features using Pascal syntax.

  14468. 

  14469.    The Pascal-specific command 'set print pascal_static-members'

  14470. controls whether static members of Pascal objects are displayed.  *Note

  14471. pascal_static-members: Print Settings.

  14472. 

  14473. 

  14474. File: gdb.info,  Node: Rust,  Next: Modula-2,  Prev: Pascal,  Up: Supported Languages

  14475. 

  14476. 15.4.8 Rust

  14477. -----------

  14478. 

  14479. GDB supports the Rust Programming Language (https://www.rust-lang.org/).

  14480. Type- and value-printing, and expression parsing, are reasonably

  14481. complete.  However, there are a few peculiarities and holes to be aware

  14482. of.

  14483. 

  14484.    * Linespecs (*note Specify Location::) are never relative to the

  14485.      current crate.  Instead, they act as if there were a global

  14486.      namespace of crates, somewhat similar to the way 'extern crate'

  14487.      behaves.

  14488. 

  14489.      That is, if GDB is stopped at a breakpoint in a function in crate

  14490.      'A', module 'B', then 'break B::f' will attempt to set a breakpoint

  14491.      in a function named 'f' in a crate named 'B'.

  14492. 

  14493.      As a consequence of this approach, linespecs also cannot refer to

  14494.      items using 'self::' or 'super::'.

  14495. 

  14496.    * Because GDB implements Rust name-lookup semantics in expressions,

  14497.      it will sometimes prepend the current crate to a name.  For

  14498.      example, if GDB is stopped at a breakpoint in the crate 'K', then

  14499.      'print ::x::y' will try to find the symbol 'K::x::y'.

  14500. 

  14501.      However, since it is useful to be able to refer to other crates

  14502.      when debugging, GDB provides the 'extern' extension to circumvent

  14503.      this.  To use the extension, just put 'extern' before a path

  14504.      expression to refer to the otherwise unavailable "global" scope.

  14505. 

  14506.      In the above example, if you wanted to refer to the symbol 'y' in

  14507.      the crate 'x', you would use 'print extern x::y'.

  14508. 

  14509.    * The Rust expression evaluator does not support "statement-like"

  14510.      expressions such as 'if' or 'match', or lambda expressions.

  14511. 

  14512.    * Tuple expressions are not implemented.

  14513. 

  14514.    * The Rust expression evaluator does not currently implement the

  14515.      'Drop' trait.  Objects that may be created by the evaluator will

  14516.      never be destroyed.

  14517. 

  14518.    * GDB does not implement type inference for generics.  In order to

  14519.      call generic functions or otherwise refer to generic items, you

  14520.      will have to specify the type parameters manually.

  14521. 

  14522.    * GDB currently uses the C++ demangler for Rust.  In most cases this

  14523.      does not cause any problems.  However, in an expression context,

  14524.      completing a generic function name will give syntactically invalid

  14525.      results.  This happens because Rust requires the '::' operator

  14526.      between the function name and its generic arguments.  For example,

  14527.      GDB might provide a completion like 'crate::f<u32>', where the

  14528.      parser would require 'crate::f::<u32>'.

  14529. 

  14530.    * As of this writing, the Rust compiler (version 1.8) has a few holes

  14531.      in the debugging information it generates.  These holes prevent

  14532.      certain features from being implemented by GDB:

  14533. 

  14534.         * Method calls cannot be made via traits.

  14535. 

  14536.         * Operator overloading is not implemented.

  14537. 

  14538.         * When debugging in a monomorphized function, you cannot use the

  14539.           generic type names.

  14540. 

  14541.         * The type 'Self' is not available.

  14542. 

  14543.         * 'use' statements are not available, so some names may not be

  14544.           available in the crate.

  14545. 

  14546. 

  14547. File: gdb.info,  Node: Modula-2,  Next: Ada,  Prev: Rust,  Up: Supported Languages

  14548. 

  14549. 15.4.9 Modula-2

  14550. ---------------

  14551. 

  14552. The extensions made to GDB to support Modula-2 only support output from

  14553. the GNU Modula-2 compiler (which is currently being developed).  Other

  14554. Modula-2 compilers are not currently supported, and attempting to debug

  14555. executables produced by them is most likely to give an error as GDB

  14556. reads in the executable's symbol table.

  14557. 

  14558. * Menu:

  14559. 

  14560. * M2 Operators::                Built-in operators

  14561. * Built-In Func/Proc::          Built-in functions and procedures

  14562. * M2 Constants::                Modula-2 constants

  14563. * M2 Types::                    Modula-2 types

  14564. * M2 Defaults::                 Default settings for Modula-2

  14565. * Deviations::                  Deviations from standard Modula-2

  14566. * M2 Checks::                   Modula-2 type and range checks

  14567. * M2 Scope::                    The scope operators '::' and '.'

  14568. * GDB/M2::                      GDB and Modula-2

  14569. 

  14570. 

  14571. File: gdb.info,  Node: M2 Operators,  Next: Built-In Func/Proc,  Up: Modula-2

  14572. 

  14573. 15.4.9.1 Operators

  14574. ..................

  14575. 

  14576. Operators must be defined on values of specific types.  For instance,

  14577. '+' is defined on numbers, but not on structures.  Operators are often

  14578. defined on groups of types.  For the purposes of Modula-2, the following

  14579. definitions hold:

  14580. 

  14581.    * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their

  14582.      subranges.

  14583. 

  14584.    * _Character types_ consist of 'CHAR' and its subranges.

  14585. 

  14586.    * _Floating-point types_ consist of 'REAL'.

  14587. 

  14588.    * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'.

  14589. 

  14590.    * _Scalar types_ consist of all of the above.

  14591. 

  14592.    * _Set types_ consist of 'SET' and 'BITSET' types.

  14593. 

  14594.    * _Boolean types_ consist of 'BOOLEAN'.

  14595. 

  14596. The following operators are supported, and appear in order of increasing

  14597. precedence:

  14598. 

  14599. ','

  14600.      Function argument or array index separator.

  14601. 

  14602. ':='

  14603.      Assignment.  The value of VAR ':=' VALUE is VALUE.

  14604. 

  14605. '<, >'

  14606.      Less than, greater than on integral, floating-point, or enumerated

  14607.      types.

  14608. 

  14609. '<=, >='

  14610.      Less than or equal to, greater than or equal to on integral,

  14611.      floating-point and enumerated types, or set inclusion on set types.

  14612.      Same precedence as '<'.

  14613. 

  14614. '=, <>, #'

  14615.      Equality and two ways of expressing inequality, valid on scalar

  14616.      types.  Same precedence as '<'.  In GDB scripts, only '<>' is

  14617.      available for inequality, since '#' conflicts with the script

  14618.      comment character.

  14619. 

  14620. 'IN'

  14621.      Set membership.  Defined on set types and the types of their

  14622.      members.  Same precedence as '<'.

  14623. 

  14624. 'OR'

  14625.      Boolean disjunction.  Defined on boolean types.

  14626. 

  14627. 'AND, &'

  14628.      Boolean conjunction.  Defined on boolean types.

  14629. 

  14630. '@'

  14631.      The GDB "artificial array" operator (*note Expressions:

  14632.      Expressions.).

  14633. 

  14634. '+, -'

  14635.      Addition and subtraction on integral and floating-point types, or

  14636.      union and difference on set types.

  14637. 

  14638. '*'

  14639.      Multiplication on integral and floating-point types, or set

  14640.      intersection on set types.

  14641. 

  14642. '/'

  14643.      Division on floating-point types, or symmetric set difference on

  14644.      set types.  Same precedence as '*'.

  14645. 

  14646. 'DIV, MOD'

  14647.      Integer division and remainder.  Defined on integral types.  Same

  14648.      precedence as '*'.

  14649. 

  14650. '-'

  14651.      Negative.  Defined on 'INTEGER' and 'REAL' data.

  14652. 

  14653. '^'

  14654.      Pointer dereferencing.  Defined on pointer types.

  14655. 

  14656. 'NOT'

  14657.      Boolean negation.  Defined on boolean types.  Same precedence as

  14658.      '^'.

  14659. 

  14660. '.'

  14661.      'RECORD' field selector.  Defined on 'RECORD' data.  Same

  14662.      precedence as '^'.

  14663. 

  14664. '[]'

  14665.      Array indexing.  Defined on 'ARRAY' data.  Same precedence as '^'.

  14666. 

  14667. '()'

  14668.      Procedure argument list.  Defined on 'PROCEDURE' objects.  Same

  14669.      precedence as '^'.

  14670. 

  14671. '::, .'

  14672.      GDB and Modula-2 scope operators.

  14673. 

  14674.      _Warning:_ Set expressions and their operations are not yet

  14675.      supported, so GDB treats the use of the operator 'IN', or the use

  14676.      of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>='

  14677.      on sets as an error.

  14678. 

  14679. 

  14680. File: gdb.info,  Node: Built-In Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2

  14681. 

  14682. 15.4.9.2 Built-in Functions and Procedures

  14683. ..........................................

  14684. 

  14685. Modula-2 also makes available several built-in procedures and functions.

  14686. In describing these, the following metavariables are used:

  14687. 

  14688. A

  14689.      represents an 'ARRAY' variable.

  14690. 

  14691. C

  14692.      represents a 'CHAR' constant or variable.

  14693. 

  14694. I

  14695.      represents a variable or constant of integral type.

  14696. 

  14697. M

  14698.      represents an identifier that belongs to a set.  Generally used in

  14699.      the same function with the metavariable S.  The type of S should be

  14700.      'SET OF MTYPE' (where MTYPE is the type of M).

  14701. 

  14702. N

  14703.      represents a variable or constant of integral or floating-point

  14704.      type.

  14705. 

  14706. R

  14707.      represents a variable or constant of floating-point type.

  14708. 

  14709. T

  14710.      represents a type.

  14711. 

  14712. V

  14713.      represents a variable.

  14714. 

  14715. X

  14716.      represents a variable or constant of one of many types.  See the

  14717.      explanation of the function for details.

  14718. 

  14719.    All Modula-2 built-in procedures also return a result, described

  14720. below.

  14721. 

  14722. 'ABS(N)'

  14723.      Returns the absolute value of N.

  14724. 

  14725. 'CAP(C)'

  14726.      If C is a lower case letter, it returns its upper case equivalent,

  14727.      otherwise it returns its argument.

  14728. 

  14729. 'CHR(I)'

  14730.      Returns the character whose ordinal value is I.

  14731. 

  14732. 'DEC(V)'

  14733.      Decrements the value in the variable V by one.  Returns the new

  14734.      value.

  14735. 

  14736. 'DEC(V,I)'

  14737.      Decrements the value in the variable V by I.  Returns the new

  14738.      value.

  14739. 

  14740. 'EXCL(M,S)'

  14741.      Removes the element M from the set S.  Returns the new set.

  14742. 

  14743. 'FLOAT(I)'

  14744.      Returns the floating point equivalent of the integer I.

  14745. 

  14746. 'HIGH(A)'

  14747.      Returns the index of the last member of A.

  14748. 

  14749. 'INC(V)'

  14750.      Increments the value in the variable V by one.  Returns the new

  14751.      value.

  14752. 

  14753. 'INC(V,I)'

  14754.      Increments the value in the variable V by I.  Returns the new

  14755.      value.

  14756. 

  14757. 'INCL(M,S)'

  14758.      Adds the element M to the set S if it is not already there.

  14759.      Returns the new set.

  14760. 

  14761. 'MAX(T)'

  14762.      Returns the maximum value of the type T.

  14763. 

  14764. 'MIN(T)'

  14765.      Returns the minimum value of the type T.

  14766. 

  14767. 'ODD(I)'

  14768.      Returns boolean TRUE if I is an odd number.

  14769. 

  14770. 'ORD(X)'

  14771.      Returns the ordinal value of its argument.  For example, the

  14772.      ordinal value of a character is its ASCII value (on machines

  14773.      supporting the ASCII character set).  The argument X must be of an

  14774.      ordered type, which include integral, character and enumerated

  14775.      types.

  14776. 

  14777. 'SIZE(X)'

  14778.      Returns the size of its argument.  The argument X can be a variable

  14779.      or a type.

  14780. 

  14781. 'TRUNC(R)'

  14782.      Returns the integral part of R.

  14783. 

  14784. 'TSIZE(X)'

  14785.      Returns the size of its argument.  The argument X can be a variable

  14786.      or a type.

  14787. 

  14788. 'VAL(T,I)'

  14789.      Returns the member of the type T whose ordinal value is I.

  14790. 

  14791.      _Warning:_ Sets and their operations are not yet supported, so GDB

  14792.      treats the use of procedures 'INCL' and 'EXCL' as an error.

  14793. 

  14794. 

  14795. File: gdb.info,  Node: M2 Constants,  Next: M2 Types,  Prev: Built-In Func/Proc,  Up: Modula-2

  14796. 

  14797. 15.4.9.3 Constants

  14798. ..................

  14799. 

  14800. GDB allows you to express the constants of Modula-2 in the following

  14801. ways:

  14802. 

  14803.    * Integer constants are simply a sequence of digits.  When used in an

  14804.      expression, a constant is interpreted to be type-compatible with

  14805.      the rest of the expression.  Hexadecimal integers are specified by

  14806.      a trailing 'H', and octal integers by a trailing 'B'.

  14807. 

  14808.    * Floating point constants appear as a sequence of digits, followed

  14809.      by a decimal point and another sequence of digits.  An optional

  14810.      exponent can then be specified, in the form 'E[+|-]NNN', where

  14811.      '[+|-]NNN' is the desired exponent.  All of the digits of the

  14812.      floating point constant must be valid decimal (base 10) digits.

  14813. 

  14814.    * Character constants consist of a single character enclosed by a

  14815.      pair of like quotes, either single (''') or double ('"').  They may

  14816.      also be expressed by their ordinal value (their ASCII value,

  14817.      usually) followed by a 'C'.

  14818. 

  14819.    * String constants consist of a sequence of characters enclosed by a

  14820.      pair of like quotes, either single (''') or double ('"').  Escape

  14821.      sequences in the style of C are also allowed.  *Note C and C++

  14822.      Constants: C Constants, for a brief explanation of escape

  14823.      sequences.

  14824. 

  14825.    * Enumerated constants consist of an enumerated identifier.

  14826. 

  14827.    * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'.

  14828. 

  14829.    * Pointer constants consist of integral values only.

  14830. 

  14831.    * Set constants are not yet supported.

  14832. 

  14833. 

  14834. File: gdb.info,  Node: M2 Types,  Next: M2 Defaults,  Prev: M2 Constants,  Up: Modula-2

  14835. 

  14836. 15.4.9.4 Modula-2 Types

  14837. .......................

  14838. 

  14839. Currently GDB can print the following data types in Modula-2 syntax:

  14840. array types, record types, set types, pointer types, procedure types,

  14841. enumerated types, subrange types and base types.  You can also print the

  14842. contents of variables declared using these type.  This section gives a

  14843. number of simple source code examples together with sample GDB sessions.

  14844. 

  14845.    The first example contains the following section of code:

  14846. 

  14847.      VAR

  14848.         s: SET OF CHAR ;

  14849.         r: [20..40] ;

  14850. 

  14851. and you can request GDB to interrogate the type and value of 'r' and

  14852. 's'.

  14853. 

  14854.      (gdb) print s

  14855.      {'A'..'C', 'Z'}

  14856.      (gdb) ptype s

  14857.      SET OF CHAR

  14858.      (gdb) print r

  14859.      21

  14860.      (gdb) ptype r

  14861.      [20..40]

  14862. 

  14863. Likewise if your source code declares 's' as:

  14864. 

  14865.      VAR

  14866.         s: SET ['A'..'Z'] ;

  14867. 

  14868. then you may query the type of 's' by:

  14869. 

  14870.      (gdb) ptype s

  14871.      type = SET ['A'..'Z']

  14872. 

  14873. Note that at present you cannot interactively manipulate set expressions

  14874. using the debugger.

  14875. 

  14876.    The following example shows how you might declare an array in

  14877. Modula-2 and how you can interact with GDB to print its type and

  14878. contents:

  14879. 

  14880.      VAR

  14881.         s: ARRAY [-10..10] OF CHAR ;

  14882. 

  14883.      (gdb) ptype s

  14884.      ARRAY [-10..10] OF CHAR

  14885. 

  14886.    Note that the array handling is not yet complete and although the

  14887. type is printed correctly, expression handling still assumes that all

  14888. arrays have a lower bound of zero and not '-10' as in the example above.

  14889. 

  14890.    Here are some more type related Modula-2 examples:

  14891. 

  14892.      TYPE

  14893.         colour = (blue, red, yellow, green) ;

  14894.         t = [blue..yellow] ;

  14895.      VAR

  14896.         s: t ;

  14897.      BEGIN

  14898.         s := blue ;

  14899. 

  14900. The GDB interaction shows how you can query the data type and value of a

  14901. variable.

  14902. 

  14903.      (gdb) print s

  14904.      $1 = blue

  14905.      (gdb) ptype t

  14906.      type = [blue..yellow]

  14907. 

  14908. In this example a Modula-2 array is declared and its contents displayed.

  14909. Observe that the contents are written in the same way as their 'C'

  14910. counterparts.

  14911. 

  14912.      VAR

  14913.         s: ARRAY [1..5] OF CARDINAL ;

  14914.      BEGIN

  14915.         s[1] := 1 ;

  14916. 

  14917.      (gdb) print s

  14918.      $1 = {1, 0, 0, 0, 0}

  14919.      (gdb) ptype s

  14920.      type = ARRAY [1..5] OF CARDINAL

  14921. 

  14922.    The Modula-2 language interface to GDB also understands pointer types

  14923. as shown in this example:

  14924. 

  14925.      VAR

  14926.         s: POINTER TO ARRAY [1..5] OF CARDINAL ;

  14927.      BEGIN

  14928.         NEW(s) ;

  14929.         s^[1] := 1 ;

  14930. 

  14931. and you can request that GDB describes the type of 's'.

  14932. 

  14933.      (gdb) ptype s

  14934.      type = POINTER TO ARRAY [1..5] OF CARDINAL

  14935. 

  14936.    GDB handles compound types as we can see in this example.  Here we

  14937. combine array types, record types, pointer types and subrange types:

  14938. 

  14939.      TYPE

  14940.         foo = RECORD

  14941.                  f1: CARDINAL ;

  14942.                  f2: CHAR ;

  14943.                  f3: myarray ;

  14944.               END ;

  14945. 

  14946.         myarray = ARRAY myrange OF CARDINAL ;

  14947.         myrange = [-2..2] ;

  14948.      VAR

  14949.         s: POINTER TO ARRAY myrange OF foo ;

  14950. 

  14951. and you can ask GDB to describe the type of 's' as shown below.

  14952. 

  14953.      (gdb) ptype s

  14954.      type = POINTER TO ARRAY [-2..2] OF foo = RECORD

  14955.          f1 : CARDINAL;

  14956.          f2 : CHAR;

  14957.          f3 : ARRAY [-2..2] OF CARDINAL;

  14958.      END

  14959. 

  14960. 

  14961. File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Types,  Up: Modula-2

  14962. 

  14963. 15.4.9.5 Modula-2 Defaults

  14964. ..........................

  14965. 

  14966. If type and range checking are set automatically by GDB, they both

  14967. default to 'on' whenever the working language changes to Modula-2.  This

  14968. happens regardless of whether you or GDB selected the working language.

  14969. 

  14970.    If you allow GDB to set the language automatically, then entering

  14971. code compiled from a file whose name ends with '.mod' sets the working

  14972. language to Modula-2.  *Note Having GDB Infer the Source Language:

  14973. Automatically, for further details.

  14974. 

  14975. 

  14976. File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2

  14977. 

  14978. 15.4.9.6 Deviations from Standard Modula-2

  14979. ..........................................

  14980. 

  14981. A few changes have been made to make Modula-2 programs easier to debug.

  14982. This is done primarily via loosening its type strictness:

  14983. 

  14984.    * Unlike in standard Modula-2, pointer constants can be formed by

  14985.      integers.  This allows you to modify pointer variables during

  14986.      debugging.  (In standard Modula-2, the actual address contained in

  14987.      a pointer variable is hidden from you; it can only be modified

  14988.      through direct assignment to another pointer variable or expression

  14989.      that returned a pointer.)

  14990. 

  14991.    * C escape sequences can be used in strings and characters to

  14992.      represent non-printable characters.  GDB prints out strings with

  14993.      these escape sequences embedded.  Single non-printable characters

  14994.      are printed using the 'CHR(NNN)' format.

  14995. 

  14996.    * The assignment operator (':=') returns the value of its right-hand

  14997.      argument.

  14998. 

  14999.    * All built-in procedures both modify _and_ return their argument.

  15000. 

  15001. 

  15002. File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2

  15003. 

  15004. 15.4.9.7 Modula-2 Type and Range Checks

  15005. .......................................

  15006. 

  15007.      _Warning:_ in this release, GDB does not yet perform type or range

  15008.      checking.

  15009. 

  15010.    GDB considers two Modula-2 variables type equivalent if:

  15011. 

  15012.    * They are of types that have been declared equivalent via a 'TYPE T1

  15013.      = T2' statement

  15014. 

  15015.    * They have been declared on the same line.  (Note: This is true of

  15016.      the GNU Modula-2 compiler, but it may not be true of other

  15017.      compilers.)

  15018. 

  15019.    As long as type checking is enabled, any attempt to combine variables

  15020. whose types are not equivalent is an error.

  15021. 

  15022.    Range checking is done on all mathematical operations, assignment,

  15023. array index bounds, and all built-in functions and procedures.

  15024. 

  15025. 

  15026. File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2

  15027. 

  15028. 15.4.9.8 The Scope Operators '::' and '.'

  15029. .........................................

  15030. 

  15031. There are a few subtle differences between the Modula-2 scope operator

  15032. ('.') and the GDB scope operator ('::').  The two have similar syntax:

  15033. 

  15034. 

  15035.      MODULE . ID

  15036.      SCOPE :: ID

  15037. 

  15038. where SCOPE is the name of a module or a procedure, MODULE the name of a

  15039. module, and ID is any declared identifier within your program, except

  15040. another module.

  15041. 

  15042.    Using the '::' operator makes GDB search the scope specified by SCOPE

  15043. for the identifier ID.  If it is not found in the specified scope, then

  15044. GDB searches all scopes enclosing the one specified by SCOPE.

  15045. 

  15046.    Using the '.' operator makes GDB search the current scope for the

  15047. identifier specified by ID that was imported from the definition module

  15048. specified by MODULE.  With this operator, it is an error if the

  15049. identifier ID was not imported from definition module MODULE, or if ID

  15050. is not an identifier in MODULE.

  15051. 

  15052. 

  15053. File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2

  15054. 

  15055. 15.4.9.9 GDB and Modula-2

  15056. .........................

  15057. 

  15058. Some GDB commands have little use when debugging Modula-2 programs.

  15059. Five subcommands of 'set print' and 'show print' apply specifically to C

  15060. and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'.  The

  15061. first four apply to C++, and the last to the C 'union' type, which has

  15062. no direct analogue in Modula-2.

  15063. 

  15064.    The '@' operator (*note Expressions: Expressions.), while available

  15065. with any language, is not useful with Modula-2.  Its intent is to aid

  15066. the debugging of "dynamic arrays", which cannot be created in Modula-2

  15067. as they can in C or C++.  However, because an address can be specified

  15068. by an integral constant, the construct '{TYPE}ADREXP' is still useful.

  15069. 

  15070.    In GDB scripts, the Modula-2 inequality operator '#' is interpreted

  15071. as the beginning of a comment.  Use '<>' instead.

  15072. 

  15073. 

  15074. File: gdb.info,  Node: Ada,  Prev: Modula-2,  Up: Supported Languages

  15075. 

  15076. 15.4.10 Ada

  15077. -----------

  15078. 

  15079. The extensions made to GDB for Ada only support output from the GNU Ada

  15080. (GNAT) compiler.  Other Ada compilers are not currently supported, and

  15081. attempting to debug executables produced by them is most likely to be

  15082. difficult.

  15083. 

  15084. * Menu:

  15085. 

  15086. * Ada Mode Intro::              General remarks on the Ada syntax

  15087.                                    and semantics supported by Ada mode

  15088.                                    in GDB.

  15089. * Omissions from Ada::          Restrictions on the Ada expression syntax.

  15090. * Additions to Ada::            Extensions of the Ada expression syntax.

  15091. * Overloading support for Ada:: Support for expressions involving overloaded

  15092.                                    subprograms.

  15093. * Stopping Before Main Program:: Debugging the program during elaboration.

  15094. * Ada Exceptions::              Ada Exceptions

  15095. * Ada Tasks::                   Listing and setting breakpoints in tasks.

  15096. * Ada Tasks and Core Files::    Tasking Support when Debugging Core Files

  15097. * Ravenscar Profile::           Tasking Support when using the Ravenscar

  15098.                                    Profile

  15099. * Ada Settings::                New settable GDB parameters for Ada.

  15100. * Ada Glitches::                Known peculiarities of Ada mode.

  15101. 

  15102. 

  15103. File: gdb.info,  Node: Ada Mode Intro,  Next: Omissions from Ada,  Up: Ada

  15104. 

  15105. 15.4.10.1 Introduction

  15106. ......................

  15107. 

  15108. The Ada mode of GDB supports a fairly large subset of Ada expression

  15109. syntax, with some extensions.  The philosophy behind the design of this

  15110. subset is

  15111. 

  15112.    * That GDB should provide basic literals and access to operations for

  15113.      arithmetic, dereferencing, field selection, indexing, and

  15114.      subprogram calls, leaving more sophisticated computations to

  15115.      subprograms written into the program (which therefore may be called

  15116.      from GDB).

  15117. 

  15118.    * That type safety and strict adherence to Ada language restrictions

  15119.      are not particularly important to the GDB user.

  15120. 

  15121.    * That brevity is important to the GDB user.

  15122. 

  15123.    Thus, for brevity, the debugger acts as if all names declared in

  15124. user-written packages are directly visible, even if they are not visible

  15125. according to Ada rules, thus making it unnecessary to fully qualify most

  15126. names with their packages, regardless of context.  Where this causes

  15127. ambiguity, GDB asks the user's intent.

  15128. 

  15129.    The debugger will start in Ada mode if it detects an Ada main

  15130. program.  As for other languages, it will enter Ada mode when stopped in

  15131. a program that was translated from an Ada source file.

  15132. 

  15133.    While in Ada mode, you may use '--' for comments.  This is useful

  15134. mostly for documenting command files.  The standard GDB comment ('#')

  15135. still works at the beginning of a line in Ada mode, but not in the

  15136. middle (to allow based literals).

  15137. 

  15138. 

  15139. File: gdb.info,  Node: Omissions from Ada,  Next: Additions to Ada,  Prev: Ada Mode Intro,  Up: Ada

  15140. 

  15141. 15.4.10.2 Omissions from Ada

  15142. ............................

  15143. 

  15144. Here are the notable omissions from the subset:

  15145. 

  15146.    * Only a subset of the attributes are supported:

  15147. 

  15148.         - 'First, 'Last, and 'Length on array objects (not on types and

  15149.           subtypes).

  15150. 

  15151.         - 'Min and 'Max.

  15152. 

  15153.         - 'Pos and 'Val.

  15154. 

  15155.         - 'Tag.

  15156. 

  15157.         - 'Range on array objects (not subtypes), but only as the right

  15158.           operand of the membership ('in') operator.

  15159. 

  15160.         - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT

  15161.           extension).

  15162. 

  15163.         - 'Address.

  15164. 

  15165.    * The names in 'Characters.Latin_1' are not available and

  15166.      concatenation is not implemented.  Thus, escape characters in

  15167.      strings are not currently available.

  15168. 

  15169.    * Equality tests ('=' and '/=') on arrays test for bitwise equality

  15170.      of representations.  They will generally work correctly for strings

  15171.      and arrays whose elements have integer or enumeration types.  They

  15172.      may not work correctly for arrays whose element types have

  15173.      user-defined equality, for arrays of real values (in particular,

  15174.      IEEE-conformant floating point, because of negative zeroes and

  15175.      NaNs), and for arrays whose elements contain unused bits with

  15176.      indeterminate values.

  15177. 

  15178.    * The other component-by-component array operations ('and', 'or',

  15179.      'xor', 'not', and relational tests other than equality) are not

  15180.      implemented.

  15181. 

  15182.    * There is limited support for array and record aggregates.  They are

  15183.      permitted only on the right sides of assignments, as in these

  15184.      examples:

  15185. 

  15186.           (gdb) set An_Array := (1, 2, 3, 4, 5, 6)

  15187.           (gdb) set An_Array := (1, others => 0)

  15188.           (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)

  15189.           (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))

  15190.           (gdb) set A_Record := (1, "Peter", True);

  15191.           (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)

  15192. 

  15193.      Changing a discriminant's value by assigning an aggregate has an

  15194.      undefined effect if that discriminant is used within the record.

  15195.      However, you can first modify discriminants by directly assigning

  15196.      to them (which normally would not be allowed in Ada), and then

  15197.      performing an aggregate assignment.  For example, given a variable

  15198.      'A_Rec' declared to have a type such as:

  15199. 

  15200.           type Rec (Len : Small_Integer := 0) is record

  15201.               Id : Integer;

  15202.               Vals : IntArray (1 .. Len);

  15203.           end record;

  15204. 

  15205.      you can assign a value with a different size of 'Vals' with two

  15206.      assignments:

  15207. 

  15208.           (gdb) set A_Rec.Len := 4

  15209.           (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))

  15210. 

  15211.      As this example also illustrates, GDB is very loose about the usual

  15212.      rules concerning aggregates.  You may leave out some of the

  15213.      components of an array or record aggregate (such as the 'Len'

  15214.      component in the assignment to 'A_Rec' above); they will retain

  15215.      their original values upon assignment.  You may freely use dynamic

  15216.      values as indices in component associations.  You may even use

  15217.      overlapping or redundant component associations, although which

  15218.      component values are assigned in such cases is not defined.

  15219. 

  15220.    * Calls to dispatching subprograms are not implemented.

  15221. 

  15222.    * The overloading algorithm is much more limited (i.e., less

  15223.      selective) than that of real Ada.  It makes only limited use of the

  15224.      context in which a subexpression appears to resolve its meaning,

  15225.      and it is much looser in its rules for allowing type matches.  As a

  15226.      result, some function calls will be ambiguous, and the user will be

  15227.      asked to choose the proper resolution.

  15228. 

  15229.    * The 'new' operator is not implemented.

  15230. 

  15231.    * Entry calls are not implemented.

  15232. 

  15233.    * Aside from printing, arithmetic operations on the native VAX

  15234.      floating-point formats are not supported.

  15235. 

  15236.    * It is not possible to slice a packed array.

  15237. 

  15238.    * The names 'True' and 'False', when not part of a qualified name,

  15239.      are interpreted as if implicitly prefixed by 'Standard', regardless

  15240.      of context.  Should your program redefine these names in a package

  15241.      or procedure (at best a dubious practice), you will have to use

  15242.      fully qualified names to access their new definitions.

  15243. 

  15244. 

  15245. File: gdb.info,  Node: Additions to Ada,  Next: Overloading support for Ada,  Prev: Omissions from Ada,  Up: Ada

  15246. 

  15247. 15.4.10.3 Additions to Ada

  15248. ..........................

  15249. 

  15250. As it does for other languages, GDB makes certain generic extensions to

  15251. Ada (*note Expressions::):

  15252. 

  15253.    * If the expression E is a variable residing in memory (typically a

  15254.      local variable or array element) and N is a positive integer, then

  15255.      'E@N' displays the values of E and the N-1 adjacent variables

  15256.      following it in memory as an array.  In Ada, this operator is

  15257.      generally not necessary, since its prime use is in displaying parts

  15258.      of an array, and slicing will usually do this in Ada.  However,

  15259.      there are occasional uses when debugging programs in which certain

  15260.      debugging information has been optimized away.

  15261. 

  15262.    * 'B::VAR' means "the variable named VAR that appears in function or

  15263.      file B."  When B is a file name, you must typically surround it in

  15264.      single quotes.

  15265. 

  15266.    * The expression '{TYPE} ADDR' means "the variable of type TYPE that

  15267.      appears at address ADDR."

  15268. 

  15269.    * A name starting with '$' is a convenience variable (*note

  15270.      Convenience Vars::) or a machine register (*note Registers::).

  15271. 

  15272.    In addition, GDB provides a few other shortcuts and outright

  15273. additions specific to Ada:

  15274. 

  15275.    * The assignment statement is allowed as an expression, returning its

  15276.      right-hand operand as its value.  Thus, you may enter

  15277. 

  15278.           (gdb) set x := y + 3

  15279.           (gdb) print A(tmp := y + 1)

  15280. 

  15281.    * The semicolon is allowed as an "operator," returning as its value

  15282.      the value of its right-hand operand.  This allows, for example,

  15283.      complex conditional breaks:

  15284. 

  15285.           (gdb) break f

  15286.           (gdb) condition 1 (report(i); k += 1; A(k) > 100)

  15287. 

  15288.    * Rather than use catenation and symbolic character names to

  15289.      introduce special characters into strings, one may instead use a

  15290.      special bracket notation, which is also used to print strings.  A

  15291.      sequence of characters of the form '["XX"]' within a string or

  15292.      character literal denotes the (single) character whose numeric

  15293.      encoding is XX in hexadecimal.  The sequence of characters '["""]'

  15294.      also denotes a single quotation mark in strings.  For example,

  15295.              "One line.["0a"]Next line.["0a"]"

  15296.      contains an ASCII newline character ('Ada.Characters.Latin_1.LF')

  15297.      after each period.

  15298. 

  15299.    * The subtype used as a prefix for the attributes 'Pos, 'Min, and

  15300.      'Max is optional (and is ignored in any case).  For example, it is

  15301.      valid to write

  15302. 

  15303.           (gdb) print 'max(x, y)

  15304. 

  15305.    * When printing arrays, GDB uses positional notation when the array

  15306.      has a lower bound of 1, and uses a modified named notation

  15307.      otherwise.  For example, a one-dimensional array of three integers

  15308.      with a lower bound of 3 might print as

  15309. 

  15310.           (3 => 10, 17, 1)

  15311. 

  15312.      That is, in contrast to valid Ada, only the first component has a

  15313.      '=>' clause.

  15314. 

  15315.    * You may abbreviate attributes in expressions with any unique,

  15316.      multi-character subsequence of their names (an exact match gets

  15317.      preference).  For example, you may use a'len, a'gth, or a'lh in

  15318.      place of a'length.

  15319. 

  15320.    * Since Ada is case-insensitive, the debugger normally maps

  15321.      identifiers you type to lower case.  The GNAT compiler uses

  15322.      upper-case characters for some of its internal identifiers, which

  15323.      are normally of no interest to users.  For the rare occasions when

  15324.      you actually have to look at them, enclose them in angle brackets

  15325.      to avoid the lower-case mapping.  For example,

  15326.           (gdb) print <JMPBUF_SAVE>[0]

  15327. 

  15328.    * Printing an object of class-wide type or dereferencing an

  15329.      access-to-class-wide value will display all the components of the

  15330.      object's specific type (as indicated by its run-time tag).

  15331.      Likewise, component selection on such a value will operate on the

  15332.      specific type of the object.

  15333. 

  15334. 

  15335. File: gdb.info,  Node: Overloading support for Ada,  Next: Stopping Before Main Program,  Prev: Additions to Ada,  Up: Ada

  15336. 

  15337. 15.4.10.4 Overloading support for Ada

  15338. .....................................

  15339. 

  15340. The debugger supports limited overloading.  Given a subprogram call in

  15341. which the function symbol has multiple definitions, it will use the

  15342. number of actual parameters and some information about their types to

  15343. attempt to narrow the set of definitions.  It also makes very limited

  15344. use of context, preferring procedures to functions in the context of the

  15345. 'call' command, and functions to procedures elsewhere.

  15346. 

  15347.    If, after narrowing, the set of matching definitions still contains

  15348. more than one definition, GDB will display a menu to query which one it

  15349. should use, for instance:

  15350. 

  15351.      (gdb) print f(1)

  15352.      Multiple matches for f

  15353.      [0] cancel

  15354.      [1] foo.f (integer) return boolean at foo.adb:23

  15355.      [2] foo.f (foo.new_integer) return boolean at foo.adb:28

  15356.      >

  15357. 

  15358.    In this case, just select one menu entry either to cancel expression

  15359. evaluation (type '0' and press <RET>) or to continue evaluation with a

  15360. specific instance (type the corresponding number and press <RET>).

  15361. 

  15362.    Here are a couple of commands to customize GDB's behavior in this

  15363. case:

  15364. 

  15365. 'set ada print-signatures'

  15366.      Control whether parameter types and return types are displayed in

  15367.      overloads selection menus.  It is 'on' by default.  *Note

  15368.      Overloading support for Ada::.

  15369. 

  15370. 'show ada print-signatures'

  15371.      Show the current setting for displaying parameter types and return

  15372.      types in overloads selection menu.  *Note Overloading support for

  15373.      Ada::.

  15374. 

  15375. 

  15376. File: gdb.info,  Node: Stopping Before Main Program,  Next: Ada Exceptions,  Prev: Overloading support for Ada,  Up: Ada

  15377. 

  15378. 15.4.10.5 Stopping at the Very Beginning

  15379. ........................................

  15380. 

  15381. It is sometimes necessary to debug the program during elaboration, and

  15382. before reaching the main procedure.  As defined in the Ada Reference

  15383. Manual, the elaboration code is invoked from a procedure called

  15384. 'adainit'.  To run your program up to the beginning of elaboration,

  15385. simply use the following two commands: 'tbreak adainit' and 'run'.

  15386. 

  15387. 

  15388. File: gdb.info,  Node: Ada Exceptions,  Next: Ada Tasks,  Prev: Stopping Before Main Program,  Up: Ada

  15389. 

  15390. 15.4.10.6 Ada Exceptions

  15391. ........................

  15392. 

  15393. A command is provided to list all Ada exceptions:

  15394. 

  15395. 'info exceptions'

  15396. 'info exceptions REGEXP'

  15397.      The 'info exceptions' command allows you to list all Ada exceptions

  15398.      defined within the program being debugged, as well as their

  15399.      addresses.  With a regular expression, REGEXP, as argument, only

  15400.      those exceptions whose names match REGEXP are listed.

  15401. 

  15402.    Below is a small example, showing how the command can be used, first

  15403. without argument, and next with a regular expression passed as an

  15404. argument.

  15405. 

  15406.      (gdb) info exceptions

  15407.      All defined Ada exceptions:

  15408.      constraint_error: 0x613da0

  15409.      program_error: 0x613d20

  15410.      storage_error: 0x613ce0

  15411.      tasking_error: 0x613ca0

  15412.      const.aint_global_e: 0x613b00

  15413.      (gdb) info exceptions const.aint

  15414.      All Ada exceptions matching regular expression "const.aint":

  15415.      constraint_error: 0x613da0

  15416.      const.aint_global_e: 0x613b00

  15417. 

  15418.    It is also possible to ask GDB to stop your program's execution when

  15419. an exception is raised.  For more details, see *note Set Catchpoints::.

  15420. 

  15421. 

  15422. File: gdb.info,  Node: Ada Tasks,  Next: Ada Tasks and Core Files,  Prev: Ada Exceptions,  Up: Ada

  15423. 

  15424. 15.4.10.7 Extensions for Ada Tasks

  15425. ..................................

  15426. 

  15427. Support for Ada tasks is analogous to that for threads (*note

  15428. Threads::).  GDB provides the following task-related commands:

  15429. 

  15430. 'info tasks'

  15431.      This command shows a list of current Ada tasks, as in the following

  15432.      example:

  15433. 

  15434.           (gdb) info tasks

  15435.             ID       TID P-ID Pri State                 Name

  15436.              1   8088000   0   15 Child Activation Wait main_task

  15437.              2   80a4000   1   15 Accept Statement      b

  15438.              3   809a800   1   15 Child Activation Wait a

  15439.           *  4   80ae800   3   15 Runnable              c

  15440. 

  15441. 

  15442.      In this listing, the asterisk before the last task indicates it to

  15443.      be the task currently being inspected.

  15444. 

  15445.      ID

  15446.           Represents GDB's internal task number.

  15447. 

  15448.      TID

  15449.           The Ada task ID.

  15450. 

  15451.      P-ID

  15452.           The parent's task ID (GDB's internal task number).

  15453. 

  15454.      Pri

  15455.           The base priority of the task.

  15456. 

  15457.      State

  15458.           Current state of the task.

  15459. 

  15460.           'Unactivated'

  15461.                The task has been created but has not been activated.  It

  15462.                cannot be executing.

  15463. 

  15464.           'Runnable'

  15465.                The task is not blocked for any reason known to Ada.  (It

  15466.                may be waiting for a mutex, though.)  It is conceptually

  15467.                "executing" in normal mode.

  15468. 

  15469.           'Terminated'

  15470.                The task is terminated, in the sense of ARM 9.3 (5).  Any

  15471.                dependents that were waiting on terminate alternatives

  15472.                have been awakened and have terminated themselves.

  15473. 

  15474.           'Child Activation Wait'

  15475.                The task is waiting for created tasks to complete

  15476.                activation.

  15477. 

  15478.           'Accept Statement'

  15479.                The task is waiting on an accept or selective wait

  15480.                statement.

  15481. 

  15482.           'Waiting on entry call'

  15483.                The task is waiting on an entry call.

  15484. 

  15485.           'Async Select Wait'

  15486.                The task is waiting to start the abortable part of an

  15487.                asynchronous select statement.

  15488. 

  15489.           'Delay Sleep'

  15490.                The task is waiting on a select statement with only a

  15491.                delay alternative open.

  15492. 

  15493.           'Child Termination Wait'

  15494.                The task is sleeping having completed a master within

  15495.                itself, and is waiting for the tasks dependent on that

  15496.                master to become terminated or waiting on a terminate

  15497.                Phase.

  15498. 

  15499.           'Wait Child in Term Alt'

  15500.                The task is sleeping waiting for tasks on terminate

  15501.                alternatives to finish terminating.

  15502. 

  15503.           'Accepting RV with TASKNO'

  15504.                The task is accepting a rendez-vous with the task TASKNO.

  15505. 

  15506.      Name

  15507.           Name of the task in the program.

  15508. 

  15509. 'info task TASKNO'

  15510.      This command shows detailed informations on the specified task, as

  15511.      in the following example:

  15512.           (gdb) info tasks

  15513.             ID       TID P-ID Pri State                  Name

  15514.              1   8077880    0  15 Child Activation Wait  main_task

  15515.           *  2   807c468    1  15 Runnable               task_1

  15516.           (gdb) info task 2

  15517.           Ada Task: 0x807c468

  15518.           Name: "task_1"

  15519.           Thread: 0

  15520.           LWP: 0x1fac

  15521.           Parent: 1 ("main_task")

  15522.           Base Priority: 15

  15523.           State: Runnable

  15524. 

  15525. 'task'

  15526.      This command prints the ID and name of the current task.

  15527. 

  15528.           (gdb) info tasks

  15529.             ID       TID P-ID Pri State                  Name

  15530.              1   8077870    0  15 Child Activation Wait  main_task

  15531.           *  2   807c458    1  15 Runnable               some_task

  15532.           (gdb) task

  15533.           [Current task is 2 "some_task"]

  15534. 

  15535. 'task TASKNO'

  15536.      This command is like the 'thread THREAD-ID' command (*note

  15537.      Threads::).  It switches the context of debugging from the current

  15538.      task to the given task.

  15539. 

  15540.           (gdb) info tasks

  15541.             ID       TID P-ID Pri State                  Name

  15542.              1   8077870    0  15 Child Activation Wait  main_task

  15543.           *  2   807c458    1  15 Runnable               some_task

  15544.           (gdb) task 1

  15545.           [Switching to task 1 "main_task"]

  15546.           #0  0x8067726 in pthread_cond_wait ()

  15547.           (gdb) bt

  15548.           #0  0x8067726 in pthread_cond_wait ()

  15549.           #1  0x8056714 in system.os_interface.pthread_cond_wait ()

  15550.           #2  0x805cb63 in system.task_primitives.operations.sleep ()

  15551.           #3  0x806153e in system.tasking.stages.activate_tasks ()

  15552.           #4  0x804aacc in un () at un.adb:5

  15553. 

  15554. 'break LOCATION task TASKNO'

  15555. 'break LOCATION task TASKNO if ...'

  15556.      These commands are like the 'break ... thread ...' command (*note

  15557.      Thread Stops::).  The LOCATION argument specifies source lines, as

  15558.      described in *note Specify Location::.

  15559. 

  15560.      Use the qualifier 'task TASKNO' with a breakpoint command to

  15561.      specify that you only want GDB to stop the program when a

  15562.      particular Ada task reaches this breakpoint.  The TASKNO is one of

  15563.      the numeric task identifiers assigned by GDB, shown in the first

  15564.      column of the 'info tasks' display.

  15565. 

  15566.      If you do not specify 'task TASKNO' when you set a breakpoint, the

  15567.      breakpoint applies to _all_ tasks of your program.

  15568. 

  15569.      You can use the 'task' qualifier on conditional breakpoints as

  15570.      well; in this case, place 'task TASKNO' before the breakpoint

  15571.      condition (before the 'if').

  15572. 

  15573.      For example,

  15574. 

  15575.           (gdb) info tasks

  15576.             ID       TID P-ID Pri State                 Name

  15577.              1 140022020   0   15 Child Activation Wait main_task

  15578.              2 140045060   1   15 Accept/Select Wait    t2

  15579.              3 140044840   1   15 Runnable              t1

  15580.           *  4 140056040   1   15 Runnable              t3

  15581.           (gdb) b 15 task 2

  15582.           Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.

  15583.           (gdb) cont

  15584.           Continuing.

  15585.           task # 1 running

  15586.           task # 2 running

  15587. 

  15588.           Breakpoint 5, test_task_debug () at test_task_debug.adb:15

  15589.           15               flush;

  15590.           (gdb) info tasks

  15591.             ID       TID P-ID Pri State                 Name

  15592.              1 140022020   0   15 Child Activation Wait main_task

  15593.           *  2 140045060   1   15 Runnable              t2

  15594.              3 140044840   1   15 Runnable              t1

  15595.              4 140056040   1   15 Delay Sleep           t3

  15596. 

  15597. 

  15598. File: gdb.info,  Node: Ada Tasks and Core Files,  Next: Ravenscar Profile,  Prev: Ada Tasks,  Up: Ada

  15599. 

  15600. 15.4.10.8 Tasking Support when Debugging Core Files

  15601. ...................................................

  15602. 

  15603. When inspecting a core file, as opposed to debugging a live program,

  15604. tasking support may be limited or even unavailable, depending on the

  15605. platform being used.  For instance, on x86-linux, the list of tasks is

  15606. available, but task switching is not supported.

  15607. 

  15608.    On certain platforms, the debugger needs to perform some memory

  15609. writes in order to provide Ada tasking support.  When inspecting a core

  15610. file, this means that the core file must be opened with read-write

  15611. privileges, using the command '"set write on"' (*note Patching::).

  15612. Under these circumstances, you should make a backup copy of the core

  15613. file before inspecting it with GDB.

  15614. 

  15615. 

  15616. File: gdb.info,  Node: Ravenscar Profile,  Next: Ada Settings,  Prev: Ada Tasks and Core Files,  Up: Ada

  15617. 

  15618. 15.4.10.9 Tasking Support when using the Ravenscar Profile

  15619. ..........................................................

  15620. 

  15621. The "Ravenscar Profile" is a subset of the Ada tasking features,

  15622. specifically designed for systems with safety-critical real-time

  15623. requirements.

  15624. 

  15625. 'set ravenscar task-switching on'

  15626.      Allows task switching when debugging a program that uses the

  15627.      Ravenscar Profile.  This is the default.

  15628. 

  15629. 'set ravenscar task-switching off'

  15630.      Turn off task switching when debugging a program that uses the

  15631.      Ravenscar Profile.  This is mostly intended to disable the code

  15632.      that adds support for the Ravenscar Profile, in case a bug in

  15633.      either GDB or in the Ravenscar runtime is preventing GDB from

  15634.      working properly.  To be effective, this command should be run

  15635.      before the program is started.

  15636. 

  15637. 'show ravenscar task-switching'

  15638.      Show whether it is possible to switch from task to task in a

  15639.      program using the Ravenscar Profile.

  15640. 

  15641.    When Ravenscar task-switching is enabled, Ravenscar tasks are

  15642. announced by GDB as if they were threads:

  15643. 

  15644.      (gdb) continue

  15645.      [New Ravenscar Thread 0x2b8f0]

  15646. 

  15647.    Both Ravenscar tasks and the underlying CPU threads will show up in

  15648. the output of 'info threads':

  15649. 

  15650.      (gdb) info threads

  15651.        Id   Target Id                  Frame

  15652.        1    Thread 1 (CPU#0 [running]) simple () at simple.adb:10

  15653.        2    Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices ()

  15654.        3    Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices ()

  15655.        4    Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle ()

  15656.      * 5    Ravenscar Thread 0x2b8f0   simple () at simple.adb:10

  15657.        6    Ravenscar Thread 0x2f150   0x000000000000c6ec in system.task_primitives.operations.idle ()

  15658. 

  15659.    One known limitation of the Ravenscar support in GDB is that it isn't

  15660. currently possible to single-step through the runtime initialization

  15661. sequence.  If you need to debug this code, you should use 'set ravenscar

  15662. task-switching off'.

  15663. 

  15664. 

  15665. File: gdb.info,  Node: Ada Settings,  Next: Ada Glitches,  Prev: Ravenscar Profile,  Up: Ada

  15666. 

  15667. 15.4.10.10 Ada Settings

  15668. .......................

  15669. 

  15670. 'set varsize-limit SIZE'

  15671.      Prevent GDB from attempting to evaluate objects whose size is above

  15672.      the given limit (SIZE) when those sizes are computed from run-time

  15673.      quantities.  This is typically the case when the object has a

  15674.      variable size, such as an array whose bounds are not known at

  15675.      compile time for example.  Setting SIZE to 'unlimited' removes the

  15676.      size limitation.  By default, the limit is about 65KB.

  15677. 

  15678.      The purpose of having such a limit is to prevent GDB from trying to

  15679.      grab enormous chunks of virtual memory when asked to evaluate a

  15680.      quantity whose bounds have been corrupted or have not yet been

  15681.      fully initialized.  The limit applies to the results of some

  15682.      subexpressions as well as to complete expressions.  For example, an

  15683.      expression denoting a simple integer component, such as 'x.y.z',

  15684.      may fail if the size of 'x.y' is variable and exceeds 'size'.  On

  15685.      the other hand, GDB is sometimes clever; the expression 'A(i)',

  15686.      where 'A' is an array variable with non-constant size, will

  15687.      generally succeed regardless of the bounds on 'A', as long as the

  15688.      component size is less than SIZE.

  15689. 

  15690. 'show varsize-limit'

  15691.      Show the limit on types whose size is determined by run-time

  15692.      quantities.

  15693. 

  15694. 

  15695. File: gdb.info,  Node: Ada Glitches,  Prev: Ada Settings,  Up: Ada

  15696. 

  15697. 15.4.10.11 Known Peculiarities of Ada Mode

  15698. ..........................................

  15699. 

  15700. Besides the omissions listed previously (*note Omissions from Ada::), we

  15701. know of several problems with and limitations of Ada mode in GDB, some

  15702. of which will be fixed with planned future releases of the debugger and

  15703. the GNU Ada compiler.

  15704. 

  15705.    * Static constants that the compiler chooses not to materialize as

  15706.      objects in storage are invisible to the debugger.

  15707. 

  15708.    * Named parameter associations in function argument lists are ignored

  15709.      (the argument lists are treated as positional).

  15710. 

  15711.    * Many useful library packages are currently invisible to the

  15712.      debugger.

  15713. 

  15714.    * Fixed-point arithmetic, conversions, input, and output is carried

  15715.      out using floating-point arithmetic, and may give results that only

  15716.      approximate those on the host machine.

  15717. 

  15718.    * The GNAT compiler never generates the prefix 'Standard' for any of

  15719.      the standard symbols defined by the Ada language.  GDB knows about

  15720.      this: it will strip the prefix from names when you use it, and will

  15721.      never look for a name you have so qualified among local symbols,

  15722.      nor match against symbols in other packages or subprograms.  If you

  15723.      have defined entities anywhere in your program other than

  15724.      parameters and local variables whose simple names match names in

  15725.      'Standard', GNAT's lack of qualification here can cause confusion.

  15726.      When this happens, you can usually resolve the confusion by

  15727.      qualifying the problematic names with package 'Standard'

  15728.      explicitly.

  15729. 

  15730.    Older versions of the compiler sometimes generate erroneous debugging

  15731. information, resulting in the debugger incorrectly printing the value of

  15732. affected entities.  In some cases, the debugger is able to work around

  15733. an issue automatically.  In other cases, the debugger is able to work

  15734. around the issue, but the work-around has to be specifically enabled.

  15735. 

  15736. 'set ada trust-PAD-over-XVS on'

  15737.      Configure GDB to strictly follow the GNAT encoding when computing

  15738.      the value of Ada entities, particularly when 'PAD' and 'PAD___XVS'

  15739.      types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a

  15740.      complete description of the encoding used by the GNAT compiler).

  15741.      This is the default.

  15742. 

  15743. 'set ada trust-PAD-over-XVS off'

  15744.      This is related to the encoding using by the GNAT compiler.  If GDB

  15745.      sometimes prints the wrong value for certain entities, changing

  15746.      'ada trust-PAD-over-XVS' to 'off' activates a work-around which may

  15747.      fix the issue.  It is always safe to set 'ada trust-PAD-over-XVS'

  15748.      to 'off', but this incurs a slight performance penalty, so it is

  15749.      recommended to leave this setting to 'on' unless necessary.

  15750. 

  15751.    Internally, the debugger also relies on the compiler following a

  15752. number of conventions known as the 'GNAT Encoding', all documented in

  15753. 'gcc/ada/exp_dbug.ads' in the GCC sources.  This encoding describes how

  15754. the debugging information should be generated for certain types.  In

  15755. particular, this convention makes use of "descriptive types", which are

  15756. artificial types generated purely to help the debugger.

  15757. 

  15758.    These encodings were defined at a time when the debugging information

  15759. format used was not powerful enough to describe some of the more complex

  15760. types available in Ada.  Since DWARF allows us to express nearly all Ada

  15761. features, the long-term goal is to slowly replace these descriptive

  15762. types by their pure DWARF equivalent.  To facilitate that transition, a

  15763. new maintenance option is available to force the debugger to ignore

  15764. those descriptive types.  It allows the user to quickly evaluate how

  15765. well GDB works without them.

  15766. 

  15767. 'maintenance ada set ignore-descriptive-types [on|off]'

  15768.      Control whether the debugger should ignore descriptive types.  The

  15769.      default is not to ignore descriptives types ('off').

  15770. 

  15771. 'maintenance ada show ignore-descriptive-types'

  15772.      Show if descriptive types are ignored by GDB.

  15773. 

  15774. 

  15775. File: gdb.info,  Node: Unsupported Languages,  Prev: Supported Languages,  Up: Languages

  15776. 

  15777. 15.5 Unsupported Languages

  15778. ==========================

  15779. 

  15780. In addition to the other fully-supported programming languages, GDB also

  15781. provides a pseudo-language, called 'minimal'.  It does not represent a

  15782. real programming language, but provides a set of capabilities close to

  15783. what the C or assembly languages provide.  This should allow most simple

  15784. operations to be performed while debugging an application that uses a

  15785. language currently not supported by GDB.

  15786. 

  15787.    If the language is set to 'auto', GDB will automatically select this

  15788. language if the current frame corresponds to an unsupported language.

  15789. 

  15790. 

  15791. File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top

  15792. 

  15793. 16 Examining the Symbol Table

  15794. *****************************

  15795. 

  15796. The commands described in this chapter allow you to inquire about the

  15797. symbols (names of variables, functions and types) defined in your

  15798. program.  This information is inherent in the text of your program and

  15799. does not change as your program executes.  GDB finds it in your

  15800. program's symbol table, in the file indicated when you started GDB

  15801. (*note Choosing Files: File Options.), or by one of the file-management

  15802. commands (*note Commands to Specify Files: Files.).

  15803. 

  15804.    Occasionally, you may need to refer to symbols that contain unusual

  15805. characters, which GDB ordinarily treats as word delimiters.  The most

  15806. frequent case is in referring to static variables in other source files

  15807. (*note Program Variables: Variables.).  File names are recorded in

  15808. object files as debugging symbols, but GDB would ordinarily parse a

  15809. typical file name, like 'foo.c', as the three words 'foo' '.'  'c'.  To

  15810. allow GDB to recognize 'foo.c' as a single symbol, enclose it in single

  15811. quotes; for example,

  15812. 

  15813.      p 'foo.c'::x

  15814. 

  15815. looks up the value of 'x' in the scope of the file 'foo.c'.

  15816. 

  15817. 'set case-sensitive on'

  15818. 'set case-sensitive off'

  15819. 'set case-sensitive auto'

  15820.      Normally, when GDB looks up symbols, it matches their names with

  15821.      case sensitivity determined by the current source language.

  15822.      Occasionally, you may wish to control that.  The command 'set

  15823.      case-sensitive' lets you do that by specifying 'on' for

  15824.      case-sensitive matches or 'off' for case-insensitive ones.  If you

  15825.      specify 'auto', case sensitivity is reset to the default suitable

  15826.      for the source language.  The default is case-sensitive matches for

  15827.      all languages except for Fortran, for which the default is

  15828.      case-insensitive matches.

  15829. 

  15830. 'show case-sensitive'

  15831.      This command shows the current setting of case sensitivity for

  15832.      symbols lookups.

  15833. 

  15834. 'set print type methods'

  15835. 'set print type methods on'

  15836. 'set print type methods off'

  15837.      Normally, when GDB prints a class, it displays any methods declared

  15838.      in that class.  You can control this behavior either by passing the

  15839.      appropriate flag to 'ptype', or using 'set print type methods'.

  15840.      Specifying 'on' will cause GDB to display the methods; this is the

  15841.      default.  Specifying 'off' will cause GDB to omit the methods.

  15842. 

  15843. 'show print type methods'

  15844.      This command shows the current setting of method display when

  15845.      printing classes.

  15846. 

  15847. 'set print type nested-type-limit LIMIT'

  15848. 'set print type nested-type-limit unlimited'

  15849.      Set the limit of displayed nested types that the type printer will

  15850.      show.  A LIMIT of 'unlimited' or '-1' will show all nested

  15851.      definitions.  By default, the type printer will not show any nested

  15852.      types defined in classes.

  15853. 

  15854. 'show print type nested-type-limit'

  15855.      This command shows the current display limit of nested types when

  15856.      printing classes.

  15857. 

  15858. 'set print type typedefs'

  15859. 'set print type typedefs on'

  15860. 'set print type typedefs off'

  15861. 

  15862.      Normally, when GDB prints a class, it displays any typedefs defined

  15863.      in that class.  You can control this behavior either by passing the

  15864.      appropriate flag to 'ptype', or using 'set print type typedefs'.

  15865.      Specifying 'on' will cause GDB to display the typedef definitions;

  15866.      this is the default.  Specifying 'off' will cause GDB to omit the

  15867.      typedef definitions.  Note that this controls whether the typedef

  15868.      definition itself is printed, not whether typedef names are

  15869.      substituted when printing other types.

  15870. 

  15871. 'show print type typedefs'

  15872.      This command shows the current setting of typedef display when

  15873.      printing classes.

  15874. 

  15875. 'info address SYMBOL'

  15876.      Describe where the data for SYMBOL is stored.  For a register

  15877.      variable, this says which register it is kept in.  For a

  15878.      non-register local variable, this prints the stack-frame offset at

  15879.      which the variable is always stored.

  15880. 

  15881.      Note the contrast with 'print &SYMBOL', which does not work at all

  15882.      for a register variable, and for a stack local variable prints the

  15883.      exact address of the current instantiation of the variable.

  15884. 

  15885. 'info symbol ADDR'

  15886.      Print the name of a symbol which is stored at the address ADDR.  If

  15887.      no symbol is stored exactly at ADDR, GDB prints the nearest symbol

  15888.      and an offset from it:

  15889. 

  15890.           (gdb) info symbol 0x54320

  15891.           _initialize_vx + 396 in section .text

  15892. 

  15893.      This is the opposite of the 'info address' command.  You can use it

  15894.      to find out the name of a variable or a function given its address.

  15895. 

  15896.      For dynamically linked executables, the name of executable or

  15897.      shared library containing the symbol is also printed:

  15898. 

  15899.           (gdb) info symbol 0x400225

  15900.           _start + 5 in section .text of /tmp/a.out

  15901.           (gdb) info symbol 0x2aaaac2811cf

  15902.           __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6

  15903. 

  15904. 'demangle [-l LANGUAGE] [--] NAME'

  15905.      Demangle NAME.  If LANGUAGE is provided it is the name of the

  15906.      language to demangle NAME in.  Otherwise NAME is demangled in the

  15907.      current language.

  15908. 

  15909.      The '--' option specifies the end of options, and is useful when

  15910.      NAME begins with a dash.

  15911. 

  15912.      The parameter 'demangle-style' specifies how to interpret the kind

  15913.      of mangling used.  *Note Print Settings::.

  15914. 

  15915. 'whatis[/FLAGS] [ARG]'

  15916.      Print the data type of ARG, which can be either an expression or a

  15917.      name of a data type.  With no argument, print the data type of '$',

  15918.      the last value in the value history.

  15919. 

  15920.      If ARG is an expression (*note Expressions: Expressions.), it is

  15921.      not actually evaluated, and any side-effecting operations (such as

  15922.      assignments or function calls) inside it do not take place.

  15923. 

  15924.      If ARG is a variable or an expression, 'whatis' prints its literal

  15925.      type as it is used in the source code.  If the type was defined

  15926.      using a 'typedef', 'whatis' will _not_ print the data type

  15927.      underlying the 'typedef'.  If the type of the variable or the

  15928.      expression is a compound data type, such as 'struct' or 'class',

  15929.      'whatis' never prints their fields or methods.  It just prints the

  15930.      'struct'/'class' name (a.k.a. its "tag").  If you want to see the

  15931.      members of such a compound data type, use 'ptype'.

  15932. 

  15933.      If ARG is a type name that was defined using 'typedef', 'whatis'

  15934.      "unrolls" only one level of that 'typedef'.  Unrolling means that

  15935.      'whatis' will show the underlying type used in the 'typedef'

  15936.      declaration of ARG.  However, if that underlying type is also a

  15937.      'typedef', 'whatis' will not unroll it.

  15938. 

  15939.      For C code, the type names may also have the form 'class

  15940.      CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum

  15941.      ENUM-TAG'.

  15942. 

  15943.      FLAGS can be used to modify how the type is displayed.  Available

  15944.      flags are:

  15945. 

  15946.      'r'

  15947.           Display in "raw" form.  Normally, GDB substitutes template

  15948.           parameters and typedefs defined in a class when printing the

  15949.           class' members.  The '/r' flag disables this.

  15950. 

  15951.      'm'

  15952.           Do not print methods defined in the class.

  15953. 

  15954.      'M'

  15955.           Print methods defined in the class.  This is the default, but

  15956.           the flag exists in case you change the default with 'set print

  15957.           type methods'.

  15958. 

  15959.      't'

  15960.           Do not print typedefs defined in the class.  Note that this

  15961.           controls whether the typedef definition itself is printed, not

  15962.           whether typedef names are substituted when printing other

  15963.           types.

  15964. 

  15965.      'T'

  15966.           Print typedefs defined in the class.  This is the default, but

  15967.           the flag exists in case you change the default with 'set print

  15968.           type typedefs'.

  15969. 

  15970.      'o'

  15971.           Print the offsets and sizes of fields in a struct, similar to

  15972.           what the 'pahole' tool does.  This option implies the '/tm'

  15973.           flags.

  15974. 

  15975.           For example, given the following declarations:

  15976. 

  15977.                struct tuv

  15978.                {

  15979.                  int a1;

  15980.                  char *a2;

  15981.                  int a3;

  15982.                };

  15983. 

  15984.                struct xyz

  15985.                {

  15986.                  int f1;

  15987.                  char f2;

  15988.                  void *f3;

  15989.                  struct tuv f4;

  15990.                };

  15991. 

  15992.                union qwe

  15993.                {

  15994.                  struct tuv fff1;

  15995.                  struct xyz fff2;

  15996.                };

  15997. 

  15998.                struct tyu

  15999.                {

  16000.                  int a1 : 1;

  16001.                  int a2 : 3;

  16002.                  int a3 : 23;

  16003.                  char a4 : 2;

  16004.                  int64_t a5;

  16005.                  int a6 : 5;

  16006.                  int64_t a7 : 3;

  16007.                };

  16008. 

  16009.           Issuing a 'ptype /o struct tuv' command would print:

  16010. 

  16011.                (gdb) ptype /o struct tuv

  16012.                /* offset    |  size */  type = struct tuv {

  16013.                /*    0      |     4 */    int a1;

  16014.                /* XXX  4-byte hole  */

  16015.                /*    8      |     8 */    char *a2;

  16016.                /*   16      |     4 */    int a3;

  16017. 

  16018.                                           /* total size (bytes):   24 */

  16019.                                         }

  16020. 

  16021.           Notice the format of the first column of comments.  There, you

  16022.           can find two parts separated by the '|' character: the

  16023.           _offset_, which indicates where the field is located inside

  16024.           the struct, in bytes, and the _size_ of the field.  Another

  16025.           interesting line is the marker of a _hole_ in the struct,

  16026.           indicating that it may be possible to pack the struct and make

  16027.           it use less space by reorganizing its fields.

  16028. 

  16029.           It is also possible to print offsets inside an union:

  16030. 

  16031.                (gdb) ptype /o union qwe

  16032.                /* offset    |  size */  type = union qwe {

  16033.                /*                24 */    struct tuv {

  16034.                /*    0      |     4 */        int a1;

  16035.                /* XXX  4-byte hole  */

  16036.                /*    8      |     8 */        char *a2;

  16037.                /*   16      |     4 */        int a3;

  16038. 

  16039.                                               /* total size (bytes):   24 */

  16040.                                           } fff1;

  16041.                /*                40 */    struct xyz {

  16042.                /*    0      |     4 */        int f1;

  16043.                /*    4      |     1 */        char f2;

  16044.                /* XXX  3-byte hole  */

  16045.                /*    8      |     8 */        void *f3;

  16046.                /*   16      |    24 */        struct tuv {

  16047.                /*   16      |     4 */            int a1;

  16048.                /* XXX  4-byte hole  */

  16049.                /*   24      |     8 */            char *a2;

  16050.                /*   32      |     4 */            int a3;

  16051. 

  16052.                                                   /* total size (bytes):   24 */

  16053.                                               } f4;

  16054. 

  16055.                                               /* total size (bytes):   40 */

  16056.                                           } fff2;

  16057. 

  16058.                                           /* total size (bytes):   40 */

  16059.                                         }

  16060. 

  16061.           In this case, since 'struct tuv' and 'struct xyz' occupy the

  16062.           same space (because we are dealing with an union), the offset

  16063.           is not printed for them.  However, you can still examine the

  16064.           offset of each of these structures' fields.

  16065. 

  16066.           Another useful scenario is printing the offsets of a struct

  16067.           containing bitfields:

  16068. 

  16069.                (gdb) ptype /o struct tyu

  16070.                /* offset    |  size */  type = struct tyu {

  16071.                /*    0:31   |     4 */    int a1 : 1;

  16072.                /*    0:28   |     4 */    int a2 : 3;

  16073.                /*    0: 5   |     4 */    int a3 : 23;

  16074.                /*    3: 3   |     1 */    signed char a4 : 2;

  16075.                /* XXX  3-bit hole   */

  16076.                /* XXX  4-byte hole  */

  16077.                /*    8      |     8 */    int64_t a5;

  16078.                /*   16: 0   |     4 */    int a6 : 5;

  16079.                /*   16: 5   |     8 */    int64_t a7 : 3;

  16080.                "/* XXX  7-byte padding  */

  16081. 

  16082.                                           /* total size (bytes):   24 */

  16083.                                         }

  16084. 

  16085.           Note how the offset information is now extended to also

  16086.           include the first bit of the bitfield.

  16087. 

  16088. 'ptype[/FLAGS] [ARG]'

  16089.      'ptype' accepts the same arguments as 'whatis', but prints a

  16090.      detailed description of the type, instead of just the name of the

  16091.      type.  *Note Expressions: Expressions.

  16092. 

  16093.      Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its

  16094.      argument declaration, whether the argument is a variable,

  16095.      expression, or a data type.  This means that 'ptype' of a variable

  16096.      or an expression will not print literally its type as present in

  16097.      the source code--use 'whatis' for that.  'typedef's at the pointer

  16098.      or reference targets are also unrolled.  Only 'typedef's of fields,

  16099.      methods and inner 'class typedef's of 'struct's, 'class'es and

  16100.      'union's are not unrolled even with 'ptype'.

  16101. 

  16102.      For example, for this variable declaration:

  16103. 

  16104.           typedef double real_t;

  16105.           struct complex { real_t real; double imag; };

  16106.           typedef struct complex complex_t;

  16107.           complex_t var;

  16108.           real_t *real_pointer_var;

  16109. 

  16110.      the two commands give this output:

  16111. 

  16112.           (gdb) whatis var

  16113.           type = complex_t

  16114.           (gdb) ptype var

  16115.           type = struct complex {

  16116.               real_t real;

  16117.               double imag;

  16118.           }

  16119.           (gdb) whatis complex_t

  16120.           type = struct complex

  16121.           (gdb) whatis struct complex

  16122.           type = struct complex

  16123.           (gdb) ptype struct complex

  16124.           type = struct complex {

  16125.               real_t real;

  16126.               double imag;

  16127.           }

  16128.           (gdb) whatis real_pointer_var

  16129.           type = real_t *

  16130.           (gdb) ptype real_pointer_var

  16131.           type = double *

  16132. 

  16133.      As with 'whatis', using 'ptype' without an argument refers to the

  16134.      type of '$', the last value in the value history.

  16135. 

  16136.      Sometimes, programs use opaque data types or incomplete

  16137.      specifications of complex data structure.  If the debug information

  16138.      included in the program does not allow GDB to display a full

  16139.      declaration of the data type, it will say '<incomplete type>'.  For

  16140.      example, given these declarations:

  16141. 

  16142.               struct foo;

  16143.               struct foo *fooptr;

  16144. 

  16145.      but no definition for 'struct foo' itself, GDB will say:

  16146. 

  16147.             (gdb) ptype foo

  16148.             $1 = <incomplete type>

  16149. 

  16150.      "Incomplete type" is C terminology for data types that are not

  16151.      completely specified.

  16152. 

  16153.      Othertimes, information about a variable's type is completely

  16154.      absent from the debug information included in the program.  This

  16155.      most often happens when the program or library where the variable

  16156.      is defined includes no debug information at all.  GDB knows the

  16157.      variable exists from inspecting the linker/loader symbol table

  16158.      (e.g., the ELF dynamic symbol table), but such symbols do not

  16159.      contain type information.  Inspecting the type of a (global)

  16160.      variable for which GDB has no type information shows:

  16161. 

  16162.             (gdb) ptype var

  16163.             type = <data variable, no debug info>

  16164. 

  16165.      *Note no debug info variables: Variables, for how to print the

  16166.      values of such variables.

  16167. 

  16168. 'info types [-q] [REGEXP]'

  16169.      Print a brief description of all types whose names match the

  16170.      regular expression REGEXP (or all types in your program, if you

  16171.      supply no argument).  Each complete typename is matched as though

  16172.      it were a complete line; thus, 'i type value' gives information on

  16173.      all types in your program whose names include the string 'value',

  16174.      but 'i type ^value$' gives information only on types whose complete

  16175.      name is 'value'.

  16176. 

  16177.      In programs using different languages, GDB chooses the syntax to

  16178.      print the type description according to the 'set language' value:

  16179.      using 'set language auto' (see *note Set Language Automatically:

  16180.      Automatically.) means to use the language of the type, other values

  16181.      mean to use the manually specified language (see *note Set Language

  16182.      Manually: Manually.).

  16183. 

  16184.      This command differs from 'ptype' in two ways: first, like

  16185.      'whatis', it does not print a detailed description; second, it

  16186.      lists all source files and line numbers where a type is defined.

  16187. 

  16188.      The output from 'into types' is proceeded with a header line

  16189.      describing what types are being listed.  The optional flag '-q',

  16190.      which stands for 'quiet', disables printing this header

  16191.      information.

  16192. 

  16193. 'info type-printers'

  16194.      Versions of GDB that ship with Python scripting enabled may have

  16195.      "type printers" available.  When using 'ptype' or 'whatis', these

  16196.      printers are consulted when the name of a type is needed.  *Note

  16197.      Type Printing API::, for more information on writing type printers.

  16198. 

  16199.      'info type-printers' displays all the available type printers.

  16200. 

  16201. 'enable type-printer NAME...'

  16202. 'disable type-printer NAME...'

  16203.      These commands can be used to enable or disable type printers.

  16204. 

  16205. 'info scope LOCATION'

  16206.      List all the variables local to a particular scope.  This command

  16207.      accepts a LOCATION argument--a function name, a source line, or an

  16208.      address preceded by a '*', and prints all the variables local to

  16209.      the scope defined by that location.  (*Note Specify Location::, for

  16210.      details about supported forms of LOCATION.)  For example:

  16211. 

  16212.           (gdb) info scope command_line_handler

  16213.           Scope for command_line_handler:

  16214.           Symbol rl is an argument at stack/frame offset 8, length 4.

  16215.           Symbol linebuffer is in static storage at address 0x150a18, length 4.

  16216.           Symbol linelength is in static storage at address 0x150a1c, length 4.

  16217.           Symbol p is a local variable in register $esi, length 4.

  16218.           Symbol p1 is a local variable in register $ebx, length 4.

  16219.           Symbol nline is a local variable in register $edx, length 4.

  16220.           Symbol repeat is a local variable at frame offset -8, length 4.

  16221. 

  16222.      This command is especially useful for determining what data to

  16223.      collect during a "trace experiment", see *note collect: Tracepoint

  16224.      Actions.

  16225. 

  16226. 'info source'

  16227.      Show information about the current source file--that is, the source

  16228.      file for the function containing the current point of execution:

  16229.         * the name of the source file, and the directory containing it,

  16230.         * the directory it was compiled in,

  16231.         * its length, in lines,

  16232.         * which programming language it is written in,

  16233.         * if the debug information provides it, the program that

  16234.           compiled the file (which may include, e.g., the compiler

  16235.           version and command line arguments),

  16236.         * whether the executable includes debugging information for that

  16237.           file, and if so, what format the information is in (e.g.,

  16238.           STABS, Dwarf 2, etc.), and

  16239.         * whether the debugging information includes information about

  16240.           preprocessor macros.

  16241. 

  16242. 'info sources'

  16243.      Print the names of all source files in your program for which there

  16244.      is debugging information, organized into two lists: files whose

  16245.      symbols have already been read, and files whose symbols will be

  16246.      read when needed.

  16247. 

  16248. 'info sources [-dirname | -basename] [--] [REGEXP]'

  16249.      Like 'info sources', but only print the names of the files matching

  16250.      the provided REGEXP.  By default, the REGEXP is used to match

  16251.      anywhere in the filename.  If '-dirname', only files having a

  16252.      dirname matching REGEXP are shown.  If '-basename', only files

  16253.      having a basename matching REGEXP are shown.  The matching is

  16254.      case-sensitive, except on operating systems that have

  16255.      case-insensitive filesystem (e.g., MS-Windows).

  16256. 

  16257. 'info functions [-q] [-n]'

  16258.      Print the names and data types of all defined functions.  Similarly

  16259.      to 'info types', this command groups its output by source files and

  16260.      annotates each function definition with its source line number.

  16261. 

  16262.      In programs using different languages, GDB chooses the syntax to

  16263.      print the function name and type according to the 'set language'

  16264.      value: using 'set language auto' (see *note Set Language

  16265.      Automatically: Automatically.) means to use the language of the

  16266.      function, other values mean to use the manually specified language

  16267.      (see *note Set Language Manually: Manually.).

  16268. 

  16269.      The '-n' flag excludes "non-debugging symbols" from the results.  A

  16270.      non-debugging symbol is a symbol that comes from the executable's

  16271.      symbol table, not from the debug information (for example, DWARF)

  16272.      associated with the executable.

  16273. 

  16274.      The optional flag '-q', which stands for 'quiet', disables printing

  16275.      header information and messages explaining why no functions have

  16276.      been printed.

  16277. 

  16278. 'info functions [-q] [-n] [-t TYPE_REGEXP] [REGEXP]'

  16279.      Like 'info functions', but only print the names and data types of

  16280.      the functions selected with the provided regexp(s).

  16281. 

  16282.      If REGEXP is provided, print only the functions whose names match

  16283.      the regular expression REGEXP.  Thus, 'info fun step' finds all

  16284.      functions whose names include 'step'; 'info fun ^step' finds those

  16285.      whose names start with 'step'.  If a function name contains

  16286.      characters that conflict with the regular expression language (e.g.

  16287.      'operator*()'), they may be quoted with a backslash.

  16288. 

  16289.      If TYPE_REGEXP is provided, print only the functions whose types,

  16290.      as printed by the 'whatis' command, match the regular expression

  16291.      TYPE_REGEXP.  If TYPE_REGEXP contains space(s), it should be

  16292.      enclosed in quote characters.  If needed, use backslash to escape

  16293.      the meaning of special characters or quotes.  Thus, 'info fun -t

  16294.      '^int ('' finds the functions that return an integer; 'info fun -t

  16295.      '(.*int.*'' finds the functions that have an argument type

  16296.      containing int; 'info fun -t '^int (' ^step' finds the functions

  16297.      whose names start with 'step' and that return int.

  16298. 

  16299.      If both REGEXP and TYPE_REGEXP are provided, a function is printed

  16300.      only if its name matches REGEXP and its type matches TYPE_REGEXP.

  16301. 

  16302. 'info variables [-q] [-n]'

  16303.      Print the names and data types of all variables that are defined

  16304.      outside of functions (i.e. excluding local variables).  The printed

  16305.      variables are grouped by source files and annotated with their

  16306.      respective source line numbers.

  16307. 

  16308.      In programs using different languages, GDB chooses the syntax to

  16309.      print the variable name and type according to the 'set language'

  16310.      value: using 'set language auto' (see *note Set Language

  16311.      Automatically: Automatically.) means to use the language of the

  16312.      variable, other values mean to use the manually specified language

  16313.      (see *note Set Language Manually: Manually.).

  16314. 

  16315.      The '-n' flag excludes non-debugging symbols from the results.

  16316. 

  16317.      The optional flag '-q', which stands for 'quiet', disables printing

  16318.      header information and messages explaining why no variables have

  16319.      been printed.

  16320. 

  16321. 'info variables [-q] [-n] [-t TYPE_REGEXP] [REGEXP]'

  16322.      Like 'info variables', but only print the variables selected with

  16323.      the provided regexp(s).

  16324. 

  16325.      If REGEXP is provided, print only the variables whose names match

  16326.      the regular expression REGEXP.

  16327. 

  16328.      If TYPE_REGEXP is provided, print only the variables whose types,

  16329.      as printed by the 'whatis' command, match the regular expression

  16330.      TYPE_REGEXP.  If TYPE_REGEXP contains space(s), it should be

  16331.      enclosed in quote characters.  If needed, use backslash to escape

  16332.      the meaning of special characters or quotes.

  16333. 

  16334.      If both REGEXP and TYPE_REGEXP are provided, an argument is printed

  16335.      only if its name matches REGEXP and its type matches TYPE_REGEXP.

  16336. 

  16337. 'info modules [-q] [REGEXP]'

  16338.      List all Fortran modules in the program, or all modules matching

  16339.      the optional regular expression REGEXP.

  16340. 

  16341.      The optional flag '-q', which stands for 'quiet', disables printing

  16342.      header information and messages explaining why no modules have been

  16343.      printed.

  16344. 

  16345. 'info module functions [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]'

  16346. 'info module variables [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]'

  16347.      List all functions or variables within all Fortran modules.  The

  16348.      set of functions or variables listed can be limited by providing

  16349.      some or all of the optional regular expressions.  If MODULE-REGEXP

  16350.      is provided, then only Fortran modules matching MODULE-REGEXP will

  16351.      be searched.  Only functions or variables whose type matches the

  16352.      optional regular expression TYPE-REGEXP will be listed.  And only

  16353.      functions or variables whose name matches the optional regular

  16354.      expression REGEXP will be listed.

  16355. 

  16356.      The optional flag '-q', which stands for 'quiet', disables printing

  16357.      header information and messages explaining why no functions or

  16358.      variables have been printed.

  16359. 

  16360. 'info classes'

  16361. 'info classes REGEXP'

  16362.      Display all Objective-C classes in your program, or (with the

  16363.      REGEXP argument) all those matching a particular regular

  16364.      expression.

  16365. 

  16366. 'info selectors'

  16367. 'info selectors REGEXP'

  16368.      Display all Objective-C selectors in your program, or (with the

  16369.      REGEXP argument) all those matching a particular regular

  16370.      expression.

  16371. 

  16372. 'set opaque-type-resolution on'

  16373.      Tell GDB to resolve opaque types.  An opaque type is a type

  16374.      declared as a pointer to a 'struct', 'class', or 'union'--for

  16375.      example, 'struct MyType *'--that is used in one source file

  16376.      although the full declaration of 'struct MyType' is in another

  16377.      source file.  The default is on.

  16378. 

  16379.      A change in the setting of this subcommand will not take effect

  16380.      until the next time symbols for a file are loaded.

  16381. 

  16382. 'set opaque-type-resolution off'

  16383.      Tell GDB not to resolve opaque types.  In this case, the type is

  16384.      printed as follows:

  16385.           {<no data fields>}

  16386. 

  16387. 'show opaque-type-resolution'

  16388.      Show whether opaque types are resolved or not.

  16389. 

  16390. 'set print symbol-loading'

  16391. 'set print symbol-loading full'

  16392. 'set print symbol-loading brief'

  16393. 'set print symbol-loading off'

  16394.      The 'set print symbol-loading' command allows you to control the

  16395.      printing of messages when GDB loads symbol information.  By default

  16396.      a message is printed for the executable and one for each shared

  16397.      library, and normally this is what you want.  However, when

  16398.      debugging apps with large numbers of shared libraries these

  16399.      messages can be annoying.  When set to 'brief' a message is printed

  16400.      for each executable, and when GDB loads a collection of shared

  16401.      libraries at once it will only print one message regardless of the

  16402.      number of shared libraries.  When set to 'off' no messages are

  16403.      printed.

  16404. 

  16405. 'show print symbol-loading'

  16406.      Show whether messages will be printed when a GDB command entered

  16407.      from the keyboard causes symbol information to be loaded.

  16408. 

  16409. 'maint print symbols [-pc ADDRESS] [FILENAME]'

  16410. 'maint print symbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]'

  16411. 'maint print psymbols [-objfile OBJFILE] [-pc ADDRESS] [--] [FILENAME]'

  16412. 'maint print psymbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]'

  16413. 'maint print msymbols [-objfile OBJFILE] [--] [FILENAME]'

  16414.      Write a dump of debugging symbol data into the file FILENAME or the

  16415.      terminal if FILENAME is unspecified.  If '-objfile OBJFILE' is

  16416.      specified, only dump symbols for that objfile.  If '-pc ADDRESS' is

  16417.      specified, only dump symbols for the file with code at that

  16418.      address.  Note that ADDRESS may be a symbol like 'main'.  If

  16419.      '-source SOURCE' is specified, only dump symbols for that source

  16420.      file.

  16421. 

  16422.      These commands are used to debug the GDB symbol-reading code.

  16423.      These commands do not modify internal GDB state, therefore 'maint

  16424.      print symbols' will only print symbols for already expanded symbol

  16425.      tables.  You can use the command 'info sources' to find out which

  16426.      files these are.  If you use 'maint print psymbols' instead, the

  16427.      dump shows information about symbols that GDB only knows

  16428.      partially--that is, symbols defined in files that GDB has skimmed,

  16429.      but not yet read completely.  Finally, 'maint print msymbols' just

  16430.      dumps "minimal symbols", e.g., "ELF symbols".

  16431. 

  16432.      *Note Commands to Specify Files: Files, for a discussion of how GDB

  16433.      reads symbols (in the description of 'symbol-file').

  16434. 

  16435. 'maint info symtabs [ REGEXP ]'

  16436. 'maint info psymtabs [ REGEXP ]'

  16437. 

  16438.      List the 'struct symtab' or 'struct partial_symtab' structures

  16439.      whose names match REGEXP.  If REGEXP is not given, list them all.

  16440.      The output includes expressions which you can copy into a GDB

  16441.      debugging this one to examine a particular structure in more

  16442.      detail.  For example:

  16443. 

  16444.           (gdb) maint info psymtabs dwarf2read

  16445.           { objfile /home/gnu/build/gdb/gdb

  16446.             ((struct objfile *) 0x82e69d0)

  16447.             { psymtab /home/gnu/src/gdb/dwarf2read.c

  16448.               ((struct partial_symtab *) 0x8474b10)

  16449.               readin no

  16450.               fullname (null)

  16451.               text addresses 0x814d3c8 -- 0x8158074

  16452.               globals (* (struct partial_symbol **) 0x8507a08 @ 9)

  16453.               statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)

  16454.               dependencies (none)

  16455.             }

  16456.           }

  16457.           (gdb) maint info symtabs

  16458.           (gdb)

  16459.      We see that there is one partial symbol table whose filename

  16460.      contains the string 'dwarf2read', belonging to the 'gdb'

  16461.      executable; and we see that GDB has not read in any symtabs yet at

  16462.      all.  If we set a breakpoint on a function, that will cause GDB to

  16463.      read the symtab for the compilation unit containing that function:

  16464. 

  16465.           (gdb) break dwarf2_psymtab_to_symtab

  16466.           Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,

  16467.           line 1574.

  16468.           (gdb) maint info symtabs

  16469.           { objfile /home/gnu/build/gdb/gdb

  16470.             ((struct objfile *) 0x82e69d0)

  16471.             { symtab /home/gnu/src/gdb/dwarf2read.c

  16472.               ((struct symtab *) 0x86c1f38)

  16473.               dirname (null)

  16474.               fullname (null)

  16475.               blockvector ((struct blockvector *) 0x86c1bd0) (primary)

  16476.               linetable ((struct linetable *) 0x8370fa0)

  16477.               debugformat DWARF 2

  16478.             }

  16479.           }

  16480.           (gdb)

  16481. 

  16482. 'maint info line-table [ REGEXP ]'

  16483. 

  16484.      List the 'struct linetable' from all 'struct symtab' instances

  16485.      whose name matches REGEXP.  If REGEXP is not given, list the

  16486.      'struct linetable' from all 'struct symtab'.

  16487. 

  16488. 'maint set symbol-cache-size SIZE'

  16489.      Set the size of the symbol cache to SIZE.  The default size is

  16490.      intended to be good enough for debugging most applications.  This

  16491.      option exists to allow for experimenting with different sizes.

  16492. 

  16493. 'maint show symbol-cache-size'

  16494.      Show the size of the symbol cache.

  16495. 

  16496. 'maint print symbol-cache'

  16497.      Print the contents of the symbol cache.  This is useful when

  16498.      debugging symbol cache issues.

  16499. 

  16500. 'maint print symbol-cache-statistics'

  16501.      Print symbol cache usage statistics.  This helps determine how well

  16502.      the cache is being utilized.

  16503. 

  16504. 'maint flush-symbol-cache'

  16505.      Flush the contents of the symbol cache, all entries are removed.

  16506.      This command is useful when debugging the symbol cache.  It is also

  16507.      useful when collecting performance data.

  16508. 

  16509. 

  16510. File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top

  16511. 

  16512. 17 Altering Execution

  16513. *********************

  16514. 

  16515. Once you think you have found an error in your program, you might want

  16516. to find out for certain whether correcting the apparent error would lead

  16517. to correct results in the rest of the run.  You can find the answer by

  16518. experiment, using the GDB features for altering execution of the

  16519. program.

  16520. 

  16521.    For example, you can store new values into variables or memory

  16522. locations, give your program a signal, restart it at a different

  16523. address, or even return prematurely from a function.

  16524. 

  16525. * Menu:

  16526. 

  16527. * Assignment::                  Assignment to variables

  16528. * Jumping::                     Continuing at a different address

  16529. * Signaling::                   Giving your program a signal

  16530. * Returning::                   Returning from a function

  16531. * Calling::                     Calling your program's functions

  16532. * Patching::                    Patching your program

  16533. * Compiling and Injecting Code:: Compiling and injecting code in GDB

  16534. 

  16535. 

  16536. File: gdb.info,  Node: Assignment,  Next: Jumping,  Up: Altering

  16537. 

  16538. 17.1 Assignment to Variables

  16539. ============================

  16540. 

  16541. To alter the value of a variable, evaluate an assignment expression.

  16542. *Note Expressions: Expressions.  For example,

  16543. 

  16544.      print x=4

  16545. 

  16546. stores the value 4 into the variable 'x', and then prints the value of

  16547. the assignment expression (which is 4).  *Note Using GDB with Different

  16548. Languages: Languages, for more information on operators in supported

  16549. languages.

  16550. 

  16551.    If you are not interested in seeing the value of the assignment, use

  16552. the 'set' command instead of the 'print' command.  'set' is really the

  16553. same as 'print' except that the expression's value is not printed and is

  16554. not put in the value history (*note Value History: Value History.).  The

  16555. expression is evaluated only for its effects.

  16556. 

  16557.    If the beginning of the argument string of the 'set' command appears

  16558. identical to a 'set' subcommand, use the 'set variable' command instead

  16559. of just 'set'.  This command is identical to 'set' except for its lack

  16560. of subcommands.  For example, if your program has a variable 'width',

  16561. you get an error if you try to set a new value with just 'set width=13',

  16562. because GDB has the command 'set width':

  16563. 

  16564.      (gdb) whatis width

  16565.      type = double

  16566.      (gdb) p width

  16567.      $4 = 13

  16568.      (gdb) set width=47

  16569.      Invalid syntax in expression.

  16570. 

  16571. The invalid expression, of course, is '=47'.  In order to actually set

  16572. the program's variable 'width', use

  16573. 

  16574.      (gdb) set var width=47

  16575. 

  16576.    Because the 'set' command has many subcommands that can conflict with

  16577. the names of program variables, it is a good idea to use the 'set

  16578. variable' command instead of just 'set'.  For example, if your program

  16579. has a variable 'g', you run into problems if you try to set a new value

  16580. with just 'set g=4', because GDB has the command 'set gnutarget',

  16581. abbreviated 'set g':

  16582. 

  16583.      (gdb) whatis g

  16584.      type = double

  16585.      (gdb) p g

  16586.      $1 = 1

  16587.      (gdb) set g=4

  16588.      (gdb) p g

  16589.      $2 = 1

  16590.      (gdb) r

  16591.      The program being debugged has been started already.

  16592.      Start it from the beginning? (y or n) y

  16593.      Starting program: /home/smith/cc_progs/a.out

  16594.      "/home/smith/cc_progs/a.out": can't open to read symbols:

  16595.                                       Invalid bfd target.

  16596.      (gdb) show g

  16597.      The current BFD target is "=4".

  16598. 

  16599. The program variable 'g' did not change, and you silently set the

  16600. 'gnutarget' to an invalid value.  In order to set the variable 'g', use

  16601. 

  16602.      (gdb) set var g=4

  16603. 

  16604.    GDB allows more implicit conversions in assignments than C; you can

  16605. freely store an integer value into a pointer variable or vice versa, and

  16606. you can convert any structure to any other structure that is the same

  16607. length or shorter.

  16608. 

  16609.    To store values into arbitrary places in memory, use the '{...}'

  16610. construct to generate a value of specified type at a specified address

  16611. (*note Expressions: Expressions.).  For example, '{int}0x83040' refers

  16612. to memory location '0x83040' as an integer (which implies a certain size

  16613. and representation in memory), and

  16614. 

  16615.      set {int}0x83040 = 4

  16616. 

  16617. stores the value 4 into that memory location.

  16618. 

  16619. 

  16620. File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering

  16621. 

  16622. 17.2 Continuing at a Different Address

  16623. ======================================

  16624. 

  16625. Ordinarily, when you continue your program, you do so at the place where

  16626. it stopped, with the 'continue' command.  You can instead continue at an

  16627. address of your own choosing, with the following commands:

  16628. 

  16629. 'jump LOCATION'

  16630. 'j LOCATION'

  16631.      Resume execution at LOCATION.  Execution stops again immediately if

  16632.      there is a breakpoint there.  *Note Specify Location::, for a

  16633.      description of the different forms of LOCATION.  It is common

  16634.      practice to use the 'tbreak' command in conjunction with 'jump'.

  16635.      *Note Setting Breakpoints: Set Breaks.

  16636. 

  16637.      The 'jump' command does not change the current stack frame, or the

  16638.      stack pointer, or the contents of any memory location or any

  16639.      register other than the program counter.  If LOCATION is in a

  16640.      different function from the one currently executing, the results

  16641.      may be bizarre if the two functions expect different patterns of

  16642.      arguments or of local variables.  For this reason, the 'jump'

  16643.      command requests confirmation if the specified line is not in the

  16644.      function currently executing.  However, even bizarre results are

  16645.      predictable if you are well acquainted with the machine-language

  16646.      code of your program.

  16647. 

  16648.    On many systems, you can get much the same effect as the 'jump'

  16649. command by storing a new value into the register '$pc'.  The difference

  16650. is that this does not start your program running; it only changes the

  16651. address of where it _will_ run when you continue.  For example,

  16652. 

  16653.      set $pc = 0x485

  16654. 

  16655. makes the next 'continue' command or stepping command execute at address

  16656. '0x485', rather than at the address where your program stopped.  *Note

  16657. Continuing and Stepping: Continuing and Stepping.

  16658. 

  16659.    The most common occasion to use the 'jump' command is to back

  16660. up--perhaps with more breakpoints set--over a portion of a program that

  16661. has already executed, in order to examine its execution in more detail.

  16662. 

  16663. 

  16664. File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering

  16665. 

  16666. 17.3 Giving your Program a Signal

  16667. =================================

  16668. 

  16669. 'signal SIGNAL'

  16670.      Resume execution where your program is stopped, but immediately

  16671.      give it the signal SIGNAL.  The SIGNAL can be the name or the

  16672.      number of a signal.  For example, on many systems 'signal 2' and

  16673.      'signal SIGINT' are both ways of sending an interrupt signal.

  16674. 

  16675.      Alternatively, if SIGNAL is zero, continue execution without giving

  16676.      a signal.  This is useful when your program stopped on account of a

  16677.      signal and would ordinarily see the signal when resumed with the

  16678.      'continue' command; 'signal 0' causes it to resume without a

  16679.      signal.

  16680. 

  16681.      _Note:_ When resuming a multi-threaded program, SIGNAL is delivered

  16682.      to the currently selected thread, not the thread that last reported

  16683.      a stop.  This includes the situation where a thread was stopped due

  16684.      to a signal.  So if you want to continue execution suppressing the

  16685.      signal that stopped a thread, you should select that same thread

  16686.      before issuing the 'signal 0' command.  If you issue the 'signal 0'

  16687.      command with another thread as the selected one, GDB detects that

  16688.      and asks for confirmation.

  16689. 

  16690.      Invoking the 'signal' command is not the same as invoking the

  16691.      'kill' utility from the shell.  Sending a signal with 'kill' causes

  16692.      GDB to decide what to do with the signal depending on the signal

  16693.      handling tables (*note Signals::).  The 'signal' command passes the

  16694.      signal directly to your program.

  16695. 

  16696.      'signal' does not repeat when you press <RET> a second time after

  16697.      executing the command.

  16698. 

  16699. 'queue-signal SIGNAL'

  16700.      Queue SIGNAL to be delivered immediately to the current thread when

  16701.      execution of the thread resumes.  The SIGNAL can be the name or the

  16702.      number of a signal.  For example, on many systems 'signal 2' and

  16703.      'signal SIGINT' are both ways of sending an interrupt signal.  The

  16704.      handling of the signal must be set to pass the signal to the

  16705.      program, otherwise GDB will report an error.  You can control the

  16706.      handling of signals from GDB with the 'handle' command (*note

  16707.      Signals::).

  16708. 

  16709.      Alternatively, if SIGNAL is zero, any currently queued signal for

  16710.      the current thread is discarded and when execution resumes no

  16711.      signal will be delivered.  This is useful when your program stopped

  16712.      on account of a signal and would ordinarily see the signal when

  16713.      resumed with the 'continue' command.

  16714. 

  16715.      This command differs from the 'signal' command in that the signal

  16716.      is just queued, execution is not resumed.  And 'queue-signal'

  16717.      cannot be used to pass a signal whose handling state has been set

  16718.      to 'nopass' (*note Signals::).

  16719. 

  16720.    *Note stepping into signal handlers::, for information on how

  16721. stepping commands behave when the thread has a signal queued.

  16722. 

  16723. 

  16724. File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering

  16725. 

  16726. 17.4 Returning from a Function

  16727. ==============================

  16728. 

  16729. 'return'

  16730. 'return EXPRESSION'

  16731.      You can cancel execution of a function call with the 'return'

  16732.      command.  If you give an EXPRESSION argument, its value is used as

  16733.      the function's return value.

  16734. 

  16735.    When you use 'return', GDB discards the selected stack frame (and all

  16736. frames within it).  You can think of this as making the discarded frame

  16737. return prematurely.  If you wish to specify a value to be returned, give

  16738. that value as the argument to 'return'.

  16739. 

  16740.    This pops the selected stack frame (*note Selecting a Frame:

  16741. Selection.), and any other frames inside of it, leaving its caller as

  16742. the innermost remaining frame.  That frame becomes selected.  The

  16743. specified value is stored in the registers used for returning values of

  16744. functions.

  16745. 

  16746.    The 'return' command does not resume execution; it leaves the program

  16747. stopped in the state that would exist if the function had just returned.

  16748. In contrast, the 'finish' command (*note Continuing and Stepping:

  16749. Continuing and Stepping.) resumes execution until the selected stack

  16750. frame returns naturally.

  16751. 

  16752.    GDB needs to know how the EXPRESSION argument should be set for the

  16753. inferior.  The concrete registers assignment depends on the OS ABI and

  16754. the type being returned by the selected stack frame.  For example it is

  16755. common for OS ABI to return floating point values in FPU registers while

  16756. integer values in CPU registers.  Still some ABIs return even floating

  16757. point values in CPU registers.  Larger integer widths (such as 'long

  16758. long int') also have specific placement rules.  GDB already knows the OS

  16759. ABI from its current target so it needs to find out also the type being

  16760. returned to make the assignment into the right register(s).

  16761. 

  16762.    Normally, the selected stack frame has debug info.  GDB will always

  16763. use the debug info instead of the implicit type of EXPRESSION when the

  16764. debug info is available.  For example, if you type 'return -1', and the

  16765. function in the current stack frame is declared to return a 'long long

  16766. int', GDB transparently converts the implicit 'int' value of -1 into a

  16767. 'long long int':

  16768. 

  16769.      Breakpoint 1, func () at gdb.base/return-nodebug.c:29

  16770.      29        return 31;

  16771.      (gdb) return -1

  16772.      Make func return now? (y or n) y

  16773.      #0  0x004004f6 in main () at gdb.base/return-nodebug.c:43

  16774.      43        printf ("result=%lld\n", func ());

  16775.      (gdb)

  16776. 

  16777.    However, if the selected stack frame does not have a debug info,

  16778. e.g., if the function was compiled without debug info, GDB has to find

  16779. out the type to return from user.  Specifying a different type by

  16780. mistake may set the value in different inferior registers than the

  16781. caller code expects.  For example, typing 'return -1' with its implicit

  16782. type 'int' would set only a part of a 'long long int' result for a debug

  16783. info less function (on 32-bit architectures).  Therefore the user is

  16784. required to specify the return type by an appropriate cast explicitly:

  16785. 

  16786.      Breakpoint 2, 0x0040050b in func ()

  16787.      (gdb) return -1

  16788.      Return value type not available for selected stack frame.

  16789.      Please use an explicit cast of the value to return.

  16790.      (gdb) return (long long int) -1

  16791.      Make selected stack frame return now? (y or n) y

  16792.      #0  0x00400526 in main ()

  16793.      (gdb)

  16794. 

  16795. 

  16796. File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering

  16797. 

  16798. 17.5 Calling Program Functions

  16799. ==============================

  16800. 

  16801. 'print EXPR'

  16802.      Evaluate the expression EXPR and display the resulting value.  The

  16803.      expression may include calls to functions in the program being

  16804.      debugged.

  16805. 

  16806. 'call EXPR'

  16807.      Evaluate the expression EXPR without displaying 'void' returned

  16808.      values.

  16809. 

  16810.      You can use this variant of the 'print' command if you want to

  16811.      execute a function from your program that does not return anything

  16812.      (a.k.a. "a void function"), but without cluttering the output with

  16813.      'void' returned values that GDB will otherwise print.  If the

  16814.      result is not void, it is printed and saved in the value history.

  16815. 

  16816.    It is possible for the function you call via the 'print' or 'call'

  16817. command to generate a signal (e.g., if there's a bug in the function, or

  16818. if you passed it incorrect arguments).  What happens in that case is

  16819. controlled by the 'set unwindonsignal' command.

  16820. 

  16821.    Similarly, with a C++ program it is possible for the function you

  16822. call via the 'print' or 'call' command to generate an exception that is

  16823. not handled due to the constraints of the dummy frame.  In this case,

  16824. any exception that is raised in the frame, but has an out-of-frame

  16825. exception handler will not be found.  GDB builds a dummy-frame for the

  16826. inferior function call, and the unwinder cannot seek for exception

  16827. handlers outside of this dummy-frame.  What happens in that case is

  16828. controlled by the 'set unwind-on-terminating-exception' command.

  16829. 

  16830. 'set unwindonsignal'

  16831.      Set unwinding of the stack if a signal is received while in a

  16832.      function that GDB called in the program being debugged.  If set to

  16833.      on, GDB unwinds the stack it created for the call and restores the

  16834.      context to what it was before the call.  If set to off (the

  16835.      default), GDB stops in the frame where the signal was received.

  16836. 

  16837. 'show unwindonsignal'

  16838.      Show the current setting of stack unwinding in the functions called

  16839.      by GDB.

  16840. 

  16841. 'set unwind-on-terminating-exception'

  16842.      Set unwinding of the stack if a C++ exception is raised, but left

  16843.      unhandled while in a function that GDB called in the program being

  16844.      debugged.  If set to on (the default), GDB unwinds the stack it

  16845.      created for the call and restores the context to what it was before

  16846.      the call.  If set to off, GDB the exception is delivered to the

  16847.      default C++ exception handler and the inferior terminated.

  16848. 

  16849. 'show unwind-on-terminating-exception'

  16850.      Show the current setting of stack unwinding in the functions called

  16851.      by GDB.

  16852. 

  16853. 'set may-call-functions'

  16854.      Set permission to call functions in the program.  This controls

  16855.      whether GDB will attempt to call functions in the program, such as

  16856.      with expressions in the 'print' command.  It defaults to 'on'.

  16857. 

  16858.      To call a function in the program, GDB has to temporarily modify

  16859.      the state of the inferior.  This has potentially undesired side

  16860.      effects.  Also, having GDB call nested functions is likely to be

  16861.      erroneous and may even crash the program being debugged.  You can

  16862.      avoid such hazards by forbidding GDB from calling functions in the

  16863.      program being debugged.  If calling functions in the program is

  16864.      forbidden, GDB will throw an error when a command (such as printing

  16865.      an expression) starts a function call in the program.

  16866. 

  16867. 'show may-call-functions'

  16868.      Show permission to call functions in the program.

  16869. 

  16870. 17.5.1 Calling functions with no debug info

  16871. -------------------------------------------

  16872. 

  16873. Sometimes, a function you wish to call is missing debug information.  In

  16874. such case, GDB does not know the type of the function, including the

  16875. types of the function's parameters.  To avoid calling the inferior

  16876. function incorrectly, which could result in the called function

  16877. functioning erroneously and even crash, GDB refuses to call the function

  16878. unless you tell it the type of the function.

  16879. 

  16880.    For prototyped (i.e. ANSI/ISO style) functions, there are two ways to

  16881. do that.  The simplest is to cast the call to the function's declared

  16882. return type.  For example:

  16883. 

  16884.      (gdb) p getenv ("PATH")

  16885.      'getenv' has unknown return type; cast the call to its declared return type

  16886.      (gdb) p (char *) getenv ("PATH")

  16887.      $1 = 0x7fffffffe7ba "/usr/local/bin:/"...

  16888. 

  16889.    Casting the return type of a no-debug function is equivalent to

  16890. casting the function to a pointer to a prototyped function that has a

  16891. prototype that matches the types of the passed-in arguments, and calling

  16892. that.  I.e., the call above is equivalent to:

  16893. 

  16894.      (gdb) p ((char * (*) (const char *)) getenv) ("PATH")

  16895. 

  16896. and given this prototyped C or C++ function with float parameters:

  16897. 

  16898.      float multiply (float v1, float v2) { return v1 * v2; }

  16899. 

  16900. these calls are equivalent:

  16901. 

  16902.      (gdb) p (float) multiply (2.0f, 3.0f)

  16903.      (gdb) p ((float (*) (float, float)) multiply) (2.0f, 3.0f)

  16904. 

  16905.    If the function you wish to call is declared as unprototyped (i.e.

  16906. old K&R style), you must use the cast-to-function-pointer syntax, so

  16907. that GDB knows that it needs to apply default argument promotions

  16908. (promote float arguments to double).  *Note float promotion: ABI. For

  16909. example, given this unprototyped C function with float parameters, and

  16910. no debug info:

  16911. 

  16912.      float

  16913.      multiply_noproto (v1, v2)

  16914.        float v1, v2;

  16915.      {

  16916.        return v1 * v2;

  16917.      }

  16918. 

  16919. you call it like this:

  16920. 

  16921.        (gdb) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f)

  16922. 

  16923. 

  16924. File: gdb.info,  Node: Patching,  Next: Compiling and Injecting Code,  Prev: Calling,  Up: Altering

  16925. 

  16926. 17.6 Patching Programs

  16927. ======================

  16928. 

  16929. By default, GDB opens the file containing your program's executable code

  16930. (or the corefile) read-only.  This prevents accidental alterations to

  16931. machine code; but it also prevents you from intentionally patching your

  16932. program's binary.

  16933. 

  16934.    If you'd like to be able to patch the binary, you can specify that

  16935. explicitly with the 'set write' command.  For example, you might want to

  16936. turn on internal debugging flags, or even to make emergency repairs.

  16937. 

  16938. 'set write on'

  16939. 'set write off'

  16940.      If you specify 'set write on', GDB opens executable and core files

  16941.      for both reading and writing; if you specify 'set write off' (the

  16942.      default), GDB opens them read-only.

  16943. 

  16944.      If you have already loaded a file, you must load it again (using

  16945.      the 'exec-file' or 'core-file' command) after changing 'set write',

  16946.      for your new setting to take effect.

  16947. 

  16948. 'show write'

  16949.      Display whether executable files and core files are opened for

  16950.      writing as well as reading.

  16951. 

  16952. 

  16953. File: gdb.info,  Node: Compiling and Injecting Code,  Prev: Patching,  Up: Altering

  16954. 

  16955. 17.7 Compiling and injecting code in GDB

  16956. ========================================

  16957. 

  16958. GDB supports on-demand compilation and code injection into programs

  16959. running under GDB.  GCC 5.0 or higher built with 'libcc1.so' must be

  16960. installed for this functionality to be enabled.  This functionality is

  16961. implemented with the following commands.

  16962. 

  16963. 'compile code SOURCE-CODE'

  16964. 'compile code -raw -- SOURCE-CODE'

  16965.      Compile SOURCE-CODE with the compiler language found as the current

  16966.      language in GDB (*note Languages::).  If compilation and injection

  16967.      is not supported with the current language specified in GDB, or the

  16968.      compiler does not support this feature, an error message will be

  16969.      printed.  If SOURCE-CODE compiles and links successfully, GDB will

  16970.      load the object-code emitted, and execute it within the context of

  16971.      the currently selected inferior.  It is important to note that the

  16972.      compiled code is executed immediately.  After execution, the

  16973.      compiled code is removed from GDB and any new types or variables

  16974.      you have defined will be deleted.

  16975. 

  16976.      The command allows you to specify SOURCE-CODE in two ways.  The

  16977.      simplest method is to provide a single line of code to the command.

  16978.      E.g.:

  16979. 

  16980.           compile code printf ("hello world\n");

  16981. 

  16982.      If you specify options on the command line as well as source code,

  16983.      they may conflict.  The '--' delimiter can be used to separate

  16984.      options from actual source code.  E.g.:

  16985. 

  16986.           compile code -r -- printf ("hello world\n");

  16987. 

  16988.      Alternatively you can enter source code as multiple lines of text.

  16989.      To enter this mode, invoke the 'compile code' command without any

  16990.      text following the command.  This will start the multiple-line

  16991.      editor and allow you to type as many lines of source code as

  16992.      required.  When you have completed typing, enter 'end' on its own

  16993.      line to exit the editor.

  16994. 

  16995.           compile code

  16996.           >printf ("hello\n");

  16997.           >printf ("world\n");

  16998.           >end

  16999. 

  17000.      Specifying '-raw', prohibits GDB from wrapping the provided

  17001.      SOURCE-CODE in a callable scope.  In this case, you must specify

  17002.      the entry point of the code by defining a function named

  17003.      '_gdb_expr_'.  The '-raw' code cannot access variables of the

  17004.      inferior.  Using '-raw' option may be needed for example when

  17005.      SOURCE-CODE requires '#include' lines which may conflict with

  17006.      inferior symbols otherwise.

  17007. 

  17008. 'compile file FILENAME'

  17009. 'compile file -raw FILENAME'

  17010.      Like 'compile code', but take the source code from FILENAME.

  17011. 

  17012.           compile file /home/user/example.c

  17013. 

  17014. 'compile print [[OPTIONS] --] EXPR'

  17015. 'compile print [[OPTIONS] --] /F EXPR'

  17016.      Compile and execute EXPR with the compiler language found as the

  17017.      current language in GDB (*note Languages::).  By default the value

  17018.      of EXPR is printed in a format appropriate to its data type; you

  17019.      can choose a different format by specifying '/F', where F is a

  17020.      letter specifying the format; see *note Output Formats: Output

  17021.      Formats.  The 'compile print' command accepts the same options as

  17022.      the 'print' command; see *note print options::.

  17023. 

  17024. 'compile print [[OPTIONS] --]'

  17025. 'compile print [[OPTIONS] --] /F'

  17026.      Alternatively you can enter the expression (source code producing

  17027.      it) as multiple lines of text.  To enter this mode, invoke the

  17028.      'compile print' command without any text following the command.

  17029.      This will start the multiple-line editor.

  17030. 

  17031. The process of compiling and injecting the code can be inspected using:

  17032. 

  17033. 'set debug compile'

  17034.      Turns on or off display of GDB process of compiling and injecting

  17035.      the code.  The default is off.

  17036. 

  17037. 'show debug compile'

  17038.      Displays the current state of displaying GDB process of compiling

  17039.      and injecting the code.

  17040. 

  17041. 'set debug compile-cplus-types'

  17042.      Turns on or off the display of C++ type conversion debugging

  17043.      information.  The default is off.

  17044. 

  17045. 'show debug compile-cplus-types'

  17046.      Displays the current state of displaying debugging information for

  17047.      C++ type conversion.

  17048. 

  17049. 17.7.1 Compilation options for the 'compile' command

  17050. ----------------------------------------------------

  17051. 

  17052. GDB needs to specify the right compilation options for the code to be

  17053. injected, in part to make its ABI compatible with the inferior and in

  17054. part to make the injected code compatible with GDB's injecting process.

  17055. 

  17056. The options used, in increasing precedence:

  17057. 

  17058. target architecture and OS options ('gdbarch')

  17059.      These options depend on target processor type and target operating

  17060.      system, usually they specify at least 32-bit ('-m32') or 64-bit

  17061.      ('-m64') compilation option.

  17062. 

  17063. compilation options recorded in the target

  17064.      GCC (since version 4.7) stores the options used for compilation

  17065.      into 'DW_AT_producer' part of DWARF debugging information according

  17066.      to the GCC option '-grecord-gcc-switches'.  One has to explicitly

  17067.      specify '-g' during inferior compilation otherwise GCC produces no

  17068.      DWARF. This feature is only relevant for platforms where '-g'

  17069.      produces DWARF by default, otherwise one may try to enforce DWARF

  17070.      by using '-gdwarf-4'.

  17071. 

  17072. compilation options set by 'set compile-args'

  17073. 

  17074. You can override compilation options using the following command:

  17075. 

  17076. 'set compile-args'

  17077.      Set compilation options used for compiling and injecting code with

  17078.      the 'compile' commands.  These options override any conflicting

  17079.      ones from the target architecture and/or options stored during

  17080.      inferior compilation.

  17081. 

  17082. 'show compile-args'

  17083.      Displays the current state of compilation options override.  This

  17084.      does not show all the options actually used during compilation, use

  17085.      *note set debug compile:: for that.

  17086. 

  17087. 17.7.2 Caveats when using the 'compile' command

  17088. -----------------------------------------------

  17089. 

  17090. There are a few caveats to keep in mind when using the 'compile'

  17091. command.  As the caveats are different per language, the table below

  17092. highlights specific issues on a per language basis.

  17093. 

  17094. C code examples and caveats

  17095.      When the language in GDB is set to 'C', the compiler will attempt

  17096.      to compile the source code with a 'C' compiler.  The source code

  17097.      provided to the 'compile' command will have much the same access to

  17098.      variables and types as it normally would if it were part of the

  17099.      program currently being debugged in GDB.

  17100. 

  17101.      Below is a sample program that forms the basis of the examples that

  17102.      follow.  This program has been compiled and loaded into GDB, much

  17103.      like any other normal debugging session.

  17104. 

  17105.           void function1 (void)

  17106.           {

  17107.              int i = 42;

  17108.              printf ("function 1\n");

  17109.           }

  17110. 

  17111.           void function2 (void)

  17112.           {

  17113.              int j = 12;

  17114.              function1 ();

  17115.           }

  17116. 

  17117.           int main(void)

  17118.           {

  17119.              int k = 6;

  17120.              int *p;

  17121.              function2 ();

  17122.              return 0;

  17123.           }

  17124. 

  17125.      For the purposes of the examples in this section, the program above

  17126.      has been compiled, loaded into GDB, stopped at the function 'main',

  17127.      and GDB is awaiting input from the user.

  17128. 

  17129.      To access variables and types for any program in GDB, the program

  17130.      must be compiled and packaged with debug information.  The

  17131.      'compile' command is not an exception to this rule.  Without debug

  17132.      information, you can still use the 'compile' command, but you will

  17133.      be very limited in what variables and types you can access.

  17134. 

  17135.      So with that in mind, the example above has been compiled with

  17136.      debug information enabled.  The 'compile' command will have access

  17137.      to all variables and types (except those that may have been

  17138.      optimized out).  Currently, as GDB has stopped the program in the

  17139.      'main' function, the 'compile' command would have access to the

  17140.      variable 'k'.  You could invoke the 'compile' command and type some

  17141.      source code to set the value of 'k'.  You can also read it, or do

  17142.      anything with that variable you would normally do in 'C'.  Be aware

  17143.      that changes to inferior variables in the 'compile' command are

  17144.      persistent.  In the following example:

  17145. 

  17146.           compile code k = 3;

  17147. 

  17148.      the variable 'k' is now 3.  It will retain that value until

  17149.      something else in the example program changes it, or another

  17150.      'compile' command changes it.

  17151. 

  17152.      Normal scope and access rules apply to source code compiled and

  17153.      injected by the 'compile' command.  In the example, the variables

  17154.      'j' and 'k' are not accessible yet, because the program is

  17155.      currently stopped in the 'main' function, where these variables are

  17156.      not in scope.  Therefore, the following command

  17157. 

  17158.           compile code j = 3;

  17159. 

  17160.      will result in a compilation error message.

  17161. 

  17162.      Once the program is continued, execution will bring these variables

  17163.      in scope, and they will become accessible; then the code you

  17164.      specify via the 'compile' command will be able to access them.

  17165. 

  17166.      You can create variables and types with the 'compile' command as

  17167.      part of your source code.  Variables and types that are created as

  17168.      part of the 'compile' command are not visible to the rest of the

  17169.      program for the duration of its run.  This example is valid:

  17170. 

  17171.           compile code int ff = 5; printf ("ff is %d\n", ff);

  17172. 

  17173.      However, if you were to type the following into GDB after that

  17174.      command has completed:

  17175. 

  17176.           compile code printf ("ff is %d\n'', ff);

  17177. 

  17178.      a compiler error would be raised as the variable 'ff' no longer

  17179.      exists.  Object code generated and injected by the 'compile'

  17180.      command is removed when its execution ends.  Caution is advised

  17181.      when assigning to program variables values of variables created by

  17182.      the code submitted to the 'compile' command.  This example is

  17183.      valid:

  17184. 

  17185.           compile code int ff = 5; k = ff;

  17186. 

  17187.      The value of the variable 'ff' is assigned to 'k'.  The variable

  17188.      'k' does not require the existence of 'ff' to maintain the value it

  17189.      has been assigned.  However, pointers require particular care in

  17190.      assignment.  If the source code compiled with the 'compile' command

  17191.      changed the address of a pointer in the example program, perhaps to

  17192.      a variable created in the 'compile' command, that pointer would

  17193.      point to an invalid location when the command exits.  The following

  17194.      example would likely cause issues with your debugged program:

  17195. 

  17196.           compile code int ff = 5; p = &ff;

  17197. 

  17198.      In this example, 'p' would point to 'ff' when the 'compile' command

  17199.      is executing the source code provided to it.  However, as variables

  17200.      in the (example) program persist with their assigned values, the

  17201.      variable 'p' would point to an invalid location when the command

  17202.      exists.  A general rule should be followed in that you should

  17203.      either assign 'NULL' to any assigned pointers, or restore a valid

  17204.      location to the pointer before the command exits.

  17205. 

  17206.      Similar caution must be exercised with any structs, unions, and

  17207.      typedefs defined in 'compile' command.  Types defined in the

  17208.      'compile' command will no longer be available in the next 'compile'

  17209.      command.  Therefore, if you cast a variable to a type defined in

  17210.      the 'compile' command, care must be taken to ensure that any future

  17211.      need to resolve the type can be achieved.

  17212. 

  17213.           (gdb) compile code static struct a { int a; } v = { 42 }; argv = &v;

  17214.           (gdb) compile code printf ("%d\n", ((struct a *) argv)->a);

  17215.           gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’

  17216.           Compilation failed.

  17217.           (gdb) compile code struct a { int a; }; printf ("%d\n", ((struct a *) argv)->a);

  17218.           42

  17219. 

  17220.      Variables that have been optimized away by the compiler are not

  17221.      accessible to the code submitted to the 'compile' command.  Access

  17222.      to those variables will generate a compiler error which GDB will

  17223.      print to the console.

  17224. 

  17225. 17.7.3 Compiler search for the 'compile' command

  17226. ------------------------------------------------

  17227. 

  17228. GDB needs to find GCC for the inferior being debugged which may not be

  17229. obvious for remote targets of different architecture than where GDB is

  17230. running.  Environment variable 'PATH' on GDB host is searched for GCC

  17231. binary matching the target architecture and operating system.  This

  17232. search can be overriden by 'set compile-gcc' GDB command below.  'PATH'

  17233. is taken from shell that executed GDB, it is not the value set by GDB

  17234. command 'set environment').  *Note Environment::.

  17235. 

  17236.    Specifically 'PATH' is searched for binaries matching regular

  17237. expression 'ARCH(-[^-]*)?-OS-gcc' according to the inferior target being

  17238. debugged.  ARCH is processor name -- multiarch is supported, so for

  17239. example both 'i386' and 'x86_64' targets look for pattern

  17240. '(x86_64|i.86)' and both 's390' and 's390x' targets look for pattern

  17241. 's390x?'.  OS is currently supported only for pattern 'linux(-gnu)?'.

  17242. 

  17243.    On Posix hosts the compiler driver GDB needs to find also shared

  17244. library 'libcc1.so' from the compiler.  It is searched in default shared

  17245. library search path (overridable with usual environment variable

  17246. 'LD_LIBRARY_PATH'), unrelated to 'PATH' or 'set compile-gcc' settings.

  17247. Contrary to it 'libcc1plugin.so' is found according to the installation

  17248. of the found compiler -- as possibly specified by the 'set compile-gcc'

  17249. command.

  17250. 

  17251. 'set compile-gcc'

  17252.      Set compilation command used for compiling and injecting code with

  17253.      the 'compile' commands.  If this option is not set (it is set to an

  17254.      empty string), the search described above will occur -- that is the

  17255.      default.

  17256. 

  17257. 'show compile-gcc'

  17258.      Displays the current compile command GCC driver filename.  If set,

  17259.      it is the main command 'gcc', found usually for example under name

  17260.      'x86_64-linux-gnu-gcc'.

  17261. 

  17262. 

  17263. File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top

  17264. 

  17265. 18 GDB Files

  17266. ************

  17267. 

  17268. GDB needs to know the file name of the program to be debugged, both in

  17269. order to read its symbol table and in order to start your program.  To

  17270. debug a core dump of a previous run, you must also tell GDB the name of

  17271. the core dump file.

  17272. 

  17273. * Menu:

  17274. 

  17275. * Files::                       Commands to specify files

  17276. * File Caching::                Information about GDB's file caching

  17277. * Separate Debug Files::        Debugging information in separate files

  17278. * MiniDebugInfo::               Debugging information in a special section

  17279. * Index Files::                 Index files speed up GDB

  17280. * Symbol Errors::               Errors reading symbol files

  17281. * Data Files::                  GDB data files

  17282. 

  17283. 

  17284. File: gdb.info,  Node: Files,  Next: File Caching,  Up: GDB Files

  17285. 

  17286. 18.1 Commands to Specify Files

  17287. ==============================

  17288. 

  17289. You may want to specify executable and core dump file names.  The usual

  17290. way to do this is at start-up time, using the arguments to GDB's

  17291. start-up commands (*note Getting In and Out of GDB: Invocation.).

  17292. 

  17293.    Occasionally it is necessary to change to a different file during a

  17294. GDB session.  Or you may run GDB and forget to specify a file you want

  17295. to use.  Or you are debugging a remote target via 'gdbserver' (*note

  17296. file: Server.).  In these situations the GDB commands to specify new

  17297. files are useful.

  17298. 

  17299. 'file FILENAME'

  17300.      Use FILENAME as the program to be debugged.  It is read for its

  17301.      symbols and for the contents of pure memory.  It is also the

  17302.      program executed when you use the 'run' command.  If you do not

  17303.      specify a directory and the file is not found in the GDB working

  17304.      directory, GDB uses the environment variable 'PATH' as a list of

  17305.      directories to search, just as the shell does when looking for a

  17306.      program to run.  You can change the value of this variable, for

  17307.      both GDB and your program, using the 'path' command.

  17308. 

  17309.      You can load unlinked object '.o' files into GDB using the 'file'

  17310.      command.  You will not be able to "run" an object file, but you can

  17311.      disassemble functions and inspect variables.  Also, if the

  17312.      underlying BFD functionality supports it, you could use 'gdb

  17313.      -write' to patch object files using this technique.  Note that GDB

  17314.      can neither interpret nor modify relocations in this case, so

  17315.      branches and some initialized variables will appear to go to the

  17316.      wrong place.  But this feature is still handy from time to time.

  17317. 

  17318. 'file'

  17319.      'file' with no argument makes GDB discard any information it has on

  17320.      both executable file and the symbol table.

  17321. 

  17322. 'exec-file [ FILENAME ]'

  17323.      Specify that the program to be run (but not the symbol table) is

  17324.      found in FILENAME.  GDB searches the environment variable 'PATH' if

  17325.      necessary to locate your program.  Omitting FILENAME means to

  17326.      discard information on the executable file.

  17327. 

  17328. 'symbol-file [ FILENAME [ -o OFFSET ]]'

  17329.      Read symbol table information from file FILENAME.  'PATH' is

  17330.      searched when necessary.  Use the 'file' command to get both symbol

  17331.      table and program to run from the same file.

  17332. 

  17333.      If an optional OFFSET is specified, it is added to the start

  17334.      address of each section in the symbol file.  This is useful if the

  17335.      program is relocated at runtime, such as the Linux kernel with

  17336.      kASLR enabled.

  17337. 

  17338.      'symbol-file' with no argument clears out GDB information on your

  17339.      program's symbol table.

  17340. 

  17341.      The 'symbol-file' command causes GDB to forget the contents of some

  17342.      breakpoints and auto-display expressions.  This is because they may

  17343.      contain pointers to the internal data recording symbols and data

  17344.      types, which are part of the old symbol table data being discarded

  17345.      inside GDB.

  17346. 

  17347.      'symbol-file' does not repeat if you press <RET> again after

  17348.      executing it once.

  17349. 

  17350.      When GDB is configured for a particular environment, it understands

  17351.      debugging information in whatever format is the standard generated

  17352.      for that environment; you may use either a GNU compiler, or other

  17353.      compilers that adhere to the local conventions.  Best results are

  17354.      usually obtained from GNU compilers; for example, using 'GCC' you

  17355.      can generate debugging information for optimized code.

  17356. 

  17357.      For most kinds of object files, with the exception of old SVR3

  17358.      systems using COFF, the 'symbol-file' command does not normally

  17359.      read the symbol table in full right away.  Instead, it scans the

  17360.      symbol table quickly to find which source files and which symbols

  17361.      are present.  The details are read later, one source file at a

  17362.      time, as they are needed.

  17363. 

  17364.      The purpose of this two-stage reading strategy is to make GDB start

  17365.      up faster.  For the most part, it is invisible except for

  17366.      occasional pauses while the symbol table details for a particular

  17367.      source file are being read.  (The 'set verbose' command can turn

  17368.      these pauses into messages if desired.  *Note Optional Warnings and

  17369.      Messages: Messages/Warnings.)

  17370. 

  17371.      We have not implemented the two-stage strategy for COFF yet.  When

  17372.      the symbol table is stored in COFF format, 'symbol-file' reads the

  17373.      symbol table data in full right away.  Note that "stabs-in-COFF"

  17374.      still does the two-stage strategy, since the debug info is actually

  17375.      in stabs format.

  17376. 

  17377. 'symbol-file [ -readnow ] FILENAME'

  17378. 'file [ -readnow ] FILENAME'

  17379.      You can override the GDB two-stage strategy for reading symbol

  17380.      tables by using the '-readnow' option with any of the commands that

  17381.      load symbol table information, if you want to be sure GDB has the

  17382.      entire symbol table available.

  17383. 

  17384. 'symbol-file [ -readnever ] FILENAME'

  17385. 'file [ -readnever ] FILENAME'

  17386.      You can instruct GDB to never read the symbolic information

  17387.      contained in FILENAME by using the '-readnever' option.  *Note

  17388.      --readnever::.

  17389. 

  17390. 'core-file [FILENAME]'

  17391. 'core'

  17392.      Specify the whereabouts of a core dump file to be used as the

  17393.      "contents of memory".  Traditionally, core files contain only some

  17394.      parts of the address space of the process that generated them; GDB

  17395.      can access the executable file itself for other parts.

  17396. 

  17397.      'core-file' with no argument specifies that no core file is to be

  17398.      used.

  17399. 

  17400.      Note that the core file is ignored when your program is actually

  17401.      running under GDB.  So, if you have been running your program and

  17402.      you wish to debug a core file instead, you must kill the subprocess

  17403.      in which the program is running.  To do this, use the 'kill'

  17404.      command (*note Killing the Child Process: Kill Process.).

  17405. 

  17406. 'add-symbol-file FILENAME [ -readnow | -readnever ] [ -o OFFSET ] [ TEXTADDRESS ] [ -s SECTION ADDRESS ... ]'

  17407.      The 'add-symbol-file' command reads additional symbol table

  17408.      information from the file FILENAME.  You would use this command

  17409.      when FILENAME has been dynamically loaded (by some other means)

  17410.      into the program that is running.  The TEXTADDRESS parameter gives

  17411.      the memory address at which the file's text section has been

  17412.      loaded.  You can additionally specify the base address of other

  17413.      sections using an arbitrary number of '-s SECTION ADDRESS' pairs.

  17414.      If a section is omitted, GDB will use its default addresses as

  17415.      found in FILENAME.  Any ADDRESS or TEXTADDRESS can be given as an

  17416.      expression.

  17417. 

  17418.      If an optional OFFSET is specified, it is added to the start

  17419.      address of each section, except those for which the address was

  17420.      specified explicitly.

  17421. 

  17422.      The symbol table of the file FILENAME is added to the symbol table

  17423.      originally read with the 'symbol-file' command.  You can use the

  17424.      'add-symbol-file' command any number of times; the new symbol data

  17425.      thus read is kept in addition to the old.

  17426. 

  17427.      Changes can be reverted using the command 'remove-symbol-file'.

  17428. 

  17429.      Although FILENAME is typically a shared library file, an executable

  17430.      file, or some other object file which has been fully relocated for

  17431.      loading into a process, you can also load symbolic information from

  17432.      relocatable '.o' files, as long as:

  17433. 

  17434.         * the file's symbolic information refers only to linker symbols

  17435.           defined in that file, not to symbols defined by other object

  17436.           files,

  17437.         * every section the file's symbolic information refers to has

  17438.           actually been loaded into the inferior, as it appears in the

  17439.           file, and

  17440.         * you can determine the address at which every section was

  17441.           loaded, and provide these to the 'add-symbol-file' command.

  17442. 

  17443.      Some embedded operating systems, like Sun Chorus and VxWorks, can

  17444.      load relocatable files into an already running program; such

  17445.      systems typically make the requirements above easy to meet.

  17446.      However, it's important to recognize that many native systems use

  17447.      complex link procedures ('.linkonce' section factoring and C++

  17448.      constructor table assembly, for example) that make the requirements

  17449.      difficult to meet.  In general, one cannot assume that using

  17450.      'add-symbol-file' to read a relocatable object file's symbolic

  17451.      information will have the same effect as linking the relocatable

  17452.      object file into the program in the normal way.

  17453. 

  17454.      'add-symbol-file' does not repeat if you press <RET> after using

  17455.      it.

  17456. 

  17457. 'remove-symbol-file FILENAME'

  17458. 'remove-symbol-file -a ADDRESS'

  17459.      Remove a symbol file added via the 'add-symbol-file' command.  The

  17460.      file to remove can be identified by its FILENAME or by an ADDRESS

  17461.      that lies within the boundaries of this symbol file in memory.

  17462.      Example:

  17463. 

  17464.           (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480

  17465.           add symbol table from file "/home/user/gdb/mylib.so" at

  17466.               .text_addr = 0x7ffff7ff9480

  17467.           (y or n) y

  17468.           Reading symbols from /home/user/gdb/mylib.so...

  17469.           (gdb) remove-symbol-file -a 0x7ffff7ff9480

  17470.           Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y

  17471.           (gdb)

  17472. 

  17473.      'remove-symbol-file' does not repeat if you press <RET> after using

  17474.      it.

  17475. 

  17476. 'add-symbol-file-from-memory ADDRESS'

  17477.      Load symbols from the given ADDRESS in a dynamically loaded object

  17478.      file whose image is mapped directly into the inferior's memory.

  17479.      For example, the Linux kernel maps a 'syscall DSO' into each

  17480.      process's address space; this DSO provides kernel-specific code for

  17481.      some system calls.  The argument can be any expression whose

  17482.      evaluation yields the address of the file's shared object file

  17483.      header.  For this command to work, you must have used 'symbol-file'

  17484.      or 'exec-file' commands in advance.

  17485. 

  17486. 'section SECTION ADDR'

  17487.      The 'section' command changes the base address of the named SECTION

  17488.      of the exec file to ADDR.  This can be used if the exec file does

  17489.      not contain section addresses, (such as in the 'a.out' format), or

  17490.      when the addresses specified in the file itself are wrong.  Each

  17491.      section must be changed separately.  The 'info files' command,

  17492.      described below, lists all the sections and their addresses.

  17493. 

  17494. 'info files'

  17495. 'info target'

  17496.      'info files' and 'info target' are synonymous; both print the

  17497.      current target (*note Specifying a Debugging Target: Targets.),

  17498.      including the names of the executable and core dump files currently

  17499.      in use by GDB, and the files from which symbols were loaded.  The

  17500.      command 'help target' lists all possible targets rather than

  17501.      current ones.

  17502. 

  17503. 'maint info sections'

  17504.      Another command that can give you extra information about program

  17505.      sections is 'maint info sections'.  In addition to the section

  17506.      information displayed by 'info files', this command displays the

  17507.      flags and file offset of each section in the executable and core

  17508.      dump files.  In addition, 'maint info sections' provides the

  17509.      following command options (which may be arbitrarily combined):

  17510. 

  17511.      'ALLOBJ'

  17512.           Display sections for all loaded object files, including shared

  17513.           libraries.

  17514.      'SECTIONS'

  17515.           Display info only for named SECTIONS.

  17516.      'SECTION-FLAGS'

  17517.           Display info only for sections for which SECTION-FLAGS are

  17518.           true.  The section flags that GDB currently knows about are:

  17519.           'ALLOC'

  17520.                Section will have space allocated in the process when

  17521.                loaded.  Set for all sections except those containing

  17522.                debug information.

  17523.           'LOAD'

  17524.                Section will be loaded from the file into the child

  17525.                process memory.  Set for pre-initialized code and data,

  17526.                clear for '.bss' sections.

  17527.           'RELOC'

  17528.                Section needs to be relocated before loading.

  17529.           'READONLY'

  17530.                Section cannot be modified by the child process.

  17531.           'CODE'

  17532.                Section contains executable code only.

  17533.           'DATA'

  17534.                Section contains data only (no executable code).

  17535.           'ROM'

  17536.                Section will reside in ROM.

  17537.           'CONSTRUCTOR'

  17538.                Section contains data for constructor/destructor lists.

  17539.           'HAS_CONTENTS'

  17540.                Section is not empty.

  17541.           'NEVER_LOAD'

  17542.                An instruction to the linker to not output the section.

  17543.           'COFF_SHARED_LIBRARY'

  17544.                A notification to the linker that the section contains

  17545.                COFF shared library information.

  17546.           'IS_COMMON'

  17547.                Section contains common symbols.

  17548. 'set trust-readonly-sections on'

  17549.      Tell GDB that readonly sections in your object file really are

  17550.      read-only (i.e. that their contents will not change).  In that

  17551.      case, GDB can fetch values from these sections out of the object

  17552.      file, rather than from the target program.  For some targets

  17553.      (notably embedded ones), this can be a significant enhancement to

  17554.      debugging performance.

  17555. 

  17556.      The default is off.

  17557. 

  17558. 'set trust-readonly-sections off'

  17559.      Tell GDB not to trust readonly sections.  This means that the

  17560.      contents of the section might change while the program is running,

  17561.      and must therefore be fetched from the target when needed.

  17562. 

  17563. 'show trust-readonly-sections'

  17564.      Show the current setting of trusting readonly sections.

  17565. 

  17566.    All file-specifying commands allow both absolute and relative file

  17567. names as arguments.  GDB always converts the file name to an absolute

  17568. file name and remembers it that way.

  17569. 

  17570.    GDB supports GNU/Linux, MS-Windows, SunOS, Darwin/Mach-O, SVr4, IBM

  17571. RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and DSBT (TIC6X) shared

  17572. libraries.

  17573. 

  17574.    On MS-Windows GDB must be linked with the Expat library to support

  17575. shared libraries.  *Note Expat::.

  17576. 

  17577.    GDB automatically loads symbol definitions from shared libraries when

  17578. you use the 'run' command, or when you examine a core file.  (Before you

  17579. issue the 'run' command, GDB does not understand references to a

  17580. function in a shared library, however--unless you are debugging a core

  17581. file).

  17582. 

  17583.    There are times, however, when you may wish to not automatically load

  17584. symbol definitions from shared libraries, such as when they are

  17585. particularly large or there are many of them.

  17586. 

  17587.    To control the automatic loading of shared library symbols, use the

  17588. commands:

  17589. 

  17590. 'set auto-solib-add MODE'

  17591.      If MODE is 'on', symbols from all shared object libraries will be

  17592.      loaded automatically when the inferior begins execution, you attach

  17593.      to an independently started inferior, or when the dynamic linker

  17594.      informs GDB that a new library has been loaded.  If MODE is 'off',

  17595.      symbols must be loaded manually, using the 'sharedlibrary' command.

  17596.      The default value is 'on'.

  17597. 

  17598.      If your program uses lots of shared libraries with debug info that

  17599.      takes large amounts of memory, you can decrease the GDB memory

  17600.      footprint by preventing it from automatically loading the symbols

  17601.      from shared libraries.  To that end, type 'set auto-solib-add off'

  17602.      before running the inferior, then load each library whose debug

  17603.      symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a

  17604.      regular expression that matches the libraries whose symbols you

  17605.      want to be loaded.

  17606. 

  17607. 'show auto-solib-add'

  17608.      Display the current autoloading mode.

  17609. 

  17610.    To explicitly load shared library symbols, use the 'sharedlibrary'

  17611. command:

  17612. 

  17613. 'info share REGEX'

  17614. 'info sharedlibrary REGEX'

  17615.      Print the names of the shared libraries which are currently loaded

  17616.      that match REGEX.  If REGEX is omitted then print all shared

  17617.      libraries that are loaded.

  17618. 

  17619. 'info dll REGEX'

  17620.      This is an alias of 'info sharedlibrary'.

  17621. 

  17622. 'sharedlibrary REGEX'

  17623. 'share REGEX'

  17624.      Load shared object library symbols for files matching a Unix

  17625.      regular expression.  As with files loaded automatically, it only

  17626.      loads shared libraries required by your program for a core file or

  17627.      after typing 'run'.  If REGEX is omitted all shared libraries

  17628.      required by your program are loaded.

  17629. 

  17630. 'nosharedlibrary'

  17631.      Unload all shared object library symbols.  This discards all

  17632.      symbols that have been loaded from all shared libraries.  Symbols

  17633.      from shared libraries that were loaded by explicit user requests

  17634.      are not discarded.

  17635. 

  17636.    Sometimes you may wish that GDB stops and gives you control when any

  17637. of shared library events happen.  The best way to do this is to use

  17638. 'catch load' and 'catch unload' (*note Set Catchpoints::).

  17639. 

  17640.    GDB also supports the 'set stop-on-solib-events' command for this.

  17641. This command exists for historical reasons.  It is less useful than

  17642. setting a catchpoint, because it does not allow for conditions or

  17643. commands as a catchpoint does.

  17644. 

  17645. 'set stop-on-solib-events'

  17646.      This command controls whether GDB should give you control when the

  17647.      dynamic linker notifies it about some shared library event.  The

  17648.      most common event of interest is loading or unloading of a new

  17649.      shared library.

  17650. 

  17651. 'show stop-on-solib-events'

  17652.      Show whether GDB stops and gives you control when shared library

  17653.      events happen.

  17654. 

  17655.    Shared libraries are also supported in many cross or remote debugging

  17656. configurations.  GDB needs to have access to the target's libraries;

  17657. this can be accomplished either by providing copies of the libraries on

  17658. the host system, or by asking GDB to automatically retrieve the

  17659. libraries from the target.  If copies of the target libraries are

  17660. provided, they need to be the same as the target libraries, although the

  17661. copies on the target can be stripped as long as the copies on the host

  17662. are not.

  17663. 

  17664.    For remote debugging, you need to tell GDB where the target libraries

  17665. are, so that it can load the correct copies--otherwise, it may try to

  17666. load the host's libraries.  GDB has two variables to specify the search

  17667. directories for target libraries.

  17668. 

  17669. 'set sysroot PATH'

  17670.      Use PATH as the system root for the program being debugged.  Any

  17671.      absolute shared library paths will be prefixed with PATH; many

  17672.      runtime loaders store the absolute paths to the shared library in

  17673.      the target program's memory.  When starting processes remotely, and

  17674.      when attaching to already-running processes (local or remote),

  17675.      their executable filenames will be prefixed with PATH if reported

  17676.      to GDB as absolute by the operating system.  If you use 'set

  17677.      sysroot' to find executables and shared libraries, they need to be

  17678.      laid out in the same way that they are on the target, with e.g. a

  17679.      '/bin', '/lib' and '/usr/lib' hierarchy under PATH.

  17680. 

  17681.      If PATH starts with the sequence 'target:' and the target system is

  17682.      remote then GDB will retrieve the target binaries from the remote

  17683.      system.  This is only supported when using a remote target that

  17684.      supports the 'remote get' command (*note Sending files to a remote

  17685.      system: File Transfer.).  The part of PATH following the initial

  17686.      'target:' (if present) is used as system root prefix on the remote

  17687.      file system.  If PATH starts with the sequence 'remote:' this is

  17688.      converted to the sequence 'target:' by 'set sysroot'(1).  If you

  17689.      want to specify a local system root using a directory that happens

  17690.      to be named 'target:' or 'remote:', you need to use some equivalent

  17691.      variant of the name like './target:'.

  17692. 

  17693.      For targets with an MS-DOS based filesystem, such as MS-Windows and

  17694.      SymbianOS, GDB tries prefixing a few variants of the target

  17695.      absolute file name with PATH.  But first, on Unix hosts, GDB

  17696.      converts all backslash directory separators into forward slashes,

  17697.      because the backslash is not a directory separator on Unix:

  17698. 

  17699.             c:\foo\bar.dll => c:/foo/bar.dll

  17700. 

  17701.      Then, GDB attempts prefixing the target file name with PATH, and

  17702.      looks for the resulting file name in the host file system:

  17703. 

  17704.             c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll

  17705. 

  17706.      If that does not find the binary, GDB tries removing the ':'

  17707.      character from the drive spec, both for convenience, and, for the

  17708.      case of the host file system not supporting file names with colons:

  17709. 

  17710.             c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll

  17711. 

  17712.      This makes it possible to have a system root that mirrors a target

  17713.      with more than one drive.  E.g., you may want to setup your local

  17714.      copies of the target system shared libraries like so (note 'c' vs

  17715.      'z'):

  17716. 

  17717.            /path/to/sysroot/c/sys/bin/foo.dll

  17718.            /path/to/sysroot/c/sys/bin/bar.dll

  17719.            /path/to/sysroot/z/sys/bin/bar.dll

  17720. 

  17721.      and point the system root at '/path/to/sysroot', so that GDB can

  17722.      find the correct copies of both 'c:\sys\bin\foo.dll', and

  17723.      'z:\sys\bin\bar.dll'.

  17724. 

  17725.      If that still does not find the binary, GDB tries removing the

  17726.      whole drive spec from the target file name:

  17727. 

  17728.             c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll

  17729. 

  17730.      This last lookup makes it possible to not care about the drive

  17731.      name, if you don't want or need to.

  17732. 

  17733.      The 'set solib-absolute-prefix' command is an alias for 'set

  17734.      sysroot'.

  17735. 

  17736.      You can set the default system root by using the configure-time

  17737.      '--with-sysroot' option.  If the system root is inside GDB's

  17738.      configured binary prefix (set with '--prefix' or '--exec-prefix'),

  17739.      then the default system root will be updated automatically if the

  17740.      installed GDB is moved to a new location.

  17741. 

  17742. 'show sysroot'

  17743.      Display the current executable and shared library prefix.

  17744. 

  17745. 'set solib-search-path PATH'

  17746.      If this variable is set, PATH is a colon-separated list of

  17747.      directories to search for shared libraries.  'solib-search-path' is

  17748.      used after 'sysroot' fails to locate the library, or if the path to

  17749.      the library is relative instead of absolute.  If you want to use

  17750.      'solib-search-path' instead of 'sysroot', be sure to set 'sysroot'

  17751.      to a nonexistent directory to prevent GDB from finding your host's

  17752.      libraries.  'sysroot' is preferred; setting it to a nonexistent

  17753.      directory may interfere with automatic loading of shared library

  17754.      symbols.

  17755. 

  17756. 'show solib-search-path'

  17757.      Display the current shared library search path.

  17758. 

  17759. 'set target-file-system-kind KIND'

  17760.      Set assumed file system kind for target reported file names.

  17761. 

  17762.      Shared library file names as reported by the target system may not

  17763.      make sense as is on the system GDB is running on.  For example,

  17764.      when remote debugging a target that has MS-DOS based file system

  17765.      semantics, from a Unix host, the target may be reporting to GDB a

  17766.      list of loaded shared libraries with file names such as

  17767.      'c:\Windows\kernel32.dll'.  On Unix hosts, there's no concept of

  17768.      drive letters, so the 'c:\' prefix is not normally understood as

  17769.      indicating an absolute file name, and neither is the backslash

  17770.      normally considered a directory separator character.  In that case,

  17771.      the native file system would interpret this whole absolute file

  17772.      name as a relative file name with no directory components.  This

  17773.      would make it impossible to point GDB at a copy of the remote

  17774.      target's shared libraries on the host using 'set sysroot', and

  17775.      impractical with 'set solib-search-path'.  Setting

  17776.      'target-file-system-kind' to 'dos-based' tells GDB to interpret

  17777.      such file names similarly to how the target would, and to map them

  17778.      to file names valid on GDB's native file system semantics.  The

  17779.      value of KIND can be '"auto"', in addition to one of the supported

  17780.      file system kinds.  In that case, GDB tries to determine the

  17781.      appropriate file system variant based on the current target's

  17782.      operating system (*note Configuring the Current ABI: ABI.). The

  17783.      supported file system settings are:

  17784. 

  17785.      'unix'

  17786.           Instruct GDB to assume the target file system is of Unix kind.

  17787.           Only file names starting the forward slash ('/') character are

  17788.           considered absolute, and the directory separator character is

  17789.           also the forward slash.

  17790. 

  17791.      'dos-based'

  17792.           Instruct GDB to assume the target file system is DOS based.

  17793.           File names starting with either a forward slash, or a drive

  17794.           letter followed by a colon (e.g., 'c:'), are considered

  17795.           absolute, and both the slash ('/') and the backslash ('\\')

  17796.           characters are considered directory separators.

  17797. 

  17798.      'auto'

  17799.           Instruct GDB to use the file system kind associated with the

  17800.           target operating system (*note Configuring the Current ABI:

  17801.           ABI.). This is the default.

  17802. 

  17803.    When processing file names provided by the user, GDB frequently needs

  17804. to compare them to the file names recorded in the program's debug info.

  17805. Normally, GDB compares just the "base names" of the files as strings,

  17806. which is reasonably fast even for very large programs.  (The base name

  17807. of a file is the last portion of its name, after stripping all the

  17808. leading directories.)  This shortcut in comparison is based upon the

  17809. assumption that files cannot have more than one base name.  This is

  17810. usually true, but references to files that use symlinks or similar

  17811. filesystem facilities violate that assumption.  If your program records

  17812. files using such facilities, or if you provide file names to GDB using

  17813. symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct

  17814. GDB to completely canonicalize each pair of file names it needs to

  17815. compare.  This will make file-name comparisons accurate, but at a price

  17816. of a significant slowdown.

  17817. 

  17818. 'set basenames-may-differ'

  17819.      Set whether a source file may have multiple base names.

  17820. 

  17821. 'show basenames-may-differ'

  17822.      Show whether a source file may have multiple base names.

  17823. 

  17824.    ---------- Footnotes ----------

  17825. 

  17826.    (1) Historically the functionality to retrieve binaries from the

  17827. remote system was provided by prefixing PATH with 'remote:'

  17828. 

  17829. 

  17830. File: gdb.info,  Node: File Caching,  Next: Separate Debug Files,  Prev: Files,  Up: GDB Files

  17831. 

  17832. 18.2 File Caching

  17833. =================

  17834. 

  17835. To speed up file loading, and reduce memory usage, GDB will reuse the

  17836. 'bfd' objects used to track open files.  *Note BFD: (bfd)Top.  The

  17837. following commands allow visibility and control of the caching behavior.

  17838. 

  17839. 'maint info bfds'

  17840.      This prints information about each 'bfd' object that is known to

  17841.      GDB.

  17842. 

  17843. 'maint set bfd-sharing'

  17844. 'maint show bfd-sharing'

  17845.      Control whether 'bfd' objects can be shared.  When sharing is

  17846.      enabled GDB reuses already open 'bfd' objects rather than reopening

  17847.      the same file.  Turning sharing off does not cause already shared

  17848.      'bfd' objects to be unshared, but all future files that are opened

  17849.      will create a new 'bfd' object.  Similarly, re-enabling sharing

  17850.      does not cause multiple existing 'bfd' objects to be collapsed into

  17851.      a single shared 'bfd' object.

  17852. 

  17853. 'set debug bfd-cache LEVEL'

  17854.      Turns on debugging of the bfd cache, setting the level to LEVEL.

  17855. 

  17856. 'show debug bfd-cache'

  17857.      Show the current debugging level of the bfd cache.

  17858. 

  17859. 

  17860. File: gdb.info,  Node: Separate Debug Files,  Next: MiniDebugInfo,  Prev: File Caching,  Up: GDB Files

  17861. 

  17862. 18.3 Debugging Information in Separate Files

  17863. ============================================

  17864. 

  17865. GDB allows you to put a program's debugging information in a file

  17866. separate from the executable itself, in a way that allows GDB to find

  17867. and load the debugging information automatically.  Since debugging

  17868. information can be very large--sometimes larger than the executable code

  17869. itself--some systems distribute debugging information for their

  17870. executables in separate files, which users can install only when they

  17871. need to debug a problem.

  17872. 

  17873.    GDB supports two ways of specifying the separate debug info file:

  17874. 

  17875.    * The executable contains a "debug link" that specifies the name of

  17876.      the separate debug info file.  The separate debug file's name is

  17877.      usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the

  17878.      corresponding executable file without leading directories (e.g.,

  17879.      'ls.debug' for '/usr/bin/ls').  In addition, the debug link

  17880.      specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the

  17881.      debug file, which GDB uses to validate that the executable and the

  17882.      debug file came from the same build.

  17883. 

  17884.    * The executable contains a "build ID", a unique bit string that is

  17885.      also present in the corresponding debug info file.  (This is

  17886.      supported only on some operating systems, when using the ELF or PE

  17887.      file formats for binary files and the GNU Binutils.)  For more

  17888.      details about this feature, see the description of the '--build-id'

  17889.      command-line option in *note Command Line Options: (ld)Options.

  17890.      The debug info file's name is not specified explicitly by the build

  17891.      ID, but can be computed from the build ID, see below.

  17892. 

  17893.    Depending on the way the debug info file is specified, GDB uses two

  17894. different methods of looking for the debug file:

  17895. 

  17896.    * For the "debug link" method, GDB looks up the named file in the

  17897.      directory of the executable file, then in a subdirectory of that

  17898.      directory named '.debug', and finally under each one of the global

  17899.      debug directories, in a subdirectory whose name is identical to the

  17900.      leading directories of the executable's absolute file name.  (On

  17901.      MS-Windows/MS-DOS, the drive letter of the executable's leading

  17902.      directories is converted to a one-letter subdirectory, i.e.

  17903.      'd:/usr/bin/' is converted to '/d/usr/bin/', because Windows

  17904.      filesystems disallow colons in file names.)

  17905. 

  17906.    * For the "build ID" method, GDB looks in the '.build-id'

  17907.      subdirectory of each one of the global debug directories for a file

  17908.      named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters

  17909.      of the build ID bit string, and NNNNNNNN are the rest of the bit

  17910.      string.  (Real build ID strings are 32 or more hex characters, not

  17911.      10.)

  17912. 

  17913.    So, for example, suppose you ask GDB to debug '/usr/bin/ls', which

  17914. has a debug link that specifies the file 'ls.debug', and a build ID

  17915. whose value in hex is 'abcdef1234'.  If the list of the global debug

  17916. directories includes '/usr/lib/debug', then GDB will look for the

  17917. following debug information files, in the indicated order:

  17918. 

  17919.    - '/usr/lib/debug/.build-id/ab/cdef1234.debug'

  17920.    - '/usr/bin/ls.debug'

  17921.    - '/usr/bin/.debug/ls.debug'

  17922.    - '/usr/lib/debug/usr/bin/ls.debug'.

  17923. 

  17924.    Global debugging info directories default to what is set by GDB

  17925. configure option '--with-separate-debug-dir'.  During GDB run you can

  17926. also set the global debugging info directories, and view the list GDB is

  17927. currently using.

  17928. 

  17929. 'set debug-file-directory DIRECTORIES'

  17930.      Set the directories which GDB searches for separate debugging

  17931.      information files to DIRECTORY.  Multiple path components can be

  17932.      set concatenating them by a path separator.

  17933. 

  17934. 'show debug-file-directory'

  17935.      Show the directories GDB searches for separate debugging

  17936.      information files.

  17937. 

  17938.    A debug link is a special section of the executable file named

  17939. '.gnu_debuglink'.  The section must contain:

  17940. 

  17941.    * A filename, with any leading directory components removed, followed

  17942.      by a zero byte,

  17943.    * zero to three bytes of padding, as needed to reach the next

  17944.      four-byte boundary within the section, and

  17945.    * a four-byte CRC checksum, stored in the same endianness used for

  17946.      the executable file itself.  The checksum is computed on the

  17947.      debugging information file's full contents by the function given

  17948.      below, passing zero as the CRC argument.

  17949. 

  17950.    Any executable file format can carry a debug link, as long as it can

  17951. contain a section named '.gnu_debuglink' with the contents described

  17952. above.

  17953. 

  17954.    The build ID is a special section in the executable file (and in

  17955. other ELF binary files that GDB may consider).  This section is often

  17956. named '.note.gnu.build-id', but that name is not mandatory.  It contains

  17957. unique identification for the built files--the ID remains the same

  17958. across multiple builds of the same build tree.  The default algorithm

  17959. SHA1 produces 160 bits (40 hexadecimal characters) of the content for

  17960. the build ID string.  The same section with an identical value is

  17961. present in the original built binary with symbols, in its stripped

  17962. variant, and in the separate debugging information file.

  17963. 

  17964.    The debugging information file itself should be an ordinary

  17965. executable, containing a full set of linker symbols, sections, and

  17966. debugging information.  The sections of the debugging information file

  17967. should have the same names, addresses, and sizes as the original file,

  17968. but they need not contain any data--much like a '.bss' section in an

  17969. ordinary executable.

  17970. 

  17971.    The GNU binary utilities (Binutils) package includes the 'objcopy'

  17972. utility that can produce the separated executable / debugging

  17973. information file pairs using the following commands:

  17974. 

  17975.      objcopy --only-keep-debug foo foo.debug

  17976.      strip -g foo

  17977. 

  17978. These commands remove the debugging information from the executable file

  17979. 'foo' and place it in the file 'foo.debug'.  You can use the first,

  17980. second or both methods to link the two files:

  17981. 

  17982.    * The debug link method needs the following additional command to

  17983.      also leave behind a debug link in 'foo':

  17984. 

  17985.           objcopy --add-gnu-debuglink=foo.debug foo

  17986. 

  17987.      Ulrich Drepper's 'elfutils' package, starting with version 0.53,

  17988.      contains a version of the 'strip' command such that the command

  17989.      'strip foo -f foo.debug' has the same functionality as the two

  17990.      'objcopy' commands and the 'ln -s' command above, together.

  17991. 

  17992.    * Build ID gets embedded into the main executable using 'ld

  17993.      --build-id' or the GCC counterpart 'gcc -Wl,--build-id'.  Build ID

  17994.      support plus compatibility fixes for debug files separation are

  17995.      present in GNU binary utilities (Binutils) package since version

  17996.      2.18.

  17997. 

  17998. 

  17999.    The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3

  18000. using the polynomial:

  18001. 

  18002.       x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}

  18003.       + x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1

  18004. 

  18005.    The function is computed byte at a time, taking the least significant

  18006. bit of each byte first.  The initial pattern '0xffffffff' is used, to

  18007. ensure leading zeros affect the CRC and the final result is inverted to

  18008. ensure trailing zeros also affect the CRC.

  18009. 

  18010.    _Note:_ This is the same CRC polynomial as used in handling the

  18011. "Remote Serial Protocol" 'qCRC' packet (*note qCRC packet::).  However

  18012. in the case of the Remote Serial Protocol, the CRC is computed _most_

  18013. significant bit first, and the result is not inverted, so trailing zeros

  18014. have no effect on the CRC value.

  18015. 

  18016.    To complete the description, we show below the code of the function

  18017. which produces the CRC used in '.gnu_debuglink'.  Inverting the

  18018. initially supplied 'crc' argument means that an initial call to this

  18019. function passing in zero will start computing the CRC using

  18020. '0xffffffff'.

  18021. 

  18022.      unsigned long

  18023.      gnu_debuglink_crc32 (unsigned long crc,

  18024.                           unsigned char *buf, size_t len)

  18025.      {

  18026.        static const unsigned long crc32_table[256] =

  18027.          {

  18028.            0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,

  18029.            0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,

  18030.            0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,

  18031.            0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,

  18032.            0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,

  18033.            0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,

  18034.            0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,

  18035.            0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,

  18036.            0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,

  18037.            0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,

  18038.            0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,

  18039.            0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,

  18040.            0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,

  18041.            0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,

  18042.            0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,

  18043.            0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,

  18044.            0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,

  18045.            0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,

  18046.            0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,

  18047.            0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,

  18048.            0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,

  18049.            0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,

  18050.            0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,

  18051.            0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,

  18052.            0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,

  18053.            0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,

  18054.            0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,

  18055.            0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,

  18056.            0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,

  18057.            0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,

  18058.            0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,

  18059.            0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,

  18060.            0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,

  18061.            0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,

  18062.            0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,

  18063.            0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,

  18064.            0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,

  18065.            0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,

  18066.            0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,

  18067.            0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,

  18068.            0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,

  18069.            0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,

  18070.            0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,

  18071.            0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,

  18072.            0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,

  18073.            0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,

  18074.            0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,

  18075.            0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,

  18076.            0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,

  18077.            0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,

  18078.            0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,

  18079.            0x2d02ef8d

  18080.          };

  18081.        unsigned char *end;

  18082. 

  18083.        crc = ~crc & 0xffffffff;

  18084.        for (end = buf + len; buf < end; ++buf)

  18085.          crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);

  18086.        return ~crc & 0xffffffff;

  18087.      }

  18088. 

  18089. This computation does not apply to the "build ID" method.

  18090. 

  18091. 

  18092. File: gdb.info,  Node: MiniDebugInfo,  Next: Index Files,  Prev: Separate Debug Files,  Up: GDB Files

  18093. 

  18094. 18.4 Debugging information in a special section

  18095. ===============================================

  18096. 

  18097. Some systems ship pre-built executables and libraries that have a

  18098. special '.gnu_debugdata' section.  This feature is called

  18099. "MiniDebugInfo".  This section holds an LZMA-compressed object and is

  18100. used to supply extra symbols for backtraces.

  18101. 

  18102.    The intent of this section is to provide extra minimal debugging

  18103. information for use in simple backtraces.  It is not intended to be a

  18104. replacement for full separate debugging information (*note Separate

  18105. Debug Files::).  The example below shows the intended use; however, GDB

  18106. does not currently put restrictions on what sort of debugging

  18107. information might be included in the section.

  18108. 

  18109.    GDB has support for this extension.  If the section exists, then it

  18110. is used provided that no other source of debugging information can be

  18111. found, and that GDB was configured with LZMA support.

  18112. 

  18113.    This section can be easily created using 'objcopy' and other standard

  18114. utilities:

  18115. 

  18116.      # Extract the dynamic symbols from the main binary, there is no need

  18117.      # to also have these in the normal symbol table.

  18118.      nm -D BINARY --format=posix --defined-only \

  18119.        | awk '{ print $1 }' | sort > dynsyms

  18120. 

  18121.      # Extract all the text (i.e. function) symbols from the debuginfo.

  18122.      # (Note that we actually also accept "D" symbols, for the benefit

  18123.      # of platforms like PowerPC64 that use function descriptors.)

  18124.      nm BINARY --format=posix --defined-only \

  18125.        | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \

  18126.        | sort > funcsyms

  18127. 

  18128.      # Keep all the function symbols not already in the dynamic symbol

  18129.      # table.

  18130.      comm -13 dynsyms funcsyms > keep_symbols

  18131. 

  18132.      # Separate full debug info into debug binary.

  18133.      objcopy --only-keep-debug BINARY debug

  18134. 

  18135.      # Copy the full debuginfo, keeping only a minimal set of symbols and

  18136.      # removing some unnecessary sections.

  18137.      objcopy -S --remove-section .gdb_index --remove-section .comment \

  18138.        --keep-symbols=keep_symbols debug mini_debuginfo

  18139. 

  18140.      # Drop the full debug info from the original binary.

  18141.      strip --strip-all -R .comment BINARY

  18142. 

  18143.      # Inject the compressed data into the .gnu_debugdata section of the

  18144.      # original binary.

  18145.      xz mini_debuginfo

  18146.      objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY

  18147. 

  18148. 

  18149. File: gdb.info,  Node: Index Files,  Next: Symbol Errors,  Prev: MiniDebugInfo,  Up: GDB Files

  18150. 

  18151. 18.5 Index Files Speed Up GDB

  18152. =============================

  18153. 

  18154. When GDB finds a symbol file, it scans the symbols in the file in order

  18155. to construct an internal symbol table.  This lets most GDB operations

  18156. work quickly--at the cost of a delay early on.  For large programs, this

  18157. delay can be quite lengthy, so GDB provides a way to build an index,

  18158. which speeds up startup.

  18159. 

  18160.    For convenience, GDB comes with a program, 'gdb-add-index', which can

  18161. be used to add the index to a symbol file.  It takes the symbol file as

  18162. its only argument:

  18163. 

  18164.      $ gdb-add-index symfile

  18165. 

  18166.    *Note gdb-add-index::.

  18167. 

  18168.    It is also possible to do the work manually.  Here is what

  18169. 'gdb-add-index' does behind the curtains.

  18170. 

  18171.    The index is stored as a section in the symbol file.  GDB can write

  18172. the index to a file, then you can put it into the symbol file using

  18173. 'objcopy'.

  18174. 

  18175.    To create an index file, use the 'save gdb-index' command:

  18176. 

  18177. 'save gdb-index [-dwarf-5] DIRECTORY'

  18178.      Create index files for all symbol files currently known by GDB.

  18179.      For each known SYMBOL-FILE, this command by default creates it

  18180.      produces a single file 'SYMBOL-FILE.gdb-index'.  If you invoke this

  18181.      command with the '-dwarf-5' option, it produces 2 files:

  18182.      'SYMBOL-FILE.debug_names' and 'SYMBOL-FILE.debug_str'.  The files

  18183.      are created in the given DIRECTORY.

  18184. 

  18185.    Once you have created an index file you can merge it into your symbol

  18186. file, here named 'symfile', using 'objcopy':

  18187. 

  18188.      $ objcopy --add-section .gdb_index=symfile.gdb-index \

  18189.          --set-section-flags .gdb_index=readonly symfile symfile

  18190. 

  18191.    Or for '-dwarf-5':

  18192. 

  18193.      $ objcopy --dump-section .debug_str=symfile.debug_str.new symfile

  18194.      $ cat symfile.debug_str >>symfile.debug_str.new

  18195.      $ objcopy --add-section .debug_names=symfile.gdb-index \

  18196.          --set-section-flags .debug_names=readonly \

  18197.          --update-section .debug_str=symfile.debug_str.new symfile symfile

  18198. 

  18199.    GDB will normally ignore older versions of '.gdb_index' sections that

  18200. have been deprecated.  Usually they are deprecated because they are

  18201. missing a new feature or have performance issues.  To tell GDB to use a

  18202. deprecated index section anyway specify 'set

  18203. use-deprecated-index-sections on'.  The default is 'off'.  This can

  18204. speed up startup, but may result in some functionality being lost.

  18205. *Note Index Section Format::.

  18206. 

  18207.    _Warning:_ Setting 'use-deprecated-index-sections' to 'on' must be

  18208. done before gdb reads the file.  The following will not work:

  18209. 

  18210.      $ gdb -ex "set use-deprecated-index-sections on" <program>

  18211. 

  18212.    Instead you must do, for example,

  18213. 

  18214.      $ gdb -iex "set use-deprecated-index-sections on" <program>

  18215. 

  18216.    Indices only work when using DWARF debugging information, not stabs.

  18217. 

  18218. 18.5.1 Automatic symbol index cache

  18219. -----------------------------------

  18220. 

  18221. It is possible for GDB to automatically save a copy of this index in a

  18222. cache on disk and retrieve it from there when loading the same binary in

  18223. the future.  This feature can be turned on with 'set index-cache on'.

  18224. The following commands can be used to tweak the behavior of the index

  18225. cache.

  18226. 

  18227. 'set index-cache on'

  18228. 'set index-cache off'

  18229.      Enable or disable the use of the symbol index cache.

  18230. 

  18231. 'set index-cache directory DIRECTORY'

  18232. 'show index-cache directory'

  18233.      Set/show the directory where index files will be saved.

  18234. 

  18235.      The default value for this directory depends on the host platform.

  18236.      On most systems, the index is cached in the 'gdb' subdirectory of

  18237.      the directory pointed to by the 'XDG_CACHE_HOME' environment

  18238.      variable, if it is defined, else in the '.cache/gdb' subdirectory

  18239.      of your home directory.  However, on some systems, the default may

  18240.      differ according to local convention.

  18241. 

  18242.      There is no limit on the disk space used by index cache.  It is

  18243.      perfectly safe to delete the content of that directory to free up

  18244.      disk space.

  18245. 

  18246. 'show index-cache stats'

  18247.      Print the number of cache hits and misses since the launch of GDB.

  18248. 

  18249. 

  18250. File: gdb.info,  Node: Symbol Errors,  Next: Data Files,  Prev: Index Files,  Up: GDB Files

  18251. 

  18252. 18.6 Errors Reading Symbol Files

  18253. ================================

  18254. 

  18255. While reading a symbol file, GDB occasionally encounters problems, such

  18256. as symbol types it does not recognize, or known bugs in compiler output.

  18257. By default, GDB does not notify you of such problems, since they are

  18258. relatively common and primarily of interest to people debugging

  18259. compilers.  If you are interested in seeing information about

  18260. ill-constructed symbol tables, you can either ask GDB to print only one

  18261. message about each such type of problem, no matter how many times the

  18262. problem occurs; or you can ask GDB to print more messages, to see how

  18263. many times the problems occur, with the 'set complaints' command (*note

  18264. Optional Warnings and Messages: Messages/Warnings.).

  18265. 

  18266.    The messages currently printed, and their meanings, include:

  18267. 

  18268. 'inner block not inside outer block in SYMBOL'

  18269. 

  18270.      The symbol information shows where symbol scopes begin and end

  18271.      (such as at the start of a function or a block of statements).

  18272.      This error indicates that an inner scope block is not fully

  18273.      contained in its outer scope blocks.

  18274. 

  18275.      GDB circumvents the problem by treating the inner block as if it

  18276.      had the same scope as the outer block.  In the error message,

  18277.      SYMBOL may be shown as "'(don't know)'" if the outer block is not a

  18278.      function.

  18279. 

  18280. 'block at ADDRESS out of order'

  18281. 

  18282.      The symbol information for symbol scope blocks should occur in

  18283.      order of increasing addresses.  This error indicates that it does

  18284.      not do so.

  18285. 

  18286.      GDB does not circumvent this problem, and has trouble locating

  18287.      symbols in the source file whose symbols it is reading.  (You can

  18288.      often determine what source file is affected by specifying 'set

  18289.      verbose on'.  *Note Optional Warnings and Messages:

  18290.      Messages/Warnings.)

  18291. 

  18292. 'bad block start address patched'

  18293. 

  18294.      The symbol information for a symbol scope block has a start address

  18295.      smaller than the address of the preceding source line.  This is

  18296.      known to occur in the SunOS 4.1.1 (and earlier) C compiler.

  18297. 

  18298.      GDB circumvents the problem by treating the symbol scope block as

  18299.      starting on the previous source line.

  18300. 

  18301. 'bad string table offset in symbol N'

  18302. 

  18303.      Symbol number N contains a pointer into the string table which is

  18304.      larger than the size of the string table.

  18305. 

  18306.      GDB circumvents the problem by considering the symbol to have the

  18307.      name 'foo', which may cause other problems if many symbols end up

  18308.      with this name.

  18309. 

  18310. 'unknown symbol type 0xNN'

  18311. 

  18312.      The symbol information contains new data types that GDB does not

  18313.      yet know how to read.  '0xNN' is the symbol type of the

  18314.      uncomprehended information, in hexadecimal.

  18315. 

  18316.      GDB circumvents the error by ignoring this symbol information.

  18317.      This usually allows you to debug your program, though certain

  18318.      symbols are not accessible.  If you encounter such a problem and

  18319.      feel like debugging it, you can debug 'gdb' with itself, breakpoint

  18320.      on 'complain', then go up to the function 'read_dbx_symtab' and

  18321.      examine '*bufp' to see the symbol.

  18322. 

  18323. 'stub type has NULL name'

  18324. 

  18325.      GDB could not find the full definition for a struct or class.

  18326. 

  18327. 'const/volatile indicator missing (ok if using g++ v1.x), got...'

  18328.      The symbol information for a C++ member function is missing some

  18329.      information that recent versions of the compiler should have output

  18330.      for it.

  18331. 

  18332. 'info mismatch between compiler and debugger'

  18333. 

  18334.      GDB could not parse a type specification output by the compiler.

  18335. 

  18336. 

  18337. File: gdb.info,  Node: Data Files,  Prev: Symbol Errors,  Up: GDB Files

  18338. 

  18339. 18.7 GDB Data Files

  18340. ===================

  18341. 

  18342. GDB will sometimes read an auxiliary data file.  These files are kept in

  18343. a directory known as the "data directory".

  18344. 

  18345.    You can set the data directory's name, and view the name GDB is

  18346. currently using.

  18347. 

  18348. 'set data-directory DIRECTORY'

  18349.      Set the directory which GDB searches for auxiliary data files to

  18350.      DIRECTORY.

  18351. 

  18352. 'show data-directory'

  18353.      Show the directory GDB searches for auxiliary data files.

  18354. 

  18355.    You can set the default data directory by using the configure-time

  18356. '--with-gdb-datadir' option.  If the data directory is inside GDB's

  18357. configured binary prefix (set with '--prefix' or '--exec-prefix'), then

  18358. the default data directory will be updated automatically if the

  18359. installed GDB is moved to a new location.

  18360. 

  18361.    The data directory may also be specified with the '--data-directory'

  18362. command line option.  *Note Mode Options::.

  18363. 

  18364. 

  18365. File: gdb.info,  Node: Targets,  Next: Remote Debugging,  Prev: GDB Files,  Up: Top

  18366. 

  18367. 19 Specifying a Debugging Target

  18368. ********************************

  18369. 

  18370. A "target" is the execution environment occupied by your program.

  18371. 

  18372.    Often, GDB runs in the same host environment as your program; in that

  18373. case, the debugging target is specified as a side effect when you use

  18374. the 'file' or 'core' commands.  When you need more flexibility--for

  18375. example, running GDB on a physically separate host, or controlling a

  18376. standalone system over a serial port or a realtime system over a TCP/IP

  18377. connection--you can use the 'target' command to specify one of the

  18378. target types configured for GDB (*note Commands for Managing Targets:

  18379. Target Commands.).

  18380. 

  18381.    It is possible to build GDB for several different "target

  18382. architectures".  When GDB is built like that, you can choose one of the

  18383. available architectures with the 'set architecture' command.

  18384. 

  18385. 'set architecture ARCH'

  18386.      This command sets the current target architecture to ARCH.  The

  18387.      value of ARCH can be '"auto"', in addition to one of the supported

  18388.      architectures.

  18389. 

  18390. 'show architecture'

  18391.      Show the current target architecture.

  18392. 

  18393. 'set processor'

  18394. 'processor'

  18395.      These are alias commands for, respectively, 'set architecture' and

  18396.      'show architecture'.

  18397. 

  18398. * Menu:

  18399. 

  18400. * Active Targets::              Active targets

  18401. * Target Commands::             Commands for managing targets

  18402. * Byte Order::                  Choosing target byte order

  18403. 

  18404. 

  18405. File: gdb.info,  Node: Active Targets,  Next: Target Commands,  Up: Targets

  18406. 

  18407. 19.1 Active Targets

  18408. ===================

  18409. 

  18410. There are multiple classes of targets such as: processes, executable

  18411. files or recording sessions.  Core files belong to the process class,

  18412. making core file and process mutually exclusive.  Otherwise, GDB can

  18413. work concurrently on multiple active targets, one in each class.  This

  18414. allows you to (for example) start a process and inspect its activity,

  18415. while still having access to the executable file after the process

  18416. finishes.  Or if you start process recording (*note Reverse Execution::)

  18417. and 'reverse-step' there, you are presented a virtual layer of the

  18418. recording target, while the process target remains stopped at the

  18419. chronologically last point of the process execution.

  18420. 

  18421.    Use the 'core-file' and 'exec-file' commands to select a new core

  18422. file or executable target (*note Commands to Specify Files: Files.).  To

  18423. specify as a target a process that is already running, use the 'attach'

  18424. command (*note Debugging an Already-running Process: Attach.).

  18425. 

  18426. 

  18427. File: gdb.info,  Node: Target Commands,  Next: Byte Order,  Prev: Active Targets,  Up: Targets

  18428. 

  18429. 19.2 Commands for Managing Targets

  18430. ==================================

  18431. 

  18432. 'target TYPE PARAMETERS'

  18433.      Connects the GDB host environment to a target machine or process.

  18434.      A target is typically a protocol for talking to debugging

  18435.      facilities.  You use the argument TYPE to specify the type or

  18436.      protocol of the target machine.

  18437. 

  18438.      Further PARAMETERS are interpreted by the target protocol, but

  18439.      typically include things like device names or host names to connect

  18440.      with, process numbers, and baud rates.

  18441. 

  18442.      The 'target' command does not repeat if you press <RET> again after

  18443.      executing the command.

  18444. 

  18445. 'help target'

  18446.      Displays the names of all targets available.  To display targets

  18447.      currently selected, use either 'info target' or 'info files' (*note

  18448.      Commands to Specify Files: Files.).

  18449. 

  18450. 'help target NAME'

  18451.      Describe a particular target, including any parameters necessary to

  18452.      select it.

  18453. 

  18454. 'set gnutarget ARGS'

  18455.      GDB uses its own library BFD to read your files.  GDB knows whether

  18456.      it is reading an "executable", a "core", or a ".o" file; however,

  18457.      you can specify the file format with the 'set gnutarget' command.

  18458.      Unlike most 'target' commands, with 'gnutarget' the 'target' refers

  18459.      to a program, not a machine.

  18460. 

  18461.           _Warning:_ To specify a file format with 'set gnutarget', you

  18462.           must know the actual BFD name.

  18463. 

  18464.      *Note Commands to Specify Files: Files.

  18465. 

  18466. 'show gnutarget'

  18467.      Use the 'show gnutarget' command to display what file format

  18468.      'gnutarget' is set to read.  If you have not set 'gnutarget', GDB

  18469.      will determine the file format for each file automatically, and

  18470.      'show gnutarget' displays 'The current BFD target is "auto"'.

  18471. 

  18472.    Here are some common targets (available, or not, depending on the GDB

  18473. configuration):

  18474. 

  18475. 'target exec PROGRAM'

  18476.      An executable file.  'target exec PROGRAM' is the same as

  18477.      'exec-file PROGRAM'.

  18478. 

  18479. 'target core FILENAME'

  18480.      A core dump file.  'target core FILENAME' is the same as 'core-file

  18481.      FILENAME'.

  18482. 

  18483. 'target remote MEDIUM'

  18484.      A remote system connected to GDB via a serial line or network

  18485.      connection.  This command tells GDB to use its own remote protocol

  18486.      over MEDIUM for debugging.  *Note Remote Debugging::.

  18487. 

  18488.      For example, if you have a board connected to '/dev/ttya' on the

  18489.      machine running GDB, you could say:

  18490. 

  18491.           target remote /dev/ttya

  18492. 

  18493.      'target remote' supports the 'load' command.  This is only useful

  18494.      if you have some other way of getting the stub to the target

  18495.      system, and you can put it somewhere in memory where it won't get

  18496.      clobbered by the download.

  18497. 

  18498. 'target sim [SIMARGS] ...'

  18499.      Builtin CPU simulator.  GDB includes simulators for most

  18500.      architectures.  In general,

  18501.                   target sim

  18502.                   load

  18503.                   run

  18504.      works; however, you cannot assume that a specific memory map,

  18505.      device drivers, or even basic I/O is available, although some

  18506.      simulators do provide these.  For info about any processor-specific

  18507.      simulator details, see the appropriate section in *note Embedded

  18508.      Processors: Embedded Processors.

  18509. 

  18510. 'target native'

  18511.      Setup for local/native process debugging.  Useful to make the 'run'

  18512.      command spawn native processes (likewise 'attach', etc.) even when

  18513.      'set auto-connect-native-target' is 'off' (*note set

  18514.      auto-connect-native-target::).

  18515. 

  18516.    Different targets are available on different configurations of GDB;

  18517. your configuration may have more or fewer targets.

  18518. 

  18519.    Many remote targets require you to download the executable's code

  18520. once you've successfully established a connection.  You may wish to

  18521. control various aspects of this process.

  18522. 

  18523. 'set hash'

  18524.      This command controls whether a hash mark '#' is displayed while

  18525.      downloading a file to the remote monitor.  If on, a hash mark is

  18526.      displayed after each S-record is successfully downloaded to the

  18527.      monitor.

  18528. 

  18529. 'show hash'

  18530.      Show the current status of displaying the hash mark.

  18531. 

  18532. 'set debug monitor'

  18533.      Enable or disable display of communications messages between GDB

  18534.      and the remote monitor.

  18535. 

  18536. 'show debug monitor'

  18537.      Show the current status of displaying communications between GDB

  18538.      and the remote monitor.

  18539. 

  18540. 'load FILENAME OFFSET'

  18541.      Depending on what remote debugging facilities are configured into

  18542.      GDB, the 'load' command may be available.  Where it exists, it is

  18543.      meant to make FILENAME (an executable) available for debugging on

  18544.      the remote system--by downloading, or dynamic linking, for example.

  18545.      'load' also records the FILENAME symbol table in GDB, like the

  18546.      'add-symbol-file' command.

  18547. 

  18548.      If your GDB does not have a 'load' command, attempting to execute

  18549.      it gets the error message "'You can't do that when your target is

  18550.      ...'"

  18551. 

  18552.      The file is loaded at whatever address is specified in the

  18553.      executable.  For some object file formats, you can specify the load

  18554.      address when you link the program; for other formats, like a.out,

  18555.      the object file format specifies a fixed address.

  18556. 

  18557.      It is also possible to tell GDB to load the executable file at a

  18558.      specific offset described by the optional argument OFFSET.  When

  18559.      OFFSET is provided, FILENAME must also be provided.

  18560. 

  18561.      Depending on the remote side capabilities, GDB may be able to load

  18562.      programs into flash memory.

  18563. 

  18564.      'load' does not repeat if you press <RET> again after using it.

  18565. 

  18566. 'flash-erase'

  18567. 

  18568.      Erases all known flash memory regions on the target.

  18569. 

  18570. 

  18571. File: gdb.info,  Node: Byte Order,  Prev: Target Commands,  Up: Targets

  18572. 

  18573. 19.3 Choosing Target Byte Order

  18574. ===============================

  18575. 

  18576. Some types of processors, such as the MIPS, PowerPC, and Renesas SH,

  18577. offer the ability to run either big-endian or little-endian byte orders.

  18578. Usually the executable or symbol will include a bit to designate the

  18579. endian-ness, and you will not need to worry about which to use.

  18580. However, you may still find it useful to adjust GDB's idea of processor

  18581. endian-ness manually.

  18582. 

  18583. 'set endian big'

  18584.      Instruct GDB to assume the target is big-endian.

  18585. 

  18586. 'set endian little'

  18587.      Instruct GDB to assume the target is little-endian.

  18588. 

  18589. 'set endian auto'

  18590.      Instruct GDB to use the byte order associated with the executable.

  18591. 

  18592. 'show endian'

  18593.      Display GDB's current idea of the target byte order.

  18594. 

  18595.    If the 'set endian auto' mode is in effect and no executable has been

  18596. selected, then the endianness used is the last one chosen either by one

  18597. of the 'set endian big' and 'set endian little' commands or by inferring

  18598. from the last executable used.  If no endianness has been previously

  18599. chosen, then the default for this mode is inferred from the target GDB

  18600. has been built for, and is 'little' if the name of the target CPU has an

  18601. 'el' suffix and 'big' otherwise.

  18602. 

  18603.    Note that these commands merely adjust interpretation of symbolic

  18604. data on the host, and that they have absolutely no effect on the target

  18605. system.

  18606. 

  18607. 

  18608. File: gdb.info,  Node: Remote Debugging,  Next: Configurations,  Prev: Targets,  Up: Top

  18609. 

  18610. 20 Debugging Remote Programs

  18611. ****************************

  18612. 

  18613. If you are trying to debug a program running on a machine that cannot

  18614. run GDB in the usual way, it is often useful to use remote debugging.

  18615. For example, you might use remote debugging on an operating system

  18616. kernel, or on a small system which does not have a general purpose

  18617. operating system powerful enough to run a full-featured debugger.

  18618. 

  18619.    Some configurations of GDB have special serial or TCP/IP interfaces

  18620. to make this work with particular debugging targets.  In addition, GDB

  18621. comes with a generic serial protocol (specific to GDB, but not specific

  18622. to any particular target system) which you can use if you write the

  18623. remote stubs--the code that runs on the remote system to communicate

  18624. with GDB.

  18625. 

  18626.    Other remote targets may be available in your configuration of GDB;

  18627. use 'help target' to list them.

  18628. 

  18629. * Menu:

  18630. 

  18631. * Connecting::                  Connecting to a remote target

  18632. * File Transfer::               Sending files to a remote system

  18633. * Server::	                Using the gdbserver program

  18634. * Remote Configuration::        Remote configuration

  18635. * Remote Stub::                 Implementing a remote stub

  18636. 

  18637. 

  18638. File: gdb.info,  Node: Connecting,  Next: File Transfer,  Up: Remote Debugging

  18639. 

  18640. 20.1 Connecting to a Remote Target

  18641. ==================================

  18642. 

  18643. This section describes how to connect to a remote target, including the

  18644. types of connections and their differences, how to set up executable and

  18645. symbol files on the host and target, and the commands used for

  18646. connecting to and disconnecting from the remote target.

  18647. 

  18648. 20.1.1 Types of Remote Connections

  18649. ----------------------------------

  18650. 

  18651. GDB supports two types of remote connections, 'target remote' mode and

  18652. 'target extended-remote' mode.  Note that many remote targets support

  18653. only 'target remote' mode.  There are several major differences between

  18654. the two types of connections, enumerated here:

  18655. 

  18656. Result of detach or program exit

  18657.      *With target remote mode:* When the debugged program exits or you

  18658.      detach from it, GDB disconnects from the target.  When using

  18659.      'gdbserver', 'gdbserver' will exit.

  18660. 

  18661.      *With target extended-remote mode:* When the debugged program exits

  18662.      or you detach from it, GDB remains connected to the target, even

  18663.      though no program is running.  You can rerun the program, attach to

  18664.      a running program, or use 'monitor' commands specific to the

  18665.      target.

  18666. 

  18667.      When using 'gdbserver' in this case, it does not exit unless it was

  18668.      invoked using the '--once' option.  If the '--once' option was not

  18669.      used, you can ask 'gdbserver' to exit using the 'monitor exit'

  18670.      command (*note Monitor Commands for gdbserver::).

  18671. 

  18672. Specifying the program to debug

  18673.      For both connection types you use the 'file' command to specify the

  18674.      program on the host system.  If you are using 'gdbserver' there are

  18675.      some differences in how to specify the location of the program on

  18676.      the target.

  18677. 

  18678.      *With target remote mode:* You must either specify the program to

  18679.      debug on the 'gdbserver' command line or use the '--attach' option

  18680.      (*note Attaching to a Running Program: Attaching to a program.).

  18681. 

  18682.      *With target extended-remote mode:* You may specify the program to

  18683.      debug on the 'gdbserver' command line, or you can load the program

  18684.      or attach to it using GDB commands after connecting to 'gdbserver'.

  18685. 

  18686.      You can start 'gdbserver' without supplying an initial command to

  18687.      run or process ID to attach.  To do this, use the '--multi' command

  18688.      line option.  Then you can connect using 'target extended-remote'

  18689.      and start the program you want to debug (see below for details on

  18690.      using the 'run' command in this scenario).  Note that the

  18691.      conditions under which 'gdbserver' terminates depend on how GDB

  18692.      connects to it ('target remote' or 'target extended-remote').  The

  18693.      '--multi' option to 'gdbserver' has no influence on that.

  18694. 

  18695. The 'run' command

  18696.      *With target remote mode:* The 'run' command is not supported.

  18697.      Once a connection has been established, you can use all the usual

  18698.      GDB commands to examine and change data.  The remote program is

  18699.      already running, so you can use commands like 'step' and

  18700.      'continue'.

  18701. 

  18702.      *With target extended-remote mode:* The 'run' command is supported.

  18703.      The 'run' command uses the value set by 'set remote exec-file'

  18704.      (*note set remote exec-file::) to select the program to run.

  18705.      Command line arguments are supported, except for wildcard expansion

  18706.      and I/O redirection (*note Arguments::).

  18707. 

  18708.      If you specify the program to debug on the command line, then the

  18709.      'run' command is not required to start execution, and you can

  18710.      resume using commands like 'step' and 'continue' as with 'target

  18711.      remote' mode.

  18712. 

  18713. Attaching

  18714.      *With target remote mode:* The GDB command 'attach' is not

  18715.      supported.  To attach to a running program using 'gdbserver', you

  18716.      must use the '--attach' option (*note Running gdbserver::).

  18717. 

  18718.      *With target extended-remote mode:* To attach to a running program,

  18719.      you may use the 'attach' command after the connection has been

  18720.      established.  If you are using 'gdbserver', you may also invoke

  18721.      'gdbserver' using the '--attach' option (*note Running

  18722.      gdbserver::).

  18723. 

  18724.      Some remote targets allow GDB to determine the executable file

  18725.      running in the process the debugger is attaching to.  In such a

  18726.      case, GDB uses the value of 'exec-file-mismatch' to handle a

  18727.      possible mismatch between the executable file name running in the

  18728.      process and the name of the current exec-file loaded by GDB (*note

  18729.      set exec-file-mismatch::).

  18730. 

  18731. 20.1.2 Host and Target Files

  18732. ----------------------------

  18733. 

  18734. GDB, running on the host, needs access to symbol and debugging

  18735. information for your program running on the target.  This requires

  18736. access to an unstripped copy of your program, and possibly any

  18737. associated symbol files.  Note that this section applies equally to both

  18738. 'target remote' mode and 'target extended-remote' mode.

  18739. 

  18740.    Some remote targets (*note qXfer executable filename read::, and

  18741. *note Host I/O Packets::) allow GDB to access program files over the

  18742. same connection used to communicate with GDB.  With such a target, if

  18743. the remote program is unstripped, the only command you need is 'target

  18744. remote' (or 'target extended-remote').

  18745. 

  18746.    If the remote program is stripped, or the target does not support

  18747. remote program file access, start up GDB using the name of the local

  18748. unstripped copy of your program as the first argument, or use the 'file'

  18749. command.  Use 'set sysroot' to specify the location (on the host) of

  18750. target libraries (unless your GDB was compiled with the correct sysroot

  18751. using '--with-sysroot').  Alternatively, you may use 'set

  18752. solib-search-path' to specify how GDB locates target libraries.

  18753. 

  18754.    The symbol file and target libraries must exactly match the

  18755. executable and libraries on the target, with one exception: the files on

  18756. the host system should not be stripped, even if the files on the target

  18757. system are.  Mismatched or missing files will lead to confusing results

  18758. during debugging.  On GNU/Linux targets, mismatched or missing files may

  18759. also prevent 'gdbserver' from debugging multi-threaded programs.

  18760. 

  18761. 20.1.3 Remote Connection Commands

  18762. ---------------------------------

  18763. 

  18764. GDB can communicate with the target over a serial line, a local Unix

  18765. domain socket, or over an IP network using TCP or UDP.  In each case,

  18766. GDB uses the same protocol for debugging your program; only the medium

  18767. carrying the debugging packets varies.  The 'target remote' and 'target

  18768. extended-remote' commands establish a connection to the target.  Both

  18769. commands accept the same arguments, which indicate the medium to use:

  18770. 

  18771. 'target remote SERIAL-DEVICE'

  18772. 'target extended-remote SERIAL-DEVICE'

  18773.      Use SERIAL-DEVICE to communicate with the target.  For example, to

  18774.      use a serial line connected to the device named '/dev/ttyb':

  18775. 

  18776.           target remote /dev/ttyb

  18777. 

  18778.      If you're using a serial line, you may want to give GDB the

  18779.      '--baud' option, or use the 'set serial baud' command (*note set

  18780.      serial baud: Remote Configuration.) before the 'target' command.

  18781. 

  18782. 'target remote LOCAL-SOCKET'

  18783. 'target extended-remote LOCAL-SOCKET'

  18784.      Use LOCAL-SOCKET to communicate with the target.  For example, to

  18785.      use a local Unix domain socket bound to the file system entry

  18786.      '/tmp/gdb-socket0':

  18787. 

  18788.           target remote /tmp/gdb-socket0

  18789. 

  18790.      Note that this command has the same form as the command to connect

  18791.      to a serial line.  GDB will automatically determine which kind of

  18792.      file you have specified and will make the appropriate kind of

  18793.      connection.  This feature is not available if the host system does

  18794.      not support Unix domain sockets.

  18795. 

  18796. 'target remote HOST:PORT'

  18797. 'target remote [HOST]:PORT'

  18798. 'target remote tcp:HOST:PORT'

  18799. 'target remote tcp:[HOST]:PORT'

  18800. 'target remote tcp4:HOST:PORT'

  18801. 'target remote tcp6:HOST:PORT'

  18802. 'target remote tcp6:[HOST]:PORT'

  18803. 'target extended-remote HOST:PORT'

  18804. 'target extended-remote [HOST]:PORT'

  18805. 'target extended-remote tcp:HOST:PORT'

  18806. 'target extended-remote tcp:[HOST]:PORT'

  18807. 'target extended-remote tcp4:HOST:PORT'

  18808. 'target extended-remote tcp6:HOST:PORT'

  18809. 'target extended-remote tcp6:[HOST]:PORT'

  18810.      Debug using a TCP connection to PORT on HOST.  The HOST may be

  18811.      either a host name, a numeric IPv4 address, or a numeric IPv6

  18812.      address (with or without the square brackets to separate the

  18813.      address from the port); PORT must be a decimal number.  The HOST

  18814.      could be the target machine itself, if it is directly connected to

  18815.      the net, or it might be a terminal server which in turn has a

  18816.      serial line to the target.

  18817. 

  18818.      For example, to connect to port 2828 on a terminal server named

  18819.      'manyfarms':

  18820. 

  18821.           target remote manyfarms:2828

  18822. 

  18823.      To connect to port 2828 on a terminal server whose address is

  18824.      '2001:0db8:85a3:0000:0000:8a2e:0370:7334', you can either use the

  18825.      square bracket syntax:

  18826. 

  18827.           target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828

  18828. 

  18829.      or explicitly specify the IPv6 protocol:

  18830. 

  18831.           target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828

  18832. 

  18833.      This last example may be confusing to the reader, because there is

  18834.      no visible separation between the hostname and the port number.

  18835.      Therefore, we recommend the user to provide IPv6 addresses using

  18836.      square brackets for clarity.  However, it is important to mention

  18837.      that for GDB there is no ambiguity: the number after the last colon

  18838.      is considered to be the port number.

  18839. 

  18840.      If your remote target is actually running on the same machine as

  18841.      your debugger session (e.g. a simulator for your target running on

  18842.      the same host), you can omit the hostname.  For example, to connect

  18843.      to port 1234 on your local machine:

  18844. 

  18845.           target remote :1234

  18846. 

  18847.      Note that the colon is still required here.

  18848. 

  18849. 'target remote udp:HOST:PORT'

  18850. 'target remote udp:[HOST]:PORT'

  18851. 'target remote udp4:HOST:PORT'

  18852. 'target remote udp6:[HOST]:PORT'

  18853. 'target extended-remote udp:HOST:PORT'

  18854. 'target extended-remote udp:HOST:PORT'

  18855. 'target extended-remote udp:[HOST]:PORT'

  18856. 'target extended-remote udp4:HOST:PORT'

  18857. 'target extended-remote udp6:HOST:PORT'

  18858. 'target extended-remote udp6:[HOST]:PORT'

  18859.      Debug using UDP packets to PORT on HOST.  For example, to connect

  18860.      to UDP port 2828 on a terminal server named 'manyfarms':

  18861. 

  18862.           target remote udp:manyfarms:2828

  18863. 

  18864.      When using a UDP connection for remote debugging, you should keep

  18865.      in mind that the 'U' stands for "Unreliable".  UDP can silently

  18866.      drop packets on busy or unreliable networks, which will cause havoc

  18867.      with your debugging session.

  18868. 

  18869. 'target remote | COMMAND'

  18870. 'target extended-remote | COMMAND'

  18871.      Run COMMAND in the background and communicate with it using a pipe.

  18872.      The COMMAND is a shell command, to be parsed and expanded by the

  18873.      system's command shell, '/bin/sh'; it should expect remote protocol

  18874.      packets on its standard input, and send replies on its standard

  18875.      output.  You could use this to run a stand-alone simulator that

  18876.      speaks the remote debugging protocol, to make net connections using

  18877.      programs like 'ssh', or for other similar tricks.

  18878. 

  18879.      If COMMAND closes its standard output (perhaps by exiting), GDB

  18880.      will try to send it a 'SIGTERM' signal.  (If the program has

  18881.      already exited, this will have no effect.)

  18882. 

  18883.    Whenever GDB is waiting for the remote program, if you type the

  18884. interrupt character (often 'Ctrl-c'), GDB attempts to stop the program.

  18885. This may or may not succeed, depending in part on the hardware and the

  18886. serial drivers the remote system uses.  If you type the interrupt

  18887. character once again, GDB displays this prompt:

  18888. 

  18889.      Interrupted while waiting for the program.

  18890.      Give up (and stop debugging it)?  (y or n)

  18891. 

  18892.    In 'target remote' mode, if you type 'y', GDB abandons the remote

  18893. debugging session.  (If you decide you want to try again later, you can

  18894. use 'target remote' again to connect once more.)  If you type 'n', GDB

  18895. goes back to waiting.

  18896. 

  18897.    In 'target extended-remote' mode, typing 'n' will leave GDB connected

  18898. to the target.

  18899. 

  18900. 'detach'

  18901.      When you have finished debugging the remote program, you can use

  18902.      the 'detach' command to release it from GDB control.  Detaching

  18903.      from the target normally resumes its execution, but the results

  18904.      will depend on your particular remote stub.  After the 'detach'

  18905.      command in 'target remote' mode, GDB is free to connect to another

  18906.      target.  In 'target extended-remote' mode, GDB is still connected

  18907.      to the target.

  18908. 

  18909. 'disconnect'

  18910.      The 'disconnect' command closes the connection to the target, and

  18911.      the target is generally not resumed.  It will wait for GDB (this

  18912.      instance or another one) to connect and continue debugging.  After

  18913.      the 'disconnect' command, GDB is again free to connect to another

  18914.      target.

  18915. 

  18916. 'monitor CMD'

  18917.      This command allows you to send arbitrary commands directly to the

  18918.      remote monitor.  Since GDB doesn't care about the commands it sends

  18919.      like this, this command is the way to extend GDB--you can add new

  18920.      commands that only the external monitor will understand and

  18921.      implement.

  18922. 

  18923. 

  18924. File: gdb.info,  Node: File Transfer,  Next: Server,  Prev: Connecting,  Up: Remote Debugging

  18925. 

  18926. 20.2 Sending files to a remote system

  18927. =====================================

  18928. 

  18929. Some remote targets offer the ability to transfer files over the same

  18930. connection used to communicate with GDB.  This is convenient for targets

  18931. accessible through other means, e.g. GNU/Linux systems running

  18932. 'gdbserver' over a network interface.  For other targets, e.g. embedded

  18933. devices with only a single serial port, this may be the only way to

  18934. upload or download files.

  18935. 

  18936.    Not all remote targets support these commands.

  18937. 

  18938. 'remote put HOSTFILE TARGETFILE'

  18939.      Copy file HOSTFILE from the host system (the machine running GDB)

  18940.      to TARGETFILE on the target system.

  18941. 

  18942. 'remote get TARGETFILE HOSTFILE'

  18943.      Copy file TARGETFILE from the target system to HOSTFILE on the host

  18944.      system.

  18945. 

  18946. 'remote delete TARGETFILE'

  18947.      Delete TARGETFILE from the target system.

  18948. 

  18949. 

  18950. File: gdb.info,  Node: Server,  Next: Remote Configuration,  Prev: File Transfer,  Up: Remote Debugging

  18951. 

  18952. 20.3 Using the 'gdbserver' Program

  18953. ==================================

  18954. 

  18955. 'gdbserver' is a control program for Unix-like systems, which allows you

  18956. to connect your program with a remote GDB via 'target remote' or 'target

  18957. extended-remote'--but without linking in the usual debugging stub.

  18958. 

  18959.    'gdbserver' is not a complete replacement for the debugging stubs,

  18960. because it requires essentially the same operating-system facilities

  18961. that GDB itself does.  In fact, a system that can run 'gdbserver' to

  18962. connect to a remote GDB could also run GDB locally!  'gdbserver' is

  18963. sometimes useful nevertheless, because it is a much smaller program than

  18964. GDB itself.  It is also easier to port than all of GDB, so you may be

  18965. able to get started more quickly on a new system by using 'gdbserver'.

  18966. Finally, if you develop code for real-time systems, you may find that

  18967. the tradeoffs involved in real-time operation make it more convenient to

  18968. do as much development work as possible on another system, for example

  18969. by cross-compiling.  You can use 'gdbserver' to make a similar choice

  18970. for debugging.

  18971. 

  18972.    GDB and 'gdbserver' communicate via either a serial line or a TCP

  18973. connection, using the standard GDB remote serial protocol.

  18974. 

  18975.      _Warning:_ 'gdbserver' does not have any built-in security.  Do not

  18976.      run 'gdbserver' connected to any public network; a GDB connection

  18977.      to 'gdbserver' provides access to the target system with the same

  18978.      privileges as the user running 'gdbserver'.

  18979. 

  18980. 20.3.1 Running 'gdbserver'

  18981. --------------------------

  18982. 

  18983. Run 'gdbserver' on the target system.  You need a copy of the program

  18984. you want to debug, including any libraries it requires.  'gdbserver'

  18985. does not need your program's symbol table, so you can strip the program

  18986. if necessary to save space.  GDB on the host system does all the symbol

  18987. handling.

  18988. 

  18989.    To use the server, you must tell it how to communicate with GDB; the

  18990. name of your program; and the arguments for your program.  The usual

  18991. syntax is:

  18992. 

  18993.      target> gdbserver COMM PROGRAM [ ARGS ... ]

  18994. 

  18995.    COMM is either a device name (to use a serial line), or a TCP

  18996. hostname and portnumber, or '-' or 'stdio' to use stdin/stdout of

  18997. 'gdbserver'.  For example, to debug Emacs with the argument 'foo.txt'

  18998. and communicate with GDB over the serial port '/dev/com1':

  18999. 

  19000.      target> gdbserver /dev/com1 emacs foo.txt

  19001. 

  19002.    'gdbserver' waits passively for the host GDB to communicate with it.

  19003. 

  19004.    To use a TCP connection instead of a serial line:

  19005. 

  19006.      target> gdbserver host:2345 emacs foo.txt

  19007. 

  19008.    The only difference from the previous example is the first argument,

  19009. specifying that you are communicating with the host GDB via TCP. The

  19010. 'host:2345' argument means that 'gdbserver' is to expect a TCP

  19011. connection from machine 'host' to local TCP port 2345.  (Currently, the

  19012. 'host' part is ignored.)  You can choose any number you want for the

  19013. port number as long as it does not conflict with any TCP ports already

  19014. in use on the target system (for example, '23' is reserved for

  19015. 'telnet').(1)  You must use the same port number with the host GDB

  19016. 'target remote' command.

  19017. 

  19018.    The 'stdio' connection is useful when starting 'gdbserver' with ssh:

  19019. 

  19020.      (gdb) target remote | ssh -T hostname gdbserver - hello

  19021. 

  19022.    The '-T' option to ssh is provided because we don't need a remote

  19023. pty, and we don't want escape-character handling.  Ssh does this by

  19024. default when a command is provided, the flag is provided to make it

  19025. explicit.  You could elide it if you want to.

  19026. 

  19027.    Programs started with stdio-connected gdbserver have '/dev/null' for

  19028. 'stdin', and 'stdout','stderr' are sent back to gdb for display through

  19029. a pipe connected to gdbserver.  Both 'stdout' and 'stderr' use the same

  19030. pipe.

  19031. 

  19032. 20.3.1.1 Attaching to a Running Program

  19033. .......................................

  19034. 

  19035. On some targets, 'gdbserver' can also attach to running programs.  This

  19036. is accomplished via the '--attach' argument.  The syntax is:

  19037. 

  19038.      target> gdbserver --attach COMM PID

  19039. 

  19040.    PID is the process ID of a currently running process.  It isn't

  19041. necessary to point 'gdbserver' at a binary for the running process.

  19042. 

  19043.    In 'target extended-remote' mode, you can also attach using the GDB

  19044. attach command (*note Attaching in Types of Remote Connections::).

  19045. 

  19046.    You can debug processes by name instead of process ID if your target

  19047. has the 'pidof' utility:

  19048. 

  19049.      target> gdbserver --attach COMM `pidof PROGRAM`

  19050. 

  19051.    In case more than one copy of PROGRAM is running, or PROGRAM has

  19052. multiple threads, most versions of 'pidof' support the '-s' option to

  19053. only return the first process ID.

  19054. 

  19055. 20.3.1.2 TCP port allocation lifecycle of 'gdbserver'

  19056. .....................................................

  19057. 

  19058. This section applies only when 'gdbserver' is run to listen on a TCP

  19059. port.

  19060. 

  19061.    'gdbserver' normally terminates after all of its debugged processes

  19062. have terminated in 'target remote' mode.  On the other hand, for 'target

  19063. extended-remote', 'gdbserver' stays running even with no processes left.

  19064. GDB normally terminates the spawned debugged process on its exit, which

  19065. normally also terminates 'gdbserver' in the 'target remote' mode.

  19066. Therefore, when the connection drops unexpectedly, and GDB cannot ask

  19067. 'gdbserver' to kill its debugged processes, 'gdbserver' stays running

  19068. even in the 'target remote' mode.

  19069. 

  19070.    When 'gdbserver' stays running, GDB can connect to it again later.

  19071. Such reconnecting is useful for features like *note disconnected

  19072. tracing::.  For completeness, at most one GDB can be connected at a

  19073. time.

  19074. 

  19075.    By default, 'gdbserver' keeps the listening TCP port open, so that

  19076. subsequent connections are possible.  However, if you start 'gdbserver'

  19077. with the '--once' option, it will stop listening for any further

  19078. connection attempts after connecting to the first GDB session.  This

  19079. means no further connections to 'gdbserver' will be possible after the

  19080. first one.  It also means 'gdbserver' will terminate after the first

  19081. connection with remote GDB has closed, even for unexpectedly closed

  19082. connections and even in the 'target extended-remote' mode.  The '--once'

  19083. option allows reusing the same port number for connecting to multiple

  19084. instances of 'gdbserver' running on the same host, since each instance

  19085. closes its port after the first connection.

  19086. 

  19087. 20.3.1.3 Other Command-Line Arguments for 'gdbserver'

  19088. .....................................................

  19089. 

  19090. You can use the '--multi' option to start 'gdbserver' without specifying

  19091. a program to debug or a process to attach to.  Then you can attach in

  19092. 'target extended-remote' mode and run or attach to a program.  For more

  19093. information, *note --multi Option in Types of Remote Connnections::.

  19094. 

  19095.    The '--debug' option tells 'gdbserver' to display extra status

  19096. information about the debugging process.  The '--remote-debug' option

  19097. tells 'gdbserver' to display remote protocol debug output.  The

  19098. '--debug-file=FILENAME' option tells 'gdbserver' to write any debug

  19099. output to the given FILENAME.  These options are intended for

  19100. 'gdbserver' development and for bug reports to the developers.

  19101. 

  19102.    The '--debug-format=option1[,option2,...]' option tells 'gdbserver'

  19103. to include additional information in each output.  Possible options are:

  19104. 

  19105. 'none'

  19106.      Turn off all extra information in debugging output.

  19107. 'all'

  19108.      Turn on all extra information in debugging output.

  19109. 'timestamps'

  19110.      Include a timestamp in each line of debugging output.

  19111. 

  19112.    Options are processed in order.  Thus, for example, if 'none' appears

  19113. last then no additional information is added to debugging output.

  19114. 

  19115.    The '--wrapper' option specifies a wrapper to launch programs for

  19116. debugging.  The option should be followed by the name of the wrapper,

  19117. then any command-line arguments to pass to the wrapper, then '--'

  19118. indicating the end of the wrapper arguments.

  19119. 

  19120.    'gdbserver' runs the specified wrapper program with a combined

  19121. command line including the wrapper arguments, then the name of the

  19122. program to debug, then any arguments to the program.  The wrapper runs

  19123. until it executes your program, and then GDB gains control.

  19124. 

  19125.    You can use any program that eventually calls 'execve' with its

  19126. arguments as a wrapper.  Several standard Unix utilities do this, e.g.

  19127. 'env' and 'nohup'.  Any Unix shell script ending with 'exec "$@"' will

  19128. also work.

  19129. 

  19130.    For example, you can use 'env' to pass an environment variable to the

  19131. debugged program, without setting the variable in 'gdbserver''s

  19132. environment:

  19133. 

  19134.      $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog

  19135. 

  19136.    The '--selftest' option runs the self tests in 'gdbserver':

  19137. 

  19138.      $ gdbserver --selftest

  19139.      Ran 2 unit tests, 0 failed

  19140. 

  19141.    These tests are disabled in release.

  19142. 

  19143. 20.3.2 Connecting to 'gdbserver'

  19144. --------------------------------

  19145. 

  19146. The basic procedure for connecting to the remote target is:

  19147. 

  19148.    * Run GDB on the host system.

  19149. 

  19150.    * Make sure you have the necessary symbol files (*note Host and

  19151.      target files::).  Load symbols for your application using the

  19152.      'file' command before you connect.  Use 'set sysroot' to locate

  19153.      target libraries (unless your GDB was compiled with the correct

  19154.      sysroot using '--with-sysroot').

  19155. 

  19156.    * Connect to your target (*note Connecting to a Remote Target:

  19157.      Connecting.).  For TCP connections, you must start up 'gdbserver'

  19158.      prior to using the 'target' command.  Otherwise you may get an

  19159.      error whose text depends on the host system, but which usually

  19160.      looks something like 'Connection refused'.  Don't use the 'load'

  19161.      command in GDB when using 'target remote' mode, since the program

  19162.      is already on the target.

  19163. 

  19164. 20.3.3 Monitor Commands for 'gdbserver'

  19165. ---------------------------------------

  19166. 

  19167. During a GDB session using 'gdbserver', you can use the 'monitor'

  19168. command to send special requests to 'gdbserver'.  Here are the available

  19169. commands.

  19170. 

  19171. 'monitor help'

  19172.      List the available monitor commands.

  19173. 

  19174. 'monitor set debug 0'

  19175. 'monitor set debug 1'

  19176.      Disable or enable general debugging messages.

  19177. 

  19178. 'monitor set remote-debug 0'

  19179. 'monitor set remote-debug 1'

  19180.      Disable or enable specific debugging messages associated with the

  19181.      remote protocol (*note Remote Protocol::).

  19182. 

  19183. 'monitor set debug-file filename'

  19184. 'monitor set debug-file'

  19185.      Send any debug output to the given file, or to stderr.

  19186. 

  19187. 'monitor set debug-format option1[,option2,...]'

  19188.      Specify additional text to add to debugging messages.  Possible

  19189.      options are:

  19190. 

  19191.      'none'

  19192.           Turn off all extra information in debugging output.

  19193.      'all'

  19194.           Turn on all extra information in debugging output.

  19195.      'timestamps'

  19196.           Include a timestamp in each line of debugging output.

  19197. 

  19198.      Options are processed in order.  Thus, for example, if 'none'

  19199.      appears last then no additional information is added to debugging

  19200.      output.

  19201. 

  19202. 'monitor set libthread-db-search-path [PATH]'

  19203.      When this command is issued, PATH is a colon-separated list of

  19204.      directories to search for 'libthread_db' (*note set

  19205.      libthread-db-search-path: Threads.).  If you omit PATH,

  19206.      'libthread-db-search-path' will be reset to its default value.

  19207. 

  19208.      The special entry '$pdir' for 'libthread-db-search-path' is not

  19209.      supported in 'gdbserver'.

  19210. 

  19211. 'monitor exit'

  19212.      Tell gdbserver to exit immediately.  This command should be

  19213.      followed by 'disconnect' to close the debugging session.

  19214.      'gdbserver' will detach from any attached processes and kill any

  19215.      processes it created.  Use 'monitor exit' to terminate 'gdbserver'

  19216.      at the end of a multi-process mode debug session.

  19217. 

  19218. 20.3.4 Tracepoints support in 'gdbserver'

  19219. -----------------------------------------

  19220. 

  19221. On some targets, 'gdbserver' supports tracepoints, fast tracepoints and

  19222. static tracepoints.

  19223. 

  19224.    For fast or static tracepoints to work, a special library called the

  19225. "in-process agent" (IPA), must be loaded in the inferior process.  This

  19226. library is built and distributed as an integral part of 'gdbserver'.  In

  19227. addition, support for static tracepoints requires building the

  19228. in-process agent library with static tracepoints support.  At present,

  19229. the UST (LTTng Userspace Tracer, <http://lttng.org/ust>) tracing engine

  19230. is supported.  This support is automatically available if UST

  19231. development headers are found in the standard include path when

  19232. 'gdbserver' is built, or if 'gdbserver' was explicitly configured using

  19233. '--with-ust' to point at such headers.  You can explicitly disable the

  19234. support using '--with-ust=no'.

  19235. 

  19236.    There are several ways to load the in-process agent in your program:

  19237. 

  19238. 'Specifying it as dependency at link time'

  19239. 

  19240.      You can link your program dynamically with the in-process agent

  19241.      library.  On most systems, this is accomplished by adding

  19242.      '-linproctrace' to the link command.

  19243. 

  19244. 'Using the system's preloading mechanisms'

  19245. 

  19246.      You can force loading the in-process agent at startup time by using

  19247.      your system's support for preloading shared libraries.  Many Unixes

  19248.      support the concept of preloading user defined libraries.  In most

  19249.      cases, you do that by specifying 'LD_PRELOAD=libinproctrace.so' in

  19250.      the environment.  See also the description of 'gdbserver''s

  19251.      '--wrapper' command line option.

  19252. 

  19253. 'Using GDB to force loading the agent at run time'

  19254. 

  19255.      On some systems, you can force the inferior to load a shared

  19256.      library, by calling a dynamic loader function in the inferior that

  19257.      takes care of dynamically looking up and loading a shared library.

  19258.      On most Unix systems, the function is 'dlopen'.  You'll use the

  19259.      'call' command for that.  For example:

  19260. 

  19261.           (gdb) call dlopen ("libinproctrace.so", ...)

  19262. 

  19263.      Note that on most Unix systems, for the 'dlopen' function to be

  19264.      available, the program needs to be linked with '-ldl'.

  19265. 

  19266.    On systems that have a userspace dynamic loader, like most Unix

  19267. systems, when you connect to 'gdbserver' using 'target remote', you'll

  19268. find that the program is stopped at the dynamic loader's entry point,

  19269. and no shared library has been loaded in the program's address space

  19270. yet, including the in-process agent.  In that case, before being able to

  19271. use any of the fast or static tracepoints features, you need to let the

  19272. loader run and load the shared libraries.  The simplest way to do that

  19273. is to run the program to the main procedure.  E.g., if debugging a C or

  19274. C++ program, start 'gdbserver' like so:

  19275. 

  19276.      $ gdbserver :9999 myprogram

  19277. 

  19278.    Start GDB and connect to 'gdbserver' like so, and run to main:

  19279. 

  19280.      $ gdb myprogram

  19281.      (gdb) target remote myhost:9999

  19282.      0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2

  19283.      (gdb) b main

  19284.      (gdb) continue

  19285. 

  19286.    The in-process tracing agent library should now be loaded into the

  19287. process; you can confirm it with the 'info sharedlibrary' command, which

  19288. will list 'libinproctrace.so' as loaded in the process.  You are now

  19289. ready to install fast tracepoints, list static tracepoint markers, probe

  19290. static tracepoints markers, and start tracing.

  19291. 

  19292.    ---------- Footnotes ----------

  19293. 

  19294.    (1) If you choose a port number that conflicts with another service,

  19295. 'gdbserver' prints an error message and exits.

  19296. 

  19297. 

  19298. File: gdb.info,  Node: Remote Configuration,  Next: Remote Stub,  Prev: Server,  Up: Remote Debugging

  19299. 

  19300. 20.4 Remote Configuration

  19301. =========================

  19302. 

  19303. This section documents the configuration options available when

  19304. debugging remote programs.  For the options related to the File I/O

  19305. extensions of the remote protocol, see *note system-call-allowed:

  19306. system.

  19307. 

  19308. 'set remoteaddresssize BITS'

  19309.      Set the maximum size of address in a memory packet to the specified

  19310.      number of bits.  GDB will mask off the address bits above that

  19311.      number, when it passes addresses to the remote target.  The default

  19312.      value is the number of bits in the target's address.

  19313. 

  19314. 'show remoteaddresssize'

  19315.      Show the current value of remote address size in bits.

  19316. 

  19317. 'set serial baud N'

  19318.      Set the baud rate for the remote serial I/O to N baud.  The value

  19319.      is used to set the speed of the serial port used for debugging

  19320.      remote targets.

  19321. 

  19322. 'show serial baud'

  19323.      Show the current speed of the remote connection.

  19324. 

  19325. 'set serial parity PARITY'

  19326.      Set the parity for the remote serial I/O. Supported values of

  19327.      PARITY are: 'even', 'none', and 'odd'.  The default is 'none'.

  19328. 

  19329. 'show serial parity'

  19330.      Show the current parity of the serial port.

  19331. 

  19332. 'set remotebreak'

  19333.      If set to on, GDB sends a 'BREAK' signal to the remote when you

  19334.      type 'Ctrl-c' to interrupt the program running on the remote.  If

  19335.      set to off, GDB sends the 'Ctrl-C' character instead.  The default

  19336.      is off, since most remote systems expect to see 'Ctrl-C' as the

  19337.      interrupt signal.

  19338. 

  19339. 'show remotebreak'

  19340.      Show whether GDB sends 'BREAK' or 'Ctrl-C' to interrupt the remote

  19341.      program.

  19342. 

  19343. 'set remoteflow on'

  19344. 'set remoteflow off'

  19345.      Enable or disable hardware flow control ('RTS'/'CTS') on the serial

  19346.      port used to communicate to the remote target.

  19347. 

  19348. 'show remoteflow'

  19349.      Show the current setting of hardware flow control.

  19350. 

  19351. 'set remotelogbase BASE'

  19352.      Set the base (a.k.a. radix) of logging serial protocol

  19353.      communications to BASE.  Supported values of BASE are: 'ascii',

  19354.      'octal', and 'hex'.  The default is 'ascii'.

  19355. 

  19356. 'show remotelogbase'

  19357.      Show the current setting of the radix for logging remote serial

  19358.      protocol.

  19359. 

  19360. 'set remotelogfile FILE'

  19361.      Record remote serial communications on the named FILE.  The default

  19362.      is not to record at all.

  19363. 

  19364. 'show remotelogfile'

  19365.      Show the current setting of the file name on which to record the

  19366.      serial communications.

  19367. 

  19368. 'set remotetimeout NUM'

  19369.      Set the timeout limit to wait for the remote target to respond to

  19370.      NUM seconds.  The default is 2 seconds.

  19371. 

  19372. 'show remotetimeout'

  19373.      Show the current number of seconds to wait for the remote target

  19374.      responses.

  19375. 

  19376. 'set remote hardware-watchpoint-limit LIMIT'

  19377. 'set remote hardware-breakpoint-limit LIMIT'

  19378.      Restrict GDB to using LIMIT remote hardware watchpoints or

  19379.      breakpoints.  The LIMIT can be set to 0 to disable hardware

  19380.      watchpoints or breakpoints, and 'unlimited' for unlimited

  19381.      watchpoints or breakpoints.

  19382. 

  19383. 'show remote hardware-watchpoint-limit'

  19384. 'show remote hardware-breakpoint-limit'

  19385.      Show the current limit for the number of hardware watchpoints or

  19386.      breakpoints that GDB can use.

  19387. 

  19388. 'set remote hardware-watchpoint-length-limit LIMIT'

  19389.      Restrict GDB to using LIMIT bytes for the maximum length of a

  19390.      remote hardware watchpoint.  A LIMIT of 0 disables hardware

  19391.      watchpoints and 'unlimited' allows watchpoints of any length.

  19392. 

  19393. 'show remote hardware-watchpoint-length-limit'

  19394.      Show the current limit (in bytes) of the maximum length of a remote

  19395.      hardware watchpoint.

  19396. 

  19397. 'set remote exec-file FILENAME'

  19398. 'show remote exec-file'

  19399.      Select the file used for 'run' with 'target extended-remote'.  This

  19400.      should be set to a filename valid on the target system.  If it is

  19401.      not set, the target will use a default filename (e.g. the last

  19402.      program run).

  19403. 

  19404. 'set remote interrupt-sequence'

  19405.      Allow the user to select one of 'Ctrl-C', a 'BREAK' or 'BREAK-g' as

  19406.      the sequence to the remote target in order to interrupt the

  19407.      execution.  'Ctrl-C' is a default.  Some system prefers 'BREAK'

  19408.      which is high level of serial line for some certain time.  Linux

  19409.      kernel prefers 'BREAK-g', a.k.a Magic SysRq g.  It is 'BREAK'

  19410.      signal followed by character 'g'.

  19411. 

  19412. 'show interrupt-sequence'

  19413.      Show which of 'Ctrl-C', 'BREAK' or 'BREAK-g' is sent by GDB to

  19414.      interrupt the remote program.  'BREAK-g' is BREAK signal followed

  19415.      by 'g' and also known as Magic SysRq g.

  19416. 

  19417. 'set remote interrupt-on-connect'

  19418.      Specify whether interrupt-sequence is sent to remote target when

  19419.      GDB connects to it.  This is mostly needed when you debug Linux

  19420.      kernel.  Linux kernel expects 'BREAK' followed by 'g' which is

  19421.      known as Magic SysRq g in order to connect GDB.

  19422. 

  19423. 'show interrupt-on-connect'

  19424.      Show whether interrupt-sequence is sent to remote target when GDB

  19425.      connects to it.

  19426. 

  19427. 'set tcp auto-retry on'

  19428.      Enable auto-retry for remote TCP connections.  This is useful if

  19429.      the remote debugging agent is launched in parallel with GDB; there

  19430.      is a race condition because the agent may not become ready to

  19431.      accept the connection before GDB attempts to connect.  When

  19432.      auto-retry is enabled, if the initial attempt to connect fails, GDB

  19433.      reattempts to establish the connection using the timeout specified

  19434.      by 'set tcp connect-timeout'.

  19435. 

  19436. 'set tcp auto-retry off'

  19437.      Do not auto-retry failed TCP connections.

  19438. 

  19439. 'show tcp auto-retry'

  19440.      Show the current auto-retry setting.

  19441. 

  19442. 'set tcp connect-timeout SECONDS'

  19443. 'set tcp connect-timeout unlimited'

  19444.      Set the timeout for establishing a TCP connection to the remote

  19445.      target to SECONDS.  The timeout affects both polling to retry

  19446.      failed connections (enabled by 'set tcp auto-retry on') and waiting

  19447.      for connections that are merely slow to complete, and represents an

  19448.      approximate cumulative value.  If SECONDS is 'unlimited', there is

  19449.      no timeout and GDB will keep attempting to establish a connection

  19450.      forever, unless interrupted with 'Ctrl-c'.  The default is 15

  19451.      seconds.

  19452. 

  19453. 'show tcp connect-timeout'

  19454.      Show the current connection timeout setting.

  19455. 

  19456.    The GDB remote protocol autodetects the packets supported by your

  19457. debugging stub.  If you need to override the autodetection, you can use

  19458. these commands to enable or disable individual packets.  Each packet can

  19459. be set to 'on' (the remote target supports this packet), 'off' (the

  19460. remote target does not support this packet), or 'auto' (detect remote

  19461. target support for this packet).  They all default to 'auto'.  For more

  19462. information about each packet, see *note Remote Protocol::.

  19463. 

  19464.    During normal use, you should not have to use any of these commands.

  19465. If you do, that may be a bug in your remote debugging stub, or a bug in

  19466. GDB.  You may want to report the problem to the GDB developers.

  19467. 

  19468.    For each packet NAME, the command to enable or disable the packet is

  19469. 'set remote NAME-packet'.  The available settings are:

  19470. 

  19471. Command Name         Remote Packet           Related Features

  19472.                                              

  19473. 'fetch-register'     'p'                     'info registers'

  19474.                                              

  19475. 'set-register'       'P'                     'set'

  19476.                                              

  19477. 'binary-download'    'X'                     'load', 'set'

  19478.                                              

  19479. 'read-aux-vector'    'qXfer:auxv:read'       'info auxv'

  19480.                                              

  19481. 'symbol-lookup'      'qSymbol'               Detecting

  19482.                                              multiple threads

  19483.                                              

  19484. 'attach'             'vAttach'               'attach'

  19485.                                              

  19486. 'verbose-resume'     'vCont'                 Stepping or

  19487.                                              resuming

  19488.                                              multiple threads

  19489.                                              

  19490. 'run'                'vRun'                  'run'

  19491.                                              

  19492. 'software-breakpoint''Z0'                    'break'

  19493.                                              

  19494. 'hardware-breakpoint''Z1'                    'hbreak'

  19495.                                              

  19496. 'write-watchpoint'   'Z2'                    'watch'

  19497.                                              

  19498. 'read-watchpoint'    'Z3'                    'rwatch'

  19499.                                              

  19500. 'access-watchpoint'  'Z4'                    'awatch'

  19501.                                              

  19502. 'pid-to-exec-file'   'qXfer:exec-file:read'  'attach', 'run'

  19503.                                              

  19504. 'target-features'    'qXfer:features:read'   'set

  19505.                                              architecture'

  19506.                                              

  19507. 'library-info'       'qXfer:libraries:read'  'info

  19508.                                              sharedlibrary'

  19509.                                              

  19510. 'memory-map'         'qXfer:memory-map:read' 'info mem'

  19511.                                              

  19512. 'read-sdata-object'  'qXfer:sdata:read'      'print $_sdata'

  19513.                                              

  19514. 'read-siginfo-object''qXfer:siginfo:read'    'print

  19515.                                              $_siginfo'

  19516.                                              

  19517. 'write-siginfo-object''qXfer:siginfo:write'  'set $_siginfo'

  19518.                                              

  19519. 'threads'            'qXfer:threads:read'    'info threads'

  19520.                                              

  19521. 'get-thread-local-   'qGetTLSAddr'           Displaying

  19522. storage-address'                             '__thread'

  19523.                                              variables

  19524.                                              

  19525. 'get-thread-information-block-address''qGetTIBAddr'Display

  19526.                                              MS-Windows

  19527.                                              Thread

  19528.                                              Information

  19529.                                              Block.

  19530.                                              

  19531. 'search-memory'      'qSearch:memory'        'find'

  19532.                                              

  19533. 'supported-packets'  'qSupported'            Remote

  19534.                                              communications

  19535.                                              parameters

  19536.                                              

  19537. 'catch-syscalls'     'QCatchSyscalls'        'catch syscall'

  19538.                                              

  19539. 'pass-signals'       'QPassSignals'          'handle SIGNAL'

  19540.                                              

  19541. 'program-signals'    'QProgramSignals'       'handle SIGNAL'

  19542.                                              

  19543. 'hostio-close-packet''vFile:close'           'remote get',

  19544.                                              'remote put'

  19545.                                              

  19546. 'hostio-open-packet' 'vFile:open'            'remote get',

  19547.                                              'remote put'

  19548.                                              

  19549. 'hostio-pread-packet''vFile:pread'           'remote get',

  19550.                                              'remote put'

  19551.                                              

  19552. 'hostio-pwrite-packet''vFile:pwrite'         'remote get',

  19553.                                              'remote put'

  19554.                                              

  19555. 'hostio-unlink-packet''vFile:unlink'         'remote delete'

  19556.                                              

  19557. 'hostio-readlink-packet''vFile:readlink'     Host I/O

  19558.                                              

  19559. 'hostio-fstat-packet''vFile:fstat'           Host I/O

  19560.                                              

  19561. 'hostio-setfs-packet''vFile:setfs'           Host I/O

  19562.                                              

  19563. 'noack-packet'       'QStartNoAckMode'       Packet

  19564.                                              acknowledgment

  19565.                                              

  19566. 'osdata'             'qXfer:osdata:read'     'info os'

  19567.                                              

  19568. 'query-attached'     'qAttached'             Querying remote

  19569.                                              process attach

  19570.                                              state.

  19571.                                              

  19572. 'trace-buffer-size'  'QTBuffer:size'         'set

  19573.                                              trace-buffer-size'

  19574.                                              

  19575. 'trace-status'       'qTStatus'              'tstatus'

  19576.                                              

  19577. 'traceframe-info'    'qXfer:traceframe-info:read'Traceframe info

  19578.                                              

  19579. 'install-in-trace'   'InstallInTrace'        Install

  19580.                                              tracepoint in

  19581.                                              tracing

  19582.                                              

  19583. 'disable-randomization''QDisableRandomization''set

  19584.                                              disable-randomization'

  19585.                                              

  19586. 'startup-with-shell' 'QStartupWithShell'     'set

  19587.                                              startup-with-shell'

  19588.                                              

  19589. 'environment-hex-encoded''QEnvironmentHexEncoded''set

  19590.                                              environment'

  19591.                                              

  19592. 'environment-unset'  'QEnvironmentUnset'     'unset

  19593.                                              environment'

  19594.                                              

  19595. 'environment-reset'  'QEnvironmentReset'     'Reset the

  19596.                                              inferior

  19597.                                              environment

  19598.                                              (i.e., unset

  19599.                                              user-set

  19600.                                              variables)'

  19601.                                              

  19602. 'set-working-dir'    'QSetWorkingDir'        'set cwd'

  19603.                                              

  19604. 'conditional-breakpoints-packet''Z0 and Z1'  'Support for

  19605.                                              target-side

  19606.                                              breakpoint

  19607.                                              condition

  19608.                                              evaluation'

  19609.                                              

  19610. 'multiprocess-extensions''multiprocess       Debug multiple

  19611.                      extensions'             processes and

  19612.                                              remote process

  19613.                                              PID awareness

  19614.                                              

  19615. 'swbreak-feature'    'swbreak stop reason'   'break'

  19616.                                              

  19617. 'hwbreak-feature'    'hwbreak stop reason'   'hbreak'

  19618.                                              

  19619. 'fork-event-feature' 'fork stop reason'      'fork'

  19620.                                              

  19621. 'vfork-event-feature''vfork stop reason'     'vfork'

  19622.                                              

  19623. 'exec-event-feature' 'exec stop reason'      'exec'

  19624.                                              

  19625. 'thread-events'      'QThreadEvents'         Tracking thread

  19626.                                              lifetime.

  19627.                                              

  19628. 'no-resumed-stop-reply''no resumed thread    Tracking thread

  19629.                      left stop reply'        lifetime.

  19630.                                              

  19631. 

  19632. 

  19633. File: gdb.info,  Node: Remote Stub,  Prev: Remote Configuration,  Up: Remote Debugging

  19634. 

  19635. 20.5 Implementing a Remote Stub

  19636. ===============================

  19637. 

  19638. The stub files provided with GDB implement the target side of the

  19639. communication protocol, and the GDB side is implemented in the GDB

  19640. source file 'remote.c'.  Normally, you can simply allow these

  19641. subroutines to communicate, and ignore the details.  (If you're

  19642. implementing your own stub file, you can still ignore the details: start

  19643. with one of the existing stub files.  'sparc-stub.c' is the best

  19644. organized, and therefore the easiest to read.)

  19645. 

  19646.    To debug a program running on another machine (the debugging "target"

  19647. machine), you must first arrange for all the usual prerequisites for the

  19648. program to run by itself.  For example, for a C program, you need:

  19649. 

  19650.   1. A startup routine to set up the C runtime environment; these

  19651.      usually have a name like 'crt0'.  The startup routine may be

  19652.      supplied by your hardware supplier, or you may have to write your

  19653.      own.

  19654. 

  19655.   2. A C subroutine library to support your program's subroutine calls,

  19656.      notably managing input and output.

  19657. 

  19658.   3. A way of getting your program to the other machine--for example, a

  19659.      download program.  These are often supplied by the hardware

  19660.      manufacturer, but you may have to write your own from hardware

  19661.      documentation.

  19662. 

  19663.    The next step is to arrange for your program to use a serial port to

  19664. communicate with the machine where GDB is running (the "host" machine).

  19665. In general terms, the scheme looks like this:

  19666. 

  19667. _On the host,_

  19668.      GDB already understands how to use this protocol; when everything

  19669.      else is set up, you can simply use the 'target remote' command

  19670.      (*note Specifying a Debugging Target: Targets.).

  19671. 

  19672. _On the target,_

  19673.      you must link with your program a few special-purpose subroutines

  19674.      that implement the GDB remote serial protocol.  The file containing

  19675.      these subroutines is called a "debugging stub".

  19676. 

  19677.      On certain remote targets, you can use an auxiliary program

  19678.      'gdbserver' instead of linking a stub into your program.  *Note

  19679.      Using the 'gdbserver' Program: Server, for details.

  19680. 

  19681.    The debugging stub is specific to the architecture of the remote

  19682. machine; for example, use 'sparc-stub.c' to debug programs on SPARC

  19683. boards.

  19684. 

  19685.    These working remote stubs are distributed with GDB:

  19686. 

  19687. 'i386-stub.c'

  19688.      For Intel 386 and compatible architectures.

  19689. 

  19690. 'm68k-stub.c'

  19691.      For Motorola 680x0 architectures.

  19692. 

  19693. 'sh-stub.c'

  19694.      For Renesas SH architectures.

  19695. 

  19696. 'sparc-stub.c'

  19697.      For SPARC architectures.

  19698. 

  19699. 'sparcl-stub.c'

  19700.      For Fujitsu SPARCLITE architectures.

  19701. 

  19702.    The 'README' file in the GDB distribution may list other recently

  19703. added stubs.

  19704. 

  19705. * Menu:

  19706. 

  19707. * Stub Contents::       What the stub can do for you

  19708. * Bootstrapping::       What you must do for the stub

  19709. * Debug Session::       Putting it all together

  19710. 

  19711. 

  19712. File: gdb.info,  Node: Stub Contents,  Next: Bootstrapping,  Up: Remote Stub

  19713. 

  19714. 20.5.1 What the Stub Can Do for You

  19715. -----------------------------------

  19716. 

  19717. The debugging stub for your architecture supplies these three

  19718. subroutines:

  19719. 

  19720. 'set_debug_traps'

  19721.      This routine arranges for 'handle_exception' to run when your

  19722.      program stops.  You must call this subroutine explicitly in your

  19723.      program's startup code.

  19724. 

  19725. 'handle_exception'

  19726.      This is the central workhorse, but your program never calls it

  19727.      explicitly--the setup code arranges for 'handle_exception' to run

  19728.      when a trap is triggered.

  19729. 

  19730.      'handle_exception' takes control when your program stops during

  19731.      execution (for example, on a breakpoint), and mediates

  19732.      communications with GDB on the host machine.  This is where the

  19733.      communications protocol is implemented; 'handle_exception' acts as

  19734.      the GDB representative on the target machine.  It begins by sending

  19735.      summary information on the state of your program, then continues to

  19736.      execute, retrieving and transmitting any information GDB needs,

  19737.      until you execute a GDB command that makes your program resume; at

  19738.      that point, 'handle_exception' returns control to your own code on

  19739.      the target machine.

  19740. 

  19741. 'breakpoint'

  19742.      Use this auxiliary subroutine to make your program contain a

  19743.      breakpoint.  Depending on the particular situation, this may be the

  19744.      only way for GDB to get control.  For instance, if your target

  19745.      machine has some sort of interrupt button, you won't need to call

  19746.      this; pressing the interrupt button transfers control to

  19747.      'handle_exception'--in effect, to GDB.  On some machines, simply

  19748.      receiving characters on the serial port may also trigger a trap;

  19749.      again, in that situation, you don't need to call 'breakpoint' from

  19750.      your own program--simply running 'target remote' from the host GDB

  19751.      session gets control.

  19752. 

  19753.      Call 'breakpoint' if none of these is true, or if you simply want

  19754.      to make certain your program stops at a predetermined point for the

  19755.      start of your debugging session.

  19756. 

  19757. 

  19758. File: gdb.info,  Node: Bootstrapping,  Next: Debug Session,  Prev: Stub Contents,  Up: Remote Stub

  19759. 

  19760. 20.5.2 What You Must Do for the Stub

  19761. ------------------------------------

  19762. 

  19763. The debugging stubs that come with GDB are set up for a particular chip

  19764. architecture, but they have no information about the rest of your

  19765. debugging target machine.

  19766. 

  19767.    First of all you need to tell the stub how to communicate with the

  19768. serial port.

  19769. 

  19770. 'int getDebugChar()'

  19771.      Write this subroutine to read a single character from the serial

  19772.      port.  It may be identical to 'getchar' for your target system; a

  19773.      different name is used to allow you to distinguish the two if you

  19774.      wish.

  19775. 

  19776. 'void putDebugChar(int)'

  19777.      Write this subroutine to write a single character to the serial

  19778.      port.  It may be identical to 'putchar' for your target system; a

  19779.      different name is used to allow you to distinguish the two if you

  19780.      wish.

  19781. 

  19782.    If you want GDB to be able to stop your program while it is running,

  19783. you need to use an interrupt-driven serial driver, and arrange for it to

  19784. stop when it receives a '^C' ('\003', the control-C character).  That is

  19785. the character which GDB uses to tell the remote system to stop.

  19786. 

  19787.    Getting the debugging target to return the proper status to GDB

  19788. probably requires changes to the standard stub; one quick and dirty way

  19789. is to just execute a breakpoint instruction (the "dirty" part is that

  19790. GDB reports a 'SIGTRAP' instead of a 'SIGINT').

  19791. 

  19792.    Other routines you need to supply are:

  19793. 

  19794. 'void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'

  19795.      Write this function to install EXCEPTION_ADDRESS in the exception

  19796.      handling tables.  You need to do this because the stub does not

  19797.      have any way of knowing what the exception handling tables on your

  19798.      target system are like (for example, the processor's table might be

  19799.      in ROM, containing entries which point to a table in RAM).  The

  19800.      EXCEPTION_NUMBER specifies the exception which should be changed;

  19801.      its meaning is architecture-dependent (for example, different

  19802.      numbers might represent divide by zero, misaligned access, etc).

  19803.      When this exception occurs, control should be transferred directly

  19804.      to EXCEPTION_ADDRESS, and the processor state (stack, registers,

  19805.      and so on) should be just as it is when a processor exception

  19806.      occurs.  So if you want to use a jump instruction to reach

  19807.      EXCEPTION_ADDRESS, it should be a simple jump, not a jump to

  19808.      subroutine.

  19809. 

  19810.      For the 386, EXCEPTION_ADDRESS should be installed as an interrupt

  19811.      gate so that interrupts are masked while the handler runs.  The

  19812.      gate should be at privilege level 0 (the most privileged level).

  19813.      The SPARC and 68k stubs are able to mask interrupts themselves

  19814.      without help from 'exceptionHandler'.

  19815. 

  19816. 'void flush_i_cache()'

  19817.      On SPARC and SPARCLITE only, write this subroutine to flush the

  19818.      instruction cache, if any, on your target machine.  If there is no

  19819.      instruction cache, this subroutine may be a no-op.

  19820. 

  19821.      On target machines that have instruction caches, GDB requires this

  19822.      function to make certain that the state of your program is stable.

  19823. 

  19824. You must also make sure this library routine is available:

  19825. 

  19826. 'void *memset(void *, int, int)'

  19827.      This is the standard library function 'memset' that sets an area of

  19828.      memory to a known value.  If you have one of the free versions of

  19829.      'libc.a', 'memset' can be found there; otherwise, you must either

  19830.      obtain it from your hardware manufacturer, or write your own.

  19831. 

  19832.    If you do not use the GNU C compiler, you may need other standard

  19833. library subroutines as well; this varies from one stub to another, but

  19834. in general the stubs are likely to use any of the common library

  19835. subroutines which 'GCC' generates as inline code.

  19836. 

  19837. 

  19838. File: gdb.info,  Node: Debug Session,  Prev: Bootstrapping,  Up: Remote Stub

  19839. 

  19840. 20.5.3 Putting it All Together

  19841. ------------------------------

  19842. 

  19843. In summary, when your program is ready to debug, you must follow these

  19844. steps.

  19845. 

  19846.   1. Make sure you have defined the supporting low-level routines (*note

  19847.      What You Must Do for the Stub: Bootstrapping.):

  19848.           'getDebugChar', 'putDebugChar',

  19849.           'flush_i_cache', 'memset', 'exceptionHandler'.

  19850. 

  19851.   2. Insert these lines in your program's startup code, before the main

  19852.      procedure is called:

  19853. 

  19854.           set_debug_traps();

  19855.           breakpoint();

  19856. 

  19857.      On some machines, when a breakpoint trap is raised, the hardware

  19858.      automatically makes the PC point to the instruction after the

  19859.      breakpoint.  If your machine doesn't do that, you may need to

  19860.      adjust 'handle_exception' to arrange for it to return to the

  19861.      instruction after the breakpoint on this first invocation, so that

  19862.      your program doesn't keep hitting the initial breakpoint instead of

  19863.      making progress.

  19864. 

  19865.   3. For the 680x0 stub only, you need to provide a variable called

  19866.      'exceptionHook'.  Normally you just use:

  19867. 

  19868.           void (*exceptionHook)() = 0;

  19869. 

  19870.      but if before calling 'set_debug_traps', you set it to point to a

  19871.      function in your program, that function is called when 'GDB'

  19872.      continues after stopping on a trap (for example, bus error).  The

  19873.      function indicated by 'exceptionHook' is called with one parameter:

  19874.      an 'int' which is the exception number.

  19875. 

  19876.   4. Compile and link together: your program, the GDB debugging stub for

  19877.      your target architecture, and the supporting subroutines.

  19878. 

  19879.   5. Make sure you have a serial connection between your target machine

  19880.      and the GDB host, and identify the serial port on the host.

  19881. 

  19882.   6. Download your program to your target machine (or get it there by

  19883.      whatever means the manufacturer provides), and start it.

  19884. 

  19885.   7. Start GDB on the host, and connect to the target (*note Connecting

  19886.      to a Remote Target: Connecting.).

  19887. 

  19888. 

  19889. File: gdb.info,  Node: Configurations,  Next: Controlling GDB,  Prev: Remote Debugging,  Up: Top

  19890. 

  19891. 21 Configuration-Specific Information

  19892. *************************************

  19893. 

  19894. While nearly all GDB commands are available for all native and cross

  19895. versions of the debugger, there are some exceptions.  This chapter

  19896. describes things that are only available in certain configurations.

  19897. 

  19898.    There are three major categories of configurations: native

  19899. configurations, where the host and target are the same, embedded

  19900. operating system configurations, which are usually the same for several

  19901. different processor architectures, and bare embedded processors, which

  19902. are quite different from each other.

  19903. 

  19904. * Menu:

  19905. 

  19906. * Native::

  19907. * Embedded OS::

  19908. * Embedded Processors::

  19909. * Architectures::

  19910. 

  19911. 

  19912. File: gdb.info,  Node: Native,  Next: Embedded OS,  Up: Configurations

  19913. 

  19914. 21.1 Native

  19915. ===========

  19916. 

  19917. This section describes details specific to particular native

  19918. configurations.

  19919. 

  19920. * Menu:

  19921. 

  19922. * BSD libkvm Interface::	Debugging BSD kernel memory images

  19923. * Process Information::         Process information

  19924. * DJGPP Native::                Features specific to the DJGPP port

  19925. * Cygwin Native::		Features specific to the Cygwin port

  19926. * Hurd Native::                 Features specific to GNU Hurd

  19927. * Darwin::			Features specific to Darwin

  19928. * FreeBSD::			Features specific to FreeBSD

  19929. 

  19930. 

  19931. File: gdb.info,  Node: BSD libkvm Interface,  Next: Process Information,  Up: Native

  19932. 

  19933. 21.1.1 BSD libkvm Interface

  19934. ---------------------------

  19935. 

  19936. BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory

  19937. interface that provides a uniform interface for accessing kernel virtual

  19938. memory images, including live systems and crash dumps.  GDB uses this

  19939. interface to allow you to debug live kernels and kernel crash dumps on

  19940. many native BSD configurations.  This is implemented as a special 'kvm'

  19941. debugging target.  For debugging a live system, load the currently

  19942. running kernel into GDB and connect to the 'kvm' target:

  19943. 

  19944.      (gdb) target kvm

  19945. 

  19946.    For debugging crash dumps, provide the file name of the crash dump as

  19947. an argument:

  19948. 

  19949.      (gdb) target kvm /var/crash/bsd.0

  19950. 

  19951.    Once connected to the 'kvm' target, the following commands are

  19952. available:

  19953. 

  19954. 'kvm pcb'

  19955.      Set current context from the "Process Control Block" (PCB) address.

  19956. 

  19957. 'kvm proc'

  19958.      Set current context from proc address.  This command isn't

  19959.      available on modern FreeBSD systems.

  19960. 

  19961. 

  19962. File: gdb.info,  Node: Process Information,  Next: DJGPP Native,  Prev: BSD libkvm Interface,  Up: Native

  19963. 

  19964. 21.1.2 Process Information

  19965. --------------------------

  19966. 

  19967. Some operating systems provide interfaces to fetch additional

  19968. information about running processes beyond memory and per-thread

  19969. register state.  If GDB is configured for an operating system with a

  19970. supported interface, the command 'info proc' is available to report

  19971. information about the process running your program, or about any process

  19972. running on your system.

  19973. 

  19974.    One supported interface is a facility called '/proc' that can be used

  19975. to examine the image of a running process using file-system subroutines.

  19976. This facility is supported on GNU/Linux and Solaris systems.

  19977. 

  19978.    On FreeBSD and NetBSD systems, system control nodes are used to query

  19979. process information.

  19980. 

  19981.    In addition, some systems may provide additional process information

  19982. in core files.  Note that a core file may include a subset of the

  19983. information available from a live process.  Process information is

  19984. currently available from cores created on GNU/Linux and FreeBSD systems.

  19985. 

  19986. 'info proc'

  19987. 'info proc PROCESS-ID'

  19988.      Summarize available information about a process.  If a process ID

  19989.      is specified by PROCESS-ID, display information about that process;

  19990.      otherwise display information about the program being debugged.

  19991.      The summary includes the debugged process ID, the command line used

  19992.      to invoke it, its current working directory, and its executable

  19993.      file's absolute file name.

  19994. 

  19995.      On some systems, PROCESS-ID can be of the form '[PID]/TID' which

  19996.      specifies a certain thread ID within a process.  If the optional

  19997.      PID part is missing, it means a thread from the process being

  19998.      debugged (the leading '/' still needs to be present, or else GDB

  19999.      will interpret the number as a process ID rather than a thread ID).

  20000. 

  20001. 'info proc cmdline'

  20002.      Show the original command line of the process.  This command is

  20003.      supported on GNU/Linux, FreeBSD and NetBSD.

  20004. 

  20005. 'info proc cwd'

  20006.      Show the current working directory of the process.  This command is

  20007.      supported on GNU/Linux, FreeBSD and NetBSD.

  20008. 

  20009. 'info proc exe'

  20010.      Show the name of executable of the process.  This command is

  20011.      supported on GNU/Linux, FreeBSD and NetBSD.

  20012. 

  20013. 'info proc files'

  20014.      Show the file descriptors open by the process.  For each open file

  20015.      descriptor, GDB shows its number, type (file, directory, character

  20016.      device, socket), file pointer offset, and the name of the resource

  20017.      open on the descriptor.  The resource name can be a file name (for

  20018.      files, directories, and devices) or a protocol followed by socket

  20019.      address (for network connections).  This command is supported on

  20020.      FreeBSD.

  20021. 

  20022.      This example shows the open file descriptors for a process using a

  20023.      tty for standard input and output as well as two network sockets:

  20024. 

  20025.           (gdb) info proc files 22136

  20026.           process 22136

  20027.           Open files:

  20028. 

  20029.                 FD   Type     Offset   Flags   Name

  20030.               text   file          - r-------- /usr/bin/ssh

  20031.               ctty    chr          - rw------- /dev/pts/20

  20032.                cwd    dir          - r-------- /usr/home/john

  20033.               root    dir          - r-------- /

  20034.                  0    chr  0x32933a4 rw------- /dev/pts/20

  20035.                  1    chr  0x32933a4 rw------- /dev/pts/20

  20036.                  2    chr  0x32933a4 rw------- /dev/pts/20

  20037.                  3 socket        0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22

  20038.                  4 socket        0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456

  20039. 

  20040. 'info proc mappings'

  20041.      Report the memory address space ranges accessible in a process.  On

  20042.      Solaris, FreeBSD and NetBSD systems, each memory range includes

  20043.      information on whether the process has read, write, or execute

  20044.      access rights to each range.  On GNU/Linux, FreeBSD and NetBSD

  20045.      systems, each memory range includes the object file which is mapped

  20046.      to that range.

  20047. 

  20048. 'info proc stat'

  20049. 'info proc status'

  20050.      Show additional process-related information, including the user ID

  20051.      and group ID; virtual memory usage; the signals that are pending,

  20052.      blocked, and ignored; its TTY; its consumption of system and user

  20053.      time; its stack size; its 'nice' value; etc.  These commands are

  20054.      supported on GNU/Linux, FreeBSD and NetBSD.

  20055. 

  20056.      For GNU/Linux systems, see the 'proc' man page for more information

  20057.      (type 'man 5 proc' from your shell prompt).

  20058. 

  20059.      For FreeBSD and NetBSD systems, 'info proc stat' is an alias for

  20060.      'info proc status'.

  20061. 

  20062. 'info proc all'

  20063.      Show all the information about the process described under all of

  20064.      the above 'info proc' subcommands.

  20065. 

  20066. 'set procfs-trace'

  20067.      This command enables and disables tracing of 'procfs' API calls.

  20068. 

  20069. 'show procfs-trace'

  20070.      Show the current state of 'procfs' API call tracing.

  20071. 

  20072. 'set procfs-file FILE'

  20073.      Tell GDB to write 'procfs' API trace to the named FILE.  GDB

  20074.      appends the trace info to the previous contents of the file.  The

  20075.      default is to display the trace on the standard output.

  20076. 

  20077. 'show procfs-file'

  20078.      Show the file to which 'procfs' API trace is written.

  20079. 

  20080. 'proc-trace-entry'

  20081. 'proc-trace-exit'

  20082. 'proc-untrace-entry'

  20083. 'proc-untrace-exit'

  20084.      These commands enable and disable tracing of entries into and exits

  20085.      from the 'syscall' interface.

  20086. 

  20087. 'info pidlist'

  20088.      For QNX Neutrino only, this command displays the list of all the

  20089.      processes and all the threads within each process.

  20090. 

  20091. 'info meminfo'

  20092.      For QNX Neutrino only, this command displays the list of all

  20093.      mapinfos.

  20094. 

  20095. 

  20096. File: gdb.info,  Node: DJGPP Native,  Next: Cygwin Native,  Prev: Process Information,  Up: Native

  20097. 

  20098. 21.1.3 Features for Debugging DJGPP Programs

  20099. --------------------------------------------

  20100. 

  20101. DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows.

  20102. DJGPP programs are 32-bit protected-mode programs that use the "DPMI"

  20103. (DOS Protected-Mode Interface) API to run on top of real-mode DOS

  20104. systems and their emulations.

  20105. 

  20106.    GDB supports native debugging of DJGPP programs, and defines a few

  20107. commands specific to the DJGPP port.  This subsection describes those

  20108. commands.

  20109. 

  20110. 'info dos'

  20111.      This is a prefix of DJGPP-specific commands which print information

  20112.      about the target system and important OS structures.

  20113. 

  20114. 'info dos sysinfo'

  20115.      This command displays assorted information about the underlying

  20116.      platform: the CPU type and features, the OS version and flavor, the

  20117.      DPMI version, and the available conventional and DPMI memory.

  20118. 

  20119. 'info dos gdt'

  20120. 'info dos ldt'

  20121. 'info dos idt'

  20122.      These 3 commands display entries from, respectively, Global, Local,

  20123.      and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor

  20124.      tables are data structures which store a descriptor for each

  20125.      segment that is currently in use.  The segment's selector is an

  20126.      index into a descriptor table; the table entry for that index holds

  20127.      the descriptor's base address and limit, and its attributes and

  20128.      access rights.

  20129. 

  20130.      A typical DJGPP program uses 3 segments: a code segment, a data

  20131.      segment (used for both data and the stack), and a DOS segment

  20132.      (which allows access to DOS/BIOS data structures and absolute

  20133.      addresses in conventional memory).  However, the DPMI host will

  20134.      usually define additional segments in order to support the DPMI

  20135.      environment.

  20136. 

  20137.      These commands allow to display entries from the descriptor tables.

  20138.      Without an argument, all entries from the specified table are

  20139.      displayed.  An argument, which should be an integer expression,

  20140.      means display a single entry whose index is given by the argument.

  20141.      For example, here's a convenient way to display information about

  20142.      the debugged program's data segment:

  20143. 

  20144.      (gdb) info dos ldt $ds

  20145.      0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)

  20146. 

  20147.      This comes in handy when you want to see whether a pointer is

  20148.      outside the data segment's limit (i.e. "garbled").

  20149. 

  20150. 'info dos pde'

  20151. 'info dos pte'

  20152.      These two commands display entries from, respectively, the Page

  20153.      Directory and the Page Tables.  Page Directories and Page Tables

  20154.      are data structures which control how virtual memory addresses are

  20155.      mapped into physical addresses.  A Page Table includes an entry for

  20156.      every page of memory that is mapped into the program's address

  20157.      space; there may be several Page Tables, each one holding up to

  20158.      4096 entries.  A Page Directory has up to 4096 entries, one each

  20159.      for every Page Table that is currently in use.

  20160. 

  20161.      Without an argument, 'info dos pde' displays the entire Page

  20162.      Directory, and 'info dos pte' displays all the entries in all of

  20163.      the Page Tables.  An argument, an integer expression, given to the

  20164.      'info dos pde' command means display only that entry from the Page

  20165.      Directory table.  An argument given to the 'info dos pte' command

  20166.      means display entries from a single Page Table, the one pointed to

  20167.      by the specified entry in the Page Directory.

  20168. 

  20169.      These commands are useful when your program uses "DMA" (Direct

  20170.      Memory Access), which needs physical addresses to program the DMA

  20171.      controller.

  20172. 

  20173.      These commands are supported only with some DPMI servers.

  20174. 

  20175. 'info dos address-pte ADDR'

  20176.      This command displays the Page Table entry for a specified linear

  20177.      address.  The argument ADDR is a linear address which should

  20178.      already have the appropriate segment's base address added to it,

  20179.      because this command accepts addresses which may belong to _any_

  20180.      segment.  For example, here's how to display the Page Table entry

  20181.      for the page where a variable 'i' is stored:

  20182. 

  20183.      (gdb) info dos address-pte __djgpp_base_address + (char *)&i

  20184.      Page Table entry for address 0x11a00d30:

  20185.      Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30

  20186. 

  20187.      This says that 'i' is stored at offset '0xd30' from the page whose

  20188.      physical base address is '0x02698000', and shows all the attributes

  20189.      of that page.

  20190. 

  20191.      Note that you must cast the addresses of variables to a 'char *',

  20192.      since otherwise the value of '__djgpp_base_address', the base

  20193.      address of all variables and functions in a DJGPP program, will be

  20194.      added using the rules of C pointer arithmetics: if 'i' is declared

  20195.      an 'int', GDB will add 4 times the value of '__djgpp_base_address'

  20196.      to the address of 'i'.

  20197. 

  20198.      Here's another example, it displays the Page Table entry for the

  20199.      transfer buffer:

  20200. 

  20201.      (gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)

  20202.      Page Table entry for address 0x29110:

  20203.      Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110

  20204. 

  20205.      (The '+ 3' offset is because the transfer buffer's address is the

  20206.      3rd member of the '_go32_info_block' structure.)  The output

  20207.      clearly shows that this DPMI server maps the addresses in

  20208.      conventional memory 1:1, i.e. the physical ('0x00029000' + '0x110')

  20209.      and linear ('0x29110') addresses are identical.

  20210. 

  20211.      This command is supported only with some DPMI servers.

  20212. 

  20213.    In addition to native debugging, the DJGPP port supports remote

  20214. debugging via a serial data link.  The following commands are specific

  20215. to remote serial debugging in the DJGPP port of GDB.

  20216. 

  20217. 'set com1base ADDR'

  20218.      This command sets the base I/O port address of the 'COM1' serial

  20219.      port.

  20220. 

  20221. 'set com1irq IRQ'

  20222.      This command sets the "Interrupt Request" ('IRQ') line to use for

  20223.      the 'COM1' serial port.

  20224. 

  20225.      There are similar commands 'set com2base', 'set com3irq', etc. for

  20226.      setting the port address and the 'IRQ' lines for the other 3 COM

  20227.      ports.

  20228. 

  20229.      The related commands 'show com1base', 'show com1irq' etc. display

  20230.      the current settings of the base address and the 'IRQ' lines used

  20231.      by the COM ports.

  20232. 

  20233. 'info serial'

  20234.      This command prints the status of the 4 DOS serial ports.  For each

  20235.      port, it prints whether it's active or not, its I/O base address

  20236.      and IRQ number, whether it uses a 16550-style FIFO, its baudrate,

  20237.      and the counts of various errors encountered so far.

  20238. 

  20239. 

  20240. File: gdb.info,  Node: Cygwin Native,  Next: Hurd Native,  Prev: DJGPP Native,  Up: Native

  20241. 

  20242. 21.1.4 Features for Debugging MS Windows PE Executables

  20243. -------------------------------------------------------

  20244. 

  20245. GDB supports native debugging of MS Windows programs, including DLLs

  20246. with and without symbolic debugging information.

  20247. 

  20248.    MS-Windows programs that call 'SetConsoleMode' to switch off the

  20249. special meaning of the 'Ctrl-C' keystroke cannot be interrupted by

  20250. typing 'C-c'.  For this reason, GDB on MS-Windows supports 'C-<BREAK>'

  20251. as an alternative interrupt key sequence, which can be used to interrupt

  20252. the debuggee even if it ignores 'C-c'.

  20253. 

  20254.    There are various additional Cygwin-specific commands, described in

  20255. this section.  Working with DLLs that have no debugging symbols is

  20256. described in *note Non-debug DLL Symbols::.

  20257. 

  20258. 'info w32'

  20259.      This is a prefix of MS Windows-specific commands which print

  20260.      information about the target system and important OS structures.

  20261. 

  20262. 'info w32 selector'

  20263.      This command displays information returned by the Win32 API

  20264.      'GetThreadSelectorEntry' function.  It takes an optional argument

  20265.      that is evaluated to a long value to give the information about

  20266.      this given selector.  Without argument, this command displays

  20267.      information about the six segment registers.

  20268. 

  20269. 'info w32 thread-information-block'

  20270.      This command displays thread specific information stored in the

  20271.      Thread Information Block (readable on the X86 CPU family using

  20272.      '$fs' selector for 32-bit programs and '$gs' for 64-bit programs).

  20273. 

  20274. 'signal-event ID'

  20275.      This command signals an event with user-provided ID.  Used to

  20276.      resume crashing process when attached to it using MS-Windows JIT

  20277.      debugging (AeDebug).

  20278. 

  20279.      To use it, create or edit the following keys in

  20280.      'HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug' and/or

  20281.      'HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows

  20282.      NT\CurrentVersion\AeDebug' (for x86_64 versions):

  20283. 

  20284.         - 'Debugger' (REG_SZ) -- a command to launch the debugger.

  20285.           Suggested command is: 'FULLY-QUALIFIED-PATH-TO-GDB.EXE -ex

  20286.           "attach %ld" -ex "signal-event %ld" -ex "continue"'.

  20287. 

  20288.           The first '%ld' will be replaced by the process ID of the

  20289.           crashing process, the second '%ld' will be replaced by the ID

  20290.           of the event that blocks the crashing process, waiting for GDB

  20291.           to attach.

  20292. 

  20293.         - 'Auto' (REG_SZ) -- either '1' or '0'.  '1' will make the

  20294.           system run debugger specified by the Debugger key

  20295.           automatically, '0' will cause a dialog box with "OK" and

  20296.           "Cancel" buttons to appear, which allows the user to either

  20297.           terminate the crashing process (OK) or debug it (Cancel).

  20298. 

  20299. 'set cygwin-exceptions MODE'

  20300.      If MODE is 'on', GDB will break on exceptions that happen inside

  20301.      the Cygwin DLL. If MODE is 'off', GDB will delay recognition of

  20302.      exceptions, and may ignore some exceptions which seem to be caused

  20303.      by internal Cygwin DLL "bookkeeping".  This option is meant

  20304.      primarily for debugging the Cygwin DLL itself; the default value is

  20305.      'off' to avoid annoying GDB users with false 'SIGSEGV' signals.

  20306. 

  20307. 'show cygwin-exceptions'

  20308.      Displays whether GDB will break on exceptions that happen inside

  20309.      the Cygwin DLL itself.

  20310. 

  20311. 'set new-console MODE'

  20312.      If MODE is 'on' the debuggee will be started in a new console on

  20313.      next start.  If MODE is 'off', the debuggee will be started in the

  20314.      same console as the debugger.

  20315. 

  20316. 'show new-console'

  20317.      Displays whether a new console is used when the debuggee is

  20318.      started.

  20319. 

  20320. 'set new-group MODE'

  20321.      This boolean value controls whether the debuggee should start a new

  20322.      group or stay in the same group as the debugger.  This affects the

  20323.      way the Windows OS handles 'Ctrl-C'.

  20324. 

  20325. 'show new-group'

  20326.      Displays current value of new-group boolean.

  20327. 

  20328. 'set debugevents'

  20329.      This boolean value adds debug output concerning kernel events

  20330.      related to the debuggee seen by the debugger.  This includes events

  20331.      that signal thread and process creation and exit, DLL loading and

  20332.      unloading, console interrupts, and debugging messages produced by

  20333.      the Windows 'OutputDebugString' API call.

  20334. 

  20335. 'set debugexec'

  20336.      This boolean value adds debug output concerning execute events

  20337.      (such as resume thread) seen by the debugger.

  20338. 

  20339. 'set debugexceptions'

  20340.      This boolean value adds debug output concerning exceptions in the

  20341.      debuggee seen by the debugger.

  20342. 

  20343. 'set debugmemory'

  20344.      This boolean value adds debug output concerning debuggee memory

  20345.      reads and writes by the debugger.

  20346. 

  20347. 'set shell'

  20348.      This boolean values specifies whether the debuggee is called via a

  20349.      shell or directly (default value is on).

  20350. 

  20351. 'show shell'

  20352.      Displays if the debuggee will be started with a shell.

  20353. 

  20354. * Menu:

  20355. 

  20356. * Non-debug DLL Symbols::  Support for DLLs without debugging symbols

  20357. 

  20358. 

  20359. File: gdb.info,  Node: Non-debug DLL Symbols,  Up: Cygwin Native

  20360. 

  20361. 21.1.4.1 Support for DLLs without Debugging Symbols

  20362. ...................................................

  20363. 

  20364. Very often on windows, some of the DLLs that your program relies on do

  20365. not include symbolic debugging information (for example,

  20366. 'kernel32.dll').  When GDB doesn't recognize any debugging symbols in a

  20367. DLL, it relies on the minimal amount of symbolic information contained

  20368. in the DLL's export table.  This section describes working with such

  20369. symbols, known internally to GDB as "minimal symbols".

  20370. 

  20371.    Note that before the debugged program has started execution, no DLLs

  20372. will have been loaded.  The easiest way around this problem is simply to

  20373. start the program -- either by setting a breakpoint or letting the

  20374. program run once to completion.

  20375. 

  20376. 21.1.4.2 DLL Name Prefixes

  20377. ..........................

  20378. 

  20379. In keeping with the naming conventions used by the Microsoft debugging

  20380. tools, DLL export symbols are made available with a prefix based on the

  20381. DLL name, for instance 'KERNEL32!CreateFileA'.  The plain name is also

  20382. entered into the symbol table, so 'CreateFileA' is often sufficient.  In

  20383. some cases there will be name clashes within a program (particularly if

  20384. the executable itself includes full debugging symbols) necessitating the

  20385. use of the fully qualified name when referring to the contents of the

  20386. DLL. Use single-quotes around the name to avoid the exclamation mark

  20387. ("!")  being interpreted as a language operator.

  20388. 

  20389.    Note that the internal name of the DLL may be all upper-case, even

  20390. though the file name of the DLL is lower-case, or vice-versa.  Since

  20391. symbols within GDB are _case-sensitive_ this may cause some confusion.

  20392. If in doubt, try the 'info functions' and 'info variables' commands or

  20393. even 'maint print msymbols' (*note Symbols::).  Here's an example:

  20394. 

  20395.      (gdb) info function CreateFileA

  20396.      All functions matching regular expression "CreateFileA":

  20397. 

  20398.      Non-debugging symbols:

  20399.      0x77e885f4  CreateFileA

  20400.      0x77e885f4  KERNEL32!CreateFileA

  20401. 

  20402.      (gdb) info function !

  20403.      All functions matching regular expression "!":

  20404. 

  20405.      Non-debugging symbols:

  20406.      0x6100114c  cygwin1!__assert

  20407.      0x61004034  cygwin1!_dll_crt0@0

  20408.      0x61004240  cygwin1!dll_crt0(per_process *)

  20409.      [etc...]

  20410. 

  20411. 21.1.4.3 Working with Minimal Symbols

  20412. .....................................

  20413. 

  20414. Symbols extracted from a DLL's export table do not contain very much

  20415. type information.  All that GDB can do is guess whether a symbol refers

  20416. to a function or variable depending on the linker section that contains

  20417. the symbol.  Also note that the actual contents of the memory contained

  20418. in a DLL are not available unless the program is running.  This means

  20419. that you cannot examine the contents of a variable or disassemble a

  20420. function within a DLL without a running program.

  20421. 

  20422.    Variables are generally treated as pointers and dereferenced

  20423. automatically.  For this reason, it is often necessary to prefix a

  20424. variable name with the address-of operator ("&") and provide explicit

  20425. type information in the command.  Here's an example of the type of

  20426. problem:

  20427. 

  20428.      (gdb) print 'cygwin1!__argv'

  20429.      'cygwin1!__argv' has unknown type; cast it to its declared type

  20430. 

  20431.      (gdb) x 'cygwin1!__argv'

  20432.      'cygwin1!__argv' has unknown type; cast it to its declared type

  20433. 

  20434.    And two possible solutions:

  20435. 

  20436.      (gdb) print ((char **)'cygwin1!__argv')[0]

  20437.      $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"

  20438. 

  20439.      (gdb) x/2x &'cygwin1!__argv'

  20440.      0x610c0aa8 <cygwin1!__argv>:    0x10021608      0x00000000

  20441.      (gdb) x/x 0x10021608

  20442.      0x10021608:     0x0022fd98

  20443.      (gdb) x/s 0x0022fd98

  20444.      0x22fd98:        "/cygdrive/c/mydirectory/myprogram"

  20445. 

  20446.    Setting a break point within a DLL is possible even before the

  20447. program starts execution.  However, under these circumstances, GDB can't

  20448. examine the initial instructions of the function in order to skip the

  20449. function's frame set-up code.  You can work around this by using "*&" to

  20450. set the breakpoint at a raw memory address:

  20451. 

  20452.      (gdb) break *&'python22!PyOS_Readline'

  20453.      Breakpoint 1 at 0x1e04eff0

  20454. 

  20455.    The author of these extensions is not entirely convinced that setting

  20456. a break point within a shared DLL like 'kernel32.dll' is completely

  20457. safe.

  20458. 

  20459. 

  20460. File: gdb.info,  Node: Hurd Native,  Next: Darwin,  Prev: Cygwin Native,  Up: Native

  20461. 

  20462. 21.1.5 Commands Specific to GNU Hurd Systems

  20463. --------------------------------------------

  20464. 

  20465. This subsection describes GDB commands specific to the GNU Hurd native

  20466. debugging.

  20467. 

  20468. 'set signals'

  20469. 'set sigs'

  20470.      This command toggles the state of inferior signal interception by

  20471.      GDB.  Mach exceptions, such as breakpoint traps, are not affected

  20472.      by this command.  'sigs' is a shorthand alias for 'signals'.

  20473. 

  20474. 'show signals'

  20475. 'show sigs'

  20476.      Show the current state of intercepting inferior's signals.

  20477. 

  20478. 'set signal-thread'

  20479. 'set sigthread'

  20480.      This command tells GDB which thread is the 'libc' signal thread.

  20481.      That thread is run when a signal is delivered to a running process.

  20482.      'set sigthread' is the shorthand alias of 'set signal-thread'.

  20483. 

  20484. 'show signal-thread'

  20485. 'show sigthread'

  20486.      These two commands show which thread will run when the inferior is

  20487.      delivered a signal.

  20488. 

  20489. 'set stopped'

  20490.      This commands tells GDB that the inferior process is stopped, as

  20491.      with the 'SIGSTOP' signal.  The stopped process can be continued by

  20492.      delivering a signal to it.

  20493. 

  20494. 'show stopped'

  20495.      This command shows whether GDB thinks the debuggee is stopped.

  20496. 

  20497. 'set exceptions'

  20498.      Use this command to turn off trapping of exceptions in the

  20499.      inferior.  When exception trapping is off, neither breakpoints nor

  20500.      single-stepping will work.  To restore the default, set exception

  20501.      trapping on.

  20502. 

  20503. 'show exceptions'

  20504.      Show the current state of trapping exceptions in the inferior.

  20505. 

  20506. 'set task pause'

  20507.      This command toggles task suspension when GDB has control.  Setting

  20508.      it to on takes effect immediately, and the task is suspended

  20509.      whenever GDB gets control.  Setting it to off will take effect the

  20510.      next time the inferior is continued.  If this option is set to off,

  20511.      you can use 'set thread default pause on' or 'set thread pause on'

  20512.      (see below) to pause individual threads.

  20513. 

  20514. 'show task pause'

  20515.      Show the current state of task suspension.

  20516. 

  20517. 'set task detach-suspend-count'

  20518.      This command sets the suspend count the task will be left with when

  20519.      GDB detaches from it.

  20520. 

  20521. 'show task detach-suspend-count'

  20522.      Show the suspend count the task will be left with when detaching.

  20523. 

  20524. 'set task exception-port'

  20525. 'set task excp'

  20526.      This command sets the task exception port to which GDB will forward

  20527.      exceptions.  The argument should be the value of the "send rights"

  20528.      of the task.  'set task excp' is a shorthand alias.

  20529. 

  20530. 'set noninvasive'

  20531.      This command switches GDB to a mode that is the least invasive as

  20532.      far as interfering with the inferior is concerned.  This is the

  20533.      same as using 'set task pause', 'set exceptions', and 'set signals'

  20534.      to values opposite to the defaults.

  20535. 

  20536. 'info send-rights'

  20537. 'info receive-rights'

  20538. 'info port-rights'

  20539. 'info port-sets'

  20540. 'info dead-names'

  20541. 'info ports'

  20542. 'info psets'

  20543.      These commands display information about, respectively, send

  20544.      rights, receive rights, port rights, port sets, and dead names of a

  20545.      task.  There are also shorthand aliases: 'info ports' for 'info

  20546.      port-rights' and 'info psets' for 'info port-sets'.

  20547. 

  20548. 'set thread pause'

  20549.      This command toggles current thread suspension when GDB has

  20550.      control.  Setting it to on takes effect immediately, and the

  20551.      current thread is suspended whenever GDB gets control.  Setting it

  20552.      to off will take effect the next time the inferior is continued.

  20553.      Normally, this command has no effect, since when GDB has control,

  20554.      the whole task is suspended.  However, if you used 'set task pause

  20555.      off' (see above), this command comes in handy to suspend only the

  20556.      current thread.

  20557. 

  20558. 'show thread pause'

  20559.      This command shows the state of current thread suspension.

  20560. 

  20561. 'set thread run'

  20562.      This command sets whether the current thread is allowed to run.

  20563. 

  20564. 'show thread run'

  20565.      Show whether the current thread is allowed to run.

  20566. 

  20567. 'set thread detach-suspend-count'

  20568.      This command sets the suspend count GDB will leave on a thread when

  20569.      detaching.  This number is relative to the suspend count found by

  20570.      GDB when it notices the thread; use 'set thread

  20571.      takeover-suspend-count' to force it to an absolute value.

  20572. 

  20573. 'show thread detach-suspend-count'

  20574.      Show the suspend count GDB will leave on the thread when detaching.

  20575. 

  20576. 'set thread exception-port'

  20577. 'set thread excp'

  20578.      Set the thread exception port to which to forward exceptions.  This

  20579.      overrides the port set by 'set task exception-port' (see above).

  20580.      'set thread excp' is the shorthand alias.

  20581. 

  20582. 'set thread takeover-suspend-count'

  20583.      Normally, GDB's thread suspend counts are relative to the value GDB

  20584.      finds when it notices each thread.  This command changes the

  20585.      suspend counts to be absolute instead.

  20586. 

  20587. 'set thread default'

  20588. 'show thread default'

  20589.      Each of the above 'set thread' commands has a 'set thread default'

  20590.      counterpart (e.g., 'set thread default pause', 'set thread default

  20591.      exception-port', etc.).  The 'thread default' variety of commands

  20592.      sets the default thread properties for all threads; you can then

  20593.      change the properties of individual threads with the non-default

  20594.      commands.

  20595. 

  20596. 

  20597. File: gdb.info,  Node: Darwin,  Next: FreeBSD,  Prev: Hurd Native,  Up: Native

  20598. 

  20599. 21.1.6 Darwin

  20600. -------------

  20601. 

  20602. GDB provides the following commands specific to the Darwin target:

  20603. 

  20604. 'set debug darwin NUM'

  20605.      When set to a non zero value, enables debugging messages specific

  20606.      to the Darwin support.  Higher values produce more verbose output.

  20607. 

  20608. 'show debug darwin'

  20609.      Show the current state of Darwin messages.

  20610. 

  20611. 'set debug mach-o NUM'

  20612.      When set to a non zero value, enables debugging messages while GDB

  20613.      is reading Darwin object files.  ("Mach-O" is the file format used

  20614.      on Darwin for object and executable files.)  Higher values produce

  20615.      more verbose output.  This is a command to diagnose problems

  20616.      internal to GDB and should not be needed in normal usage.

  20617. 

  20618. 'show debug mach-o'

  20619.      Show the current state of Mach-O file messages.

  20620. 

  20621. 'set mach-exceptions on'

  20622. 'set mach-exceptions off'

  20623.      On Darwin, faults are first reported as a Mach exception and are

  20624.      then mapped to a Posix signal.  Use this command to turn on

  20625.      trapping of Mach exceptions in the inferior.  This might be

  20626.      sometimes useful to better understand the cause of a fault.  The

  20627.      default is off.

  20628. 

  20629. 'show mach-exceptions'

  20630.      Show the current state of exceptions trapping.

  20631. 

  20632. 

  20633. File: gdb.info,  Node: FreeBSD,  Prev: Darwin,  Up: Native

  20634. 

  20635. 21.1.7 FreeBSD

  20636. --------------

  20637. 

  20638. When the ABI of a system call is changed in the FreeBSD kernel, this is

  20639. implemented by leaving a compatibility system call using the old ABI at

  20640. the existing number and allocating a new system call number for the

  20641. version using the new ABI. As a convenience, when a system call is

  20642. caught by name (*note catch syscall::), compatibility system calls are

  20643. also caught.

  20644. 

  20645.    For example, FreeBSD 12 introduced a new variant of the 'kevent'

  20646. system call and catching the 'kevent' system call by name catches both

  20647. variants:

  20648. 

  20649.      (gdb) catch syscall kevent

  20650.      Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])

  20651.      (gdb)

  20652. 

  20653. 

  20654. File: gdb.info,  Node: Embedded OS,  Next: Embedded Processors,  Prev: Native,  Up: Configurations

  20655. 

  20656. 21.2 Embedded Operating Systems

  20657. ===============================

  20658. 

  20659. This section describes configurations involving the debugging of

  20660. embedded operating systems that are available for several different

  20661. architectures.

  20662. 

  20663.    GDB includes the ability to debug programs running on various

  20664. real-time operating systems.

  20665. 

  20666. 

  20667. File: gdb.info,  Node: Embedded Processors,  Next: Architectures,  Prev: Embedded OS,  Up: Configurations

  20668. 

  20669. 21.3 Embedded Processors

  20670. ========================

  20671. 

  20672. This section goes into details specific to particular embedded

  20673. configurations.

  20674. 

  20675.    Whenever a specific embedded processor has a simulator, GDB allows to

  20676. send an arbitrary command to the simulator.

  20677. 

  20678. 'sim COMMAND'

  20679.      Send an arbitrary COMMAND string to the simulator.  Consult the

  20680.      documentation for the specific simulator in use for information

  20681.      about acceptable commands.

  20682. 

  20683. * Menu:

  20684. 

  20685. * ARC::                         Synopsys ARC

  20686. * ARM::                         ARM

  20687. * BPF::                         eBPF

  20688. * M68K::                        Motorola M68K

  20689. * MicroBlaze::			Xilinx MicroBlaze

  20690. * MIPS Embedded::               MIPS Embedded

  20691. * OpenRISC 1000::               OpenRISC 1000 (or1k)

  20692. * PowerPC Embedded::            PowerPC Embedded

  20693. * AVR::                         Atmel AVR

  20694. * CRIS::                        CRIS

  20695. * Super-H::                     Renesas Super-H

  20696. 

  20697. 

  20698. File: gdb.info,  Node: ARC,  Next: ARM,  Up: Embedded Processors

  20699. 

  20700. 21.3.1 Synopsys ARC

  20701. -------------------

  20702. 

  20703. GDB provides the following ARC-specific commands:

  20704. 

  20705. 'set debug arc'

  20706.      Control the level of ARC specific debug messages.  Use 0 for no

  20707.      messages (the default), 1 for debug messages, and 2 for even more

  20708.      debug messages.

  20709. 

  20710. 'show debug arc'

  20711.      Show the level of ARC specific debugging in operation.

  20712. 

  20713. 'maint print arc arc-instruction ADDRESS'

  20714.      Print internal disassembler information about instruction at a

  20715.      given address.

  20716. 

  20717. 

  20718. File: gdb.info,  Node: ARM,  Next: BPF,  Prev: ARC,  Up: Embedded Processors

  20719. 

  20720. 21.3.2 ARM

  20721. ----------

  20722. 

  20723. GDB provides the following ARM-specific commands:

  20724. 

  20725. 'set arm disassembler'

  20726.      This commands selects from a list of disassembly styles.  The

  20727.      '"std"' style is the standard style.

  20728. 

  20729. 'show arm disassembler'

  20730.      Show the current disassembly style.

  20731. 

  20732. 'set arm apcs32'

  20733.      This command toggles ARM operation mode between 32-bit and 26-bit.

  20734. 

  20735. 'show arm apcs32'

  20736.      Display the current usage of the ARM 32-bit mode.

  20737. 

  20738. 'set arm fpu FPUTYPE'

  20739.      This command sets the ARM floating-point unit (FPU) type.  The

  20740.      argument FPUTYPE can be one of these:

  20741. 

  20742.      'auto'

  20743.           Determine the FPU type by querying the OS ABI.

  20744.      'softfpa'

  20745.           Software FPU, with mixed-endian doubles on little-endian ARM

  20746.           processors.

  20747.      'fpa'

  20748.           GCC-compiled FPA co-processor.

  20749.      'softvfp'

  20750.           Software FPU with pure-endian doubles.

  20751.      'vfp'

  20752.           VFP co-processor.

  20753. 

  20754. 'show arm fpu'

  20755.      Show the current type of the FPU.

  20756. 

  20757. 'set arm abi'

  20758.      This command forces GDB to use the specified ABI.

  20759. 

  20760. 'show arm abi'

  20761.      Show the currently used ABI.

  20762. 

  20763. 'set arm fallback-mode (arm|thumb|auto)'

  20764.      GDB uses the symbol table, when available, to determine whether

  20765.      instructions are ARM or Thumb.  This command controls GDB's default

  20766.      behavior when the symbol table is not available.  The default is

  20767.      'auto', which causes GDB to use the current execution mode (from

  20768.      the 'T' bit in the 'CPSR' register).

  20769. 

  20770. 'show arm fallback-mode'

  20771.      Show the current fallback instruction mode.

  20772. 

  20773. 'set arm force-mode (arm|thumb|auto)'

  20774.      This command overrides use of the symbol table to determine whether

  20775.      instructions are ARM or Thumb.  The default is 'auto', which causes

  20776.      GDB to use the symbol table and then the setting of 'set arm

  20777.      fallback-mode'.

  20778. 

  20779. 'show arm force-mode'

  20780.      Show the current forced instruction mode.

  20781. 

  20782. 'set debug arm'

  20783.      Toggle whether to display ARM-specific debugging messages from the

  20784.      ARM target support subsystem.

  20785. 

  20786. 'show debug arm'

  20787.      Show whether ARM-specific debugging messages are enabled.

  20788. 

  20789. 'target sim [SIMARGS] ...'

  20790.      The GDB ARM simulator accepts the following optional arguments.

  20791. 

  20792.      '--swi-support=TYPE'

  20793.           Tell the simulator which SWI interfaces to support.  The

  20794.           argument TYPE may be a comma separated list of the following

  20795.           values.  The default value is 'all'.

  20796. 

  20797.           'none'

  20798.           'demon'

  20799.           'angel'

  20800.           'redboot'

  20801.           'all'

  20802. 

  20803. 

  20804. File: gdb.info,  Node: BPF,  Next: M68K,  Prev: ARM,  Up: Embedded Processors

  20805. 

  20806. 21.3.3 BPF

  20807. ----------

  20808. 

  20809. 'target sim [SIMARGS] ...'

  20810.      The GDB BPF simulator accepts the following optional arguments.

  20811. 

  20812.      '--skb-data-offset=OFFSET'

  20813.           Tell the simulator the offset, measured in bytes, of the

  20814.           'skb_data' field in the kernel 'struct sk_buff' structure.

  20815.           This offset is used by some BPF specific-purpose load/store

  20816.           instructions.  Defaults to 0.

  20817. 

  20818. 

  20819. File: gdb.info,  Node: M68K,  Next: MicroBlaze,  Prev: BPF,  Up: Embedded Processors

  20820. 

  20821. 21.3.4 M68k

  20822. -----------

  20823. 

  20824. The Motorola m68k configuration includes ColdFire support.

  20825. 

  20826. 

  20827. File: gdb.info,  Node: MicroBlaze,  Next: MIPS Embedded,  Prev: M68K,  Up: Embedded Processors

  20828. 

  20829. 21.3.5 MicroBlaze

  20830. -----------------

  20831. 

  20832. The MicroBlaze is a soft-core processor supported on various Xilinx

  20833. FPGAs, such as Spartan or Virtex series.  Boards with these processors

  20834. usually have JTAG ports which connect to a host system running the

  20835. Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK).

  20836. This host system is used to download the configuration bitstream to the

  20837. target FPGA. The Xilinx Microprocessor Debugger (XMD) program

  20838. communicates with the target board using the JTAG interface and presents

  20839. a 'gdbserver' interface to the board.  By default 'xmd' uses port

  20840. '1234'.  (While it is possible to change this default port, it requires

  20841. the use of undocumented 'xmd' commands.  Contact Xilinx support if you

  20842. need to do this.)

  20843. 

  20844.    Use these GDB commands to connect to the MicroBlaze target processor.

  20845. 

  20846. 'target remote :1234'

  20847.      Use this command to connect to the target if you are running GDB on

  20848.      the same system as 'xmd'.

  20849. 

  20850. 'target remote XMD-HOST:1234'

  20851.      Use this command to connect to the target if it is connected to

  20852.      'xmd' running on a different system named XMD-HOST.

  20853. 

  20854. 'load'

  20855.      Use this command to download a program to the MicroBlaze target.

  20856. 

  20857. 'set debug microblaze N'

  20858.      Enable MicroBlaze-specific debugging messages if non-zero.

  20859. 

  20860. 'show debug microblaze N'

  20861.      Show MicroBlaze-specific debugging level.

  20862. 

  20863. 

  20864. File: gdb.info,  Node: MIPS Embedded,  Next: OpenRISC 1000,  Prev: MicroBlaze,  Up: Embedded Processors

  20865. 

  20866. 21.3.6 MIPS Embedded

  20867. --------------------

  20868. 

  20869. GDB supports these special commands for MIPS targets:

  20870. 

  20871. 'set mipsfpu double'

  20872. 'set mipsfpu single'

  20873. 'set mipsfpu none'

  20874. 'set mipsfpu auto'

  20875. 'show mipsfpu'

  20876.      If your target board does not support the MIPS floating point

  20877.      coprocessor, you should use the command 'set mipsfpu none' (if you

  20878.      need this, you may wish to put the command in your GDB init file).

  20879.      This tells GDB how to find the return value of functions which

  20880.      return floating point values.  It also allows GDB to avoid saving

  20881.      the floating point registers when calling functions on the board.

  20882.      If you are using a floating point coprocessor with only single

  20883.      precision floating point support, as on the R4650 processor, use

  20884.      the command 'set mipsfpu single'.  The default double precision

  20885.      floating point coprocessor may be selected using 'set mipsfpu

  20886.      double'.

  20887. 

  20888.      In previous versions the only choices were double precision or no

  20889.      floating point, so 'set mipsfpu on' will select double precision

  20890.      and 'set mipsfpu off' will select no floating point.

  20891. 

  20892.      As usual, you can inquire about the 'mipsfpu' variable with 'show

  20893.      mipsfpu'.

  20894. 

  20895. 

  20896. File: gdb.info,  Node: OpenRISC 1000,  Next: PowerPC Embedded,  Prev: MIPS Embedded,  Up: Embedded Processors

  20897. 

  20898. 21.3.7 OpenRISC 1000

  20899. --------------------

  20900. 

  20901. The OpenRISC 1000 provides a free RISC instruction set architecture.  It

  20902. is mainly provided as a soft-core which can run on Xilinx, Altera and

  20903. other FPGA's.

  20904. 

  20905.    GDB for OpenRISC supports the below commands when connecting to a

  20906. target:

  20907. 

  20908. 'target sim'

  20909. 

  20910.      Runs the builtin CPU simulator which can run very basic programs

  20911.      but does not support most hardware functions like MMU. For more

  20912.      complex use cases the user is advised to run an external target,

  20913.      and connect using 'target remote'.

  20914. 

  20915.      Example: 'target sim'

  20916. 

  20917. 'set debug or1k'

  20918.      Toggle whether to display OpenRISC-specific debugging messages from

  20919.      the OpenRISC target support subsystem.

  20920. 

  20921. 'show debug or1k'

  20922.      Show whether OpenRISC-specific debugging messages are enabled.

  20923. 

  20924. 

  20925. File: gdb.info,  Node: PowerPC Embedded,  Next: AVR,  Prev: OpenRISC 1000,  Up: Embedded Processors

  20926. 

  20927. 21.3.8 PowerPC Embedded

  20928. -----------------------

  20929. 

  20930. GDB supports using the DVC (Data Value Compare) register to implement in

  20931. hardware simple hardware watchpoint conditions of the form:

  20932. 

  20933.      (gdb) watch ADDRESS|VARIABLE \

  20934.        if  ADDRESS|VARIABLE == CONSTANT EXPRESSION

  20935. 

  20936.    The DVC register will be automatically used when GDB detects such

  20937. pattern in a condition expression, and the created watchpoint uses one

  20938. debug register (either the 'exact-watchpoints' option is on and the

  20939. variable is scalar, or the variable has a length of one byte).  This

  20940. feature is available in native GDB running on a Linux kernel version

  20941. 2.6.34 or newer.

  20942. 

  20943.    When running on PowerPC embedded processors, GDB automatically uses

  20944. ranged hardware watchpoints, unless the 'exact-watchpoints' option is

  20945. on, in which case watchpoints using only one debug register are created

  20946. when watching variables of scalar types.

  20947. 

  20948.    You can create an artificial array to watch an arbitrary memory

  20949. region using one of the following commands (*note Expressions::):

  20950. 

  20951.      (gdb) watch *((char *) ADDRESS)@LENGTH

  20952.      (gdb) watch {char[LENGTH]} ADDRESS

  20953. 

  20954.    PowerPC embedded processors support masked watchpoints.  See the

  20955. discussion about the 'mask' argument in *note Set Watchpoints::.

  20956. 

  20957.    PowerPC embedded processors support hardware accelerated "ranged

  20958. breakpoints".  A ranged breakpoint stops execution of the inferior

  20959. whenever it executes an instruction at any address within the range it

  20960. specifies.  To set a ranged breakpoint in GDB, use the 'break-range'

  20961. command.

  20962. 

  20963.    GDB provides the following PowerPC-specific commands:

  20964. 

  20965. 'break-range START-LOCATION, END-LOCATION'

  20966.      Set a breakpoint for an address range given by START-LOCATION and

  20967.      END-LOCATION, which can specify a function name, a line number, an

  20968.      offset of lines from the current line or from the start location,

  20969.      or an address of an instruction (see *note Specify Location::, for

  20970.      a list of all the possible ways to specify a LOCATION.)  The

  20971.      breakpoint will stop execution of the inferior whenever it executes

  20972.      an instruction at any address within the specified range,

  20973.      (including START-LOCATION and END-LOCATION.)

  20974. 

  20975. 'set powerpc soft-float'

  20976. 'show powerpc soft-float'

  20977.      Force GDB to use (or not use) a software floating point calling

  20978.      convention.  By default, GDB selects the calling convention based

  20979.      on the selected architecture and the provided executable file.

  20980. 

  20981. 'set powerpc vector-abi'

  20982. 'show powerpc vector-abi'

  20983.      Force GDB to use the specified calling convention for vector

  20984.      arguments and return values.  The valid options are 'auto';

  20985.      'generic', to avoid vector registers even if they are present;

  20986.      'altivec', to use AltiVec registers; and 'spe' to use SPE

  20987.      registers.  By default, GDB selects the calling convention based on

  20988.      the selected architecture and the provided executable file.

  20989. 

  20990. 'set powerpc exact-watchpoints'

  20991. 'show powerpc exact-watchpoints'

  20992.      Allow GDB to use only one debug register when watching a variable

  20993.      of scalar type, thus assuming that the variable is accessed through

  20994.      the address of its first byte.

  20995. 

  20996. 

  20997. File: gdb.info,  Node: AVR,  Next: CRIS,  Prev: PowerPC Embedded,  Up: Embedded Processors

  20998. 

  20999. 21.3.9 Atmel AVR

  21000. ----------------

  21001. 

  21002. When configured for debugging the Atmel AVR, GDB supports the following

  21003. AVR-specific commands:

  21004. 

  21005. 'info io_registers'

  21006.      This command displays information about the AVR I/O registers.  For

  21007.      each register, GDB prints its number and value.

  21008. 

  21009. 

  21010. File: gdb.info,  Node: CRIS,  Next: Super-H,  Prev: AVR,  Up: Embedded Processors

  21011. 

  21012. 21.3.10 CRIS

  21013. ------------

  21014. 

  21015. When configured for debugging CRIS, GDB provides the following

  21016. CRIS-specific commands:

  21017. 

  21018. 'set cris-version VER'

  21019.      Set the current CRIS version to VER, either '10' or '32'.  The CRIS

  21020.      version affects register names and sizes.  This command is useful

  21021.      in case autodetection of the CRIS version fails.

  21022. 

  21023. 'show cris-version'

  21024.      Show the current CRIS version.

  21025. 

  21026. 'set cris-dwarf2-cfi'

  21027.      Set the usage of DWARF-2 CFI for CRIS debugging.  The default is

  21028.      'on'.  Change to 'off' when using 'gcc-cris' whose version is below

  21029.      'R59'.

  21030. 

  21031. 'show cris-dwarf2-cfi'

  21032.      Show the current state of using DWARF-2 CFI.

  21033. 

  21034. 'set cris-mode MODE'

  21035.      Set the current CRIS mode to MODE.  It should only be changed when

  21036.      debugging in guru mode, in which case it should be set to 'guru'

  21037.      (the default is 'normal').

  21038. 

  21039. 'show cris-mode'

  21040.      Show the current CRIS mode.

  21041. 

  21042. 

  21043. File: gdb.info,  Node: Super-H,  Prev: CRIS,  Up: Embedded Processors

  21044. 

  21045. 21.3.11 Renesas Super-H

  21046. -----------------------

  21047. 

  21048. For the Renesas Super-H processor, GDB provides these commands:

  21049. 

  21050. 'set sh calling-convention CONVENTION'

  21051.      Set the calling-convention used when calling functions from GDB.

  21052.      Allowed values are 'gcc', which is the default setting, and

  21053.      'renesas'.  With the 'gcc' setting, functions are called using the

  21054.      GCC calling convention.  If the DWARF-2 information of the called

  21055.      function specifies that the function follows the Renesas calling

  21056.      convention, the function is called using the Renesas calling

  21057.      convention.  If the calling convention is set to 'renesas', the

  21058.      Renesas calling convention is always used, regardless of the

  21059.      DWARF-2 information.  This can be used to override the default of

  21060.      'gcc' if debug information is missing, or the compiler does not

  21061.      emit the DWARF-2 calling convention entry for a function.

  21062. 

  21063. 'show sh calling-convention'

  21064.      Show the current calling convention setting.

  21065. 

  21066. 

  21067. File: gdb.info,  Node: Architectures,  Prev: Embedded Processors,  Up: Configurations

  21068. 

  21069. 21.4 Architectures

  21070. ==================

  21071. 

  21072. This section describes characteristics of architectures that affect all

  21073. uses of GDB with the architecture, both native and cross.

  21074. 

  21075. * Menu:

  21076. 

  21077. * AArch64::

  21078. * i386::

  21079. * Alpha::

  21080. * MIPS::

  21081. * HPPA::               HP PA architecture

  21082. * PowerPC::

  21083. * Nios II::

  21084. * Sparc64::

  21085. * S12Z::

  21086. 

  21087. 

  21088. File: gdb.info,  Node: AArch64,  Next: i386,  Up: Architectures

  21089. 

  21090. 21.4.1 AArch64

  21091. --------------

  21092. 

  21093. When GDB is debugging the AArch64 architecture, it provides the

  21094. following special commands:

  21095. 

  21096. 'set debug aarch64'

  21097.      This command determines whether AArch64 architecture-specific

  21098.      debugging messages are to be displayed.

  21099. 

  21100. 'show debug aarch64'

  21101.      Show whether AArch64 debugging messages are displayed.

  21102. 

  21103. 21.4.1.1 AArch64 SVE.

  21104. .....................

  21105. 

  21106. When GDB is debugging the AArch64 architecture, if the Scalable Vector

  21107. Extension (SVE) is present, then GDB will provide the vector registers

  21108. '$z0' through '$z31', vector predicate registers '$p0' through '$p15',

  21109. and the '$ffr' register.  In addition, the pseudo register '$vg' will be

  21110. provided.  This is the vector granule for the current thread and

  21111. represents the number of 64-bit chunks in an SVE 'z' register.

  21112. 

  21113.    If the vector length changes, then the '$vg' register will be

  21114. updated, but the lengths of the 'z' and 'p' registers will not change.

  21115. This is a known limitation of GDB and does not affect the execution of

  21116. the target process.

  21117. 

  21118. 21.4.1.2 AArch64 Pointer Authentication.

  21119. ........................................

  21120. 

  21121. When GDB is debugging the AArch64 architecture, and the program is using

  21122. the v8.3-A feature Pointer Authentication (PAC), then whenever the link

  21123. register '$lr' is pointing to an PAC function its value will be masked.

  21124. When GDB prints a backtrace, any addresses that required unmasking will

  21125. be postfixed with the marker [PAC]. When using the MI, this is printed

  21126. as part of the 'addr_flags' field.

  21127. 

  21128. 

  21129. File: gdb.info,  Node: i386,  Next: Alpha,  Prev: AArch64,  Up: Architectures

  21130. 

  21131. 21.4.2 x86 Architecture-specific Issues

  21132. ---------------------------------------

  21133. 

  21134. 'set struct-convention MODE'

  21135.      Set the convention used by the inferior to return 'struct's and

  21136.      'union's from functions to MODE.  Possible values of MODE are

  21137.      '"pcc"', '"reg"', and '"default"' (the default).  '"default"' or

  21138.      '"pcc"' means that 'struct's are returned on the stack, while

  21139.      '"reg"' means that a 'struct' or a 'union' whose size is 1, 2, 4,

  21140.      or 8 bytes will be returned in a register.

  21141. 

  21142. 'show struct-convention'

  21143.      Show the current setting of the convention to return 'struct's from

  21144.      functions.

  21145. 

  21146. 21.4.2.1 Intel "Memory Protection Extensions" (MPX).

  21147. ....................................................

  21148. 

  21149. Memory Protection Extension (MPX) adds the bound registers 'BND0' (1)

  21150. through 'BND3'.  Bound registers store a pair of 64-bit values which are

  21151. the lower bound and upper bound.  Bounds are effective addresses or

  21152. memory locations.  The upper bounds are architecturally represented in

  21153. 1's complement form.  A bound having lower bound = 0, and upper bound =

  21154. 0 (1's complement of all bits set) will allow access to the entire

  21155. address space.

  21156. 

  21157.    'BND0' through 'BND3' are represented in GDB as 'bnd0raw' through

  21158. 'bnd3raw'.  Pseudo registers 'bnd0' through 'bnd3' display the upper

  21159. bound performing the complement of one operation on the upper bound

  21160. value, i.e. when upper bound in 'bnd0raw' is 0 in the GDB 'bnd0' it will

  21161. be '0xfff...'.  In this sense it can also be noted that the upper bounds

  21162. are inclusive.

  21163. 

  21164.    As an example, assume that the register BND0 holds bounds for a

  21165. pointer having access allowed for the range between 0x32 and 0x71.  The

  21166. values present on bnd0raw and bnd registers are presented as follows:

  21167. 

  21168.      	bnd0raw = {0x32, 0xffffffff8e}

  21169.      	bnd0 = {lbound = 0x32, ubound = 0x71} : size 64

  21170. 

  21171.    This way the raw value can be accessed via bnd0raw...bnd3raw.  Any

  21172. change on bnd0...bnd3 or bnd0raw...bnd3raw is reflect on its

  21173. counterpart.  When the bnd0...bnd3 registers are displayed via Python,

  21174. the display includes the memory size, in bits, accessible to the

  21175. pointer.

  21176. 

  21177.    Bounds can also be stored in bounds tables, which are stored in

  21178. application memory.  These tables store bounds for pointers by

  21179. specifying the bounds pointer's value along with its bounds.  Evaluating

  21180. and changing bounds located in bound tables is therefore interesting

  21181. while investigating bugs on MPX context.  GDB provides commands for this

  21182. purpose:

  21183. 

  21184. 'show mpx bound POINTER'

  21185.      Display bounds of the given POINTER.

  21186. 

  21187. 'set mpx bound POINTER, LBOUND, UBOUND'

  21188.      Set the bounds of a pointer in the bound table.  This command takes

  21189.      three parameters: POINTER is the pointers whose bounds are to be

  21190.      changed, LBOUND and UBOUND are new values for lower and upper

  21191.      bounds respectively.

  21192. 

  21193.    When you call an inferior function on an Intel MPX enabled program,

  21194. GDB sets the inferior's bound registers to the init (disabled) state

  21195. before calling the function.  As a consequence, bounds checks for the

  21196. pointer arguments passed to the function will always pass.

  21197. 

  21198.    This is necessary because when you call an inferior function, the

  21199. program is usually in the middle of the execution of other function.

  21200. Since at that point bound registers are in an arbitrary state, not

  21201. clearing them would lead to random bound violations in the called

  21202. function.

  21203. 

  21204.    You can still examine the influence of the bound registers on the

  21205. execution of the called function by stopping the execution of the called

  21206. function at its prologue, setting bound registers, and continuing the

  21207. execution.  For example:

  21208. 

  21209.      	$ break *upper

  21210.      	Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47.

  21211.      	$ print upper (a, b, c, d, 1)

  21212.      	Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48)....

  21213.      	$ print $bnd0

  21214.      	{lbound = 0x0, ubound = ffffffff} : size -1

  21215. 

  21216.    At this last step the value of bnd0 can be changed for investigation

  21217. of bound violations caused along the execution of the call.  In order to

  21218. know how to set the bound registers or bound table for the call consult

  21219. the ABI.

  21220. 

  21221.    ---------- Footnotes ----------

  21222. 

  21223.    (1) The register named with capital letters represent the

  21224. architecture registers.

  21225. 

  21226. 

  21227. File: gdb.info,  Node: Alpha,  Next: MIPS,  Prev: i386,  Up: Architectures

  21228. 

  21229. 21.4.3 Alpha

  21230. ------------

  21231. 

  21232. See the following section.

  21233. 

  21234. 

  21235. File: gdb.info,  Node: MIPS,  Next: HPPA,  Prev: Alpha,  Up: Architectures

  21236. 

  21237. 21.4.4 MIPS

  21238. -----------

  21239. 

  21240. Alpha- and MIPS-based computers use an unusual stack frame, which

  21241. sometimes requires GDB to search backward in the object code to find the

  21242. beginning of a function.

  21243. 

  21244.    To improve response time (especially for embedded applications, where

  21245. GDB may be restricted to a slow serial line for this search) you may

  21246. want to limit the size of this search, using one of these commands:

  21247. 

  21248. 'set heuristic-fence-post LIMIT'

  21249.      Restrict GDB to examining at most LIMIT bytes in its search for the

  21250.      beginning of a function.  A value of 0 (the default) means there is

  21251.      no limit.  However, except for 0, the larger the limit the more

  21252.      bytes 'heuristic-fence-post' must search and therefore the longer

  21253.      it takes to run.  You should only need to use this command when

  21254.      debugging a stripped executable.

  21255. 

  21256. 'show heuristic-fence-post'

  21257.      Display the current limit.

  21258. 

  21259. These commands are available _only_ when GDB is configured for debugging

  21260. programs on Alpha or MIPS processors.

  21261. 

  21262.    Several MIPS-specific commands are available when debugging MIPS

  21263. programs:

  21264. 

  21265. 'set mips abi ARG'

  21266.      Tell GDB which MIPS ABI is used by the inferior.  Possible values

  21267.      of ARG are:

  21268. 

  21269.      'auto'

  21270.           The default ABI associated with the current binary (this is

  21271.           the default).

  21272.      'o32'

  21273.      'o64'

  21274.      'n32'

  21275.      'n64'

  21276.      'eabi32'

  21277.      'eabi64'

  21278. 

  21279. 'show mips abi'

  21280.      Show the MIPS ABI used by GDB to debug the inferior.

  21281. 

  21282. 'set mips compression ARG'

  21283.      Tell GDB which MIPS compressed ISA (Instruction Set Architecture)

  21284.      encoding is used by the inferior.  GDB uses this for code

  21285.      disassembly and other internal interpretation purposes.  This

  21286.      setting is only referred to when no executable has been associated

  21287.      with the debugging session or the executable does not provide

  21288.      information about the encoding it uses.  Otherwise this setting is

  21289.      automatically updated from information provided by the executable.

  21290. 

  21291.      Possible values of ARG are 'mips16' and 'micromips'.  The default

  21292.      compressed ISA encoding is 'mips16', as executables containing

  21293.      MIPS16 code frequently are not identified as such.

  21294. 

  21295.      This setting is "sticky"; that is, it retains its value across

  21296.      debugging sessions until reset either explicitly with this command

  21297.      or implicitly from an executable.

  21298. 

  21299.      The compiler and/or assembler typically add symbol table

  21300.      annotations to identify functions compiled for the MIPS16 or

  21301.      microMIPS ISAs.  If these function-scope annotations are present,

  21302.      GDB uses them in preference to the global compressed ISA encoding

  21303.      setting.

  21304. 

  21305. 'show mips compression'

  21306.      Show the MIPS compressed ISA encoding used by GDB to debug the

  21307.      inferior.

  21308. 

  21309. 'set mipsfpu'

  21310. 'show mipsfpu'

  21311.      *Note set mipsfpu: MIPS Embedded.

  21312. 

  21313. 'set mips mask-address ARG'

  21314.      This command determines whether the most-significant 32 bits of

  21315.      64-bit MIPS addresses are masked off.  The argument ARG can be

  21316.      'on', 'off', or 'auto'.  The latter is the default setting, which

  21317.      lets GDB determine the correct value.

  21318. 

  21319. 'show mips mask-address'

  21320.      Show whether the upper 32 bits of MIPS addresses are masked off or

  21321.      not.

  21322. 

  21323. 'set remote-mips64-transfers-32bit-regs'

  21324.      This command controls compatibility with 64-bit MIPS targets that

  21325.      transfer data in 32-bit quantities.  If you have an old MIPS 64

  21326.      target that transfers 32 bits for some registers, like SR and FSR,

  21327.      and 64 bits for other registers, set this option to 'on'.

  21328. 

  21329. 'show remote-mips64-transfers-32bit-regs'

  21330.      Show the current setting of compatibility with older MIPS 64

  21331.      targets.

  21332. 

  21333. 'set debug mips'

  21334.      This command turns on and off debugging messages for the

  21335.      MIPS-specific target code in GDB.

  21336. 

  21337. 'show debug mips'

  21338.      Show the current setting of MIPS debugging messages.

  21339. 

  21340. 

  21341. File: gdb.info,  Node: HPPA,  Next: PowerPC,  Prev: MIPS,  Up: Architectures

  21342. 

  21343. 21.4.5 HPPA

  21344. -----------

  21345. 

  21346. When GDB is debugging the HP PA architecture, it provides the following

  21347. special commands:

  21348. 

  21349. 'set debug hppa'

  21350.      This command determines whether HPPA architecture-specific

  21351.      debugging messages are to be displayed.

  21352. 

  21353. 'show debug hppa'

  21354.      Show whether HPPA debugging messages are displayed.

  21355. 

  21356. 'maint print unwind ADDRESS'

  21357.      This command displays the contents of the unwind table entry at the

  21358.      given ADDRESS.

  21359. 

  21360. 

  21361. File: gdb.info,  Node: PowerPC,  Next: Nios II,  Prev: HPPA,  Up: Architectures

  21362. 

  21363. 21.4.6 PowerPC

  21364. --------------

  21365. 

  21366. When GDB is debugging the PowerPC architecture, it provides a set of

  21367. pseudo-registers to enable inspection of 128-bit wide Decimal Floating

  21368. Point numbers stored in the floating point registers.  These values must

  21369. be stored in two consecutive registers, always starting at an even

  21370. register like 'f0' or 'f2'.

  21371. 

  21372.    The pseudo-registers go from '$dl0' through '$dl15', and are formed

  21373. by joining the even/odd register pairs 'f0' and 'f1' for '$dl0', 'f2'

  21374. and 'f3' for '$dl1' and so on.

  21375. 

  21376.    For POWER7 processors, GDB provides a set of pseudo-registers, the

  21377. 64-bit wide Extended Floating Point Registers ('f32' through 'f63').

  21378. 

  21379. 

  21380. File: gdb.info,  Node: Nios II,  Next: Sparc64,  Prev: PowerPC,  Up: Architectures

  21381. 

  21382. 21.4.7 Nios II

  21383. --------------

  21384. 

  21385. When GDB is debugging the Nios II architecture, it provides the

  21386. following special commands:

  21387. 

  21388. 'set debug nios2'

  21389.      This command turns on and off debugging messages for the Nios II

  21390.      target code in GDB.

  21391. 

  21392. 'show debug nios2'

  21393.      Show the current setting of Nios II debugging messages.

  21394. 

  21395. 

  21396. File: gdb.info,  Node: Sparc64,  Next: S12Z,  Prev: Nios II,  Up: Architectures

  21397. 

  21398. 21.4.8 Sparc64

  21399. --------------

  21400. 

  21401. 21.4.8.1 ADI Support

  21402. ....................

  21403. 

  21404. The M7 processor supports an Application Data Integrity (ADI) feature

  21405. that detects invalid data accesses.  When software allocates memory and

  21406. enables ADI on the allocated memory, it chooses a 4-bit version number,

  21407. sets the version in the upper 4 bits of the 64-bit pointer to that data,

  21408. and stores the 4-bit version in every cacheline of that data.  Hardware

  21409. saves the latter in spare bits in the cache and memory hierarchy.  On

  21410. each load and store, the processor compares the upper 4 VA (virtual

  21411. address) bits to the cacheline's version.  If there is a mismatch, the

  21412. processor generates a version mismatch trap which can be either precise

  21413. or disrupting.  The trap is an error condition which the kernel delivers

  21414. to the process as a SIGSEGV signal.

  21415. 

  21416.    Note that only 64-bit applications can use ADI and need to be built

  21417. with ADI-enabled.

  21418. 

  21419.    Values of the ADI version tags, which are in granularity of a

  21420. cacheline (64 bytes), can be viewed or modified.

  21421. 

  21422. 'adi (examine | x) [ / N ] ADDR'

  21423. 

  21424.      The 'adi examine' command displays the value of one ADI version tag

  21425.      per cacheline.

  21426. 

  21427.      N is a decimal integer specifying the number in bytes; the default

  21428.      is 1.  It specifies how much ADI version information, at the ratio

  21429.      of 1:ADI block size, to display.

  21430. 

  21431.      ADDR is the address in user address space where you want GDB to

  21432.      begin displaying the ADI version tags.

  21433. 

  21434.      Below is an example of displaying ADI versions of variable

  21435.      "shmaddr".

  21436. 

  21437.           (gdb) adi x/100 shmaddr

  21438.              0xfff800010002c000:     0 0

  21439. 

  21440. 'adi (assign | a) [ / N ] ADDR = TAG'

  21441. 

  21442.      The 'adi assign' command is used to assign new ADI version tag to

  21443.      an address.

  21444. 

  21445.      N is a decimal integer specifying the number in bytes; the default

  21446.      is 1.  It specifies how much ADI version information, at the ratio

  21447.      of 1:ADI block size, to modify.

  21448. 

  21449.      ADDR is the address in user address space where you want GDB to

  21450.      begin modifying the ADI version tags.

  21451. 

  21452.      TAG is the new ADI version tag.

  21453. 

  21454.      For example, do the following to modify then verify ADI versions of

  21455.      variable "shmaddr":

  21456. 

  21457.           (gdb) adi a/100 shmaddr = 7

  21458.           (gdb) adi x/100 shmaddr

  21459.              0xfff800010002c000:     7 7

  21460. 

  21461. 

  21462. File: gdb.info,  Node: S12Z,  Prev: Sparc64,  Up: Architectures

  21463. 

  21464. 21.4.9 S12Z

  21465. -----------

  21466. 

  21467. When GDB is debugging the S12Z architecture, it provides the following

  21468. special command:

  21469. 

  21470. 'maint info bdccsr'

  21471.      This command displays the current value of the microprocessor's

  21472.      BDCCSR register.

  21473. 

  21474. 

  21475. File: gdb.info,  Node: Controlling GDB,  Next: Extending GDB,  Prev: Configurations,  Up: Top

  21476. 

  21477. 22 Controlling GDB

  21478. ******************

  21479. 

  21480. You can alter the way GDB interacts with you by using the 'set' command.

  21481. For commands controlling how GDB displays data, see *note Print

  21482. Settings: Print Settings.  Other settings are described here.

  21483. 

  21484. * Menu:

  21485. 

  21486. * Prompt::                      Prompt

  21487. * Editing::                     Command editing

  21488. * Command History::             Command history

  21489. * Screen Size::                 Screen size

  21490. * Output Styling::              Output styling

  21491. * Numbers::                     Numbers

  21492. * ABI::                         Configuring the current ABI

  21493. * Auto-loading::                Automatically loading associated files

  21494. * Messages/Warnings::           Optional warnings and messages

  21495. * Debugging Output::            Optional messages about internal happenings

  21496. * Other Misc Settings::         Other Miscellaneous Settings

  21497. 

  21498. 

  21499. File: gdb.info,  Node: Prompt,  Next: Editing,  Up: Controlling GDB

  21500. 

  21501. 22.1 Prompt

  21502. ===========

  21503. 

  21504. GDB indicates its readiness to read a command by printing a string

  21505. called the "prompt".  This string is normally '(gdb)'.  You can change

  21506. the prompt string with the 'set prompt' command.  For instance, when

  21507. debugging GDB with GDB, it is useful to change the prompt in one of the

  21508. GDB sessions so that you can always tell which one you are talking to.

  21509. 

  21510.    _Note:_ 'set prompt' does not add a space for you after the prompt

  21511. you set.  This allows you to set a prompt which ends in a space or a

  21512. prompt that does not.

  21513. 

  21514. 'set prompt NEWPROMPT'

  21515.      Directs GDB to use NEWPROMPT as its prompt string henceforth.

  21516. 

  21517. 'show prompt'

  21518.      Prints a line of the form: 'Gdb's prompt is: YOUR-PROMPT'

  21519. 

  21520.    Versions of GDB that ship with Python scripting enabled have prompt

  21521. extensions.  The commands for interacting with these extensions are:

  21522. 

  21523. 'set extended-prompt PROMPT'

  21524.      Set an extended prompt that allows for substitutions.  *Note

  21525.      gdb.prompt::, for a list of escape sequences that can be used for

  21526.      substitution.  Any escape sequences specified as part of the prompt

  21527.      string are replaced with the corresponding strings each time the

  21528.      prompt is displayed.

  21529. 

  21530.      For example:

  21531. 

  21532.           set extended-prompt Current working directory: \w (gdb)

  21533. 

  21534.      Note that when an extended-prompt is set, it takes control of the

  21535.      PROMPT_HOOK hook.  *Note prompt_hook::, for further information.

  21536. 

  21537. 'show extended-prompt'

  21538.      Prints the extended prompt.  Any escape sequences specified as part

  21539.      of the prompt string with 'set extended-prompt', are replaced with

  21540.      the corresponding strings each time the prompt is displayed.

  21541. 

  21542. 

  21543. File: gdb.info,  Node: Editing,  Next: Command History,  Prev: Prompt,  Up: Controlling GDB

  21544. 

  21545. 22.2 Command Editing

  21546. ====================

  21547. 

  21548. GDB reads its input commands via the "Readline" interface.  This GNU

  21549. library provides consistent behavior for programs which provide a

  21550. command line interface to the user.  Advantages are GNU Emacs-style or

  21551. "vi"-style inline editing of commands, 'csh'-like history substitution,

  21552. and a storage and recall of command history across debugging sessions.

  21553. 

  21554.    You may control the behavior of command line editing in GDB with the

  21555. command 'set'.

  21556. 

  21557. 'set editing'

  21558. 'set editing on'

  21559.      Enable command line editing (enabled by default).

  21560. 

  21561. 'set editing off'

  21562.      Disable command line editing.

  21563. 

  21564. 'show editing'

  21565.      Show whether command line editing is enabled.

  21566. 

  21567.    *Note Command Line Editing::, for more details about the Readline

  21568. interface.  Users unfamiliar with GNU Emacs or 'vi' are encouraged to

  21569. read that chapter.

  21570. 

  21571.    GDB sets the Readline application name to 'gdb'.  This is useful for

  21572. conditions in '.inputrc'.

  21573. 

  21574.    GDB defines a bindable Readline command, 'operate-and-get-next'.

  21575. This is bound to 'C-o' by default.  This command accepts the current

  21576. line for execution and fetches the next line relative to the current

  21577. line from the history for editing.  Any argument is ignored.

  21578. 

  21579. 

  21580. File: gdb.info,  Node: Command History,  Next: Screen Size,  Prev: Editing,  Up: Controlling GDB

  21581. 

  21582. 22.3 Command History

  21583. ====================

  21584. 

  21585. GDB can keep track of the commands you type during your debugging

  21586. sessions, so that you can be certain of precisely what happened.  Use

  21587. these commands to manage the GDB command history facility.

  21588. 

  21589.    GDB uses the GNU History library, a part of the Readline package, to

  21590. provide the history facility.  *Note Using History Interactively::, for

  21591. the detailed description of the History library.

  21592. 

  21593.    To issue a command to GDB without affecting certain aspects of the

  21594. state which is seen by users, prefix it with 'server ' (*note Server

  21595. Prefix::).  This means that this command will not affect the command

  21596. history, nor will it affect GDB's notion of which command to repeat if

  21597. <RET> is pressed on a line by itself.

  21598. 

  21599.    The server prefix does not affect the recording of values into the

  21600. value history; to print a value without recording it into the value

  21601. history, use the 'output' command instead of the 'print' command.

  21602. 

  21603.    Here is the description of GDB commands related to command history.

  21604. 

  21605. 'set history filename [FNAME]'

  21606.      Set the name of the GDB command history file to FNAME.  This is the

  21607.      file where GDB reads an initial command history list, and where it

  21608.      writes the command history from this session when it exits.  You

  21609.      can access this list through history expansion or through the

  21610.      history command editing characters listed below.  This file

  21611.      defaults to the value of the environment variable 'GDBHISTFILE', or

  21612.      to './.gdb_history' ('./_gdb_history' on MS-DOS) if this variable

  21613.      is not set.

  21614. 

  21615.      The 'GDBHISTFILE' environment variable is read after processing any

  21616.      GDB initialization files (*note Startup::) and after processing any

  21617.      commands passed using command line options (for example, '-ex').

  21618. 

  21619.      If the FNAME argument is not given, or if the 'GDBHISTFILE' is the

  21620.      empty string then GDB will neither try to load an existing history

  21621.      file, nor will it try to save the history on exit.

  21622. 

  21623. 'set history save'

  21624. 'set history save on'

  21625.      Record command history in a file, whose name may be specified with

  21626.      the 'set history filename' command.  By default, this option is

  21627.      disabled.  The command history will be recorded when GDB exits.  If

  21628.      'set history filename' is set to the empty string then history

  21629.      saving is disabled, even when 'set history save' is 'on'.

  21630. 

  21631. 'set history save off'

  21632.      Don't record the command history into the file specified by 'set

  21633.      history filename' when GDB exits.

  21634. 

  21635. 'set history size SIZE'

  21636. 'set history size unlimited'

  21637.      Set the number of commands which GDB keeps in its history list.

  21638.      This defaults to the value of the environment variable

  21639.      'GDBHISTSIZE', or to 256 if this variable is not set.  Non-numeric

  21640.      values of 'GDBHISTSIZE' are ignored.  If SIZE is 'unlimited' or if

  21641.      'GDBHISTSIZE' is either a negative number or the empty string, then

  21642.      the number of commands GDB keeps in the history list is unlimited.

  21643. 

  21644.      The 'GDBHISTSIZE' environment variable is read after processing any

  21645.      GDB initialization files (*note Startup::) and after processing any

  21646.      commands passed using command line options (for example, '-ex').

  21647. 

  21648. 'set history remove-duplicates COUNT'

  21649. 'set history remove-duplicates unlimited'

  21650.      Control the removal of duplicate history entries in the command

  21651.      history list.  If COUNT is non-zero, GDB will look back at the last

  21652.      COUNT history entries and remove the first entry that is a

  21653.      duplicate of the current entry being added to the command history

  21654.      list.  If COUNT is 'unlimited' then this lookbehind is unbounded.

  21655.      If COUNT is 0, then removal of duplicate history entries is

  21656.      disabled.

  21657. 

  21658.      Only history entries added during the current session are

  21659.      considered for removal.  This option is set to 0 by default.

  21660. 

  21661.    History expansion assigns special meaning to the character '!'.

  21662. *Note Event Designators::, for more details.

  21663. 

  21664.    Since '!' is also the logical not operator in C, history expansion is

  21665. off by default.  If you decide to enable history expansion with the 'set

  21666. history expansion on' command, you may sometimes need to follow '!'

  21667. (when it is used as logical not, in an expression) with a space or a tab

  21668. to prevent it from being expanded.  The readline history facilities do

  21669. not attempt substitution on the strings '!=' and '!(', even when history

  21670. expansion is enabled.

  21671. 

  21672.    The commands to control history expansion are:

  21673. 

  21674. 'set history expansion on'

  21675. 'set history expansion'

  21676.      Enable history expansion.  History expansion is off by default.

  21677. 

  21678. 'set history expansion off'

  21679.      Disable history expansion.

  21680. 

  21681. 'show history'

  21682. 'show history filename'

  21683. 'show history save'

  21684. 'show history size'

  21685. 'show history expansion'

  21686.      These commands display the state of the GDB history parameters.

  21687.      'show history' by itself displays all four states.

  21688. 

  21689. 'show commands'

  21690.      Display the last ten commands in the command history.

  21691. 

  21692. 'show commands N'

  21693.      Print ten commands centered on command number N.

  21694. 

  21695. 'show commands +'

  21696.      Print ten commands just after the commands last printed.

  21697. 

  21698. 

  21699. File: gdb.info,  Node: Screen Size,  Next: Output Styling,  Prev: Command History,  Up: Controlling GDB

  21700. 

  21701. 22.4 Screen Size

  21702. ================

  21703. 

  21704. Certain commands to GDB may produce large amounts of information output

  21705. to the screen.  To help you read all of it, GDB pauses and asks you for

  21706. input at the end of each page of output.  Type <RET> when you want to

  21707. see one more page of output, 'q' to discard the remaining output, or 'c'

  21708. to continue without paging for the rest of the current command.  Also,

  21709. the screen width setting determines when to wrap lines of output.

  21710. Depending on what is being printed, GDB tries to break the line at a

  21711. readable place, rather than simply letting it overflow onto the

  21712. following line.

  21713. 

  21714.    Normally GDB knows the size of the screen from the terminal driver

  21715. software.  For example, on Unix GDB uses the termcap data base together

  21716. with the value of the 'TERM' environment variable and the 'stty rows'

  21717. and 'stty cols' settings.  If this is not correct, you can override it

  21718. with the 'set height' and 'set width' commands:

  21719. 

  21720. 'set height LPP'

  21721. 'set height unlimited'

  21722. 'show height'

  21723. 'set width CPL'

  21724. 'set width unlimited'

  21725. 'show width'

  21726.      These 'set' commands specify a screen height of LPP lines and a

  21727.      screen width of CPL characters.  The associated 'show' commands

  21728.      display the current settings.

  21729. 

  21730.      If you specify a height of either 'unlimited' or zero lines, GDB

  21731.      does not pause during output no matter how long the output is.

  21732.      This is useful if output is to a file or to an editor buffer.

  21733. 

  21734.      Likewise, you can specify 'set width unlimited' or 'set width 0' to

  21735.      prevent GDB from wrapping its output.

  21736. 

  21737. 'set pagination on'

  21738. 'set pagination off'

  21739.      Turn the output pagination on or off; the default is on.  Turning

  21740.      pagination off is the alternative to 'set height unlimited'.  Note

  21741.      that running GDB with the '--batch' option (*note -batch: Mode

  21742.      Options.) also automatically disables pagination.

  21743. 

  21744. 'show pagination'

  21745.      Show the current pagination mode.

  21746. 

  21747. 

  21748. File: gdb.info,  Node: Output Styling,  Next: Numbers,  Prev: Screen Size,  Up: Controlling GDB

  21749. 

  21750. 22.5 Output Styling

  21751. ===================

  21752. 

  21753. GDB can style its output on a capable terminal.  This is enabled by

  21754. default on most systems, but disabled by default when in batch mode

  21755. (*note Mode Options::).  Various style settings are available; and

  21756. styles can also be disabled entirely.

  21757. 

  21758. 'set style enabled 'on|off''

  21759.      Enable or disable all styling.  The default is host-dependent, with

  21760.      most hosts defaulting to 'on'.

  21761. 

  21762. 'show style enabled'

  21763.      Show the current state of styling.

  21764. 

  21765. 'set style sources 'on|off''

  21766.      Enable or disable source code styling.  This affects whether source

  21767.      code, such as the output of the 'list' command, is styled.  Note

  21768.      that source styling only works if styling in general is enabled,

  21769.      and if GDB was linked with the GNU Source Highlight library.  The

  21770.      default is 'on'.

  21771. 

  21772. 'show style sources'

  21773.      Show the current state of source code styling.

  21774. 

  21775.    Subcommands of 'set style' control specific forms of styling.  These

  21776. subcommands all follow the same pattern: each style-able object can be

  21777. styled with a foreground color, a background color, and an intensity.

  21778. 

  21779.    For example, the style of file names can be controlled using the 'set

  21780. style filename' group of commands:

  21781. 

  21782. 'set style filename background COLOR'

  21783.      Set the background to COLOR.  Valid colors are 'none' (meaning the

  21784.      terminal's default color), 'black', 'red', 'green', 'yellow',

  21785.      'blue', 'magenta', 'cyan', and'white'.

  21786. 

  21787. 'set style filename foreground COLOR'

  21788.      Set the foreground to COLOR.  Valid colors are 'none' (meaning the

  21789.      terminal's default color), 'black', 'red', 'green', 'yellow',

  21790.      'blue', 'magenta', 'cyan', and'white'.

  21791. 

  21792. 'set style filename intensity VALUE'

  21793.      Set the intensity to VALUE.  Valid intensities are 'normal' (the

  21794.      default), 'bold', and 'dim'.

  21795. 

  21796.    The 'show style' command and its subcommands are styling a style name

  21797. in their output using its own style.  So, use 'show style' to see the

  21798. complete list of styles, their characteristics and the visual aspect of

  21799. each style.

  21800. 

  21801.    The style-able objects are:

  21802. 'filename'

  21803.      Control the styling of file names.  By default, this style's

  21804.      foreground color is green.

  21805. 

  21806. 'function'

  21807.      Control the styling of function names.  These are managed with the

  21808.      'set style function' family of commands.  By default, this style's

  21809.      foreground color is yellow.

  21810. 

  21811. 'variable'

  21812.      Control the styling of variable names.  These are managed with the

  21813.      'set style variable' family of commands.  By default, this style's

  21814.      foreground color is cyan.

  21815. 

  21816. 'address'

  21817.      Control the styling of addresses.  These are managed with the 'set

  21818.      style address' family of commands.  By default, this style's

  21819.      foreground color is blue.

  21820. 

  21821. 'title'

  21822.      Control the styling of titles.  These are managed with the 'set

  21823.      style title' family of commands.  By default, this style's

  21824.      intensity is bold.  Commands are using the title style to improve

  21825.      the readability of large output.  For example, the commands

  21826.      'apropos' and 'help' are using the title style for the command

  21827.      names.

  21828. 

  21829. 'highlight'

  21830.      Control the styling of highlightings.  These are managed with the

  21831.      'set style highlight' family of commands.  By default, this style's

  21832.      foreground color is red.  Commands are using the highlight style to

  21833.      draw the user attention to some specific parts of their output.

  21834.      For example, the command 'apropos -v REGEXP' uses the highlight

  21835.      style to mark the documentation parts matching REGEXP.

  21836. 

  21837. 'tui-border'

  21838.      Control the styling of the TUI border.  Note that, unlike other

  21839.      styling options, only the color of the border can be controlled via

  21840.      'set style'.  This was done for compatibility reasons, as TUI

  21841.      controls to set the border's intensity predated the addition of

  21842.      general styling to GDB.  *Note TUI Configuration::.

  21843. 

  21844. 'tui-active-border'

  21845.      Control the styling of the active TUI border; that is, the TUI

  21846.      window that has the focus.

  21847. 

  21848. 

  21849. File: gdb.info,  Node: Numbers,  Next: ABI,  Prev: Output Styling,  Up: Controlling GDB

  21850. 

  21851. 22.6 Numbers

  21852. ============

  21853. 

  21854. You can always enter numbers in octal, decimal, or hexadecimal in GDB by

  21855. the usual conventions: octal numbers begin with '0', decimal numbers end

  21856. with '.', and hexadecimal numbers begin with '0x'.  Numbers that neither

  21857. begin with '0' or '0x', nor end with a '.' are, by default, entered in

  21858. base 10; likewise, the default display for numbers--when no particular

  21859. format is specified--is base 10.  You can change the default base for

  21860. both input and output with the commands described below.

  21861. 

  21862. 'set input-radix BASE'

  21863.      Set the default base for numeric input.  Supported choices for BASE

  21864.      are decimal 8, 10, or 16.  The base must itself be specified either

  21865.      unambiguously or using the current input radix; for example, any of

  21866. 

  21867.           set input-radix 012

  21868.           set input-radix 10.

  21869.           set input-radix 0xa

  21870. 

  21871.      sets the input base to decimal.  On the other hand, 'set

  21872.      input-radix 10' leaves the input radix unchanged, no matter what it

  21873.      was, since '10', being without any leading or trailing signs of its

  21874.      base, is interpreted in the current radix.  Thus, if the current

  21875.      radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which

  21876.      doesn't change the radix.

  21877. 

  21878. 'set output-radix BASE'

  21879.      Set the default base for numeric display.  Supported choices for

  21880.      BASE are decimal 8, 10, or 16.  The base must itself be specified

  21881.      either unambiguously or using the current input radix.

  21882. 

  21883. 'show input-radix'

  21884.      Display the current default base for numeric input.

  21885. 

  21886. 'show output-radix'

  21887.      Display the current default base for numeric display.

  21888. 

  21889. 'set radix [BASE]'

  21890. 'show radix'

  21891.      These commands set and show the default base for both input and

  21892.      output of numbers.  'set radix' sets the radix of input and output

  21893.      to the same base; without an argument, it resets the radix back to

  21894.      its default value of 10.

  21895. 

  21896. 

  21897. File: gdb.info,  Node: ABI,  Next: Auto-loading,  Prev: Numbers,  Up: Controlling GDB

  21898. 

  21899. 22.7 Configuring the Current ABI

  21900. ================================

  21901. 

  21902. GDB can determine the "ABI" (Application Binary Interface) of your

  21903. application automatically.  However, sometimes you need to override its

  21904. conclusions.  Use these commands to manage GDB's view of the current

  21905. ABI.

  21906. 

  21907.    One GDB configuration can debug binaries for multiple operating

  21908. system targets, either via remote debugging or native emulation.  GDB

  21909. will autodetect the "OS ABI" (Operating System ABI) in use, but you can

  21910. override its conclusion using the 'set osabi' command.  One example

  21911. where this is useful is in debugging of binaries which use an alternate

  21912. C library (e.g. UCLIBC for GNU/Linux) which does not have the same

  21913. identifying marks that the standard C library for your platform

  21914. provides.

  21915. 

  21916.    When GDB is debugging the AArch64 architecture, it provides a

  21917. "Newlib" OS ABI. This is useful for handling 'setjmp' and 'longjmp' when

  21918. debugging binaries that use the NEWLIB C library.  The "Newlib" OS ABI

  21919. can be selected by 'set osabi Newlib'.

  21920. 

  21921. 'show osabi'

  21922.      Show the OS ABI currently in use.

  21923. 

  21924. 'set osabi'

  21925.      With no argument, show the list of registered available OS ABI's.

  21926. 

  21927. 'set osabi ABI'

  21928.      Set the current OS ABI to ABI.

  21929. 

  21930.    Generally, the way that an argument of type 'float' is passed to a

  21931. function depends on whether the function is prototyped.  For a

  21932. prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed

  21933. unchanged, according to the architecture's convention for 'float'.  For

  21934. unprototyped (i.e. K&R style) functions, 'float' arguments are first

  21935. promoted to type 'double' and then passed.

  21936. 

  21937.    Unfortunately, some forms of debug information do not reliably

  21938. indicate whether a function is prototyped.  If GDB calls a function that

  21939. is not marked as prototyped, it consults 'set coerce-float-to-double'.

  21940. 

  21941. 'set coerce-float-to-double'

  21942. 'set coerce-float-to-double on'

  21943.      Arguments of type 'float' will be promoted to 'double' when passed

  21944.      to an unprototyped function.  This is the default setting.

  21945. 

  21946. 'set coerce-float-to-double off'

  21947.      Arguments of type 'float' will be passed directly to unprototyped

  21948.      functions.

  21949. 

  21950. 'show coerce-float-to-double'

  21951.      Show the current setting of promoting 'float' to 'double'.

  21952. 

  21953.    GDB needs to know the ABI used for your program's C++ objects.  The

  21954. correct C++ ABI depends on which C++ compiler was used to build your

  21955. application.  GDB only fully supports programs with a single C++ ABI; if

  21956. your program contains code using multiple C++ ABI's or if GDB can not

  21957. identify your program's ABI correctly, you can tell GDB which ABI to

  21958. use.  Currently supported ABI's include "gnu-v2", for 'g++' versions

  21959. before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for

  21960. the HP ANSI C++ compiler.  Other C++ compilers may use the "gnu-v2" or

  21961. "gnu-v3" ABI's as well.  The default setting is "auto".

  21962. 

  21963. 'show cp-abi'

  21964.      Show the C++ ABI currently in use.

  21965. 

  21966. 'set cp-abi'

  21967.      With no argument, show the list of supported C++ ABI's.

  21968. 

  21969. 'set cp-abi ABI'

  21970. 'set cp-abi auto'

  21971.      Set the current C++ ABI to ABI, or return to automatic detection.

  21972. 

  21973. 

  21974. File: gdb.info,  Node: Auto-loading,  Next: Messages/Warnings,  Prev: ABI,  Up: Controlling GDB

  21975. 

  21976. 22.8 Automatically loading associated files

  21977. ===========================================

  21978. 

  21979. GDB sometimes reads files with commands and settings automatically,

  21980. without being explicitly told so by the user.  We call this feature

  21981. "auto-loading".  While auto-loading is useful for automatically adapting

  21982. GDB to the needs of your project, it can sometimes produce unexpected

  21983. results or introduce security risks (e.g., if the file comes from

  21984. untrusted sources).

  21985. 

  21986. * Menu:

  21987. 

  21988. * Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit'

  21989. * libthread_db.so.1 file::             'set/show/info auto-load libthread-db'

  21990. 

  21991. * Auto-loading safe path::             'set/show/info auto-load safe-path'

  21992. * Auto-loading verbose mode::          'set/show debug auto-load'

  21993. 

  21994.    There are various kinds of files GDB can automatically load.  In

  21995. addition to these files, GDB supports auto-loading code written in

  21996. various extension languages.  *Note Auto-loading extensions::.

  21997. 

  21998.    Note that loading of these associated files (including the local

  21999. '.gdbinit' file) requires accordingly configured 'auto-load safe-path'

  22000. (*note Auto-loading safe path::).

  22001. 

  22002.    For these reasons, GDB includes commands and options to let you

  22003. control when to auto-load files and which files should be auto-loaded.

  22004. 

  22005. 'set auto-load off'

  22006.      Globally disable loading of all auto-loaded files.  You may want to

  22007.      use this command with the '-iex' option (*note Option

  22008.      -init-eval-command::) such as:

  22009.           $ gdb -iex "set auto-load off" untrusted-executable corefile

  22010. 

  22011.      Be aware that system init file (*note System-wide configuration::)

  22012.      and init files from your home directory (*note Home Directory Init

  22013.      File::) still get read (as they come from generally trusted

  22014.      directories).  To prevent GDB from auto-loading even those init

  22015.      files, use the '-nx' option (*note Mode Options::), in addition to

  22016.      'set auto-load no'.

  22017. 

  22018. 'show auto-load'

  22019.      Show whether auto-loading of each specific 'auto-load' file(s) is

  22020.      enabled or disabled.

  22021. 

  22022.           (gdb) show auto-load

  22023.           gdb-scripts:  Auto-loading of canned sequences of commands scripts is on.

  22024.           libthread-db:  Auto-loading of inferior specific libthread_db is on.

  22025.           local-gdbinit:  Auto-loading of .gdbinit script from current directory

  22026.                           is on.

  22027.           python-scripts:  Auto-loading of Python scripts is on.

  22028.           safe-path:  List of directories from which it is safe to auto-load files

  22029.                       is $debugdir:$datadir/auto-load.

  22030.           scripts-directory:  List of directories from which to load auto-loaded scripts

  22031.                               is $debugdir:$datadir/auto-load.

  22032. 

  22033. 'info auto-load'

  22034.      Print whether each specific 'auto-load' file(s) have been

  22035.      auto-loaded or not.

  22036. 

  22037.           (gdb) info auto-load

  22038.           gdb-scripts:

  22039.           Loaded  Script

  22040.           Yes     /home/user/gdb/gdb-gdb.gdb

  22041.           libthread-db:  No auto-loaded libthread-db.

  22042.           local-gdbinit:  Local .gdbinit file "/home/user/gdb/.gdbinit" has been

  22043.                           loaded.

  22044.           python-scripts:

  22045.           Loaded  Script

  22046.           Yes     /home/user/gdb/gdb-gdb.py

  22047. 

  22048.    These are GDB control commands for the auto-loading:

  22049. 

  22050. *Note set auto-load off::.           Disable auto-loading globally.

  22051. *Note show auto-load::.              Show setting of all kinds of

  22052.                                      files.

  22053. *Note info auto-load::.              Show state of all kinds of files.

  22054. *Note set auto-load gdb-scripts::.   Control for GDB command scripts.

  22055. *Note show auto-load gdb-scripts::.  Show setting of GDB command

  22056.                                      scripts.

  22057. *Note info auto-load gdb-scripts::.  Show state of GDB command scripts.

  22058. *Note set auto-load python-scripts::.Control for GDB Python scripts.

  22059. *Note show auto-load python-scripts::.Show setting of GDB Python

  22060.                                      scripts.

  22061. *Note info auto-load python-scripts::.Show state of GDB Python scripts.

  22062. *Note set auto-load guile-scripts::. Control for GDB Guile scripts.

  22063. *Note show auto-load guile-scripts::.Show setting of GDB Guile scripts.

  22064. *Note info auto-load guile-scripts::.Show state of GDB Guile scripts.

  22065. *Note set auto-load scripts-directory::.Control for GDB auto-loaded

  22066.                                      scripts location.

  22067. *Note show auto-load scripts-directory::.Show GDB auto-loaded scripts

  22068.                                      location.

  22069. *Note add-auto-load-scripts-directory::.Add directory for auto-loaded

  22070.                                      scripts location list.

  22071. *Note set auto-load local-gdbinit::. Control for init file in the

  22072.                                      current directory.

  22073. *Note show auto-load local-gdbinit::.Show setting of init file in the

  22074.                                      current directory.

  22075. *Note info auto-load local-gdbinit::.Show state of init file in the

  22076.                                      current directory.

  22077. *Note set auto-load libthread-db::.  Control for thread debugging

  22078.                                      library.

  22079. *Note show auto-load libthread-db::. Show setting of thread debugging

  22080.                                      library.

  22081. *Note info auto-load libthread-db::. Show state of thread debugging

  22082.                                      library.

  22083. *Note set auto-load safe-path::.     Control directories trusted for

  22084.                                      automatic loading.

  22085. *Note show auto-load safe-path::.    Show directories trusted for

  22086.                                      automatic loading.

  22087. *Note add-auto-load-safe-path::.     Add directory trusted for

  22088.                                      automatic loading.

  22089. 

  22090. 

  22091. File: gdb.info,  Node: Init File in the Current Directory,  Next: libthread_db.so.1 file,  Up: Auto-loading

  22092. 

  22093. 22.8.1 Automatically loading init file in the current directory

  22094. ---------------------------------------------------------------

  22095. 

  22096. By default, GDB reads and executes the canned sequences of commands from

  22097. init file (if any) in the current working directory, see *note Init File

  22098. in the Current Directory during Startup::.

  22099. 

  22100.    Note that loading of this local '.gdbinit' file also requires

  22101. accordingly configured 'auto-load safe-path' (*note Auto-loading safe

  22102. path::).

  22103. 

  22104. 'set auto-load local-gdbinit [on|off]'

  22105.      Enable or disable the auto-loading of canned sequences of commands

  22106.      (*note Sequences::) found in init file in the current directory.

  22107. 

  22108. 'show auto-load local-gdbinit'

  22109.      Show whether auto-loading of canned sequences of commands from init

  22110.      file in the current directory is enabled or disabled.

  22111. 

  22112. 'info auto-load local-gdbinit'

  22113.      Print whether canned sequences of commands from init file in the

  22114.      current directory have been auto-loaded.

  22115. 

  22116. 

  22117. File: gdb.info,  Node: libthread_db.so.1 file,  Next: Auto-loading safe path,  Prev: Init File in the Current Directory,  Up: Auto-loading

  22118. 

  22119. 22.8.2 Automatically loading thread debugging library

  22120. -----------------------------------------------------

  22121. 

  22122. This feature is currently present only on GNU/Linux native hosts.

  22123. 

  22124.    GDB reads in some cases thread debugging library from places specific

  22125. to the inferior (*note set libthread-db-search-path::).

  22126. 

  22127.    The special 'libthread-db-search-path' entry '$sdir' is processed

  22128. without checking this 'set auto-load libthread-db' switch as system

  22129. libraries have to be trusted in general.  In all other cases of

  22130. 'libthread-db-search-path' entries GDB checks first if 'set auto-load

  22131. libthread-db' is enabled before trying to open such thread debugging

  22132. library.

  22133. 

  22134.    Note that loading of this debugging library also requires accordingly

  22135. configured 'auto-load safe-path' (*note Auto-loading safe path::).

  22136. 

  22137. 'set auto-load libthread-db [on|off]'

  22138.      Enable or disable the auto-loading of inferior specific thread

  22139.      debugging library.

  22140. 

  22141. 'show auto-load libthread-db'

  22142.      Show whether auto-loading of inferior specific thread debugging

  22143.      library is enabled or disabled.

  22144. 

  22145. 'info auto-load libthread-db'

  22146.      Print the list of all loaded inferior specific thread debugging

  22147.      libraries and for each such library print list of inferior PIDs

  22148.      using it.

  22149. 

  22150. 

  22151. File: gdb.info,  Node: Auto-loading safe path,  Next: Auto-loading verbose mode,  Prev: libthread_db.so.1 file,  Up: Auto-loading

  22152. 

  22153. 22.8.3 Security restriction for auto-loading

  22154. --------------------------------------------

  22155. 

  22156. As the files of inferior can come from untrusted source (such as

  22157. submitted by an application user) GDB does not always load any files

  22158. automatically.  GDB provides the 'set auto-load safe-path' setting to

  22159. list directories trusted for loading files not explicitly requested by

  22160. user.  Each directory can also be a shell wildcard pattern.

  22161. 

  22162.    If the path is not set properly you will see a warning and the file

  22163. will not get loaded:

  22164. 

  22165.      $ ./gdb -q ./gdb

  22166.      Reading symbols from /home/user/gdb/gdb...

  22167.      warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been

  22168.               declined by your `auto-load safe-path' set

  22169.               to "$debugdir:$datadir/auto-load".

  22170.      warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been

  22171.               declined by your `auto-load safe-path' set

  22172.               to "$debugdir:$datadir/auto-load".

  22173. 

  22174. To instruct GDB to go ahead and use the init files anyway, invoke GDB

  22175. like this:

  22176. 

  22177.      $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb

  22178. 

  22179.    The list of trusted directories is controlled by the following

  22180. commands:

  22181. 

  22182. 'set auto-load safe-path [DIRECTORIES]'

  22183.      Set the list of directories (and their subdirectories) trusted for

  22184.      automatic loading and execution of scripts.  You can also enter a

  22185.      specific trusted file.  Each directory can also be a shell wildcard

  22186.      pattern; wildcards do not match directory separator - see

  22187.      'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch:

  22188.      (libc)Wildcard Matching.).  If you omit DIRECTORIES, 'auto-load

  22189.      safe-path' will be reset to its default value as specified during

  22190.      GDB compilation.

  22191. 

  22192.      The list of directories uses path separator (':' on GNU and Unix

  22193.      systems, ';' on MS-Windows and MS-DOS) to separate directories,

  22194.      similarly to the 'PATH' environment variable.

  22195. 

  22196. 'show auto-load safe-path'

  22197.      Show the list of directories trusted for automatic loading and

  22198.      execution of scripts.

  22199. 

  22200. 'add-auto-load-safe-path'

  22201.      Add an entry (or list of entries) to the list of directories

  22202.      trusted for automatic loading and execution of scripts.  Multiple

  22203.      entries may be delimited by the host platform path separator in

  22204.      use.

  22205. 

  22206.    This variable defaults to what '--with-auto-load-dir' has been

  22207. configured to (*note with-auto-load-dir::).  '$debugdir' and '$datadir'

  22208. substitution applies the same as for *note set auto-load

  22209. scripts-directory::.  The default 'set auto-load safe-path' value can be

  22210. also overriden by GDB configuration option '--with-auto-load-safe-path'.

  22211. 

  22212.    Setting this variable to '/' disables this security protection,

  22213. corresponding GDB configuration option is

  22214. '--without-auto-load-safe-path'.  This variable is supposed to be set to

  22215. the system directories writable by the system superuser only.  Users can

  22216. add their source directories in init files in their home directories

  22217. (*note Home Directory Init File::).  See also deprecated init file in

  22218. the current directory (*note Init File in the Current Directory during

  22219. Startup::).

  22220. 

  22221.    To force GDB to load the files it declined to load in the previous

  22222. example, you could use one of the following ways:

  22223. 

  22224. '~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb'

  22225.      Specify this trusted directory (or a file) as additional component

  22226.      of the list.  You have to specify also any existing directories

  22227.      displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in

  22228.      this example).

  22229. 

  22230. 'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...'

  22231.      Specify this directory as in the previous case but just for a

  22232.      single GDB session.

  22233. 

  22234. 'gdb -iex "set auto-load safe-path /" ...'

  22235.      Disable auto-loading safety for a single GDB session.  This assumes

  22236.      all the files you debug during this GDB session will come from

  22237.      trusted sources.

  22238. 

  22239. './configure --without-auto-load-safe-path'

  22240.      During compilation of GDB you may disable any auto-loading safety.

  22241.      This assumes all the files you will ever debug with this GDB come

  22242.      from trusted sources.

  22243. 

  22244.    On the other hand you can also explicitly forbid automatic files

  22245. loading which also suppresses any such warning messages:

  22246. 

  22247. 'gdb -iex "set auto-load no" ...'

  22248.      You can use GDB command-line option for a single GDB session.

  22249. 

  22250. '~/.gdbinit': 'set auto-load no'

  22251.      Disable auto-loading globally for the user (*note Home Directory

  22252.      Init File::).  While it is improbable, you could also use system

  22253.      init file instead (*note System-wide configuration::).

  22254. 

  22255.    This setting applies to the file names as entered by user.  If no

  22256. entry matches GDB tries as a last resort to also resolve all the file

  22257. names into their canonical form (typically resolving symbolic links) and

  22258. compare the entries again.  GDB already canonicalizes most of the

  22259. filenames on its own before starting the comparison so a canonical form

  22260. of directories is recommended to be entered.

  22261. 

  22262. 

  22263. File: gdb.info,  Node: Auto-loading verbose mode,  Prev: Auto-loading safe path,  Up: Auto-loading

  22264. 

  22265. 22.8.4 Displaying files tried for auto-load

  22266. -------------------------------------------

  22267. 

  22268. For better visibility of all the file locations where you can place

  22269. scripts to be auto-loaded with inferior -- or to protect yourself

  22270. against accidental execution of untrusted scripts -- GDB provides a

  22271. feature for printing all the files attempted to be loaded.  Both

  22272. existing and non-existing files may be printed.

  22273. 

  22274.    For example the list of directories from which it is safe to

  22275. auto-load files (*note Auto-loading safe path::) applies also to

  22276. canonicalized filenames which may not be too obvious while setting it

  22277. up.

  22278. 

  22279.      (gdb) set debug auto-load on

  22280.      (gdb) file ~/src/t/true

  22281.      auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"

  22282.                 for objfile "/tmp/true".

  22283.      auto-load: Updating directories of "/usr:/opt".

  22284.      auto-load: Using directory "/usr".

  22285.      auto-load: Using directory "/opt".

  22286.      warning: File "/tmp/true-gdb.gdb" auto-loading has been declined

  22287.               by your `auto-load safe-path' set to "/usr:/opt".

  22288. 

  22289. 'set debug auto-load [on|off]'

  22290.      Set whether to print the filenames attempted to be auto-loaded.

  22291. 

  22292. 'show debug auto-load'

  22293.      Show whether printing of the filenames attempted to be auto-loaded

  22294.      is turned on or off.

  22295. 

  22296. 

  22297. File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: Auto-loading,  Up: Controlling GDB

  22298. 

  22299. 22.9 Optional Warnings and Messages

  22300. ===================================

  22301. 

  22302. By default, GDB is silent about its inner workings.  If you are running

  22303. on a slow machine, you may want to use the 'set verbose' command.  This

  22304. makes GDB tell you when it does a lengthy internal operation, so you

  22305. will not think it has crashed.

  22306. 

  22307.    Currently, the messages controlled by 'set verbose' are those which

  22308. announce that the symbol table for a source file is being read; see

  22309. 'symbol-file' in *note Commands to Specify Files: Files.

  22310. 

  22311. 'set verbose on'

  22312.      Enables GDB output of certain informational messages.

  22313. 

  22314. 'set verbose off'

  22315.      Disables GDB output of certain informational messages.

  22316. 

  22317. 'show verbose'

  22318.      Displays whether 'set verbose' is on or off.

  22319. 

  22320.    By default, if GDB encounters bugs in the symbol table of an object

  22321. file, it is silent; but if you are debugging a compiler, you may find

  22322. this information useful (*note Errors Reading Symbol Files: Symbol

  22323. Errors.).

  22324. 

  22325. 'set complaints LIMIT'

  22326.      Permits GDB to output LIMIT complaints about each type of unusual

  22327.      symbols before becoming silent about the problem.  Set LIMIT to

  22328.      zero to suppress all complaints; set it to a large number to

  22329.      prevent complaints from being suppressed.

  22330. 

  22331. 'show complaints'

  22332.      Displays how many symbol complaints GDB is permitted to produce.

  22333. 

  22334.    By default, GDB is cautious, and asks what sometimes seems to be a

  22335. lot of stupid questions to confirm certain commands.  For example, if

  22336. you try to run a program which is already running:

  22337. 

  22338.      (gdb) run

  22339.      The program being debugged has been started already.

  22340.      Start it from the beginning? (y or n)

  22341. 

  22342.    If you are willing to unflinchingly face the consequences of your own

  22343. commands, you can disable this "feature":

  22344. 

  22345. 'set confirm off'

  22346.      Disables confirmation requests.  Note that running GDB with the

  22347.      '--batch' option (*note -batch: Mode Options.) also automatically

  22348.      disables confirmation requests.

  22349. 

  22350. 'set confirm on'

  22351.      Enables confirmation requests (the default).

  22352. 

  22353. 'show confirm'

  22354.      Displays state of confirmation requests.

  22355. 

  22356.    If you need to debug user-defined commands or sourced files you may

  22357. find it useful to enable "command tracing".  In this mode each command

  22358. will be printed as it is executed, prefixed with one or more '+'

  22359. symbols, the quantity denoting the call depth of each command.

  22360. 

  22361. 'set trace-commands on'

  22362.      Enable command tracing.

  22363. 'set trace-commands off'

  22364.      Disable command tracing.

  22365. 'show trace-commands'

  22366.      Display the current state of command tracing.

  22367. 

  22368. 

  22369. File: gdb.info,  Node: Debugging Output,  Next: Other Misc Settings,  Prev: Messages/Warnings,  Up: Controlling GDB

  22370. 

  22371. 22.10 Optional Messages about Internal Happenings

  22372. =================================================

  22373. 

  22374. GDB has commands that enable optional debugging messages from various

  22375. GDB subsystems; normally these commands are of interest to GDB

  22376. maintainers, or when reporting a bug.  This section documents those

  22377. commands.

  22378. 

  22379. 'set exec-done-display'

  22380.      Turns on or off the notification of asynchronous commands'

  22381.      completion.  When on, GDB will print a message when an asynchronous

  22382.      command finishes its execution.  The default is off.

  22383. 'show exec-done-display'

  22384.      Displays the current setting of asynchronous command completion

  22385.      notification.

  22386. 'set debug aarch64'

  22387.      Turns on or off display of debugging messages related to ARM

  22388.      AArch64.  The default is off.

  22389. 'show debug aarch64'

  22390.      Displays the current state of displaying debugging messages related

  22391.      to ARM AArch64.

  22392. 'set debug arch'

  22393.      Turns on or off display of gdbarch debugging info.  The default is

  22394.      off

  22395. 'show debug arch'

  22396.      Displays the current state of displaying gdbarch debugging info.

  22397. 'set debug aix-solib'

  22398.      Control display of debugging messages from the AIX shared library

  22399.      support module.  The default is off.

  22400. 'show debug aix-thread'

  22401.      Show the current state of displaying AIX shared library debugging

  22402.      messages.

  22403. 'set debug aix-thread'

  22404.      Display debugging messages about inner workings of the AIX thread

  22405.      module.

  22406. 'show debug aix-thread'

  22407.      Show the current state of AIX thread debugging info display.

  22408. 'set debug check-physname'

  22409.      Check the results of the "physname" computation.  When reading

  22410.      DWARF debugging information for C++, GDB attempts to compute each

  22411.      entity's name.  GDB can do this computation in two different ways,

  22412.      depending on exactly what information is present.  When enabled,

  22413.      this setting causes GDB to compute the names both ways and display

  22414.      any discrepancies.

  22415. 'show debug check-physname'

  22416.      Show the current state of "physname" checking.

  22417. 'set debug coff-pe-read'

  22418.      Control display of debugging messages related to reading of COFF/PE

  22419.      exported symbols.  The default is off.

  22420. 'show debug coff-pe-read'

  22421.      Displays the current state of displaying debugging messages related

  22422.      to reading of COFF/PE exported symbols.

  22423. 'set debug dwarf-die'

  22424.      Dump DWARF DIEs after they are read in.  The value is the number of

  22425.      nesting levels to print.  A value of zero turns off the display.

  22426. 'show debug dwarf-die'

  22427.      Show the current state of DWARF DIE debugging.

  22428. 'set debug dwarf-line'

  22429.      Turns on or off display of debugging messages related to reading

  22430.      DWARF line tables.  The default is 0 (off).  A value of 1 provides

  22431.      basic information.  A value greater than 1 provides more verbose

  22432.      information.

  22433. 'show debug dwarf-line'

  22434.      Show the current state of DWARF line table debugging.

  22435. 'set debug dwarf-read'

  22436.      Turns on or off display of debugging messages related to reading

  22437.      DWARF debug info.  The default is 0 (off).  A value of 1 provides

  22438.      basic information.  A value greater than 1 provides more verbose

  22439.      information.

  22440. 'show debug dwarf-read'

  22441.      Show the current state of DWARF reader debugging.

  22442. 'set debug displaced'

  22443.      Turns on or off display of GDB debugging info for the displaced

  22444.      stepping support.  The default is off.

  22445. 'show debug displaced'

  22446.      Displays the current state of displaying GDB debugging info related

  22447.      to displaced stepping.

  22448. 'set debug event'

  22449.      Turns on or off display of GDB event debugging info.  The default

  22450.      is off.

  22451. 'show debug event'

  22452.      Displays the current state of displaying GDB event debugging info.

  22453. 'set debug expression'

  22454.      Turns on or off display of debugging info about GDB expression

  22455.      parsing.  The default is off.

  22456. 'show debug expression'

  22457.      Displays the current state of displaying debugging info about GDB

  22458.      expression parsing.

  22459. 'set debug fbsd-lwp'

  22460.      Turns on or off debugging messages from the FreeBSD LWP debug

  22461.      support.

  22462. 'show debug fbsd-lwp'

  22463.      Show the current state of FreeBSD LWP debugging messages.

  22464. 'set debug fbsd-nat'

  22465.      Turns on or off debugging messages from the FreeBSD native target.

  22466. 'show debug fbsd-nat'

  22467.      Show the current state of FreeBSD native target debugging messages.

  22468. 'set debug frame'

  22469.      Turns on or off display of GDB frame debugging info.  The default

  22470.      is off.

  22471. 'show debug frame'

  22472.      Displays the current state of displaying GDB frame debugging info.

  22473. 'set debug gnu-nat'

  22474.      Turn on or off debugging messages from the GNU/Hurd debug support.

  22475. 'show debug gnu-nat'

  22476.      Show the current state of GNU/Hurd debugging messages.

  22477. 'set debug infrun'

  22478.      Turns on or off display of GDB debugging info for running the

  22479.      inferior.  The default is off.  'infrun.c' contains GDB's runtime

  22480.      state machine used for implementing operations such as

  22481.      single-stepping the inferior.

  22482. 'show debug infrun'

  22483.      Displays the current state of GDB inferior debugging.

  22484. 'set debug jit'

  22485.      Turn on or off debugging messages from JIT debug support.

  22486. 'show debug jit'

  22487.      Displays the current state of GDB JIT debugging.

  22488. 'set debug lin-lwp'

  22489.      Turn on or off debugging messages from the Linux LWP debug support.

  22490. 'show debug lin-lwp'

  22491.      Show the current state of Linux LWP debugging messages.

  22492. 'set debug linux-namespaces'

  22493.      Turn on or off debugging messages from the Linux namespaces debug

  22494.      support.

  22495. 'show debug linux-namespaces'

  22496.      Show the current state of Linux namespaces debugging messages.

  22497. 'set debug mach-o'

  22498.      Control display of debugging messages related to Mach-O symbols

  22499.      processing.  The default is off.

  22500. 'show debug mach-o'

  22501.      Displays the current state of displaying debugging messages related

  22502.      to reading of COFF/PE exported symbols.

  22503. 'set debug notification'

  22504.      Turn on or off debugging messages about remote async notification.

  22505.      The default is off.

  22506. 'show debug notification'

  22507.      Displays the current state of remote async notification debugging

  22508.      messages.

  22509. 'set debug observer'

  22510.      Turns on or off display of GDB observer debugging.  This includes

  22511.      info such as the notification of observable events.

  22512. 'show debug observer'

  22513.      Displays the current state of observer debugging.

  22514. 'set debug overload'

  22515.      Turns on or off display of GDB C++ overload debugging info.  This

  22516.      includes info such as ranking of functions, etc.  The default is

  22517.      off.

  22518. 'show debug overload'

  22519.      Displays the current state of displaying GDB C++ overload debugging

  22520.      info.

  22521. 'set debug parser'

  22522.      Turns on or off the display of expression parser debugging output.

  22523.      Internally, this sets the 'yydebug' variable in the expression

  22524.      parser.  *Note Tracing Your Parser: (bison)Tracing, for details.

  22525.      The default is off.

  22526. 'show debug parser'

  22527.      Show the current state of expression parser debugging.

  22528. 'set debug remote'

  22529.      Turns on or off display of reports on all packets sent back and

  22530.      forth across the serial line to the remote machine.  The info is

  22531.      printed on the GDB standard output stream.  The default is off.

  22532. 'show debug remote'

  22533.      Displays the state of display of remote packets.

  22534. 

  22535. 'set debug remote-packet-max-chars'

  22536.      Sets the maximum number of characters to display for each remote

  22537.      packet when 'set debug remote' is on.  This is useful to prevent

  22538.      GDB from displaying lengthy remote packets and polluting the

  22539.      console.

  22540. 

  22541.      The default value is '512', which means GDB will truncate each

  22542.      remote packet after 512 bytes.

  22543. 

  22544.      Setting this option to 'unlimited' will disable truncation and will

  22545.      output the full length of the remote packets.

  22546. 'show debug remote-packet-max-chars'

  22547.      Displays the number of bytes to output for remote packet debugging.

  22548. 

  22549. 'set debug separate-debug-file'

  22550.      Turns on or off display of debug output about separate debug file

  22551.      search.

  22552. 'show debug separate-debug-file'

  22553.      Displays the state of separate debug file search debug output.

  22554. 

  22555. 'set debug serial'

  22556.      Turns on or off display of GDB serial debugging info.  The default

  22557.      is off.

  22558. 'show debug serial'

  22559.      Displays the current state of displaying GDB serial debugging info.

  22560. 'set debug solib-frv'

  22561.      Turn on or off debugging messages for FR-V shared-library code.

  22562. 'show debug solib-frv'

  22563.      Display the current state of FR-V shared-library code debugging

  22564.      messages.

  22565. 'set debug symbol-lookup'

  22566.      Turns on or off display of debugging messages related to symbol

  22567.      lookup.  The default is 0 (off).  A value of 1 provides basic

  22568.      information.  A value greater than 1 provides more verbose

  22569.      information.

  22570. 'show debug symbol-lookup'

  22571.      Show the current state of symbol lookup debugging messages.

  22572. 'set debug symfile'

  22573.      Turns on or off display of debugging messages related to symbol

  22574.      file functions.  The default is off.  *Note Files::.

  22575. 'show debug symfile'

  22576.      Show the current state of symbol file debugging messages.

  22577. 'set debug symtab-create'

  22578.      Turns on or off display of debugging messages related to symbol

  22579.      table creation.  The default is 0 (off).  A value of 1 provides

  22580.      basic information.  A value greater than 1 provides more verbose

  22581.      information.

  22582. 'show debug symtab-create'

  22583.      Show the current state of symbol table creation debugging.

  22584. 'set debug target'

  22585.      Turns on or off display of GDB target debugging info.  This info

  22586.      includes what is going on at the target level of GDB, as it

  22587.      happens.  The default is 0.  Set it to 1 to track events, and to 2

  22588.      to also track the value of large memory transfers.

  22589. 'show debug target'

  22590.      Displays the current state of displaying GDB target debugging info.

  22591. 'set debug timestamp'

  22592.      Turns on or off display of timestamps with GDB debugging info.

  22593.      When enabled, seconds and microseconds are displayed before each

  22594.      debugging message.

  22595. 'show debug timestamp'

  22596.      Displays the current state of displaying timestamps with GDB

  22597.      debugging info.

  22598. 'set debug varobj'

  22599.      Turns on or off display of GDB variable object debugging info.  The

  22600.      default is off.

  22601. 'show debug varobj'

  22602.      Displays the current state of displaying GDB variable object

  22603.      debugging info.

  22604. 'set debug xml'

  22605.      Turn on or off debugging messages for built-in XML parsers.

  22606. 'show debug xml'

  22607.      Displays the current state of XML debugging messages.

  22608. 

  22609. 

  22610. File: gdb.info,  Node: Other Misc Settings,  Prev: Debugging Output,  Up: Controlling GDB

  22611. 

  22612. 22.11 Other Miscellaneous Settings

  22613. ==================================

  22614. 

  22615. 'set interactive-mode'

  22616.      If 'on', forces GDB to assume that GDB was started in a terminal.

  22617.      In practice, this means that GDB should wait for the user to answer

  22618.      queries generated by commands entered at the command prompt.  If

  22619.      'off', forces GDB to operate in the opposite mode, and it uses the

  22620.      default answers to all queries.  If 'auto' (the default), GDB tries

  22621.      to determine whether its standard input is a terminal, and works in

  22622.      interactive-mode if it is, non-interactively otherwise.

  22623. 

  22624.      In the vast majority of cases, the debugger should be able to guess

  22625.      correctly which mode should be used.  But this setting can be

  22626.      useful in certain specific cases, such as running a MinGW GDB

  22627.      inside a cygwin window.

  22628. 

  22629. 'show interactive-mode'

  22630.      Displays whether the debugger is operating in interactive mode or

  22631.      not.

  22632. 

  22633. 

  22634. File: gdb.info,  Node: Extending GDB,  Next: Interpreters,  Prev: Controlling GDB,  Up: Top

  22635. 

  22636. 23 Extending GDB

  22637. ****************

  22638. 

  22639. GDB provides several mechanisms for extension.  GDB also provides the

  22640. ability to automatically load extensions when it reads a file for

  22641. debugging.  This allows the user to automatically customize GDB for the

  22642. program being debugged.

  22643. 

  22644. * Menu:

  22645. 

  22646. * Sequences::                Canned Sequences of GDB Commands

  22647. * Python::                   Extending GDB using Python

  22648. * Guile::                    Extending GDB using Guile

  22649. * Auto-loading extensions::  Automatically loading extensions

  22650. * Multiple Extension Languages:: Working with multiple extension languages

  22651. * Aliases::                  Creating new spellings of existing commands

  22652. 

  22653.    To facilitate the use of extension languages, GDB is capable of

  22654. evaluating the contents of a file.  When doing so, GDB can recognize

  22655. which extension language is being used by looking at the filename

  22656. extension.  Files with an unrecognized filename extension are always

  22657. treated as a GDB Command Files.  *Note Command files: Command Files.

  22658. 

  22659.    You can control how GDB evaluates these files with the following

  22660. setting:

  22661. 

  22662. 'set script-extension off'

  22663.      All scripts are always evaluated as GDB Command Files.

  22664. 

  22665. 'set script-extension soft'

  22666.      The debugger determines the scripting language based on filename

  22667.      extension.  If this scripting language is supported, GDB evaluates

  22668.      the script using that language.  Otherwise, it evaluates the file

  22669.      as a GDB Command File.

  22670. 

  22671. 'set script-extension strict'

  22672.      The debugger determines the scripting language based on filename

  22673.      extension, and evaluates the script using that language.  If the

  22674.      language is not supported, then the evaluation fails.

  22675. 

  22676. 'show script-extension'

  22677.      Display the current value of the 'script-extension' option.

  22678. 

  22679. 

  22680. File: gdb.info,  Node: Sequences,  Next: Python,  Up: Extending GDB

  22681. 

  22682. 23.1 Canned Sequences of Commands

  22683. =================================

  22684. 

  22685. Aside from breakpoint commands (*note Breakpoint Command Lists: Break

  22686. Commands.), GDB provides two ways to store sequences of commands for

  22687. execution as a unit: user-defined commands and command files.

  22688. 

  22689. * Menu:

  22690. 

  22691. * Define::             How to define your own commands

  22692. * Hooks::              Hooks for user-defined commands

  22693. * Command Files::      How to write scripts of commands to be stored in a file

  22694. * Output::             Commands for controlled output

  22695. * Auto-loading sequences::  Controlling auto-loaded command files

  22696. 

  22697. 

  22698. File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences

  22699. 

  22700. 23.1.1 User-defined Commands

  22701. ----------------------------

  22702. 

  22703. A "user-defined command" is a sequence of GDB commands to which you

  22704. assign a new name as a command.  This is done with the 'define' command.

  22705. User commands may accept an unlimited number of arguments separated by

  22706. whitespace.  Arguments are accessed within the user command via

  22707. '$arg0...$argN'.  A trivial example:

  22708. 

  22709.      define adder

  22710.        print $arg0 + $arg1 + $arg2

  22711.      end

  22712. 

  22713. To execute the command use:

  22714. 

  22715.      adder 1 2 3

  22716. 

  22717. This defines the command 'adder', which prints the sum of its three

  22718. arguments.  Note the arguments are text substitutions, so they may

  22719. reference variables, use complex expressions, or even perform inferior

  22720. functions calls.

  22721. 

  22722.    In addition, '$argc' may be used to find out how many arguments have

  22723. been passed.

  22724. 

  22725.      define adder

  22726.        if $argc == 2

  22727.          print $arg0 + $arg1

  22728.        end

  22729.        if $argc == 3

  22730.          print $arg0 + $arg1 + $arg2

  22731.        end

  22732.      end

  22733. 

  22734.    Combining with the 'eval' command (*note eval::) makes it easier to

  22735. process a variable number of arguments:

  22736. 

  22737.      define adder

  22738.        set $i = 0

  22739.        set $sum = 0

  22740.        while $i < $argc

  22741.          eval "set $sum = $sum + $arg%d", $i

  22742.          set $i = $i + 1

  22743.        end

  22744.        print $sum

  22745.      end

  22746. 

  22747. 'define COMMANDNAME'

  22748.      Define a command named COMMANDNAME.  If there is already a command

  22749.      by that name, you are asked to confirm that you want to redefine

  22750.      it.  The argument COMMANDNAME may be a bare command name consisting

  22751.      of letters, numbers, dashes, dots, and underscores.  It may also

  22752.      start with any predefined or user-defined prefix command.  For

  22753.      example, 'define target my-target' creates a user-defined 'target

  22754.      my-target' command.

  22755. 

  22756.      The definition of the command is made up of other GDB command

  22757.      lines, which are given following the 'define' command.  The end of

  22758.      these commands is marked by a line containing 'end'.

  22759. 

  22760. 'document COMMANDNAME'

  22761.      Document the user-defined command COMMANDNAME, so that it can be

  22762.      accessed by 'help'.  The command COMMANDNAME must already be

  22763.      defined.  This command reads lines of documentation just as

  22764.      'define' reads the lines of the command definition, ending with

  22765.      'end'.  After the 'document' command is finished, 'help' on command

  22766.      COMMANDNAME displays the documentation you have written.

  22767. 

  22768.      You may use the 'document' command again to change the

  22769.      documentation of a command.  Redefining the command with 'define'

  22770.      does not change the documentation.

  22771. 

  22772. 'define-prefix COMMANDNAME'

  22773.      Define or mark the command COMMANDNAME as a user-defined prefix

  22774.      command.  Once marked, COMMANDNAME can be used as prefix command by

  22775.      the 'define' command.  Note that 'define-prefix' can be used with a

  22776.      not yet defined COMMANDNAME.  In such a case, COMMANDNAME is

  22777.      defined as an empty user-defined command.  In case you redefine a

  22778.      command that was marked as a user-defined prefix command, the

  22779.      subcommands of the redefined command are kept (and GDB indicates so

  22780.      to the user).

  22781. 

  22782.      Example:

  22783.           (gdb) define-prefix abc

  22784.           (gdb) define-prefix abc def

  22785.           (gdb) define abc def

  22786.           Type commands for definition of "abc def".

  22787.           End with a line saying just "end".

  22788.           >echo command initial def\n

  22789.           >end

  22790.           (gdb) define abc def ghi

  22791.           Type commands for definition of "abc def ghi".

  22792.           End with a line saying just "end".

  22793.           >echo command ghi\n

  22794.           >end

  22795.           (gdb) define abc def

  22796.           Keeping subcommands of prefix command "def".

  22797.           Redefine command "def"? (y or n) y

  22798.           Type commands for definition of "abc def".

  22799.           End with a line saying just "end".

  22800.           >echo command def\n

  22801.           >end

  22802.           (gdb) abc def ghi

  22803.           command ghi

  22804.           (gdb) abc def

  22805.           command def

  22806.           (gdb)

  22807. 

  22808. 'dont-repeat'

  22809.      Used inside a user-defined command, this tells GDB that this

  22810.      command should not be repeated when the user hits <RET> (*note

  22811.      repeat last command: Command Syntax.).

  22812. 

  22813. 'help user-defined'

  22814.      List all user-defined commands and all python commands defined in

  22815.      class COMMAND_USER. The first line of the documentation or

  22816.      docstring is included (if any).

  22817. 

  22818. 'show user'

  22819. 'show user COMMANDNAME'

  22820.      Display the GDB commands used to define COMMANDNAME (but not its

  22821.      documentation).  If no COMMANDNAME is given, display the

  22822.      definitions for all user-defined commands.  This does not work for

  22823.      user-defined python commands.

  22824. 

  22825. 'show max-user-call-depth'

  22826. 'set max-user-call-depth'

  22827.      The value of 'max-user-call-depth' controls how many recursion

  22828.      levels are allowed in user-defined commands before GDB suspects an

  22829.      infinite recursion and aborts the command.  This does not apply to

  22830.      user-defined python commands.

  22831. 

  22832.    In addition to the above commands, user-defined commands frequently

  22833. use control flow commands, described in *note Command Files::.

  22834. 

  22835.    When user-defined commands are executed, the commands of the

  22836. definition are not printed.  An error in any command stops execution of

  22837. the user-defined command.

  22838. 

  22839.    If used interactively, commands that would ask for confirmation

  22840. proceed without asking when used inside a user-defined command.  Many

  22841. GDB commands that normally print messages to say what they are doing

  22842. omit the messages when used in a user-defined command.

  22843. 

  22844. 

  22845. File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences

  22846. 

  22847. 23.1.2 User-defined Command Hooks

  22848. ---------------------------------

  22849. 

  22850. You may define "hooks", which are a special kind of user-defined

  22851. command.  Whenever you run the command 'foo', if the user-defined

  22852. command 'hook-foo' exists, it is executed (with no arguments) before

  22853. that command.

  22854. 

  22855.    A hook may also be defined which is run after the command you

  22856. executed.  Whenever you run the command 'foo', if the user-defined

  22857. command 'hookpost-foo' exists, it is executed (with no arguments) after

  22858. that command.  Post-execution hooks may exist simultaneously with

  22859. pre-execution hooks, for the same command.

  22860. 

  22861.    It is valid for a hook to call the command which it hooks.  If this

  22862. occurs, the hook is not re-executed, thereby avoiding infinite

  22863. recursion.

  22864. 

  22865.    In addition, a pseudo-command, 'stop' exists.  Defining ('hook-stop')

  22866. makes the associated commands execute every time execution stops in your

  22867. program: before breakpoint commands are run, displays are printed, or

  22868. the stack frame is printed.

  22869. 

  22870.    For example, to ignore 'SIGALRM' signals while single-stepping, but

  22871. treat them normally during normal execution, you could define:

  22872. 

  22873.      define hook-stop

  22874.      handle SIGALRM nopass

  22875.      end

  22876. 

  22877.      define hook-run

  22878.      handle SIGALRM pass

  22879.      end

  22880. 

  22881.      define hook-continue

  22882.      handle SIGALRM pass

  22883.      end

  22884. 

  22885.    As a further example, to hook at the beginning and end of the 'echo'

  22886. command, and to add extra text to the beginning and end of the message,

  22887. you could define:

  22888. 

  22889.      define hook-echo

  22890.      echo <<<---

  22891.      end

  22892. 

  22893.      define hookpost-echo

  22894.      echo --->>>\n

  22895.      end

  22896. 

  22897.      (gdb) echo Hello World

  22898.      <<<---Hello World--->>>

  22899.      (gdb)

  22900. 

  22901. 

  22902.    You can define a hook for any single-word command in GDB, but not for

  22903. command aliases; you should define a hook for the basic command name,

  22904. e.g. 'backtrace' rather than 'bt'.  You can hook a multi-word command by

  22905. adding 'hook-' or 'hookpost-' to the last word of the command, e.g.

  22906. 'define target hook-remote' to add a hook to 'target remote'.

  22907. 

  22908.    If an error occurs during the execution of your hook, execution of

  22909. GDB commands stops and GDB issues a prompt (before the command that you

  22910. actually typed had a chance to run).

  22911. 

  22912.    If you try to define a hook which does not match any known command,

  22913. you get a warning from the 'define' command.

  22914. 

  22915. 

  22916. File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences

  22917. 

  22918. 23.1.3 Command Files

  22919. --------------------

  22920. 

  22921. A command file for GDB is a text file made of lines that are GDB

  22922. commands.  Comments (lines starting with '#') may also be included.  An

  22923. empty line in a command file does nothing; it does not mean to repeat

  22924. the last command, as it would from the terminal.

  22925. 

  22926.    You can request the execution of a command file with the 'source'

  22927. command.  Note that the 'source' command is also used to evaluate

  22928. scripts that are not Command Files.  The exact behavior can be

  22929. configured using the 'script-extension' setting.  *Note Extending GDB:

  22930. Extending GDB.

  22931. 

  22932. 'source [-s] [-v] FILENAME'

  22933.      Execute the command file FILENAME.

  22934. 

  22935.    The lines in a command file are generally executed sequentially,

  22936. unless the order of execution is changed by one of the _flow-control

  22937. commands_ described below.  The commands are not printed as they are

  22938. executed.  An error in any command terminates execution of the command

  22939. file and control is returned to the console.

  22940. 

  22941.    GDB first searches for FILENAME in the current directory.  If the

  22942. file is not found there, and FILENAME does not specify a directory, then

  22943. GDB also looks for the file on the source search path (specified with

  22944. the 'directory' command); except that '$cdir' is not searched because

  22945. the compilation directory is not relevant to scripts.

  22946. 

  22947.    If '-s' is specified, then GDB searches for FILENAME on the search

  22948. path even if FILENAME specifies a directory.  The search is done by

  22949. appending FILENAME to each element of the search path.  So, for example,

  22950. if FILENAME is 'mylib/myscript' and the search path contains

  22951. '/home/user' then GDB will look for the script

  22952. '/home/user/mylib/myscript'.  The search is also done if FILENAME is an

  22953. absolute path.  For example, if FILENAME is '/tmp/myscript' and the

  22954. search path contains '/home/user' then GDB will look for the script

  22955. '/home/user/tmp/myscript'.  For DOS-like systems, if FILENAME contains a

  22956. drive specification, it is stripped before concatenation.  For example,

  22957. if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then

  22958. GDB will look for the script 'c:/tmp/myscript'.

  22959. 

  22960.    If '-v', for verbose mode, is given then GDB displays each command as

  22961. it is executed.  The option must be given before FILENAME, and is

  22962. interpreted as part of the filename anywhere else.

  22963. 

  22964.    Commands that would ask for confirmation if used interactively

  22965. proceed without asking when used in a command file.  Many GDB commands

  22966. that normally print messages to say what they are doing omit the

  22967. messages when called from command files.

  22968. 

  22969.    GDB also accepts command input from standard input.  In this mode,

  22970. normal output goes to standard output and error output goes to standard

  22971. error.  Errors in a command file supplied on standard input do not

  22972. terminate execution of the command file--execution continues with the

  22973. next command.

  22974. 

  22975.      gdb < cmds > log 2>&1

  22976. 

  22977.    (The syntax above will vary depending on the shell used.)  This

  22978. example will execute commands from the file 'cmds'.  All output and

  22979. errors would be directed to 'log'.

  22980. 

  22981.    Since commands stored on command files tend to be more general than

  22982. commands typed interactively, they frequently need to deal with

  22983. complicated situations, such as different or unexpected values of

  22984. variables and symbols, changes in how the program being debugged is

  22985. built, etc.  GDB provides a set of flow-control commands to deal with

  22986. these complexities.  Using these commands, you can write complex scripts

  22987. that loop over data structures, execute commands conditionally, etc.

  22988. 

  22989. 'if'

  22990. 'else'

  22991.      This command allows to include in your script conditionally

  22992.      executed commands.  The 'if' command takes a single argument, which

  22993.      is an expression to evaluate.  It is followed by a series of

  22994.      commands that are executed only if the expression is true (its

  22995.      value is nonzero).  There can then optionally be an 'else' line,

  22996.      followed by a series of commands that are only executed if the

  22997.      expression was false.  The end of the list is marked by a line

  22998.      containing 'end'.

  22999. 

  23000. 'while'

  23001.      This command allows to write loops.  Its syntax is similar to 'if':

  23002.      the command takes a single argument, which is an expression to

  23003.      evaluate, and must be followed by the commands to execute, one per

  23004.      line, terminated by an 'end'.  These commands are called the "body"

  23005.      of the loop.  The commands in the body of 'while' are executed

  23006.      repeatedly as long as the expression evaluates to true.

  23007. 

  23008. 'loop_break'

  23009.      This command exits the 'while' loop in whose body it is included.

  23010.      Execution of the script continues after that 'while's 'end' line.

  23011. 

  23012. 'loop_continue'

  23013.      This command skips the execution of the rest of the body of

  23014.      commands in the 'while' loop in whose body it is included.

  23015.      Execution branches to the beginning of the 'while' loop, where it

  23016.      evaluates the controlling expression.

  23017. 

  23018. 'end'

  23019.      Terminate the block of commands that are the body of 'if', 'else',

  23020.      or 'while' flow-control commands.

  23021. 

  23022. 

  23023. File: gdb.info,  Node: Output,  Next: Auto-loading sequences,  Prev: Command Files,  Up: Sequences

  23024. 

  23025. 23.1.4 Commands for Controlled Output

  23026. -------------------------------------

  23027. 

  23028. During the execution of a command file or a user-defined command, normal

  23029. GDB output is suppressed; the only output that appears is what is

  23030. explicitly printed by the commands in the definition.  This section

  23031. describes three commands useful for generating exactly the output you

  23032. want.

  23033. 

  23034. 'echo TEXT'

  23035.      Print TEXT.  Nonprinting characters can be included in TEXT using C

  23036.      escape sequences, such as '\n' to print a newline.  *No newline is

  23037.      printed unless you specify one.*  In addition to the standard C

  23038.      escape sequences, a backslash followed by a space stands for a

  23039.      space.  This is useful for displaying a string with spaces at the

  23040.      beginning or the end, since leading and trailing spaces are

  23041.      otherwise trimmed from all arguments.  To print ' and foo = ', use

  23042.      the command 'echo \ and foo = \ '.

  23043. 

  23044.      A backslash at the end of TEXT can be used, as in C, to continue

  23045.      the command onto subsequent lines.  For example,

  23046. 

  23047.           echo This is some text\n\

  23048.           which is continued\n\

  23049.           onto several lines.\n

  23050. 

  23051.      produces the same output as

  23052. 

  23053.           echo This is some text\n

  23054.           echo which is continued\n

  23055.           echo onto several lines.\n

  23056. 

  23057. 'output EXPRESSION'

  23058.      Print the value of EXPRESSION and nothing but that value: no

  23059.      newlines, no '$NN = '.  The value is not entered in the value

  23060.      history either.  *Note Expressions: Expressions, for more

  23061.      information on expressions.

  23062. 

  23063. 'output/FMT EXPRESSION'

  23064.      Print the value of EXPRESSION in format FMT.  You can use the same

  23065.      formats as for 'print'.  *Note Output Formats: Output Formats, for

  23066.      more information.

  23067. 

  23068. 'printf TEMPLATE, EXPRESSIONS...'

  23069.      Print the values of one or more EXPRESSIONS under the control of

  23070.      the string TEMPLATE.  To print several values, make EXPRESSIONS be

  23071.      a comma-separated list of individual expressions, which may be

  23072.      either numbers or pointers.  Their values are printed as specified

  23073.      by TEMPLATE, exactly as a C program would do by executing the code

  23074.      below:

  23075. 

  23076.           printf (TEMPLATE, EXPRESSIONS...);

  23077. 

  23078.      As in 'C' 'printf', ordinary characters in TEMPLATE are printed

  23079.      verbatim, while "conversion specification" introduced by the '%'

  23080.      character cause subsequent EXPRESSIONS to be evaluated, their

  23081.      values converted and formatted according to type and style

  23082.      information encoded in the conversion specifications, and then

  23083.      printed.

  23084. 

  23085.      For example, you can print two values in hex like this:

  23086. 

  23087.           printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo

  23088. 

  23089.      'printf' supports all the standard 'C' conversion specifications,

  23090.      including the flags and modifiers between the '%' character and the

  23091.      conversion letter, with the following exceptions:

  23092. 

  23093.         * The argument-ordering modifiers, such as '2$', are not

  23094.           supported.

  23095. 

  23096.         * The modifier '*' is not supported for specifying precision or

  23097.           width.

  23098. 

  23099.         * The ''' flag (for separation of digits into groups according

  23100.           to 'LC_NUMERIC'') is not supported.

  23101. 

  23102.         * The type modifiers 'hh', 'j', 't', and 'z' are not supported.

  23103. 

  23104.         * The conversion letter 'n' (as in '%n') is not supported.

  23105. 

  23106.         * The conversion letters 'a' and 'A' are not supported.

  23107. 

  23108.      Note that the 'll' type modifier is supported only if the

  23109.      underlying 'C' implementation used to build GDB supports the 'long

  23110.      long int' type, and the 'L' type modifier is supported only if

  23111.      'long double' type is available.

  23112. 

  23113.      As in 'C', 'printf' supports simple backslash-escape sequences,

  23114.      such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of

  23115.      backslash followed by a single character.  Octal and hexadecimal

  23116.      escape sequences are not supported.

  23117. 

  23118.      Additionally, 'printf' supports conversion specifications for DFP

  23119.      ("Decimal Floating Point") types using the following length

  23120.      modifiers together with a floating point specifier.  letters:

  23121. 

  23122.         * 'H' for printing 'Decimal32' types.

  23123. 

  23124.         * 'D' for printing 'Decimal64' types.

  23125. 

  23126.         * 'DD' for printing 'Decimal128' types.

  23127. 

  23128.      If the underlying 'C' implementation used to build GDB has support

  23129.      for the three length modifiers for DFP types, other modifiers such

  23130.      as width and precision will also be available for GDB to use.

  23131. 

  23132.      In case there is no such 'C' support, no additional modifiers will

  23133.      be available and the value will be printed in the standard way.

  23134. 

  23135.      Here's an example of printing DFP types using the above conversion

  23136.      letters:

  23137.           printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl

  23138. 

  23139. 'eval TEMPLATE, EXPRESSIONS...'

  23140.      Convert the values of one or more EXPRESSIONS under the control of

  23141.      the string TEMPLATE to a command line, and call it.

  23142. 

  23143. 

  23144. File: gdb.info,  Node: Auto-loading sequences,  Prev: Output,  Up: Sequences

  23145. 

  23146. 23.1.5 Controlling auto-loading native GDB scripts

  23147. --------------------------------------------------

  23148. 

  23149. When a new object file is read (for example, due to the 'file' command,

  23150. or because the inferior has loaded a shared library), GDB will look for

  23151. the command file 'OBJFILE-gdb.gdb'.  *Note Auto-loading extensions::.

  23152. 

  23153.    Auto-loading can be enabled or disabled, and the list of auto-loaded

  23154. scripts can be printed.

  23155. 

  23156. 'set auto-load gdb-scripts [on|off]'

  23157.      Enable or disable the auto-loading of canned sequences of commands

  23158.      scripts.

  23159. 

  23160. 'show auto-load gdb-scripts'

  23161.      Show whether auto-loading of canned sequences of commands scripts

  23162.      is enabled or disabled.

  23163. 

  23164. 'info auto-load gdb-scripts [REGEXP]'

  23165.      Print the list of all canned sequences of commands scripts that GDB

  23166.      auto-loaded.

  23167. 

  23168.    If REGEXP is supplied only canned sequences of commands scripts with

  23169. matching names are printed.

  23170. 

  23171. 

  23172. File: gdb.info,  Node: Python,  Next: Guile,  Prev: Sequences,  Up: Extending GDB

  23173. 

  23174. 23.2 Extending GDB using Python

  23175. ===============================

  23176. 

  23177. You can extend GDB using the Python programming language

  23178. (http://www.python.org/).  This feature is available only if GDB was

  23179. configured using '--with-python'.  GDB can be built against either

  23180. Python 2 or Python 3; which one you have depends on this configure-time

  23181. option.

  23182. 

  23183.    Python scripts used by GDB should be installed in

  23184. 'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as

  23185. determined at GDB startup (*note Data Files::).  This directory, known

  23186. as the "python directory", is automatically added to the Python Search

  23187. Path in order to allow the Python interpreter to locate all scripts

  23188. installed at this location.

  23189. 

  23190.    Additionally, GDB commands and convenience functions which are

  23191. written in Python and are located in the

  23192. 'DATA-DIRECTORY/python/gdb/command' or

  23193. 'DATA-DIRECTORY/python/gdb/function' directories are automatically

  23194. imported when GDB starts.

  23195. 

  23196. * Menu:

  23197. 

  23198. * Python Commands::             Accessing Python from GDB.

  23199. * Python API::                  Accessing GDB from Python.

  23200. * Python Auto-loading::         Automatically loading Python code.

  23201. * Python modules::              Python modules provided by GDB.

  23202. 

  23203. 

  23204. File: gdb.info,  Node: Python Commands,  Next: Python API,  Up: Python

  23205. 

  23206. 23.2.1 Python Commands

  23207. ----------------------

  23208. 

  23209. GDB provides two commands for accessing the Python interpreter, and one

  23210. related setting:

  23211. 

  23212. 'python-interactive [COMMAND]'

  23213. 'pi [COMMAND]'

  23214.      Without an argument, the 'python-interactive' command can be used

  23215.      to start an interactive Python prompt.  To return to GDB, type the

  23216.      'EOF' character (e.g., 'Ctrl-D' on an empty prompt).

  23217. 

  23218.      Alternatively, a single-line Python command can be given as an

  23219.      argument and evaluated.  If the command is an expression, the

  23220.      result will be printed; otherwise, nothing will be printed.  For

  23221.      example:

  23222. 

  23223.           (gdb) python-interactive 2 + 3

  23224.           5

  23225. 

  23226. 'python [COMMAND]'

  23227. 'py [COMMAND]'

  23228.      The 'python' command can be used to evaluate Python code.

  23229. 

  23230.      If given an argument, the 'python' command will evaluate the

  23231.      argument as a Python command.  For example:

  23232. 

  23233.           (gdb) python print 23

  23234.           23

  23235. 

  23236.      If you do not provide an argument to 'python', it will act as a

  23237.      multi-line command, like 'define'.  In this case, the Python script

  23238.      is made up of subsequent command lines, given after the 'python'

  23239.      command.  This command list is terminated using a line containing

  23240.      'end'.  For example:

  23241. 

  23242.           (gdb) python

  23243.           >print 23

  23244.           >end

  23245.           23

  23246. 

  23247. 'set python print-stack'

  23248.      By default, GDB will print only the message component of a Python

  23249.      exception when an error occurs in a Python script.  This can be

  23250.      controlled using 'set python print-stack': if 'full', then full

  23251.      Python stack printing is enabled; if 'none', then Python stack and

  23252.      message printing is disabled; if 'message', the default, only the

  23253.      message component of the error is printed.

  23254. 

  23255.    It is also possible to execute a Python script from the GDB

  23256. interpreter:

  23257. 

  23258. 'source script-name'

  23259.      The script name must end with '.py' and GDB must be configured to

  23260.      recognize the script language based on filename extension using the

  23261.      'script-extension' setting.  *Note Extending GDB: Extending GDB.

  23262. 

  23263. 

  23264. File: gdb.info,  Node: Python API,  Next: Python Auto-loading,  Prev: Python Commands,  Up: Python

  23265. 

  23266. 23.2.2 Python API

  23267. -----------------

  23268. 

  23269. You can get quick online help for GDB's Python API by issuing the

  23270. command 'python help (gdb)'.

  23271. 

  23272.    Functions and methods which have two or more optional arguments allow

  23273. them to be specified using keyword syntax.  This allows passing some

  23274. optional arguments while skipping others.  Example:

  23275. 'gdb.some_function ('foo', bar = 1, baz = 2)'.

  23276. 

  23277. * Menu:

  23278. 

  23279. * Basic Python::                Basic Python Functions.

  23280. * Exception Handling::          How Python exceptions are translated.

  23281. * Values From Inferior::        Python representation of values.

  23282. * Types In Python::             Python representation of types.

  23283. * Pretty Printing API::         Pretty-printing values.

  23284. * Selecting Pretty-Printers::   How GDB chooses a pretty-printer.

  23285. * Writing a Pretty-Printer::    Writing a Pretty-Printer.

  23286. * Type Printing API::		Pretty-printing types.

  23287. * Frame Filter API::            Filtering Frames.

  23288. * Frame Decorator API::         Decorating Frames.

  23289. * Writing a Frame Filter::      Writing a Frame Filter.

  23290. * Unwinding Frames in Python::  Writing frame unwinder.

  23291. * Xmethods In Python::          Adding and replacing methods of C++ classes.

  23292. * Xmethod API::                 Xmethod types.

  23293. * Writing an Xmethod::          Writing an xmethod.

  23294. * Inferiors In Python::         Python representation of inferiors (processes)

  23295. * Events In Python::            Listening for events from GDB.

  23296. * Threads In Python::           Accessing inferior threads from Python.

  23297. * Recordings In Python::        Accessing recordings from Python.

  23298. * Commands In Python::          Implementing new commands in Python.

  23299. * Parameters In Python::        Adding new GDB parameters.

  23300. * Functions In Python::         Writing new convenience functions.

  23301. * Progspaces In Python::        Program spaces.

  23302. * Objfiles In Python::          Object files.

  23303. * Frames In Python::            Accessing inferior stack frames from Python.

  23304. * Blocks In Python::            Accessing blocks from Python.

  23305. * Symbols In Python::           Python representation of symbols.

  23306. * Symbol Tables In Python::     Python representation of symbol tables.

  23307. * Line Tables In Python::       Python representation of line tables.

  23308. * Breakpoints In Python::       Manipulating breakpoints using Python.

  23309. * Finish Breakpoints in Python:: Setting Breakpoints on function return

  23310.                                 using Python.

  23311. * Lazy Strings In Python::      Python representation of lazy strings.

  23312. * Architectures In Python::     Python representation of architectures.

  23313. * Registers In Python::         Python representation of registers.

  23314. * TUI Windows In Python::       Implementing new TUI windows.

  23315. 

  23316. 

  23317. File: gdb.info,  Node: Basic Python,  Next: Exception Handling,  Up: Python API

  23318. 

  23319. 23.2.2.1 Basic Python

  23320. .....................

  23321. 

  23322. At startup, GDB overrides Python's 'sys.stdout' and 'sys.stderr' to

  23323. print using GDB's output-paging streams.  A Python program which outputs

  23324. to one of these streams may have its output interrupted by the user

  23325. (*note Screen Size::).  In this situation, a Python 'KeyboardInterrupt'

  23326. exception is thrown.

  23327. 

  23328.    Some care must be taken when writing Python code to run in GDB.  Two

  23329. things worth noting in particular:

  23330. 

  23331.    * GDB install handlers for 'SIGCHLD' and 'SIGINT'.  Python code must

  23332.      not override these, or even change the options using 'sigaction'.

  23333.      If your program changes the handling of these signals, GDB will

  23334.      most likely stop working correctly.  Note that it is unfortunately

  23335.      common for GUI toolkits to install a 'SIGCHLD' handler.

  23336. 

  23337.    * GDB takes care to mark its internal file descriptors as

  23338.      close-on-exec.  However, this cannot be done in a thread-safe way

  23339.      on all platforms.  Your Python programs should be aware of this and

  23340.      should both create new file descriptors with the close-on-exec flag

  23341.      set and arrange to close unneeded file descriptors before starting

  23342.      a child process.

  23343. 

  23344.    GDB introduces a new Python module, named 'gdb'.  All methods and

  23345. classes added by GDB are placed in this module.  GDB automatically

  23346. 'import's the 'gdb' module for use in all scripts evaluated by the

  23347. 'python' command.

  23348. 

  23349.    Some types of the 'gdb' module come with a textual representation

  23350. (accessible through the 'repr' or 'str' functions).  These are offered

  23351. for debugging purposes only, expect them to change over time.

  23352. 

  23353.  -- Variable: gdb.PYTHONDIR

  23354.      A string containing the python directory (*note Python::).

  23355. 

  23356.  -- Function: gdb.execute (command [, from_tty [, to_string]])

  23357.      Evaluate COMMAND, a string, as a GDB CLI command.  If a GDB

  23358.      exception happens while COMMAND runs, it is translated as described

  23359.      in *note Exception Handling: Exception Handling.

  23360. 

  23361.      The FROM_TTY flag specifies whether GDB ought to consider this

  23362.      command as having originated from the user invoking it

  23363.      interactively.  It must be a boolean value.  If omitted, it

  23364.      defaults to 'False'.

  23365. 

  23366.      By default, any output produced by COMMAND is sent to GDB's

  23367.      standard output (and to the log output if logging is turned on).

  23368.      If the TO_STRING parameter is 'True', then output will be collected

  23369.      by 'gdb.execute' and returned as a string.  The default is 'False',

  23370.      in which case the return value is 'None'.  If TO_STRING is 'True',

  23371.      the GDB virtual terminal will be temporarily set to unlimited width

  23372.      and height, and its pagination will be disabled; *note Screen

  23373.      Size::.

  23374. 

  23375.  -- Function: gdb.breakpoints ()

  23376.      Return a sequence holding all of GDB's breakpoints.  *Note

  23377.      Breakpoints In Python::, for more information.  In GDB version 7.11

  23378.      and earlier, this function returned 'None' if there were no

  23379.      breakpoints.  This peculiarity was subsequently fixed, and now

  23380.      'gdb.breakpoints' returns an empty sequence in this case.

  23381. 

  23382.  -- Function: gdb.rbreak (regex [, minsyms [, throttle, [, symtabs ]]])

  23383.      Return a Python list holding a collection of newly set

  23384.      'gdb.Breakpoint' objects matching function names defined by the

  23385.      REGEX pattern.  If the MINSYMS keyword is 'True', all system

  23386.      functions (those not explicitly defined in the inferior) will also

  23387.      be included in the match.  The THROTTLE keyword takes an integer

  23388.      that defines the maximum number of pattern matches for functions

  23389.      matched by the REGEX pattern.  If the number of matches exceeds the

  23390.      integer value of THROTTLE, a 'RuntimeError' will be raised and no

  23391.      breakpoints will be created.  If THROTTLE is not defined then there

  23392.      is no imposed limit on the maximum number of matches and

  23393.      breakpoints to be created.  The SYMTABS keyword takes a Python

  23394.      iterable that yields a collection of 'gdb.Symtab' objects and will

  23395.      restrict the search to those functions only contained within the

  23396.      'gdb.Symtab' objects.

  23397. 

  23398.  -- Function: gdb.parameter (parameter)

  23399.      Return the value of a GDB PARAMETER given by its name, a string;

  23400.      the parameter name string may contain spaces if the parameter has a

  23401.      multi-part name.  For example, 'print object' is a valid parameter

  23402.      name.

  23403. 

  23404.      If the named parameter does not exist, this function throws a

  23405.      'gdb.error' (*note Exception Handling::).  Otherwise, the

  23406.      parameter's value is converted to a Python value of the appropriate

  23407.      type, and returned.

  23408. 

  23409.  -- Function: gdb.history (number)

  23410.      Return a value from GDB's value history (*note Value History::).

  23411.      The NUMBER argument indicates which history element to return.  If

  23412.      NUMBER is negative, then GDB will take its absolute value and count

  23413.      backward from the last element (i.e., the most recent element) to

  23414.      find the value to return.  If NUMBER is zero, then GDB will return

  23415.      the most recent element.  If the element specified by NUMBER

  23416.      doesn't exist in the value history, a 'gdb.error' exception will be

  23417.      raised.

  23418. 

  23419.      If no exception is raised, the return value is always an instance

  23420.      of 'gdb.Value' (*note Values From Inferior::).

  23421. 

  23422.  -- Function: gdb.convenience_variable (name)

  23423.      Return the value of the convenience variable (*note Convenience

  23424.      Vars::) named NAME.  NAME must be a string.  The name should not

  23425.      include the '$' that is used to mark a convenience variable in an

  23426.      expression.  If the convenience variable does not exist, then

  23427.      'None' is returned.

  23428. 

  23429.  -- Function: gdb.set_convenience_variable (name, value)

  23430.      Set the value of the convenience variable (*note Convenience

  23431.      Vars::) named NAME.  NAME must be a string.  The name should not

  23432.      include the '$' that is used to mark a convenience variable in an

  23433.      expression.  If VALUE is 'None', then the convenience variable is

  23434.      removed.  Otherwise, if VALUE is not a 'gdb.Value' (*note Values

  23435.      From Inferior::), it is is converted using the 'gdb.Value'

  23436.      constructor.

  23437. 

  23438.  -- Function: gdb.parse_and_eval (expression)

  23439.      Parse EXPRESSION, which must be a string, as an expression in the

  23440.      current language, evaluate it, and return the result as a

  23441.      'gdb.Value'.

  23442. 

  23443.      This function can be useful when implementing a new command (*note

  23444.      Commands In Python::), as it provides a way to parse the command's

  23445.      argument as an expression.  It is also useful simply to compute

  23446.      values.

  23447. 

  23448.  -- Function: gdb.find_pc_line (pc)

  23449.      Return the 'gdb.Symtab_and_line' object corresponding to the PC

  23450.      value.  *Note Symbol Tables In Python::.  If an invalid value of PC

  23451.      is passed as an argument, then the 'symtab' and 'line' attributes

  23452.      of the returned 'gdb.Symtab_and_line' object will be 'None' and 0

  23453.      respectively.  This is identical to

  23454.      'gdb.current_progspace().find_pc_line(pc)' and is included for

  23455.      historical compatibility.

  23456. 

  23457.  -- Function: gdb.post_event (event)

  23458.      Put EVENT, a callable object taking no arguments, into GDB's

  23459.      internal event queue.  This callable will be invoked at some later

  23460.      point, during GDB's event processing.  Events posted using

  23461.      'post_event' will be run in the order in which they were posted;

  23462.      however, there is no way to know when they will be processed

  23463.      relative to other events inside GDB.

  23464. 

  23465.      GDB is not thread-safe.  If your Python program uses multiple

  23466.      threads, you must be careful to only call GDB-specific functions in

  23467.      the GDB thread.  'post_event' ensures this.  For example:

  23468. 

  23469.           (gdb) python

  23470.           >import threading

  23471.           >

  23472.           >class Writer():

  23473.           > def __init__(self, message):

  23474.           >        self.message = message;

  23475.           > def __call__(self):

  23476.           >        gdb.write(self.message)

  23477.           >

  23478.           >class MyThread1 (threading.Thread):

  23479.           > def run (self):

  23480.           >        gdb.post_event(Writer("Hello "))

  23481.           >

  23482.           >class MyThread2 (threading.Thread):

  23483.           > def run (self):

  23484.           >        gdb.post_event(Writer("World\n"))

  23485.           >

  23486.           >MyThread1().start()

  23487.           >MyThread2().start()

  23488.           >end

  23489.           (gdb) Hello World

  23490. 

  23491.  -- Function: gdb.write (string [, stream])

  23492.      Print a string to GDB's paginated output stream.  The optional

  23493.      STREAM determines the stream to print to.  The default stream is

  23494.      GDB's standard output stream.  Possible stream values are:

  23495. 

  23496.      'gdb.STDOUT'

  23497.           GDB's standard output stream.

  23498. 

  23499.      'gdb.STDERR'

  23500.           GDB's standard error stream.

  23501. 

  23502.      'gdb.STDLOG'

  23503.           GDB's log stream (*note Logging Output::).

  23504. 

  23505.      Writing to 'sys.stdout' or 'sys.stderr' will automatically call

  23506.      this function and will automatically direct the output to the

  23507.      relevant stream.

  23508. 

  23509.  -- Function: gdb.flush ()

  23510.      Flush the buffer of a GDB paginated stream so that the contents are

  23511.      displayed immediately.  GDB will flush the contents of a stream

  23512.      automatically when it encounters a newline in the buffer.  The

  23513.      optional STREAM determines the stream to flush.  The default stream

  23514.      is GDB's standard output stream.  Possible stream values are:

  23515. 

  23516.      'gdb.STDOUT'

  23517.           GDB's standard output stream.

  23518. 

  23519.      'gdb.STDERR'

  23520.           GDB's standard error stream.

  23521. 

  23522.      'gdb.STDLOG'

  23523.           GDB's log stream (*note Logging Output::).

  23524. 

  23525.      Flushing 'sys.stdout' or 'sys.stderr' will automatically call this

  23526.      function for the relevant stream.

  23527. 

  23528.  -- Function: gdb.target_charset ()

  23529.      Return the name of the current target character set (*note

  23530.      Character Sets::).  This differs from

  23531.      'gdb.parameter('target-charset')' in that 'auto' is never returned.

  23532. 

  23533.  -- Function: gdb.target_wide_charset ()

  23534.      Return the name of the current target wide character set (*note

  23535.      Character Sets::).  This differs from

  23536.      'gdb.parameter('target-wide-charset')' in that 'auto' is never

  23537.      returned.

  23538. 

  23539.  -- Function: gdb.solib_name (address)

  23540.      Return the name of the shared library holding the given ADDRESS as

  23541.      a string, or 'None'.  This is identical to

  23542.      'gdb.current_progspace().solib_name(address)' and is included for

  23543.      historical compatibility.

  23544. 

  23545.  -- Function: gdb.decode_line ([expression])

  23546.      Return locations of the line specified by EXPRESSION, or of the

  23547.      current line if no argument was given.  This function returns a

  23548.      Python tuple containing two elements.  The first element contains a

  23549.      string holding any unparsed section of EXPRESSION (or 'None' if the

  23550.      expression has been fully parsed).  The second element contains

  23551.      either 'None' or another tuple that contains all the locations that

  23552.      match the expression represented as 'gdb.Symtab_and_line' objects

  23553.      (*note Symbol Tables In Python::).  If EXPRESSION is provided, it

  23554.      is decoded the way that GDB's inbuilt 'break' or 'edit' commands do

  23555.      (*note Specify Location::).

  23556. 

  23557.  -- Function: gdb.prompt_hook (current_prompt)

  23558. 

  23559.      If PROMPT_HOOK is callable, GDB will call the method assigned to

  23560.      this operation before a prompt is displayed by GDB.

  23561. 

  23562.      The parameter 'current_prompt' contains the current GDB prompt.

  23563.      This method must return a Python string, or 'None'.  If a string is

  23564.      returned, the GDB prompt will be set to that string.  If 'None' is

  23565.      returned, GDB will continue to use the current prompt.

  23566. 

  23567.      Some prompts cannot be substituted in GDB.  Secondary prompts such

  23568.      as those used by readline for command input, and annotation related

  23569.      prompts are prohibited from being changed.

  23570. 

  23571. 

  23572. File: gdb.info,  Node: Exception Handling,  Next: Values From Inferior,  Prev: Basic Python,  Up: Python API

  23573. 

  23574. 23.2.2.2 Exception Handling

  23575. ...........................

  23576. 

  23577. When executing the 'python' command, Python exceptions uncaught within

  23578. the Python code are translated to calls to GDB error-reporting

  23579. mechanism.  If the command that called 'python' does not handle the

  23580. error, GDB will terminate it and print an error message containing the

  23581. Python exception name, the associated value, and the Python call stack

  23582. backtrace at the point where the exception was raised.  Example:

  23583. 

  23584.      (gdb) python print foo

  23585.      Traceback (most recent call last):

  23586.        File "<string>", line 1, in <module>

  23587.      NameError: name 'foo' is not defined

  23588. 

  23589.    GDB errors that happen in GDB commands invoked by Python code are

  23590. converted to Python exceptions.  The type of the Python exception

  23591. depends on the error.

  23592. 

  23593. 'gdb.error'

  23594.      This is the base class for most exceptions generated by GDB.  It is

  23595.      derived from 'RuntimeError', for compatibility with earlier

  23596.      versions of GDB.

  23597. 

  23598.      If an error occurring in GDB does not fit into some more specific

  23599.      category, then the generated exception will have this type.

  23600. 

  23601. 'gdb.MemoryError'

  23602.      This is a subclass of 'gdb.error' which is thrown when an operation

  23603.      tried to access invalid memory in the inferior.

  23604. 

  23605. 'KeyboardInterrupt'

  23606.      User interrupt (via 'C-c' or by typing 'q' at a pagination prompt)

  23607.      is translated to a Python 'KeyboardInterrupt' exception.

  23608. 

  23609.    In all cases, your exception handler will see the GDB error message

  23610. as its value and the Python call stack backtrace at the Python statement

  23611. closest to where the GDB error occured as the traceback.

  23612. 

  23613.    When implementing GDB commands in Python via 'gdb.Command', or

  23614. functions via 'gdb.Function', it is useful to be able to throw an

  23615. exception that doesn't cause a traceback to be printed.  For example,

  23616. the user may have invoked the command incorrectly.  GDB provides a

  23617. special exception class that can be used for this purpose.

  23618. 

  23619. 'gdb.GdbError'

  23620.      When thrown from a command or function, this exception will cause

  23621.      the command or function to fail, but the Python stack will not be

  23622.      displayed.  GDB does not throw this exception itself, but rather

  23623.      recognizes it when thrown from user Python code.  Example:

  23624. 

  23625.           (gdb) python

  23626.           >class HelloWorld (gdb.Command):

  23627.           >  """Greet the whole world."""

  23628.           >  def __init__ (self):

  23629.           >    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)

  23630.           >  def invoke (self, args, from_tty):

  23631.           >    argv = gdb.string_to_argv (args)

  23632.           >    if len (argv) != 0:

  23633.           >      raise gdb.GdbError ("hello-world takes no arguments")

  23634.           >    print "Hello, World!"

  23635.           >HelloWorld ()

  23636.           >end

  23637.           (gdb) hello-world 42

  23638.           hello-world takes no arguments

  23639. 

  23640. 

  23641. File: gdb.info,  Node: Values From Inferior,  Next: Types In Python,  Prev: Exception Handling,  Up: Python API

  23642. 

  23643. 23.2.2.3 Values From Inferior

  23644. .............................

  23645. 

  23646. GDB provides values it obtains from the inferior program in an object of

  23647. type 'gdb.Value'.  GDB uses this object for its internal bookkeeping of

  23648. the inferior's values, and for fetching values when necessary.

  23649. 

  23650.    Inferior values that are simple scalars can be used directly in

  23651. Python expressions that are valid for the value's data type.  Here's an

  23652. example for an integer or floating-point value 'some_val':

  23653. 

  23654.      bar = some_val + 2

  23655. 

  23656. As result of this, 'bar' will also be a 'gdb.Value' object whose values

  23657. are of the same type as those of 'some_val'.  Valid Python operations

  23658. can also be performed on 'gdb.Value' objects representing a 'struct' or

  23659. 'class' object.  For such cases, the overloaded operator (if present),

  23660. is used to perform the operation.  For example, if 'val1' and 'val2' are

  23661. 'gdb.Value' objects representing instances of a 'class' which overloads

  23662. the '+' operator, then one can use the '+' operator in their Python

  23663. script as follows:

  23664. 

  23665.      val3 = val1 + val2

  23666. 

  23667. The result of the operation 'val3' is also a 'gdb.Value' object

  23668. corresponding to the value returned by the overloaded '+' operator.  In

  23669. general, overloaded operators are invoked for the following operations:

  23670. '+' (binary addition), '-' (binary subtraction), '*' (multiplication),

  23671. '/', '%', '<<', '>>', '|', '&', '^'.

  23672. 

  23673.    Inferior values that are structures or instances of some class can be

  23674. accessed using the Python "dictionary syntax".  For example, if

  23675. 'some_val' is a 'gdb.Value' instance holding a structure, you can access

  23676. its 'foo' element with:

  23677. 

  23678.      bar = some_val['foo']

  23679. 

  23680.    Again, 'bar' will also be a 'gdb.Value' object.  Structure elements

  23681. can also be accessed by using 'gdb.Field' objects as subscripts (*note

  23682. Types In Python::, for more information on 'gdb.Field' objects).  For

  23683. example, if 'foo_field' is a 'gdb.Field' object corresponding to element

  23684. 'foo' of the above structure, then 'bar' can also be accessed as

  23685. follows:

  23686. 

  23687.      bar = some_val[foo_field]

  23688. 

  23689.    A 'gdb.Value' that represents a function can be executed via inferior

  23690. function call.  Any arguments provided to the call must match the

  23691. function's prototype, and must be provided in the order specified by

  23692. that prototype.

  23693. 

  23694.    For example, 'some_val' is a 'gdb.Value' instance representing a

  23695. function that takes two integers as arguments.  To execute this

  23696. function, call it like so:

  23697. 

  23698.      result = some_val (10,20)

  23699. 

  23700.    Any values returned from a function call will be stored as a

  23701. 'gdb.Value'.

  23702. 

  23703.    The following attributes are provided:

  23704. 

  23705.  -- Variable: Value.address

  23706.      If this object is addressable, this read-only attribute holds a

  23707.      'gdb.Value' object representing the address.  Otherwise, this

  23708.      attribute holds 'None'.

  23709. 

  23710.  -- Variable: Value.is_optimized_out

  23711.      This read-only boolean attribute is true if the compiler optimized

  23712.      out this value, thus it is not available for fetching from the

  23713.      inferior.

  23714. 

  23715.  -- Variable: Value.type

  23716.      The type of this 'gdb.Value'.  The value of this attribute is a

  23717.      'gdb.Type' object (*note Types In Python::).

  23718. 

  23719.  -- Variable: Value.dynamic_type

  23720.      The dynamic type of this 'gdb.Value'.  This uses the object's

  23721.      virtual table and the C++ run-time type information (RTTI) to

  23722.      determine the dynamic type of the value.  If this value is of class

  23723.      type, it will return the class in which the value is embedded, if

  23724.      any.  If this value is of pointer or reference to a class type, it

  23725.      will compute the dynamic type of the referenced object, and return

  23726.      a pointer or reference to that type, respectively.  In all other

  23727.      cases, it will return the value's static type.

  23728. 

  23729.      Note that this feature will only work when debugging a C++ program

  23730.      that includes RTTI for the object in question.  Otherwise, it will

  23731.      just return the static type of the value as in 'ptype foo' (*note

  23732.      ptype: Symbols.).

  23733. 

  23734.  -- Variable: Value.is_lazy

  23735.      The value of this read-only boolean attribute is 'True' if this

  23736.      'gdb.Value' has not yet been fetched from the inferior.  GDB does

  23737.      not fetch values until necessary, for efficiency.  For example:

  23738. 

  23739.           myval = gdb.parse_and_eval ('somevar')

  23740. 

  23741.      The value of 'somevar' is not fetched at this time.  It will be

  23742.      fetched when the value is needed, or when the 'fetch_lazy' method

  23743.      is invoked.

  23744. 

  23745.    The following methods are provided:

  23746. 

  23747.  -- Function: Value.__init__ (VAL)

  23748.      Many Python values can be converted directly to a 'gdb.Value' via

  23749.      this object initializer.  Specifically:

  23750. 

  23751.      Python boolean

  23752.           A Python boolean is converted to the boolean type from the

  23753.           current language.

  23754. 

  23755.      Python integer

  23756.           A Python integer is converted to the C 'long' type for the

  23757.           current architecture.

  23758. 

  23759.      Python long

  23760.           A Python long is converted to the C 'long long' type for the

  23761.           current architecture.

  23762. 

  23763.      Python float

  23764.           A Python float is converted to the C 'double' type for the

  23765.           current architecture.

  23766. 

  23767.      Python string

  23768.           A Python string is converted to a target string in the current

  23769.           target language using the current target encoding.  If a

  23770.           character cannot be represented in the current target

  23771.           encoding, then an exception is thrown.

  23772. 

  23773.      'gdb.Value'

  23774.           If 'val' is a 'gdb.Value', then a copy of the value is made.

  23775. 

  23776.      'gdb.LazyString'

  23777.           If 'val' is a 'gdb.LazyString' (*note Lazy Strings In

  23778.           Python::), then the lazy string's 'value' method is called,

  23779.           and its result is used.

  23780. 

  23781.  -- Function: Value.__init__ (VAL, TYPE)

  23782.      This second form of the 'gdb.Value' constructor returns a

  23783.      'gdb.Value' of type TYPE where the value contents are taken from

  23784.      the Python buffer object specified by VAL.  The number of bytes in

  23785.      the Python buffer object must be greater than or equal to the size

  23786.      of TYPE.

  23787. 

  23788.  -- Function: Value.cast (type)

  23789.      Return a new instance of 'gdb.Value' that is the result of casting

  23790.      this instance to the type described by TYPE, which must be a

  23791.      'gdb.Type' object.  If the cast cannot be performed for some

  23792.      reason, this method throws an exception.

  23793. 

  23794.  -- Function: Value.dereference ()

  23795.      For pointer data types, this method returns a new 'gdb.Value'

  23796.      object whose contents is the object pointed to by the pointer.  For

  23797.      example, if 'foo' is a C pointer to an 'int', declared in your C

  23798.      program as

  23799. 

  23800.           int *foo;

  23801. 

  23802.      then you can use the corresponding 'gdb.Value' to access what 'foo'

  23803.      points to like this:

  23804. 

  23805.           bar = foo.dereference ()

  23806. 

  23807.      The result 'bar' will be a 'gdb.Value' object holding the value

  23808.      pointed to by 'foo'.

  23809. 

  23810.      A similar function 'Value.referenced_value' exists which also

  23811.      returns 'gdb.Value' objects corresponding to the values pointed to

  23812.      by pointer values (and additionally, values referenced by reference

  23813.      values).  However, the behavior of 'Value.dereference' differs from

  23814.      'Value.referenced_value' by the fact that the behavior of

  23815.      'Value.dereference' is identical to applying the C unary operator

  23816.      '*' on a given value.  For example, consider a reference to a

  23817.      pointer 'ptrref', declared in your C++ program as

  23818. 

  23819.           typedef int *intptr;

  23820.           ...

  23821.           int val = 10;

  23822.           intptr ptr = &val;

  23823.           intptr &ptrref = ptr;

  23824. 

  23825.      Though 'ptrref' is a reference value, one can apply the method

  23826.      'Value.dereference' to the 'gdb.Value' object corresponding to it

  23827.      and obtain a 'gdb.Value' which is identical to that corresponding

  23828.      to 'val'.  However, if you apply the method

  23829.      'Value.referenced_value', the result would be a 'gdb.Value' object

  23830.      identical to that corresponding to 'ptr'.

  23831. 

  23832.           py_ptrref = gdb.parse_and_eval ("ptrref")

  23833.           py_val = py_ptrref.dereference ()

  23834.           py_ptr = py_ptrref.referenced_value ()

  23835. 

  23836.      The 'gdb.Value' object 'py_val' is identical to that corresponding

  23837.      to 'val', and 'py_ptr' is identical to that corresponding to 'ptr'.

  23838.      In general, 'Value.dereference' can be applied whenever the C unary

  23839.      operator '*' can be applied to the corresponding C value.  For

  23840.      those cases where applying both 'Value.dereference' and

  23841.      'Value.referenced_value' is allowed, the results obtained need not

  23842.      be identical (as we have seen in the above example).  The results

  23843.      are however identical when applied on 'gdb.Value' objects

  23844.      corresponding to pointers ('gdb.Value' objects with type code

  23845.      'TYPE_CODE_PTR') in a C/C++ program.

  23846. 

  23847.  -- Function: Value.referenced_value ()

  23848.      For pointer or reference data types, this method returns a new

  23849.      'gdb.Value' object corresponding to the value referenced by the

  23850.      pointer/reference value.  For pointer data types,

  23851.      'Value.dereference' and 'Value.referenced_value' produce identical

  23852.      results.  The difference between these methods is that

  23853.      'Value.dereference' cannot get the values referenced by reference

  23854.      values.  For example, consider a reference to an 'int', declared in

  23855.      your C++ program as

  23856. 

  23857.           int val = 10;

  23858.           int &ref = val;

  23859. 

  23860.      then applying 'Value.dereference' to the 'gdb.Value' object

  23861.      corresponding to 'ref' will result in an error, while applying

  23862.      'Value.referenced_value' will result in a 'gdb.Value' object

  23863.      identical to that corresponding to 'val'.

  23864. 

  23865.           py_ref = gdb.parse_and_eval ("ref")

  23866.           er_ref = py_ref.dereference ()       # Results in error

  23867.           py_val = py_ref.referenced_value ()  # Returns the referenced value

  23868. 

  23869.      The 'gdb.Value' object 'py_val' is identical to that corresponding

  23870.      to 'val'.

  23871. 

  23872.  -- Function: Value.reference_value ()

  23873.      Return a 'gdb.Value' object which is a reference to the value

  23874.      encapsulated by this instance.

  23875. 

  23876.  -- Function: Value.const_value ()

  23877.      Return a 'gdb.Value' object which is a 'const' version of the value

  23878.      encapsulated by this instance.

  23879. 

  23880.  -- Function: Value.dynamic_cast (type)

  23881.      Like 'Value.cast', but works as if the C++ 'dynamic_cast' operator

  23882.      were used.  Consult a C++ reference for details.

  23883. 

  23884.  -- Function: Value.reinterpret_cast (type)

  23885.      Like 'Value.cast', but works as if the C++ 'reinterpret_cast'

  23886.      operator were used.  Consult a C++ reference for details.

  23887. 

  23888.  -- Function: Value.format_string (...)

  23889.      Convert a 'gdb.Value' to a string, similarly to what the 'print'

  23890.      command does.  Invoked with no arguments, this is equivalent to

  23891.      calling the 'str' function on the 'gdb.Value'.  The representation

  23892.      of the same value may change across different versions of GDB, so

  23893.      you shouldn't, for instance, parse the strings returned by this

  23894.      method.

  23895. 

  23896.      All the arguments are keyword only.  If an argument is not

  23897.      specified, the current global default setting is used.

  23898. 

  23899.      'raw'

  23900.           'True' if pretty-printers (*note Pretty Printing::) should not

  23901.           be used to format the value.  'False' if enabled

  23902.           pretty-printers matching the type represented by the

  23903.           'gdb.Value' should be used to format it.

  23904. 

  23905.      'pretty_arrays'

  23906.           'True' if arrays should be pretty printed to be more

  23907.           convenient to read, 'False' if they shouldn't (see 'set print

  23908.           array' in *note Print Settings::).

  23909. 

  23910.      'pretty_structs'

  23911.           'True' if structs should be pretty printed to be more

  23912.           convenient to read, 'False' if they shouldn't (see 'set print

  23913.           pretty' in *note Print Settings::).

  23914. 

  23915.      'array_indexes'

  23916.           'True' if array indexes should be included in the string

  23917.           representation of arrays, 'False' if they shouldn't (see 'set

  23918.           print array-indexes' in *note Print Settings::).

  23919. 

  23920.      'symbols'

  23921.           'True' if the string representation of a pointer should

  23922.           include the corresponding symbol name (if one exists), 'False'

  23923.           if it shouldn't (see 'set print symbol' in *note Print

  23924.           Settings::).

  23925. 

  23926.      'unions'

  23927.           'True' if unions which are contained in other structures or

  23928.           unions should be expanded, 'False' if they shouldn't (see 'set

  23929.           print union' in *note Print Settings::).

  23930. 

  23931.      'deref_refs'

  23932.           'True' if C++ references should be resolved to the value they

  23933.           refer to, 'False' (the default) if they shouldn't.  Note that,

  23934.           unlike for the 'print' command, references are not

  23935.           automatically expanded when using the 'format_string' method

  23936.           or the 'str' function.  There is no global 'print' setting to

  23937.           change the default behaviour.

  23938. 

  23939.      'actual_objects'

  23940.           'True' if the representation of a pointer to an object should

  23941.           identify the _actual_ (derived) type of the object rather than

  23942.           the _declared_ type, using the virtual function table.

  23943.           'False' if the _declared_ type should be used.  (See 'set

  23944.           print object' in *note Print Settings::).

  23945. 

  23946.      'static_fields'

  23947.           'True' if static members should be included in the string

  23948.           representation of a C++ object, 'False' if they shouldn't (see

  23949.           'set print static-members' in *note Print Settings::).

  23950. 

  23951.      'max_elements'

  23952.           Number of array elements to print, or '0' to print an

  23953.           unlimited number of elements (see 'set print elements' in

  23954.           *note Print Settings::).

  23955. 

  23956.      'max_depth'

  23957.           The maximum depth to print for nested structs and unions, or

  23958.           '-1' to print an unlimited number of elements (see 'set print

  23959.           max-depth' in *note Print Settings::).

  23960. 

  23961.      'repeat_threshold'

  23962.           Set the threshold for suppressing display of repeated array

  23963.           elements, or '0' to represent all elements, even if repeated.

  23964.           (See 'set print repeats' in *note Print Settings::).

  23965. 

  23966.      'format'

  23967.           A string containing a single character representing the format

  23968.           to use for the returned string.  For instance, ''x'' is

  23969.           equivalent to using the GDB command 'print' with the '/x'

  23970.           option and formats the value as a hexadecimal number.

  23971. 

  23972.  -- Function: Value.string ([encoding[, errors[, length]]])

  23973.      If this 'gdb.Value' represents a string, then this method converts

  23974.      the contents to a Python string.  Otherwise, this method will throw

  23975.      an exception.

  23976. 

  23977.      Values are interpreted as strings according to the rules of the

  23978.      current language.  If the optional length argument is given, the

  23979.      string will be converted to that length, and will include any

  23980.      embedded zeroes that the string may contain.  Otherwise, for

  23981.      languages where the string is zero-terminated, the entire string

  23982.      will be converted.

  23983. 

  23984.      For example, in C-like languages, a value is a string if it is a

  23985.      pointer to or an array of characters or ints of type 'wchar_t',

  23986.      'char16_t', or 'char32_t'.

  23987. 

  23988.      If the optional ENCODING argument is given, it must be a string

  23989.      naming the encoding of the string in the 'gdb.Value', such as

  23990.      '"ascii"', '"iso-8859-6"' or '"utf-8"'.  It accepts the same

  23991.      encodings as the corresponding argument to Python's 'string.decode'

  23992.      method, and the Python codec machinery will be used to convert the

  23993.      string.  If ENCODING is not given, or if ENCODING is the empty

  23994.      string, then either the 'target-charset' (*note Character Sets::)

  23995.      will be used, or a language-specific encoding will be used, if the

  23996.      current language is able to supply one.

  23997. 

  23998.      The optional ERRORS argument is the same as the corresponding

  23999.      argument to Python's 'string.decode' method.

  24000. 

  24001.      If the optional LENGTH argument is given, the string will be

  24002.      fetched and converted to the given length.

  24003. 

  24004.  -- Function: Value.lazy_string ([encoding [, length]])

  24005.      If this 'gdb.Value' represents a string, then this method converts

  24006.      the contents to a 'gdb.LazyString' (*note Lazy Strings In

  24007.      Python::).  Otherwise, this method will throw an exception.

  24008. 

  24009.      If the optional ENCODING argument is given, it must be a string

  24010.      naming the encoding of the 'gdb.LazyString'.  Some examples are:

  24011.      'ascii', 'iso-8859-6' or 'utf-8'.  If the ENCODING argument is an

  24012.      encoding that GDB does recognize, GDB will raise an error.

  24013. 

  24014.      When a lazy string is printed, the GDB encoding machinery is used

  24015.      to convert the string during printing.  If the optional ENCODING

  24016.      argument is not provided, or is an empty string, GDB will

  24017.      automatically select the encoding most suitable for the string

  24018.      type.  For further information on encoding in GDB please see *note

  24019.      Character Sets::.

  24020. 

  24021.      If the optional LENGTH argument is given, the string will be

  24022.      fetched and encoded to the length of characters specified.  If the

  24023.      LENGTH argument is not provided, the string will be fetched and

  24024.      encoded until a null of appropriate width is found.

  24025. 

  24026.  -- Function: Value.fetch_lazy ()

  24027.      If the 'gdb.Value' object is currently a lazy value

  24028.      ('gdb.Value.is_lazy' is 'True'), then the value is fetched from the

  24029.      inferior.  Any errors that occur in the process will produce a

  24030.      Python exception.

  24031. 

  24032.      If the 'gdb.Value' object is not a lazy value, this method has no

  24033.      effect.

  24034. 

  24035.      This method does not return a value.

  24036. 

  24037. 

  24038. File: gdb.info,  Node: Types In Python,  Next: Pretty Printing API,  Prev: Values From Inferior,  Up: Python API

  24039. 

  24040. 23.2.2.4 Types In Python

  24041. ........................

  24042. 

  24043. GDB represents types from the inferior using the class 'gdb.Type'.

  24044. 

  24045.    The following type-related functions are available in the 'gdb'

  24046. module:

  24047. 

  24048.  -- Function: gdb.lookup_type (name [, block])

  24049.      This function looks up a type by its NAME, which must be a string.

  24050. 

  24051.      If BLOCK is given, then NAME is looked up in that scope.

  24052.      Otherwise, it is searched for globally.

  24053. 

  24054.      Ordinarily, this function will return an instance of 'gdb.Type'.

  24055.      If the named type cannot be found, it will throw an exception.

  24056. 

  24057.    If the type is a structure or class type, or an enum type, the fields

  24058. of that type can be accessed using the Python "dictionary syntax".  For

  24059. example, if 'some_type' is a 'gdb.Type' instance holding a structure

  24060. type, you can access its 'foo' field with:

  24061. 

  24062.      bar = some_type['foo']

  24063. 

  24064.    'bar' will be a 'gdb.Field' object; see below under the description

  24065. of the 'Type.fields' method for a description of the 'gdb.Field' class.

  24066. 

  24067.    An instance of 'Type' has the following attributes:

  24068. 

  24069.  -- Variable: Type.alignof

  24070.      The alignment of this type, in bytes.  Type alignment comes from

  24071.      the debugging information; if it was not specified, then GDB will

  24072.      use the relevant ABI to try to determine the alignment.  In some

  24073.      cases, even this is not possible, and zero will be returned.

  24074. 

  24075.  -- Variable: Type.code

  24076.      The type code for this type.  The type code will be one of the

  24077.      'TYPE_CODE_' constants defined below.

  24078. 

  24079.  -- Variable: Type.dynamic

  24080.      A boolean indicating whether this type is dynamic.  In some

  24081.      situations, such as Rust 'enum' types or Ada variant records, the

  24082.      concrete type of a value may vary depending on its contents.  That

  24083.      is, the declared type of a variable, or the type returned by

  24084.      'gdb.lookup_type' may be dynamic; while the type of the variable's

  24085.      value will be a concrete instance of that dynamic type.

  24086. 

  24087.      For example, consider this code:

  24088.           int n;

  24089.           int array[n];

  24090. 

  24091.      Here, at least conceptually (whether your compiler actually does

  24092.      this is a separate issue), examining

  24093.      'gdb.lookup_symbol("array", ...).type' could yield a 'gdb.Type'

  24094.      which reports a size of 'None'.  This is the dynamic type.

  24095. 

  24096.      However, examining 'gdb.parse_and_eval("array").type' would yield a

  24097.      concrete type, whose length would be known.

  24098. 

  24099.  -- Variable: Type.name

  24100.      The name of this type.  If this type has no name, then 'None' is

  24101.      returned.

  24102. 

  24103.  -- Variable: Type.sizeof

  24104.      The size of this type, in target 'char' units.  Usually, a target's

  24105.      'char' type will be an 8-bit byte.  However, on some unusual

  24106.      platforms, this type may have a different size.  A dynamic type may

  24107.      not have a fixed size; in this case, this attribute's value will be

  24108.      'None'.

  24109. 

  24110.  -- Variable: Type.tag

  24111.      The tag name for this type.  The tag name is the name after

  24112.      'struct', 'union', or 'enum' in C and C++; not all languages have

  24113.      this concept.  If this type has no tag name, then 'None' is

  24114.      returned.

  24115. 

  24116.  -- Variable: Type.objfile

  24117.      The 'gdb.Objfile' that this type was defined in, or 'None' if there

  24118.      is no associated objfile.

  24119. 

  24120.    The following methods are provided:

  24121. 

  24122.  -- Function: Type.fields ()

  24123.      For structure and union types, this method returns the fields.

  24124.      Range types have two fields, the minimum and maximum values.  Enum

  24125.      types have one field per enum constant.  Function and method types

  24126.      have one field per parameter.  The base types of C++ classes are

  24127.      also represented as fields.  If the type has no fields, or does not

  24128.      fit into one of these categories, an empty sequence will be

  24129.      returned.

  24130. 

  24131.      Each field is a 'gdb.Field' object, with some pre-defined

  24132.      attributes:

  24133.      'bitpos'

  24134.           This attribute is not available for 'enum' or 'static' (as in

  24135.           C++) fields.  The value is the position, counting in bits,

  24136.           from the start of the containing type.  Note that, in a

  24137.           dynamic type, the position of a field may not be constant.  In

  24138.           this case, the value will be 'None'.  Also, a dynamic type may

  24139.           have fields that do not appear in a corresponding concrete

  24140.           type.

  24141. 

  24142.      'enumval'

  24143.           This attribute is only available for 'enum' fields, and its

  24144.           value is the enumeration member's integer representation.

  24145. 

  24146.      'name'

  24147.           The name of the field, or 'None' for anonymous fields.

  24148. 

  24149.      'artificial'

  24150.           This is 'True' if the field is artificial, usually meaning

  24151.           that it was provided by the compiler and not the user.  This

  24152.           attribute is always provided, and is 'False' if the field is

  24153.           not artificial.

  24154. 

  24155.      'is_base_class'

  24156.           This is 'True' if the field represents a base class of a C++

  24157.           structure.  This attribute is always provided, and is 'False'

  24158.           if the field is not a base class of the type that is the

  24159.           argument of 'fields', or if that type was not a C++ class.

  24160. 

  24161.      'bitsize'

  24162.           If the field is packed, or is a bitfield, then this will have

  24163.           a non-zero value, which is the size of the field in bits.

  24164.           Otherwise, this will be zero; in this case the field's size is

  24165.           given by its type.

  24166. 

  24167.      'type'

  24168.           The type of the field.  This is usually an instance of 'Type',

  24169.           but it can be 'None' in some situations.

  24170. 

  24171.      'parent_type'

  24172.           The type which contains this field.  This is an instance of

  24173.           'gdb.Type'.

  24174. 

  24175.  -- Function: Type.array (N1 [, N2])

  24176.      Return a new 'gdb.Type' object which represents an array of this

  24177.      type.  If one argument is given, it is the inclusive upper bound of

  24178.      the array; in this case the lower bound is zero.  If two arguments

  24179.      are given, the first argument is the lower bound of the array, and

  24180.      the second argument is the upper bound of the array.  An array's

  24181.      length must not be negative, but the bounds can be.

  24182. 

  24183.  -- Function: Type.vector (N1 [, N2])

  24184.      Return a new 'gdb.Type' object which represents a vector of this

  24185.      type.  If one argument is given, it is the inclusive upper bound of

  24186.      the vector; in this case the lower bound is zero.  If two arguments

  24187.      are given, the first argument is the lower bound of the vector, and

  24188.      the second argument is the upper bound of the vector.  A vector's

  24189.      length must not be negative, but the bounds can be.

  24190. 

  24191.      The difference between an 'array' and a 'vector' is that arrays

  24192.      behave like in C: when used in expressions they decay to a pointer

  24193.      to the first element whereas vectors are treated as first class

  24194.      values.

  24195. 

  24196.  -- Function: Type.const ()

  24197.      Return a new 'gdb.Type' object which represents a 'const'-qualified

  24198.      variant of this type.

  24199. 

  24200.  -- Function: Type.volatile ()

  24201.      Return a new 'gdb.Type' object which represents a

  24202.      'volatile'-qualified variant of this type.

  24203. 

  24204.  -- Function: Type.unqualified ()

  24205.      Return a new 'gdb.Type' object which represents an unqualified

  24206.      variant of this type.  That is, the result is neither 'const' nor

  24207.      'volatile'.

  24208. 

  24209.  -- Function: Type.range ()

  24210.      Return a Python 'Tuple' object that contains two elements: the low

  24211.      bound of the argument type and the high bound of that type.  If the

  24212.      type does not have a range, GDB will raise a 'gdb.error' exception

  24213.      (*note Exception Handling::).

  24214. 

  24215.  -- Function: Type.reference ()

  24216.      Return a new 'gdb.Type' object which represents a reference to this

  24217.      type.

  24218. 

  24219.  -- Function: Type.pointer ()

  24220.      Return a new 'gdb.Type' object which represents a pointer to this

  24221.      type.

  24222. 

  24223.  -- Function: Type.strip_typedefs ()

  24224.      Return a new 'gdb.Type' that represents the real type, after

  24225.      removing all layers of typedefs.

  24226. 

  24227.  -- Function: Type.target ()

  24228.      Return a new 'gdb.Type' object which represents the target type of

  24229.      this type.

  24230. 

  24231.      For a pointer type, the target type is the type of the pointed-to

  24232.      object.  For an array type (meaning C-like arrays), the target type

  24233.      is the type of the elements of the array.  For a function or method

  24234.      type, the target type is the type of the return value.  For a

  24235.      complex type, the target type is the type of the elements.  For a

  24236.      typedef, the target type is the aliased type.

  24237. 

  24238.      If the type does not have a target, this method will throw an

  24239.      exception.

  24240. 

  24241.  -- Function: Type.template_argument (n [, block])

  24242.      If this 'gdb.Type' is an instantiation of a template, this will

  24243.      return a new 'gdb.Value' or 'gdb.Type' which represents the value

  24244.      of the Nth template argument (indexed starting at 0).

  24245. 

  24246.      If this 'gdb.Type' is not a template type, or if the type has fewer

  24247.      than N template arguments, this will throw an exception.

  24248.      Ordinarily, only C++ code will have template types.

  24249. 

  24250.      If BLOCK is given, then NAME is looked up in that scope.

  24251.      Otherwise, it is searched for globally.

  24252. 

  24253.  -- Function: Type.optimized_out ()

  24254.      Return 'gdb.Value' instance of this type whose value is optimized

  24255.      out.  This allows a frame decorator to indicate that the value of

  24256.      an argument or a local variable is not known.

  24257. 

  24258.    Each type has a code, which indicates what category this type falls

  24259. into.  The available type categories are represented by constants

  24260. defined in the 'gdb' module:

  24261. 

  24262. 'gdb.TYPE_CODE_PTR'

  24263.      The type is a pointer.

  24264. 

  24265. 'gdb.TYPE_CODE_ARRAY'

  24266.      The type is an array.

  24267. 

  24268. 'gdb.TYPE_CODE_STRUCT'

  24269.      The type is a structure.

  24270. 

  24271. 'gdb.TYPE_CODE_UNION'

  24272.      The type is a union.

  24273. 

  24274. 'gdb.TYPE_CODE_ENUM'

  24275.      The type is an enum.

  24276. 

  24277. 'gdb.TYPE_CODE_FLAGS'

  24278.      A bit flags type, used for things such as status registers.

  24279. 

  24280. 'gdb.TYPE_CODE_FUNC'

  24281.      The type is a function.

  24282. 

  24283. 'gdb.TYPE_CODE_INT'

  24284.      The type is an integer type.

  24285. 

  24286. 'gdb.TYPE_CODE_FLT'

  24287.      A floating point type.

  24288. 

  24289. 'gdb.TYPE_CODE_VOID'

  24290.      The special type 'void'.

  24291. 

  24292. 'gdb.TYPE_CODE_SET'

  24293.      A Pascal set type.

  24294. 

  24295. 'gdb.TYPE_CODE_RANGE'

  24296.      A range type, that is, an integer type with bounds.

  24297. 

  24298. 'gdb.TYPE_CODE_STRING'

  24299.      A string type.  Note that this is only used for certain languages

  24300.      with language-defined string types; C strings are not represented

  24301.      this way.

  24302. 

  24303. 'gdb.TYPE_CODE_BITSTRING'

  24304.      A string of bits.  It is deprecated.

  24305. 

  24306. 'gdb.TYPE_CODE_ERROR'

  24307.      An unknown or erroneous type.

  24308. 

  24309. 'gdb.TYPE_CODE_METHOD'

  24310.      A method type, as found in C++.

  24311. 

  24312. 'gdb.TYPE_CODE_METHODPTR'

  24313.      A pointer-to-member-function.

  24314. 

  24315. 'gdb.TYPE_CODE_MEMBERPTR'

  24316.      A pointer-to-member.

  24317. 

  24318. 'gdb.TYPE_CODE_REF'

  24319.      A reference type.

  24320. 

  24321. 'gdb.TYPE_CODE_RVALUE_REF'

  24322.      A C++11 rvalue reference type.

  24323. 

  24324. 'gdb.TYPE_CODE_CHAR'

  24325.      A character type.

  24326. 

  24327. 'gdb.TYPE_CODE_BOOL'

  24328.      A boolean type.

  24329. 

  24330. 'gdb.TYPE_CODE_COMPLEX'

  24331.      A complex float type.

  24332. 

  24333. 'gdb.TYPE_CODE_TYPEDEF'

  24334.      A typedef to some other type.

  24335. 

  24336. 'gdb.TYPE_CODE_NAMESPACE'

  24337.      A C++ namespace.

  24338. 

  24339. 'gdb.TYPE_CODE_DECFLOAT'

  24340.      A decimal floating point type.

  24341. 

  24342. 'gdb.TYPE_CODE_INTERNAL_FUNCTION'

  24343.      A function internal to GDB.  This is the type used to represent

  24344.      convenience functions.

  24345. 

  24346.    Further support for types is provided in the 'gdb.types' Python

  24347. module (*note gdb.types::).

  24348. 

  24349. 

  24350. File: gdb.info,  Node: Pretty Printing API,  Next: Selecting Pretty-Printers,  Prev: Types In Python,  Up: Python API

  24351. 

  24352. 23.2.2.5 Pretty Printing API

  24353. ............................

  24354. 

  24355. A pretty-printer is just an object that holds a value and implements a

  24356. specific interface, defined here.  An example output is provided (*note

  24357. Pretty Printing::).

  24358. 

  24359.  -- Function: pretty_printer.children (self)

  24360.      GDB will call this method on a pretty-printer to compute the

  24361.      children of the pretty-printer's value.

  24362. 

  24363.      This method must return an object conforming to the Python iterator

  24364.      protocol.  Each item returned by the iterator must be a tuple

  24365.      holding two elements.  The first element is the "name" of the

  24366.      child; the second element is the child's value.  The value can be

  24367.      any Python object which is convertible to a GDB value.

  24368. 

  24369.      This method is optional.  If it does not exist, GDB will act as

  24370.      though the value has no children.

  24371. 

  24372.      For efficiency, the 'children' method should lazily compute its

  24373.      results.  This will let GDB read as few elements as necessary, for

  24374.      example when various print settings (*note Print Settings::) or

  24375.      '-var-list-children' (*note GDB/MI Variable Objects::) limit the

  24376.      number of elements to be displayed.

  24377. 

  24378.      Children may be hidden from display based on the value of 'set

  24379.      print max-depth' (*note Print Settings::).

  24380. 

  24381.  -- Function: pretty_printer.display_hint (self)

  24382.      The CLI may call this method and use its result to change the

  24383.      formatting of a value.  The result will also be supplied to an MI

  24384.      consumer as a 'displayhint' attribute of the variable being

  24385.      printed.

  24386. 

  24387.      This method is optional.  If it does exist, this method must return

  24388.      a string or the special value 'None'.

  24389. 

  24390.      Some display hints are predefined by GDB:

  24391. 

  24392.      'array'

  24393.           Indicate that the object being printed is "array-like".  The

  24394.           CLI uses this to respect parameters such as 'set print

  24395.           elements' and 'set print array'.

  24396. 

  24397.      'map'

  24398.           Indicate that the object being printed is "map-like", and that

  24399.           the children of this value can be assumed to alternate between

  24400.           keys and values.

  24401. 

  24402.      'string'

  24403.           Indicate that the object being printed is "string-like".  If

  24404.           the printer's 'to_string' method returns a Python string of

  24405.           some kind, then GDB will call its internal language-specific

  24406.           string-printing function to format the string.  For the CLI

  24407.           this means adding quotation marks, possibly escaping some

  24408.           characters, respecting 'set print elements', and the like.

  24409. 

  24410.      The special value 'None' causes GDB to apply the default display

  24411.      rules.

  24412. 

  24413.  -- Function: pretty_printer.to_string (self)

  24414.      GDB will call this method to display the string representation of

  24415.      the value passed to the object's constructor.

  24416. 

  24417.      When printing from the CLI, if the 'to_string' method exists, then

  24418.      GDB will prepend its result to the values returned by 'children'.

  24419.      Exactly how this formatting is done is dependent on the display

  24420.      hint, and may change as more hints are added.  Also, depending on

  24421.      the print settings (*note Print Settings::), the CLI may print just

  24422.      the result of 'to_string' in a stack trace, omitting the result of

  24423.      'children'.

  24424. 

  24425.      If this method returns a string, it is printed verbatim.

  24426. 

  24427.      Otherwise, if this method returns an instance of 'gdb.Value', then

  24428.      GDB prints this value.  This may result in a call to another

  24429.      pretty-printer.

  24430. 

  24431.      If instead the method returns a Python value which is convertible

  24432.      to a 'gdb.Value', then GDB performs the conversion and prints the

  24433.      resulting value.  Again, this may result in a call to another

  24434.      pretty-printer.  Python scalars (integers, floats, and booleans)

  24435.      and strings are convertible to 'gdb.Value'; other types are not.

  24436. 

  24437.      Finally, if this method returns 'None' then no further operations

  24438.      are peformed in this method and nothing is printed.

  24439. 

  24440.      If the result is not one of these types, an exception is raised.

  24441. 

  24442.    GDB provides a function which can be used to look up the default

  24443. pretty-printer for a 'gdb.Value':

  24444. 

  24445.  -- Function: gdb.default_visualizer (value)

  24446.      This function takes a 'gdb.Value' object as an argument.  If a

  24447.      pretty-printer for this value exists, then it is returned.  If no

  24448.      such printer exists, then this returns 'None'.

  24449. 

  24450. 

  24451. File: gdb.info,  Node: Selecting Pretty-Printers,  Next: Writing a Pretty-Printer,  Prev: Pretty Printing API,  Up: Python API

  24452. 

  24453. 23.2.2.6 Selecting Pretty-Printers

  24454. ..................................

  24455. 

  24456. GDB provides several ways to register a pretty-printer: globally, per

  24457. program space, and per objfile.  When choosing how to register your

  24458. pretty-printer, a good rule is to register it with the smallest scope

  24459. possible: that is prefer a specific objfile first, then a program space,

  24460. and only register a printer globally as a last resort.

  24461. 

  24462.  -- Variable: gdb.pretty_printers

  24463.      The Python list 'gdb.pretty_printers' contains an array of

  24464.      functions or callable objects that have been registered via

  24465.      addition as a pretty-printer.  Printers in this list are called

  24466.      'global' printers, they're available when debugging all inferiors.

  24467. 

  24468.    Each 'gdb.Progspace' contains a 'pretty_printers' attribute.  Each

  24469. 'gdb.Objfile' also contains a 'pretty_printers' attribute.

  24470. 

  24471.    Each function on these lists is passed a single 'gdb.Value' argument

  24472. and should return a pretty-printer object conforming to the interface

  24473. definition above (*note Pretty Printing API::).  If a function cannot

  24474. create a pretty-printer for the value, it should return 'None'.

  24475. 

  24476.    GDB first checks the 'pretty_printers' attribute of each

  24477. 'gdb.Objfile' in the current program space and iteratively calls each

  24478. enabled lookup routine in the list for that 'gdb.Objfile' until it

  24479. receives a pretty-printer object.  If no pretty-printer is found in the

  24480. objfile lists, GDB then searches the pretty-printer list of the current

  24481. program space, calling each enabled function until an object is

  24482. returned.  After these lists have been exhausted, it tries the global

  24483. 'gdb.pretty_printers' list, again calling each enabled function until an

  24484. object is returned.

  24485. 

  24486.    The order in which the objfiles are searched is not specified.  For a

  24487. given list, functions are always invoked from the head of the list, and

  24488. iterated over sequentially until the end of the list, or a printer

  24489. object is returned.

  24490. 

  24491.    For various reasons a pretty-printer may not work.  For example, the

  24492. underlying data structure may have changed and the pretty-printer is out

  24493. of date.

  24494. 

  24495.    The consequences of a broken pretty-printer are severe enough that

  24496. GDB provides support for enabling and disabling individual printers.

  24497. For example, if 'print frame-arguments' is on, a backtrace can become

  24498. highly illegible if any argument is printed with a broken printer.

  24499. 

  24500.    Pretty-printers are enabled and disabled by attaching an 'enabled'

  24501. attribute to the registered function or callable object.  If this

  24502. attribute is present and its value is 'False', the printer is disabled,

  24503. otherwise the printer is enabled.

  24504. 

  24505. 

  24506. File: gdb.info,  Node: Writing a Pretty-Printer,  Next: Type Printing API,  Prev: Selecting Pretty-Printers,  Up: Python API

  24507. 

  24508. 23.2.2.7 Writing a Pretty-Printer

  24509. .................................

  24510. 

  24511. A pretty-printer consists of two parts: a lookup function to detect if

  24512. the type is supported, and the printer itself.

  24513. 

  24514.    Here is an example showing how a 'std::string' printer might be

  24515. written.  *Note Pretty Printing API::, for details on the API this class

  24516. must provide.

  24517. 

  24518.      class StdStringPrinter(object):

  24519.          "Print a std::string"

  24520. 

  24521.          def __init__(self, val):

  24522.              self.val = val

  24523. 

  24524.          def to_string(self):

  24525.              return self.val['_M_dataplus']['_M_p']

  24526. 

  24527.          def display_hint(self):

  24528.              return 'string'

  24529. 

  24530.    And here is an example showing how a lookup function for the printer

  24531. example above might be written.

  24532. 

  24533.      def str_lookup_function(val):

  24534.          lookup_tag = val.type.tag

  24535.          if lookup_tag == None:

  24536.              return None

  24537.          regex = re.compile("^std::basic_string<char,.*>$")

  24538.          if regex.match(lookup_tag):

  24539.              return StdStringPrinter(val)

  24540.          return None

  24541. 

  24542.    The example lookup function extracts the value's type, and attempts

  24543. to match it to a type that it can pretty-print.  If it is a type the

  24544. printer can pretty-print, it will return a printer object.  If not, it

  24545. returns 'None'.

  24546. 

  24547.    We recommend that you put your core pretty-printers into a Python

  24548. package.  If your pretty-printers are for use with a library, we further

  24549. recommend embedding a version number into the package name.  This

  24550. practice will enable GDB to load multiple versions of your

  24551. pretty-printers at the same time, because they will have different

  24552. names.

  24553. 

  24554.    You should write auto-loaded code (*note Python Auto-loading::) such

  24555. that it can be evaluated multiple times without changing its meaning.

  24556. An ideal auto-load file will consist solely of 'import's of your printer

  24557. modules, followed by a call to a register pretty-printers with the

  24558. current objfile.

  24559. 

  24560.    Taken as a whole, this approach will scale nicely to multiple

  24561. inferiors, each potentially using a different library version.

  24562. Embedding a version number in the Python package name will ensure that

  24563. GDB is able to load both sets of printers simultaneously.  Then, because

  24564. the search for pretty-printers is done by objfile, and because your

  24565. auto-loaded code took care to register your library's printers with a

  24566. specific objfile, GDB will find the correct printers for the specific

  24567. version of the library used by each inferior.

  24568. 

  24569.    To continue the 'std::string' example (*note Pretty Printing API::),

  24570. this code might appear in 'gdb.libstdcxx.v6':

  24571. 

  24572.      def register_printers(objfile):

  24573.          objfile.pretty_printers.append(str_lookup_function)

  24574. 

  24575. And then the corresponding contents of the auto-load file would be:

  24576. 

  24577.      import gdb.libstdcxx.v6

  24578.      gdb.libstdcxx.v6.register_printers(gdb.current_objfile())

  24579. 

  24580.    The previous example illustrates a basic pretty-printer.  There are a

  24581. few things that can be improved on.  The printer doesn't have a name,

  24582. making it hard to identify in a list of installed printers.  The lookup

  24583. function has a name, but lookup functions can have arbitrary, even

  24584. identical, names.

  24585. 

  24586.    Second, the printer only handles one type, whereas a library

  24587. typically has several types.  One could install a lookup function for

  24588. each desired type in the library, but one could also have a single

  24589. lookup function recognize several types.  The latter is the conventional

  24590. way this is handled.  If a pretty-printer can handle multiple data

  24591. types, then its "subprinters" are the printers for the individual data

  24592. types.

  24593. 

  24594.    The 'gdb.printing' module provides a formal way of solving these

  24595. problems (*note gdb.printing::).  Here is another example that handles

  24596. multiple types.

  24597. 

  24598.    These are the types we are going to pretty-print:

  24599. 

  24600.      struct foo { int a, b; };

  24601.      struct bar { struct foo x, y; };

  24602. 

  24603.    Here are the printers:

  24604. 

  24605.      class fooPrinter:

  24606.          """Print a foo object."""

  24607. 

  24608.          def __init__(self, val):

  24609.              self.val = val

  24610. 

  24611.          def to_string(self):

  24612.              return ("a=<" + str(self.val["a"]) +

  24613.                      "> b=<" + str(self.val["b"]) + ">")

  24614. 

  24615.      class barPrinter:

  24616.          """Print a bar object."""

  24617. 

  24618.          def __init__(self, val):

  24619.              self.val = val

  24620. 

  24621.          def to_string(self):

  24622.              return ("x=<" + str(self.val["x"]) +

  24623.                      "> y=<" + str(self.val["y"]) + ">")

  24624. 

  24625.    This example doesn't need a lookup function, that is handled by the

  24626. 'gdb.printing' module.  Instead a function is provided to build up the

  24627. object that handles the lookup.

  24628. 

  24629.      import gdb.printing

  24630. 

  24631.      def build_pretty_printer():

  24632.          pp = gdb.printing.RegexpCollectionPrettyPrinter(

  24633.              "my_library")

  24634.          pp.add_printer('foo', '^foo$', fooPrinter)

  24635.          pp.add_printer('bar', '^bar$', barPrinter)

  24636.          return pp

  24637. 

  24638.    And here is the autoload support:

  24639. 

  24640.      import gdb.printing

  24641.      import my_library

  24642.      gdb.printing.register_pretty_printer(

  24643.          gdb.current_objfile(),

  24644.          my_library.build_pretty_printer())

  24645. 

  24646.    Finally, when this printer is loaded into GDB, here is the

  24647. corresponding output of 'info pretty-printer':

  24648. 

  24649.      (gdb) info pretty-printer

  24650.      my_library.so:

  24651.        my_library

  24652.          foo

  24653.          bar

  24654. 

  24655. 

  24656. File: gdb.info,  Node: Type Printing API,  Next: Frame Filter API,  Prev: Writing a Pretty-Printer,  Up: Python API

  24657. 

  24658. 23.2.2.8 Type Printing API

  24659. ..........................

  24660. 

  24661. GDB provides a way for Python code to customize type display.  This is

  24662. mainly useful for substituting canonical typedef names for types.

  24663. 

  24664.    A "type printer" is just a Python object conforming to a certain

  24665. protocol.  A simple base class implementing the protocol is provided;

  24666. see *note gdb.types::.  A type printer must supply at least:

  24667. 

  24668.  -- Instance Variable of type_printer: enabled

  24669.      A boolean which is True if the printer is enabled, and False

  24670.      otherwise.  This is manipulated by the 'enable type-printer' and

  24671.      'disable type-printer' commands.

  24672. 

  24673.  -- Instance Variable of type_printer: name

  24674.      The name of the type printer.  This must be a string.  This is used

  24675.      by the 'enable type-printer' and 'disable type-printer' commands.

  24676. 

  24677.  -- Method on type_printer: instantiate (self)

  24678.      This is called by GDB at the start of type-printing.  It is only

  24679.      called if the type printer is enabled.  This method must return a

  24680.      new object that supplies a 'recognize' method, as described below.

  24681. 

  24682.    When displaying a type, say via the 'ptype' command, GDB will compute

  24683. a list of type recognizers.  This is done by iterating first over the

  24684. per-objfile type printers (*note Objfiles In Python::), followed by the

  24685. per-progspace type printers (*note Progspaces In Python::), and finally

  24686. the global type printers.

  24687. 

  24688.    GDB will call the 'instantiate' method of each enabled type printer.

  24689. If this method returns 'None', then the result is ignored; otherwise, it

  24690. is appended to the list of recognizers.

  24691. 

  24692.    Then, when GDB is going to display a type name, it iterates over the

  24693. list of recognizers.  For each one, it calls the recognition function,

  24694. stopping if the function returns a non-'None' value.  The recognition

  24695. function is defined as:

  24696. 

  24697.  -- Method on type_recognizer: recognize (self, type)

  24698.      If TYPE is not recognized, return 'None'.  Otherwise, return a

  24699.      string which is to be printed as the name of TYPE.  The TYPE

  24700.      argument will be an instance of 'gdb.Type' (*note Types In

  24701.      Python::).

  24702. 

  24703.    GDB uses this two-pass approach so that type printers can efficiently

  24704. cache information without holding on to it too long.  For example, it

  24705. can be convenient to look up type information in a type printer and hold

  24706. it for a recognizer's lifetime; if a single pass were done then type

  24707. printers would have to make use of the event system in order to avoid

  24708. holding information that could become stale as the inferior changed.

  24709. 

  24710. 

  24711. File: gdb.info,  Node: Frame Filter API,  Next: Frame Decorator API,  Prev: Type Printing API,  Up: Python API

  24712. 

  24713. 23.2.2.9 Filtering Frames

  24714. .........................

  24715. 

  24716. Frame filters are Python objects that manipulate the visibility of a

  24717. frame or frames when a backtrace (*note Backtrace::) is printed by GDB.

  24718. 

  24719.    Only commands that print a backtrace, or, in the case of GDB/MI

  24720. commands (*note GDB/MI::), those that return a collection of frames are

  24721. affected.  The commands that work with frame filters are:

  24722. 

  24723.    'backtrace' (*note The backtrace command: backtrace-command.),

  24724. '-stack-list-frames' (*note The -stack-list-frames command:

  24725. -stack-list-frames.), '-stack-list-variables' (*note The

  24726. -stack-list-variables command: -stack-list-variables.),

  24727. '-stack-list-arguments' *note The -stack-list-arguments command:

  24728. -stack-list-arguments.) and '-stack-list-locals' (*note The

  24729. -stack-list-locals command: -stack-list-locals.).

  24730. 

  24731.    A frame filter works by taking an iterator as an argument, applying

  24732. actions to the contents of that iterator, and returning another iterator

  24733. (or, possibly, the same iterator it was provided in the case where the

  24734. filter does not perform any operations).  Typically, frame filters

  24735. utilize tools such as the Python's 'itertools' module to work with and

  24736. create new iterators from the source iterator.  Regardless of how a

  24737. filter chooses to apply actions, it must not alter the underlying GDB

  24738. frame or frames, or attempt to alter the call-stack within GDB.  This

  24739. preserves data integrity within GDB.  Frame filters are executed on a

  24740. priority basis and care should be taken that some frame filters may have

  24741. been executed before, and that some frame filters will be executed

  24742. after.

  24743. 

  24744.    An important consideration when designing frame filters, and well

  24745. worth reflecting upon, is that frame filters should avoid unwinding the

  24746. call stack if possible.  Some stacks can run very deep, into the tens of

  24747. thousands in some cases.  To search every frame when a frame filter

  24748. executes may be too expensive at that step.  The frame filter cannot

  24749. know how many frames it has to iterate over, and it may have to iterate

  24750. through them all.  This ends up duplicating effort as GDB performs this

  24751. iteration when it prints the frames.  If the filter can defer unwinding

  24752. frames until frame decorators are executed, after the last filter has

  24753. executed, it should.  *Note Frame Decorator API::, for more information

  24754. on decorators.  Also, there are examples for both frame decorators and

  24755. filters in later chapters.  *Note Writing a Frame Filter::, for more

  24756. information.

  24757. 

  24758.    The Python dictionary 'gdb.frame_filters' contains key/object

  24759. pairings that comprise a frame filter.  Frame filters in this dictionary

  24760. are called 'global' frame filters, and they are available when debugging

  24761. all inferiors.  These frame filters must register with the dictionary

  24762. directly.  In addition to the 'global' dictionary, there are other

  24763. dictionaries that are loaded with different inferiors via auto-loading

  24764. (*note Python Auto-loading::).  The two other areas where frame filter

  24765. dictionaries can be found are: 'gdb.Progspace' which contains a

  24766. 'frame_filters' dictionary attribute, and each 'gdb.Objfile' object

  24767. which also contains a 'frame_filters' dictionary attribute.

  24768. 

  24769.    When a command is executed from GDB that is compatible with frame

  24770. filters, GDB combines the 'global', 'gdb.Progspace' and all

  24771. 'gdb.Objfile' dictionaries currently loaded.  All of the 'gdb.Objfile'

  24772. dictionaries are combined, as several frames, and thus several object

  24773. files, might be in use.  GDB then prunes any frame filter whose

  24774. 'enabled' attribute is 'False'.  This pruned list is then sorted

  24775. according to the 'priority' attribute in each filter.

  24776. 

  24777.    Once the dictionaries are combined, pruned and sorted, GDB creates an

  24778. iterator which wraps each frame in the call stack in a 'FrameDecorator'

  24779. object, and calls each filter in order.  The output from the previous

  24780. filter will always be the input to the next filter, and so on.

  24781. 

  24782.    Frame filters have a mandatory interface which each frame filter must

  24783. implement, defined here:

  24784. 

  24785.  -- Function: FrameFilter.filter (iterator)

  24786.      GDB will call this method on a frame filter when it has reached the

  24787.      order in the priority list for that filter.

  24788. 

  24789.      For example, if there are four frame filters:

  24790. 

  24791.           Name         Priority

  24792. 

  24793.           Filter1      5

  24794.           Filter2      10

  24795.           Filter3      100

  24796.           Filter4      1

  24797. 

  24798.      The order that the frame filters will be called is:

  24799. 

  24800.           Filter3 -> Filter2 -> Filter1 -> Filter4

  24801. 

  24802.      Note that the output from 'Filter3' is passed to the input of

  24803.      'Filter2', and so on.

  24804. 

  24805.      This 'filter' method is passed a Python iterator.  This iterator

  24806.      contains a sequence of frame decorators that wrap each 'gdb.Frame',

  24807.      or a frame decorator that wraps another frame decorator.  The first

  24808.      filter that is executed in the sequence of frame filters will

  24809.      receive an iterator entirely comprised of default 'FrameDecorator'

  24810.      objects.  However, after each frame filter is executed, the

  24811.      previous frame filter may have wrapped some or all of the frame

  24812.      decorators with their own frame decorator.  As frame decorators

  24813.      must also conform to a mandatory interface, these decorators can be

  24814.      assumed to act in a uniform manner (*note Frame Decorator API::).

  24815. 

  24816.      This method must return an object conforming to the Python iterator

  24817.      protocol.  Each item in the iterator must be an object conforming

  24818.      to the frame decorator interface.  If a frame filter does not wish

  24819.      to perform any operations on this iterator, it should return that

  24820.      iterator untouched.

  24821. 

  24822.      This method is not optional.  If it does not exist, GDB will raise

  24823.      and print an error.

  24824. 

  24825.  -- Variable: FrameFilter.name

  24826.      The 'name' attribute must be Python string which contains the name

  24827.      of the filter displayed by GDB (*note Frame Filter Management::).

  24828.      This attribute may contain any combination of letters or numbers.

  24829.      Care should be taken to ensure that it is unique.  This attribute

  24830.      is mandatory.

  24831. 

  24832.  -- Variable: FrameFilter.enabled

  24833.      The 'enabled' attribute must be Python boolean.  This attribute

  24834.      indicates to GDB whether the frame filter is enabled, and should be

  24835.      considered when frame filters are executed.  If 'enabled' is

  24836.      'True', then the frame filter will be executed when any of the

  24837.      backtrace commands detailed earlier in this chapter are executed.

  24838.      If 'enabled' is 'False', then the frame filter will not be

  24839.      executed.  This attribute is mandatory.

  24840. 

  24841.  -- Variable: FrameFilter.priority

  24842.      The 'priority' attribute must be Python integer.  This attribute

  24843.      controls the order of execution in relation to other frame filters.

  24844.      There are no imposed limits on the range of 'priority' other than

  24845.      it must be a valid integer.  The higher the 'priority' attribute,

  24846.      the sooner the frame filter will be executed in relation to other

  24847.      frame filters.  Although 'priority' can be negative, it is

  24848.      recommended practice to assume zero is the lowest priority that a

  24849.      frame filter can be assigned.  Frame filters that have the same

  24850.      priority are executed in unsorted order in that priority slot.

  24851.      This attribute is mandatory.  100 is a good default priority.

  24852. 

  24853. 

  24854. File: gdb.info,  Node: Frame Decorator API,  Next: Writing a Frame Filter,  Prev: Frame Filter API,  Up: Python API

  24855. 

  24856. 23.2.2.10 Decorating Frames

  24857. ...........................

  24858. 

  24859. Frame decorators are sister objects to frame filters (*note Frame Filter

  24860. API::).  Frame decorators are applied by a frame filter and can only be

  24861. used in conjunction with frame filters.

  24862. 

  24863.    The purpose of a frame decorator is to customize the printed content

  24864. of each 'gdb.Frame' in commands where frame filters are executed.  This

  24865. concept is called decorating a frame.  Frame decorators decorate a

  24866. 'gdb.Frame' with Python code contained within each API call.  This

  24867. separates the actual data contained in a 'gdb.Frame' from the decorated

  24868. data produced by a frame decorator.  This abstraction is necessary to

  24869. maintain integrity of the data contained in each 'gdb.Frame'.

  24870. 

  24871.    Frame decorators have a mandatory interface, defined below.

  24872. 

  24873.    GDB already contains a frame decorator called 'FrameDecorator'.  This

  24874. contains substantial amounts of boilerplate code to decorate the content

  24875. of a 'gdb.Frame'.  It is recommended that other frame decorators inherit

  24876. and extend this object, and only to override the methods needed.

  24877. 

  24878.    'FrameDecorator' is defined in the Python module

  24879. 'gdb.FrameDecorator', so your code can import it like:

  24880.      from gdb.FrameDecorator import FrameDecorator

  24881. 

  24882.  -- Function: FrameDecorator.elided (self)

  24883. 

  24884.      The 'elided' method groups frames together in a hierarchical

  24885.      system.  An example would be an interpreter, where multiple

  24886.      low-level frames make up a single call in the interpreted language.

  24887.      In this example, the frame filter would elide the low-level frames

  24888.      and present a single high-level frame, representing the call in the

  24889.      interpreted language, to the user.

  24890. 

  24891.      The 'elided' function must return an iterable and this iterable

  24892.      must contain the frames that are being elided wrapped in a suitable

  24893.      frame decorator.  If no frames are being elided this function may

  24894.      return an empty iterable, or 'None'.  Elided frames are indented

  24895.      from normal frames in a 'CLI' backtrace, or in the case of

  24896.      'GDB/MI', are placed in the 'children' field of the eliding frame.

  24897. 

  24898.      It is the frame filter's task to also filter out the elided frames

  24899.      from the source iterator.  This will avoid printing the frame

  24900.      twice.

  24901. 

  24902.  -- Function: FrameDecorator.function (self)

  24903. 

  24904.      This method returns the name of the function in the frame that is

  24905.      to be printed.

  24906. 

  24907.      This method must return a Python string describing the function, or

  24908.      'None'.

  24909. 

  24910.      If this function returns 'None', GDB will not print any data for

  24911.      this field.

  24912. 

  24913.  -- Function: FrameDecorator.address (self)

  24914. 

  24915.      This method returns the address of the frame that is to be printed.

  24916. 

  24917.      This method must return a Python numeric integer type of sufficient

  24918.      size to describe the address of the frame, or 'None'.

  24919. 

  24920.      If this function returns a 'None', GDB will not print any data for

  24921.      this field.

  24922. 

  24923.  -- Function: FrameDecorator.filename (self)

  24924. 

  24925.      This method returns the filename and path associated with this

  24926.      frame.

  24927. 

  24928.      This method must return a Python string containing the filename and

  24929.      the path to the object file backing the frame, or 'None'.

  24930. 

  24931.      If this function returns a 'None', GDB will not print any data for

  24932.      this field.

  24933. 

  24934.  -- Function: FrameDecorator.line (self):

  24935. 

  24936.      This method returns the line number associated with the current

  24937.      position within the function addressed by this frame.

  24938. 

  24939.      This method must return a Python integer type, or 'None'.

  24940. 

  24941.      If this function returns a 'None', GDB will not print any data for

  24942.      this field.

  24943. 

  24944.  -- Function: FrameDecorator.frame_args (self)

  24945. 

  24946.      This method must return an iterable, or 'None'.  Returning an empty

  24947.      iterable, or 'None' means frame arguments will not be printed for

  24948.      this frame.  This iterable must contain objects that implement two

  24949.      methods, described here.

  24950. 

  24951.      This object must implement a 'argument' method which takes a single

  24952.      'self' parameter and must return a 'gdb.Symbol' (*note Symbols In

  24953.      Python::), or a Python string.  The object must also implement a

  24954.      'value' method which takes a single 'self' parameter and must

  24955.      return a 'gdb.Value' (*note Values From Inferior::), a Python

  24956.      value, or 'None'.  If the 'value' method returns 'None', and the

  24957.      'argument' method returns a 'gdb.Symbol', GDB will look-up and

  24958.      print the value of the 'gdb.Symbol' automatically.

  24959. 

  24960.      A brief example:

  24961. 

  24962.           class SymValueWrapper():

  24963. 

  24964.               def __init__(self, symbol, value):

  24965.                   self.sym = symbol

  24966.                   self.val = value

  24967. 

  24968.               def value(self):

  24969.                   return self.val

  24970. 

  24971.               def symbol(self):

  24972.                   return self.sym

  24973. 

  24974.           class SomeFrameDecorator()

  24975.           ...

  24976.           ...

  24977.               def frame_args(self):

  24978.                   args = []

  24979.                   try:

  24980.                       block = self.inferior_frame.block()

  24981.                   except:

  24982.                       return None

  24983. 

  24984.                   # Iterate over all symbols in a block.  Only add

  24985.                   # symbols that are arguments.

  24986.                   for sym in block:

  24987.                       if not sym.is_argument:

  24988.                           continue

  24989.                       args.append(SymValueWrapper(sym,None))

  24990. 

  24991.                   # Add example synthetic argument.

  24992.                   args.append(SymValueWrapper(``foo'', 42))

  24993. 

  24994.                   return args

  24995. 

  24996.  -- Function: FrameDecorator.frame_locals (self)

  24997. 

  24998.      This method must return an iterable or 'None'.  Returning an empty

  24999.      iterable, or 'None' means frame local arguments will not be printed

  25000.      for this frame.

  25001. 

  25002.      The object interface, the description of the various strategies for

  25003.      reading frame locals, and the example are largely similar to those

  25004.      described in the 'frame_args' function, (*note The frame filter

  25005.      frame_args function: frame_args.).  Below is a modified example:

  25006. 

  25007.           class SomeFrameDecorator()

  25008.           ...

  25009.           ...

  25010.               def frame_locals(self):

  25011.                   vars = []

  25012.                   try:

  25013.                       block = self.inferior_frame.block()

  25014.                   except:

  25015.                       return None

  25016. 

  25017.                   # Iterate over all symbols in a block.  Add all

  25018.                   # symbols, except arguments.

  25019.                   for sym in block:

  25020.                       if sym.is_argument:

  25021.                           continue

  25022.                       vars.append(SymValueWrapper(sym,None))

  25023. 

  25024.                   # Add an example of a synthetic local variable.

  25025.                   vars.append(SymValueWrapper(``bar'', 99))

  25026. 

  25027.                   return vars

  25028. 

  25029.  -- Function: FrameDecorator.inferior_frame (self):

  25030. 

  25031.      This method must return the underlying 'gdb.Frame' that this frame

  25032.      decorator is decorating.  GDB requires the underlying frame for

  25033.      internal frame information to determine how to print certain values

  25034.      when printing a frame.

  25035. 

  25036. 

  25037. File: gdb.info,  Node: Writing a Frame Filter,  Next: Unwinding Frames in Python,  Prev: Frame Decorator API,  Up: Python API

  25038. 

  25039. 23.2.2.11 Writing a Frame Filter

  25040. ................................

  25041. 

  25042. There are three basic elements that a frame filter must implement: it

  25043. must correctly implement the documented interface (*note Frame Filter

  25044. API::), it must register itself with GDB, and finally, it must decide if

  25045. it is to work on the data provided by GDB.  In all cases, whether it

  25046. works on the iterator or not, each frame filter must return an iterator.

  25047. A bare-bones frame filter follows the pattern in the following example.

  25048. 

  25049.      import gdb

  25050. 

  25051.      class FrameFilter():

  25052. 

  25053.          def __init__(self):

  25054.              # Frame filter attribute creation.

  25055.              #

  25056.              # 'name' is the name of the filter that GDB will display.

  25057.              #

  25058.              # 'priority' is the priority of the filter relative to other

  25059.              # filters.

  25060.              #

  25061.              # 'enabled' is a boolean that indicates whether this filter is

  25062.              # enabled and should be executed.

  25063. 

  25064.              self.name = "Foo"

  25065.              self.priority = 100

  25066.              self.enabled = True

  25067. 

  25068.              # Register this frame filter with the global frame_filters

  25069.              # dictionary.

  25070.              gdb.frame_filters[self.name] = self

  25071. 

  25072.          def filter(self, frame_iter):

  25073.              # Just return the iterator.

  25074.              return frame_iter

  25075. 

  25076.    The frame filter in the example above implements the three

  25077. requirements for all frame filters.  It implements the API, self

  25078. registers, and makes a decision on the iterator (in this case, it just

  25079. returns the iterator untouched).

  25080. 

  25081.    The first step is attribute creation and assignment, and as shown in

  25082. the comments the filter assigns the following attributes: 'name',

  25083. 'priority' and whether the filter should be enabled with the 'enabled'

  25084. attribute.

  25085. 

  25086.    The second step is registering the frame filter with the dictionary

  25087. or dictionaries that the frame filter has interest in.  As shown in the

  25088. comments, this filter just registers itself with the global dictionary

  25089. 'gdb.frame_filters'.  As noted earlier, 'gdb.frame_filters' is a

  25090. dictionary that is initialized in the 'gdb' module when GDB starts.

  25091. What dictionary a filter registers with is an important consideration.

  25092. Generally, if a filter is specific to a set of code, it should be

  25093. registered either in the 'objfile' or 'progspace' dictionaries as they

  25094. are specific to the program currently loaded in GDB.  The global

  25095. dictionary is always present in GDB and is never unloaded.  Any filters

  25096. registered with the global dictionary will exist until GDB exits.  To

  25097. avoid filters that may conflict, it is generally better to register

  25098. frame filters against the dictionaries that more closely align with the

  25099. usage of the filter currently in question.  *Note Python Auto-loading::,

  25100. for further information on auto-loading Python scripts.

  25101. 

  25102.    GDB takes a hands-off approach to frame filter registration,

  25103. therefore it is the frame filter's responsibility to ensure registration

  25104. has occurred, and that any exceptions are handled appropriately.  In

  25105. particular, you may wish to handle exceptions relating to Python

  25106. dictionary key uniqueness.  It is mandatory that the dictionary key is

  25107. the same as frame filter's 'name' attribute.  When a user manages frame

  25108. filters (*note Frame Filter Management::), the names GDB will display

  25109. are those contained in the 'name' attribute.

  25110. 

  25111.    The final step of this example is the implementation of the 'filter'

  25112. method.  As shown in the example comments, we define the 'filter' method

  25113. and note that the method must take an iterator, and also must return an

  25114. iterator.  In this bare-bones example, the frame filter is not very

  25115. useful as it just returns the iterator untouched.  However this is a

  25116. valid operation for frame filters that have the 'enabled' attribute set,

  25117. but decide not to operate on any frames.

  25118. 

  25119.    In the next example, the frame filter operates on all frames and

  25120. utilizes a frame decorator to perform some work on the frames.  *Note

  25121. Frame Decorator API::, for further information on the frame decorator

  25122. interface.

  25123. 

  25124.    This example works on inlined frames.  It highlights frames which are

  25125. inlined by tagging them with an "[inlined]" tag.  By applying a frame

  25126. decorator to all frames with the Python 'itertools imap' method, the

  25127. example defers actions to the frame decorator.  Frame decorators are

  25128. only processed when GDB prints the backtrace.

  25129. 

  25130.    This introduces a new decision making topic: whether to perform

  25131. decision making operations at the filtering step, or at the printing

  25132. step.  In this example's approach, it does not perform any filtering

  25133. decisions at the filtering step beyond mapping a frame decorator to each

  25134. frame.  This allows the actual decision making to be performed when each

  25135. frame is printed.  This is an important consideration, and well worth

  25136. reflecting upon when designing a frame filter.  An issue that frame

  25137. filters should avoid is unwinding the stack if possible.  Some stacks

  25138. can run very deep, into the tens of thousands in some cases.  To search

  25139. every frame to determine if it is inlined ahead of time may be too

  25140. expensive at the filtering step.  The frame filter cannot know how many

  25141. frames it has to iterate over, and it would have to iterate through them

  25142. all.  This ends up duplicating effort as GDB performs this iteration

  25143. when it prints the frames.

  25144. 

  25145.    In this example decision making can be deferred to the printing step.

  25146. As each frame is printed, the frame decorator can examine each frame in

  25147. turn when GDB iterates.  From a performance viewpoint, this is the most

  25148. appropriate decision to make as it avoids duplicating the effort that

  25149. the printing step would undertake anyway.  Also, if there are many frame

  25150. filters unwinding the stack during filtering, it can substantially delay

  25151. the printing of the backtrace which will result in large memory usage,

  25152. and a poor user experience.

  25153. 

  25154.      class InlineFilter():

  25155. 

  25156.          def __init__(self):

  25157.              self.name = "InlinedFrameFilter"

  25158.              self.priority = 100

  25159.              self.enabled = True

  25160.              gdb.frame_filters[self.name] = self

  25161. 

  25162.          def filter(self, frame_iter):

  25163.              frame_iter = itertools.imap(InlinedFrameDecorator,

  25164.                                          frame_iter)

  25165.              return frame_iter

  25166. 

  25167.    This frame filter is somewhat similar to the earlier example, except

  25168. that the 'filter' method applies a frame decorator object called

  25169. 'InlinedFrameDecorator' to each element in the iterator.  The 'imap'

  25170. Python method is light-weight.  It does not proactively iterate over the

  25171. iterator, but rather creates a new iterator which wraps the existing

  25172. one.

  25173. 

  25174.    Below is the frame decorator for this example.

  25175. 

  25176.      class InlinedFrameDecorator(FrameDecorator):

  25177. 

  25178.          def __init__(self, fobj):

  25179.              super(InlinedFrameDecorator, self).__init__(fobj)

  25180. 

  25181.          def function(self):

  25182.              frame = fobj.inferior_frame()

  25183.              name = str(frame.name())

  25184. 

  25185.              if frame.type() == gdb.INLINE_FRAME:

  25186.                  name = name + " [inlined]"

  25187. 

  25188.              return name

  25189. 

  25190.    This frame decorator only defines and overrides the 'function'

  25191. method.  It lets the supplied 'FrameDecorator', which is shipped with

  25192. GDB, perform the other work associated with printing this frame.

  25193. 

  25194.    The combination of these two objects create this output from a

  25195. backtrace:

  25196. 

  25197.      #0  0x004004e0 in bar () at inline.c:11

  25198.      #1  0x00400566 in max [inlined] (b=6, a=12) at inline.c:21

  25199.      #2  0x00400566 in main () at inline.c:31

  25200. 

  25201.    So in the case of this example, a frame decorator is applied to all

  25202. frames, regardless of whether they may be inlined or not.  As GDB

  25203. iterates over the iterator produced by the frame filters, GDB executes

  25204. each frame decorator which then makes a decision on what to print in the

  25205. 'function' callback.  Using a strategy like this is a way to defer

  25206. decisions on the frame content to printing time.

  25207. 

  25208. Eliding Frames

  25209. --------------

  25210. 

  25211. It might be that the above example is not desirable for representing

  25212. inlined frames, and a hierarchical approach may be preferred.  If we

  25213. want to hierarchically represent frames, the 'elided' frame decorator

  25214. interface might be preferable.

  25215. 

  25216.    This example approaches the issue with the 'elided' method.  This

  25217. example is quite long, but very simplistic.  It is out-of-scope for this

  25218. section to write a complete example that comprehensively covers all

  25219. approaches of finding and printing inlined frames.  However, this

  25220. example illustrates the approach an author might use.

  25221. 

  25222.    This example comprises of three sections.

  25223. 

  25224.      class InlineFrameFilter():

  25225. 

  25226.          def __init__(self):

  25227.              self.name = "InlinedFrameFilter"

  25228.              self.priority = 100

  25229.              self.enabled = True

  25230.              gdb.frame_filters[self.name] = self

  25231. 

  25232.          def filter(self, frame_iter):

  25233.              return ElidingInlineIterator(frame_iter)

  25234. 

  25235.    This frame filter is very similar to the other examples.  The only

  25236. difference is this frame filter is wrapping the iterator provided to it

  25237. ('frame_iter') with a custom iterator called 'ElidingInlineIterator'.

  25238. This again defers actions to when GDB prints the backtrace, as the

  25239. iterator is not traversed until printing.

  25240. 

  25241.    The iterator for this example is as follows.  It is in this section

  25242. of the example where decisions are made on the content of the backtrace.

  25243. 

  25244.      class ElidingInlineIterator:

  25245.          def __init__(self, ii):

  25246.              self.input_iterator = ii

  25247. 

  25248.          def __iter__(self):

  25249.              return self

  25250. 

  25251.          def next(self):

  25252.              frame = next(self.input_iterator)

  25253. 

  25254.              if frame.inferior_frame().type() != gdb.INLINE_FRAME:

  25255.                  return frame

  25256. 

  25257.              try:

  25258.                  eliding_frame = next(self.input_iterator)

  25259.              except StopIteration:

  25260.                  return frame

  25261.              return ElidingFrameDecorator(eliding_frame, [frame])

  25262. 

  25263.    This iterator implements the Python iterator protocol.  When the

  25264. 'next' function is called (when GDB prints each frame), the iterator

  25265. checks if this frame decorator, 'frame', is wrapping an inlined frame.

  25266. If it is not, it returns the existing frame decorator untouched.  If it

  25267. is wrapping an inlined frame, it assumes that the inlined frame was

  25268. contained within the next oldest frame, 'eliding_frame', which it

  25269. fetches.  It then creates and returns a frame decorator,

  25270. 'ElidingFrameDecorator', which contains both the elided frame, and the

  25271. eliding frame.

  25272. 

  25273.      class ElidingInlineDecorator(FrameDecorator):

  25274. 

  25275.          def __init__(self, frame, elided_frames):

  25276.              super(ElidingInlineDecorator, self).__init__(frame)

  25277.              self.frame = frame

  25278.              self.elided_frames = elided_frames

  25279. 

  25280.          def elided(self):

  25281.              return iter(self.elided_frames)

  25282. 

  25283.    This frame decorator overrides one function and returns the inlined

  25284. frame in the 'elided' method.  As before it lets 'FrameDecorator' do the

  25285. rest of the work involved in printing this frame.  This produces the

  25286. following output.

  25287. 

  25288.      #0  0x004004e0 in bar () at inline.c:11

  25289.      #2  0x00400529 in main () at inline.c:25

  25290.          #1  0x00400529 in max (b=6, a=12) at inline.c:15

  25291. 

  25292.    In that output, 'max' which has been inlined into 'main' is printed

  25293. hierarchically.  Another approach would be to combine the 'function'

  25294. method, and the 'elided' method to both print a marker in the inlined

  25295. frame, and also show the hierarchical relationship.

  25296. 

  25297. 

  25298. File: gdb.info,  Node: Unwinding Frames in Python,  Next: Xmethods In Python,  Prev: Writing a Frame Filter,  Up: Python API

  25299. 

  25300. 23.2.2.12 Unwinding Frames in Python

  25301. ....................................

  25302. 

  25303. In GDB terminology "unwinding" is the process of finding the previous

  25304. frame (that is, caller's) from the current one.  An unwinder has three

  25305. methods.  The first one checks if it can handle given frame ("sniff"

  25306. it).  For the frames it can sniff an unwinder provides two additional

  25307. methods: it can return frame's ID, and it can fetch registers from the

  25308. previous frame.  A running GDB mantains a list of the unwinders and

  25309. calls each unwinder's sniffer in turn until it finds the one that

  25310. recognizes the current frame.  There is an API to register an unwinder.

  25311. 

  25312.    The unwinders that come with GDB handle standard frames.  However,

  25313. mixed language applications (for example, an application running Java

  25314. Virtual Machine) sometimes use frame layouts that cannot be handled by

  25315. the GDB unwinders.  You can write Python code that can handle such

  25316. custom frames.

  25317. 

  25318.    You implement a frame unwinder in Python as a class with which has

  25319. two attributes, 'name' and 'enabled', with obvious meanings, and a

  25320. single method '__call__', which examines a given frame and returns an

  25321. object (an instance of 'gdb.UnwindInfo class)' describing it.  If an

  25322. unwinder does not recognize a frame, it should return 'None'.  The code

  25323. in GDB that enables writing unwinders in Python uses this object to

  25324. return frame's ID and previous frame registers when GDB core asks for

  25325. them.

  25326. 

  25327.    An unwinder should do as little work as possible.  Some otherwise

  25328. innocuous operations can cause problems (even crashes, as this code is

  25329. not not well-hardened yet).  For example, making an inferior call from

  25330. an unwinder is unadvisable, as an inferior call will reset GDB's stack

  25331. unwinding process, potentially causing re-entrant unwinding.

  25332. 

  25333. Unwinder Input

  25334. --------------

  25335. 

  25336. An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides

  25337. a method to read frame's registers:

  25338. 

  25339.  -- Function: PendingFrame.read_register (reg)

  25340.      This method returns the contents of the register REG in the frame

  25341.      as a 'gdb.Value' object.  For a description of the acceptable

  25342.      values of REG see *note Frame.read_register:

  25343.      gdbpy_frame_read_register.  If REG does not name a register for the

  25344.      current architecture, this method will throw an exception.

  25345. 

  25346.      Note that this method will always return a 'gdb.Value' for a valid

  25347.      register name.  This does not mean that the value will be valid.

  25348.      For example, you may request a register that an earlier unwinder

  25349.      could not unwind--the value will be unavailable.  Instead, the

  25350.      'gdb.Value' returned from this method will be lazy; that is, its

  25351.      underlying bits will not be fetched until it is first used.  So,

  25352.      attempting to use such a value will cause an exception at the point

  25353.      of use.

  25354. 

  25355.      The type of the returned 'gdb.Value' depends on the register and

  25356.      the architecture.  It is common for registers to have a scalar

  25357.      type, like 'long long'; but many other types are possible, such as

  25358.      pointer, pointer-to-function, floating point or vector types.

  25359. 

  25360.    It also provides a factory method to create a 'gdb.UnwindInfo'

  25361. instance to be returned to GDB:

  25362. 

  25363.  -- Function: PendingFrame.create_unwind_info (frame_id)

  25364.      Returns a new 'gdb.UnwindInfo' instance identified by given

  25365.      FRAME_ID.  The argument is used to build GDB's frame ID using one

  25366.      of functions provided by GDB.  FRAME_ID's attributes determine

  25367.      which function will be used, as follows:

  25368. 

  25369.      'sp, pc'

  25370.           The frame is identified by the given stack address and PC. The

  25371.           stack address must be chosen so that it is constant throughout

  25372.           the lifetime of the frame, so a typical choice is the value of

  25373.           the stack pointer at the start of the function--in the DWARF

  25374.           standard, this would be the "Call Frame Address".

  25375. 

  25376.           This is the most common case by far.  The other cases are

  25377.           documented for completeness but are only useful in specialized

  25378.           situations.

  25379. 

  25380.      'sp, pc, special'

  25381.           The frame is identified by the stack address, the PC, and a

  25382.           "special" address.  The special address is used on

  25383.           architectures that can have frames that do not change the

  25384.           stack, but which are still distinct, for example the IA-64,

  25385.           which has a second stack for registers.  Both SP and SPECIAL

  25386.           must be constant throughout the lifetime of the frame.

  25387. 

  25388.      'sp'

  25389.           The frame is identified by the stack address only.  Any other

  25390.           stack frame with a matching SP will be considered to match

  25391.           this frame.  Inside gdb, this is called a "wild frame".  You

  25392.           will never need this.

  25393. 

  25394.      Each attribute value should be an instance of 'gdb.Value'.

  25395. 

  25396.  -- Function: PendingFrame.architecture ()

  25397.      Return the 'gdb.Architecture' (*note Architectures In Python::) for

  25398.      this 'gdb.PendingFrame'.  This represents the architecture of the

  25399.      particular frame being unwound.

  25400. 

  25401. Unwinder Output: UnwindInfo

  25402. ---------------------------

  25403. 

  25404. Use 'PendingFrame.create_unwind_info' method described above to create a

  25405. 'gdb.UnwindInfo' instance.  Use the following method to specify caller

  25406. registers that have been saved in this frame:

  25407. 

  25408.  -- Function: gdb.UnwindInfo.add_saved_register (reg, value)

  25409.      REG identifies the register, for a description of the acceptable

  25410.      values see *note Frame.read_register: gdbpy_frame_read_register.

  25411.      VALUE is a register value (a 'gdb.Value' object).

  25412. 

  25413. Unwinder Skeleton Code

  25414. ----------------------

  25415. 

  25416. GDB comes with the module containing the base 'Unwinder' class.  Derive

  25417. your unwinder class from it and structure the code as follows:

  25418. 

  25419.      from gdb.unwinders import Unwinder

  25420. 

  25421.      class FrameId(object):

  25422.          def __init__(self, sp, pc):

  25423.              self.sp = sp

  25424.              self.pc = pc

  25425. 

  25426. 

  25427.      class MyUnwinder(Unwinder):

  25428.          def __init__(....):

  25429.              super(MyUnwinder, self).__init___(<expects unwinder name argument>)

  25430. 

  25431.          def __call__(pending_frame):

  25432.              if not <we recognize frame>:

  25433.                  return None

  25434.              # Create UnwindInfo.  Usually the frame is identified by the stack

  25435.              # pointer and the program counter.

  25436.              sp = pending_frame.read_register(<SP number>)

  25437.              pc = pending_frame.read_register(<PC number>)

  25438.              unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))

  25439. 

  25440.              # Find the values of the registers in the caller's frame and

  25441.              # save them in the result:

  25442.              unwind_info.add_saved_register(<register>, <value>)

  25443.              ....

  25444. 

  25445.              # Return the result:

  25446.              return unwind_info

  25447. 

  25448. 

  25449. Registering a Unwinder

  25450. ----------------------

  25451. 

  25452. An object file, a program space, and the GDB proper can have unwinders

  25453. registered with it.

  25454. 

  25455.    The 'gdb.unwinders' module provides the function to register a

  25456. unwinder:

  25457. 

  25458.  -- Function: gdb.unwinder.register_unwinder (locus, unwinder,

  25459.           replace=False)

  25460.      LOCUS is specifies an object file or a program space to which

  25461.      UNWINDER is added.  Passing 'None' or 'gdb' adds UNWINDER to the

  25462.      GDB's global unwinder list.  The newly added UNWINDER will be

  25463.      called before any other unwinder from the same locus.  Two

  25464.      unwinders in the same locus cannot have the same name.  An attempt

  25465.      to add a unwinder with already existing name raises an exception

  25466.      unless REPLACE is 'True', in which case the old unwinder is

  25467.      deleted.

  25468. 

  25469. Unwinder Precedence

  25470. -------------------

  25471. 

  25472. GDB first calls the unwinders from all the object files in no particular

  25473. order, then the unwinders from the current program space, and finally

  25474. the unwinders from GDB.

  25475. 

  25476. 

  25477. File: gdb.info,  Node: Xmethods In Python,  Next: Xmethod API,  Prev: Unwinding Frames in Python,  Up: Python API

  25478. 

  25479. 23.2.2.13 Xmethods In Python

  25480. ............................

  25481. 

  25482. "Xmethods" are additional methods or replacements for existing methods

  25483. of a C++ class.  This feature is useful for those cases where a method

  25484. defined in C++ source code could be inlined or optimized out by the

  25485. compiler, making it unavailable to GDB.  For such cases, one can define

  25486. an xmethod to serve as a replacement for the method defined in the C++

  25487. source code.  GDB will then invoke the xmethod, instead of the C++

  25488. method, to evaluate expressions.  One can also use xmethods when

  25489. debugging with core files.  Moreover, when debugging live programs,

  25490. invoking an xmethod need not involve running the inferior (which can

  25491. potentially perturb its state).  Hence, even if the C++ method is

  25492. available, it is better to use its replacement xmethod if one is

  25493. defined.

  25494. 

  25495.    The xmethods feature in Python is available via the concepts of an

  25496. "xmethod matcher" and an "xmethod worker".  To implement an xmethod, one

  25497. has to implement a matcher and a corresponding worker for it (more than

  25498. one worker can be implemented, each catering to a different overloaded

  25499. instance of the method).  Internally, GDB invokes the 'match' method of

  25500. a matcher to match the class type and method name.  On a match, the

  25501. 'match' method returns a list of matching _worker_ objects.  Each worker

  25502. object typically corresponds to an overloaded instance of the xmethod.

  25503. They implement a 'get_arg_types' method which returns a sequence of

  25504. types corresponding to the arguments the xmethod requires.  GDB uses

  25505. this sequence of types to perform overload resolution and picks a

  25506. winning xmethod worker.  A winner is also selected from among the

  25507. methods GDB finds in the C++ source code.  Next, the winning xmethod

  25508. worker and the winning C++ method are compared to select an overall

  25509. winner.  In case of a tie between a xmethod worker and a C++ method, the

  25510. xmethod worker is selected as the winner.  That is, if a winning xmethod

  25511. worker is found to be equivalent to the winning C++ method, then the

  25512. xmethod worker is treated as a replacement for the C++ method.  GDB uses

  25513. the overall winner to invoke the method.  If the winning xmethod worker

  25514. is the overall winner, then the corresponding xmethod is invoked via the

  25515. '__call__' method of the worker object.

  25516. 

  25517.    If one wants to implement an xmethod as a replacement for an existing

  25518. C++ method, then they have to implement an equivalent xmethod which has

  25519. exactly the same name and takes arguments of exactly the same type as

  25520. the C++ method.  If the user wants to invoke the C++ method even though

  25521. a replacement xmethod is available for that method, then they can

  25522. disable the xmethod.

  25523. 

  25524.    *Note Xmethod API::, for API to implement xmethods in Python.  *Note

  25525. Writing an Xmethod::, for implementing xmethods in Python.

  25526. 

  25527. 

  25528. File: gdb.info,  Node: Xmethod API,  Next: Writing an Xmethod,  Prev: Xmethods In Python,  Up: Python API

  25529. 

  25530. 23.2.2.14 Xmethod API

  25531. .....................

  25532. 

  25533. The GDB Python API provides classes, interfaces and functions to

  25534. implement, register and manipulate xmethods.  *Note Xmethods In

  25535. Python::.

  25536. 

  25537.    An xmethod matcher should be an instance of a class derived from

  25538. 'XMethodMatcher' defined in the module 'gdb.xmethod', or an object with

  25539. similar interface and attributes.  An instance of 'XMethodMatcher' has

  25540. the following attributes:

  25541. 

  25542.  -- Variable: name

  25543.      The name of the matcher.

  25544. 

  25545.  -- Variable: enabled

  25546.      A boolean value indicating whether the matcher is enabled or

  25547.      disabled.

  25548. 

  25549.  -- Variable: methods

  25550.      A list of named methods managed by the matcher.  Each object in the

  25551.      list is an instance of the class 'XMethod' defined in the module

  25552.      'gdb.xmethod', or any object with the following attributes:

  25553. 

  25554.      'name'

  25555.           Name of the xmethod which should be unique for each xmethod

  25556.           managed by the matcher.

  25557. 

  25558.      'enabled'

  25559.           A boolean value indicating whether the xmethod is enabled or

  25560.           disabled.

  25561. 

  25562.      The class 'XMethod' is a convenience class with same attributes as

  25563.      above along with the following constructor:

  25564. 

  25565.       -- Function: XMethod.__init__ (self, name)

  25566.           Constructs an enabled xmethod with name NAME.

  25567. 

  25568. The 'XMethodMatcher' class has the following methods:

  25569. 

  25570.  -- Function: XMethodMatcher.__init__ (self, name)

  25571.      Constructs an enabled xmethod matcher with name NAME.  The

  25572.      'methods' attribute is initialized to 'None'.

  25573. 

  25574.  -- Function: XMethodMatcher.match (self, class_type, method_name)

  25575.      Derived classes should override this method.  It should return a

  25576.      xmethod worker object (or a sequence of xmethod worker objects)

  25577.      matching the CLASS_TYPE and METHOD_NAME.  CLASS_TYPE is a

  25578.      'gdb.Type' object, and METHOD_NAME is a string value.  If the

  25579.      matcher manages named methods as listed in its 'methods' attribute,

  25580.      then only those worker objects whose corresponding entries in the

  25581.      'methods' list are enabled should be returned.

  25582. 

  25583.    An xmethod worker should be an instance of a class derived from

  25584. 'XMethodWorker' defined in the module 'gdb.xmethod', or support the

  25585. following interface:

  25586. 

  25587.  -- Function: XMethodWorker.get_arg_types (self)

  25588.      This method returns a sequence of 'gdb.Type' objects corresponding

  25589.      to the arguments that the xmethod takes.  It can return an empty

  25590.      sequence or 'None' if the xmethod does not take any arguments.  If

  25591.      the xmethod takes a single argument, then a single 'gdb.Type'

  25592.      object corresponding to it can be returned.

  25593. 

  25594.  -- Function: XMethodWorker.get_result_type (self, *args)

  25595.      This method returns a 'gdb.Type' object representing the type of

  25596.      the result of invoking this xmethod.  The ARGS argument is the same

  25597.      tuple of arguments that would be passed to the '__call__' method of

  25598.      this worker.

  25599. 

  25600.  -- Function: XMethodWorker.__call__ (self, *args)

  25601.      This is the method which does the _work_ of the xmethod.  The ARGS

  25602.      arguments is the tuple of arguments to the xmethod.  Each element

  25603.      in this tuple is a gdb.Value object.  The first element is always

  25604.      the 'this' pointer value.

  25605. 

  25606.    For GDB to lookup xmethods, the xmethod matchers should be registered

  25607. using the following function defined in the module 'gdb.xmethod':

  25608. 

  25609.  -- Function: register_xmethod_matcher (locus, matcher, replace=False)

  25610.      The 'matcher' is registered with 'locus', replacing an existing

  25611.      matcher with the same name as 'matcher' if 'replace' is 'True'.

  25612.      'locus' can be a 'gdb.Objfile' object (*note Objfiles In Python::),

  25613.      or a 'gdb.Progspace' object (*note Progspaces In Python::), or

  25614.      'None'.  If it is 'None', then 'matcher' is registered globally.

  25615. 

  25616. 

  25617. File: gdb.info,  Node: Writing an Xmethod,  Next: Inferiors In Python,  Prev: Xmethod API,  Up: Python API

  25618. 

  25619. 23.2.2.15 Writing an Xmethod

  25620. ............................

  25621. 

  25622. Implementing xmethods in Python will require implementing xmethod

  25623. matchers and xmethod workers (*note Xmethods In Python::).  Consider the

  25624. following C++ class:

  25625. 

  25626.      class MyClass

  25627.      {

  25628.      public:

  25629.        MyClass (int a) : a_(a) { }

  25630. 

  25631.        int geta (void) { return a_; }

  25632.        int operator+ (int b);

  25633. 

  25634.      private:

  25635.        int a_;

  25636.      };

  25637. 

  25638.      int

  25639.      MyClass::operator+ (int b)

  25640.      {

  25641.        return a_ + b;

  25642.      }

  25643. 

  25644. Let us define two xmethods for the class 'MyClass', one replacing the

  25645. method 'geta', and another adding an overloaded flavor of 'operator+'

  25646. which takes a 'MyClass' argument (the C++ code above already has an

  25647. overloaded 'operator+' which takes an 'int' argument).  The xmethod

  25648. matcher can be defined as follows:

  25649. 

  25650.      class MyClass_geta(gdb.xmethod.XMethod):

  25651.          def __init__(self):

  25652.              gdb.xmethod.XMethod.__init__(self, 'geta')

  25653. 

  25654.          def get_worker(self, method_name):

  25655.              if method_name == 'geta':

  25656.                  return MyClassWorker_geta()

  25657. 

  25658. 

  25659.      class MyClass_sum(gdb.xmethod.XMethod):

  25660.          def __init__(self):

  25661.              gdb.xmethod.XMethod.__init__(self, 'sum')

  25662. 

  25663.          def get_worker(self, method_name):

  25664.              if method_name == 'operator+':

  25665.                  return MyClassWorker_plus()

  25666. 

  25667. 

  25668.      class MyClassMatcher(gdb.xmethod.XMethodMatcher):

  25669.          def __init__(self):

  25670.              gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')

  25671.              # List of methods 'managed' by this matcher

  25672.              self.methods = [MyClass_geta(), MyClass_sum()]

  25673. 

  25674.          def match(self, class_type, method_name):

  25675.              if class_type.tag != 'MyClass':

  25676.                  return None

  25677.              workers = []

  25678.              for method in self.methods:

  25679.                  if method.enabled:

  25680.                      worker = method.get_worker(method_name)

  25681.                      if worker:

  25682.                          workers.append(worker)

  25683. 

  25684.              return workers

  25685. 

  25686. Notice that the 'match' method of 'MyClassMatcher' returns a worker

  25687. object of type 'MyClassWorker_geta' for the 'geta' method, and a worker

  25688. object of type 'MyClassWorker_plus' for the 'operator+' method.  This is

  25689. done indirectly via helper classes derived from 'gdb.xmethod.XMethod'.

  25690. One does not need to use the 'methods' attribute in a matcher as it is

  25691. optional.  However, if a matcher manages more than one xmethod, it is a

  25692. good practice to list the xmethods in the 'methods' attribute of the

  25693. matcher.  This will then facilitate enabling and disabling individual

  25694. xmethods via the 'enable/disable' commands.  Notice also that a worker

  25695. object is returned only if the corresponding entry in the 'methods'

  25696. attribute of the matcher is enabled.

  25697. 

  25698.    The implementation of the worker classes returned by the matcher

  25699. setup above is as follows:

  25700. 

  25701.      class MyClassWorker_geta(gdb.xmethod.XMethodWorker):

  25702.          def get_arg_types(self):

  25703.              return None

  25704. 

  25705.          def get_result_type(self, obj):

  25706.              return gdb.lookup_type('int')

  25707. 

  25708.          def __call__(self, obj):

  25709.              return obj['a_']

  25710. 

  25711. 

  25712.      class MyClassWorker_plus(gdb.xmethod.XMethodWorker):

  25713.          def get_arg_types(self):

  25714.              return gdb.lookup_type('MyClass')

  25715. 

  25716.          def get_result_type(self, obj):

  25717.              return gdb.lookup_type('int')

  25718. 

  25719.          def __call__(self, obj, other):

  25720.              return obj['a_'] + other['a_']

  25721. 

  25722.    For GDB to actually lookup a xmethod, it has to be registered with

  25723. it.  The matcher defined above is registered with GDB globally as

  25724. follows:

  25725. 

  25726.      gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())

  25727. 

  25728.    If an object 'obj' of type 'MyClass' is initialized in C++ code as

  25729. follows:

  25730. 

  25731.      MyClass obj(5);

  25732. 

  25733. then, after loading the Python script defining the xmethod matchers and

  25734. workers into 'GDBN', invoking the method 'geta' or using the operator

  25735. '+' on 'obj' will invoke the xmethods defined above:

  25736. 

  25737.      (gdb) p obj.geta()

  25738.      $1 = 5

  25739. 

  25740.      (gdb) p obj + obj

  25741.      $2 = 10

  25742. 

  25743.    Consider another example with a C++ template class:

  25744. 

  25745.      template <class T>

  25746.      class MyTemplate

  25747.      {

  25748.      public:

  25749.        MyTemplate () : dsize_(10), data_ (new T [10]) { }

  25750.        ~MyTemplate () { delete [] data_; }

  25751. 

  25752.        int footprint (void)

  25753.        {

  25754.          return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);

  25755.        }

  25756. 

  25757.      private:

  25758.        int dsize_;

  25759.        T *data_;

  25760.      };

  25761. 

  25762.    Let us implement an xmethod for the above class which serves as a

  25763. replacement for the 'footprint' method.  The full code listing of the

  25764. xmethod workers and xmethod matchers is as follows:

  25765. 

  25766.      class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):

  25767.          def __init__(self, class_type):

  25768.              self.class_type = class_type

  25769. 

  25770.          def get_arg_types(self):

  25771.              return None

  25772. 

  25773.          def get_result_type(self):

  25774.              return gdb.lookup_type('int')

  25775. 

  25776.          def __call__(self, obj):

  25777.              return (self.class_type.sizeof +

  25778.                      obj['dsize_'] *

  25779.                      self.class_type.template_argument(0).sizeof)

  25780. 

  25781. 

  25782.      class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):

  25783.          def __init__(self):

  25784.              gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')

  25785. 

  25786.          def match(self, class_type, method_name):

  25787.              if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',

  25788.                           class_type.tag) and

  25789.                  method_name == 'footprint'):

  25790.                  return MyTemplateWorker_footprint(class_type)

  25791. 

  25792.    Notice that, in this example, we have not used the 'methods'

  25793. attribute of the matcher as the matcher manages only one xmethod.  The

  25794. user can enable/disable this xmethod by enabling/disabling the matcher

  25795. itself.

  25796. 

  25797. 

  25798. File: gdb.info,  Node: Inferiors In Python,  Next: Events In Python,  Prev: Writing an Xmethod,  Up: Python API

  25799. 

  25800. 23.2.2.16 Inferiors In Python

  25801. .............................

  25802. 

  25803. Programs which are being run under GDB are called inferiors (*note

  25804. Inferiors Connections and Programs::).  Python scripts can access

  25805. information about and manipulate inferiors controlled by GDB via objects

  25806. of the 'gdb.Inferior' class.

  25807. 

  25808.    The following inferior-related functions are available in the 'gdb'

  25809. module:

  25810. 

  25811.  -- Function: gdb.inferiors ()

  25812.      Return a tuple containing all inferior objects.

  25813. 

  25814.  -- Function: gdb.selected_inferior ()

  25815.      Return an object representing the current inferior.

  25816. 

  25817.    A 'gdb.Inferior' object has the following attributes:

  25818. 

  25819.  -- Variable: Inferior.num

  25820.      ID of inferior, as assigned by GDB.

  25821. 

  25822.  -- Variable: Inferior.pid

  25823.      Process ID of the inferior, as assigned by the underlying operating

  25824.      system.

  25825. 

  25826.  -- Variable: Inferior.was_attached

  25827.      Boolean signaling whether the inferior was created using 'attach',

  25828.      or started by GDB itself.

  25829. 

  25830.  -- Variable: Inferior.progspace

  25831.      The inferior's program space.  *Note Progspaces In Python::.

  25832. 

  25833.    A 'gdb.Inferior' object has the following methods:

  25834. 

  25835.  -- Function: Inferior.is_valid ()

  25836.      Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if

  25837.      not.  A 'gdb.Inferior' object will become invalid if the inferior

  25838.      no longer exists within GDB.  All other 'gdb.Inferior' methods will

  25839.      throw an exception if it is invalid at the time the method is

  25840.      called.

  25841. 

  25842.  -- Function: Inferior.threads ()

  25843.      This method returns a tuple holding all the threads which are valid

  25844.      when it is called.  If there are no valid threads, the method will

  25845.      return an empty tuple.

  25846. 

  25847.  -- Function: Inferior.architecture ()

  25848.      Return the 'gdb.Architecture' (*note Architectures In Python::) for

  25849.      this inferior.  This represents the architecture of the inferior as

  25850.      a whole.  Some platforms can have multiple architectures in a

  25851.      single address space, so this may not match the architecture of a

  25852.      particular frame (*note Frames In Python::).

  25853. 

  25854.  -- Function: Inferior.read_memory (address, length)

  25855.      Read LENGTH addressable memory units from the inferior, starting at

  25856.      ADDRESS.  Returns a buffer object, which behaves much like an array

  25857.      or a string.  It can be modified and given to the

  25858.      'Inferior.write_memory' function.  In Python 3, the return value is

  25859.      a 'memoryview' object.

  25860. 

  25861.  -- Function: Inferior.write_memory (address, buffer [, length])

  25862.      Write the contents of BUFFER to the inferior, starting at ADDRESS.

  25863.      The BUFFER parameter must be a Python object which supports the

  25864.      buffer protocol, i.e., a string, an array or the object returned

  25865.      from 'Inferior.read_memory'.  If given, LENGTH determines the

  25866.      number of addressable memory units from BUFFER to be written.

  25867. 

  25868.  -- Function: Inferior.search_memory (address, length, pattern)

  25869.      Search a region of the inferior memory starting at ADDRESS with the

  25870.      given LENGTH using the search pattern supplied in PATTERN.  The

  25871.      PATTERN parameter must be a Python object which supports the buffer

  25872.      protocol, i.e., a string, an array or the object returned from

  25873.      'gdb.read_memory'.  Returns a Python 'Long' containing the address

  25874.      where the pattern was found, or 'None' if the pattern could not be

  25875.      found.

  25876. 

  25877.  -- Function: Inferior.thread_from_handle (handle)

  25878.      Return the thread object corresponding to HANDLE, a thread library

  25879.      specific data structure such as 'pthread_t' for pthreads library

  25880.      implementations.

  25881. 

  25882.      The function 'Inferior.thread_from_thread_handle' provides the same

  25883.      functionality, but use of 'Inferior.thread_from_thread_handle' is

  25884.      deprecated.

  25885. 

  25886. 

  25887. File: gdb.info,  Node: Events In Python,  Next: Threads In Python,  Prev: Inferiors In Python,  Up: Python API

  25888. 

  25889. 23.2.2.17 Events In Python

  25890. ..........................

  25891. 

  25892. GDB provides a general event facility so that Python code can be

  25893. notified of various state changes, particularly changes that occur in

  25894. the inferior.

  25895. 

  25896.    An "event" is just an object that describes some state change.  The

  25897. type of the object and its attributes will vary depending on the details

  25898. of the change.  All the existing events are described below.

  25899. 

  25900.    In order to be notified of an event, you must register an event

  25901. handler with an "event registry".  An event registry is an object in the

  25902. 'gdb.events' module which dispatches particular events.  A registry

  25903. provides methods to register and unregister event handlers:

  25904. 

  25905.  -- Function: EventRegistry.connect (object)

  25906.      Add the given callable OBJECT to the registry.  This object will be

  25907.      called when an event corresponding to this registry occurs.

  25908. 

  25909.  -- Function: EventRegistry.disconnect (object)

  25910.      Remove the given OBJECT from the registry.  Once removed, the

  25911.      object will no longer receive notifications of events.

  25912. 

  25913.    Here is an example:

  25914. 

  25915.      def exit_handler (event):

  25916.          print "event type: exit"

  25917.          print "exit code: %d" % (event.exit_code)

  25918. 

  25919.      gdb.events.exited.connect (exit_handler)

  25920. 

  25921.    In the above example we connect our handler 'exit_handler' to the

  25922. registry 'events.exited'.  Once connected, 'exit_handler' gets called

  25923. when the inferior exits.  The argument "event" in this example is of

  25924. type 'gdb.ExitedEvent'.  As you can see in the example the 'ExitedEvent'

  25925. object has an attribute which indicates the exit code of the inferior.

  25926. 

  25927.    The following is a listing of the event registries that are available

  25928. and details of the events they emit:

  25929. 

  25930. 'events.cont'

  25931.      Emits 'gdb.ThreadEvent'.

  25932. 

  25933.      Some events can be thread specific when GDB is running in non-stop

  25934.      mode.  When represented in Python, these events all extend

  25935.      'gdb.ThreadEvent'.  Note, this event is not emitted directly;

  25936.      instead, events which are emitted by this or other modules might

  25937.      extend this event.  Examples of these events are

  25938.      'gdb.BreakpointEvent' and 'gdb.ContinueEvent'.

  25939. 

  25940.       -- Variable: ThreadEvent.inferior_thread

  25941.           In non-stop mode this attribute will be set to the specific

  25942.           thread which was involved in the emitted event.  Otherwise, it

  25943.           will be set to 'None'.

  25944. 

  25945.      Emits 'gdb.ContinueEvent' which extends 'gdb.ThreadEvent'.

  25946. 

  25947.      This event indicates that the inferior has been continued after a

  25948.      stop.  For inherited attribute refer to 'gdb.ThreadEvent' above.

  25949. 

  25950. 'events.exited'

  25951.      Emits 'events.ExitedEvent' which indicates that the inferior has

  25952.      exited.  'events.ExitedEvent' has two attributes:

  25953.       -- Variable: ExitedEvent.exit_code

  25954.           An integer representing the exit code, if available, which the

  25955.           inferior has returned.  (The exit code could be unavailable

  25956.           if, for example, GDB detaches from the inferior.)  If the exit

  25957.           code is unavailable, the attribute does not exist.

  25958.       -- Variable: ExitedEvent.inferior

  25959.           A reference to the inferior which triggered the 'exited'

  25960.           event.

  25961. 

  25962. 'events.stop'

  25963.      Emits 'gdb.StopEvent' which extends 'gdb.ThreadEvent'.

  25964. 

  25965.      Indicates that the inferior has stopped.  All events emitted by

  25966.      this registry extend StopEvent.  As a child of 'gdb.ThreadEvent',

  25967.      'gdb.StopEvent' will indicate the stopped thread when GDB is

  25968.      running in non-stop mode.  Refer to 'gdb.ThreadEvent' above for

  25969.      more details.

  25970. 

  25971.      Emits 'gdb.SignalEvent' which extends 'gdb.StopEvent'.

  25972. 

  25973.      This event indicates that the inferior or one of its threads has

  25974.      received as signal.  'gdb.SignalEvent' has the following

  25975.      attributes:

  25976. 

  25977.       -- Variable: SignalEvent.stop_signal

  25978.           A string representing the signal received by the inferior.  A

  25979.           list of possible signal values can be obtained by running the

  25980.           command 'info signals' in the GDB command prompt.

  25981. 

  25982.      Also emits 'gdb.BreakpointEvent' which extends 'gdb.StopEvent'.

  25983. 

  25984.      'gdb.BreakpointEvent' event indicates that one or more breakpoints

  25985.      have been hit, and has the following attributes:

  25986. 

  25987.       -- Variable: BreakpointEvent.breakpoints

  25988.           A sequence containing references to all the breakpoints (type

  25989.           'gdb.Breakpoint') that were hit.  *Note Breakpoints In

  25990.           Python::, for details of the 'gdb.Breakpoint' object.

  25991.       -- Variable: BreakpointEvent.breakpoint

  25992.           A reference to the first breakpoint that was hit.  This

  25993.           function is maintained for backward compatibility and is now

  25994.           deprecated in favor of the 'gdb.BreakpointEvent.breakpoints'

  25995.           attribute.

  25996. 

  25997. 'events.new_objfile'

  25998.      Emits 'gdb.NewObjFileEvent' which indicates that a new object file

  25999.      has been loaded by GDB.  'gdb.NewObjFileEvent' has one attribute:

  26000. 

  26001.       -- Variable: NewObjFileEvent.new_objfile

  26002.           A reference to the object file ('gdb.Objfile') which has been

  26003.           loaded.  *Note Objfiles In Python::, for details of the

  26004.           'gdb.Objfile' object.

  26005. 

  26006. 'events.clear_objfiles'

  26007.      Emits 'gdb.ClearObjFilesEvent' which indicates that the list of

  26008.      object files for a program space has been reset.

  26009.      'gdb.ClearObjFilesEvent' has one attribute:

  26010. 

  26011.       -- Variable: ClearObjFilesEvent.progspace

  26012.           A reference to the program space ('gdb.Progspace') whose

  26013.           objfile list has been cleared.  *Note Progspaces In Python::.

  26014. 

  26015. 'events.inferior_call'

  26016.      Emits events just before and after a function in the inferior is

  26017.      called by GDB.  Before an inferior call, this emits an event of

  26018.      type 'gdb.InferiorCallPreEvent', and after an inferior call, this

  26019.      emits an event of type 'gdb.InferiorCallPostEvent'.

  26020. 

  26021.      'gdb.InferiorCallPreEvent'

  26022.           Indicates that a function in the inferior is about to be

  26023.           called.

  26024. 

  26025.            -- Variable: InferiorCallPreEvent.ptid

  26026.                The thread in which the call will be run.

  26027. 

  26028.            -- Variable: InferiorCallPreEvent.address

  26029.                The location of the function to be called.

  26030. 

  26031.      'gdb.InferiorCallPostEvent'

  26032.           Indicates that a function in the inferior has just been

  26033.           called.

  26034. 

  26035.            -- Variable: InferiorCallPostEvent.ptid

  26036.                The thread in which the call was run.

  26037. 

  26038.            -- Variable: InferiorCallPostEvent.address

  26039.                The location of the function that was called.

  26040. 

  26041. 'events.memory_changed'

  26042.      Emits 'gdb.MemoryChangedEvent' which indicates that the memory of

  26043.      the inferior has been modified by the GDB user, for instance via a

  26044.      command like 'set *addr = value'.  The event has the following

  26045.      attributes:

  26046. 

  26047.       -- Variable: MemoryChangedEvent.address

  26048.           The start address of the changed region.

  26049. 

  26050.       -- Variable: MemoryChangedEvent.length

  26051.           Length in bytes of the changed region.

  26052. 

  26053. 'events.register_changed'

  26054.      Emits 'gdb.RegisterChangedEvent' which indicates that a register in

  26055.      the inferior has been modified by the GDB user.

  26056. 

  26057.       -- Variable: RegisterChangedEvent.frame

  26058.           A gdb.Frame object representing the frame in which the

  26059.           register was modified.

  26060.       -- Variable: RegisterChangedEvent.regnum

  26061.           Denotes which register was modified.

  26062. 

  26063. 'events.breakpoint_created'

  26064.      This is emitted when a new breakpoint has been created.  The

  26065.      argument that is passed is the new 'gdb.Breakpoint' object.

  26066. 

  26067. 'events.breakpoint_modified'

  26068.      This is emitted when a breakpoint has been modified in some way.

  26069.      The argument that is passed is the new 'gdb.Breakpoint' object.

  26070. 

  26071. 'events.breakpoint_deleted'

  26072.      This is emitted when a breakpoint has been deleted.  The argument

  26073.      that is passed is the 'gdb.Breakpoint' object.  When this event is

  26074.      emitted, the 'gdb.Breakpoint' object will already be in its invalid

  26075.      state; that is, the 'is_valid' method will return 'False'.

  26076. 

  26077. 'events.before_prompt'

  26078.      This event carries no payload.  It is emitted each time GDB

  26079.      presents a prompt to the user.

  26080. 

  26081. 'events.new_inferior'

  26082.      This is emitted when a new inferior is created.  Note that the

  26083.      inferior is not necessarily running; in fact, it may not even have

  26084.      an associated executable.

  26085. 

  26086.      The event is of type 'gdb.NewInferiorEvent'.  This has a single

  26087.      attribute:

  26088. 

  26089.       -- Variable: NewInferiorEvent.inferior

  26090.           The new inferior, a 'gdb.Inferior' object.

  26091. 

  26092. 'events.inferior_deleted'

  26093.      This is emitted when an inferior has been deleted.  Note that this

  26094.      is not the same as process exit; it is notified when the inferior

  26095.      itself is removed, say via 'remove-inferiors'.

  26096. 

  26097.      The event is of type 'gdb.InferiorDeletedEvent'.  This has a single

  26098.      attribute:

  26099. 

  26100.       -- Variable: NewInferiorEvent.inferior

  26101.           The inferior that is being removed, a 'gdb.Inferior' object.

  26102. 

  26103. 'events.new_thread'

  26104.      This is emitted when GDB notices a new thread.  The event is of

  26105.      type 'gdb.NewThreadEvent', which extends 'gdb.ThreadEvent'.  This

  26106.      has a single attribute:

  26107. 

  26108.       -- Variable: NewThreadEvent.inferior_thread

  26109.           The new thread.

  26110. 

  26111. 

  26112. File: gdb.info,  Node: Threads In Python,  Next: Recordings In Python,  Prev: Events In Python,  Up: Python API

  26113. 

  26114. 23.2.2.18 Threads In Python

  26115. ...........................

  26116. 

  26117. Python scripts can access information about, and manipulate inferior

  26118. threads controlled by GDB, via objects of the 'gdb.InferiorThread'

  26119. class.

  26120. 

  26121.    The following thread-related functions are available in the 'gdb'

  26122. module:

  26123. 

  26124.  -- Function: gdb.selected_thread ()

  26125.      This function returns the thread object for the selected thread.

  26126.      If there is no selected thread, this will return 'None'.

  26127. 

  26128.    To get the list of threads for an inferior, use the

  26129. 'Inferior.threads()' method.  *Note Inferiors In Python::.

  26130. 

  26131.    A 'gdb.InferiorThread' object has the following attributes:

  26132. 

  26133.  -- Variable: InferiorThread.name

  26134.      The name of the thread.  If the user specified a name using 'thread

  26135.      name', then this returns that name.  Otherwise, if an OS-supplied

  26136.      name is available, then it is returned.  Otherwise, this returns

  26137.      'None'.

  26138. 

  26139.      This attribute can be assigned to.  The new value must be a string

  26140.      object, which sets the new name, or 'None', which removes any

  26141.      user-specified thread name.

  26142. 

  26143.  -- Variable: InferiorThread.num

  26144.      The per-inferior number of the thread, as assigned by GDB.

  26145. 

  26146.  -- Variable: InferiorThread.global_num

  26147.      The global ID of the thread, as assigned by GDB. You can use this

  26148.      to make Python breakpoints thread-specific, for example (*note The

  26149.      Breakpoint.thread attribute: python_breakpoint_thread.).

  26150. 

  26151.  -- Variable: InferiorThread.ptid

  26152.      ID of the thread, as assigned by the operating system.  This

  26153.      attribute is a tuple containing three integers.  The first is the

  26154.      Process ID (PID); the second is the Lightweight Process ID (LWPID),

  26155.      and the third is the Thread ID (TID). Either the LWPID or TID may

  26156.      be 0, which indicates that the operating system does not use that

  26157.      identifier.

  26158. 

  26159.  -- Variable: InferiorThread.inferior

  26160.      The inferior this thread belongs to.  This attribute is represented

  26161.      as a 'gdb.Inferior' object.  This attribute is not writable.

  26162. 

  26163.    A 'gdb.InferiorThread' object has the following methods:

  26164. 

  26165.  -- Function: InferiorThread.is_valid ()

  26166.      Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False'

  26167.      if not.  A 'gdb.InferiorThread' object will become invalid if the

  26168.      thread exits, or the inferior that the thread belongs is deleted.

  26169.      All other 'gdb.InferiorThread' methods will throw an exception if

  26170.      it is invalid at the time the method is called.

  26171. 

  26172.  -- Function: InferiorThread.switch ()

  26173.      This changes GDB's currently selected thread to the one represented

  26174.      by this object.

  26175. 

  26176.  -- Function: InferiorThread.is_stopped ()

  26177.      Return a Boolean indicating whether the thread is stopped.

  26178. 

  26179.  -- Function: InferiorThread.is_running ()

  26180.      Return a Boolean indicating whether the thread is running.

  26181. 

  26182.  -- Function: InferiorThread.is_exited ()

  26183.      Return a Boolean indicating whether the thread is exited.

  26184. 

  26185.  -- Function: InferiorThread.handle ()

  26186.      Return the thread object's handle, represented as a Python 'bytes'

  26187.      object.  A 'gdb.Value' representation of the handle may be

  26188.      constructed via 'gdb.Value(bufobj, type)' where BUFOBJ is the

  26189.      Python 'bytes' representation of the handle and TYPE is a

  26190.      'gdb.Type' for the handle type.

  26191. 

  26192. 

  26193. File: gdb.info,  Node: Recordings In Python,  Next: Commands In Python,  Prev: Threads In Python,  Up: Python API

  26194. 

  26195. 23.2.2.19 Recordings In Python

  26196. ..............................

  26197. 

  26198. The following recordings-related functions (*note Process Record and

  26199. Replay::) are available in the 'gdb' module:

  26200. 

  26201.  -- Function: gdb.start_recording ([method], [format])

  26202.      Start a recording using the given METHOD and FORMAT.  If no FORMAT

  26203.      is given, the default format for the recording method is used.  If

  26204.      no METHOD is given, the default method will be used.  Returns a

  26205.      'gdb.Record' object on success.  Throw an exception on failure.

  26206. 

  26207.      The following strings can be passed as METHOD:

  26208. 

  26209.         * '"full"'

  26210.         * '"btrace"': Possible values for FORMAT: '"pt"', '"bts"' or

  26211.           leave out for default format.

  26212. 

  26213.  -- Function: gdb.current_recording ()

  26214.      Access a currently running recording.  Return a 'gdb.Record' object

  26215.      on success.  Return 'None' if no recording is currently active.

  26216. 

  26217.  -- Function: gdb.stop_recording ()

  26218.      Stop the current recording.  Throw an exception if no recording is

  26219.      currently active.  All record objects become invalid after this

  26220.      call.

  26221. 

  26222.    A 'gdb.Record' object has the following attributes:

  26223. 

  26224.  -- Variable: Record.method

  26225.      A string with the current recording method, e.g. 'full' or

  26226.      'btrace'.

  26227. 

  26228.  -- Variable: Record.format

  26229.      A string with the current recording format, e.g. 'bt', 'pts' or

  26230.      'None'.

  26231. 

  26232.  -- Variable: Record.begin

  26233.      A method specific instruction object representing the first

  26234.      instruction in this recording.

  26235. 

  26236.  -- Variable: Record.end

  26237.      A method specific instruction object representing the current

  26238.      instruction, that is not actually part of the recording.

  26239. 

  26240.  -- Variable: Record.replay_position

  26241.      The instruction representing the current replay position.  If there

  26242.      is no replay active, this will be 'None'.

  26243. 

  26244.  -- Variable: Record.instruction_history

  26245.      A list with all recorded instructions.

  26246. 

  26247.  -- Variable: Record.function_call_history

  26248.      A list with all recorded function call segments.

  26249. 

  26250.    A 'gdb.Record' object has the following methods:

  26251. 

  26252.  -- Function: Record.goto (instruction)

  26253.      Move the replay position to the given INSTRUCTION.

  26254. 

  26255.    The common 'gdb.Instruction' class that recording method specific

  26256. instruction objects inherit from, has the following attributes:

  26257. 

  26258.  -- Variable: Instruction.pc

  26259.      An integer representing this instruction's address.

  26260. 

  26261.  -- Variable: Instruction.data

  26262.      A buffer with the raw instruction data.  In Python 3, the return

  26263.      value is a 'memoryview' object.

  26264. 

  26265.  -- Variable: Instruction.decoded

  26266.      A human readable string with the disassembled instruction.

  26267. 

  26268.  -- Variable: Instruction.size

  26269.      The size of the instruction in bytes.

  26270. 

  26271.    Additionally 'gdb.RecordInstruction' has the following attributes:

  26272. 

  26273.  -- Variable: RecordInstruction.number

  26274.      An integer identifying this instruction.  'number' corresponds to

  26275.      the numbers seen in 'record instruction-history' (*note Process

  26276.      Record and Replay::).

  26277. 

  26278.  -- Variable: RecordInstruction.sal

  26279.      A 'gdb.Symtab_and_line' object representing the associated symtab

  26280.      and line of this instruction.  May be 'None' if no debug

  26281.      information is available.

  26282. 

  26283.  -- Variable: RecordInstruction.is_speculative

  26284.      A boolean indicating whether the instruction was executed

  26285.      speculatively.

  26286. 

  26287.    If an error occured during recording or decoding a recording, this

  26288. error is represented by a 'gdb.RecordGap' object in the instruction

  26289. list.  It has the following attributes:

  26290. 

  26291.  -- Variable: RecordGap.number

  26292.      An integer identifying this gap.  'number' corresponds to the

  26293.      numbers seen in 'record instruction-history' (*note Process Record

  26294.      and Replay::).

  26295. 

  26296.  -- Variable: RecordGap.error_code

  26297.      A numerical representation of the reason for the gap.  The value is

  26298.      specific to the current recording method.

  26299. 

  26300.  -- Variable: RecordGap.error_string

  26301.      A human readable string with the reason for the gap.

  26302. 

  26303.    A 'gdb.RecordFunctionSegment' object has the following attributes:

  26304. 

  26305.  -- Variable: RecordFunctionSegment.number

  26306.      An integer identifying this function segment.  'number' corresponds

  26307.      to the numbers seen in 'record function-call-history' (*note

  26308.      Process Record and Replay::).

  26309. 

  26310.  -- Variable: RecordFunctionSegment.symbol

  26311.      A 'gdb.Symbol' object representing the associated symbol.  May be

  26312.      'None' if no debug information is available.

  26313. 

  26314.  -- Variable: RecordFunctionSegment.level

  26315.      An integer representing the function call's stack level.  May be

  26316.      'None' if the function call is a gap.

  26317. 

  26318.  -- Variable: RecordFunctionSegment.instructions

  26319.      A list of 'gdb.RecordInstruction' or 'gdb.RecordGap' objects

  26320.      associated with this function call.

  26321. 

  26322.  -- Variable: RecordFunctionSegment.up

  26323.      A 'gdb.RecordFunctionSegment' object representing the caller's

  26324.      function segment.  If the call has not been recorded, this will be

  26325.      the function segment to which control returns.  If neither the call

  26326.      nor the return have been recorded, this will be 'None'.

  26327. 

  26328.  -- Variable: RecordFunctionSegment.prev

  26329.      A 'gdb.RecordFunctionSegment' object representing the previous

  26330.      segment of this function call.  May be 'None'.

  26331. 

  26332.  -- Variable: RecordFunctionSegment.next

  26333.      A 'gdb.RecordFunctionSegment' object representing the next segment

  26334.      of this function call.  May be 'None'.

  26335. 

  26336.    The following example demonstrates the usage of these objects and

  26337. functions to create a function that will rewind a record to the last

  26338. time a function in a different file was executed.  This would typically

  26339. be used to track the execution of user provided callback functions in a

  26340. library which typically are not visible in a back trace.

  26341. 

  26342.      def bringback ():

  26343.          rec = gdb.current_recording ()

  26344.          if not rec:

  26345.              return

  26346. 

  26347.          insn = rec.instruction_history

  26348.          if len (insn) == 0:

  26349.              return

  26350. 

  26351.          try:

  26352.              position = insn.index (rec.replay_position)

  26353.          except:

  26354.              position = -1

  26355.          try:

  26356.              filename = insn[position].sal.symtab.fullname ()

  26357.          except:

  26358.              filename = None

  26359. 

  26360.          for i in reversed (insn[:position]):

  26361.      	try:

  26362.                  current = i.sal.symtab.fullname ()

  26363.      	except:

  26364.                  current = None

  26365. 

  26366.              if filename == current:

  26367.                  continue

  26368. 

  26369.              rec.goto (i)

  26370.              return

  26371. 

  26372.    Another possible application is to write a function that counts the

  26373. number of code executions in a given line range.  This line range can

  26374. contain parts of functions or span across several functions and is not

  26375. limited to be contiguous.

  26376. 

  26377.      def countrange (filename, linerange):

  26378.          count = 0

  26379. 

  26380.          def filter_only (file_name):

  26381.              for call in gdb.current_recording ().function_call_history:

  26382.                  try:

  26383.                      if file_name in call.symbol.symtab.fullname ():

  26384.                          yield call

  26385.                  except:

  26386.                      pass

  26387. 

  26388.          for c in filter_only (filename):

  26389.              for i in c.instructions:

  26390.                  try:

  26391.                      if i.sal.line in linerange:

  26392.                          count += 1

  26393.                          break;

  26394.                  except:

  26395.                          pass

  26396. 

  26397.          return count

  26398. 

  26399. 

  26400. File: gdb.info,  Node: Commands In Python,  Next: Parameters In Python,  Prev: Recordings In Python,  Up: Python API

  26401. 

  26402. 23.2.2.20 Commands In Python

  26403. ............................

  26404. 

  26405. You can implement new GDB CLI commands in Python.  A CLI command is

  26406. implemented using an instance of the 'gdb.Command' class, most commonly

  26407. using a subclass.

  26408. 

  26409.  -- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS

  26410.           [, PREFIX]])

  26411.      The object initializer for 'Command' registers the new command with

  26412.      GDB.  This initializer is normally invoked from the subclass' own

  26413.      '__init__' method.

  26414. 

  26415.      NAME is the name of the command.  If NAME consists of multiple

  26416.      words, then the initial words are looked for as prefix commands.

  26417.      In this case, if one of the prefix commands does not exist, an

  26418.      exception is raised.

  26419. 

  26420.      There is no support for multi-line commands.

  26421. 

  26422.      COMMAND_CLASS should be one of the 'COMMAND_' constants defined

  26423.      below.  This argument tells GDB how to categorize the new command

  26424.      in the help system.

  26425. 

  26426.      COMPLETER_CLASS is an optional argument.  If given, it should be

  26427.      one of the 'COMPLETE_' constants defined below.  This argument

  26428.      tells GDB how to perform completion for this command.  If not

  26429.      given, GDB will attempt to complete using the object's 'complete'

  26430.      method (see below); if no such method is found, an error will occur

  26431.      when completion is attempted.

  26432. 

  26433.      PREFIX is an optional argument.  If 'True', then the new command is

  26434.      a prefix command; sub-commands of this command may be registered.

  26435. 

  26436.      The help text for the new command is taken from the Python

  26437.      documentation string for the command's class, if there is one.  If

  26438.      no documentation string is provided, the default value "This

  26439.      command is not documented."  is used.

  26440. 

  26441.  -- Function: Command.dont_repeat ()

  26442.      By default, a GDB command is repeated when the user enters a blank

  26443.      line at the command prompt.  A command can suppress this behavior

  26444.      by invoking the 'dont_repeat' method.  This is similar to the user

  26445.      command 'dont-repeat', see *note dont-repeat: Define.

  26446. 

  26447.  -- Function: Command.invoke (argument, from_tty)

  26448.      This method is called by GDB when this command is invoked.

  26449. 

  26450.      ARGUMENT is a string.  It is the argument to the command, after

  26451.      leading and trailing whitespace has been stripped.

  26452. 

  26453.      FROM_TTY is a boolean argument.  When true, this means that the

  26454.      command was entered by the user at the terminal; when false it

  26455.      means that the command came from elsewhere.

  26456. 

  26457.      If this method throws an exception, it is turned into a GDB 'error'

  26458.      call.  Otherwise, the return value is ignored.

  26459. 

  26460.      To break ARGUMENT up into an argv-like string use

  26461.      'gdb.string_to_argv'.  This function behaves identically to GDB's

  26462.      internal argument lexer 'buildargv'.  It is recommended to use this

  26463.      for consistency.  Arguments are separated by spaces and may be

  26464.      quoted.  Example:

  26465. 

  26466.           print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")

  26467.           ['1', '2 "3', '4 "5', "6 '7"]

  26468. 

  26469.  -- Function: Command.complete (text, word)

  26470.      This method is called by GDB when the user attempts completion on

  26471.      this command.  All forms of completion are handled by this method,

  26472.      that is, the <TAB> and <M-?> key bindings (*note Completion::), and

  26473.      the 'complete' command (*note complete: Help.).

  26474. 

  26475.      The arguments TEXT and WORD are both strings; TEXT holds the

  26476.      complete command line up to the cursor's location, while WORD holds

  26477.      the last word of the command line; this is computed using a

  26478.      word-breaking heuristic.

  26479. 

  26480.      The 'complete' method can return several values:

  26481.         * If the return value is a sequence, the contents of the

  26482.           sequence are used as the completions.  It is up to 'complete'

  26483.           to ensure that the contents actually do complete the word.  A

  26484.           zero-length sequence is allowed, it means that there were no

  26485.           completions available.  Only string elements of the sequence

  26486.           are used; other elements in the sequence are ignored.

  26487. 

  26488.         * If the return value is one of the 'COMPLETE_' constants

  26489.           defined below, then the corresponding GDB-internal completion

  26490.           function is invoked, and its result is used.

  26491. 

  26492.         * All other results are treated as though there were no

  26493.           available completions.

  26494. 

  26495.    When a new command is registered, it must be declared as a member of

  26496. some general class of commands.  This is used to classify top-level

  26497. commands in the on-line help system; note that prefix commands are not

  26498. listed under their own category but rather that of their top-level

  26499. command.  The available classifications are represented by constants

  26500. defined in the 'gdb' module:

  26501. 

  26502. 'gdb.COMMAND_NONE'

  26503.      The command does not belong to any particular class.  A command in

  26504.      this category will not be displayed in any of the help categories.

  26505. 

  26506. 'gdb.COMMAND_RUNNING'

  26507.      The command is related to running the inferior.  For example,

  26508.      'start', 'step', and 'continue' are in this category.  Type 'help

  26509.      running' at the GDB prompt to see a list of commands in this

  26510.      category.

  26511. 

  26512. 'gdb.COMMAND_DATA'

  26513.      The command is related to data or variables.  For example, 'call',

  26514.      'find', and 'print' are in this category.  Type 'help data' at the

  26515.      GDB prompt to see a list of commands in this category.

  26516. 

  26517. 'gdb.COMMAND_STACK'

  26518.      The command has to do with manipulation of the stack.  For example,

  26519.      'backtrace', 'frame', and 'return' are in this category.  Type

  26520.      'help stack' at the GDB prompt to see a list of commands in this

  26521.      category.

  26522. 

  26523. 'gdb.COMMAND_FILES'

  26524.      This class is used for file-related commands.  For example, 'file',

  26525.      'list' and 'section' are in this category.  Type 'help files' at

  26526.      the GDB prompt to see a list of commands in this category.

  26527. 

  26528. 'gdb.COMMAND_SUPPORT'

  26529.      This should be used for "support facilities", generally meaning

  26530.      things that are useful to the user when interacting with GDB, but

  26531.      not related to the state of the inferior.  For example, 'help',

  26532.      'make', and 'shell' are in this category.  Type 'help support' at

  26533.      the GDB prompt to see a list of commands in this category.

  26534. 

  26535. 'gdb.COMMAND_STATUS'

  26536.      The command is an 'info'-related command, that is, related to the

  26537.      state of GDB itself.  For example, 'info', 'macro', and 'show' are

  26538.      in this category.  Type 'help status' at the GDB prompt to see a

  26539.      list of commands in this category.

  26540. 

  26541. 'gdb.COMMAND_BREAKPOINTS'

  26542.      The command has to do with breakpoints.  For example, 'break',

  26543.      'clear', and 'delete' are in this category.  Type 'help

  26544.      breakpoints' at the GDB prompt to see a list of commands in this

  26545.      category.

  26546. 

  26547. 'gdb.COMMAND_TRACEPOINTS'

  26548.      The command has to do with tracepoints.  For example, 'trace',

  26549.      'actions', and 'tfind' are in this category.  Type 'help

  26550.      tracepoints' at the GDB prompt to see a list of commands in this

  26551.      category.

  26552. 

  26553. 'gdb.COMMAND_TUI'

  26554.      The command has to do with the text user interface (*note TUI::).

  26555.      Type 'help tui' at the GDB prompt to see a list of commands in this

  26556.      category.

  26557. 

  26558. 'gdb.COMMAND_USER'

  26559.      The command is a general purpose command for the user, and

  26560.      typically does not fit in one of the other categories.  Type 'help

  26561.      user-defined' at the GDB prompt to see a list of commands in this

  26562.      category, as well as the list of gdb macros (*note Sequences::).

  26563. 

  26564. 'gdb.COMMAND_OBSCURE'

  26565.      The command is only used in unusual circumstances, or is not of

  26566.      general interest to users.  For example, 'checkpoint', 'fork', and

  26567.      'stop' are in this category.  Type 'help obscure' at the GDB prompt

  26568.      to see a list of commands in this category.

  26569. 

  26570. 'gdb.COMMAND_MAINTENANCE'

  26571.      The command is only useful to GDB maintainers.  The 'maintenance'

  26572.      and 'flushregs' commands are in this category.  Type 'help

  26573.      internals' at the GDB prompt to see a list of commands in this

  26574.      category.

  26575. 

  26576.    A new command can use a predefined completion function, either by

  26577. specifying it via an argument at initialization, or by returning it from

  26578. the 'complete' method.  These predefined completion constants are all

  26579. defined in the 'gdb' module:

  26580. 

  26581. 'gdb.COMPLETE_NONE'

  26582.      This constant means that no completion should be done.

  26583. 

  26584. 'gdb.COMPLETE_FILENAME'

  26585.      This constant means that filename completion should be performed.

  26586. 

  26587. 'gdb.COMPLETE_LOCATION'

  26588.      This constant means that location completion should be done.  *Note

  26589.      Specify Location::.

  26590. 

  26591. 'gdb.COMPLETE_COMMAND'

  26592.      This constant means that completion should examine GDB command

  26593.      names.

  26594. 

  26595. 'gdb.COMPLETE_SYMBOL'

  26596.      This constant means that completion should be done using symbol

  26597.      names as the source.

  26598. 

  26599. 'gdb.COMPLETE_EXPRESSION'

  26600.      This constant means that completion should be done on expressions.

  26601.      Often this means completing on symbol names, but some language

  26602.      parsers also have support for completing on field names.

  26603. 

  26604.    The following code snippet shows how a trivial CLI command can be

  26605. implemented in Python:

  26606. 

  26607.      class HelloWorld (gdb.Command):

  26608.        """Greet the whole world."""

  26609. 

  26610.        def __init__ (self):

  26611.          super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)

  26612. 

  26613.        def invoke (self, arg, from_tty):

  26614.          print "Hello, World!"

  26615. 

  26616.      HelloWorld ()

  26617. 

  26618.    The last line instantiates the class, and is necessary to trigger the

  26619. registration of the command with GDB.  Depending on how the Python code

  26620. is read into GDB, you may need to import the 'gdb' module explicitly.

  26621. 

  26622. 

  26623. File: gdb.info,  Node: Parameters In Python,  Next: Functions In Python,  Prev: Commands In Python,  Up: Python API

  26624. 

  26625. 23.2.2.21 Parameters In Python

  26626. ..............................

  26627. 

  26628. You can implement new GDB parameters using Python.  A new parameter is

  26629. implemented as an instance of the 'gdb.Parameter' class.

  26630. 

  26631.    Parameters are exposed to the user via the 'set' and 'show' commands.

  26632. *Note Help::.

  26633. 

  26634.    There are many parameters that already exist and can be set in GDB.

  26635. Two examples are: 'set follow fork' and 'set charset'.  Setting these

  26636. parameters influences certain behavior in GDB.  Similarly, you can

  26637. define parameters that can be used to influence behavior in custom

  26638. Python scripts and commands.

  26639. 

  26640.  -- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS

  26641.           [, ENUM-SEQUENCE])

  26642.      The object initializer for 'Parameter' registers the new parameter

  26643.      with GDB.  This initializer is normally invoked from the subclass'

  26644.      own '__init__' method.

  26645. 

  26646.      NAME is the name of the new parameter.  If NAME consists of

  26647.      multiple words, then the initial words are looked for as prefix

  26648.      parameters.  An example of this can be illustrated with the 'set

  26649.      print' set of parameters.  If NAME is 'print foo', then 'print'

  26650.      will be searched as the prefix parameter.  In this case the

  26651.      parameter can subsequently be accessed in GDB as 'set print foo'.

  26652. 

  26653.      If NAME consists of multiple words, and no prefix parameter group

  26654.      can be found, an exception is raised.

  26655. 

  26656.      COMMAND-CLASS should be one of the 'COMMAND_' constants (*note

  26657.      Commands In Python::).  This argument tells GDB how to categorize

  26658.      the new parameter in the help system.

  26659. 

  26660.      PARAMETER-CLASS should be one of the 'PARAM_' constants defined

  26661.      below.  This argument tells GDB the type of the new parameter; this

  26662.      information is used for input validation and completion.

  26663. 

  26664.      If PARAMETER-CLASS is 'PARAM_ENUM', then ENUM-SEQUENCE must be a

  26665.      sequence of strings.  These strings represent the possible values

  26666.      for the parameter.

  26667. 

  26668.      If PARAMETER-CLASS is not 'PARAM_ENUM', then the presence of a

  26669.      fourth argument will cause an exception to be thrown.

  26670. 

  26671.      The help text for the new parameter is taken from the Python

  26672.      documentation string for the parameter's class, if there is one.

  26673.      If there is no documentation string, a default value is used.

  26674. 

  26675.  -- Variable: Parameter.set_doc

  26676.      If this attribute exists, and is a string, then its value is used

  26677.      as the help text for this parameter's 'set' command.  The value is

  26678.      examined when 'Parameter.__init__' is invoked; subsequent changes

  26679.      have no effect.

  26680. 

  26681.  -- Variable: Parameter.show_doc

  26682.      If this attribute exists, and is a string, then its value is used

  26683.      as the help text for this parameter's 'show' command.  The value is

  26684.      examined when 'Parameter.__init__' is invoked; subsequent changes

  26685.      have no effect.

  26686. 

  26687.  -- Variable: Parameter.value

  26688.      The 'value' attribute holds the underlying value of the parameter.

  26689.      It can be read and assigned to just as any other attribute.  GDB

  26690.      does validation when assignments are made.

  26691. 

  26692.    There are two methods that may be implemented in any 'Parameter'

  26693. class.  These are:

  26694. 

  26695.  -- Function: Parameter.get_set_string (self)

  26696.      If this method exists, GDB will call it when a PARAMETER's value

  26697.      has been changed via the 'set' API (for example, 'set foo off').

  26698.      The 'value' attribute has already been populated with the new value

  26699.      and may be used in output.  This method must return a string.  If

  26700.      the returned string is not empty, GDB will present it to the user.

  26701. 

  26702.      If this method raises the 'gdb.GdbError' exception (*note Exception

  26703.      Handling::), then GDB will print the exception's string and the

  26704.      'set' command will fail.  Note, however, that the 'value' attribute

  26705.      will not be reset in this case.  So, if your parameter must

  26706.      validate values, it should store the old value internally and reset

  26707.      the exposed value, like so:

  26708. 

  26709.           class ExampleParam (gdb.Parameter):

  26710.              def __init__ (self, name):

  26711.                 super (ExampleParam, self).__init__ (name,

  26712.                              gdb.COMMAND_DATA,

  26713.                              gdb.PARAM_BOOLEAN)

  26714.                 self.value = True

  26715.                 self.saved_value = True

  26716.              def validate(self):

  26717.                 return False

  26718.              def get_set_string (self):

  26719.                 if not self.validate():

  26720.                   self.value = self.saved_value

  26721.                   raise gdb.GdbError('Failed to validate')

  26722.                 self.saved_value = self.value

  26723. 

  26724.  -- Function: Parameter.get_show_string (self, svalue)

  26725.      GDB will call this method when a PARAMETER's 'show' API has been

  26726.      invoked (for example, 'show foo').  The argument 'svalue' receives

  26727.      the string representation of the current value.  This method must

  26728.      return a string.

  26729. 

  26730.    When a new parameter is defined, its type must be specified.  The

  26731. available types are represented by constants defined in the 'gdb'

  26732. module:

  26733. 

  26734. 'gdb.PARAM_BOOLEAN'

  26735.      The value is a plain boolean.  The Python boolean values, 'True'

  26736.      and 'False' are the only valid values.

  26737. 

  26738. 'gdb.PARAM_AUTO_BOOLEAN'

  26739.      The value has three possible states: true, false, and 'auto'.  In

  26740.      Python, true and false are represented using boolean constants, and

  26741.      'auto' is represented using 'None'.

  26742. 

  26743. 'gdb.PARAM_UINTEGER'

  26744.      The value is an unsigned integer.  The value of 0 should be

  26745.      interpreted to mean "unlimited".

  26746. 

  26747. 'gdb.PARAM_INTEGER'

  26748.      The value is a signed integer.  The value of 0 should be

  26749.      interpreted to mean "unlimited".

  26750. 

  26751. 'gdb.PARAM_STRING'

  26752.      The value is a string.  When the user modifies the string, any

  26753.      escape sequences, such as '\t', '\f', and octal escapes, are

  26754.      translated into corresponding characters and encoded into the

  26755.      current host charset.

  26756. 

  26757. 'gdb.PARAM_STRING_NOESCAPE'

  26758.      The value is a string.  When the user modifies the string, escapes

  26759.      are passed through untranslated.

  26760. 

  26761. 'gdb.PARAM_OPTIONAL_FILENAME'

  26762.      The value is a either a filename (a string), or 'None'.

  26763. 

  26764. 'gdb.PARAM_FILENAME'

  26765.      The value is a filename.  This is just like

  26766.      'PARAM_STRING_NOESCAPE', but uses file names for completion.

  26767. 

  26768. 'gdb.PARAM_ZINTEGER'

  26769.      The value is an integer.  This is like 'PARAM_INTEGER', except 0 is

  26770.      interpreted as itself.

  26771. 

  26772. 'gdb.PARAM_ZUINTEGER'

  26773.      The value is an unsigned integer.  This is like 'PARAM_INTEGER',

  26774.      except 0 is interpreted as itself, and the value cannot be

  26775.      negative.

  26776. 

  26777. 'gdb.PARAM_ZUINTEGER_UNLIMITED'

  26778.      The value is a signed integer.  This is like 'PARAM_ZUINTEGER',

  26779.      except the special value -1 should be interpreted to mean

  26780.      "unlimited".  Other negative values are not allowed.

  26781. 

  26782. 'gdb.PARAM_ENUM'

  26783.      The value is a string, which must be one of a collection string

  26784.      constants provided when the parameter is created.

  26785. 

  26786. 

  26787. File: gdb.info,  Node: Functions In Python,  Next: Progspaces In Python,  Prev: Parameters In Python,  Up: Python API

  26788. 

  26789. 23.2.2.22 Writing new convenience functions

  26790. ...........................................

  26791. 

  26792. You can implement new convenience functions (*note Convenience Vars::)

  26793. in Python.  A convenience function is an instance of a subclass of the

  26794. class 'gdb.Function'.

  26795. 

  26796.  -- Function: Function.__init__ (name)

  26797.      The initializer for 'Function' registers the new function with GDB.

  26798.      The argument NAME is the name of the function, a string.  The

  26799.      function will be visible to the user as a convenience variable of

  26800.      type 'internal function', whose name is the same as the given NAME.

  26801. 

  26802.      The documentation for the new function is taken from the

  26803.      documentation string for the new class.

  26804. 

  26805.  -- Function: Function.invoke (*ARGS)

  26806.      When a convenience function is evaluated, its arguments are

  26807.      converted to instances of 'gdb.Value', and then the function's

  26808.      'invoke' method is called.  Note that GDB does not predetermine the

  26809.      arity of convenience functions.  Instead, all available arguments

  26810.      are passed to 'invoke', following the standard Python calling

  26811.      convention.  In particular, a convenience function can have default

  26812.      values for parameters without ill effect.

  26813. 

  26814.      The return value of this method is used as its value in the

  26815.      enclosing expression.  If an ordinary Python value is returned, it

  26816.      is converted to a 'gdb.Value' following the usual rules.

  26817. 

  26818.    The following code snippet shows how a trivial convenience function

  26819. can be implemented in Python:

  26820. 

  26821.      class Greet (gdb.Function):

  26822.        """Return string to greet someone.

  26823.      Takes a name as argument."""

  26824. 

  26825.        def __init__ (self):

  26826.          super (Greet, self).__init__ ("greet")

  26827. 

  26828.        def invoke (self, name):

  26829.          return "Hello, %s!" % name.string ()

  26830. 

  26831.      Greet ()

  26832. 

  26833.    The last line instantiates the class, and is necessary to trigger the

  26834. registration of the function with GDB.  Depending on how the Python code

  26835. is read into GDB, you may need to import the 'gdb' module explicitly.

  26836. 

  26837.    Now you can use the function in an expression:

  26838. 

  26839.      (gdb) print $greet("Bob")

  26840.      $1 = "Hello, Bob!"

  26841. 

  26842. 

  26843. File: gdb.info,  Node: Progspaces In Python,  Next: Objfiles In Python,  Prev: Functions In Python,  Up: Python API

  26844. 

  26845. 23.2.2.23 Program Spaces In Python

  26846. ..................................

  26847. 

  26848. A program space, or "progspace", represents a symbolic view of an

  26849. address space.  It consists of all of the objfiles of the program.

  26850. *Note Objfiles In Python::.  *Note program spaces: Inferiors Connections

  26851. and Programs, for more details about program spaces.

  26852. 

  26853.    The following progspace-related functions are available in the 'gdb'

  26854. module:

  26855. 

  26856.  -- Function: gdb.current_progspace ()

  26857.      This function returns the program space of the currently selected

  26858.      inferior.  *Note Inferiors Connections and Programs::.  This is

  26859.      identical to 'gdb.selected_inferior().progspace' (*note Inferiors

  26860.      In Python::) and is included for historical compatibility.

  26861. 

  26862.  -- Function: gdb.progspaces ()

  26863.      Return a sequence of all the progspaces currently known to GDB.

  26864. 

  26865.    Each progspace is represented by an instance of the 'gdb.Progspace'

  26866. class.

  26867. 

  26868.  -- Variable: Progspace.filename

  26869.      The file name of the progspace as a string.

  26870. 

  26871.  -- Variable: Progspace.pretty_printers

  26872.      The 'pretty_printers' attribute is a list of functions.  It is used

  26873.      to look up pretty-printers.  A 'Value' is passed to each function

  26874.      in order; if the function returns 'None', then the search

  26875.      continues.  Otherwise, the return value should be an object which

  26876.      is used to format the value.  *Note Pretty Printing API::, for more

  26877.      information.

  26878. 

  26879.  -- Variable: Progspace.type_printers

  26880.      The 'type_printers' attribute is a list of type printer objects.

  26881.      *Note Type Printing API::, for more information.

  26882. 

  26883.  -- Variable: Progspace.frame_filters

  26884.      The 'frame_filters' attribute is a dictionary of frame filter

  26885.      objects.  *Note Frame Filter API::, for more information.

  26886. 

  26887.    A program space has the following methods:

  26888. 

  26889.  -- Function: Progspace.block_for_pc (pc)

  26890.      Return the innermost 'gdb.Block' containing the given PC value.  If

  26891.      the block cannot be found for the PC value specified, the function

  26892.      will return 'None'.

  26893. 

  26894.  -- Function: Progspace.find_pc_line (pc)

  26895.      Return the 'gdb.Symtab_and_line' object corresponding to the PC

  26896.      value.  *Note Symbol Tables In Python::.  If an invalid value of PC

  26897.      is passed as an argument, then the 'symtab' and 'line' attributes

  26898.      of the returned 'gdb.Symtab_and_line' object will be 'None' and 0

  26899.      respectively.

  26900. 

  26901.  -- Function: Progspace.is_valid ()

  26902.      Returns 'True' if the 'gdb.Progspace' object is valid, 'False' if

  26903.      not.  A 'gdb.Progspace' object can become invalid if the program

  26904.      space file it refers to is not referenced by any inferior.  All

  26905.      other 'gdb.Progspace' methods will throw an exception if it is

  26906.      invalid at the time the method is called.

  26907. 

  26908.  -- Function: Progspace.objfiles ()

  26909.      Return a sequence of all the objfiles referenced by this program

  26910.      space.  *Note Objfiles In Python::.

  26911. 

  26912.  -- Function: Progspace.solib_name (address)

  26913.      Return the name of the shared library holding the given ADDRESS as

  26914.      a string, or 'None'.

  26915. 

  26916.    One may add arbitrary attributes to 'gdb.Progspace' objects in the

  26917. usual Python way.  This is useful if, for example, one needs to do some

  26918. extra record keeping associated with the program space.

  26919. 

  26920.    In this contrived example, we want to perform some processing when an

  26921. objfile with a certain symbol is loaded, but we only want to do this

  26922. once because it is expensive.  To achieve this we record the results

  26923. with the program space because we can't predict when the desired objfile

  26924. will be loaded.

  26925. 

  26926.      (gdb) python

  26927.      def clear_objfiles_handler(event):

  26928.          event.progspace.expensive_computation = None

  26929.      def expensive(symbol):

  26930.          """A mock routine to perform an "expensive" computation on symbol."""

  26931.          print "Computing the answer to the ultimate question ..."

  26932.          return 42

  26933.      def new_objfile_handler(event):

  26934.          objfile = event.new_objfile

  26935.          progspace = objfile.progspace

  26936.          if not hasattr(progspace, 'expensive_computation') or \

  26937.                  progspace.expensive_computation is None:

  26938.              # We use 'main' for the symbol to keep the example simple.

  26939.              # Note: There's no current way to constrain the lookup

  26940.              # to one objfile.

  26941.              symbol = gdb.lookup_global_symbol('main')

  26942.              if symbol is not None:

  26943.                  progspace.expensive_computation = expensive(symbol)

  26944.      gdb.events.clear_objfiles.connect(clear_objfiles_handler)

  26945.      gdb.events.new_objfile.connect(new_objfile_handler)

  26946.      end

  26947.      (gdb) file /tmp/hello

  26948.      Reading symbols from /tmp/hello...

  26949.      Computing the answer to the ultimate question ...

  26950.      (gdb) python print gdb.current_progspace().expensive_computation

  26951.      42

  26952.      (gdb) run

  26953.      Starting program: /tmp/hello

  26954.      Hello.

  26955.      [Inferior 1 (process 4242) exited normally]

  26956. 

  26957. 

  26958. File: gdb.info,  Node: Objfiles In Python,  Next: Frames In Python,  Prev: Progspaces In Python,  Up: Python API

  26959. 

  26960. 23.2.2.24 Objfiles In Python

  26961. ............................

  26962. 

  26963. GDB loads symbols for an inferior from various symbol-containing files

  26964. (*note Files::).  These include the primary executable file, any shared

  26965. libraries used by the inferior, and any separate debug info files (*note

  26966. Separate Debug Files::).  GDB calls these symbol-containing files

  26967. "objfiles".

  26968. 

  26969.    The following objfile-related functions are available in the 'gdb'

  26970. module:

  26971. 

  26972.  -- Function: gdb.current_objfile ()

  26973.      When auto-loading a Python script (*note Python Auto-loading::),

  26974.      GDB sets the "current objfile" to the corresponding objfile.  This

  26975.      function returns the current objfile.  If there is no current

  26976.      objfile, this function returns 'None'.

  26977. 

  26978.  -- Function: gdb.objfiles ()

  26979.      Return a sequence of objfiles referenced by the current program

  26980.      space.  *Note Objfiles In Python::, and *note Progspaces In

  26981.      Python::.  This is identical to

  26982.      'gdb.selected_inferior().progspace.objfiles()' and is included for

  26983.      historical compatibility.

  26984. 

  26985.  -- Function: gdb.lookup_objfile (name [, by_build_id])

  26986.      Look up NAME, a file name or build ID, in the list of objfiles for

  26987.      the current program space (*note Progspaces In Python::).  If the

  26988.      objfile is not found throw the Python 'ValueError' exception.

  26989. 

  26990.      If NAME is a relative file name, then it will match any source file

  26991.      name with the same trailing components.  For example, if NAME is

  26992.      'gcc/expr.c', then it will match source file name of

  26993.      '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or

  26994.      '/build/trunk/gcc/x-expr.c'.

  26995. 

  26996.      If BY_BUILD_ID is provided and is 'True' then NAME is the build ID

  26997.      of the objfile.  Otherwise, NAME is a file name.  This is supported

  26998.      only on some operating systems, notably those which use the ELF

  26999.      format for binary files and the GNU Binutils.  For more details

  27000.      about this feature, see the description of the '--build-id'

  27001.      command-line option in *note Command Line Options: (ld)Options.

  27002. 

  27003.    Each objfile is represented by an instance of the 'gdb.Objfile'

  27004. class.

  27005. 

  27006.  -- Variable: Objfile.filename

  27007.      The file name of the objfile as a string, with symbolic links

  27008.      resolved.

  27009. 

  27010.      The value is 'None' if the objfile is no longer valid.  See the

  27011.      'gdb.Objfile.is_valid' method, described below.

  27012. 

  27013.  -- Variable: Objfile.username

  27014.      The file name of the objfile as specified by the user as a string.

  27015. 

  27016.      The value is 'None' if the objfile is no longer valid.  See the

  27017.      'gdb.Objfile.is_valid' method, described below.

  27018. 

  27019.  -- Variable: Objfile.owner

  27020.      For separate debug info objfiles this is the corresponding

  27021.      'gdb.Objfile' object that debug info is being provided for.

  27022.      Otherwise this is 'None'.  Separate debug info objfiles are added

  27023.      with the 'gdb.Objfile.add_separate_debug_file' method, described

  27024.      below.

  27025. 

  27026.  -- Variable: Objfile.build_id

  27027.      The build ID of the objfile as a string.  If the objfile does not

  27028.      have a build ID then the value is 'None'.

  27029. 

  27030.      This is supported only on some operating systems, notably those

  27031.      which use the ELF format for binary files and the GNU Binutils.

  27032.      For more details about this feature, see the description of the

  27033.      '--build-id' command-line option in *note Command Line Options:

  27034.      (ld)Options.

  27035. 

  27036.  -- Variable: Objfile.progspace

  27037.      The containing program space of the objfile as a 'gdb.Progspace'

  27038.      object.  *Note Progspaces In Python::.

  27039. 

  27040.  -- Variable: Objfile.pretty_printers

  27041.      The 'pretty_printers' attribute is a list of functions.  It is used

  27042.      to look up pretty-printers.  A 'Value' is passed to each function

  27043.      in order; if the function returns 'None', then the search

  27044.      continues.  Otherwise, the return value should be an object which

  27045.      is used to format the value.  *Note Pretty Printing API::, for more

  27046.      information.

  27047. 

  27048.  -- Variable: Objfile.type_printers

  27049.      The 'type_printers' attribute is a list of type printer objects.

  27050.      *Note Type Printing API::, for more information.

  27051. 

  27052.  -- Variable: Objfile.frame_filters

  27053.      The 'frame_filters' attribute is a dictionary of frame filter

  27054.      objects.  *Note Frame Filter API::, for more information.

  27055. 

  27056.    One may add arbitrary attributes to 'gdb.Objfile' objects in the

  27057. usual Python way.  This is useful if, for example, one needs to do some

  27058. extra record keeping associated with the objfile.

  27059. 

  27060.    In this contrived example we record the time when GDB loaded the

  27061. objfile.

  27062. 

  27063.      (gdb) python

  27064.      import datetime

  27065.      def new_objfile_handler(event):

  27066.          # Set the time_loaded attribute of the new objfile.

  27067.          event.new_objfile.time_loaded = datetime.datetime.today()

  27068.      gdb.events.new_objfile.connect(new_objfile_handler)

  27069.      end

  27070.      (gdb) file ./hello

  27071.      Reading symbols from ./hello...

  27072.      (gdb) python print gdb.objfiles()[0].time_loaded

  27073.      2014-10-09 11:41:36.770345

  27074. 

  27075.    A 'gdb.Objfile' object has the following methods:

  27076. 

  27077.  -- Function: Objfile.is_valid ()

  27078.      Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if

  27079.      not.  A 'gdb.Objfile' object can become invalid if the object file

  27080.      it refers to is not loaded in GDB any longer.  All other

  27081.      'gdb.Objfile' methods will throw an exception if it is invalid at

  27082.      the time the method is called.

  27083. 

  27084.  -- Function: Objfile.add_separate_debug_file (file)

  27085.      Add FILE to the list of files that GDB will search for debug

  27086.      information for the objfile.  This is useful when the debug info

  27087.      has been removed from the program and stored in a separate file.

  27088.      GDB has built-in support for finding separate debug info files

  27089.      (*note Separate Debug Files::), but if the file doesn't live in one

  27090.      of the standard places that GDB searches then this function can be

  27091.      used to add a debug info file from a different place.

  27092. 

  27093.  -- Function: Objfile.lookup_global_symbol (name [, domain])

  27094.      Search for a global symbol named NAME in this objfile.  Optionally,

  27095.      the search scope can be restricted with the DOMAIN argument.  The

  27096.      DOMAIN argument must be a domain constant defined in the 'gdb'

  27097.      module and described in *note Symbols In Python::.  This function

  27098.      is similar to 'gdb.lookup_global_symbol', except that the search is

  27099.      limited to this objfile.

  27100. 

  27101.      The result is a 'gdb.Symbol' object or 'None' if the symbol is not

  27102.      found.

  27103. 

  27104.  -- Function: Objfile.lookup_static_symbol (name [, domain])

  27105.      Like 'Objfile.lookup_global_symbol', but searches for a global

  27106.      symbol with static linkage named NAME in this objfile.

  27107. 

  27108. 

  27109. File: gdb.info,  Node: Frames In Python,  Next: Blocks In Python,  Prev: Objfiles In Python,  Up: Python API

  27110. 

  27111. 23.2.2.25 Accessing inferior stack frames from Python

  27112. .....................................................

  27113. 

  27114. When the debugged program stops, GDB is able to analyze its call stack

  27115. (*note Stack frames: Frames.).  The 'gdb.Frame' class represents a frame

  27116. in the stack.  A 'gdb.Frame' object is only valid while its

  27117. corresponding frame exists in the inferior's stack.  If you try to use

  27118. an invalid frame object, GDB will throw a 'gdb.error' exception (*note

  27119. Exception Handling::).

  27120. 

  27121.    Two 'gdb.Frame' objects can be compared for equality with the '=='

  27122. operator, like:

  27123. 

  27124.      (gdb) python print gdb.newest_frame() == gdb.selected_frame ()

  27125.      True

  27126. 

  27127.    The following frame-related functions are available in the 'gdb'

  27128. module:

  27129. 

  27130.  -- Function: gdb.selected_frame ()

  27131.      Return the selected frame object.  (*note Selecting a Frame:

  27132.      Selection.).

  27133. 

  27134.  -- Function: gdb.newest_frame ()

  27135.      Return the newest frame object for the selected thread.

  27136. 

  27137.  -- Function: gdb.frame_stop_reason_string (reason)

  27138.      Return a string explaining the reason why GDB stopped unwinding

  27139.      frames, as expressed by the given REASON code (an integer, see the

  27140.      'unwind_stop_reason' method further down in this section).

  27141. 

  27142.  -- Function: gdb.invalidate_cached_frames

  27143.      GDB internally keeps a cache of the frames that have been unwound.

  27144.      This function invalidates this cache.

  27145. 

  27146.      This function should not generally be called by ordinary Python

  27147.      code.  It is documented for the sake of completeness.

  27148. 

  27149.    A 'gdb.Frame' object has the following methods:

  27150. 

  27151.  -- Function: Frame.is_valid ()

  27152.      Returns true if the 'gdb.Frame' object is valid, false if not.  A

  27153.      frame object can become invalid if the frame it refers to doesn't

  27154.      exist anymore in the inferior.  All 'gdb.Frame' methods will throw

  27155.      an exception if it is invalid at the time the method is called.

  27156. 

  27157.  -- Function: Frame.name ()

  27158.      Returns the function name of the frame, or 'None' if it can't be

  27159.      obtained.

  27160. 

  27161.  -- Function: Frame.architecture ()

  27162.      Returns the 'gdb.Architecture' object corresponding to the frame's

  27163.      architecture.  *Note Architectures In Python::.

  27164. 

  27165.  -- Function: Frame.type ()

  27166.      Returns the type of the frame.  The value can be one of:

  27167.      'gdb.NORMAL_FRAME'

  27168.           An ordinary stack frame.

  27169. 

  27170.      'gdb.DUMMY_FRAME'

  27171.           A fake stack frame that was created by GDB when performing an

  27172.           inferior function call.

  27173. 

  27174.      'gdb.INLINE_FRAME'

  27175.           A frame representing an inlined function.  The function was

  27176.           inlined into a 'gdb.NORMAL_FRAME' that is older than this one.

  27177. 

  27178.      'gdb.TAILCALL_FRAME'

  27179.           A frame representing a tail call.  *Note Tail Call Frames::.

  27180. 

  27181.      'gdb.SIGTRAMP_FRAME'

  27182.           A signal trampoline frame.  This is the frame created by the

  27183.           OS when it calls into a signal handler.

  27184. 

  27185.      'gdb.ARCH_FRAME'

  27186.           A fake stack frame representing a cross-architecture call.

  27187. 

  27188.      'gdb.SENTINEL_FRAME'

  27189.           This is like 'gdb.NORMAL_FRAME', but it is only used for the

  27190.           newest frame.

  27191. 

  27192.  -- Function: Frame.unwind_stop_reason ()

  27193.      Return an integer representing the reason why it's not possible to

  27194.      find more frames toward the outermost frame.  Use

  27195.      'gdb.frame_stop_reason_string' to convert the value returned by

  27196.      this function to a string.  The value can be one of:

  27197. 

  27198.      'gdb.FRAME_UNWIND_NO_REASON'

  27199.           No particular reason (older frames should be available).

  27200. 

  27201.      'gdb.FRAME_UNWIND_NULL_ID'

  27202.           The previous frame's analyzer returns an invalid result.  This

  27203.           is no longer used by GDB, and is kept only for backward

  27204.           compatibility.

  27205. 

  27206.      'gdb.FRAME_UNWIND_OUTERMOST'

  27207.           This frame is the outermost.

  27208. 

  27209.      'gdb.FRAME_UNWIND_UNAVAILABLE'

  27210.           Cannot unwind further, because that would require knowing the

  27211.           values of registers or memory that have not been collected.

  27212. 

  27213.      'gdb.FRAME_UNWIND_INNER_ID'

  27214.           This frame ID looks like it ought to belong to a NEXT frame,

  27215.           but we got it for a PREV frame.  Normally, this is a sign of

  27216.           unwinder failure.  It could also indicate stack corruption.

  27217. 

  27218.      'gdb.FRAME_UNWIND_SAME_ID'

  27219.           This frame has the same ID as the previous one.  That means

  27220.           that unwinding further would almost certainly give us another

  27221.           frame with exactly the same ID, so break the chain.  Normally,

  27222.           this is a sign of unwinder failure.  It could also indicate

  27223.           stack corruption.

  27224. 

  27225.      'gdb.FRAME_UNWIND_NO_SAVED_PC'

  27226.           The frame unwinder did not find any saved PC, but we needed

  27227.           one to unwind further.

  27228. 

  27229.      'gdb.FRAME_UNWIND_MEMORY_ERROR'

  27230.           The frame unwinder caused an error while trying to access

  27231.           memory.

  27232. 

  27233.      'gdb.FRAME_UNWIND_FIRST_ERROR'

  27234.           Any stop reason greater or equal to this value indicates some

  27235.           kind of error.  This special value facilitates writing code

  27236.           that tests for errors in unwinding in a way that will work

  27237.           correctly even if the list of the other values is modified in

  27238.           future GDB versions.  Using it, you could write:

  27239.                reason = gdb.selected_frame().unwind_stop_reason ()

  27240.                reason_str =  gdb.frame_stop_reason_string (reason)

  27241.                if reason >=  gdb.FRAME_UNWIND_FIRST_ERROR:

  27242.                    print "An error occured: %s" % reason_str

  27243. 

  27244.  -- Function: Frame.pc ()

  27245.      Returns the frame's resume address.

  27246. 

  27247.  -- Function: Frame.block ()

  27248.      Return the frame's code block.  *Note Blocks In Python::.  If the

  27249.      frame does not have a block - for example, if there is no debugging

  27250.      information for the code in question - then this will throw an

  27251.      exception.

  27252. 

  27253.  -- Function: Frame.function ()

  27254.      Return the symbol for the function corresponding to this frame.

  27255.      *Note Symbols In Python::.

  27256. 

  27257.  -- Function: Frame.older ()

  27258.      Return the frame that called this frame.

  27259. 

  27260.  -- Function: Frame.newer ()

  27261.      Return the frame called by this frame.

  27262. 

  27263.  -- Function: Frame.find_sal ()

  27264.      Return the frame's symtab and line object.  *Note Symbol Tables In

  27265.      Python::.

  27266. 

  27267.  -- Function: Frame.read_register (register)

  27268.      Return the value of REGISTER in this frame.  Returns a 'Gdb.Value'

  27269.      object.  Throws an exception if REGISTER does not exist.  The

  27270.      REGISTER argument must be one of the following:

  27271.        1. A string that is the name of a valid register (e.g., ''sp'' or

  27272.           ''rax'').

  27273.        2. A 'gdb.RegisterDescriptor' object (*note Registers In

  27274.           Python::).

  27275.        3. A GDB internal, platform specific number.  Using these numbers

  27276.           is supported for historic reasons, but is not recommended as

  27277.           future changes to GDB could change the mapping between numbers

  27278.           and the registers they represent, breaking any Python code

  27279.           that uses the platform-specific numbers.  The numbers are

  27280.           usually found in the corresponding 'PLATFORM-tdep.h' file in

  27281.           the GDB source tree.

  27282.      Using a string to access registers will be slightly slower than the

  27283.      other two methods as GDB must look up the mapping between name and

  27284.      internal register number.  If performance is critical consider

  27285.      looking up and caching a 'gdb.RegisterDescriptor' object.

  27286. 

  27287.  -- Function: Frame.read_var (variable [, block])

  27288.      Return the value of VARIABLE in this frame.  If the optional

  27289.      argument BLOCK is provided, search for the variable from that

  27290.      block; otherwise start at the frame's current block (which is

  27291.      determined by the frame's current program counter).  The VARIABLE

  27292.      argument must be a string or a 'gdb.Symbol' object; BLOCK must be a

  27293.      'gdb.Block' object.

  27294. 

  27295.  -- Function: Frame.select ()

  27296.      Set this frame to be the selected frame.  *Note Examining the

  27297.      Stack: Stack.

  27298. 

  27299. 

  27300. File: gdb.info,  Node: Blocks In Python,  Next: Symbols In Python,  Prev: Frames In Python,  Up: Python API

  27301. 

  27302. 23.2.2.26 Accessing blocks from Python

  27303. ......................................

  27304. 

  27305. In GDB, symbols are stored in blocks.  A block corresponds roughly to a

  27306. scope in the source code.  Blocks are organized hierarchically, and are

  27307. represented individually in Python as a 'gdb.Block'.  Blocks rely on

  27308. debugging information being available.

  27309. 

  27310.    A frame has a block.  Please see *note Frames In Python::, for a more

  27311. in-depth discussion of frames.

  27312. 

  27313.    The outermost block is known as the "global block".  The global block

  27314. typically holds public global variables and functions.

  27315. 

  27316.    The block nested just inside the global block is the "static block".

  27317. The static block typically holds file-scoped variables and functions.

  27318. 

  27319.    GDB provides a method to get a block's superblock, but there is

  27320. currently no way to examine the sub-blocks of a block, or to iterate

  27321. over all the blocks in a symbol table (*note Symbol Tables In Python::).

  27322. 

  27323.    Here is a short example that should help explain blocks:

  27324. 

  27325.      /* This is in the global block.  */

  27326.      int global;

  27327. 

  27328.      /* This is in the static block.  */

  27329.      static int file_scope;

  27330. 

  27331.      /* 'function' is in the global block, and 'argument' is

  27332.         in a block nested inside of 'function'.  */

  27333.      int function (int argument)

  27334.      {

  27335.        /* 'local' is in a block inside 'function'.  It may or may

  27336.           not be in the same block as 'argument'.  */

  27337.        int local;

  27338. 

  27339.        {

  27340.           /* 'inner' is in a block whose superblock is the one holding

  27341.              'local'.  */

  27342.           int inner;

  27343. 

  27344.           /* If this call is expanded by the compiler, you may see

  27345.              a nested block here whose function is 'inline_function'

  27346.              and whose superblock is the one holding 'inner'.  */

  27347.           inline_function ();

  27348.        }

  27349.      }

  27350. 

  27351.    A 'gdb.Block' is iterable.  The iterator returns the symbols (*note

  27352. Symbols In Python::) local to the block.  Python programs should not

  27353. assume that a specific block object will always contain a given symbol,

  27354. since changes in GDB features and infrastructure may cause symbols move

  27355. across blocks in a symbol table.  You can also use Python's "dictionary

  27356. syntax" to access variables in this block, e.g.:

  27357. 

  27358.      symbol = some_block['variable']  # symbol is of type gdb.Symbol

  27359. 

  27360.    The following block-related functions are available in the 'gdb'

  27361. module:

  27362. 

  27363.  -- Function: gdb.block_for_pc (pc)

  27364.      Return the innermost 'gdb.Block' containing the given PC value.  If

  27365.      the block cannot be found for the PC value specified, the function

  27366.      will return 'None'.  This is identical to

  27367.      'gdb.current_progspace().block_for_pc(pc)' and is included for

  27368.      historical compatibility.

  27369. 

  27370.    A 'gdb.Block' object has the following methods:

  27371. 

  27372.  -- Function: Block.is_valid ()

  27373.      Returns 'True' if the 'gdb.Block' object is valid, 'False' if not.

  27374.      A block object can become invalid if the block it refers to doesn't

  27375.      exist anymore in the inferior.  All other 'gdb.Block' methods will

  27376.      throw an exception if it is invalid at the time the method is

  27377.      called.  The block's validity is also checked during iteration over

  27378.      symbols of the block.

  27379. 

  27380.    A 'gdb.Block' object has the following attributes:

  27381. 

  27382.  -- Variable: Block.start

  27383.      The start address of the block.  This attribute is not writable.

  27384. 

  27385.  -- Variable: Block.end

  27386.      One past the last address that appears in the block.  This

  27387.      attribute is not writable.

  27388. 

  27389.  -- Variable: Block.function

  27390.      The name of the block represented as a 'gdb.Symbol'.  If the block

  27391.      is not named, then this attribute holds 'None'.  This attribute is

  27392.      not writable.

  27393. 

  27394.      For ordinary function blocks, the superblock is the static block.

  27395.      However, you should note that it is possible for a function block

  27396.      to have a superblock that is not the static block - for instance

  27397.      this happens for an inlined function.

  27398. 

  27399.  -- Variable: Block.superblock

  27400.      The block containing this block.  If this parent block does not

  27401.      exist, this attribute holds 'None'.  This attribute is not

  27402.      writable.

  27403. 

  27404.  -- Variable: Block.global_block

  27405.      The global block associated with this block.  This attribute is not

  27406.      writable.

  27407. 

  27408.  -- Variable: Block.static_block

  27409.      The static block associated with this block.  This attribute is not

  27410.      writable.

  27411. 

  27412.  -- Variable: Block.is_global

  27413.      'True' if the 'gdb.Block' object is a global block, 'False' if not.

  27414.      This attribute is not writable.

  27415. 

  27416.  -- Variable: Block.is_static

  27417.      'True' if the 'gdb.Block' object is a static block, 'False' if not.

  27418.      This attribute is not writable.

  27419. 

  27420. 

  27421. File: gdb.info,  Node: Symbols In Python,  Next: Symbol Tables In Python,  Prev: Blocks In Python,  Up: Python API

  27422. 

  27423. 23.2.2.27 Python representation of Symbols

  27424. ..........................................

  27425. 

  27426. GDB represents every variable, function and type as an entry in a symbol

  27427. table.  *Note Examining the Symbol Table: Symbols.  Similarly, Python

  27428. represents these symbols in GDB with the 'gdb.Symbol' object.

  27429. 

  27430.    The following symbol-related functions are available in the 'gdb'

  27431. module:

  27432. 

  27433.  -- Function: gdb.lookup_symbol (name [, block [, domain]])

  27434.      This function searches for a symbol by name.  The search scope can

  27435.      be restricted to the parameters defined in the optional domain and

  27436.      block arguments.

  27437. 

  27438.      NAME is the name of the symbol.  It must be a string.  The optional

  27439.      BLOCK argument restricts the search to symbols visible in that

  27440.      BLOCK.  The BLOCK argument must be a 'gdb.Block' object.  If

  27441.      omitted, the block for the current frame is used.  The optional

  27442.      DOMAIN argument restricts the search to the domain type.  The

  27443.      DOMAIN argument must be a domain constant defined in the 'gdb'

  27444.      module and described later in this chapter.

  27445. 

  27446.      The result is a tuple of two elements.  The first element is a

  27447.      'gdb.Symbol' object or 'None' if the symbol is not found.  If the

  27448.      symbol is found, the second element is 'True' if the symbol is a

  27449.      field of a method's object (e.g., 'this' in C++), otherwise it is

  27450.      'False'.  If the symbol is not found, the second element is

  27451.      'False'.

  27452. 

  27453.  -- Function: gdb.lookup_global_symbol (name [, domain])

  27454.      This function searches for a global symbol by name.  The search

  27455.      scope can be restricted to by the domain argument.

  27456. 

  27457.      NAME is the name of the symbol.  It must be a string.  The optional

  27458.      DOMAIN argument restricts the search to the domain type.  The

  27459.      DOMAIN argument must be a domain constant defined in the 'gdb'

  27460.      module and described later in this chapter.

  27461. 

  27462.      The result is a 'gdb.Symbol' object or 'None' if the symbol is not

  27463.      found.

  27464. 

  27465.  -- Function: gdb.lookup_static_symbol (name [, domain])

  27466.      This function searches for a global symbol with static linkage by

  27467.      name.  The search scope can be restricted to by the domain

  27468.      argument.

  27469. 

  27470.      NAME is the name of the symbol.  It must be a string.  The optional

  27471.      DOMAIN argument restricts the search to the domain type.  The

  27472.      DOMAIN argument must be a domain constant defined in the 'gdb'

  27473.      module and described later in this chapter.

  27474. 

  27475.      The result is a 'gdb.Symbol' object or 'None' if the symbol is not

  27476.      found.

  27477. 

  27478.      Note that this function will not find function-scoped static

  27479.      variables.  To look up such variables, iterate over the variables

  27480.      of the function's 'gdb.Block' and check that 'block.addr_class' is

  27481.      'gdb.SYMBOL_LOC_STATIC'.

  27482. 

  27483.      There can be multiple global symbols with static linkage with the

  27484.      same name.  This function will only return the first matching

  27485.      symbol that it finds.  Which symbol is found depends on where GDB

  27486.      is currently stopped, as GDB will first search for matching symbols

  27487.      in the current object file, and then search all other object files.

  27488.      If the application is not yet running then GDB will search all

  27489.      object files in the order they appear in the debug information.

  27490. 

  27491.  -- Function: gdb.lookup_static_symbols (name [, domain])

  27492.      Similar to 'gdb.lookup_static_symbol', this function searches for

  27493.      global symbols with static linkage by name, and optionally

  27494.      restricted by the domain argument.  However, this function returns

  27495.      a list of all matching symbols found, not just the first one.

  27496. 

  27497.      NAME is the name of the symbol.  It must be a string.  The optional

  27498.      DOMAIN argument restricts the search to the domain type.  The

  27499.      DOMAIN argument must be a domain constant defined in the 'gdb'

  27500.      module and described later in this chapter.

  27501. 

  27502.      The result is a list of 'gdb.Symbol' objects which could be empty

  27503.      if no matching symbols were found.

  27504. 

  27505.      Note that this function will not find function-scoped static

  27506.      variables.  To look up such variables, iterate over the variables

  27507.      of the function's 'gdb.Block' and check that 'block.addr_class' is

  27508.      'gdb.SYMBOL_LOC_STATIC'.

  27509. 

  27510.    A 'gdb.Symbol' object has the following attributes:

  27511. 

  27512.  -- Variable: Symbol.type

  27513.      The type of the symbol or 'None' if no type is recorded.  This

  27514.      attribute is represented as a 'gdb.Type' object.  *Note Types In

  27515.      Python::.  This attribute is not writable.

  27516. 

  27517.  -- Variable: Symbol.symtab

  27518.      The symbol table in which the symbol appears.  This attribute is

  27519.      represented as a 'gdb.Symtab' object.  *Note Symbol Tables In

  27520.      Python::.  This attribute is not writable.

  27521. 

  27522.  -- Variable: Symbol.line

  27523.      The line number in the source code at which the symbol was defined.

  27524.      This is an integer.

  27525. 

  27526.  -- Variable: Symbol.name

  27527.      The name of the symbol as a string.  This attribute is not

  27528.      writable.

  27529. 

  27530.  -- Variable: Symbol.linkage_name

  27531.      The name of the symbol, as used by the linker (i.e., may be

  27532.      mangled).  This attribute is not writable.

  27533. 

  27534.  -- Variable: Symbol.print_name

  27535.      The name of the symbol in a form suitable for output.  This is

  27536.      either 'name' or 'linkage_name', depending on whether the user

  27537.      asked GDB to display demangled or mangled names.

  27538. 

  27539.  -- Variable: Symbol.addr_class

  27540.      The address class of the symbol.  This classifies how to find the

  27541.      value of a symbol.  Each address class is a constant defined in the

  27542.      'gdb' module and described later in this chapter.

  27543. 

  27544.  -- Variable: Symbol.needs_frame

  27545.      This is 'True' if evaluating this symbol's value requires a frame

  27546.      (*note Frames In Python::) and 'False' otherwise.  Typically, local

  27547.      variables will require a frame, but other symbols will not.

  27548. 

  27549.  -- Variable: Symbol.is_argument

  27550.      'True' if the symbol is an argument of a function.

  27551. 

  27552.  -- Variable: Symbol.is_constant

  27553.      'True' if the symbol is a constant.

  27554. 

  27555.  -- Variable: Symbol.is_function

  27556.      'True' if the symbol is a function or a method.

  27557. 

  27558.  -- Variable: Symbol.is_variable

  27559.      'True' if the symbol is a variable.

  27560. 

  27561.    A 'gdb.Symbol' object has the following methods:

  27562. 

  27563.  -- Function: Symbol.is_valid ()

  27564.      Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not.

  27565.      A 'gdb.Symbol' object can become invalid if the symbol it refers to

  27566.      does not exist in GDB any longer.  All other 'gdb.Symbol' methods

  27567.      will throw an exception if it is invalid at the time the method is

  27568.      called.

  27569. 

  27570.  -- Function: Symbol.value ([frame])

  27571.      Compute the value of the symbol, as a 'gdb.Value'.  For functions,

  27572.      this computes the address of the function, cast to the appropriate

  27573.      type.  If the symbol requires a frame in order to compute its

  27574.      value, then FRAME must be given.  If FRAME is not given, or if

  27575.      FRAME is invalid, then this method will throw an exception.

  27576. 

  27577.    The available domain categories in 'gdb.Symbol' are represented as

  27578. constants in the 'gdb' module:

  27579. 

  27580. 'gdb.SYMBOL_UNDEF_DOMAIN'

  27581.      This is used when a domain has not been discovered or none of the

  27582.      following domains apply.  This usually indicates an error either in

  27583.      the symbol information or in GDB's handling of symbols.

  27584. 

  27585. 'gdb.SYMBOL_VAR_DOMAIN'

  27586.      This domain contains variables, function names, typedef names and

  27587.      enum type values.

  27588. 

  27589. 'gdb.SYMBOL_STRUCT_DOMAIN'

  27590.      This domain holds struct, union and enum type names.

  27591. 

  27592. 'gdb.SYMBOL_LABEL_DOMAIN'

  27593.      This domain contains names of labels (for gotos).

  27594. 

  27595. 'gdb.SYMBOL_MODULE_DOMAIN'

  27596.      This domain contains names of Fortran module types.

  27597. 

  27598. 'gdb.SYMBOL_COMMON_BLOCK_DOMAIN'

  27599.      This domain contains names of Fortran common blocks.

  27600. 

  27601.    The available address class categories in 'gdb.Symbol' are

  27602. represented as constants in the 'gdb' module:

  27603. 

  27604. 'gdb.SYMBOL_LOC_UNDEF'

  27605.      If this is returned by address class, it indicates an error either

  27606.      in the symbol information or in GDB's handling of symbols.

  27607. 

  27608. 'gdb.SYMBOL_LOC_CONST'

  27609.      Value is constant int.

  27610. 

  27611. 'gdb.SYMBOL_LOC_STATIC'

  27612.      Value is at a fixed address.

  27613. 

  27614. 'gdb.SYMBOL_LOC_REGISTER'

  27615.      Value is in a register.

  27616. 

  27617. 'gdb.SYMBOL_LOC_ARG'

  27618.      Value is an argument.  This value is at the offset stored within

  27619.      the symbol inside the frame's argument list.

  27620. 

  27621. 'gdb.SYMBOL_LOC_REF_ARG'

  27622.      Value address is stored in the frame's argument list.  Just like

  27623.      'LOC_ARG' except that the value's address is stored at the offset,

  27624.      not the value itself.

  27625. 

  27626. 'gdb.SYMBOL_LOC_REGPARM_ADDR'

  27627.      Value is a specified register.  Just like 'LOC_REGISTER' except the

  27628.      register holds the address of the argument instead of the argument

  27629.      itself.

  27630. 

  27631. 'gdb.SYMBOL_LOC_LOCAL'

  27632.      Value is a local variable.

  27633. 

  27634. 'gdb.SYMBOL_LOC_TYPEDEF'

  27635.      Value not used.  Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all

  27636.      have this class.

  27637. 

  27638. 'gdb.SYMBOL_LOC_BLOCK'

  27639.      Value is a block.

  27640. 

  27641. 'gdb.SYMBOL_LOC_CONST_BYTES'

  27642.      Value is a byte-sequence.

  27643. 

  27644. 'gdb.SYMBOL_LOC_UNRESOLVED'

  27645.      Value is at a fixed address, but the address of the variable has to

  27646.      be determined from the minimal symbol table whenever the variable

  27647.      is referenced.

  27648. 

  27649. 'gdb.SYMBOL_LOC_OPTIMIZED_OUT'

  27650.      The value does not actually exist in the program.

  27651. 

  27652. 'gdb.SYMBOL_LOC_COMPUTED'

  27653.      The value's address is a computed location.

  27654. 

  27655. 'gdb.SYMBOL_LOC_COMPUTED'

  27656.      The value's address is a symbol.  This is only used for Fortran

  27657.      common blocks.

  27658. 

  27659. 

  27660. File: gdb.info,  Node: Symbol Tables In Python,  Next: Line Tables In Python,  Prev: Symbols In Python,  Up: Python API

  27661. 

  27662. 23.2.2.28 Symbol table representation in Python

  27663. ...............................................

  27664. 

  27665. Access to symbol table data maintained by GDB on the inferior is exposed

  27666. to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'.

  27667. Symbol table and line data for a frame is returned from the 'find_sal'

  27668. method in 'gdb.Frame' object.  *Note Frames In Python::.

  27669. 

  27670.    For more information on GDB's symbol table management, see *note

  27671. Examining the Symbol Table: Symbols, for more information.

  27672. 

  27673.    A 'gdb.Symtab_and_line' object has the following attributes:

  27674. 

  27675.  -- Variable: Symtab_and_line.symtab

  27676.      The symbol table object ('gdb.Symtab') for this frame.  This

  27677.      attribute is not writable.

  27678. 

  27679.  -- Variable: Symtab_and_line.pc

  27680.      Indicates the start of the address range occupied by code for the

  27681.      current source line.  This attribute is not writable.

  27682. 

  27683.  -- Variable: Symtab_and_line.last

  27684.      Indicates the end of the address range occupied by code for the

  27685.      current source line.  This attribute is not writable.

  27686. 

  27687.  -- Variable: Symtab_and_line.line

  27688.      Indicates the current line number for this object.  This attribute

  27689.      is not writable.

  27690. 

  27691.    A 'gdb.Symtab_and_line' object has the following methods:

  27692. 

  27693.  -- Function: Symtab_and_line.is_valid ()

  27694.      Returns 'True' if the 'gdb.Symtab_and_line' object is valid,

  27695.      'False' if not.  A 'gdb.Symtab_and_line' object can become invalid

  27696.      if the Symbol table and line object it refers to does not exist in

  27697.      GDB any longer.  All other 'gdb.Symtab_and_line' methods will throw

  27698.      an exception if it is invalid at the time the method is called.

  27699. 

  27700.    A 'gdb.Symtab' object has the following attributes:

  27701. 

  27702.  -- Variable: Symtab.filename

  27703.      The symbol table's source filename.  This attribute is not

  27704.      writable.

  27705. 

  27706.  -- Variable: Symtab.objfile

  27707.      The symbol table's backing object file.  *Note Objfiles In

  27708.      Python::.  This attribute is not writable.

  27709. 

  27710.  -- Variable: Symtab.producer

  27711.      The name and possibly version number of the program that compiled

  27712.      the code in the symbol table.  The contents of this string is up to

  27713.      the compiler.  If no producer information is available then 'None'

  27714.      is returned.  This attribute is not writable.

  27715. 

  27716.    A 'gdb.Symtab' object has the following methods:

  27717. 

  27718.  -- Function: Symtab.is_valid ()

  27719.      Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not.

  27720.      A 'gdb.Symtab' object can become invalid if the symbol table it

  27721.      refers to does not exist in GDB any longer.  All other 'gdb.Symtab'

  27722.      methods will throw an exception if it is invalid at the time the

  27723.      method is called.

  27724. 

  27725.  -- Function: Symtab.fullname ()

  27726.      Return the symbol table's source absolute file name.

  27727. 

  27728.  -- Function: Symtab.global_block ()

  27729.      Return the global block of the underlying symbol table.  *Note

  27730.      Blocks In Python::.

  27731. 

  27732.  -- Function: Symtab.static_block ()

  27733.      Return the static block of the underlying symbol table.  *Note

  27734.      Blocks In Python::.

  27735. 

  27736.  -- Function: Symtab.linetable ()

  27737.      Return the line table associated with the symbol table.  *Note Line

  27738.      Tables In Python::.

  27739. 

  27740. 

  27741. File: gdb.info,  Node: Line Tables In Python,  Next: Breakpoints In Python,  Prev: Symbol Tables In Python,  Up: Python API

  27742. 

  27743. 23.2.2.29 Manipulating line tables using Python

  27744. ...............................................

  27745. 

  27746. Python code can request and inspect line table information from a symbol

  27747. table that is loaded in GDB.  A line table is a mapping of source lines

  27748. to their executable locations in memory.  To acquire the line table

  27749. information for a particular symbol table, use the 'linetable' function

  27750. (*note Symbol Tables In Python::).

  27751. 

  27752.    A 'gdb.LineTable' is iterable.  The iterator returns 'LineTableEntry'

  27753. objects that correspond to the source line and address for each line

  27754. table entry.  'LineTableEntry' objects have the following attributes:

  27755. 

  27756.  -- Variable: LineTableEntry.line

  27757.      The source line number for this line table entry.  This number

  27758.      corresponds to the actual line of source.  This attribute is not

  27759.      writable.

  27760. 

  27761.  -- Variable: LineTableEntry.pc

  27762.      The address that is associated with the line table entry where the

  27763.      executable code for that source line resides in memory.  This

  27764.      attribute is not writable.

  27765. 

  27766.    As there can be multiple addresses for a single source line, you may

  27767. receive multiple 'LineTableEntry' objects with matching 'line'

  27768. attributes, but with different 'pc' attributes.  The iterator is sorted

  27769. in ascending 'pc' order.  Here is a small example illustrating iterating

  27770. over a line table.

  27771. 

  27772.      symtab = gdb.selected_frame().find_sal().symtab

  27773.      linetable = symtab.linetable()

  27774.      for line in linetable:

  27775.         print "Line: "+str(line.line)+" Address: "+hex(line.pc)

  27776. 

  27777.    This will have the following output:

  27778. 

  27779.      Line: 33 Address: 0x4005c8L

  27780.      Line: 37 Address: 0x4005caL

  27781.      Line: 39 Address: 0x4005d2L

  27782.      Line: 40 Address: 0x4005f8L

  27783.      Line: 42 Address: 0x4005ffL

  27784.      Line: 44 Address: 0x400608L

  27785.      Line: 42 Address: 0x40060cL

  27786.      Line: 45 Address: 0x400615L

  27787. 

  27788.    In addition to being able to iterate over a 'LineTable', it also has

  27789. the following direct access methods:

  27790. 

  27791.  -- Function: LineTable.line (line)

  27792.      Return a Python 'Tuple' of 'LineTableEntry' objects for any entries

  27793.      in the line table for the given LINE, which specifies the source

  27794.      code line.  If there are no entries for that source code LINE, the

  27795.      Python 'None' is returned.

  27796. 

  27797.  -- Function: LineTable.has_line (line)

  27798.      Return a Python 'Boolean' indicating whether there is an entry in

  27799.      the line table for this source line.  Return 'True' if an entry is

  27800.      found, or 'False' if not.

  27801. 

  27802.  -- Function: LineTable.source_lines ()

  27803.      Return a Python 'List' of the source line numbers in the symbol

  27804.      table.  Only lines with executable code locations are returned.

  27805.      The contents of the 'List' will just be the source line entries

  27806.      represented as Python 'Long' values.

  27807. 

  27808. 

  27809. File: gdb.info,  Node: Breakpoints In Python,  Next: Finish Breakpoints in Python,  Prev: Line Tables In Python,  Up: Python API

  27810. 

  27811. 23.2.2.30 Manipulating breakpoints using Python

  27812. ...............................................

  27813. 

  27814. Python code can manipulate breakpoints via the 'gdb.Breakpoint' class.

  27815. 

  27816.    A breakpoint can be created using one of the two forms of the

  27817. 'gdb.Breakpoint' constructor.  The first one accepts a string like one

  27818. would pass to the 'break' (*note Setting Breakpoints: Set Breaks.) and

  27819. 'watch' (*note Setting Watchpoints: Set Watchpoints.) commands, and can

  27820. be used to create both breakpoints and watchpoints.  The second accepts

  27821. separate Python arguments similar to *note Explicit Locations::, and can

  27822. only be used to create breakpoints.

  27823. 

  27824.  -- Function: Breakpoint.__init__ (spec [, type ][, wp_class ][,

  27825.           internal ][, temporary ][, qualified ])

  27826.      Create a new breakpoint according to SPEC, which is a string naming

  27827.      the location of a breakpoint, or an expression that defines a

  27828.      watchpoint.  The string should describe a location in a format

  27829.      recognized by the 'break' command (*note Setting Breakpoints: Set

  27830.      Breaks.) or, in the case of a watchpoint, by the 'watch' command

  27831.      (*note Setting Watchpoints: Set Watchpoints.).

  27832. 

  27833.      The optional TYPE argument specifies the type of the breakpoint to

  27834.      create, as defined below.

  27835. 

  27836.      The optional WP_CLASS argument defines the class of watchpoint to

  27837.      create, if TYPE is 'gdb.BP_WATCHPOINT'.  If WP_CLASS is omitted, it

  27838.      defaults to 'gdb.WP_WRITE'.

  27839. 

  27840.      The optional INTERNAL argument allows the breakpoint to become

  27841.      invisible to the user.  The breakpoint will neither be reported

  27842.      when created, nor will it be listed in the output from 'info

  27843.      breakpoints' (but will be listed with the 'maint info breakpoints'

  27844.      command).

  27845. 

  27846.      The optional TEMPORARY argument makes the breakpoint a temporary

  27847.      breakpoint.  Temporary breakpoints are deleted after they have been

  27848.      hit.  Any further access to the Python breakpoint after it has been

  27849.      hit will result in a runtime error (as that breakpoint has now been

  27850.      automatically deleted).

  27851. 

  27852.      The optional QUALIFIED argument is a boolean that allows

  27853.      interpreting the function passed in 'spec' as a fully-qualified

  27854.      name.  It is equivalent to 'break''s '-qualified' flag (*note

  27855.      Linespec Locations:: and *note Explicit Locations::).

  27856. 

  27857.  -- Function: Breakpoint.__init__ ([ source ][, function ][, label ][,

  27858.           line ], ][ internal ][, temporary ][, qualified ])

  27859.      This second form of creating a new breakpoint specifies the

  27860.      explicit location (*note Explicit Locations::) using keywords.  The

  27861.      new breakpoint will be created in the specified source file SOURCE,

  27862.      at the specified FUNCTION, LABEL and LINE.

  27863. 

  27864.      INTERNAL, TEMPORARY and QUALIFIED have the same usage as explained

  27865.      previously.

  27866. 

  27867.    The available types are represented by constants defined in the 'gdb'

  27868. module:

  27869. 

  27870. 'gdb.BP_BREAKPOINT'

  27871.      Normal code breakpoint.

  27872. 

  27873. 'gdb.BP_WATCHPOINT'

  27874.      Watchpoint breakpoint.

  27875. 

  27876. 'gdb.BP_HARDWARE_WATCHPOINT'

  27877.      Hardware assisted watchpoint.

  27878. 

  27879. 'gdb.BP_READ_WATCHPOINT'

  27880.      Hardware assisted read watchpoint.

  27881. 

  27882. 'gdb.BP_ACCESS_WATCHPOINT'

  27883.      Hardware assisted access watchpoint.

  27884. 

  27885.    The available watchpoint types represented by constants are defined

  27886. in the 'gdb' module:

  27887. 

  27888. 'gdb.WP_READ'

  27889.      Read only watchpoint.

  27890. 

  27891. 'gdb.WP_WRITE'

  27892.      Write only watchpoint.

  27893. 

  27894. 'gdb.WP_ACCESS'

  27895.      Read/Write watchpoint.

  27896. 

  27897.  -- Function: Breakpoint.stop (self)

  27898.      The 'gdb.Breakpoint' class can be sub-classed and, in particular,

  27899.      you may choose to implement the 'stop' method.  If this method is

  27900.      defined in a sub-class of 'gdb.Breakpoint', it will be called when

  27901.      the inferior reaches any location of a breakpoint which

  27902.      instantiates that sub-class.  If the method returns 'True', the

  27903.      inferior will be stopped at the location of the breakpoint,

  27904.      otherwise the inferior will continue.

  27905. 

  27906.      If there are multiple breakpoints at the same location with a

  27907.      'stop' method, each one will be called regardless of the return

  27908.      status of the previous.  This ensures that all 'stop' methods have

  27909.      a chance to execute at that location.  In this scenario if one of

  27910.      the methods returns 'True' but the others return 'False', the

  27911.      inferior will still be stopped.

  27912. 

  27913.      You should not alter the execution state of the inferior (i.e.,

  27914.      step, next, etc.), alter the current frame context (i.e., change

  27915.      the current active frame), or alter, add or delete any breakpoint.

  27916.      As a general rule, you should not alter any data within GDB or the

  27917.      inferior at this time.

  27918. 

  27919.      Example 'stop' implementation:

  27920. 

  27921.           class MyBreakpoint (gdb.Breakpoint):

  27922.                 def stop (self):

  27923.                   inf_val = gdb.parse_and_eval("foo")

  27924.                   if inf_val == 3:

  27925.                     return True

  27926.                   return False

  27927. 

  27928.  -- Function: Breakpoint.is_valid ()

  27929.      Return 'True' if this 'Breakpoint' object is valid, 'False'

  27930.      otherwise.  A 'Breakpoint' object can become invalid if the user

  27931.      deletes the breakpoint.  In this case, the object still exists, but

  27932.      the underlying breakpoint does not.  In the cases of watchpoint

  27933.      scope, the watchpoint remains valid even if execution of the

  27934.      inferior leaves the scope of that watchpoint.

  27935. 

  27936.  -- Function: Breakpoint.delete ()

  27937.      Permanently deletes the GDB breakpoint.  This also invalidates the

  27938.      Python 'Breakpoint' object.  Any further access to this object's

  27939.      attributes or methods will raise an error.

  27940. 

  27941.  -- Variable: Breakpoint.enabled

  27942.      This attribute is 'True' if the breakpoint is enabled, and 'False'

  27943.      otherwise.  This attribute is writable.  You can use it to enable

  27944.      or disable the breakpoint.

  27945. 

  27946.  -- Variable: Breakpoint.silent

  27947.      This attribute is 'True' if the breakpoint is silent, and 'False'

  27948.      otherwise.  This attribute is writable.

  27949. 

  27950.      Note that a breakpoint can also be silent if it has commands and

  27951.      the first command is 'silent'.  This is not reported by the

  27952.      'silent' attribute.

  27953. 

  27954.  -- Variable: Breakpoint.pending

  27955.      This attribute is 'True' if the breakpoint is pending, and 'False'

  27956.      otherwise.  *Note Set Breaks::.  This attribute is read-only.

  27957. 

  27958.  -- Variable: Breakpoint.thread

  27959.      If the breakpoint is thread-specific, this attribute holds the

  27960.      thread's global id.  If the breakpoint is not thread-specific, this

  27961.      attribute is 'None'.  This attribute is writable.

  27962. 

  27963.  -- Variable: Breakpoint.task

  27964.      If the breakpoint is Ada task-specific, this attribute holds the

  27965.      Ada task id.  If the breakpoint is not task-specific (or the

  27966.      underlying language is not Ada), this attribute is 'None'.  This

  27967.      attribute is writable.

  27968. 

  27969.  -- Variable: Breakpoint.ignore_count

  27970.      This attribute holds the ignore count for the breakpoint, an

  27971.      integer.  This attribute is writable.

  27972. 

  27973.  -- Variable: Breakpoint.number

  27974.      This attribute holds the breakpoint's number -- the identifier used

  27975.      by the user to manipulate the breakpoint.  This attribute is not

  27976.      writable.

  27977. 

  27978.  -- Variable: Breakpoint.type

  27979.      This attribute holds the breakpoint's type -- the identifier used

  27980.      to determine the actual breakpoint type or use-case.  This

  27981.      attribute is not writable.

  27982. 

  27983.  -- Variable: Breakpoint.visible

  27984.      This attribute tells whether the breakpoint is visible to the user

  27985.      when set, or when the 'info breakpoints' command is run.  This

  27986.      attribute is not writable.

  27987. 

  27988.  -- Variable: Breakpoint.temporary

  27989.      This attribute indicates whether the breakpoint was created as a

  27990.      temporary breakpoint.  Temporary breakpoints are automatically

  27991.      deleted after that breakpoint has been hit.  Access to this

  27992.      attribute, and all other attributes and functions other than the

  27993.      'is_valid' function, will result in an error after the breakpoint

  27994.      has been hit (as it has been automatically deleted).  This

  27995.      attribute is not writable.

  27996. 

  27997.  -- Variable: Breakpoint.hit_count

  27998.      This attribute holds the hit count for the breakpoint, an integer.

  27999.      This attribute is writable, but currently it can only be set to

  28000.      zero.

  28001. 

  28002.  -- Variable: Breakpoint.location

  28003.      This attribute holds the location of the breakpoint, as specified

  28004.      by the user.  It is a string.  If the breakpoint does not have a

  28005.      location (that is, it is a watchpoint) the attribute's value is

  28006.      'None'.  This attribute is not writable.

  28007. 

  28008.  -- Variable: Breakpoint.expression

  28009.      This attribute holds a breakpoint expression, as specified by the

  28010.      user.  It is a string.  If the breakpoint does not have an

  28011.      expression (the breakpoint is not a watchpoint) the attribute's

  28012.      value is 'None'.  This attribute is not writable.

  28013. 

  28014.  -- Variable: Breakpoint.condition

  28015.      This attribute holds the condition of the breakpoint, as specified

  28016.      by the user.  It is a string.  If there is no condition, this

  28017.      attribute's value is 'None'.  This attribute is writable.

  28018. 

  28019.  -- Variable: Breakpoint.commands

  28020.      This attribute holds the commands attached to the breakpoint.  If

  28021.      there are commands, this attribute's value is a string holding all

  28022.      the commands, separated by newlines.  If there are no commands,

  28023.      this attribute is 'None'.  This attribute is writable.

  28024. 

  28025. 

  28026. File: gdb.info,  Node: Finish Breakpoints in Python,  Next: Lazy Strings In Python,  Prev: Breakpoints In Python,  Up: Python API

  28027. 

  28028. 23.2.2.31 Finish Breakpoints

  28029. ............................

  28030. 

  28031. A finish breakpoint is a temporary breakpoint set at the return address

  28032. of a frame, based on the 'finish' command.  'gdb.FinishBreakpoint'

  28033. extends 'gdb.Breakpoint'.  The underlying breakpoint will be disabled

  28034. and deleted when the execution will run out of the breakpoint scope

  28035. (i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered).

  28036. Finish breakpoints are thread specific and must be create with the right

  28037. thread selected.

  28038. 

  28039.  -- Function: FinishBreakpoint.__init__ ([frame] [, internal])

  28040.      Create a finish breakpoint at the return address of the 'gdb.Frame'

  28041.      object FRAME.  If FRAME is not provided, this defaults to the

  28042.      newest frame.  The optional INTERNAL argument allows the breakpoint

  28043.      to become invisible to the user.  *Note Breakpoints In Python::,

  28044.      for further details about this argument.

  28045. 

  28046.  -- Function: FinishBreakpoint.out_of_scope (self)

  28047.      In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return'

  28048.      command, ...), a function may not properly terminate, and thus

  28049.      never hit the finish breakpoint.  When GDB notices such a

  28050.      situation, the 'out_of_scope' callback will be triggered.

  28051. 

  28052.      You may want to sub-class 'gdb.FinishBreakpoint' and override this

  28053.      method:

  28054. 

  28055.           class MyFinishBreakpoint (gdb.FinishBreakpoint)

  28056.               def stop (self):

  28057.                   print "normal finish"

  28058.                   return True

  28059. 

  28060.               def out_of_scope ():

  28061.                   print "abnormal finish"

  28062. 

  28063.  -- Variable: FinishBreakpoint.return_value

  28064.      When GDB is stopped at a finish breakpoint and the frame used to

  28065.      build the 'gdb.FinishBreakpoint' object had debug symbols, this

  28066.      attribute will contain a 'gdb.Value' object corresponding to the

  28067.      return value of the function.  The value will be 'None' if the

  28068.      function return type is 'void' or if the return value was not

  28069.      computable.  This attribute is not writable.

  28070. 

  28071. 

  28072. File: gdb.info,  Node: Lazy Strings In Python,  Next: Architectures In Python,  Prev: Finish Breakpoints in Python,  Up: Python API

  28073. 

  28074. 23.2.2.32 Python representation of lazy strings

  28075. ...............................................

  28076. 

  28077. A "lazy string" is a string whose contents is not retrieved or encoded

  28078. until it is needed.

  28079. 

  28080.    A 'gdb.LazyString' is represented in GDB as an 'address' that points

  28081. to a region of memory, an 'encoding' that will be used to encode that

  28082. region of memory, and a 'length' to delimit the region of memory that

  28083. represents the string.  The difference between a 'gdb.LazyString' and a

  28084. string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be

  28085. treated differently by GDB when printing.  A 'gdb.LazyString' is

  28086. retrieved and encoded during printing, while a 'gdb.Value' wrapping a

  28087. string is immediately retrieved and encoded on creation.

  28088. 

  28089.    A 'gdb.LazyString' object has the following functions:

  28090. 

  28091.  -- Function: LazyString.value ()

  28092.      Convert the 'gdb.LazyString' to a 'gdb.Value'.  This value will

  28093.      point to the string in memory, but will lose all the delayed

  28094.      retrieval, encoding and handling that GDB applies to a

  28095.      'gdb.LazyString'.

  28096. 

  28097.  -- Variable: LazyString.address

  28098.      This attribute holds the address of the string.  This attribute is

  28099.      not writable.

  28100. 

  28101.  -- Variable: LazyString.length

  28102.      This attribute holds the length of the string in characters.  If

  28103.      the length is -1, then the string will be fetched and encoded up to

  28104.      the first null of appropriate width.  This attribute is not

  28105.      writable.

  28106. 

  28107.  -- Variable: LazyString.encoding

  28108.      This attribute holds the encoding that will be applied to the

  28109.      string when the string is printed by GDB.  If the encoding is not

  28110.      set, or contains an empty string, then GDB will select the most

  28111.      appropriate encoding when the string is printed.  This attribute is

  28112.      not writable.

  28113. 

  28114.  -- Variable: LazyString.type

  28115.      This attribute holds the type that is represented by the lazy

  28116.      string's type.  For a lazy string this is a pointer or array type.

  28117.      To resolve this to the lazy string's character type, use the type's

  28118.      'target' method.  *Note Types In Python::.  This attribute is not

  28119.      writable.

  28120. 

  28121. 

  28122. File: gdb.info,  Node: Architectures In Python,  Next: Registers In Python,  Prev: Lazy Strings In Python,  Up: Python API

  28123. 

  28124. 23.2.2.33 Python representation of architectures

  28125. ................................................

  28126. 

  28127. GDB uses architecture specific parameters and artifacts in a number of

  28128. its various computations.  An architecture is represented by an instance

  28129. of the 'gdb.Architecture' class.

  28130. 

  28131.    A 'gdb.Architecture' class has the following methods:

  28132. 

  28133.  -- Function: Architecture.name ()

  28134.      Return the name (string value) of the architecture.

  28135. 

  28136.  -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]])

  28137.      Return a list of disassembled instructions starting from the memory

  28138.      address START_PC.  The optional arguments END_PC and COUNT

  28139.      determine the number of instructions in the returned list.  If both

  28140.      the optional arguments END_PC and COUNT are specified, then a list

  28141.      of at most COUNT disassembled instructions whose start address

  28142.      falls in the closed memory address interval from START_PC to END_PC

  28143.      are returned.  If END_PC is not specified, but COUNT is specified,

  28144.      then COUNT number of instructions starting from the address

  28145.      START_PC are returned.  If COUNT is not specified but END_PC is

  28146.      specified, then all instructions whose start address falls in the

  28147.      closed memory address interval from START_PC to END_PC are

  28148.      returned.  If neither END_PC nor COUNT are specified, then a single

  28149.      instruction at START_PC is returned.  For all of these cases, each

  28150.      element of the returned list is a Python 'dict' with the following

  28151.      string keys:

  28152. 

  28153.      'addr'

  28154.           The value corresponding to this key is a Python long integer

  28155.           capturing the memory address of the instruction.

  28156. 

  28157.      'asm'

  28158.           The value corresponding to this key is a string value which

  28159.           represents the instruction with assembly language mnemonics.

  28160.           The assembly language flavor used is the same as that

  28161.           specified by the current CLI variable 'disassembly-flavor'.

  28162.           *Note Machine Code::.

  28163. 

  28164.      'length'

  28165.           The value corresponding to this key is the length (integer

  28166.           value) of the instruction in bytes.

  28167. 

  28168.  -- Function: Architecture.registers ([ REGGROUP ])

  28169.      Return a 'gdb.RegisterDescriptorIterator' (*note Registers In

  28170.      Python::) for all of the registers in REGGROUP, a string that is

  28171.      the name of a register group.  If REGGROUP is omitted, or is the

  28172.      empty string, then the register group 'all' is assumed.

  28173. 

  28174.  -- Function: Architecture.register_groups ()

  28175.      Return a 'gdb.RegisterGroupsIterator' (*note Registers In Python::)

  28176.      for all of the register groups available for the

  28177.      'gdb.Architecture'.

  28178. 

  28179. 

  28180. File: gdb.info,  Node: Registers In Python,  Next: TUI Windows In Python,  Prev: Architectures In Python,  Up: Python API

  28181. 

  28182. 23.2.2.34 Registers In Python

  28183. .............................

  28184. 

  28185. Python code can request from a 'gdb.Architecture' information about the

  28186. set of registers available (*note 'Architecture.registers':

  28187. gdbpy_architecture_registers.).  The register information is returned as

  28188. a 'gdb.RegisterDescriptorIterator', which is an iterator that in turn

  28189. returns 'gdb.RegisterDescriptor' objects.

  28190. 

  28191.    A 'gdb.RegisterDescriptor' does not provide the value of a register

  28192. (*note 'Frame.read_register': gdbpy_frame_read_register. for reading a

  28193. register's value), instead the 'RegisterDescriptor' is a way to discover

  28194. which registers are available for a particular architecture.

  28195. 

  28196.    A 'gdb.RegisterDescriptor' has the following read-only properties:

  28197. 

  28198.  -- Variable: RegisterDescriptor.name

  28199.      The name of this register.

  28200. 

  28201.    It is also possible to lookup a register descriptor based on its name

  28202. using the following 'gdb.RegisterDescriptorIterator' function:

  28203. 

  28204.  -- Function: RegisterDescriptorIterator.find (NAME)

  28205.      Takes NAME as an argument, which must be a string, and returns a

  28206.      'gdb.RegisterDescriptor' for the register with that name, or 'None'

  28207.      if there is no register with that name.

  28208. 

  28209.    Python code can also request from a 'gdb.Architecture' information

  28210. about the set of register groups available on a given architecture

  28211. (*note 'Architecture.register_groups': gdbpy_architecture_reggroups.).

  28212. 

  28213.    Every register can be a member of zero or more register groups.  Some

  28214. register groups are used internally within GDB to control things like

  28215. which registers must be saved when calling into the program being

  28216. debugged (*note Calling Program Functions: Calling.).  Other register

  28217. groups exist to allow users to easily see related sets of registers in

  28218. commands like 'info registers' (*note 'info registers REGGROUP':

  28219. info_registers_reggroup.).

  28220. 

  28221.    The register groups information is returned as a

  28222. 'gdb.RegisterGroupsIterator', which is an iterator that in turn returns

  28223. 'gdb.RegisterGroup' objects.

  28224. 

  28225.    A 'gdb.RegisterGroup' object has the following read-only properties:

  28226. 

  28227.  -- Variable: RegisterGroup.name

  28228.      A string that is the name of this register group.

  28229. 

  28230. 

  28231. File: gdb.info,  Node: TUI Windows In Python,  Prev: Registers In Python,  Up: Python API

  28232. 

  28233. 23.2.2.35 Implementing new TUI windows

  28234. ......................................

  28235. 

  28236. New TUI (*note TUI::) windows can be implemented in Python.

  28237. 

  28238.  -- Function: gdb.register_window_type (NAME, FACTORY)

  28239.      Because TUI windows are created and destroyed depending on the

  28240.      layout the user chooses, new window types are implemented by

  28241.      registering a factory function with GDB.

  28242. 

  28243.      NAME is the name of the new window.  It's an error to try to

  28244.      replace one of the built-in windows, but other window types can be

  28245.      replaced.

  28246. 

  28247.      FUNCTION is a factory function that is called to create the TUI

  28248.      window.  This is called with a single argument of type

  28249.      'gdb.TuiWindow', described below.  It should return an object that

  28250.      implements the TUI window protocol, also described below.

  28251. 

  28252.    As mentioned above, when a factory function is called, it is passed a

  28253. an object of type 'gdb.TuiWindow'.  This object has these methods and

  28254. attributes:

  28255. 

  28256.  -- Function: TuiWindow.is_valid ()

  28257.      This method returns 'True' when this window is valid.  When the

  28258.      user changes the TUI layout, windows no longer visible in the new

  28259.      layout will be destroyed.  At this point, the 'gdb.TuiWindow' will

  28260.      no longer be valid, and methods (and attributes) other than

  28261.      'is_valid' will throw an exception.

  28262. 

  28263.  -- Variable: TuiWindow.width

  28264.      This attribute holds the width of the window.  It is not writable.

  28265. 

  28266.  -- Variable: TuiWindow.height

  28267.      This attribute holds the height of the window.  It is not writable.

  28268. 

  28269.  -- Variable: TuiWindow.title

  28270.      This attribute holds the window's title, a string.  This is

  28271.      normally displayed above the window.  This attribute can be

  28272.      modified.

  28273. 

  28274.  -- Function: TuiWindow.erase ()

  28275.      Remove all the contents of the window.

  28276. 

  28277.  -- Function: TuiWindow.write (STRING)

  28278.      Write STRING to the window.  STRING can contain ANSI terminal

  28279.      escape styling sequences; GDB will translate these as appropriate

  28280.      for the terminal.

  28281. 

  28282.    The factory function that you supply should return an object

  28283. conforming to the TUI window protocol.  These are the method that can be

  28284. called on this object, which is referred to below as the "window

  28285. object".  The methods documented below are optional; if the object does

  28286. not implement one of these methods, GDB will not attempt to call it.

  28287. Additional new methods may be added to the window protocol in the

  28288. future.  GDB guarantees that they will begin with a lower-case letter,

  28289. so you can start implementation methods with upper-case letters or

  28290. underscore to avoid any future conflicts.

  28291. 

  28292.  -- Function: Window.close ()

  28293.      When the TUI window is closed, the 'gdb.TuiWindow' object will be

  28294.      put into an invalid state.  At this time, GDB will call 'close'

  28295.      method on the window object.

  28296. 

  28297.      After this method is called, GDB will discard any references it

  28298.      holds on this window object, and will no longer call methods on

  28299.      this object.

  28300. 

  28301.  -- Function: Window.render ()

  28302.      In some situations, a TUI window can change size.  For example,

  28303.      this can happen if the user resizes the terminal, or changes the

  28304.      layout.  When this happens, GDB will call the 'render' method on

  28305.      the window object.

  28306. 

  28307.      If your window is intended to update in response to changes in the

  28308.      inferior, you will probably also want to register event listeners

  28309.      and send output to the 'gdb.TuiWindow'.

  28310. 

  28311.  -- Function: Window.hscroll (NUM)

  28312.      This is a request to scroll the window horizontally.  NUM is the

  28313.      amount by which to scroll, with negative numbers meaning to scroll

  28314.      right.  In the TUI model, it is the viewport that moves, not the

  28315.      contents.  A positive argument should cause the viewport to move

  28316.      right, and so the content should appear to move to the left.

  28317. 

  28318.  -- Function: Window.vscroll (NUM)

  28319.      This is a request to scroll the window vertically.  NUM is the

  28320.      amount by which to scroll, with negative numbers meaning to scroll

  28321.      backward.  In the TUI model, it is the viewport that moves, not the

  28322.      contents.  A positive argument should cause the viewport to move

  28323.      down, and so the content should appear to move up.

  28324. 

  28325. 

  28326. File: gdb.info,  Node: Python Auto-loading,  Next: Python modules,  Prev: Python API,  Up: Python

  28327. 

  28328. 23.2.3 Python Auto-loading

  28329. --------------------------

  28330. 

  28331. When a new object file is read (for example, due to the 'file' command,

  28332. or because the inferior has loaded a shared library), GDB will look for

  28333. Python support scripts in several ways: 'OBJFILE-gdb.py' and

  28334. '.debug_gdb_scripts' section.  *Note Auto-loading extensions::.

  28335. 

  28336.    The auto-loading feature is useful for supplying application-specific

  28337. debugging commands and scripts.

  28338. 

  28339.    Auto-loading can be enabled or disabled, and the list of auto-loaded

  28340. scripts can be printed.

  28341. 

  28342. 'set auto-load python-scripts [on|off]'

  28343.      Enable or disable the auto-loading of Python scripts.

  28344. 

  28345. 'show auto-load python-scripts'

  28346.      Show whether auto-loading of Python scripts is enabled or disabled.

  28347. 

  28348. 'info auto-load python-scripts [REGEXP]'

  28349.      Print the list of all Python scripts that GDB auto-loaded.

  28350. 

  28351.      Also printed is the list of Python scripts that were mentioned in

  28352.      the '.debug_gdb_scripts' section and were either not found (*note

  28353.      dotdebug_gdb_scripts section::) or were not auto-loaded due to

  28354.      'auto-load safe-path' rejection (*note Auto-loading::).  This is

  28355.      useful because their names are not printed when GDB tries to load

  28356.      them and fails.  There may be many of them, and printing an error

  28357.      message for each one is problematic.

  28358. 

  28359.      If REGEXP is supplied only Python scripts with matching names are

  28360.      printed.

  28361. 

  28362.      Example:

  28363. 

  28364.           (gdb) info auto-load python-scripts

  28365.           Loaded Script

  28366.           Yes    py-section-script.py

  28367.                  full name: /tmp/py-section-script.py

  28368.           No     my-foo-pretty-printers.py

  28369. 

  28370.    When reading an auto-loaded file or script, GDB sets the "current

  28371. objfile".  This is available via the 'gdb.current_objfile' function

  28372. (*note Objfiles In Python::).  This can be useful for registering

  28373. objfile-specific pretty-printers and frame-filters.

  28374. 

  28375. 

  28376. File: gdb.info,  Node: Python modules,  Prev: Python Auto-loading,  Up: Python

  28377. 

  28378. 23.2.4 Python modules

  28379. ---------------------

  28380. 

  28381. GDB comes with several modules to assist writing Python code.

  28382. 

  28383. * Menu:

  28384. 

  28385. * gdb.printing::       Building and registering pretty-printers.

  28386. * gdb.types::          Utilities for working with types.

  28387. * gdb.prompt::         Utilities for prompt value substitution.

  28388. 

  28389. 

  28390. File: gdb.info,  Node: gdb.printing,  Next: gdb.types,  Up: Python modules

  28391. 

  28392. 23.2.4.1 gdb.printing

  28393. .....................

  28394. 

  28395. This module provides a collection of utilities for working with

  28396. pretty-printers.

  28397. 

  28398. 'PrettyPrinter (NAME, SUBPRINTERS=None)'

  28399.      This class specifies the API that makes 'info pretty-printer',

  28400.      'enable pretty-printer' and 'disable pretty-printer' work.

  28401.      Pretty-printers should generally inherit from this class.

  28402. 

  28403. 'SubPrettyPrinter (NAME)'

  28404.      For printers that handle multiple types, this class specifies the

  28405.      corresponding API for the subprinters.

  28406. 

  28407. 'RegexpCollectionPrettyPrinter (NAME)'

  28408.      Utility class for handling multiple printers, all recognized via

  28409.      regular expressions.  *Note Writing a Pretty-Printer::, for an

  28410.      example.

  28411. 

  28412. 'FlagEnumerationPrinter (NAME)'

  28413.      A pretty-printer which handles printing of 'enum' values.  Unlike

  28414.      GDB's built-in 'enum' printing, this printer attempts to work

  28415.      properly when there is some overlap between the enumeration

  28416.      constants.  The argument NAME is the name of the printer and also

  28417.      the name of the 'enum' type to look up.

  28418. 

  28419. 'register_pretty_printer (OBJ, PRINTER, REPLACE=False)'

  28420.      Register PRINTER with the pretty-printer list of OBJ.  If REPLACE

  28421.      is 'True' then any existing copy of the printer is replaced.

  28422.      Otherwise a 'RuntimeError' exception is raised if a printer with

  28423.      the same name already exists.

  28424. 

  28425. 

  28426. File: gdb.info,  Node: gdb.types,  Next: gdb.prompt,  Prev: gdb.printing,  Up: Python modules

  28427. 

  28428. 23.2.4.2 gdb.types

  28429. ..................

  28430. 

  28431. This module provides a collection of utilities for working with

  28432. 'gdb.Type' objects.

  28433. 

  28434. 'get_basic_type (TYPE)'

  28435.      Return TYPE with const and volatile qualifiers stripped, and with

  28436.      typedefs and C++ references converted to the underlying type.

  28437. 

  28438.      C++ example:

  28439. 

  28440.           typedef const int const_int;

  28441.           const_int foo (3);

  28442.           const_int& foo_ref (foo);

  28443.           int main () { return 0; }

  28444. 

  28445.      Then in gdb:

  28446. 

  28447.           (gdb) start

  28448.           (gdb) python import gdb.types

  28449.           (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")

  28450.           (gdb) python print gdb.types.get_basic_type(foo_ref.type)

  28451.           int

  28452. 

  28453. 'has_field (TYPE, FIELD)'

  28454.      Return 'True' if TYPE, assumed to be a type with fields (e.g., a

  28455.      structure or union), has field FIELD.

  28456. 

  28457. 'make_enum_dict (ENUM_TYPE)'

  28458.      Return a Python 'dictionary' type produced from ENUM_TYPE.

  28459. 

  28460. 'deep_items (TYPE)'

  28461.      Returns a Python iterator similar to the standard

  28462.      'gdb.Type.iteritems' method, except that the iterator returned by

  28463.      'deep_items' will recursively traverse anonymous struct or union

  28464.      fields.  For example:

  28465. 

  28466.           struct A

  28467.           {

  28468.               int a;

  28469.               union {

  28470.                   int b0;

  28471.                   int b1;

  28472.               };

  28473.           };

  28474. 

  28475.      Then in GDB:

  28476.           (gdb) python import gdb.types

  28477.           (gdb) python struct_a = gdb.lookup_type("struct A")

  28478.           (gdb) python print struct_a.keys ()

  28479.           {['a', '']}

  28480.           (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]

  28481.           {['a', 'b0', 'b1']}

  28482. 

  28483. 'get_type_recognizers ()'

  28484.      Return a list of the enabled type recognizers for the current

  28485.      context.  This is called by GDB during the type-printing process

  28486.      (*note Type Printing API::).

  28487. 

  28488. 'apply_type_recognizers (recognizers, type_obj)'

  28489.      Apply the type recognizers, RECOGNIZERS, to the type object

  28490.      TYPE_OBJ.  If any recognizer returns a string, return that string.

  28491.      Otherwise, return 'None'.  This is called by GDB during the

  28492.      type-printing process (*note Type Printing API::).

  28493. 

  28494. 'register_type_printer (locus, printer)'

  28495.      This is a convenience function to register a type printer PRINTER.

  28496.      The printer must implement the type printer protocol.  The LOCUS

  28497.      argument is either a 'gdb.Objfile', in which case the printer is

  28498.      registered with that objfile; a 'gdb.Progspace', in which case the

  28499.      printer is registered with that progspace; or 'None', in which case

  28500.      the printer is registered globally.

  28501. 

  28502. 'TypePrinter'

  28503.      This is a base class that implements the type printer protocol.

  28504.      Type printers are encouraged, but not required, to derive from this

  28505.      class.  It defines a constructor:

  28506. 

  28507.       -- Method on TypePrinter: __init__ (self, name)

  28508.           Initialize the type printer with the given name.  The new

  28509.           printer starts in the enabled state.

  28510. 

  28511. 

  28512. File: gdb.info,  Node: gdb.prompt,  Prev: gdb.types,  Up: Python modules

  28513. 

  28514. 23.2.4.3 gdb.prompt

  28515. ...................

  28516. 

  28517. This module provides a method for prompt value-substitution.

  28518. 

  28519. 'substitute_prompt (STRING)'

  28520.      Return STRING with escape sequences substituted by values.  Some

  28521.      escape sequences take arguments.  You can specify arguments inside

  28522.      "{}" immediately following the escape sequence.

  28523. 

  28524.      The escape sequences you can pass to this function are:

  28525. 

  28526.      '\\'

  28527.           Substitute a backslash.

  28528.      '\e'

  28529.           Substitute an ESC character.

  28530.      '\f'

  28531.           Substitute the selected frame; an argument names a frame

  28532.           parameter.

  28533.      '\n'

  28534.           Substitute a newline.

  28535.      '\p'

  28536.           Substitute a parameter's value; the argument names the

  28537.           parameter.

  28538.      '\r'

  28539.           Substitute a carriage return.

  28540.      '\t'

  28541.           Substitute the selected thread; an argument names a thread

  28542.           parameter.

  28543.      '\v'

  28544.           Substitute the version of GDB.

  28545.      '\w'

  28546.           Substitute the current working directory.

  28547.      '\['

  28548.           Begin a sequence of non-printing characters.  These sequences

  28549.           are typically used with the ESC character, and are not counted

  28550.           in the string length.  Example: "\[\e[0;34m\](gdb)\[\e[0m\]"

  28551.           will return a blue-colored "(gdb)" prompt where the length is

  28552.           five.

  28553.      '\]'

  28554.           End a sequence of non-printing characters.

  28555. 

  28556.      For example:

  28557. 

  28558.           substitute_prompt ("frame: \f, args: \p{print frame-arguments}")

  28559. 

  28560. will return the string:

  28561. 

  28562.           "frame: main, args: scalars"

  28563. 

  28564. 

  28565. File: gdb.info,  Node: Guile,  Next: Auto-loading extensions,  Prev: Python,  Up: Extending GDB

  28566. 

  28567. 23.3 Extending GDB using Guile

  28568. ==============================

  28569. 

  28570. You can extend GDB using the Guile implementation of the Scheme

  28571. programming language (http://www.gnu.org/software/guile/).  This feature

  28572. is available only if GDB was configured using '--with-guile'.

  28573. 

  28574. * Menu:

  28575. 

  28576. * Guile Introduction::     Introduction to Guile scripting in GDB

  28577. * Guile Commands::         Accessing Guile from GDB

  28578. * Guile API::              Accessing GDB from Guile

  28579. * Guile Auto-loading::     Automatically loading Guile code

  28580. * Guile Modules::          Guile modules provided by GDB

  28581. 

  28582. 

  28583. File: gdb.info,  Node: Guile Introduction,  Next: Guile Commands,  Up: Guile

  28584. 

  28585. 23.3.1 Guile Introduction

  28586. -------------------------

  28587. 

  28588. Guile is an implementation of the Scheme programming language and is the

  28589. GNU project's official extension language.

  28590. 

  28591.    Guile support in GDB follows the Python support in GDB reasonably

  28592. closely, so concepts there should carry over.  However, some things are

  28593. done differently where it makes sense.

  28594. 

  28595.    GDB requires Guile version 3.0, 2.2, or 2.0.

  28596. 

  28597.    Guile scripts used by GDB should be installed in

  28598. 'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as

  28599. determined at GDB startup (*note Data Files::).  This directory, known

  28600. as the "guile directory", is automatically added to the Guile Search

  28601. Path in order to allow the Guile interpreter to locate all scripts

  28602. installed at this location.

  28603. 

  28604. 

  28605. File: gdb.info,  Node: Guile Commands,  Next: Guile API,  Prev: Guile Introduction,  Up: Guile

  28606. 

  28607. 23.3.2 Guile Commands

  28608. ---------------------

  28609. 

  28610. GDB provides two commands for accessing the Guile interpreter:

  28611. 

  28612. 'guile-repl'

  28613. 'gr'

  28614.      The 'guile-repl' command can be used to start an interactive Guile

  28615.      prompt or "repl".  To return to GDB, type ',q' or the 'EOF'

  28616.      character (e.g., 'Ctrl-D' on an empty prompt).  These commands do

  28617.      not take any arguments.

  28618. 

  28619. 'guile [SCHEME-EXPRESSION]'

  28620. 'gu [SCHEME-EXPRESSION]'

  28621.      The 'guile' command can be used to evaluate a Scheme expression.

  28622. 

  28623.      If given an argument, GDB will pass the argument to the Guile

  28624.      interpreter for evaluation.

  28625. 

  28626.           (gdb) guile (display (+ 20 3)) (newline)

  28627.           23

  28628. 

  28629.      The result of the Scheme expression is displayed using normal Guile

  28630.      rules.

  28631. 

  28632.           (gdb) guile (+ 20 3)

  28633.           23

  28634. 

  28635.      If you do not provide an argument to 'guile', it will act as a

  28636.      multi-line command, like 'define'.  In this case, the Guile script

  28637.      is made up of subsequent command lines, given after the 'guile'

  28638.      command.  This command list is terminated using a line containing

  28639.      'end'.  For example:

  28640. 

  28641.           (gdb) guile

  28642.           >(display 23)

  28643.           >(newline)

  28644.           >end

  28645.           23

  28646. 

  28647.    It is also possible to execute a Guile script from the GDB

  28648. interpreter:

  28649. 

  28650. 'source script-name'

  28651.      The script name must end with '.scm' and GDB must be configured to

  28652.      recognize the script language based on filename extension using the

  28653.      'script-extension' setting.  *Note Extending GDB: Extending GDB.

  28654. 

  28655. 'guile (load "script-name")'

  28656.      This method uses the 'load' Guile function.  It takes a string

  28657.      argument that is the name of the script to load.  See the Guile

  28658.      documentation for a description of this function.  (*note

  28659.      (guile)Loading::).

  28660. 

  28661. 

  28662. File: gdb.info,  Node: Guile API,  Next: Guile Auto-loading,  Prev: Guile Commands,  Up: Guile

  28663. 

  28664. 23.3.3 Guile API

  28665. ----------------

  28666. 

  28667. You can get quick online help for GDB's Guile API by issuing the command

  28668. 'help guile', or by issuing the command ',help' from an interactive

  28669. Guile session.  Furthermore, most Guile procedures provided by GDB have

  28670. doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d

  28671. PROCEDURE-NAME' from the Guile interactive prompt.

  28672. 

  28673. * Menu:

  28674. 

  28675. * Basic Guile::              Basic Guile Functions

  28676. * Guile Configuration::      Guile configuration variables

  28677. * GDB Scheme Data Types::    Scheme representations of GDB objects

  28678. * Guile Exception Handling:: How Guile exceptions are translated

  28679. * Values From Inferior In Guile:: Guile representation of values

  28680. * Arithmetic In Guile::      Arithmetic in Guile

  28681. * Types In Guile::           Guile representation of types

  28682. * Guile Pretty Printing API:: Pretty-printing values with Guile

  28683. * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer

  28684. * Writing a Guile Pretty-Printer:: Writing a pretty-printer

  28685. * Commands In Guile::        Implementing new commands in Guile

  28686. * Parameters In Guile::      Adding new GDB parameters

  28687. * Progspaces In Guile::      Program spaces

  28688. * Objfiles In Guile::        Object files in Guile

  28689. * Frames In Guile::          Accessing inferior stack frames from Guile

  28690. * Blocks In Guile::          Accessing blocks from Guile

  28691. * Symbols In Guile::         Guile representation of symbols

  28692. * Symbol Tables In Guile::   Guile representation of symbol tables

  28693. * Breakpoints In Guile::     Manipulating breakpoints using Guile

  28694. * Lazy Strings In Guile::    Guile representation of lazy strings

  28695. * Architectures In Guile::   Guile representation of architectures

  28696. * Disassembly In Guile::     Disassembling instructions from Guile

  28697. * I/O Ports in Guile::       GDB I/O ports

  28698. * Memory Ports in Guile::    Accessing memory through ports and bytevectors

  28699. * Iterators In Guile::       Basic iterator support

  28700. 

  28701. 

  28702. File: gdb.info,  Node: Basic Guile,  Next: Guile Configuration,  Up: Guile API

  28703. 

  28704. 23.3.3.1 Basic Guile

  28705. ....................

  28706. 

  28707. At startup, GDB overrides Guile's 'current-output-port' and

  28708. 'current-error-port' to print using GDB's output-paging streams.  A

  28709. Guile program which outputs to one of these streams may have its output

  28710. interrupted by the user (*note Screen Size::).  In this situation, a

  28711. Guile 'signal' exception is thrown with value 'SIGINT'.

  28712. 

  28713.    Guile's history mechanism uses the same naming as GDB's, namely the

  28714. user of dollar-variables (e.g., $1, $2, etc.).  The results of

  28715. evaluations in Guile and in GDB are counted separately, '$1' in Guile is

  28716. not the same value as '$1' in GDB.

  28717. 

  28718.    GDB is not thread-safe.  If your Guile program uses multiple threads,

  28719. you must be careful to only call GDB-specific functions in the GDB

  28720. thread.

  28721. 

  28722.    Some care must be taken when writing Guile code to run in GDB.  Two

  28723. things are worth noting in particular:

  28724. 

  28725.    * GDB installs handlers for 'SIGCHLD' and 'SIGINT'.  Guile code must

  28726.      not override these, or even change the options using 'sigaction'.

  28727.      If your program changes the handling of these signals, GDB will

  28728.      most likely stop working correctly.  Note that it is unfortunately

  28729.      common for GUI toolkits to install a 'SIGCHLD' handler.

  28730. 

  28731.    * GDB takes care to mark its internal file descriptors as

  28732.      close-on-exec.  However, this cannot be done in a thread-safe way

  28733.      on all platforms.  Your Guile programs should be aware of this and

  28734.      should both create new file descriptors with the close-on-exec flag

  28735.      set and arrange to close unneeded file descriptors before starting

  28736.      a child process.

  28737. 

  28738.    GDB introduces a new Guile module, named 'gdb'.  All methods and

  28739. classes added by GDB are placed in this module.  GDB does not

  28740. automatically 'import' the 'gdb' module, scripts must do this

  28741. themselves.  There are various options for how to import a module, so

  28742. GDB leaves the choice of how the 'gdb' module is imported to the user.

  28743. To simplify interactive use, it is recommended to add one of the

  28744. following to your ~/.gdbinit.

  28745. 

  28746.      guile (use-modules (gdb))

  28747. 

  28748.      guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))

  28749. 

  28750.    Which one to choose depends on your preference.  The second one adds

  28751. 'gdb:' as a prefix to all module functions and variables.

  28752. 

  28753.    The rest of this manual assumes the 'gdb' module has been imported

  28754. without any prefix.  See the Guile documentation for 'use-modules' for

  28755. more information (*note (guile)Using Guile Modules::).

  28756. 

  28757.    Example:

  28758. 

  28759.      (gdb) guile (value-type (make-value 1))

  28760.      ERROR: Unbound variable: value-type

  28761.      Error while executing Scheme code.

  28762.      (gdb) guile (use-modules (gdb))

  28763.      (gdb) guile (value-type (make-value 1))

  28764.      int

  28765.      (gdb)

  28766. 

  28767.    The '(gdb)' module provides these basic Guile functions.

  28768. 

  28769.  -- Scheme Procedure: execute command [#:from-tty boolean] [#:to-string

  28770.           boolean]

  28771.      Evaluate COMMAND, a string, as a GDB CLI command.  If a GDB

  28772.      exception happens while COMMAND runs, it is translated as described

  28773.      in *note Guile Exception Handling: Guile Exception Handling.

  28774. 

  28775.      FROM-TTY specifies whether GDB ought to consider this command as

  28776.      having originated from the user invoking it interactively.  It must

  28777.      be a boolean value.  If omitted, it defaults to '#f'.

  28778. 

  28779.      By default, any output produced by COMMAND is sent to GDB's

  28780.      standard output (and to the log output if logging is turned on).

  28781.      If the TO-STRING parameter is '#t', then output will be collected

  28782.      by 'execute' and returned as a string.  The default is '#f', in

  28783.      which case the return value is unspecified.  If TO-STRING is '#t',

  28784.      the GDB virtual terminal will be temporarily set to unlimited width

  28785.      and height, and its pagination will be disabled; *note Screen

  28786.      Size::.

  28787. 

  28788.  -- Scheme Procedure: history-ref number

  28789.      Return a value from GDB's value history (*note Value History::).

  28790.      The NUMBER argument indicates which history element to return.  If

  28791.      NUMBER is negative, then GDB will take its absolute value and count

  28792.      backward from the last element (i.e., the most recent element) to

  28793.      find the value to return.  If NUMBER is zero, then GDB will return

  28794.      the most recent element.  If the element specified by NUMBER

  28795.      doesn't exist in the value history, a 'gdb:error' exception will be

  28796.      raised.

  28797. 

  28798.      If no exception is raised, the return value is always an instance

  28799.      of '<gdb:value>' (*note Values From Inferior In Guile::).

  28800. 

  28801.      _Note:_ GDB's value history is independent of Guile's.  '$1' in

  28802.      GDB's value history contains the result of evaluating an expression

  28803.      from GDB's command line and '$1' from Guile's history contains the

  28804.      result of evaluating an expression from Guile's command line.

  28805. 

  28806.  -- Scheme Procedure: history-append! value

  28807.      Append VALUE, an instance of '<gdb:value>', to GDB's value history.

  28808.      Return its index in the history.

  28809. 

  28810.      Putting into history values returned by Guile extensions will allow

  28811.      the user convenient access to those values via CLI history

  28812.      facilities.

  28813. 

  28814.  -- Scheme Procedure: parse-and-eval expression

  28815.      Parse EXPRESSION as an expression in the current language, evaluate

  28816.      it, and return the result as a '<gdb:value>'.  The EXPRESSION must

  28817.      be a string.

  28818. 

  28819.      This function can be useful when implementing a new command (*note

  28820.      Commands In Guile::), as it provides a way to parse the command's

  28821.      arguments as an expression.  It is also is useful when computing

  28822.      values.  For example, it is the only way to get the value of a

  28823.      convenience variable (*note Convenience Vars::) as a '<gdb:value>'.

  28824. 

  28825. 

  28826. File: gdb.info,  Node: Guile Configuration,  Next: GDB Scheme Data Types,  Prev: Basic Guile,  Up: Guile API

  28827. 

  28828. 23.3.3.2 Guile Configuration

  28829. ............................

  28830. 

  28831. GDB provides these Scheme functions to access various configuration

  28832. parameters.

  28833. 

  28834.  -- Scheme Procedure: data-directory

  28835.      Return a string containing GDB's data directory.  This directory

  28836.      contains GDB's ancillary files.

  28837. 

  28838.  -- Scheme Procedure: guile-data-directory

  28839.      Return a string containing GDB's Guile data directory.  This

  28840.      directory contains the Guile modules provided by GDB.

  28841. 

  28842.  -- Scheme Procedure: gdb-version

  28843.      Return a string containing the GDB version.

  28844. 

  28845.  -- Scheme Procedure: host-config

  28846.      Return a string containing the host configuration.  This is the

  28847.      string passed to '--host' when GDB was configured.

  28848. 

  28849.  -- Scheme Procedure: target-config

  28850.      Return a string containing the target configuration.  This is the

  28851.      string passed to '--target' when GDB was configured.

  28852. 

  28853. 

  28854. File: gdb.info,  Node: GDB Scheme Data Types,  Next: Guile Exception Handling,  Prev: Guile Configuration,  Up: Guile API

  28855. 

  28856. 23.3.3.3 GDB Scheme Data Types

  28857. ..............................

  28858. 

  28859. The values exposed by GDB to Guile are known as "GDB objects".  There

  28860. are several kinds of GDB object, and each is disjoint from all other

  28861. types known to Guile.

  28862. 

  28863.  -- Scheme Procedure: gdb-object-kind object

  28864.      Return the kind of the GDB object, e.g., '<gdb:breakpoint>', as a

  28865.      symbol.

  28866. 

  28867.    GDB defines the following object types:

  28868. 

  28869. '<gdb:arch>'

  28870.      *Note Architectures In Guile::.

  28871. 

  28872. '<gdb:block>'

  28873.      *Note Blocks In Guile::.

  28874. 

  28875. '<gdb:block-symbols-iterator>'

  28876.      *Note Blocks In Guile::.

  28877. 

  28878. '<gdb:breakpoint>'

  28879.      *Note Breakpoints In Guile::.

  28880. 

  28881. '<gdb:command>'

  28882.      *Note Commands In Guile::.

  28883. 

  28884. '<gdb:exception>'

  28885.      *Note Guile Exception Handling::.

  28886. 

  28887. '<gdb:frame>'

  28888.      *Note Frames In Guile::.

  28889. 

  28890. '<gdb:iterator>'

  28891.      *Note Iterators In Guile::.

  28892. 

  28893. '<gdb:lazy-string>'

  28894.      *Note Lazy Strings In Guile::.

  28895. 

  28896. '<gdb:objfile>'

  28897.      *Note Objfiles In Guile::.

  28898. 

  28899. '<gdb:parameter>'

  28900.      *Note Parameters In Guile::.

  28901. 

  28902. '<gdb:pretty-printer>'

  28903.      *Note Guile Pretty Printing API::.

  28904. 

  28905. '<gdb:pretty-printer-worker>'

  28906.      *Note Guile Pretty Printing API::.

  28907. 

  28908. '<gdb:progspace>'

  28909.      *Note Progspaces In Guile::.

  28910. 

  28911. '<gdb:symbol>'

  28912.      *Note Symbols In Guile::.

  28913. 

  28914. '<gdb:symtab>'

  28915.      *Note Symbol Tables In Guile::.

  28916. 

  28917. '<gdb:sal>'

  28918.      *Note Symbol Tables In Guile::.

  28919. 

  28920. '<gdb:type>'

  28921.      *Note Types In Guile::.

  28922. 

  28923. '<gdb:field>'

  28924.      *Note Types In Guile::.

  28925. 

  28926. '<gdb:value>'

  28927.      *Note Values From Inferior In Guile::.

  28928. 

  28929.    The following GDB objects are managed internally so that the Scheme

  28930. function 'eq?' may be applied to them.

  28931. 

  28932. '<gdb:arch>'

  28933. '<gdb:block>'

  28934. '<gdb:breakpoint>'

  28935. '<gdb:frame>'

  28936. '<gdb:objfile>'

  28937. '<gdb:progspace>'

  28938. '<gdb:symbol>'

  28939. '<gdb:symtab>'

  28940. '<gdb:type>'

  28941. 

  28942. 

  28943. File: gdb.info,  Node: Guile Exception Handling,  Next: Values From Inferior In Guile,  Prev: GDB Scheme Data Types,  Up: Guile API

  28944. 

  28945. 23.3.3.4 Guile Exception Handling

  28946. .................................

  28947. 

  28948. When executing the 'guile' command, Guile exceptions uncaught within the

  28949. Guile code are translated to calls to the GDB error-reporting mechanism.

  28950. If the command that called 'guile' does not handle the error, GDB will

  28951. terminate it and report the error according to the setting of the 'guile

  28952. print-stack' parameter.

  28953. 

  28954.    The 'guile print-stack' parameter has three settings:

  28955. 

  28956. 'none'

  28957.      Nothing is printed.

  28958. 

  28959. 'message'

  28960.      An error message is printed containing the Guile exception name,

  28961.      the associated value, and the Guile call stack backtrace at the

  28962.      point where the exception was raised.  Example:

  28963. 

  28964.           (gdb) guile (display foo)

  28965.           ERROR: In procedure memoize-variable-access!:

  28966.           ERROR: Unbound variable: foo

  28967.           Error while executing Scheme code.

  28968. 

  28969. 'full'

  28970.      In addition to an error message a full backtrace is printed.

  28971. 

  28972.           (gdb) set guile print-stack full

  28973.           (gdb) guile (display foo)

  28974.           Guile Backtrace:

  28975.           In ice-9/boot-9.scm:

  28976.            157: 10 [catch #t #<catch-closure 2c76e20> ...]

  28977.           In unknown file:

  28978.              ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]

  28979.           In ice-9/boot-9.scm:

  28980.            157: 8 [catch #t #<catch-closure 2c76d20> ...]

  28981.           In unknown file:

  28982.              ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]

  28983.              ?: 6 [call-with-input-string "(display foo)" ...]

  28984.           In ice-9/boot-9.scm:

  28985.           2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]

  28986.           In ice-9/eval-string.scm:

  28987.             44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]

  28988.             37: 3 [lp (display foo)]

  28989.           In ice-9/eval.scm:

  28990.            387: 2 [eval # ()]

  28991.            393: 1 [eval #<memoized foo> ()]

  28992.           In unknown file:

  28993.              ?: 0 [memoize-variable-access! #<memoized foo> ...]

  28994. 

  28995.           ERROR: In procedure memoize-variable-access!:

  28996.           ERROR: Unbound variable: foo

  28997.           Error while executing Scheme code.

  28998. 

  28999.    GDB errors that happen in GDB commands invoked by Guile code are

  29000. converted to Guile exceptions.  The type of the Guile exception depends

  29001. on the error.

  29002. 

  29003.    Guile procedures provided by GDB can throw the standard Guile

  29004. exceptions like 'wrong-type-arg' and 'out-of-range'.

  29005. 

  29006.    User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is

  29007. translated to a Guile 'signal' exception with value 'SIGINT'.

  29008. 

  29009.    GDB Guile procedures can also throw these exceptions:

  29010. 

  29011. 'gdb:error'

  29012.      This exception is a catch-all for errors generated from within GDB.

  29013. 

  29014. 'gdb:invalid-object'

  29015.      This exception is thrown when accessing Guile objects that wrap

  29016.      underlying GDB objects have become invalid.  For example, a

  29017.      '<gdb:breakpoint>' object becomes invalid if the user deletes it

  29018.      from the command line.  The object still exists in Guile, but the

  29019.      object it represents is gone.  Further operations on this

  29020.      breakpoint will throw this exception.

  29021. 

  29022. 'gdb:memory-error'

  29023.      This exception is thrown when an operation tried to access invalid

  29024.      memory in the inferior.

  29025. 

  29026. 'gdb:pp-type-error'

  29027.      This exception is thrown when a Guile pretty-printer passes a bad

  29028.      object to GDB.

  29029. 

  29030.    The following exception-related procedures are provided by the

  29031. '(gdb)' module.

  29032. 

  29033.  -- Scheme Procedure: make-exception key args

  29034.      Return a '<gdb:exception>' object given by its KEY and ARGS, which

  29035.      are the standard Guile parameters of an exception.  See the Guile

  29036.      documentation for more information (*note (guile)Exceptions::).

  29037. 

  29038.  -- Scheme Procedure: exception? object

  29039.      Return '#t' if OBJECT is a '<gdb:exception>' object.  Otherwise

  29040.      return '#f'.

  29041. 

  29042.  -- Scheme Procedure: exception-key exception

  29043.      Return the ARGS field of a '<gdb:exception>' object.

  29044. 

  29045.  -- Scheme Procedure: exception-args exception

  29046.      Return the ARGS field of a '<gdb:exception>' object.

  29047. 

  29048. 

  29049. File: gdb.info,  Node: Values From Inferior In Guile,  Next: Arithmetic In Guile,  Prev: Guile Exception Handling,  Up: Guile API

  29050. 

  29051. 23.3.3.5 Values From Inferior In Guile

  29052. ......................................

  29053. 

  29054. GDB provides values it obtains from the inferior program in an object of

  29055. type '<gdb:value>'.  GDB uses this object for its internal bookkeeping

  29056. of the inferior's values, and for fetching values when necessary.

  29057. 

  29058.    GDB does not memoize '<gdb:value>' objects.  'make-value' always

  29059. returns a fresh object.

  29060. 

  29061.      (gdb) guile (eq? (make-value 1) (make-value 1))

  29062.      $1 = #f

  29063.      (gdb) guile (equal? (make-value 1) (make-value 1))

  29064.      $1 = #t

  29065. 

  29066.    A '<gdb:value>' that represents a function can be executed via

  29067. inferior function call with 'value-call'.  Any arguments provided to the

  29068. call must match the function's prototype, and must be provided in the

  29069. order specified by that prototype.

  29070. 

  29071.    For example, 'some-val' is a '<gdb:value>' instance representing a

  29072. function that takes two integers as arguments.  To execute this

  29073. function, call it like so:

  29074. 

  29075.      (define result (value-call some-val 10 20))

  29076. 

  29077.    Any values returned from a function call are '<gdb:value>' objects.

  29078. 

  29079.    Note: Unlike Python scripting in GDB, inferior values that are simple

  29080. scalars cannot be used directly in Scheme expressions that are valid for

  29081. the value's data type.  For example, '(+ (parse-and-eval "int_variable")

  29082. 2)' does not work.  And inferior values that are structures or instances

  29083. of some class cannot be accessed using any special syntax, instead

  29084. 'value-field' must be used.

  29085. 

  29086.    The following value-related procedures are provided by the '(gdb)'

  29087. module.

  29088. 

  29089.  -- Scheme Procedure: value? object

  29090.      Return '#t' if OBJECT is a '<gdb:value>' object.  Otherwise return

  29091.      '#f'.

  29092. 

  29093.  -- Scheme Procedure: make-value value [#:type type]

  29094.      Many Scheme values can be converted directly to a '<gdb:value>'

  29095.      with this procedure.  If TYPE is specified, the result is a value

  29096.      of this type, and if VALUE can't be represented with this type an

  29097.      exception is thrown.  Otherwise the type of the result is

  29098.      determined from VALUE as described below.

  29099. 

  29100.      *Note Architectures In Guile::, for a list of the builtin types for

  29101.      an architecture.

  29102. 

  29103.      Here's how Scheme values are converted when TYPE argument to

  29104.      'make-value' is not specified:

  29105. 

  29106.      Scheme boolean

  29107.           A Scheme boolean is converted the boolean type for the current

  29108.           language.

  29109. 

  29110.      Scheme integer

  29111.           A Scheme integer is converted to the first of a C 'int',

  29112.           'unsigned int', 'long', 'unsigned long', 'long long' or

  29113.           'unsigned long long' type for the current architecture that

  29114.           can represent the value.

  29115. 

  29116.           If the Scheme integer cannot be represented as a target

  29117.           integer an 'out-of-range' exception is thrown.

  29118. 

  29119.      Scheme real

  29120.           A Scheme real is converted to the C 'double' type for the

  29121.           current architecture.

  29122. 

  29123.      Scheme string

  29124.           A Scheme string is converted to a string in the current target

  29125.           language using the current target encoding.  Characters that

  29126.           cannot be represented in the current target encoding are

  29127.           replaced with the corresponding escape sequence.  This is

  29128.           Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion

  29129.           strategy (*note (guile)Strings::).

  29130. 

  29131.           Passing TYPE is not supported in this case, if it is provided

  29132.           a 'wrong-type-arg' exception is thrown.

  29133. 

  29134.      '<gdb:lazy-string>'

  29135.           If VALUE is a '<gdb:lazy-string>' object (*note Lazy Strings

  29136.           In Guile::), then the 'lazy-string->value' procedure is

  29137.           called, and its result is used.

  29138. 

  29139.           Passing TYPE is not supported in this case, if it is provided

  29140.           a 'wrong-type-arg' exception is thrown.

  29141. 

  29142.      Scheme bytevector

  29143.           If VALUE is a Scheme bytevector and TYPE is provided, VALUE

  29144.           must be the same size, in bytes, of values of type TYPE, and

  29145.           the result is essentially created by using 'memcpy'.

  29146. 

  29147.           If VALUE is a Scheme bytevector and TYPE is not provided, the

  29148.           result is an array of type 'uint8' of the same length.

  29149. 

  29150.  -- Scheme Procedure: value-optimized-out? value

  29151.      Return '#t' if the compiler optimized out VALUE, thus it is not

  29152.      available for fetching from the inferior.  Otherwise return '#f'.

  29153. 

  29154.  -- Scheme Procedure: value-address value

  29155.      If VALUE is addressable, returns a '<gdb:value>' object

  29156.      representing the address.  Otherwise, '#f' is returned.

  29157. 

  29158.  -- Scheme Procedure: value-type value

  29159.      Return the type of VALUE as a '<gdb:type>' object (*note Types In

  29160.      Guile::).

  29161. 

  29162.  -- Scheme Procedure: value-dynamic-type value

  29163.      Return the dynamic type of VALUE.  This uses C++ run-time type

  29164.      information (RTTI) to determine the dynamic type of the value.  If

  29165.      the value is of class type, it will return the class in which the

  29166.      value is embedded, if any.  If the value is of pointer or reference

  29167.      to a class type, it will compute the dynamic type of the referenced

  29168.      object, and return a pointer or reference to that type,

  29169.      respectively.  In all other cases, it will return the value's

  29170.      static type.

  29171. 

  29172.      Note that this feature will only work when debugging a C++ program

  29173.      that includes RTTI for the object in question.  Otherwise, it will

  29174.      just return the static type of the value as in 'ptype foo'.  *Note

  29175.      ptype: Symbols.

  29176. 

  29177.  -- Scheme Procedure: value-cast value type

  29178.      Return a new instance of '<gdb:value>' that is the result of

  29179.      casting VALUE to the type described by TYPE, which must be a

  29180.      '<gdb:type>' object.  If the cast cannot be performed for some

  29181.      reason, this method throws an exception.

  29182. 

  29183.  -- Scheme Procedure: value-dynamic-cast value type

  29184.      Like 'value-cast', but works as if the C++ 'dynamic_cast' operator

  29185.      were used.  Consult a C++ reference for details.

  29186. 

  29187.  -- Scheme Procedure: value-reinterpret-cast value type

  29188.      Like 'value-cast', but works as if the C++ 'reinterpret_cast'

  29189.      operator were used.  Consult a C++ reference for details.

  29190. 

  29191.  -- Scheme Procedure: value-dereference value

  29192.      For pointer data types, this method returns a new '<gdb:value>'

  29193.      object whose contents is the object pointed to by VALUE.  For

  29194.      example, if 'foo' is a C pointer to an 'int', declared in your C

  29195.      program as

  29196. 

  29197.           int *foo;

  29198. 

  29199.      then you can use the corresponding '<gdb:value>' to access what

  29200.      'foo' points to like this:

  29201. 

  29202.           (define bar (value-dereference foo))

  29203. 

  29204.      The result 'bar' will be a '<gdb:value>' object holding the value

  29205.      pointed to by 'foo'.

  29206. 

  29207.      A similar function 'value-referenced-value' exists which also

  29208.      returns '<gdb:value>' objects corresponding to the values pointed

  29209.      to by pointer values (and additionally, values referenced by

  29210.      reference values).  However, the behavior of 'value-dereference'

  29211.      differs from 'value-referenced-value' by the fact that the behavior

  29212.      of 'value-dereference' is identical to applying the C unary

  29213.      operator '*' on a given value.  For example, consider a reference

  29214.      to a pointer 'ptrref', declared in your C++ program as

  29215. 

  29216.           typedef int *intptr;

  29217.           ...

  29218.           int val = 10;

  29219.           intptr ptr = &val;

  29220.           intptr &ptrref = ptr;

  29221. 

  29222.      Though 'ptrref' is a reference value, one can apply the method

  29223.      'value-dereference' to the '<gdb:value>' object corresponding to it

  29224.      and obtain a '<gdb:value>' which is identical to that corresponding

  29225.      to 'val'.  However, if you apply the method

  29226.      'value-referenced-value', the result would be a '<gdb:value>'

  29227.      object identical to that corresponding to 'ptr'.

  29228. 

  29229.           (define scm-ptrref (parse-and-eval "ptrref"))

  29230.           (define scm-val (value-dereference scm-ptrref))

  29231.           (define scm-ptr (value-referenced-value scm-ptrref))

  29232. 

  29233.      The '<gdb:value>' object 'scm-val' is identical to that

  29234.      corresponding to 'val', and 'scm-ptr' is identical to that

  29235.      corresponding to 'ptr'.  In general, 'value-dereference' can be

  29236.      applied whenever the C unary operator '*' can be applied to the

  29237.      corresponding C value.  For those cases where applying both

  29238.      'value-dereference' and 'value-referenced-value' is allowed, the

  29239.      results obtained need not be identical (as we have seen in the

  29240.      above example).  The results are however identical when applied on

  29241.      '<gdb:value>' objects corresponding to pointers ('<gdb:value>'

  29242.      objects with type code 'TYPE_CODE_PTR') in a C/C++ program.

  29243. 

  29244.  -- Scheme Procedure: value-referenced-value value

  29245.      For pointer or reference data types, this method returns a new

  29246.      '<gdb:value>' object corresponding to the value referenced by the

  29247.      pointer/reference value.  For pointer data types,

  29248.      'value-dereference' and 'value-referenced-value' produce identical

  29249.      results.  The difference between these methods is that

  29250.      'value-dereference' cannot get the values referenced by reference

  29251.      values.  For example, consider a reference to an 'int', declared in

  29252.      your C++ program as

  29253. 

  29254.           int val = 10;

  29255.           int &ref = val;

  29256. 

  29257.      then applying 'value-dereference' to the '<gdb:value>' object

  29258.      corresponding to 'ref' will result in an error, while applying

  29259.      'value-referenced-value' will result in a '<gdb:value>' object

  29260.      identical to that corresponding to 'val'.

  29261. 

  29262.           (define scm-ref (parse-and-eval "ref"))

  29263.           (define err-ref (value-dereference scm-ref))      ;; error

  29264.           (define scm-val (value-referenced-value scm-ref)) ;; ok

  29265. 

  29266.      The '<gdb:value>' object 'scm-val' is identical to that

  29267.      corresponding to 'val'.

  29268. 

  29269.  -- Scheme Procedure: value-field value field-name

  29270.      Return field FIELD-NAME from '<gdb:value>' object VALUE.

  29271. 

  29272.  -- Scheme Procedure: value-subscript value index

  29273.      Return the value of array VALUE at index INDEX.  The VALUE argument

  29274.      must be a subscriptable '<gdb:value>' object.

  29275. 

  29276.  -- Scheme Procedure: value-call value arg-list

  29277.      Perform an inferior function call, taking VALUE as a pointer to the

  29278.      function to call.  Each element of list ARG-LIST must be a

  29279.      <gdb:value> object or an object that can be converted to a value.

  29280.      The result is the value returned by the function.

  29281. 

  29282.  -- Scheme Procedure: value->bool value

  29283.      Return the Scheme boolean representing '<gdb:value>' VALUE.  The

  29284.      value must be "integer like".  Pointers are ok.

  29285. 

  29286.  -- Scheme Procedure: value->integer

  29287.      Return the Scheme integer representing '<gdb:value>' VALUE.  The

  29288.      value must be "integer like".  Pointers are ok.

  29289. 

  29290.  -- Scheme Procedure: value->real

  29291.      Return the Scheme real number representing '<gdb:value>' VALUE.

  29292.      The value must be a number.

  29293. 

  29294.  -- Scheme Procedure: value->bytevector

  29295.      Return a Scheme bytevector with the raw contents of '<gdb:value>'

  29296.      VALUE.  No transformation, endian or otherwise, is performed.

  29297. 

  29298.  -- Scheme Procedure: value->string value [#:encoding encoding]

  29299.           [#:errors errors] [#:length length]

  29300.      If VALUE> represents a string, then this method converts the

  29301.      contents to a Guile string.  Otherwise, this method will throw an

  29302.      exception.

  29303. 

  29304.      Values are interpreted as strings according to the rules of the

  29305.      current language.  If the optional length argument is given, the

  29306.      string will be converted to that length, and will include any

  29307.      embedded zeroes that the string may contain.  Otherwise, for

  29308.      languages where the string is zero-terminated, the entire string

  29309.      will be converted.

  29310. 

  29311.      For example, in C-like languages, a value is a string if it is a

  29312.      pointer to or an array of characters or ints of type 'wchar_t',

  29313.      'char16_t', or 'char32_t'.

  29314. 

  29315.      If the optional ENCODING argument is given, it must be a string

  29316.      naming the encoding of the string in the '<gdb:value>', such as

  29317.      '"ascii"', '"iso-8859-6"' or '"utf-8"'.  It accepts the same

  29318.      encodings as the corresponding argument to Guile's

  29319.      'scm_from_stringn' function, and the Guile codec machinery will be

  29320.      used to convert the string.  If ENCODING is not given, or if

  29321.      ENCODING is the empty string, then either the 'target-charset'

  29322.      (*note Character Sets::) will be used, or a language-specific

  29323.      encoding will be used, if the current language is able to supply

  29324.      one.

  29325. 

  29326.      The optional ERRORS argument is one of '#f', 'error' or

  29327.      'substitute'.  'error' and 'substitute' must be symbols.  If ERRORS

  29328.      is not specified, or if its value is '#f', then the default

  29329.      conversion strategy is used, which is set with the Scheme function

  29330.      'set-port-conversion-strategy!'.  If the value is ''error' then an

  29331.      exception is thrown if there is any conversion error.  If the value

  29332.      is ''substitute' then any conversion error is replaced with

  29333.      question marks.  *Note (guile)Strings::.

  29334. 

  29335.      If the optional LENGTH argument is given, the string will be

  29336.      fetched and converted to the given length.  The length must be a

  29337.      Scheme integer and not a '<gdb:value>' integer.

  29338. 

  29339.  -- Scheme Procedure: value->lazy-string value [#:encoding encoding]

  29340.           [#:length length]

  29341.      If this '<gdb:value>' represents a string, then this method

  29342.      converts VALUE to a '<gdb:lazy-string' (*note Lazy Strings In

  29343.      Guile::).  Otherwise, this method will throw an exception.

  29344. 

  29345.      If the optional ENCODING argument is given, it must be a string

  29346.      naming the encoding of the '<gdb:lazy-string'.  Some examples are:

  29347.      '"ascii"', '"iso-8859-6"' or '"utf-8"'.  If the ENCODING argument

  29348.      is an encoding that GDB does not recognize, GDB will raise an

  29349.      error.

  29350. 

  29351.      When a lazy string is printed, the GDB encoding machinery is used

  29352.      to convert the string during printing.  If the optional ENCODING

  29353.      argument is not provided, or is an empty string, GDB will

  29354.      automatically select the encoding most suitable for the string

  29355.      type.  For further information on encoding in GDB please see *note

  29356.      Character Sets::.

  29357. 

  29358.      If the optional LENGTH argument is given, the string will be

  29359.      fetched and encoded to the length of characters specified.  If the

  29360.      LENGTH argument is not provided, the string will be fetched and

  29361.      encoded until a null of appropriate width is found.  The length

  29362.      must be a Scheme integer and not a '<gdb:value>' integer.

  29363. 

  29364.  -- Scheme Procedure: value-lazy? value

  29365.      Return '#t' if VALUE has not yet been fetched from the inferior.

  29366.      Otherwise return '#f'.  GDB does not fetch values until necessary,

  29367.      for efficiency.  For example:

  29368. 

  29369.           (define myval (parse-and-eval "somevar"))

  29370. 

  29371.      The value of 'somevar' is not fetched at this time.  It will be

  29372.      fetched when the value is needed, or when the 'fetch-lazy'

  29373.      procedure is invoked.

  29374. 

  29375.  -- Scheme Procedure: make-lazy-value type address

  29376.      Return a '<gdb:value>' that will be lazily fetched from the target.

  29377.      The object of type '<gdb:type>' whose value to fetch is specified

  29378.      by its TYPE and its target memory ADDRESS, which is a Scheme

  29379.      integer.

  29380. 

  29381.  -- Scheme Procedure: value-fetch-lazy! value

  29382.      If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the

  29383.      value is fetched from the inferior.  Any errors that occur in the

  29384.      process will produce a Guile exception.

  29385. 

  29386.      If VALUE is not a lazy value, this method has no effect.

  29387. 

  29388.      The result of this function is unspecified.

  29389. 

  29390.  -- Scheme Procedure: value-print value

  29391.      Return the string representation (print form) of '<gdb:value>'

  29392.      VALUE.

  29393. 

  29394. 

  29395. File: gdb.info,  Node: Arithmetic In Guile,  Next: Types In Guile,  Prev: Values From Inferior In Guile,  Up: Guile API

  29396. 

  29397. 23.3.3.6 Arithmetic In Guile

  29398. ............................

  29399. 

  29400. The '(gdb)' module provides several functions for performing arithmetic

  29401. on '<gdb:value>' objects.  The arithmetic is performed as if it were

  29402. done by the target, and therefore has target semantics which are not

  29403. necessarily those of Scheme.  For example operations work with a fixed

  29404. precision, not the arbitrary precision of Scheme.

  29405. 

  29406.    Wherever a function takes an integer or pointer as an operand, GDB

  29407. will convert appropriate Scheme values to perform the operation.

  29408. 

  29409.  -- Scheme Procedure: value-add a b

  29410. 

  29411.  -- Scheme Procedure: value-sub a b

  29412. 

  29413.  -- Scheme Procedure: value-mul a b

  29414. 

  29415.  -- Scheme Procedure: value-div a b

  29416. 

  29417.  -- Scheme Procedure: value-rem a b

  29418. 

  29419.  -- Scheme Procedure: value-mod a b

  29420. 

  29421.  -- Scheme Procedure: value-pow a b

  29422. 

  29423.  -- Scheme Procedure: value-not a

  29424. 

  29425.  -- Scheme Procedure: value-neg a

  29426. 

  29427.  -- Scheme Procedure: value-pos a

  29428. 

  29429.  -- Scheme Procedure: value-abs a

  29430. 

  29431.  -- Scheme Procedure: value-lsh a b

  29432. 

  29433.  -- Scheme Procedure: value-rsh a b

  29434. 

  29435.  -- Scheme Procedure: value-min a b

  29436. 

  29437.  -- Scheme Procedure: value-max a b

  29438. 

  29439.  -- Scheme Procedure: value-lognot a

  29440. 

  29441.  -- Scheme Procedure: value-logand a b

  29442. 

  29443.  -- Scheme Procedure: value-logior a b

  29444. 

  29445.  -- Scheme Procedure: value-logxor a b

  29446. 

  29447.  -- Scheme Procedure: value=? a b

  29448. 

  29449.  -- Scheme Procedure: value<? a b

  29450. 

  29451.  -- Scheme Procedure: value<=? a b

  29452. 

  29453.  -- Scheme Procedure: value>? a b

  29454. 

  29455.  -- Scheme Procedure: value>=? a b

  29456. 

  29457.    Scheme does not provide a 'not-equal' function, and thus Guile

  29458. support in GDB does not either.

  29459. 

  29460. 

  29461. File: gdb.info,  Node: Types In Guile,  Next: Guile Pretty Printing API,  Prev: Arithmetic In Guile,  Up: Guile API

  29462. 

  29463. 23.3.3.7 Types In Guile

  29464. .......................

  29465. 

  29466. GDB represents types from the inferior in objects of type '<gdb:type>'.

  29467. 

  29468.    The following type-related procedures are provided by the '(gdb)'

  29469. module.

  29470. 

  29471.  -- Scheme Procedure: type? object

  29472.      Return '#t' if OBJECT is an object of type '<gdb:type>'.  Otherwise

  29473.      return '#f'.

  29474. 

  29475.  -- Scheme Procedure: lookup-type name [#:block block]

  29476.      This function looks up a type by its NAME, which must be a string.

  29477. 

  29478.      If BLOCK is given, it is an object of type '<gdb:block>', and NAME

  29479.      is looked up in that scope.  Otherwise, it is searched for

  29480.      globally.

  29481. 

  29482.      Ordinarily, this function will return an instance of '<gdb:type>'.

  29483.      If the named type cannot be found, it will throw an exception.

  29484. 

  29485.  -- Scheme Procedure: type-code type

  29486.      Return the type code of TYPE.  The type code will be one of the

  29487.      'TYPE_CODE_' constants defined below.

  29488. 

  29489.  -- Scheme Procedure: type-tag type

  29490.      Return the tag name of TYPE.  The tag name is the name after

  29491.      'struct', 'union', or 'enum' in C and C++; not all languages have

  29492.      this concept.  If this type has no tag name, then '#f' is returned.

  29493. 

  29494.  -- Scheme Procedure: type-name type

  29495.      Return the name of TYPE.  If this type has no name, then '#f' is

  29496.      returned.

  29497. 

  29498.  -- Scheme Procedure: type-print-name type

  29499.      Return the print name of TYPE.  This returns something even for

  29500.      anonymous types.  For example, for an anonymous C struct '"struct

  29501.      {...}"' is returned.

  29502. 

  29503.  -- Scheme Procedure: type-sizeof type

  29504.      Return the size of this type, in target 'char' units.  Usually, a

  29505.      target's 'char' type will be an 8-bit byte.  However, on some

  29506.      unusual platforms, this type may have a different size.

  29507. 

  29508.  -- Scheme Procedure: type-strip-typedefs type

  29509.      Return a new '<gdb:type>' that represents the real type of TYPE,

  29510.      after removing all layers of typedefs.

  29511. 

  29512.  -- Scheme Procedure: type-array type n1 [n2]

  29513.      Return a new '<gdb:type>' object which represents an array of this

  29514.      type.  If one argument is given, it is the inclusive upper bound of

  29515.      the array; in this case the lower bound is zero.  If two arguments

  29516.      are given, the first argument is the lower bound of the array, and

  29517.      the second argument is the upper bound of the array.  An array's

  29518.      length must not be negative, but the bounds can be.

  29519. 

  29520.  -- Scheme Procedure: type-vector type n1 [n2]

  29521.      Return a new '<gdb:type>' object which represents a vector of this

  29522.      type.  If one argument is given, it is the inclusive upper bound of

  29523.      the vector; in this case the lower bound is zero.  If two arguments

  29524.      are given, the first argument is the lower bound of the vector, and

  29525.      the second argument is the upper bound of the vector.  A vector's

  29526.      length must not be negative, but the bounds can be.

  29527. 

  29528.      The difference between an 'array' and a 'vector' is that arrays

  29529.      behave like in C: when used in expressions they decay to a pointer

  29530.      to the first element whereas vectors are treated as first class

  29531.      values.

  29532. 

  29533.  -- Scheme Procedure: type-pointer type

  29534.      Return a new '<gdb:type>' object which represents a pointer to

  29535.      TYPE.

  29536. 

  29537.  -- Scheme Procedure: type-range type

  29538.      Return a list of two elements: the low bound and high bound of

  29539.      TYPE.  If TYPE does not have a range, an exception is thrown.

  29540. 

  29541.  -- Scheme Procedure: type-reference type

  29542.      Return a new '<gdb:type>' object which represents a reference to

  29543.      TYPE.

  29544. 

  29545.  -- Scheme Procedure: type-target type

  29546.      Return a new '<gdb:type>' object which represents the target type

  29547.      of TYPE.

  29548. 

  29549.      For a pointer type, the target type is the type of the pointed-to

  29550.      object.  For an array type (meaning C-like arrays), the target type

  29551.      is the type of the elements of the array.  For a function or method

  29552.      type, the target type is the type of the return value.  For a

  29553.      complex type, the target type is the type of the elements.  For a

  29554.      typedef, the target type is the aliased type.

  29555. 

  29556.      If the type does not have a target, this method will throw an

  29557.      exception.

  29558. 

  29559.  -- Scheme Procedure: type-const type

  29560.      Return a new '<gdb:type>' object which represents a

  29561.      'const'-qualified variant of TYPE.

  29562. 

  29563.  -- Scheme Procedure: type-volatile type

  29564.      Return a new '<gdb:type>' object which represents a

  29565.      'volatile'-qualified variant of TYPE.

  29566. 

  29567.  -- Scheme Procedure: type-unqualified type

  29568.      Return a new '<gdb:type>' object which represents an unqualified

  29569.      variant of TYPE.  That is, the result is neither 'const' nor

  29570.      'volatile'.

  29571. 

  29572.  -- Scheme Procedure: type-num-fields

  29573.      Return the number of fields of '<gdb:type>' TYPE.

  29574. 

  29575.  -- Scheme Procedure: type-fields type

  29576.      Return the fields of TYPE as a list.  For structure and union

  29577.      types, 'fields' has the usual meaning.  Range types have two

  29578.      fields, the minimum and maximum values.  Enum types have one field

  29579.      per enum constant.  Function and method types have one field per

  29580.      parameter.  The base types of C++ classes are also represented as

  29581.      fields.  If the type has no fields, or does not fit into one of

  29582.      these categories, an empty list will be returned.  *Note Fields of

  29583.      a type in Guile::.

  29584. 

  29585.  -- Scheme Procedure: make-field-iterator type

  29586.      Return the fields of TYPE as a <gdb:iterator> object.  *Note

  29587.      Iterators In Guile::.

  29588. 

  29589.  -- Scheme Procedure: type-field type field-name

  29590.      Return field named FIELD-NAME in TYPE.  The result is an object of

  29591.      type '<gdb:field>'.  *Note Fields of a type in Guile::.  If the

  29592.      type does not have fields, or FIELD-NAME is not a field of TYPE, an

  29593.      exception is thrown.

  29594. 

  29595.      For example, if 'some-type' is a '<gdb:type>' instance holding a

  29596.      structure type, you can access its 'foo' field with:

  29597. 

  29598.           (define bar (type-field some-type "foo"))

  29599. 

  29600.      'bar' will be a '<gdb:field>' object.

  29601. 

  29602.  -- Scheme Procedure: type-has-field? type name

  29603.      Return '#t' if '<gdb:type>' TYPE has field named NAME.  Otherwise

  29604.      return '#f'.

  29605. 

  29606.    Each type has a code, which indicates what category this type falls

  29607. into.  The available type categories are represented by constants

  29608. defined in the '(gdb)' module:

  29609. 

  29610. 'TYPE_CODE_PTR'

  29611.      The type is a pointer.

  29612. 

  29613. 'TYPE_CODE_ARRAY'

  29614.      The type is an array.

  29615. 

  29616. 'TYPE_CODE_STRUCT'

  29617.      The type is a structure.

  29618. 

  29619. 'TYPE_CODE_UNION'

  29620.      The type is a union.

  29621. 

  29622. 'TYPE_CODE_ENUM'

  29623.      The type is an enum.

  29624. 

  29625. 'TYPE_CODE_FLAGS'

  29626.      A bit flags type, used for things such as status registers.

  29627. 

  29628. 'TYPE_CODE_FUNC'

  29629.      The type is a function.

  29630. 

  29631. 'TYPE_CODE_INT'

  29632.      The type is an integer type.

  29633. 

  29634. 'TYPE_CODE_FLT'

  29635.      A floating point type.

  29636. 

  29637. 'TYPE_CODE_VOID'

  29638.      The special type 'void'.

  29639. 

  29640. 'TYPE_CODE_SET'

  29641.      A Pascal set type.

  29642. 

  29643. 'TYPE_CODE_RANGE'

  29644.      A range type, that is, an integer type with bounds.

  29645. 

  29646. 'TYPE_CODE_STRING'

  29647.      A string type.  Note that this is only used for certain languages

  29648.      with language-defined string types; C strings are not represented

  29649.      this way.

  29650. 

  29651. 'TYPE_CODE_BITSTRING'

  29652.      A string of bits.  It is deprecated.

  29653. 

  29654. 'TYPE_CODE_ERROR'

  29655.      An unknown or erroneous type.

  29656. 

  29657. 'TYPE_CODE_METHOD'

  29658.      A method type, as found in C++.

  29659. 

  29660. 'TYPE_CODE_METHODPTR'

  29661.      A pointer-to-member-function.

  29662. 

  29663. 'TYPE_CODE_MEMBERPTR'

  29664.      A pointer-to-member.

  29665. 

  29666. 'TYPE_CODE_REF'

  29667.      A reference type.

  29668. 

  29669. 'TYPE_CODE_CHAR'

  29670.      A character type.

  29671. 

  29672. 'TYPE_CODE_BOOL'

  29673.      A boolean type.

  29674. 

  29675. 'TYPE_CODE_COMPLEX'

  29676.      A complex float type.

  29677. 

  29678. 'TYPE_CODE_TYPEDEF'

  29679.      A typedef to some other type.

  29680. 

  29681. 'TYPE_CODE_NAMESPACE'

  29682.      A C++ namespace.

  29683. 

  29684. 'TYPE_CODE_DECFLOAT'

  29685.      A decimal floating point type.

  29686. 

  29687. 'TYPE_CODE_INTERNAL_FUNCTION'

  29688.      A function internal to GDB.  This is the type used to represent

  29689.      convenience functions (*note Convenience Funs::).

  29690. 

  29691.    Further support for types is provided in the '(gdb types)' Guile

  29692. module (*note Guile Types Module::).

  29693. 

  29694.    Each field is represented as an object of type '<gdb:field>'.

  29695. 

  29696.    The following field-related procedures are provided by the '(gdb)'

  29697. module:

  29698. 

  29699.  -- Scheme Procedure: field? object

  29700.      Return '#t' if OBJECT is an object of type '<gdb:field>'.

  29701.      Otherwise return '#f'.

  29702. 

  29703.  -- Scheme Procedure: field-name field

  29704.      Return the name of the field, or '#f' for anonymous fields.

  29705. 

  29706.  -- Scheme Procedure: field-type field

  29707.      Return the type of the field.  This is usually an instance of

  29708.      '<gdb:type>', but it can be '#f' in some situations.

  29709. 

  29710.  -- Scheme Procedure: field-enumval field

  29711.      Return the enum value represented by '<gdb:field>' FIELD.

  29712. 

  29713.  -- Scheme Procedure: field-bitpos field

  29714.      Return the bit position of '<gdb:field>' FIELD.  This attribute is

  29715.      not available for 'static' fields (as in C++).

  29716. 

  29717.  -- Scheme Procedure: field-bitsize field

  29718.      If the field is packed, or is a bitfield, return the size of

  29719.      '<gdb:field>' FIELD in bits.  Otherwise, zero is returned; in which

  29720.      case the field's size is given by its type.

  29721. 

  29722.  -- Scheme Procedure: field-artificial? field

  29723.      Return '#t' if the field is artificial, usually meaning that it was

  29724.      provided by the compiler and not the user.  Otherwise return '#f'.

  29725. 

  29726.  -- Scheme Procedure: field-base-class? field

  29727.      Return '#t' if the field represents a base class of a C++

  29728.      structure.  Otherwise return '#f'.

  29729. 

  29730. 

  29731. File: gdb.info,  Node: Guile Pretty Printing API,  Next: Selecting Guile Pretty-Printers,  Prev: Types In Guile,  Up: Guile API

  29732. 

  29733. 23.3.3.8 Guile Pretty Printing API

  29734. ..................................

  29735. 

  29736. An example output is provided (*note Pretty Printing::).

  29737. 

  29738.    A pretty-printer is represented by an object of type

  29739. <gdb:pretty-printer>.  Pretty-printer objects are created with

  29740. 'make-pretty-printer'.

  29741. 

  29742.    The following pretty-printer-related procedures are provided by the

  29743. '(gdb)' module:

  29744. 

  29745.  -- Scheme Procedure: make-pretty-printer name lookup-function

  29746.      Return a '<gdb:pretty-printer>' object named NAME.

  29747. 

  29748.      LOOKUP-FUNCTION is a function of one parameter: the value to be

  29749.      printed.  If the value is handled by this pretty-printer, then

  29750.      LOOKUP-FUNCTION returns an object of type

  29751.      <gdb:pretty-printer-worker> to perform the actual pretty-printing.

  29752.      Otherwise LOOKUP-FUNCTION returns '#f'.

  29753. 

  29754.  -- Scheme Procedure: pretty-printer? object

  29755.      Return '#t' if OBJECT is a '<gdb:pretty-printer>' object.

  29756.      Otherwise return '#f'.

  29757. 

  29758.  -- Scheme Procedure: pretty-printer-enabled? pretty-printer

  29759.      Return '#t' if PRETTY-PRINTER is enabled.  Otherwise return '#f'.

  29760. 

  29761.  -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag

  29762.      Set the enabled flag of PRETTY-PRINTER to FLAG.  The value returned

  29763.      is unspecified.

  29764. 

  29765.  -- Scheme Procedure: pretty-printers

  29766.      Return the list of global pretty-printers.

  29767. 

  29768.  -- Scheme Procedure: set-pretty-printers! pretty-printers

  29769.      Set the list of global pretty-printers to PRETTY-PRINTERS.  The

  29770.      value returned is unspecified.

  29771. 

  29772.  -- Scheme Procedure: make-pretty-printer-worker display-hint to-string

  29773.           children

  29774.      Return an object of type '<gdb:pretty-printer-worker>'.

  29775. 

  29776.      This function takes three parameters:

  29777. 

  29778.      'display-hint'

  29779.           DISPLAY-HINT provides a hint to GDB or GDB front end via MI to

  29780.           change the formatting of the value being printed.  The value

  29781.           must be a string or '#f' (meaning there is no hint).  Several

  29782.           values for DISPLAY-HINT are predefined by GDB:

  29783. 

  29784.           'array'

  29785.                Indicate that the object being printed is "array-like".

  29786.                The CLI uses this to respect parameters such as 'set

  29787.                print elements' and 'set print array'.

  29788. 

  29789.           'map'

  29790.                Indicate that the object being printed is "map-like", and

  29791.                that the children of this value can be assumed to

  29792.                alternate between keys and values.

  29793. 

  29794.           'string'

  29795.                Indicate that the object being printed is "string-like".

  29796.                If the printer's 'to-string' function returns a Guile

  29797.                string of some kind, then GDB will call its internal

  29798.                language-specific string-printing function to format the

  29799.                string.  For the CLI this means adding quotation marks,

  29800.                possibly escaping some characters, respecting 'set print

  29801.                elements', and the like.

  29802. 

  29803.      'to-string'

  29804.           TO-STRING is either a function of one parameter, the

  29805.           '<gdb:pretty-printer-worker>' object, or '#f'.

  29806. 

  29807.           When printing from the CLI, if the 'to-string' method exists,

  29808.           then GDB will prepend its result to the values returned by

  29809.           'children'.  Exactly how this formatting is done is dependent

  29810.           on the display hint, and may change as more hints are added.

  29811.           Also, depending on the print settings (*note Print

  29812.           Settings::), the CLI may print just the result of 'to-string'

  29813.           in a stack trace, omitting the result of 'children'.

  29814. 

  29815.           If this method returns a string, it is printed verbatim.

  29816. 

  29817.           Otherwise, if this method returns an instance of

  29818.           '<gdb:value>', then GDB prints this value.  This may result in

  29819.           a call to another pretty-printer.

  29820. 

  29821.           If instead the method returns a Guile value which is

  29822.           convertible to a '<gdb:value>', then GDB performs the

  29823.           conversion and prints the resulting value.  Again, this may

  29824.           result in a call to another pretty-printer.  Guile scalars

  29825.           (integers, floats, and booleans) and strings are convertible

  29826.           to '<gdb:value>'; other types are not.

  29827. 

  29828.           Finally, if this method returns '#f' then no further

  29829.           operations are peformed in this method and nothing is printed.

  29830. 

  29831.           If the result is not one of these types, an exception is

  29832.           raised.

  29833. 

  29834.           TO-STRING may also be '#f' in which case it is left to

  29835.           CHILDREN to print the value.

  29836. 

  29837.      'children'

  29838.           CHILDREN is either a function of one parameter, the

  29839.           '<gdb:pretty-printer-worker>' object, or '#f'.

  29840. 

  29841.           GDB will call this function on a pretty-printer to compute the

  29842.           children of the pretty-printer's value.

  29843. 

  29844.           This function must return a <gdb:iterator> object.  Each item

  29845.           returned by the iterator must be a tuple holding two elements.

  29846.           The first element is the "name" of the child; the second

  29847.           element is the child's value.  The value can be any Guile

  29848.           object which is convertible to a GDB value.

  29849. 

  29850.           If CHILDREN is '#f', GDB will act as though the value has no

  29851.           children.

  29852. 

  29853.           Children may be hidden from display based on the value of 'set

  29854.           print max-depth' (*note Print Settings::).

  29855. 

  29856.    GDB provides a function which can be used to look up the default

  29857. pretty-printer for a '<gdb:value>':

  29858. 

  29859.  -- Scheme Procedure: default-visualizer value

  29860.      This function takes a '<gdb:value>' object as an argument.  If a

  29861.      pretty-printer for this value exists, then it is returned.  If no

  29862.      such printer exists, then this returns '#f'.

  29863. 

  29864. 

  29865. File: gdb.info,  Node: Selecting Guile Pretty-Printers,  Next: Writing a Guile Pretty-Printer,  Prev: Guile Pretty Printing API,  Up: Guile API

  29866. 

  29867. 23.3.3.9 Selecting Guile Pretty-Printers

  29868. ........................................

  29869. 

  29870. There are three sets of pretty-printers that GDB searches:

  29871. 

  29872.    * Per-objfile list of pretty-printers (*note Objfiles In Guile::).

  29873.    * Per-progspace list of pretty-printers (*note Progspaces In

  29874.      Guile::).

  29875.    * The global list of pretty-printers (*note Guile Pretty Printing

  29876.      API::).  These printers are available when debugging any inferior.

  29877. 

  29878.    Pretty-printer lookup is done by passing the value to be printed to

  29879. the lookup function of each enabled object in turn.  Lookup stops when a

  29880. lookup function returns a non-'#f' value or when the list is exhausted.

  29881. Lookup functions must return either a '<gdb:pretty-printer-worker>'

  29882. object or '#f'.  Otherwise an exception is thrown.

  29883. 

  29884.    GDB first checks the result of 'objfile-pretty-printers' of each

  29885. '<gdb:objfile>' in the current program space and iteratively calls each

  29886. enabled lookup function in the list for that '<gdb:objfile>' until a

  29887. non-'#f' object is returned.  If no pretty-printer is found in the

  29888. objfile lists, GDB then searches the result of

  29889. 'progspace-pretty-printers' of the current program space, calling each

  29890. enabled function until a non-'#f' object is returned.  After these lists

  29891. have been exhausted, it tries the global pretty-printers list, obtained

  29892. with 'pretty-printers', again calling each enabled function until a

  29893. non-'#f' object is returned.

  29894. 

  29895.    The order in which the objfiles are searched is not specified.  For a

  29896. given list, functions are always invoked from the head of the list, and

  29897. iterated over sequentially until the end of the list, or a

  29898. '<gdb:pretty-printer-worker>' object is returned.

  29899. 

  29900.    For various reasons a pretty-printer may not work.  For example, the

  29901. underlying data structure may have changed and the pretty-printer is out

  29902. of date.

  29903. 

  29904.    The consequences of a broken pretty-printer are severe enough that

  29905. GDB provides support for enabling and disabling individual printers.

  29906. For example, if 'print frame-arguments' is on, a backtrace can become

  29907. highly illegible if any argument is printed with a broken printer.

  29908. 

  29909.    Pretty-printers are enabled and disabled from Scheme by calling

  29910. 'set-pretty-printer-enabled!'.  *Note Guile Pretty Printing API::.

  29911. 

  29912. 

  29913. File: gdb.info,  Node: Writing a Guile Pretty-Printer,  Next: Commands In Guile,  Prev: Selecting Guile Pretty-Printers,  Up: Guile API

  29914. 

  29915. 23.3.3.10 Writing a Guile Pretty-Printer

  29916. ........................................

  29917. 

  29918. A pretty-printer consists of two basic parts: a lookup function to

  29919. determine if the type is supported, and the printer itself.

  29920. 

  29921.    Here is an example showing how a 'std::string' printer might be

  29922. written.  *Note Guile Pretty Printing API::, for details.

  29923. 

  29924.      (define (make-my-string-printer value)

  29925.        "Print a my::string string"

  29926.        (make-pretty-printer-worker

  29927.         "string"

  29928.         (lambda (printer)

  29929.           (value-field value "_data"))

  29930.         #f))

  29931. 

  29932.    And here is an example showing how a lookup function for the printer

  29933. example above might be written.

  29934. 

  29935.      (define (str-lookup-function pretty-printer value)

  29936.        (let ((tag (type-tag (value-type value))))

  29937.          (and tag

  29938.               (string-prefix? "std::string<" tag)

  29939.               (make-my-string-printer value))))

  29940. 

  29941.    Then to register this printer in the global printer list:

  29942. 

  29943.      (append-pretty-printer!

  29944.       (make-pretty-printer "my-string" str-lookup-function))

  29945. 

  29946.    The example lookup function extracts the value's type, and attempts

  29947. to match it to a type that it can pretty-print.  If it is a type the

  29948. printer can pretty-print, it will return a <gdb:pretty-printer-worker>

  29949. object.  If not, it returns '#f'.

  29950. 

  29951.    We recommend that you put your core pretty-printers into a Guile

  29952. package.  If your pretty-printers are for use with a library, we further

  29953. recommend embedding a version number into the package name.  This

  29954. practice will enable GDB to load multiple versions of your

  29955. pretty-printers at the same time, because they will have different

  29956. names.

  29957. 

  29958.    You should write auto-loaded code (*note Guile Auto-loading::) such

  29959. that it can be evaluated multiple times without changing its meaning.

  29960. An ideal auto-load file will consist solely of 'import's of your printer

  29961. modules, followed by a call to a register pretty-printers with the

  29962. current objfile.

  29963. 

  29964.    Taken as a whole, this approach will scale nicely to multiple

  29965. inferiors, each potentially using a different library version.

  29966. Embedding a version number in the Guile package name will ensure that

  29967. GDB is able to load both sets of printers simultaneously.  Then, because

  29968. the search for pretty-printers is done by objfile, and because your

  29969. auto-loaded code took care to register your library's printers with a

  29970. specific objfile, GDB will find the correct printers for the specific

  29971. version of the library used by each inferior.

  29972. 

  29973.    To continue the 'my::string' example, this code might appear in

  29974. '(my-project my-library v1)':

  29975. 

  29976.      (use-modules (gdb))

  29977.      (define (register-printers objfile)

  29978.        (append-objfile-pretty-printer!

  29979.         (make-pretty-printer "my-string" str-lookup-function)))

  29980. 

  29981. And then the corresponding contents of the auto-load file would be:

  29982. 

  29983.      (use-modules (gdb) (my-project my-library v1))

  29984.      (register-printers (current-objfile))

  29985. 

  29986.    The previous example illustrates a basic pretty-printer.  There are a

  29987. few things that can be improved on.  The printer only handles one type,

  29988. whereas a library typically has several types.  One could install a

  29989. lookup function for each desired type in the library, but one could also

  29990. have a single lookup function recognize several types.  The latter is

  29991. the conventional way this is handled.  If a pretty-printer can handle

  29992. multiple data types, then its "subprinters" are the printers for the

  29993. individual data types.

  29994. 

  29995.    The '(gdb printing)' module provides a formal way of solving this

  29996. problem (*note Guile Printing Module::).  Here is another example that

  29997. handles multiple types.

  29998. 

  29999.    These are the types we are going to pretty-print:

  30000. 

  30001.      struct foo { int a, b; };

  30002.      struct bar { struct foo x, y; };

  30003. 

  30004.    Here are the printers:

  30005. 

  30006.      (define (make-foo-printer value)

  30007.        "Print a foo object"

  30008.        (make-pretty-printer-worker

  30009.         "foo"

  30010.         (lambda (printer)

  30011.           (format #f "a=<~a> b=<~a>"

  30012.                   (value-field value "a") (value-field value "a")))

  30013.         #f))

  30014. 

  30015.      (define (make-bar-printer value)

  30016.        "Print a bar object"

  30017.        (make-pretty-printer-worker

  30018.         "foo"

  30019.         (lambda (printer)

  30020.           (format #f "x=<~a> y=<~a>"

  30021.                   (value-field value "x") (value-field value "y")))

  30022.         #f))

  30023. 

  30024.    This example doesn't need a lookup function, that is handled by the

  30025. '(gdb printing)' module.  Instead a function is provided to build up the

  30026. object that handles the lookup.

  30027. 

  30028.      (use-modules (gdb printing))

  30029. 

  30030.      (define (build-pretty-printer)

  30031.        (let ((pp (make-pretty-printer-collection "my-library")))

  30032.          (pp-collection-add-tag-printer "foo" make-foo-printer)

  30033.          (pp-collection-add-tag-printer "bar" make-bar-printer)

  30034.          pp))

  30035. 

  30036.    And here is the autoload support:

  30037. 

  30038.      (use-modules (gdb) (my-library))

  30039.      (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))

  30040. 

  30041.    Finally, when this printer is loaded into GDB, here is the

  30042. corresponding output of 'info pretty-printer':

  30043. 

  30044.      (gdb) info pretty-printer

  30045.      my_library.so:

  30046.        my-library

  30047.          foo

  30048.          bar

  30049. 

  30050. 

  30051. File: gdb.info,  Node: Commands In Guile,  Next: Parameters In Guile,  Prev: Writing a Guile Pretty-Printer,  Up: Guile API

  30052. 

  30053. 23.3.3.11 Commands In Guile

  30054. ...........................

  30055. 

  30056. You can implement new GDB CLI commands in Guile.  A CLI command object

  30057. is created with the 'make-command' Guile function, and added to GDB with

  30058. the 'register-command!' Guile function.  This two-step approach is taken

  30059. to separate out the side-effect of adding the command to GDB from

  30060. 'make-command'.

  30061. 

  30062.    There is no support for multi-line commands, that is commands that

  30063. consist of multiple lines and are terminated with 'end'.

  30064. 

  30065.  -- Scheme Procedure: (make-command name [#:invoke invoke]

  30066.           [#:command-class command-class] [#:completer-class completer]

  30067.           [#:prefix? prefix] [#:doc doc-string])

  30068. 

  30069.      The argument NAME is the name of the command.  If NAME consists of

  30070.      multiple words, then the initial words are looked for as prefix

  30071.      commands.  In this case, if one of the prefix commands does not

  30072.      exist, an exception is raised.

  30073. 

  30074.      The result is the '<gdb:command>' object representing the command.

  30075.      The command is not usable until it has been registered with GDB

  30076.      with 'register-command!'.

  30077. 

  30078.      The rest of the arguments are optional.

  30079. 

  30080.      The argument INVOKE is a procedure of three arguments: SELF, ARGS

  30081.      and FROM-TTY.  The argument SELF is the '<gdb:command>' object

  30082.      representing the command.  The argument ARGS is a string

  30083.      representing the arguments passed to the command, after leading and

  30084.      trailing whitespace has been stripped.  The argument FROM-TTY is a

  30085.      boolean flag and specifies whether the command should consider

  30086.      itself to have been originated from the user invoking it

  30087.      interactively.  If this function throws an exception, it is turned

  30088.      into a GDB 'error' call.  Otherwise, the return value is ignored.

  30089. 

  30090.      The argument COMMAND-CLASS is one of the 'COMMAND_' constants

  30091.      defined below.  This argument tells GDB how to categorize the new

  30092.      command in the help system.  The default is 'COMMAND_NONE'.

  30093. 

  30094.      The argument COMPLETER is either '#f', one of the 'COMPLETE_'

  30095.      constants defined below, or a procedure, also defined below.  This

  30096.      argument tells GDB how to perform completion for this command.  If

  30097.      not provided or if the value is '#f', then no completion is

  30098.      performed on the command.

  30099. 

  30100.      The argument PREFIX is a boolean flag indicating whether the new

  30101.      command is a prefix command; sub-commands of this command may be

  30102.      registered.

  30103. 

  30104.      The argument DOC-STRING is help text for the new command.  If no

  30105.      documentation string is provided, the default value "This command

  30106.      is not documented."  is used.

  30107. 

  30108.  -- Scheme Procedure: register-command! command

  30109.      Add COMMAND, a '<gdb:command>' object, to GDB's list of commands.

  30110.      It is an error to register a command more than once.  The result is

  30111.      unspecified.

  30112. 

  30113.  -- Scheme Procedure: command? object

  30114.      Return '#t' if OBJECT is a '<gdb:command>' object.  Otherwise

  30115.      return '#f'.

  30116. 

  30117.  -- Scheme Procedure: dont-repeat

  30118.      By default, a GDB command is repeated when the user enters a blank

  30119.      line at the command prompt.  A command can suppress this behavior

  30120.      by invoking the 'dont-repeat' function.  This is similar to the

  30121.      user command 'dont-repeat', see *note dont-repeat: Define.

  30122. 

  30123.  -- Scheme Procedure: string->argv string

  30124.      Convert a string to a list of strings split up according to GDB's

  30125.      argv parsing rules.  It is recommended to use this for consistency.

  30126.      Arguments are separated by spaces and may be quoted.  Example:

  30127. 

  30128.           scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")

  30129.           $1 = ("1" "2 \"3" "4 \"5" "6 '7")

  30130. 

  30131.  -- Scheme Procedure: throw-user-error message . args

  30132.      Throw a 'gdb:user-error' exception.  The argument MESSAGE is the

  30133.      error message as a format string, like the FMT argument to the

  30134.      'format' Scheme function.  *Note (guile)Formatted Output::.  The

  30135.      argument ARGS is a list of the optional arguments of MESSAGE.

  30136. 

  30137.      This is used when the command detects a user error of some kind,

  30138.      say a bad command argument.

  30139. 

  30140.           (gdb) guile (use-modules (gdb))

  30141.           (gdb) guile

  30142.           (register-command! (make-command "test-user-error"

  30143.             #:command-class COMMAND_OBSCURE

  30144.             #:invoke (lambda (self arg from-tty)

  30145.               (throw-user-error "Bad argument ~a" arg))))

  30146.           end

  30147.           (gdb) test-user-error ugh

  30148.           ERROR: Bad argument ugh

  30149. 

  30150.  -- completer: self text word

  30151.      If the COMPLETER option to 'make-command' is a procedure, it takes

  30152.      three arguments: SELF which is the '<gdb:command>' object, and TEXT

  30153.      and WORD which are both strings.  The argument TEXT holds the

  30154.      complete command line up to the cursor's location.  The argument

  30155.      WORD holds the last word of the command line; this is computed

  30156.      using a word-breaking heuristic.

  30157. 

  30158.      All forms of completion are handled by this function, that is, the

  30159.      <TAB> and <M-?> key bindings (*note Completion::), and the

  30160.      'complete' command (*note complete: Help.).

  30161. 

  30162.      This procedure can return several kinds of values:

  30163. 

  30164.         * If the return value is a list, the contents of the list are

  30165.           used as the completions.  It is up to COMPLETER to ensure that

  30166.           the contents actually do complete the word.  An empty list is

  30167.           allowed, it means that there were no completions available.

  30168.           Only string elements of the list are used; other elements in

  30169.           the list are ignored.

  30170. 

  30171.         * If the return value is a '<gdb:iterator>' object, it is

  30172.           iterated over to obtain the completions.  It is up to

  30173.           'completer-procedure' to ensure that the results actually do

  30174.           complete the word.  Only string elements of the result are

  30175.           used; other elements in the sequence are ignored.

  30176. 

  30177.         * All other results are treated as though there were no

  30178.           available completions.

  30179. 

  30180.    When a new command is registered, it will have been declared as a

  30181. member of some general class of commands.  This is used to classify

  30182. top-level commands in the on-line help system; note that prefix commands

  30183. are not listed under their own category but rather that of their

  30184. top-level command.  The available classifications are represented by

  30185. constants defined in the 'gdb' module:

  30186. 

  30187. 'COMMAND_NONE'

  30188.      The command does not belong to any particular class.  A command in

  30189.      this category will not be displayed in any of the help categories.

  30190.      This is the default.

  30191. 

  30192. 'COMMAND_RUNNING'

  30193.      The command is related to running the inferior.  For example,

  30194.      'start', 'step', and 'continue' are in this category.  Type 'help

  30195.      running' at the GDB prompt to see a list of commands in this

  30196.      category.

  30197. 

  30198. 'COMMAND_DATA'

  30199.      The command is related to data or variables.  For example, 'call',

  30200.      'find', and 'print' are in this category.  Type 'help data' at the

  30201.      GDB prompt to see a list of commands in this category.

  30202. 

  30203. 'COMMAND_STACK'

  30204.      The command has to do with manipulation of the stack.  For example,

  30205.      'backtrace', 'frame', and 'return' are in this category.  Type

  30206.      'help stack' at the GDB prompt to see a list of commands in this

  30207.      category.

  30208. 

  30209. 'COMMAND_FILES'

  30210.      This class is used for file-related commands.  For example, 'file',

  30211.      'list' and 'section' are in this category.  Type 'help files' at

  30212.      the GDB prompt to see a list of commands in this category.

  30213. 

  30214. 'COMMAND_SUPPORT'

  30215.      This should be used for "support facilities", generally meaning

  30216.      things that are useful to the user when interacting with GDB, but

  30217.      not related to the state of the inferior.  For example, 'help',

  30218.      'make', and 'shell' are in this category.  Type 'help support' at

  30219.      the GDB prompt to see a list of commands in this category.

  30220. 

  30221. 'COMMAND_STATUS'

  30222.      The command is an 'info'-related command, that is, related to the

  30223.      state of GDB itself.  For example, 'info', 'macro', and 'show' are

  30224.      in this category.  Type 'help status' at the GDB prompt to see a

  30225.      list of commands in this category.

  30226. 

  30227. 'COMMAND_BREAKPOINTS'

  30228.      The command has to do with breakpoints.  For example, 'break',

  30229.      'clear', and 'delete' are in this category.  Type 'help

  30230.      breakpoints' at the GDB prompt to see a list of commands in this

  30231.      category.

  30232. 

  30233. 'COMMAND_TRACEPOINTS'

  30234.      The command has to do with tracepoints.  For example, 'trace',

  30235.      'actions', and 'tfind' are in this category.  Type 'help

  30236.      tracepoints' at the GDB prompt to see a list of commands in this

  30237.      category.

  30238. 

  30239. 'COMMAND_USER'

  30240.      The command is a general purpose command for the user, and

  30241.      typically does not fit in one of the other categories.  Type 'help

  30242.      user-defined' at the GDB prompt to see a list of commands in this

  30243.      category, as well as the list of gdb macros (*note Sequences::).

  30244. 

  30245. 'COMMAND_OBSCURE'

  30246.      The command is only used in unusual circumstances, or is not of

  30247.      general interest to users.  For example, 'checkpoint', 'fork', and

  30248.      'stop' are in this category.  Type 'help obscure' at the GDB prompt

  30249.      to see a list of commands in this category.

  30250. 

  30251. 'COMMAND_MAINTENANCE'

  30252.      The command is only useful to GDB maintainers.  The 'maintenance'

  30253.      and 'flushregs' commands are in this category.  Type 'help

  30254.      internals' at the GDB prompt to see a list of commands in this

  30255.      category.

  30256. 

  30257.    A new command can use a predefined completion function, either by

  30258. specifying it via an argument at initialization, or by returning it from

  30259. the 'completer' procedure.  These predefined completion constants are

  30260. all defined in the 'gdb' module:

  30261. 

  30262. 'COMPLETE_NONE'

  30263.      This constant means that no completion should be done.

  30264. 

  30265. 'COMPLETE_FILENAME'

  30266.      This constant means that filename completion should be performed.

  30267. 

  30268. 'COMPLETE_LOCATION'

  30269.      This constant means that location completion should be done.  *Note

  30270.      Specify Location::.

  30271. 

  30272. 'COMPLETE_COMMAND'

  30273.      This constant means that completion should examine GDB command

  30274.      names.

  30275. 

  30276. 'COMPLETE_SYMBOL'

  30277.      This constant means that completion should be done using symbol

  30278.      names as the source.

  30279. 

  30280. 'COMPLETE_EXPRESSION'

  30281.      This constant means that completion should be done on expressions.

  30282.      Often this means completing on symbol names, but some language

  30283.      parsers also have support for completing on field names.

  30284. 

  30285.    The following code snippet shows how a trivial CLI command can be

  30286. implemented in Guile:

  30287. 

  30288.      (gdb) guile

  30289.      (register-command! (make-command "hello-world"

  30290.        #:command-class COMMAND_USER

  30291.        #:doc "Greet the whole world."

  30292.        #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))

  30293.      end

  30294.      (gdb) hello-world

  30295.      Hello, World!

  30296. 

  30297. 

  30298. File: gdb.info,  Node: Parameters In Guile,  Next: Progspaces In Guile,  Prev: Commands In Guile,  Up: Guile API

  30299. 

  30300. 23.3.3.12 Parameters In Guile

  30301. .............................

  30302. 

  30303. You can implement new GDB "parameters" using Guile (1).

  30304. 

  30305.    There are many parameters that already exist and can be set in GDB.

  30306. Two examples are: 'set follow-fork' and 'set charset'.  Setting these

  30307. parameters influences certain behavior in GDB.  Similarly, you can

  30308. define parameters that can be used to influence behavior in custom Guile

  30309. scripts and commands.

  30310. 

  30311.    A new parameter is defined with the 'make-parameter' Guile function,

  30312. and added to GDB with the 'register-parameter!' Guile function.  This

  30313. two-step approach is taken to separate out the side-effect of adding the

  30314. parameter to GDB from 'make-parameter'.

  30315. 

  30316.    Parameters are exposed to the user via the 'set' and 'show' commands.

  30317. *Note Help::.

  30318. 

  30319.  -- Scheme Procedure: (make-parameter name [#:command-class

  30320.           command-class] [#:parameter-type parameter-type] [#:enum-list

  30321.           enum-list] [#:set-func set-func] [#:show-func show-func]

  30322.           [#:doc doc] [#:set-doc set-doc] [#:show-doc show-doc]

  30323.           [#:initial-value initial-value])

  30324. 

  30325.      The argument NAME is the name of the new parameter.  If NAME

  30326.      consists of multiple words, then the initial words are looked for

  30327.      as prefix parameters.  An example of this can be illustrated with

  30328.      the 'set print' set of parameters.  If NAME is 'print foo', then

  30329.      'print' will be searched as the prefix parameter.  In this case the

  30330.      parameter can subsequently be accessed in GDB as 'set print foo'.

  30331.      If NAME consists of multiple words, and no prefix parameter group

  30332.      can be found, an exception is raised.

  30333. 

  30334.      The result is the '<gdb:parameter>' object representing the

  30335.      parameter.  The parameter is not usable until it has been

  30336.      registered with GDB with 'register-parameter!'.

  30337. 

  30338.      The rest of the arguments are optional.

  30339. 

  30340.      The argument COMMAND-CLASS should be one of the 'COMMAND_'

  30341.      constants (*note Commands In Guile::).  This argument tells GDB how

  30342.      to categorize the new parameter in the help system.  The default is

  30343.      'COMMAND_NONE'.

  30344. 

  30345.      The argument PARAMETER-TYPE should be one of the 'PARAM_' constants

  30346.      defined below.  This argument tells GDB the type of the new

  30347.      parameter; this information is used for input validation and

  30348.      completion.  The default is 'PARAM_BOOLEAN'.

  30349. 

  30350.      If PARAMETER-TYPE is 'PARAM_ENUM', then ENUM-LIST must be a list of

  30351.      strings.  These strings represent the possible values for the

  30352.      parameter.

  30353. 

  30354.      If PARAMETER-TYPE is not 'PARAM_ENUM', then the presence of

  30355.      ENUM-LIST will cause an exception to be thrown.

  30356. 

  30357.      The argument SET-FUNC is a function of one argument: SELF which is

  30358.      the '<gdb:parameter>' object representing the parameter.  GDB will

  30359.      call this function when a PARAMETER's value has been changed via

  30360.      the 'set' API (for example, 'set foo off').  The value of the

  30361.      parameter has already been set to the new value.  This function

  30362.      must return a string to be displayed to the user.  GDB will add a

  30363.      trailing newline if the string is non-empty.  GDB generally doesn't

  30364.      print anything when a parameter is set, thus typically this

  30365.      function should return '""'.  A non-empty string result should

  30366.      typically be used for displaying warnings and errors.

  30367. 

  30368.      The argument SHOW-FUNC is a function of two arguments: SELF which

  30369.      is the '<gdb:parameter>' object representing the parameter, and

  30370.      SVALUE which is the string representation of the current value.

  30371.      GDB will call this function when a PARAMETER's 'show' API has been

  30372.      invoked (for example, 'show foo').  This function must return a

  30373.      string, and will be displayed to the user.  GDB will add a trailing

  30374.      newline.

  30375. 

  30376.      The argument DOC is the help text for the new parameter.  If there

  30377.      is no documentation string, a default value is used.

  30378. 

  30379.      The argument SET-DOC is the help text for this parameter's 'set'

  30380.      command.

  30381. 

  30382.      The argument SHOW-DOC is the help text for this parameter's 'show'

  30383.      command.

  30384. 

  30385.      The argument INITIAL-VALUE specifies the initial value of the

  30386.      parameter.  If it is a function, it takes one parameter, the

  30387.      '<gdb:parameter>' object and its result is used as the initial

  30388.      value of the parameter.  The initial value must be valid for the

  30389.      parameter type, otherwise an exception is thrown.

  30390. 

  30391.  -- Scheme Procedure: register-parameter! parameter

  30392.      Add PARAMETER, a '<gdb:parameter>' object, to GDB's list of

  30393.      parameters.  It is an error to register a parameter more than once.

  30394.      The result is unspecified.

  30395. 

  30396.  -- Scheme Procedure: parameter? object

  30397.      Return '#t' if OBJECT is a '<gdb:parameter>' object.  Otherwise

  30398.      return '#f'.

  30399. 

  30400.  -- Scheme Procedure: parameter-value parameter

  30401.      Return the value of PARAMETER which may either be a

  30402.      '<gdb:parameter>' object or a string naming the parameter.

  30403. 

  30404.  -- Scheme Procedure: set-parameter-value! parameter new-value

  30405.      Assign PARAMETER the value of NEW-VALUE.  The argument PARAMETER

  30406.      must be an object of type '<gdb:parameter>'.  GDB does validation

  30407.      when assignments are made.

  30408. 

  30409.    When a new parameter is defined, its type must be specified.  The

  30410. available types are represented by constants defined in the 'gdb'

  30411. module:

  30412. 

  30413. 'PARAM_BOOLEAN'

  30414.      The value is a plain boolean.  The Guile boolean values, '#t' and

  30415.      '#f' are the only valid values.

  30416. 

  30417. 'PARAM_AUTO_BOOLEAN'

  30418.      The value has three possible states: true, false, and 'auto'.  In

  30419.      Guile, true and false are represented using boolean constants, and

  30420.      'auto' is represented using '#:auto'.

  30421. 

  30422. 'PARAM_UINTEGER'

  30423.      The value is an unsigned integer.  The value of 0 should be

  30424.      interpreted to mean "unlimited".

  30425. 

  30426. 'PARAM_ZINTEGER'

  30427.      The value is an integer.

  30428. 

  30429. 'PARAM_ZUINTEGER'

  30430.      The value is an unsigned integer.

  30431. 

  30432. 'PARAM_ZUINTEGER_UNLIMITED'

  30433.      The value is an integer in the range '[0, INT_MAX]'.  A value of

  30434.      '-1' means "unlimited", and other negative numbers are not allowed.

  30435. 

  30436. 'PARAM_STRING'

  30437.      The value is a string.  When the user modifies the string, any

  30438.      escape sequences, such as '\t', '\f', and octal escapes, are

  30439.      translated into corresponding characters and encoded into the

  30440.      current host charset.

  30441. 

  30442. 'PARAM_STRING_NOESCAPE'

  30443.      The value is a string.  When the user modifies the string, escapes

  30444.      are passed through untranslated.

  30445. 

  30446. 'PARAM_OPTIONAL_FILENAME'

  30447.      The value is a either a filename (a string), or '#f'.

  30448. 

  30449. 'PARAM_FILENAME'

  30450.      The value is a filename.  This is just like

  30451.      'PARAM_STRING_NOESCAPE', but uses file names for completion.

  30452. 

  30453. 'PARAM_ENUM'

  30454.      The value is a string, which must be one of a collection of string

  30455.      constants provided when the parameter is created.

  30456. 

  30457.    ---------- Footnotes ----------

  30458. 

  30459.    (1) Note that GDB parameters must not be confused with Guile’s

  30460. parameter objects (*note (guile)Parameters::).

  30461. 

  30462. 

  30463. File: gdb.info,  Node: Progspaces In Guile,  Next: Objfiles In Guile,  Prev: Parameters In Guile,  Up: Guile API

  30464. 

  30465. 23.3.3.13 Program Spaces In Guile

  30466. .................................

  30467. 

  30468. A program space, or "progspace", represents a symbolic view of an

  30469. address space.  It consists of all of the objfiles of the program.

  30470. *Note Objfiles In Guile::.  *Note program spaces: Inferiors Connections

  30471. and Programs, for more details about program spaces.

  30472. 

  30473.    Each progspace is represented by an instance of the '<gdb:progspace>'

  30474. smob.  *Note GDB Scheme Data Types::.

  30475. 

  30476.    The following progspace-related functions are available in the

  30477. '(gdb)' module:

  30478. 

  30479.  -- Scheme Procedure: progspace? object

  30480.      Return '#t' if OBJECT is a '<gdb:progspace>' object.  Otherwise

  30481.      return '#f'.

  30482. 

  30483.  -- Scheme Procedure: progspace-valid? progspace

  30484.      Return '#t' if PROGSPACE is valid, '#f' if not.  A

  30485.      '<gdb:progspace>' object can become invalid if the program it

  30486.      refers to is not loaded in GDB any longer.

  30487. 

  30488.  -- Scheme Procedure: current-progspace

  30489.      This function returns the program space of the currently selected

  30490.      inferior.  There is always a current progspace, this never returns

  30491.      '#f'.  *Note Inferiors Connections and Programs::.

  30492. 

  30493.  -- Scheme Procedure: progspaces

  30494.      Return a list of all the progspaces currently known to GDB.

  30495. 

  30496.  -- Scheme Procedure: progspace-filename progspace

  30497.      Return the absolute file name of PROGSPACE as a string.  This is

  30498.      the name of the file passed as the argument to the 'file' or

  30499.      'symbol-file' commands.  If the program space does not have an

  30500.      associated file name, then '#f' is returned.  This occurs, for

  30501.      example, when GDB is started without a program to debug.

  30502. 

  30503.      A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is

  30504.      invalid.

  30505. 

  30506.  -- Scheme Procedure: progspace-objfiles progspace

  30507.      Return the list of objfiles of PROGSPACE.  The order of objfiles in

  30508.      the result is arbitrary.  Each element is an object of type

  30509.      '<gdb:objfile>'.  *Note Objfiles In Guile::.

  30510. 

  30511.      A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is

  30512.      invalid.

  30513. 

  30514.  -- Scheme Procedure: progspace-pretty-printers progspace

  30515.      Return the list of pretty-printers of PROGSPACE.  Each element is

  30516.      an object of type '<gdb:pretty-printer>'.  *Note Guile Pretty

  30517.      Printing API::, for more information.

  30518. 

  30519.  -- Scheme Procedure: set-progspace-pretty-printers! progspace

  30520.           printer-list

  30521.      Set the list of registered '<gdb:pretty-printer>' objects for

  30522.      PROGSPACE to PRINTER-LIST.  *Note Guile Pretty Printing API::, for

  30523.      more information.

  30524. 

  30525. 

  30526. File: gdb.info,  Node: Objfiles In Guile,  Next: Frames In Guile,  Prev: Progspaces In Guile,  Up: Guile API

  30527. 

  30528. 23.3.3.14 Objfiles In Guile

  30529. ...........................

  30530. 

  30531. GDB loads symbols for an inferior from various symbol-containing files

  30532. (*note Files::).  These include the primary executable file, any shared

  30533. libraries used by the inferior, and any separate debug info files (*note

  30534. Separate Debug Files::).  GDB calls these symbol-containing files

  30535. "objfiles".

  30536. 

  30537.    Each objfile is represented as an object of type '<gdb:objfile>'.

  30538. 

  30539.    The following objfile-related procedures are provided by the '(gdb)'

  30540. module:

  30541. 

  30542.  -- Scheme Procedure: objfile? object

  30543.      Return '#t' if OBJECT is a '<gdb:objfile>' object.  Otherwise

  30544.      return '#f'.

  30545. 

  30546.  -- Scheme Procedure: objfile-valid? objfile

  30547.      Return '#t' if OBJFILE is valid, '#f' if not.  A '<gdb:objfile>'

  30548.      object can become invalid if the object file it refers to is not

  30549.      loaded in GDB any longer.  All other '<gdb:objfile>' procedures

  30550.      will throw an exception if it is invalid at the time the procedure

  30551.      is called.

  30552. 

  30553.  -- Scheme Procedure: objfile-filename objfile

  30554.      Return the file name of OBJFILE as a string, with symbolic links

  30555.      resolved.

  30556. 

  30557.  -- Scheme Procedure: objfile-progspace objfile

  30558.      Return the '<gdb:progspace>' that this object file lives in.  *Note

  30559.      Progspaces In Guile::, for more on progspaces.

  30560. 

  30561.  -- Scheme Procedure: objfile-pretty-printers objfile

  30562.      Return the list of registered '<gdb:pretty-printer>' objects for

  30563.      OBJFILE.  *Note Guile Pretty Printing API::, for more information.

  30564. 

  30565.  -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list

  30566.      Set the list of registered '<gdb:pretty-printer>' objects for

  30567.      OBJFILE to PRINTER-LIST.  The PRINTER-LIST must be a list of

  30568.      '<gdb:pretty-printer>' objects.  *Note Guile Pretty Printing API::,

  30569.      for more information.

  30570. 

  30571.  -- Scheme Procedure: current-objfile

  30572.      When auto-loading a Guile script (*note Guile Auto-loading::), GDB

  30573.      sets the "current objfile" to the corresponding objfile.  This

  30574.      function returns the current objfile.  If there is no current

  30575.      objfile, this function returns '#f'.

  30576. 

  30577.  -- Scheme Procedure: objfiles

  30578.      Return a list of all the objfiles in the current program space.

  30579. 

  30580. 

  30581. File: gdb.info,  Node: Frames In Guile,  Next: Blocks In Guile,  Prev: Objfiles In Guile,  Up: Guile API

  30582. 

  30583. 23.3.3.15 Accessing inferior stack frames from Guile.

  30584. .....................................................

  30585. 

  30586. When the debugged program stops, GDB is able to analyze its call stack

  30587. (*note Stack frames: Frames.).  The '<gdb:frame>' class represents a

  30588. frame in the stack.  A '<gdb:frame>' object is only valid while its

  30589. corresponding frame exists in the inferior's stack.  If you try to use

  30590. an invalid frame object, GDB will throw a 'gdb:invalid-object' exception

  30591. (*note Guile Exception Handling::).

  30592. 

  30593.    Two '<gdb:frame>' objects can be compared for equality with the

  30594. 'equal?' function, like:

  30595. 

  30596.      (gdb) guile (equal? (newest-frame) (selected-frame))

  30597.      #t

  30598. 

  30599.    The following frame-related procedures are provided by the '(gdb)'

  30600. module:

  30601. 

  30602.  -- Scheme Procedure: frame? object

  30603.      Return '#t' if OBJECT is a '<gdb:frame>' object.  Otherwise return

  30604.      '#f'.

  30605. 

  30606.  -- Scheme Procedure: frame-valid? frame

  30607.      Returns '#t' if FRAME is valid, '#f' if not.  A frame object can

  30608.      become invalid if the frame it refers to doesn't exist anymore in

  30609.      the inferior.  All '<gdb:frame>' procedures will throw an exception

  30610.      if the frame is invalid at the time the procedure is called.

  30611. 

  30612.  -- Scheme Procedure: frame-name frame

  30613.      Return the function name of FRAME, or '#f' if it can't be obtained.

  30614. 

  30615.  -- Scheme Procedure: frame-arch frame

  30616.      Return the '<gdb:architecture>' object corresponding to FRAME's

  30617.      architecture.  *Note Architectures In Guile::.

  30618. 

  30619.  -- Scheme Procedure: frame-type frame

  30620.      Return the type of FRAME.  The value can be one of:

  30621. 

  30622.      'NORMAL_FRAME'

  30623.           An ordinary stack frame.

  30624. 

  30625.      'DUMMY_FRAME'

  30626.           A fake stack frame that was created by GDB when performing an

  30627.           inferior function call.

  30628. 

  30629.      'INLINE_FRAME'

  30630.           A frame representing an inlined function.  The function was

  30631.           inlined into a 'NORMAL_FRAME' that is older than this one.

  30632. 

  30633.      'TAILCALL_FRAME'

  30634.           A frame representing a tail call.  *Note Tail Call Frames::.

  30635. 

  30636.      'SIGTRAMP_FRAME'

  30637.           A signal trampoline frame.  This is the frame created by the

  30638.           OS when it calls into a signal handler.

  30639. 

  30640.      'ARCH_FRAME'

  30641.           A fake stack frame representing a cross-architecture call.

  30642. 

  30643.      'SENTINEL_FRAME'

  30644.           This is like 'NORMAL_FRAME', but it is only used for the

  30645.           newest frame.

  30646. 

  30647.  -- Scheme Procedure: frame-unwind-stop-reason frame

  30648.      Return an integer representing the reason why it's not possible to

  30649.      find more frames toward the outermost frame.  Use

  30650.      'unwind-stop-reason-string' to convert the value returned by this

  30651.      function to a string.  The value can be one of:

  30652. 

  30653.      'FRAME_UNWIND_NO_REASON'

  30654.           No particular reason (older frames should be available).

  30655. 

  30656.      'FRAME_UNWIND_NULL_ID'

  30657.           The previous frame's analyzer returns an invalid result.

  30658. 

  30659.      'FRAME_UNWIND_OUTERMOST'

  30660.           This frame is the outermost.

  30661. 

  30662.      'FRAME_UNWIND_UNAVAILABLE'

  30663.           Cannot unwind further, because that would require knowing the

  30664.           values of registers or memory that have not been collected.

  30665. 

  30666.      'FRAME_UNWIND_INNER_ID'

  30667.           This frame ID looks like it ought to belong to a NEXT frame,

  30668.           but we got it for a PREV frame.  Normally, this is a sign of

  30669.           unwinder failure.  It could also indicate stack corruption.

  30670. 

  30671.      'FRAME_UNWIND_SAME_ID'

  30672.           This frame has the same ID as the previous one.  That means

  30673.           that unwinding further would almost certainly give us another

  30674.           frame with exactly the same ID, so break the chain.  Normally,

  30675.           this is a sign of unwinder failure.  It could also indicate

  30676.           stack corruption.

  30677. 

  30678.      'FRAME_UNWIND_NO_SAVED_PC'

  30679.           The frame unwinder did not find any saved PC, but we needed

  30680.           one to unwind further.

  30681. 

  30682.      'FRAME_UNWIND_MEMORY_ERROR'

  30683.           The frame unwinder caused an error while trying to access

  30684.           memory.

  30685. 

  30686.      'FRAME_UNWIND_FIRST_ERROR'

  30687.           Any stop reason greater or equal to this value indicates some

  30688.           kind of error.  This special value facilitates writing code

  30689.           that tests for errors in unwinding in a way that will work

  30690.           correctly even if the list of the other values is modified in

  30691.           future GDB versions.  Using it, you could write:

  30692. 

  30693.                (define reason (frame-unwind-stop-readon (selected-frame)))

  30694.                (define reason-str (unwind-stop-reason-string reason))

  30695.                (if (>= reason FRAME_UNWIND_FIRST_ERROR)

  30696.                    (format #t "An error occured: ~s\n" reason-str))

  30697. 

  30698.  -- Scheme Procedure: frame-pc frame

  30699.      Return the frame's resume address.

  30700. 

  30701.  -- Scheme Procedure: frame-block frame

  30702.      Return the frame's code block as a '<gdb:block>' object.  *Note

  30703.      Blocks In Guile::.

  30704. 

  30705.  -- Scheme Procedure: frame-function frame

  30706.      Return the symbol for the function corresponding to this frame as a

  30707.      '<gdb:symbol>' object, or '#f' if there isn't one.  *Note Symbols

  30708.      In Guile::.

  30709. 

  30710.  -- Scheme Procedure: frame-older frame

  30711.      Return the frame that called FRAME.

  30712. 

  30713.  -- Scheme Procedure: frame-newer frame

  30714.      Return the frame called by FRAME.

  30715. 

  30716.  -- Scheme Procedure: frame-sal frame

  30717.      Return the frame's '<gdb:sal>' (symtab and line) object.  *Note

  30718.      Symbol Tables In Guile::.

  30719. 

  30720.  -- Scheme Procedure: frame-read-register frame register

  30721.      Return the value of REGISTER in FRAME.  REGISTER should be a

  30722.      string, like 'pc'.

  30723. 

  30724.  -- Scheme Procedure: frame-read-var frame variable [#:block block]

  30725.      Return the value of VARIABLE in FRAME.  If the optional argument

  30726.      BLOCK is provided, search for the variable from that block;

  30727.      otherwise start at the frame's current block (which is determined

  30728.      by the frame's current program counter).  The VARIABLE must be

  30729.      given as a string or a '<gdb:symbol>' object, and BLOCK must be a

  30730.      '<gdb:block>' object.

  30731. 

  30732.  -- Scheme Procedure: frame-select frame

  30733.      Set FRAME to be the selected frame.  *Note Examining the Stack:

  30734.      Stack.

  30735. 

  30736.  -- Scheme Procedure: selected-frame

  30737.      Return the selected frame object.  *Note Selecting a Frame:

  30738.      Selection.

  30739. 

  30740.  -- Scheme Procedure: newest-frame

  30741.      Return the newest frame object for the selected thread.

  30742. 

  30743.  -- Scheme Procedure: unwind-stop-reason-string reason

  30744.      Return a string explaining the reason why GDB stopped unwinding

  30745.      frames, as expressed by the given REASON code (an integer, see the

  30746.      'frame-unwind-stop-reason' procedure above in this section).

  30747. 

  30748. 

  30749. File: gdb.info,  Node: Blocks In Guile,  Next: Symbols In Guile,  Prev: Frames In Guile,  Up: Guile API

  30750. 

  30751. 23.3.3.16 Accessing blocks from Guile.

  30752. ......................................

  30753. 

  30754. In GDB, symbols are stored in blocks.  A block corresponds roughly to a

  30755. scope in the source code.  Blocks are organized hierarchically, and are

  30756. represented individually in Guile as an object of type '<gdb:block>'.

  30757. Blocks rely on debugging information being available.

  30758. 

  30759.    A frame has a block.  Please see *note Frames In Guile::, for a more

  30760. in-depth discussion of frames.

  30761. 

  30762.    The outermost block is known as the "global block".  The global block

  30763. typically holds public global variables and functions.

  30764. 

  30765.    The block nested just inside the global block is the "static block".

  30766. The static block typically holds file-scoped variables and functions.

  30767. 

  30768.    GDB provides a method to get a block's superblock, but there is

  30769. currently no way to examine the sub-blocks of a block, or to iterate

  30770. over all the blocks in a symbol table (*note Symbol Tables In Guile::).

  30771. 

  30772.    Here is a short example that should help explain blocks:

  30773. 

  30774.      /* This is in the global block.  */

  30775.      int global;

  30776. 

  30777.      /* This is in the static block.  */

  30778.      static int file_scope;

  30779. 

  30780.      /* 'function' is in the global block, and 'argument' is

  30781.         in a block nested inside of 'function'.  */

  30782.      int function (int argument)

  30783.      {

  30784.        /* 'local' is in a block inside 'function'.  It may or may

  30785.           not be in the same block as 'argument'.  */

  30786.        int local;

  30787. 

  30788.        {

  30789.           /* 'inner' is in a block whose superblock is the one holding

  30790.              'local'.  */

  30791.           int inner;

  30792. 

  30793.           /* If this call is expanded by the compiler, you may see

  30794.              a nested block here whose function is 'inline_function'

  30795.              and whose superblock is the one holding 'inner'.  */

  30796.           inline_function ();

  30797.        }

  30798.      }

  30799. 

  30800.    The following block-related procedures are provided by the '(gdb)'

  30801. module:

  30802. 

  30803.  -- Scheme Procedure: block? object

  30804.      Return '#t' if OBJECT is a '<gdb:block>' object.  Otherwise return

  30805.      '#f'.

  30806. 

  30807.  -- Scheme Procedure: block-valid? block

  30808.      Returns '#t' if '<gdb:block>' BLOCK is valid, '#f' if not.  A block

  30809.      object can become invalid if the block it refers to doesn't exist

  30810.      anymore in the inferior.  All other '<gdb:block>' methods will

  30811.      throw an exception if it is invalid at the time the procedure is

  30812.      called.  The block's validity is also checked during iteration over

  30813.      symbols of the block.

  30814. 

  30815.  -- Scheme Procedure: block-start block

  30816.      Return the start address of '<gdb:block>' BLOCK.

  30817. 

  30818.  -- Scheme Procedure: block-end block

  30819.      Return the end address of '<gdb:block>' BLOCK.

  30820. 

  30821.  -- Scheme Procedure: block-function block

  30822.      Return the name of '<gdb:block>' BLOCK represented as a

  30823.      '<gdb:symbol>' object.  If the block is not named, then '#f' is

  30824.      returned.

  30825. 

  30826.      For ordinary function blocks, the superblock is the static block.

  30827.      However, you should note that it is possible for a function block

  30828.      to have a superblock that is not the static block - for instance

  30829.      this happens for an inlined function.

  30830. 

  30831.  -- Scheme Procedure: block-superblock block

  30832.      Return the block containing '<gdb:block>' BLOCK.  If the parent

  30833.      block does not exist, then '#f' is returned.

  30834. 

  30835.  -- Scheme Procedure: block-global-block block

  30836.      Return the global block associated with '<gdb:block>' BLOCK.

  30837. 

  30838.  -- Scheme Procedure: block-static-block block

  30839.      Return the static block associated with '<gdb:block>' BLOCK.

  30840. 

  30841.  -- Scheme Procedure: block-global? block

  30842.      Return '#t' if '<gdb:block>' BLOCK is a global block.  Otherwise

  30843.      return '#f'.

  30844. 

  30845.  -- Scheme Procedure: block-static? block

  30846.      Return '#t' if '<gdb:block>' BLOCK is a static block.  Otherwise

  30847.      return '#f'.

  30848. 

  30849.  -- Scheme Procedure: block-symbols

  30850.      Return a list of all symbols (as <gdb:symbol> objects) in

  30851.      '<gdb:block>' BLOCK.

  30852. 

  30853.  -- Scheme Procedure: make-block-symbols-iterator block

  30854.      Return an object of type '<gdb:iterator>' that will iterate over

  30855.      all symbols of the block.  Guile programs should not assume that a

  30856.      specific block object will always contain a given symbol, since

  30857.      changes in GDB features and infrastructure may cause symbols move

  30858.      across blocks in a symbol table.  *Note Iterators In Guile::.

  30859. 

  30860.  -- Scheme Procedure: block-symbols-progress?

  30861.      Return #t if the object is a <gdb:block-symbols-progress> object.

  30862.      This object would be obtained from the 'progress' element of the

  30863.      '<gdb:iterator>' object returned by 'make-block-symbols-iterator'.

  30864. 

  30865.  -- Scheme Procedure: lookup-block pc

  30866.      Return the innermost '<gdb:block>' containing the given PC value.

  30867.      If the block cannot be found for the PC value specified, the

  30868.      function will return '#f'.

  30869. 

  30870. 

  30871. File: gdb.info,  Node: Symbols In Guile,  Next: Symbol Tables In Guile,  Prev: Blocks In Guile,  Up: Guile API

  30872. 

  30873. 23.3.3.17 Guile representation of Symbols.

  30874. ..........................................

  30875. 

  30876. GDB represents every variable, function and type as an entry in a symbol

  30877. table.  *Note Examining the Symbol Table: Symbols.  Guile represents

  30878. these symbols in GDB with the '<gdb:symbol>' object.

  30879. 

  30880.    The following symbol-related procedures are provided by the '(gdb)'

  30881. module:

  30882. 

  30883.  -- Scheme Procedure: symbol? object

  30884.      Return '#t' if OBJECT is an object of type '<gdb:symbol>'.

  30885.      Otherwise return '#f'.

  30886. 

  30887.  -- Scheme Procedure: symbol-valid? symbol

  30888.      Return '#t' if the '<gdb:symbol>' object is valid, '#f' if not.  A

  30889.      '<gdb:symbol>' object can become invalid if the symbol it refers to

  30890.      does not exist in GDB any longer.  All other '<gdb:symbol>'

  30891.      procedures will throw an exception if it is invalid at the time the

  30892.      procedure is called.

  30893. 

  30894.  -- Scheme Procedure: symbol-type symbol

  30895.      Return the type of SYMBOL or '#f' if no type is recorded.  The

  30896.      result is an object of type '<gdb:type>'.  *Note Types In Guile::.

  30897. 

  30898.  -- Scheme Procedure: symbol-symtab symbol

  30899.      Return the symbol table in which SYMBOL appears.  The result is an

  30900.      object of type '<gdb:symtab>'.  *Note Symbol Tables In Guile::.

  30901. 

  30902.  -- Scheme Procedure: symbol-line symbol

  30903.      Return the line number in the source code at which SYMBOL was

  30904.      defined.  This is an integer.

  30905. 

  30906.  -- Scheme Procedure: symbol-name symbol

  30907.      Return the name of SYMBOL as a string.

  30908. 

  30909.  -- Scheme Procedure: symbol-linkage-name symbol

  30910.      Return the name of SYMBOL, as used by the linker (i.e., may be

  30911.      mangled).

  30912. 

  30913.  -- Scheme Procedure: symbol-print-name symbol

  30914.      Return the name of SYMBOL in a form suitable for output.  This is

  30915.      either 'name' or 'linkage_name', depending on whether the user

  30916.      asked GDB to display demangled or mangled names.

  30917. 

  30918.  -- Scheme Procedure: symbol-addr-class symbol

  30919.      Return the address class of the symbol.  This classifies how to

  30920.      find the value of a symbol.  Each address class is a constant

  30921.      defined in the '(gdb)' module and described later in this chapter.

  30922. 

  30923.  -- Scheme Procedure: symbol-needs-frame? symbol

  30924.      Return '#t' if evaluating SYMBOL's value requires a frame (*note

  30925.      Frames In Guile::) and '#f' otherwise.  Typically, local variables

  30926.      will require a frame, but other symbols will not.

  30927. 

  30928.  -- Scheme Procedure: symbol-argument? symbol

  30929.      Return '#t' if SYMBOL is an argument of a function.  Otherwise

  30930.      return '#f'.

  30931. 

  30932.  -- Scheme Procedure: symbol-constant? symbol

  30933.      Return '#t' if SYMBOL is a constant.  Otherwise return '#f'.

  30934. 

  30935.  -- Scheme Procedure: symbol-function? symbol

  30936.      Return '#t' if SYMBOL is a function or a method.  Otherwise return

  30937.      '#f'.

  30938. 

  30939.  -- Scheme Procedure: symbol-variable? symbol

  30940.      Return '#t' if SYMBOL is a variable.  Otherwise return '#f'.

  30941. 

  30942.  -- Scheme Procedure: symbol-value symbol [#:frame frame]

  30943.      Compute the value of SYMBOL, as a '<gdb:value>'.  For functions,

  30944.      this computes the address of the function, cast to the appropriate

  30945.      type.  If the symbol requires a frame in order to compute its

  30946.      value, then FRAME must be given.  If FRAME is not given, or if

  30947.      FRAME is invalid, then an exception is thrown.

  30948. 

  30949.  -- Scheme Procedure: lookup-symbol name [#:block block] [#:domain

  30950.           domain]

  30951.      This function searches for a symbol by name.  The search scope can

  30952.      be restricted to the parameters defined in the optional domain and

  30953.      block arguments.

  30954. 

  30955.      NAME is the name of the symbol.  It must be a string.  The optional

  30956.      BLOCK argument restricts the search to symbols visible in that

  30957.      BLOCK.  The BLOCK argument must be a '<gdb:block>' object.  If

  30958.      omitted, the block for the current frame is used.  The optional

  30959.      DOMAIN argument restricts the search to the domain type.  The

  30960.      DOMAIN argument must be a domain constant defined in the '(gdb)'

  30961.      module and described later in this chapter.

  30962. 

  30963.      The result is a list of two elements.  The first element is a

  30964.      '<gdb:symbol>' object or '#f' if the symbol is not found.  If the

  30965.      symbol is found, the second element is '#t' if the symbol is a

  30966.      field of a method's object (e.g., 'this' in C++), otherwise it is

  30967.      '#f'.  If the symbol is not found, the second element is '#f'.

  30968. 

  30969.  -- Scheme Procedure: lookup-global-symbol name [#:domain domain]

  30970.      This function searches for a global symbol by name.  The search

  30971.      scope can be restricted by the domain argument.

  30972. 

  30973.      NAME is the name of the symbol.  It must be a string.  The optional

  30974.      DOMAIN argument restricts the search to the domain type.  The

  30975.      DOMAIN argument must be a domain constant defined in the '(gdb)'

  30976.      module and described later in this chapter.

  30977. 

  30978.      The result is a '<gdb:symbol>' object or '#f' if the symbol is not

  30979.      found.

  30980. 

  30981.    The available domain categories in '<gdb:symbol>' are represented as

  30982. constants in the '(gdb)' module:

  30983. 

  30984. 'SYMBOL_UNDEF_DOMAIN'

  30985.      This is used when a domain has not been discovered or none of the

  30986.      following domains apply.  This usually indicates an error either in

  30987.      the symbol information or in GDB's handling of symbols.

  30988. 

  30989. 'SYMBOL_VAR_DOMAIN'

  30990.      This domain contains variables, function names, typedef names and

  30991.      enum type values.

  30992. 

  30993. 'SYMBOL_STRUCT_DOMAIN'

  30994.      This domain holds struct, union and enum type names.

  30995. 

  30996. 'SYMBOL_LABEL_DOMAIN'

  30997.      This domain contains names of labels (for gotos).

  30998. 

  30999. 'SYMBOL_VARIABLES_DOMAIN'

  31000.      This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains

  31001.      everything minus functions and types.

  31002. 

  31003. 'SYMBOL_FUNCTIONS_DOMAIN'

  31004.      This domain contains all functions.

  31005. 

  31006. 'SYMBOL_TYPES_DOMAIN'

  31007.      This domain contains all types.

  31008. 

  31009.    The available address class categories in '<gdb:symbol>' are

  31010. represented as constants in the 'gdb' module:

  31011. 

  31012. 'SYMBOL_LOC_UNDEF'

  31013.      If this is returned by address class, it indicates an error either

  31014.      in the symbol information or in GDB's handling of symbols.

  31015. 

  31016. 'SYMBOL_LOC_CONST'

  31017.      Value is constant int.

  31018. 

  31019. 'SYMBOL_LOC_STATIC'

  31020.      Value is at a fixed address.

  31021. 

  31022. 'SYMBOL_LOC_REGISTER'

  31023.      Value is in a register.

  31024. 

  31025. 'SYMBOL_LOC_ARG'

  31026.      Value is an argument.  This value is at the offset stored within

  31027.      the symbol inside the frame's argument list.

  31028. 

  31029. 'SYMBOL_LOC_REF_ARG'

  31030.      Value address is stored in the frame's argument list.  Just like

  31031.      'LOC_ARG' except that the value's address is stored at the offset,

  31032.      not the value itself.

  31033. 

  31034. 'SYMBOL_LOC_REGPARM_ADDR'

  31035.      Value is a specified register.  Just like 'LOC_REGISTER' except the

  31036.      register holds the address of the argument instead of the argument

  31037.      itself.

  31038. 

  31039. 'SYMBOL_LOC_LOCAL'

  31040.      Value is a local variable.

  31041. 

  31042. 'SYMBOL_LOC_TYPEDEF'

  31043.      Value not used.  Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all

  31044.      have this class.

  31045. 

  31046. 'SYMBOL_LOC_BLOCK'

  31047.      Value is a block.

  31048. 

  31049. 'SYMBOL_LOC_CONST_BYTES'

  31050.      Value is a byte-sequence.

  31051. 

  31052. 'SYMBOL_LOC_UNRESOLVED'

  31053.      Value is at a fixed address, but the address of the variable has to

  31054.      be determined from the minimal symbol table whenever the variable

  31055.      is referenced.

  31056. 

  31057. 'SYMBOL_LOC_OPTIMIZED_OUT'

  31058.      The value does not actually exist in the program.

  31059. 

  31060. 'SYMBOL_LOC_COMPUTED'

  31061.      The value's address is a computed location.

  31062. 

  31063. 

  31064. File: gdb.info,  Node: Symbol Tables In Guile,  Next: Breakpoints In Guile,  Prev: Symbols In Guile,  Up: Guile API

  31065. 

  31066. 23.3.3.18 Symbol table representation in Guile.

  31067. ...............................................

  31068. 

  31069. Access to symbol table data maintained by GDB on the inferior is exposed

  31070. to Guile via two objects: '<gdb:sal>' (symtab-and-line) and

  31071. '<gdb:symtab>'.  Symbol table and line data for a frame is returned from

  31072. the 'frame-find-sal' '<gdb:frame>' procedure.  *Note Frames In Guile::.

  31073. 

  31074.    For more information on GDB's symbol table management, see *note

  31075. Examining the Symbol Table: Symbols.

  31076. 

  31077.    The following symtab-related procedures are provided by the '(gdb)'

  31078. module:

  31079. 

  31080.  -- Scheme Procedure: symtab? object

  31081.      Return '#t' if OBJECT is an object of type '<gdb:symtab>'.

  31082.      Otherwise return '#f'.

  31083. 

  31084.  -- Scheme Procedure: symtab-valid? symtab

  31085.      Return '#t' if the '<gdb:symtab>' object is valid, '#f' if not.  A

  31086.      '<gdb:symtab>' object becomes invalid when the symbol table it

  31087.      refers to no longer exists in GDB.  All other '<gdb:symtab>'

  31088.      procedures will throw an exception if it is invalid at the time the

  31089.      procedure is called.

  31090. 

  31091.  -- Scheme Procedure: symtab-filename symtab

  31092.      Return the symbol table's source filename.

  31093. 

  31094.  -- Scheme Procedure: symtab-fullname symtab

  31095.      Return the symbol table's source absolute file name.

  31096. 

  31097.  -- Scheme Procedure: symtab-objfile symtab

  31098.      Return the symbol table's backing object file.  *Note Objfiles In

  31099.      Guile::.

  31100. 

  31101.  -- Scheme Procedure: symtab-global-block symtab

  31102.      Return the global block of the underlying symbol table.  *Note

  31103.      Blocks In Guile::.

  31104. 

  31105.  -- Scheme Procedure: symtab-static-block symtab

  31106.      Return the static block of the underlying symbol table.  *Note

  31107.      Blocks In Guile::.

  31108. 

  31109.    The following symtab-and-line-related procedures are provided by the

  31110. '(gdb)' module:

  31111. 

  31112.  -- Scheme Procedure: sal? object

  31113.      Return '#t' if OBJECT is an object of type '<gdb:sal>'.  Otherwise

  31114.      return '#f'.

  31115. 

  31116.  -- Scheme Procedure: sal-valid? sal

  31117.      Return '#t' if SAL is valid, '#f' if not.  A '<gdb:sal>' object

  31118.      becomes invalid when the Symbol table object it refers to no longer

  31119.      exists in GDB.  All other '<gdb:sal>' procedures will throw an

  31120.      exception if it is invalid at the time the procedure is called.

  31121. 

  31122.  -- Scheme Procedure: sal-symtab sal

  31123.      Return the symbol table object ('<gdb:symtab>') for SAL.

  31124. 

  31125.  -- Scheme Procedure: sal-line sal

  31126.      Return the line number for SAL.

  31127. 

  31128.  -- Scheme Procedure: sal-pc sal

  31129.      Return the start of the address range occupied by code for SAL.

  31130. 

  31131.  -- Scheme Procedure: sal-last sal

  31132.      Return the end of the address range occupied by code for SAL.

  31133. 

  31134.  -- Scheme Procedure: find-pc-line pc

  31135.      Return the '<gdb:sal>' object corresponding to the PC value.  If an

  31136.      invalid value of PC is passed as an argument, then the 'symtab' and

  31137.      'line' attributes of the returned '<gdb:sal>' object will be '#f'

  31138.      and 0 respectively.

  31139. 

  31140. 

  31141. File: gdb.info,  Node: Breakpoints In Guile,  Next: Lazy Strings In Guile,  Prev: Symbol Tables In Guile,  Up: Guile API

  31142. 

  31143. 23.3.3.19 Manipulating breakpoints using Guile

  31144. ..............................................

  31145. 

  31146. Breakpoints in Guile are represented by objects of type

  31147. '<gdb:breakpoint>'.  New breakpoints can be created with the

  31148. 'make-breakpoint' Guile function, and then added to GDB with the

  31149. 'register-breakpoint!' Guile function.  This two-step approach is taken

  31150. to separate out the side-effect of adding the breakpoint to GDB from

  31151. 'make-breakpoint'.

  31152. 

  31153.    Support is also provided to view and manipulate breakpoints created

  31154. outside of Guile.

  31155. 

  31156.    The following breakpoint-related procedures are provided by the

  31157. '(gdb)' module:

  31158. 

  31159.  -- Scheme Procedure: make-breakpoint location [#:type type] [#:wp-class

  31160.           wp-class] [#:internal internal]

  31161.      Create a new breakpoint at LOCATION, a string naming the location

  31162.      of the breakpoint, or an expression that defines a watchpoint.  The

  31163.      contents can be any location recognized by the 'break' command, or

  31164.      in the case of a watchpoint, by the 'watch' command.

  31165. 

  31166.      The breakpoint is initially marked as 'invalid'.  The breakpoint is

  31167.      not usable until it has been registered with GDB with

  31168.      'register-breakpoint!', at which point it becomes 'valid'.  The

  31169.      result is the '<gdb:breakpoint>' object representing the

  31170.      breakpoint.

  31171. 

  31172.      The optional TYPE denotes the breakpoint to create.  This argument

  31173.      can be either 'BP_BREAKPOINT' or 'BP_WATCHPOINT', and defaults to

  31174.      'BP_BREAKPOINT'.

  31175. 

  31176.      The optional WP-CLASS argument defines the class of watchpoint to

  31177.      create, if TYPE is 'BP_WATCHPOINT'.  If a watchpoint class is not

  31178.      provided, it is assumed to be a 'WP_WRITE' class.

  31179. 

  31180.      The optional INTERNAL argument allows the breakpoint to become

  31181.      invisible to the user.  The breakpoint will neither be reported

  31182.      when registered, nor will it be listed in the output from 'info

  31183.      breakpoints' (but will be listed with the 'maint info breakpoints'

  31184.      command).  If an internal flag is not provided, the breakpoint is

  31185.      visible (non-internal).

  31186. 

  31187.      When a watchpoint is created, GDB will try to create a hardware

  31188.      assisted watchpoint.  If successful, the type of the watchpoint is

  31189.      changed from 'BP_WATCHPOINT' to 'BP_HARDWARE_WATCHPOINT' for

  31190.      'WP_WRITE', 'BP_READ_WATCHPOINT' for 'WP_READ', and

  31191.      'BP_ACCESS_WATCHPOINT' for 'WP_ACCESS'.  If not successful, the

  31192.      type of the watchpoint is left as 'WP_WATCHPOINT'.

  31193. 

  31194.      The available types are represented by constants defined in the

  31195.      'gdb' module:

  31196. 

  31197.      'BP_BREAKPOINT'

  31198.           Normal code breakpoint.

  31199. 

  31200.      'BP_WATCHPOINT'

  31201.           Watchpoint breakpoint.

  31202. 

  31203.      'BP_HARDWARE_WATCHPOINT'

  31204.           Hardware assisted watchpoint.  This value cannot be specified

  31205.           when creating the breakpoint.

  31206. 

  31207.      'BP_READ_WATCHPOINT'

  31208.           Hardware assisted read watchpoint.  This value cannot be

  31209.           specified when creating the breakpoint.

  31210. 

  31211.      'BP_ACCESS_WATCHPOINT'

  31212.           Hardware assisted access watchpoint.  This value cannot be

  31213.           specified when creating the breakpoint.

  31214. 

  31215.      The available watchpoint types represented by constants are defined

  31216.      in the '(gdb)' module:

  31217. 

  31218.      'WP_READ'

  31219.           Read only watchpoint.

  31220. 

  31221.      'WP_WRITE'

  31222.           Write only watchpoint.

  31223. 

  31224.      'WP_ACCESS'

  31225.           Read/Write watchpoint.

  31226. 

  31227.  -- Scheme Procedure: register-breakpoint! breakpoint

  31228.      Add BREAKPOINT, a '<gdb:breakpoint>' object, to GDB's list of

  31229.      breakpoints.  The breakpoint must have been created with

  31230.      'make-breakpoint'.  One cannot register breakpoints that have been

  31231.      created outside of Guile.  Once a breakpoint is registered it

  31232.      becomes 'valid'.  It is an error to register an already registered

  31233.      breakpoint.  The result is unspecified.

  31234. 

  31235.  -- Scheme Procedure: delete-breakpoint! breakpoint

  31236.      Remove BREAKPOINT from GDB's list of breakpoints.  This also

  31237.      invalidates the Guile BREAKPOINT object.  Any further attempt to

  31238.      access the object will throw an exception.

  31239. 

  31240.      If BREAKPOINT was created from Guile with 'make-breakpoint' it may

  31241.      be re-registered with GDB, in which case the breakpoint becomes

  31242.      valid again.

  31243. 

  31244.  -- Scheme Procedure: breakpoints

  31245.      Return a list of all breakpoints.  Each element of the list is a

  31246.      '<gdb:breakpoint>' object.

  31247. 

  31248.  -- Scheme Procedure: breakpoint? object

  31249.      Return '#t' if OBJECT is a '<gdb:breakpoint>' object, and '#f'

  31250.      otherwise.

  31251. 

  31252.  -- Scheme Procedure: breakpoint-valid? breakpoint

  31253.      Return '#t' if BREAKPOINT is valid, '#f' otherwise.  Breakpoints

  31254.      created with 'make-breakpoint' are marked as invalid until they are

  31255.      registered with GDB with 'register-breakpoint!'.  A

  31256.      '<gdb:breakpoint>' object can become invalid if the user deletes

  31257.      the breakpoint.  In this case, the object still exists, but the

  31258.      underlying breakpoint does not.  In the cases of watchpoint scope,

  31259.      the watchpoint remains valid even if execution of the inferior

  31260.      leaves the scope of that watchpoint.

  31261. 

  31262.  -- Scheme Procedure: breakpoint-number breakpoint

  31263.      Return the breakpoint's number -- the identifier used by the user

  31264.      to manipulate the breakpoint.

  31265. 

  31266.  -- Scheme Procedure: breakpoint-type breakpoint

  31267.      Return the breakpoint's type -- the identifier used to determine

  31268.      the actual breakpoint type or use-case.

  31269. 

  31270.  -- Scheme Procedure: breakpoint-visible? breakpoint

  31271.      Return '#t' if the breakpoint is visible to the user when hit, or

  31272.      when the 'info breakpoints' command is run.  Otherwise return '#f'.

  31273. 

  31274.  -- Scheme Procedure: breakpoint-location breakpoint

  31275.      Return the location of the breakpoint, as specified by the user.

  31276.      It is a string.  If the breakpoint does not have a location (that

  31277.      is, it is a watchpoint) return '#f'.

  31278. 

  31279.  -- Scheme Procedure: breakpoint-expression breakpoint

  31280.      Return the breakpoint expression, as specified by the user.  It is

  31281.      a string.  If the breakpoint does not have an expression (the

  31282.      breakpoint is not a watchpoint) return '#f'.

  31283. 

  31284.  -- Scheme Procedure: breakpoint-enabled? breakpoint

  31285.      Return '#t' if the breakpoint is enabled, and '#f' otherwise.

  31286. 

  31287.  -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag

  31288.      Set the enabled state of BREAKPOINT to FLAG.  If flag is '#f' it is

  31289.      disabled, otherwise it is enabled.

  31290. 

  31291.  -- Scheme Procedure: breakpoint-silent? breakpoint

  31292.      Return '#t' if the breakpoint is silent, and '#f' otherwise.

  31293. 

  31294.      Note that a breakpoint can also be silent if it has commands and

  31295.      the first command is 'silent'.  This is not reported by the

  31296.      'silent' attribute.

  31297. 

  31298.  -- Scheme Procedure: set-breakpoint-silent! breakpoint flag

  31299.      Set the silent state of BREAKPOINT to FLAG.  If flag is '#f' the

  31300.      breakpoint is made silent, otherwise it is made non-silent (or

  31301.      noisy).

  31302. 

  31303.  -- Scheme Procedure: breakpoint-ignore-count breakpoint

  31304.      Return the ignore count for BREAKPOINT.

  31305. 

  31306.  -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count

  31307.      Set the ignore count for BREAKPOINT to COUNT.

  31308. 

  31309.  -- Scheme Procedure: breakpoint-hit-count breakpoint

  31310.      Return hit count of BREAKPOINT.

  31311. 

  31312.  -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count

  31313.      Set the hit count of BREAKPOINT to COUNT.  At present, COUNT must

  31314.      be zero.

  31315. 

  31316.  -- Scheme Procedure: breakpoint-thread breakpoint

  31317.      Return the global-thread-id for thread-specific breakpoint

  31318.      BREAKPOINT.  Return #f if BREAKPOINT is not thread-specific.

  31319. 

  31320.  -- Scheme Procedure: set-breakpoint-thread! breakpoint

  31321.           global-thread-id|#f

  31322.      Set the thread-id for BREAKPOINT to GLOBAL-THREAD-ID If set to

  31323.      '#f', the breakpoint is no longer thread-specific.

  31324. 

  31325.  -- Scheme Procedure: breakpoint-task breakpoint

  31326.      If the breakpoint is Ada task-specific, return the Ada task id.  If

  31327.      the breakpoint is not task-specific (or the underlying language is

  31328.      not Ada), return '#f'.

  31329. 

  31330.  -- Scheme Procedure: set-breakpoint-task! breakpoint task

  31331.      Set the Ada task of BREAKPOINT to TASK.  If set to '#f', the

  31332.      breakpoint is no longer task-specific.

  31333. 

  31334.  -- Scheme Procedure: breakpoint-condition breakpoint

  31335.      Return the condition of BREAKPOINT, as specified by the user.  It

  31336.      is a string.  If there is no condition, return '#f'.

  31337. 

  31338.  -- Scheme Procedure: set-breakpoint-condition! breakpoint condition

  31339.      Set the condition of BREAKPOINT to CONDITION, which must be a

  31340.      string.  If set to '#f' then the breakpoint becomes unconditional.

  31341. 

  31342.  -- Scheme Procedure: breakpoint-stop breakpoint

  31343.      Return the stop predicate of BREAKPOINT.  See

  31344.      'set-breakpoint-stop!' below in this section.

  31345. 

  31346.  -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f

  31347.      Set the stop predicate of BREAKPOINT.  The predicate PROCEDURE

  31348.      takes one argument: the <gdb:breakpoint> object.  If this predicate

  31349.      is set to a procedure then it is invoked whenever the inferior

  31350.      reaches this breakpoint.  If it returns '#t', or any non-'#f'

  31351.      value, then the inferior is stopped, otherwise the inferior will

  31352.      continue.

  31353. 

  31354.      If there are multiple breakpoints at the same location with a

  31355.      'stop' predicate, each one will be called regardless of the return

  31356.      status of the previous.  This ensures that all 'stop' predicates

  31357.      have a chance to execute at that location.  In this scenario if one

  31358.      of the methods returns '#t' but the others return '#f', the

  31359.      inferior will still be stopped.

  31360. 

  31361.      You should not alter the execution state of the inferior (i.e.,

  31362.      step, next, etc.), alter the current frame context (i.e., change

  31363.      the current active frame), or alter, add or delete any breakpoint.

  31364.      As a general rule, you should not alter any data within GDB or the

  31365.      inferior at this time.

  31366. 

  31367.      Example 'stop' implementation:

  31368. 

  31369.           (define (my-stop? bkpt)

  31370.             (let ((int-val (parse-and-eval "foo")))

  31371.               (value=? int-val 3)))

  31372.           (define bkpt (make-breakpoint "main.c:42"))

  31373.           (register-breakpoint! bkpt)

  31374.           (set-breakpoint-stop! bkpt my-stop?)

  31375. 

  31376.  -- Scheme Procedure: breakpoint-commands breakpoint

  31377.      Return the commands attached to BREAKPOINT as a string, or '#f' if

  31378.      there are none.

  31379. 

  31380. 

  31381. File: gdb.info,  Node: Lazy Strings In Guile,  Next: Architectures In Guile,  Prev: Breakpoints In Guile,  Up: Guile API

  31382. 

  31383. 23.3.3.20 Guile representation of lazy strings.

  31384. ...............................................

  31385. 

  31386. A "lazy string" is a string whose contents is not retrieved or encoded

  31387. until it is needed.

  31388. 

  31389.    A '<gdb:lazy-string>' is represented in GDB as an 'address' that

  31390. points to a region of memory, an 'encoding' that will be used to encode

  31391. that region of memory, and a 'length' to delimit the region of memory

  31392. that represents the string.  The difference between a

  31393. '<gdb:lazy-string>' and a string wrapped within a '<gdb:value>' is that

  31394. a '<gdb:lazy-string>' will be treated differently by GDB when printing.

  31395. A '<gdb:lazy-string>' is retrieved and encoded during printing, while a

  31396. '<gdb:value>' wrapping a string is immediately retrieved and encoded on

  31397. creation.

  31398. 

  31399.    The following lazy-string-related procedures are provided by the

  31400. '(gdb)' module:

  31401. 

  31402.  -- Scheme Procedure: lazy-string? object

  31403.      Return '#t' if OBJECT is an object of type '<gdb:lazy-string>'.

  31404.      Otherwise return '#f'.

  31405. 

  31406.  -- Scheme Procedure: lazy-string-address lazy-sring

  31407.      Return the address of LAZY-STRING.

  31408. 

  31409.  -- Scheme Procedure: lazy-string-length lazy-string

  31410.      Return the length of LAZY-STRING in characters.  If the length is

  31411.      -1, then the string will be fetched and encoded up to the first

  31412.      null of appropriate width.

  31413. 

  31414.  -- Scheme Procedure: lazy-string-encoding lazy-string

  31415.      Return the encoding that will be applied to LAZY-STRING when the

  31416.      string is printed by GDB.  If the encoding is not set, or contains

  31417.      an empty string, then GDB will select the most appropriate encoding

  31418.      when the string is printed.

  31419. 

  31420.  -- Scheme Procedure: lazy-string-type lazy-string

  31421.      Return the type that is represented by LAZY-STRING's type.  For a

  31422.      lazy string this is a pointer or array type.  To resolve this to

  31423.      the lazy string's character type, use 'type-target-type'.  *Note

  31424.      Types In Guile::.

  31425. 

  31426.  -- Scheme Procedure: lazy-string->value lazy-string

  31427.      Convert the '<gdb:lazy-string>' to a '<gdb:value>'.  This value

  31428.      will point to the string in memory, but will lose all the delayed

  31429.      retrieval, encoding and handling that GDB applies to a

  31430.      '<gdb:lazy-string>'.

  31431. 

  31432. 

  31433. File: gdb.info,  Node: Architectures In Guile,  Next: Disassembly In Guile,  Prev: Lazy Strings In Guile,  Up: Guile API

  31434. 

  31435. 23.3.3.21 Guile representation of architectures

  31436. ...............................................

  31437. 

  31438. GDB uses architecture specific parameters and artifacts in a number of

  31439. its various computations.  An architecture is represented by an instance

  31440. of the '<gdb:arch>' class.

  31441. 

  31442.    The following architecture-related procedures are provided by the

  31443. '(gdb)' module:

  31444. 

  31445.  -- Scheme Procedure: arch? object

  31446.      Return '#t' if OBJECT is an object of type '<gdb:arch>'.  Otherwise

  31447.      return '#f'.

  31448. 

  31449.  -- Scheme Procedure: current-arch

  31450.      Return the current architecture as a '<gdb:arch>' object.

  31451. 

  31452.  -- Scheme Procedure: arch-name arch

  31453.      Return the name (string value) of '<gdb:arch>' ARCH.

  31454. 

  31455.  -- Scheme Procedure: arch-charset arch

  31456.      Return name of target character set of '<gdb:arch>' ARCH.

  31457. 

  31458.  -- Scheme Procedure: arch-wide-charset

  31459.      Return name of target wide character set of '<gdb:arch>' ARCH.

  31460. 

  31461.    Each architecture provides a set of predefined types, obtained by the

  31462. following functions.

  31463. 

  31464.  -- Scheme Procedure: arch-void-type arch

  31465.      Return the '<gdb:type>' object for a 'void' type of architecture

  31466.      ARCH.

  31467. 

  31468.  -- Scheme Procedure: arch-char-type arch

  31469.      Return the '<gdb:type>' object for a 'char' type of architecture

  31470.      ARCH.

  31471. 

  31472.  -- Scheme Procedure: arch-short-type arch

  31473.      Return the '<gdb:type>' object for a 'short' type of architecture

  31474.      ARCH.

  31475. 

  31476.  -- Scheme Procedure: arch-int-type arch

  31477.      Return the '<gdb:type>' object for an 'int' type of architecture

  31478.      ARCH.

  31479. 

  31480.  -- Scheme Procedure: arch-long-type arch

  31481.      Return the '<gdb:type>' object for a 'long' type of architecture

  31482.      ARCH.

  31483. 

  31484.  -- Scheme Procedure: arch-schar-type arch

  31485.      Return the '<gdb:type>' object for a 'signed char' type of

  31486.      architecture ARCH.

  31487. 

  31488.  -- Scheme Procedure: arch-uchar-type arch

  31489.      Return the '<gdb:type>' object for an 'unsigned char' type of

  31490.      architecture ARCH.

  31491. 

  31492.  -- Scheme Procedure: arch-ushort-type arch

  31493.      Return the '<gdb:type>' object for an 'unsigned short' type of

  31494.      architecture ARCH.

  31495. 

  31496.  -- Scheme Procedure: arch-uint-type arch

  31497.      Return the '<gdb:type>' object for an 'unsigned int' type of

  31498.      architecture ARCH.

  31499. 

  31500.  -- Scheme Procedure: arch-ulong-type arch

  31501.      Return the '<gdb:type>' object for an 'unsigned long' type of

  31502.      architecture ARCH.

  31503. 

  31504.  -- Scheme Procedure: arch-float-type arch

  31505.      Return the '<gdb:type>' object for a 'float' type of architecture

  31506.      ARCH.

  31507. 

  31508.  -- Scheme Procedure: arch-double-type arch

  31509.      Return the '<gdb:type>' object for a 'double' type of architecture

  31510.      ARCH.

  31511. 

  31512.  -- Scheme Procedure: arch-longdouble-type arch

  31513.      Return the '<gdb:type>' object for a 'long double' type of

  31514.      architecture ARCH.

  31515. 

  31516.  -- Scheme Procedure: arch-bool-type arch

  31517.      Return the '<gdb:type>' object for a 'bool' type of architecture

  31518.      ARCH.

  31519. 

  31520.  -- Scheme Procedure: arch-longlong-type arch

  31521.      Return the '<gdb:type>' object for a 'long long' type of

  31522.      architecture ARCH.

  31523. 

  31524.  -- Scheme Procedure: arch-ulonglong-type arch

  31525.      Return the '<gdb:type>' object for an 'unsigned long long' type of

  31526.      architecture ARCH.

  31527. 

  31528.  -- Scheme Procedure: arch-int8-type arch

  31529.      Return the '<gdb:type>' object for an 'int8' type of architecture

  31530.      ARCH.

  31531. 

  31532.  -- Scheme Procedure: arch-uint8-type arch

  31533.      Return the '<gdb:type>' object for a 'uint8' type of architecture

  31534.      ARCH.

  31535. 

  31536.  -- Scheme Procedure: arch-int16-type arch

  31537.      Return the '<gdb:type>' object for an 'int16' type of architecture

  31538.      ARCH.

  31539. 

  31540.  -- Scheme Procedure: arch-uint16-type arch

  31541.      Return the '<gdb:type>' object for a 'uint16' type of architecture

  31542.      ARCH.

  31543. 

  31544.  -- Scheme Procedure: arch-int32-type arch

  31545.      Return the '<gdb:type>' object for an 'int32' type of architecture

  31546.      ARCH.

  31547. 

  31548.  -- Scheme Procedure: arch-uint32-type arch

  31549.      Return the '<gdb:type>' object for a 'uint32' type of architecture

  31550.      ARCH.

  31551. 

  31552.  -- Scheme Procedure: arch-int64-type arch

  31553.      Return the '<gdb:type>' object for an 'int64' type of architecture

  31554.      ARCH.

  31555. 

  31556.  -- Scheme Procedure: arch-uint64-type arch

  31557.      Return the '<gdb:type>' object for a 'uint64' type of architecture

  31558.      ARCH.

  31559. 

  31560.    Example:

  31561. 

  31562.      (gdb) guile (type-name (arch-uchar-type (current-arch)))

  31563.      "unsigned char"

  31564. 

  31565. 

  31566. File: gdb.info,  Node: Disassembly In Guile,  Next: I/O Ports in Guile,  Prev: Architectures In Guile,  Up: Guile API

  31567. 

  31568. 23.3.3.22 Disassembly In Guile

  31569. ..............................

  31570. 

  31571. The disassembler can be invoked from Scheme code.  Furthermore, the

  31572. disassembler can take a Guile port as input, allowing one to disassemble

  31573. from any source, and not just target memory.

  31574. 

  31575.  -- Scheme Procedure: arch-disassemble arch start-pc [#:port port]

  31576.           [#:offset offset] [#:size size] [#:count count]

  31577.      Return a list of disassembled instructions starting from the memory

  31578.      address START-PC.

  31579. 

  31580.      The optional argument PORT specifies the input port to read bytes

  31581.      from.  If PORT is '#f' then bytes are read from target memory.

  31582. 

  31583.      The optional argument OFFSET specifies the address offset of the

  31584.      first byte in PORT.  This is useful, for example, when PORT

  31585.      specifies a 'bytevector' and you want the bytevector to be

  31586.      disassembled as if it came from that address.  The START-PC passed

  31587.      to the reader for PORT is offset by the same amount.

  31588. 

  31589.      Example:

  31590.           (gdb) guile (use-modules (rnrs io ports))

  31591.           (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))

  31592.           (gdb) guile (define mem (open-memory #:start pc))

  31593.           (gdb) guile (define bv (get-bytevector-n mem 10))

  31594.           (gdb) guile (define bv-port (open-bytevector-input-port bv))

  31595.           (gdb) guile (define arch (current-arch))

  31596.           (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)

  31597.           (((address . 4195516) (asm . "mov    $0x4005c8,%edi") (length . 5)))

  31598. 

  31599.      The optional arguments SIZE and COUNT determine the number of

  31600.      instructions in the returned list.  If either SIZE or COUNT is

  31601.      specified as zero, then no instructions are disassembled and an

  31602.      empty list is returned.  If both the optional arguments SIZE and

  31603.      COUNT are specified, then a list of at most COUNT disassembled

  31604.      instructions whose start address falls in the closed memory address

  31605.      interval from START-PC to (START-PC + SIZE - 1) are returned.  If

  31606.      SIZE is not specified, but COUNT is specified, then COUNT number of

  31607.      instructions starting from the address START-PC are returned.  If

  31608.      COUNT is not specified but SIZE is specified, then all instructions

  31609.      whose start address falls in the closed memory address interval

  31610.      from START-PC to (START-PC + SIZE - 1) are returned.  If neither

  31611.      SIZE nor COUNT are specified, then a single instruction at START-PC

  31612.      is returned.

  31613. 

  31614.      Each element of the returned list is an alist (associative list)

  31615.      with the following keys:

  31616. 

  31617.      'address'

  31618.           The value corresponding to this key is a Guile integer of the

  31619.           memory address of the instruction.

  31620. 

  31621.      'asm'

  31622.           The value corresponding to this key is a string value which

  31623.           represents the instruction with assembly language mnemonics.

  31624.           The assembly language flavor used is the same as that

  31625.           specified by the current CLI variable 'disassembly-flavor'.

  31626.           *Note Machine Code::.

  31627. 

  31628.      'length'

  31629.           The value corresponding to this key is the length of the

  31630.           instruction in bytes.

  31631. 

  31632. 

  31633. File: gdb.info,  Node: I/O Ports in Guile,  Next: Memory Ports in Guile,  Prev: Disassembly In Guile,  Up: Guile API

  31634. 

  31635. 23.3.3.23 I/O Ports in Guile

  31636. ............................

  31637. 

  31638.  -- Scheme Procedure: input-port

  31639.      Return GDB's input port as a Guile port object.

  31640. 

  31641.  -- Scheme Procedure: output-port

  31642.      Return GDB's output port as a Guile port object.

  31643. 

  31644.  -- Scheme Procedure: error-port

  31645.      Return GDB's error port as a Guile port object.

  31646. 

  31647.  -- Scheme Procedure: stdio-port? object

  31648.      Return '#t' if OBJECT is a GDB stdio port.  Otherwise return '#f'.

  31649. 

  31650. 

  31651. File: gdb.info,  Node: Memory Ports in Guile,  Next: Iterators In Guile,  Prev: I/O Ports in Guile,  Up: Guile API

  31652. 

  31653. 23.3.3.24 Memory Ports in Guile

  31654. ...............................

  31655. 

  31656. GDB provides a 'port' interface to target memory.  This allows Guile

  31657. code to read/write target memory using Guile's port and bytevector

  31658. functionality.  The main routine is 'open-memory' which returns a port

  31659. object.  One can then read/write memory using that object.

  31660. 

  31661.  -- Scheme Procedure: open-memory [#:mode mode] [#:start address]

  31662.           [#:size size]

  31663.      Return a port object that can be used for reading and writing

  31664.      memory.  The port will be open according to MODE, which is the

  31665.      standard mode argument to Guile port open routines, except that the

  31666.      '"a"' and '"l"' modes are not supported.  *Note (guile)File

  31667.      Ports::.  The '"b"' (binary) character may be present, but is

  31668.      ignored: memory ports are binary only.  If '"0"' is appended then

  31669.      the port is marked as unbuffered.  The default is '"r"', read-only

  31670.      and buffered.

  31671. 

  31672.      The chunk of memory that can be accessed can be bounded.  If both

  31673.      START and SIZE are unspecified, all of memory can be accessed.  If

  31674.      only START is specified, all of memory from that point on can be

  31675.      accessed.  If only SIZE if specified, all memory in the range

  31676.      [0,SIZE) can be accessed.  If both are specified, all memory in the

  31677.      rane [START,START+SIZE) can be accessed.

  31678. 

  31679.  -- Scheme Procedure: memory-port?

  31680.      Return '#t' if OBJECT is an object of type '<gdb:memory-port>'.

  31681.      Otherwise return '#f'.

  31682. 

  31683.  -- Scheme Procedure: memory-port-range memory-port

  31684.      Return the range of '<gdb:memory-port>' MEMORY-PORT as a list of

  31685.      two elements: '(start end)'.  The range is START to END inclusive.

  31686. 

  31687.  -- Scheme Procedure: memory-port-read-buffer-size memory-port

  31688.      Return the size of the read buffer of '<gdb:memory-port>'

  31689.      MEMORY-PORT.

  31690. 

  31691.      This procedure is deprecated and will be removed in GDB 11.  It

  31692.      returns 0 when using Guile 2.2 or later.

  31693. 

  31694.  -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size

  31695.      Set the size of the read buffer of '<gdb:memory-port>' MEMORY-PORT

  31696.      to SIZE.  The result is unspecified.

  31697. 

  31698.      This procedure is deprecated and will be removed in GDB 11.  When

  31699.      GDB is built with Guile 2.2 or later, you can call 'setvbuf'

  31700.      instead (*note 'setvbuf': (guile)Buffering.).

  31701. 

  31702.  -- Scheme Procedure: memory-port-write-buffer-size memory-port

  31703.      Return the size of the write buffer of '<gdb:memory-port>'

  31704.      MEMORY-PORT.

  31705. 

  31706.      This procedure is deprecated and will be removed in GDB 11.  It

  31707.      returns 0 when GDB is built with Guile 2.2 or later.

  31708. 

  31709.  -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port

  31710.           size

  31711.      Set the size of the write buffer of '<gdb:memory-port>' MEMORY-PORT

  31712.      to SIZE.  The result is unspecified.

  31713. 

  31714.      This procedure is deprecated and will be removed in GDB 11.  When

  31715.      GDB is built with Guile 2.2 or later, you can call 'setvbuf'

  31716.      instead.

  31717. 

  31718.    A memory port is closed like any other port, with 'close-port'.

  31719. 

  31720.    Combined with Guile's 'bytevectors', memory ports provide a lot of

  31721. utility.  For example, to fill a buffer of 10 integers in memory, one

  31722. can do something like the following.

  31723. 

  31724.      ;; In the program: int buffer[10];

  31725.      (use-modules (rnrs bytevectors))

  31726.      (use-modules (rnrs io ports))

  31727.      (define addr (parse-and-eval "buffer"))

  31728.      (define n 10)

  31729.      (define byte-size (* n 4))

  31730.      (define mem-port (open-memory #:mode "r+" #:start

  31731.                                    (value->integer addr) #:size byte-size))

  31732.      (define byte-vec (make-bytevector byte-size))

  31733.      (do ((i 0 (+ i 1)))

  31734.          ((>= i n))

  31735.          (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))

  31736.      (put-bytevector mem-port byte-vec)

  31737.      (close-port mem-port)

  31738. 

  31739. 

  31740. File: gdb.info,  Node: Iterators In Guile,  Prev: Memory Ports in Guile,  Up: Guile API

  31741. 

  31742. 23.3.3.25 Iterators In Guile

  31743. ............................

  31744. 

  31745. A simple iterator facility is provided to allow, for example, iterating

  31746. over the set of program symbols without having to first construct a list

  31747. of all of them.  A useful contribution would be to add support for SRFI

  31748. 41 and SRFI 45.

  31749. 

  31750.  -- Scheme Procedure: make-iterator object progress next!

  31751.      A '<gdb:iterator>' object is constructed with the 'make-iterator'

  31752.      procedure.  It takes three arguments: the object to be iterated

  31753.      over, an object to record the progress of the iteration, and a

  31754.      procedure to return the next element in the iteration, or an

  31755.      implementation chosen value to denote the end of iteration.

  31756. 

  31757.      By convention, end of iteration is marked with

  31758.      '(end-of-iteration)', and may be tested with the

  31759.      'end-of-iteration?' predicate.  The result of '(end-of-iteration)'

  31760.      is chosen so that it is not otherwise used by the '(gdb)' module.

  31761.      If you are using '<gdb:iterator>' in your own code it is your

  31762.      responsibility to maintain this invariant.

  31763. 

  31764.      A trivial example for illustration's sake:

  31765. 

  31766.           (use-modules (gdb iterator))

  31767.           (define my-list (list 1 2 3))

  31768.           (define iter

  31769.             (make-iterator my-list my-list

  31770.                            (lambda (iter)

  31771.                              (let ((l (iterator-progress iter)))

  31772.                                (if (eq? l '())

  31773.                                    (end-of-iteration)

  31774.                                    (begin

  31775.                                      (set-iterator-progress! iter (cdr l))

  31776.                                      (car l)))))))

  31777. 

  31778.      Here is a slightly more realistic example, which computes a list of

  31779.      all the functions in 'my-global-block'.

  31780. 

  31781.           (use-modules (gdb iterator))

  31782.           (define this-sal (find-pc-line (frame-pc (selected-frame))))

  31783.           (define this-symtab (sal-symtab this-sal))

  31784.           (define this-global-block (symtab-global-block this-symtab))

  31785.           (define syms-iter (make-block-symbols-iterator this-global-block))

  31786.           (define functions (iterator-filter symbol-function? syms-iter))

  31787. 

  31788.  -- Scheme Procedure: iterator? object

  31789.      Return '#t' if OBJECT is a '<gdb:iterator>' object.  Otherwise

  31790.      return '#f'.

  31791. 

  31792.  -- Scheme Procedure: iterator-object iterator

  31793.      Return the first argument that was passed to 'make-iterator'.  This

  31794.      is the object being iterated over.

  31795. 

  31796.  -- Scheme Procedure: iterator-progress iterator

  31797.      Return the object tracking iteration progress.

  31798. 

  31799.  -- Scheme Procedure: set-iterator-progress! iterator new-value

  31800.      Set the object tracking iteration progress.

  31801. 

  31802.  -- Scheme Procedure: iterator-next! iterator

  31803.      Invoke the procedure that was the third argument to

  31804.      'make-iterator', passing it one argument, the '<gdb:iterator>'

  31805.      object.  The result is either the next element in the iteration, or

  31806.      an end marker as implemented by the 'next!' procedure.  By

  31807.      convention the end marker is the result of '(end-of-iteration)'.

  31808. 

  31809.  -- Scheme Procedure: end-of-iteration

  31810.      Return the Scheme object that denotes end of iteration.

  31811. 

  31812.  -- Scheme Procedure: end-of-iteration? object

  31813.      Return '#t' if OBJECT is the end of iteration marker.  Otherwise

  31814.      return '#f'.

  31815. 

  31816.    These functions are provided by the '(gdb iterator)' module to assist

  31817. in using iterators.

  31818. 

  31819.  -- Scheme Procedure: make-list-iterator list

  31820.      Return a '<gdb:iterator>' object that will iterate over LIST.

  31821. 

  31822.  -- Scheme Procedure: iterator->list iterator

  31823.      Return the elements pointed to by ITERATOR as a list.

  31824. 

  31825.  -- Scheme Procedure: iterator-map proc iterator

  31826.      Return the list of objects obtained by applying PROC to the object

  31827.      pointed to by ITERATOR and to each subsequent object.

  31828. 

  31829.  -- Scheme Procedure: iterator-for-each proc iterator

  31830.      Apply PROC to each element pointed to by ITERATOR.  The result is

  31831.      unspecified.

  31832. 

  31833.  -- Scheme Procedure: iterator-filter pred iterator

  31834.      Return the list of elements pointed to by ITERATOR that satisfy

  31835.      PRED.

  31836. 

  31837.  -- Scheme Procedure: iterator-until pred iterator

  31838.      Run ITERATOR until the result of '(pred element)' is true and

  31839.      return that as the result.  Otherwise return '#f'.

  31840. 

  31841. 

  31842. File: gdb.info,  Node: Guile Auto-loading,  Next: Guile Modules,  Prev: Guile API,  Up: Guile

  31843. 

  31844. 23.3.4 Guile Auto-loading

  31845. -------------------------

  31846. 

  31847. When a new object file is read (for example, due to the 'file' command,

  31848. or because the inferior has loaded a shared library), GDB will look for

  31849. Guile support scripts in two ways: 'OBJFILE-gdb.scm' and the

  31850. '.debug_gdb_scripts' section.  *Note Auto-loading extensions::.

  31851. 

  31852.    The auto-loading feature is useful for supplying application-specific

  31853. debugging commands and scripts.

  31854. 

  31855.    Auto-loading can be enabled or disabled, and the list of auto-loaded

  31856. scripts can be printed.

  31857. 

  31858. 'set auto-load guile-scripts [on|off]'

  31859.      Enable or disable the auto-loading of Guile scripts.

  31860. 

  31861. 'show auto-load guile-scripts'

  31862.      Show whether auto-loading of Guile scripts is enabled or disabled.

  31863. 

  31864. 'info auto-load guile-scripts [REGEXP]'

  31865.      Print the list of all Guile scripts that GDB auto-loaded.

  31866. 

  31867.      Also printed is the list of Guile scripts that were mentioned in

  31868.      the '.debug_gdb_scripts' section and were not found.  This is

  31869.      useful because their names are not printed when GDB tries to load

  31870.      them and fails.  There may be many of them, and printing an error

  31871.      message for each one is problematic.

  31872. 

  31873.      If REGEXP is supplied only Guile scripts with matching names are

  31874.      printed.

  31875. 

  31876.      Example:

  31877. 

  31878.           (gdb) info auto-load guile-scripts

  31879.           Loaded Script

  31880.           Yes    scm-section-script.scm

  31881.                  full name: /tmp/scm-section-script.scm

  31882.           No     my-foo-pretty-printers.scm

  31883. 

  31884.    When reading an auto-loaded file, GDB sets the "current objfile".

  31885. This is available via the 'current-objfile' procedure (*note Objfiles In

  31886. Guile::).  This can be useful for registering objfile-specific

  31887. pretty-printers.

  31888. 

  31889. 

  31890. File: gdb.info,  Node: Guile Modules,  Prev: Guile Auto-loading,  Up: Guile

  31891. 

  31892. 23.3.5 Guile Modules

  31893. --------------------

  31894. 

  31895. GDB comes with several modules to assist writing Guile code.

  31896. 

  31897. * Menu:

  31898. 

  31899. * Guile Printing Module::  Building and registering pretty-printers

  31900. * Guile Types Module::     Utilities for working with types

  31901. 

  31902. 

  31903. File: gdb.info,  Node: Guile Printing Module,  Next: Guile Types Module,  Up: Guile Modules

  31904. 

  31905. 23.3.5.1 Guile Printing Module

  31906. ..............................

  31907. 

  31908. This module provides a collection of utilities for working with

  31909. pretty-printers.

  31910. 

  31911.    Usage:

  31912. 

  31913.      (use-modules (gdb printing))

  31914. 

  31915.  -- Scheme Procedure: prepend-pretty-printer! object printer

  31916.      Add PRINTER to the front of the list of pretty-printers for OBJECT.

  31917.      The OBJECT must either be a '<gdb:objfile>' object, or '#f' in

  31918.      which case PRINTER is added to the global list of printers.

  31919. 

  31920.  -- Scheme Procecure: append-pretty-printer! object printer

  31921.      Add PRINTER to the end of the list of pretty-printers for OBJECT.

  31922.      The OBJECT must either be a '<gdb:objfile>' object, or '#f' in

  31923.      which case PRINTER is added to the global list of printers.

  31924. 

  31925. 

  31926. File: gdb.info,  Node: Guile Types Module,  Prev: Guile Printing Module,  Up: Guile Modules

  31927. 

  31928. 23.3.5.2 Guile Types Module

  31929. ...........................

  31930. 

  31931. This module provides a collection of utilities for working with

  31932. '<gdb:type>' objects.

  31933. 

  31934.    Usage:

  31935. 

  31936.      (use-modules (gdb types))

  31937. 

  31938.  -- Scheme Procedure: get-basic-type type

  31939.      Return TYPE with const and volatile qualifiers stripped, and with

  31940.      typedefs and C++ references converted to the underlying type.

  31941. 

  31942.      C++ example:

  31943. 

  31944.           typedef const int const_int;

  31945.           const_int foo (3);

  31946.           const_int& foo_ref (foo);

  31947.           int main () { return 0; }

  31948. 

  31949.      Then in gdb:

  31950. 

  31951.           (gdb) start

  31952.           (gdb) guile (use-modules (gdb) (gdb types))

  31953.           (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))

  31954.           (gdb) guile (get-basic-type (value-type foo-ref))

  31955.           int

  31956. 

  31957.  -- Scheme Procedure: type-has-field-deep? type field

  31958.      Return '#t' if TYPE, assumed to be a type with fields (e.g., a

  31959.      structure or union), has field FIELD.  Otherwise return '#f'.  This

  31960.      searches baseclasses, whereas 'type-has-field?' does not.

  31961. 

  31962.  -- Scheme Procedure: make-enum-hashtable enum-type

  31963.      Return a Guile hash table produced from ENUM-TYPE.  Elements in the

  31964.      hash table are referenced with 'hashq-ref'.

  31965. 

  31966. 

  31967. File: gdb.info,  Node: Auto-loading extensions,  Next: Multiple Extension Languages,  Prev: Guile,  Up: Extending GDB

  31968. 

  31969. 23.4 Auto-loading extensions

  31970. ============================

  31971. 

  31972. GDB provides two mechanisms for automatically loading extensions when a

  31973. new object file is read (for example, due to the 'file' command, or

  31974. because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' and

  31975. the '.debug_gdb_scripts' section of modern file formats like ELF.

  31976. 

  31977. * Menu:

  31978. 

  31979. * objfile-gdb.ext file: objfile-gdbdotext file.  The 'OBJFILE-gdb.EXT' file

  31980. * .debug_gdb_scripts section: dotdebug_gdb_scripts section.  The '.debug_gdb_scripts' section

  31981. * Which flavor to choose?::

  31982. 

  31983.    The auto-loading feature is useful for supplying application-specific

  31984. debugging commands and features.

  31985. 

  31986.    Auto-loading can be enabled or disabled, and the list of auto-loaded

  31987. scripts can be printed.  See the 'auto-loading' section of each

  31988. extension language for more information.  For GDB command files see

  31989. *note Auto-loading sequences::.  For Python files see *note Python

  31990. Auto-loading::.

  31991. 

  31992.    Note that loading of this script file also requires accordingly

  31993. configured 'auto-load safe-path' (*note Auto-loading safe path::).

  31994. 

  31995. 

  31996. File: gdb.info,  Node: objfile-gdbdotext file,  Next: dotdebug_gdb_scripts section,  Up: Auto-loading extensions

  31997. 

  31998. 23.4.1 The 'OBJFILE-gdb.EXT' file

  31999. ---------------------------------

  32000. 

  32001. When a new object file is read, GDB looks for a file named

  32002. 'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the

  32003. object file's name and where EXT is the file extension for the extension

  32004. language:

  32005. 

  32006. 'OBJFILE-gdb.gdb'

  32007.      GDB's own command language

  32008. 'OBJFILE-gdb.py'

  32009.      Python

  32010. 'OBJFILE-gdb.scm'

  32011.      Guile

  32012. 

  32013.    SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is

  32014. absolute, following all symlinks, and resolving '.' and '..' components,

  32015. and appending the '-gdb.EXT' suffix.  If this file exists and is

  32016. readable, GDB will evaluate it as a script in the specified extension

  32017. language.

  32018. 

  32019.    If this file does not exist, then GDB will look for SCRIPT-NAME file

  32020. in all of the directories as specified below.  (On MS-Windows/MS-DOS,

  32021. the drive letter of the executable's leading directories is converted to

  32022. a one-letter subdirectory, i.e. 'd:/usr/bin/' is converted to

  32023. '/d/usr/bin/', because Windows filesystems disallow colons in file

  32024. names.)

  32025. 

  32026.    Note that loading of these files requires an accordingly configured

  32027. 'auto-load safe-path' (*note Auto-loading safe path::).

  32028. 

  32029.    For object files using '.exe' suffix GDB tries to load first the

  32030. scripts normally according to its '.exe' filename.  But if no scripts

  32031. are found GDB also tries script filenames matching the object file

  32032. without its '.exe' suffix.  This '.exe' stripping is case insensitive

  32033. and it is attempted on any platform.  This makes the script filenames

  32034. compatible between Unix and MS-Windows hosts.

  32035. 

  32036. 'set auto-load scripts-directory [DIRECTORIES]'

  32037.      Control GDB auto-loaded scripts location.  Multiple directory

  32038.      entries may be delimited by the host platform path separator in use

  32039.      (':' on Unix, ';' on MS-Windows and MS-DOS).

  32040. 

  32041.      Each entry here needs to be covered also by the security setting

  32042.      'set auto-load safe-path' (*note set auto-load safe-path::).

  32043. 

  32044.      This variable defaults to '$debugdir:$datadir/auto-load'.  The

  32045.      default 'set auto-load safe-path' value can be also overriden by

  32046.      GDB configuration option '--with-auto-load-dir'.

  32047. 

  32048.      Any reference to '$debugdir' will get replaced by

  32049.      DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any

  32050.      reference to '$datadir' will get replaced by DATA-DIRECTORY which

  32051.      is determined at GDB startup (*note Data Files::).  '$debugdir' and

  32052.      '$datadir' must be placed as a directory component -- either alone

  32053.      or delimited by '/' or '\' directory separators, depending on the

  32054.      host platform.

  32055. 

  32056.      The list of directories uses path separator (':' on GNU and Unix

  32057.      systems, ';' on MS-Windows and MS-DOS) to separate directories,

  32058.      similarly to the 'PATH' environment variable.

  32059. 

  32060. 'show auto-load scripts-directory'

  32061.      Show GDB auto-loaded scripts location.

  32062. 

  32063. 'add-auto-load-scripts-directory [DIRECTORIES...]'

  32064.      Add an entry (or list of entries) to the list of auto-loaded

  32065.      scripts locations.  Multiple entries may be delimited by the host

  32066.      platform path separator in use.

  32067. 

  32068.    GDB does not track which files it has already auto-loaded this way.

  32069. GDB will load the associated script every time the corresponding OBJFILE

  32070. is opened.  So your '-gdb.EXT' file should be careful to avoid errors if

  32071. it is evaluated more than once.

  32072. 

  32073. 

  32074. File: gdb.info,  Node: dotdebug_gdb_scripts section,  Next: Which flavor to choose?,  Prev: objfile-gdbdotext file,  Up: Auto-loading extensions

  32075. 

  32076. 23.4.2 The '.debug_gdb_scripts' section

  32077. ---------------------------------------

  32078. 

  32079. For systems using file formats like ELF and COFF, when GDB loads a new

  32080. object file it will look for a special section named

  32081. '.debug_gdb_scripts'.  If this section exists, its contents is a list of

  32082. null-terminated entries specifying scripts to load.  Each entry begins

  32083. with a non-null prefix byte that specifies the kind of entry, typically

  32084. the extension language and whether the script is in a file or inlined in

  32085. '.debug_gdb_scripts'.

  32086. 

  32087.    The following entries are supported:

  32088. 

  32089. 'SECTION_SCRIPT_ID_PYTHON_FILE = 1'

  32090. 'SECTION_SCRIPT_ID_SCHEME_FILE = 3'

  32091. 'SECTION_SCRIPT_ID_PYTHON_TEXT = 4'

  32092. 'SECTION_SCRIPT_ID_SCHEME_TEXT = 6'

  32093. 

  32094. 23.4.2.1 Script File Entries

  32095. ............................

  32096. 

  32097. If the entry specifies a file, GDB will look for the file first in the

  32098. current directory and then along the source search path (*note

  32099. Specifying Source Directories: Source Path.), except that '$cdir' is not

  32100. searched, since the compilation directory is not relevant to scripts.

  32101. 

  32102.    File entries can be placed in section '.debug_gdb_scripts' with, for

  32103. example, this GCC macro for Python scripts.

  32104. 

  32105.      /* Note: The "MS" section flags are to remove duplicates.  */

  32106.      #define DEFINE_GDB_PY_SCRIPT(script_name) \

  32107.        asm("\

  32108.      .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\

  32109.      .byte 1 /* Python */\n\

  32110.      .asciz \"" script_name "\"\n\

  32111.      .popsection \n\

  32112.      ");

  32113. 

  32114. For Guile scripts, replace '.byte 1' with '.byte 3'.  Then one can

  32115. reference the macro in a header or source file like this:

  32116. 

  32117.      DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")

  32118. 

  32119.    The script name may include directories if desired.

  32120. 

  32121.    Note that loading of this script file also requires accordingly

  32122. configured 'auto-load safe-path' (*note Auto-loading safe path::).

  32123. 

  32124.    If the macro invocation is put in a header, any application or

  32125. library using this header will get a reference to the specified script,

  32126. and with the use of '"MS"' attributes on the section, the linker will

  32127. remove duplicates.

  32128. 

  32129. 23.4.2.2 Script Text Entries

  32130. ............................

  32131. 

  32132. Script text entries allow to put the executable script in the entry

  32133. itself instead of loading it from a file.  The first line of the entry,

  32134. everything after the prefix byte and up to the first newline ('0xa')

  32135. character, is the script name, and must not contain any kind of space

  32136. character, e.g., spaces or tabs.  The rest of the entry, up to the

  32137. trailing null byte, is the script to execute in the specified language.

  32138. The name needs to be unique among all script names, as GDB executes each

  32139. script only once based on its name.

  32140. 

  32141.    Here is an example from file 'py-section-script.c' in the GDB

  32142. testsuite.

  32143. 

  32144.      #include "symcat.h"

  32145.      #include "gdb/section-scripts.h"

  32146.      asm(

  32147.      ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n"

  32148.      ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n"

  32149.      ".ascii \"gdb.inlined-script\\n\"\n"

  32150.      ".ascii \"class test_cmd (gdb.Command):\\n\"\n"

  32151.      ".ascii \"  def __init__ (self):\\n\"\n"

  32152.      ".ascii \"    super (test_cmd, self).__init__ ("

  32153.          "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n"

  32154.      ".ascii \"  def invoke (self, arg, from_tty):\\n\"\n"

  32155.      ".ascii \"    print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n"

  32156.      ".ascii \"test_cmd ()\\n\"\n"

  32157.      ".byte 0\n"

  32158.      ".popsection\n"

  32159.      );

  32160. 

  32161.    Loading of inlined scripts requires a properly configured 'auto-load

  32162. safe-path' (*note Auto-loading safe path::).  The path to specify in

  32163. 'auto-load safe-path' is the path of the file containing the

  32164. '.debug_gdb_scripts' section.

  32165. 

  32166. 

  32167. File: gdb.info,  Node: Which flavor to choose?,  Prev: dotdebug_gdb_scripts section,  Up: Auto-loading extensions

  32168. 

  32169. 23.4.3 Which flavor to choose?

  32170. ------------------------------

  32171. 

  32172. Given the multiple ways of auto-loading extensions, it might not always

  32173. be clear which one to choose.  This section provides some guidance.

  32174. 

  32175. Benefits of the '-gdb.EXT' way:

  32176. 

  32177.    * Can be used with file formats that don't support multiple sections.

  32178. 

  32179.    * Ease of finding scripts for public libraries.

  32180. 

  32181.      Scripts specified in the '.debug_gdb_scripts' section are searched

  32182.      for in the source search path.  For publicly installed libraries,

  32183.      e.g., 'libstdc++', there typically isn't a source directory in

  32184.      which to find the script.

  32185. 

  32186.    * Doesn't require source code additions.

  32187. 

  32188. Benefits of the '.debug_gdb_scripts' way:

  32189. 

  32190.    * Works with static linking.

  32191. 

  32192.      Scripts for libraries done the '-gdb.EXT' way require an objfile to

  32193.      trigger their loading.  When an application is statically linked

  32194.      the only objfile available is the executable, and it is cumbersome

  32195.      to attach all the scripts from all the input libraries to the

  32196.      executable's '-gdb.EXT' script.

  32197. 

  32198.    * Works with classes that are entirely inlined.

  32199. 

  32200.      Some classes can be entirely inlined, and thus there may not be an

  32201.      associated shared library to attach a '-gdb.EXT' script to.

  32202. 

  32203.    * Scripts needn't be copied out of the source tree.

  32204. 

  32205.      In some circumstances, apps can be built out of large collections

  32206.      of internal libraries, and the build infrastructure necessary to

  32207.      install the '-gdb.EXT' scripts in a place where GDB can find them

  32208.      is cumbersome.  It may be easier to specify the scripts in the

  32209.      '.debug_gdb_scripts' section as relative paths, and add a path to

  32210.      the top of the source tree to the source search path.

  32211. 

  32212. 

  32213. File: gdb.info,  Node: Multiple Extension Languages,  Next: Aliases,  Prev: Auto-loading extensions,  Up: Extending GDB

  32214. 

  32215. 23.5 Multiple Extension Languages

  32216. =================================

  32217. 

  32218. The Guile and Python extension languages do not share any state, and

  32219. generally do not interfere with each other.  There are some things to be

  32220. aware of, however.

  32221. 

  32222. 23.5.1 Python comes first

  32223. -------------------------

  32224. 

  32225. Python was GDB's first extension language, and to avoid breaking

  32226. existing behaviour Python comes first.  This is generally solved by the

  32227. "first one wins" principle.  GDB maintains a list of enabled extension

  32228. languages, and when it makes a call to an extension language, (say to

  32229. pretty-print a value), it tries each in turn until an extension language

  32230. indicates it has performed the request (e.g., has returned the

  32231. pretty-printed form of a value).  This extends to errors while

  32232. performing such requests: If an error happens while, for example, trying

  32233. to pretty-print an object then the error is reported and any following

  32234. extension languages are not tried.

  32235. 

  32236. 

  32237. File: gdb.info,  Node: Aliases,  Prev: Multiple Extension Languages,  Up: Extending GDB

  32238. 

  32239. 23.6 Creating new spellings of existing commands

  32240. ================================================

  32241. 

  32242. It is often useful to define alternate spellings of existing commands.

  32243. For example, if a new GDB command defined in Python has a long name to

  32244. type, it is handy to have an abbreviated version of it that involves

  32245. less typing.

  32246. 

  32247.    GDB itself uses aliases.  For example 's' is an alias of the 'step'

  32248. command even though it is otherwise an ambiguous abbreviation of other

  32249. commands like 'set' and 'show'.

  32250. 

  32251.    Aliases are also used to provide shortened or more common versions of

  32252. multi-word commands.  For example, GDB provides the 'tty' alias of the

  32253. 'set inferior-tty' command.

  32254. 

  32255.    You can define a new alias with the 'alias' command.

  32256. 

  32257. 'alias [-a] [--] ALIAS = COMMAND [DEFAULT-ARGS...]'

  32258. 

  32259.    ALIAS specifies the name of the new alias.  Each word of ALIAS must

  32260. consist of letters, numbers, dashes and underscores.

  32261. 

  32262.    COMMAND specifies the name of an existing command that is being

  32263. aliased.

  32264. 

  32265.    COMMAND can also be the name of an existing alias.  In this case,

  32266. COMMAND cannot be an alias that has default arguments.

  32267. 

  32268.    The '-a' option specifies that the new alias is an abbreviation of

  32269. the command.  Abbreviations are not used in command completion.

  32270. 

  32271.    The '--' option specifies the end of options, and is useful when

  32272. ALIAS begins with a dash.

  32273. 

  32274.    You can specify DEFAULT-ARGS for your alias.  These DEFAULT-ARGS will

  32275. be automatically added before the alias arguments typed explicitly on

  32276. the command line.

  32277. 

  32278.    For example, the below defines an alias 'btfullall' that shows all

  32279. local variables and all frame arguments:

  32280.      (gdb) alias btfullall = backtrace -full -frame-arguments all

  32281. 

  32282.    For more information about DEFAULT-ARGS, see *note Automatically

  32283. prepend default arguments to user-defined aliases: Command aliases

  32284. default args.

  32285. 

  32286.    Here is a simple example showing how to make an abbreviation of a

  32287. command so that there is less to type.  Suppose you were tired of typing

  32288. 'disas', the current shortest unambiguous abbreviation of the

  32289. 'disassemble' command and you wanted an even shorter version named 'di'.

  32290. The following will accomplish this.

  32291. 

  32292.      (gdb) alias -a di = disas

  32293. 

  32294.    Note that aliases are different from user-defined commands.  With a

  32295. user-defined command, you also need to write documentation for it with

  32296. the 'document' command.  An alias automatically picks up the

  32297. documentation of the existing command.

  32298. 

  32299.    Here is an example where we make 'elms' an abbreviation of 'elements'

  32300. in the 'set print elements' command.  This is to show that you can make

  32301. an abbreviation of any part of a command.

  32302. 

  32303.      (gdb) alias -a set print elms = set print elements

  32304.      (gdb) alias -a show print elms = show print elements

  32305.      (gdb) set p elms 20

  32306.      (gdb) show p elms

  32307.      Limit on string chars or array elements to print is 200.

  32308. 

  32309.    Note that if you are defining an alias of a 'set' command, and you

  32310. want to have an alias for the corresponding 'show' command, then you

  32311. need to define the latter separately.

  32312. 

  32313.    Unambiguously abbreviated commands are allowed in COMMAND and ALIAS,

  32314. just as they are normally.

  32315. 

  32316.      (gdb) alias -a set pr elms = set p ele

  32317. 

  32318.    Finally, here is an example showing the creation of a one word alias

  32319. for a more complex command.  This creates alias 'spe' of the command

  32320. 'set print elements'.

  32321. 

  32322.      (gdb) alias spe = set print elements

  32323.      (gdb) spe 20

  32324. 

  32325. 

  32326. File: gdb.info,  Node: Interpreters,  Next: TUI,  Prev: Extending GDB,  Up: Top

  32327. 

  32328. 24 Command Interpreters

  32329. ***********************

  32330. 

  32331. GDB supports multiple command interpreters, and some command

  32332. infrastructure to allow users or user interface writers to switch

  32333. between interpreters or run commands in other interpreters.

  32334. 

  32335.    GDB currently supports two command interpreters, the console

  32336. interpreter (sometimes called the command-line interpreter or CLI) and

  32337. the machine interface interpreter (or GDB/MI).  This manual describes

  32338. both of these interfaces in great detail.

  32339. 

  32340.    By default, GDB will start with the console interpreter.  However,

  32341. the user may choose to start GDB with another interpreter by specifying

  32342. the '-i' or '--interpreter' startup options.  Defined interpreters

  32343. include:

  32344. 

  32345. 'console'

  32346.      The traditional console or command-line interpreter.  This is the

  32347.      most often used interpreter with GDB.  With no interpreter

  32348.      specified at runtime, GDB will use this interpreter.

  32349. 

  32350. 'mi'

  32351.      The newest GDB/MI interface (currently 'mi3').  Used primarily by

  32352.      programs wishing to use GDB as a backend for a debugger GUI or an

  32353.      IDE. For more information, see *note The GDB/MI Interface: GDB/MI.

  32354. 

  32355. 'mi3'

  32356.      The GDB/MI interface introduced in GDB 9.1.

  32357. 

  32358. 'mi2'

  32359.      The GDB/MI interface introduced in GDB 6.0.

  32360. 

  32361. 'mi1'

  32362.      The GDB/MI interface introduced in GDB 5.1.

  32363. 

  32364.    You may execute commands in any interpreter from the current

  32365. interpreter using the appropriate command.  If you are running the

  32366. console interpreter, simply use the 'interpreter-exec' command:

  32367. 

  32368.      interpreter-exec mi "-data-list-register-names"

  32369. 

  32370.    GDB/MI has a similar command, although it is only available in

  32371. versions of GDB which support GDB/MI version 2 (or greater).

  32372. 

  32373.    Note that 'interpreter-exec' only changes the interpreter for the

  32374. duration of the specified command.  It does not change the interpreter

  32375. permanently.

  32376. 

  32377.    Although you may only choose a single interpreter at startup, it is

  32378. possible to run an independent interpreter on a specified input/output

  32379. device (usually a tty).

  32380. 

  32381.    For example, consider a debugger GUI or IDE that wants to provide a

  32382. GDB console view.  It may do so by embedding a terminal emulator widget

  32383. in its GUI, starting GDB in the traditional command-line mode with

  32384. stdin/stdout/stderr redirected to that terminal, and then creating an MI

  32385. interpreter running on a specified input/output device.  The console

  32386. interpreter created by GDB at startup handles commands the user types in

  32387. the terminal widget, while the GUI controls and synchronizes state with

  32388. GDB using the separate MI interpreter.

  32389. 

  32390.    To start a new secondary "user interface" running MI, use the

  32391. 'new-ui' command:

  32392. 

  32393.      new-ui INTERPRETER TTY

  32394. 

  32395.    The INTERPRETER parameter specifies the interpreter to run.  This

  32396. accepts the same values as the 'interpreter-exec' command.  For example,

  32397. 'console', 'mi', 'mi2', etc.  The TTY parameter specifies the name of

  32398. the bidirectional file the interpreter uses for input/output, usually

  32399. the name of a pseudoterminal slave on Unix systems.  For example:

  32400. 

  32401.      (gdb) new-ui mi /dev/pts/9

  32402. 

  32403. runs an MI interpreter on '/dev/pts/9'.

  32404. 

  32405. 

  32406. File: gdb.info,  Node: TUI,  Next: Emacs,  Prev: Interpreters,  Up: Top

  32407. 

  32408. 25 GDB Text User Interface

  32409. **************************

  32410. 

  32411. * Menu:

  32412. 

  32413. * TUI Overview::                TUI overview

  32414. * TUI Keys::                    TUI key bindings

  32415. * TUI Single Key Mode::         TUI single key mode

  32416. * TUI Commands::                TUI-specific commands

  32417. * TUI Configuration::           TUI configuration variables

  32418. 

  32419. The GDB Text User Interface (TUI) is a terminal interface which uses the

  32420. 'curses' library to show the source file, the assembly output, the

  32421. program registers and GDB commands in separate text windows.  The TUI

  32422. mode is supported only on platforms where a suitable version of the

  32423. 'curses' library is available.

  32424. 

  32425.    The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'.

  32426. You can also switch in and out of TUI mode while GDB runs by using

  32427. various TUI commands and key bindings, such as 'tui enable' or 'C-x

  32428. C-a'.  *Note TUI Commands: TUI Commands, and *note TUI Key Bindings: TUI

  32429. Keys.

  32430. 

  32431. 

  32432. File: gdb.info,  Node: TUI Overview,  Next: TUI Keys,  Up: TUI

  32433. 

  32434. 25.1 TUI Overview

  32435. =================

  32436. 

  32437. In TUI mode, GDB can display several text windows:

  32438. 

  32439. _command_

  32440.      This window is the GDB command window with the GDB prompt and the

  32441.      GDB output.  The GDB input is still managed using readline.

  32442. 

  32443. _source_

  32444.      The source window shows the source file of the program.  The

  32445.      current line and active breakpoints are displayed in this window.

  32446. 

  32447. _assembly_

  32448.      The assembly window shows the disassembly output of the program.

  32449. 

  32450. _register_

  32451.      This window shows the processor registers.  Registers are

  32452.      highlighted when their values change.

  32453. 

  32454.    The source and assembly windows show the current program position by

  32455. highlighting the current line and marking it with a '>' marker.

  32456. Breakpoints are indicated with two markers.  The first marker indicates

  32457. the breakpoint type:

  32458. 

  32459. 'B'

  32460.      Breakpoint which was hit at least once.

  32461. 

  32462. 'b'

  32463.      Breakpoint which was never hit.

  32464. 

  32465. 'H'

  32466.      Hardware breakpoint which was hit at least once.

  32467. 

  32468. 'h'

  32469.      Hardware breakpoint which was never hit.

  32470. 

  32471.    The second marker indicates whether the breakpoint is enabled or not:

  32472. 

  32473. '+'

  32474.      Breakpoint is enabled.

  32475. 

  32476. '-'

  32477.      Breakpoint is disabled.

  32478. 

  32479.    The source, assembly and register windows are updated when the

  32480. current thread changes, when the frame changes, or when the program

  32481. counter changes.

  32482. 

  32483.    These windows are not all visible at the same time.  The command

  32484. window is always visible.  The others can be arranged in several

  32485. layouts:

  32486. 

  32487.    * source only,

  32488. 

  32489.    * assembly only,

  32490. 

  32491.    * source and assembly,

  32492. 

  32493.    * source and registers, or

  32494. 

  32495.    * assembly and registers.

  32496. 

  32497.    These are the standard layouts, but other layouts can be defined.

  32498. 

  32499.    A status line above the command window shows the following

  32500. information:

  32501. 

  32502. _target_

  32503.      Indicates the current GDB target.  (*note Specifying a Debugging

  32504.      Target: Targets.).

  32505. 

  32506. _process_

  32507.      Gives the current process or thread number.  When no process is

  32508.      being debugged, this field is set to 'No process'.

  32509. 

  32510. _function_

  32511.      Gives the current function name for the selected frame.  The name

  32512.      is demangled if demangling is turned on (*note Print Settings::).

  32513.      When there is no symbol corresponding to the current program

  32514.      counter, the string '??' is displayed.

  32515. 

  32516. _line_

  32517.      Indicates the current line number for the selected frame.  When the

  32518.      current line number is not known, the string '??' is displayed.

  32519. 

  32520. _pc_

  32521.      Indicates the current program counter address.

  32522. 

  32523. 

  32524. File: gdb.info,  Node: TUI Keys,  Next: TUI Single Key Mode,  Prev: TUI Overview,  Up: TUI

  32525. 

  32526. 25.2 TUI Key Bindings

  32527. =====================

  32528. 

  32529. The TUI installs several key bindings in the readline keymaps (*note

  32530. Command Line Editing::).  The following key bindings are installed for

  32531. both TUI mode and the GDB standard mode.

  32532. 

  32533. 'C-x C-a'

  32534. 'C-x a'

  32535. 'C-x A'

  32536.      Enter or leave the TUI mode.  When leaving the TUI mode, the curses

  32537.      window management stops and GDB operates using its standard mode,

  32538.      writing on the terminal directly.  When reentering the TUI mode,

  32539.      control is given back to the curses windows.  The screen is then

  32540.      refreshed.

  32541. 

  32542.      This key binding uses the bindable Readline function

  32543.      'tui-switch-mode'.

  32544. 

  32545. 'C-x 1'

  32546.      Use a TUI layout with only one window.  The layout will either be

  32547.      'source' or 'assembly'.  When the TUI mode is not active, it will

  32548.      switch to the TUI mode.

  32549. 

  32550.      Think of this key binding as the Emacs 'C-x 1' binding.

  32551. 

  32552.      This key binding uses the bindable Readline function

  32553.      'tui-delete-other-windows'.

  32554. 

  32555. 'C-x 2'

  32556.      Use a TUI layout with at least two windows.  When the current

  32557.      layout already has two windows, the next layout with two windows is

  32558.      used.  When a new layout is chosen, one window will always be

  32559.      common to the previous layout and the new one.

  32560. 

  32561.      Think of it as the Emacs 'C-x 2' binding.

  32562. 

  32563.      This key binding uses the bindable Readline function

  32564.      'tui-change-windows'.

  32565. 

  32566. 'C-x o'

  32567.      Change the active window.  The TUI associates several key bindings

  32568.      (like scrolling and arrow keys) with the active window.  This

  32569.      command gives the focus to the next TUI window.

  32570. 

  32571.      Think of it as the Emacs 'C-x o' binding.

  32572. 

  32573.      This key binding uses the bindable Readline function

  32574.      'tui-other-window'.

  32575. 

  32576. 'C-x s'

  32577.      Switch in and out of the TUI SingleKey mode that binds single keys

  32578.      to GDB commands (*note TUI Single Key Mode::).

  32579. 

  32580.      This key binding uses the bindable Readline function 'next-keymap'.

  32581. 

  32582.    The following key bindings only work in the TUI mode:

  32583. 

  32584. <PgUp>

  32585.      Scroll the active window one page up.

  32586. 

  32587. <PgDn>

  32588.      Scroll the active window one page down.

  32589. 

  32590. <Up>

  32591.      Scroll the active window one line up.

  32592. 

  32593. <Down>

  32594.      Scroll the active window one line down.

  32595. 

  32596. <Left>

  32597.      Scroll the active window one column left.

  32598. 

  32599. <Right>

  32600.      Scroll the active window one column right.

  32601. 

  32602. 'C-L'

  32603.      Refresh the screen.

  32604. 

  32605.    Because the arrow keys scroll the active window in the TUI mode, they

  32606. are not available for their normal use by readline unless the command

  32607. window has the focus.  When another window is active, you must use other

  32608. readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control

  32609. the command window.

  32610. 

  32611. 

  32612. File: gdb.info,  Node: TUI Single Key Mode,  Next: TUI Commands,  Prev: TUI Keys,  Up: TUI

  32613. 

  32614. 25.3 TUI Single Key Mode

  32615. ========================

  32616. 

  32617. The TUI also provides a "SingleKey" mode, which binds several frequently

  32618. used GDB commands to single keys.  Type 'C-x s' to switch into this

  32619. mode, where the following key bindings are used:

  32620. 

  32621. 'c'

  32622.      continue

  32623. 

  32624. 'd'

  32625.      down

  32626. 

  32627. 'f'

  32628.      finish

  32629. 

  32630. 'n'

  32631.      next

  32632. 

  32633. 'o'

  32634.      nexti.  The shortcut letter 'o' stands for "step Over".

  32635. 

  32636. 'q'

  32637.      exit the SingleKey mode.

  32638. 

  32639. 'r'

  32640.      run

  32641. 

  32642. 's'

  32643.      step

  32644. 

  32645. 'i'

  32646.      stepi.  The shortcut letter 'i' stands for "step Into".

  32647. 

  32648. 'u'

  32649.      up

  32650. 

  32651. 'v'

  32652.      info locals

  32653. 

  32654. 'w'

  32655.      where

  32656. 

  32657.    Other keys temporarily switch to the GDB command prompt.  The key

  32658. that was pressed is inserted in the editing buffer so that it is

  32659. possible to type most GDB commands without interaction with the TUI

  32660. SingleKey mode.  Once the command is entered the TUI SingleKey mode is

  32661. restored.  The only way to permanently leave this mode is by typing 'q'

  32662. or 'C-x s'.

  32663. 

  32664.    If GDB was built with Readline 8.0 or later, the TUI SingleKey keymap

  32665. will be named 'SingleKey'.  This can be used in '.inputrc' to add

  32666. additional bindings to this keymap.

  32667. 

  32668. 

  32669. File: gdb.info,  Node: TUI Commands,  Next: TUI Configuration,  Prev: TUI Single Key Mode,  Up: TUI

  32670. 

  32671. 25.4 TUI-specific Commands

  32672. ==========================

  32673. 

  32674. The TUI has specific commands to control the text windows.  These

  32675. commands are always available, even when GDB is not in the TUI mode.

  32676. When GDB is in the standard mode, most of these commands will

  32677. automatically switch to the TUI mode.

  32678. 

  32679.    Note that if GDB's 'stdout' is not connected to a terminal, or GDB

  32680. has been started with the machine interface interpreter (*note The

  32681. GDB/MI Interface: GDB/MI.), most of these commands will fail with an

  32682. error, because it would not be possible or desirable to enable curses

  32683. window management.

  32684. 

  32685. 'tui enable'

  32686.      Activate TUI mode.  The last active TUI window layout will be used

  32687.      if TUI mode has previously been used in the current debugging

  32688.      session, otherwise a default layout is used.

  32689. 

  32690. 'tui disable'

  32691.      Disable TUI mode, returning to the console interpreter.

  32692. 

  32693. 'info win'

  32694.      List and give the size of all displayed windows.

  32695. 

  32696. 'tui new-layout NAME WINDOW WEIGHT [WINDOW WEIGHT...]'

  32697.      Create a new TUI layout.  The new layout will be named NAME, and

  32698.      can be accessed using the 'layout' command (see below).

  32699. 

  32700.      Each WINDOW parameter is either the name of a window to display, or

  32701.      a window description.  The windows will be displayed from top to

  32702.      bottom in the order listed.

  32703. 

  32704.      The names of the windows are the same as the ones given to the

  32705.      'focus' command (see below); additional, the 'status' window can be

  32706.      specified.  Note that, because it is of fixed height, the weight

  32707.      assigned to the status window is of no importance.  It is

  32708.      conventional to use '0' here.

  32709. 

  32710.      A window description looks a bit like an invocation of 'tui

  32711.      new-layout', and is of the form {['-horizontal']WINDOW WEIGHT

  32712.      [WINDOW WEIGHT...]}.

  32713. 

  32714.      This specifies a sub-layout.  If '-horizontal' is given, the

  32715.      windows in this description will be arranged side-by-side, rather

  32716.      than top-to-bottom.

  32717. 

  32718.      Each WEIGHT is an integer.  It is the weight of this window

  32719.      relative to all the other windows in the layout.  These numbers are

  32720.      used to calculate how much of the screen is given to each window.

  32721. 

  32722.      For example:

  32723. 

  32724.           (gdb) tui new-layout example src 1 regs 1 status 0 cmd 1

  32725. 

  32726.      Here, the new layout is called 'example'.  It shows the source and

  32727.      register windows, followed by the status window, and then finally

  32728.      the command window.  The non-status windows all have the same

  32729.      weight, so the terminal will be split into three roughly equal

  32730.      sections.

  32731. 

  32732.      Here is a more complex example, showing a horizontal layout:

  32733. 

  32734.           (gdb) tui new-layout example {-horizontal src 1 asm 1} 2 status 0 cmd 1

  32735. 

  32736.      This will result in side-by-side source and assembly windows; with

  32737.      the status and command window being beneath these, filling the

  32738.      entire width of the terminal.  Because they have weight 2, the

  32739.      source and assembly windows will be twice the height of the command

  32740.      window.

  32741. 

  32742. 'layout NAME'

  32743.      Changes which TUI windows are displayed.  The NAME parameter

  32744.      controls which layout is shown.  It can be either one of the

  32745.      built-in layout names, or the name of a layout defined by the user

  32746.      using 'tui new-layout'.

  32747. 

  32748.      The built-in layouts are as follows:

  32749. 

  32750.      'next'

  32751.           Display the next layout.

  32752. 

  32753.      'prev'

  32754.           Display the previous layout.

  32755. 

  32756.      'src'

  32757.           Display the source and command windows.

  32758. 

  32759.      'asm'

  32760.           Display the assembly and command windows.

  32761. 

  32762.      'split'

  32763.           Display the source, assembly, and command windows.

  32764. 

  32765.      'regs'

  32766.           When in 'src' layout display the register, source, and command

  32767.           windows.  When in 'asm' or 'split' layout display the

  32768.           register, assembler, and command windows.

  32769. 

  32770. 'focus NAME'

  32771.      Changes which TUI window is currently active for scrolling.  The

  32772.      NAME parameter can be any of the following:

  32773. 

  32774.      'next'

  32775.           Make the next window active for scrolling.

  32776. 

  32777.      'prev'

  32778.           Make the previous window active for scrolling.

  32779. 

  32780.      'src'

  32781.           Make the source window active for scrolling.

  32782. 

  32783.      'asm'

  32784.           Make the assembly window active for scrolling.

  32785. 

  32786.      'regs'

  32787.           Make the register window active for scrolling.

  32788. 

  32789.      'cmd'

  32790.           Make the command window active for scrolling.

  32791. 

  32792. 'refresh'

  32793.      Refresh the screen.  This is similar to typing 'C-L'.

  32794. 

  32795. 'tui reg GROUP'

  32796.      Changes the register group displayed in the tui register window to

  32797.      GROUP.  If the register window is not currently displayed this

  32798.      command will cause the register window to be displayed.  The list

  32799.      of register groups, as well as their order is target specific.  The

  32800.      following groups are available on most targets:

  32801.      'next'

  32802.           Repeatedly selecting this group will cause the display to

  32803.           cycle through all of the available register groups.

  32804. 

  32805.      'prev'

  32806.           Repeatedly selecting this group will cause the display to

  32807.           cycle through all of the available register groups in the

  32808.           reverse order to NEXT.

  32809. 

  32810.      'general'

  32811.           Display the general registers.

  32812.      'float'

  32813.           Display the floating point registers.

  32814.      'system'

  32815.           Display the system registers.

  32816.      'vector'

  32817.           Display the vector registers.

  32818.      'all'

  32819.           Display all registers.

  32820. 

  32821. 'update'

  32822.      Update the source window and the current execution point.

  32823. 

  32824. 'winheight NAME +COUNT'

  32825. 'winheight NAME -COUNT'

  32826.      Change the height of the window NAME by COUNT lines.  Positive

  32827.      counts increase the height, while negative counts decrease it.  The

  32828.      NAME parameter can be one of 'src' (the source window), 'cmd' (the

  32829.      command window), 'asm' (the disassembly window), or 'regs' (the

  32830.      register display window).

  32831. 

  32832. 

  32833. File: gdb.info,  Node: TUI Configuration,  Prev: TUI Commands,  Up: TUI

  32834. 

  32835. 25.5 TUI Configuration Variables

  32836. ================================

  32837. 

  32838. Several configuration variables control the appearance of TUI windows.

  32839. 

  32840. 'set tui border-kind KIND'

  32841.      Select the border appearance for the source, assembly and register

  32842.      windows.  The possible values are the following:

  32843.      'space'

  32844.           Use a space character to draw the border.

  32845. 

  32846.      'ascii'

  32847.           Use ASCII characters '+', '-' and '|' to draw the border.

  32848. 

  32849.      'acs'

  32850.           Use the Alternate Character Set to draw the border.  The

  32851.           border is drawn using character line graphics if the terminal

  32852.           supports them.

  32853. 

  32854. 'set tui border-mode MODE'

  32855. 'set tui active-border-mode MODE'

  32856.      Select the display attributes for the borders of the inactive

  32857.      windows or the active window.  The MODE can be one of the

  32858.      following:

  32859.      'normal'

  32860.           Use normal attributes to display the border.

  32861. 

  32862.      'standout'

  32863.           Use standout mode.

  32864. 

  32865.      'reverse'

  32866.           Use reverse video mode.

  32867. 

  32868.      'half'

  32869.           Use half bright mode.

  32870. 

  32871.      'half-standout'

  32872.           Use half bright and standout mode.

  32873. 

  32874.      'bold'

  32875.           Use extra bright or bold mode.

  32876. 

  32877.      'bold-standout'

  32878.           Use extra bright or bold and standout mode.

  32879. 

  32880. 'set tui tab-width NCHARS'

  32881.      Set the width of tab stops to be NCHARS characters.  This setting

  32882.      affects the display of TAB characters in the source and assembly

  32883.      windows.

  32884. 

  32885. 'set tui compact-source [on|off]'

  32886.      Set whether the TUI source window is displayed in "compact" form.

  32887.      The default display uses more space for line numbers and starts the

  32888.      source text at the next tab stop; the compact display uses only as

  32889.      much space as is needed for the line numbers in the current file,

  32890.      and only a single space to separate the line numbers from the

  32891.      source.

  32892. 

  32893.    Note that the colors of the TUI borders can be controlled using the

  32894. appropriate 'set style' commands.  *Note Output Styling::.

  32895. 

  32896. 

  32897. File: gdb.info,  Node: Emacs,  Next: GDB/MI,  Prev: TUI,  Up: Top

  32898. 

  32899. 26 Using GDB under GNU Emacs

  32900. ****************************

  32901. 

  32902. A special interface allows you to use GNU Emacs to view (and edit) the

  32903. source files for the program you are debugging with GDB.

  32904. 

  32905.    To use this interface, use the command 'M-x gdb' in Emacs.  Give the

  32906. executable file you want to debug as an argument.  This command starts

  32907. GDB as a subprocess of Emacs, with input and output through a newly

  32908. created Emacs buffer.

  32909. 

  32910.    Running GDB under Emacs can be just like running GDB normally except

  32911. for two things:

  32912. 

  32913.    * All "terminal" input and output goes through an Emacs buffer,

  32914.      called the GUD buffer.

  32915. 

  32916.      This applies both to GDB commands and their output, and to the

  32917.      input and output done by the program you are debugging.

  32918. 

  32919.      This is useful because it means that you can copy the text of

  32920.      previous commands and input them again; you can even use parts of

  32921.      the output in this way.

  32922. 

  32923.      All the facilities of Emacs' Shell mode are available for

  32924.      interacting with your program.  In particular, you can send signals

  32925.      the usual way--for example, 'C-c C-c' for an interrupt, 'C-c C-z'

  32926.      for a stop.

  32927. 

  32928.    * GDB displays source code through Emacs.

  32929. 

  32930.      Each time GDB displays a stack frame, Emacs automatically finds the

  32931.      source file for that frame and puts an arrow ('=>') at the left

  32932.      margin of the current line.  Emacs uses a separate buffer for

  32933.      source display, and splits the screen to show both your GDB session

  32934.      and the source.

  32935. 

  32936.      Explicit GDB 'list' or search commands still produce output as

  32937.      usual, but you probably have no reason to use them from Emacs.

  32938. 

  32939.    We call this "text command mode".  Emacs 22.1, and later, also uses a

  32940. graphical mode, enabled by default, which provides further buffers that

  32941. can control the execution and describe the state of your program.  *Note

  32942. (Emacs)GDB Graphical Interface::.

  32943. 

  32944.    If you specify an absolute file name when prompted for the 'M-x gdb'

  32945. argument, then Emacs sets your current working directory to where your

  32946. program resides.  If you only specify the file name, then Emacs sets

  32947. your current working directory to the directory associated with the

  32948. previous buffer.  In this case, GDB may find your program by searching

  32949. your environment's 'PATH' variable, but on some operating systems it

  32950. might not find the source.  So, although the GDB input and output

  32951. session proceeds normally, the auxiliary buffer does not display the

  32952. current source and line of execution.

  32953. 

  32954.    The initial working directory of GDB is printed on the top line of

  32955. the GUD buffer and this serves as a default for the commands that

  32956. specify files for GDB to operate on.  *Note Commands to Specify Files:

  32957. Files.

  32958. 

  32959.    By default, 'M-x gdb' calls the program called 'gdb'.  If you need to

  32960. call GDB by a different name (for example, if you keep several

  32961. configurations around, with different names) you can customize the Emacs

  32962. variable 'gud-gdb-command-name' to run the one you want.

  32963. 

  32964.    In the GUD buffer, you can use these special Emacs commands in

  32965. addition to the standard Shell mode commands:

  32966. 

  32967. 'C-h m'

  32968.      Describe the features of Emacs' GUD Mode.

  32969. 

  32970. 'C-c C-s'

  32971.      Execute to another source line, like the GDB 'step' command; also

  32972.      update the display window to show the current file and location.

  32973. 

  32974. 'C-c C-n'

  32975.      Execute to next source line in this function, skipping all function

  32976.      calls, like the GDB 'next' command.  Then update the display window

  32977.      to show the current file and location.

  32978. 

  32979. 'C-c C-i'

  32980.      Execute one instruction, like the GDB 'stepi' command; update

  32981.      display window accordingly.

  32982. 

  32983. 'C-c C-f'

  32984.      Execute until exit from the selected stack frame, like the GDB

  32985.      'finish' command.

  32986. 

  32987. 'C-c C-r'

  32988.      Continue execution of your program, like the GDB 'continue'

  32989.      command.

  32990. 

  32991. 'C-c <'

  32992.      Go up the number of frames indicated by the numeric argument (*note

  32993.      Numeric Arguments: (Emacs)Arguments.), like the GDB 'up' command.

  32994. 

  32995. 'C-c >'

  32996.      Go down the number of frames indicated by the numeric argument,

  32997.      like the GDB 'down' command.

  32998. 

  32999.    In any source file, the Emacs command 'C-x <SPC>' ('gud-break') tells

  33000. GDB to set a breakpoint on the source line point is on.

  33001. 

  33002.    In text command mode, if you type 'M-x speedbar', Emacs displays a

  33003. separate frame which shows a backtrace when the GUD buffer is current.

  33004. Move point to any frame in the stack and type <RET> to make it become

  33005. the current frame and display the associated source in the source

  33006. buffer.  Alternatively, click 'Mouse-2' to make the selected frame

  33007. become the current one.  In graphical mode, the speedbar displays watch

  33008. expressions.

  33009. 

  33010.    If you accidentally delete the source-display buffer, an easy way to

  33011. get it back is to type the command 'f' in the GDB buffer, to request a

  33012. frame display; when you run under Emacs, this recreates the source

  33013. buffer if necessary to show you the context of the current frame.

  33014. 

  33015.    The source files displayed in Emacs are in ordinary Emacs buffers

  33016. which are visiting the source files in the usual way.  You can edit the

  33017. files with these buffers if you wish; but keep in mind that GDB

  33018. communicates with Emacs in terms of line numbers.  If you add or delete

  33019. lines from the text, the line numbers that GDB knows cease to correspond

  33020. properly with the code.

  33021. 

  33022.    A more detailed description of Emacs' interaction with GDB is given

  33023. in the Emacs manual (*note (Emacs)Debuggers::).

  33024. 

  33025. 

  33026. File: gdb.info,  Node: GDB/MI,  Next: Annotations,  Prev: Emacs,  Up: Top

  33027. 

  33028. 27 The GDB/MI Interface

  33029. ***********************

  33030. 

  33031. * Menu:

  33032. 

  33033. * GDB/MI General Design::

  33034. * GDB/MI Command Syntax::

  33035. * GDB/MI Compatibility with CLI::

  33036. * GDB/MI Development and Front Ends::

  33037. * GDB/MI Output Records::

  33038. * GDB/MI Simple Examples::

  33039. * GDB/MI Command Description Format::

  33040. * GDB/MI Breakpoint Commands::

  33041. * GDB/MI Catchpoint Commands::

  33042. * GDB/MI Program Context::

  33043. * GDB/MI Thread Commands::

  33044. * GDB/MI Ada Tasking Commands::

  33045. * GDB/MI Program Execution::

  33046. * GDB/MI Stack Manipulation::

  33047. * GDB/MI Variable Objects::

  33048. * GDB/MI Data Manipulation::

  33049. * GDB/MI Tracepoint Commands::

  33050. * GDB/MI Symbol Query::

  33051. * GDB/MI File Commands::

  33052. * GDB/MI Target Manipulation::

  33053. * GDB/MI File Transfer Commands::

  33054. * GDB/MI Ada Exceptions Commands::

  33055. * GDB/MI Support Commands::

  33056. * GDB/MI Miscellaneous Commands::

  33057. 

  33058. Function and Purpose

  33059. ====================

  33060. 

  33061. GDB/MI is a line based machine oriented text interface to GDB and is

  33062. activated by specifying using the '--interpreter' command line option

  33063. (*note Mode Options::).  It is specifically intended to support the

  33064. development of systems which use the debugger as just one small

  33065. component of a larger system.

  33066. 

  33067.    This chapter is a specification of the GDB/MI interface.  It is

  33068. written in the form of a reference manual.

  33069. 

  33070.    Note that GDB/MI is still under construction, so some of the features

  33071. described below are incomplete and subject to change (*note GDB/MI

  33072. Development and Front Ends: GDB/MI Development and Front Ends.).

  33073. 

  33074. Notation and Terminology

  33075. ========================

  33076. 

  33077. This chapter uses the following notation:

  33078. 

  33079.    * '|' separates two alternatives.

  33080. 

  33081.    * '[ SOMETHING ]' indicates that SOMETHING is optional: it may or may

  33082.      not be given.

  33083. 

  33084.    * '( GROUP )*' means that GROUP inside the parentheses may repeat

  33085.      zero or more times.

  33086. 

  33087.    * '( GROUP )+' means that GROUP inside the parentheses may repeat one

  33088.      or more times.

  33089. 

  33090.    * '"STRING"' means a literal STRING.

  33091. 

  33092. * Menu:

  33093. 

  33094. * GDB/MI General Design::

  33095. * GDB/MI Command Syntax::

  33096. * GDB/MI Compatibility with CLI::

  33097. * GDB/MI Development and Front Ends::

  33098. * GDB/MI Output Records::

  33099. * GDB/MI Simple Examples::

  33100. * GDB/MI Command Description Format::

  33101. * GDB/MI Breakpoint Commands::

  33102. * GDB/MI Catchpoint Commands::

  33103. * GDB/MI Program Context::

  33104. * GDB/MI Thread Commands::

  33105. * GDB/MI Ada Tasking Commands::

  33106. * GDB/MI Program Execution::

  33107. * GDB/MI Stack Manipulation::

  33108. * GDB/MI Variable Objects::

  33109. * GDB/MI Data Manipulation::

  33110. * GDB/MI Tracepoint Commands::

  33111. * GDB/MI Symbol Query::

  33112. * GDB/MI File Commands::

  33113. * GDB/MI Target Manipulation::

  33114. * GDB/MI File Transfer Commands::

  33115. * GDB/MI Ada Exceptions Commands::

  33116. * GDB/MI Support Commands::

  33117. * GDB/MI Miscellaneous Commands::

  33118. 

  33119. 

  33120. File: gdb.info,  Node: GDB/MI General Design,  Next: GDB/MI Command Syntax,  Up: GDB/MI

  33121. 

  33122. 27.1 GDB/MI General Design

  33123. ==========================

  33124. 

  33125. Interaction of a GDB/MI frontend with GDB involves three parts--commands

  33126. sent to GDB, responses to those commands and notifications.  Each

  33127. command results in exactly one response, indicating either successful

  33128. completion of the command, or an error.  For the commands that do not

  33129. resume the target, the response contains the requested information.  For

  33130. the commands that resume the target, the response only indicates whether

  33131. the target was successfully resumed.  Notifications is the mechanism for

  33132. reporting changes in the state of the target, or in GDB state, that

  33133. cannot conveniently be associated with a command and reported as part of

  33134. that command response.

  33135. 

  33136.    The important examples of notifications are:

  33137. 

  33138.    * Exec notifications.  These are used to report changes in target

  33139.      state--when a target is resumed, or stopped.  It would not be

  33140.      feasible to include this information in response of resuming

  33141.      commands, because one resume commands can result in multiple events

  33142.      in different threads.  Also, quite some time may pass before any

  33143.      event happens in the target, while a frontend needs to know whether

  33144.      the resuming command itself was successfully executed.

  33145. 

  33146.    * Console output, and status notifications.  Console output

  33147.      notifications are used to report output of CLI commands, as well as

  33148.      diagnostics for other commands.  Status notifications are used to

  33149.      report the progress of a long-running operation.  Naturally,

  33150.      including this information in command response would mean no output

  33151.      is produced until the command is finished, which is undesirable.

  33152. 

  33153.    * General notifications.  Commands may have various side effects on

  33154.      the GDB or target state beyond their official purpose.  For

  33155.      example, a command may change the selected thread.  Although such

  33156.      changes can be included in command response, using notification

  33157.      allows for more orthogonal frontend design.

  33158. 

  33159.    There's no guarantee that whenever an MI command reports an error,

  33160. GDB or the target are in any specific state, and especially, the state

  33161. is not reverted to the state before the MI command was processed.

  33162. Therefore, whenever an MI command results in an error, we recommend that

  33163. the frontend refreshes all the information shown in the user interface.

  33164. 

  33165. * Menu:

  33166. 

  33167. * Context management::

  33168. * Asynchronous and non-stop modes::

  33169. * Thread groups::

  33170. 

  33171. 

  33172. File: gdb.info,  Node: Context management,  Next: Asynchronous and non-stop modes,  Up: GDB/MI General Design

  33173. 

  33174. 27.1.1 Context management

  33175. -------------------------

  33176. 

  33177. 27.1.1.1 Threads and Frames

  33178. ...........................

  33179. 

  33180. In most cases when GDB accesses the target, this access is done in

  33181. context of a specific thread and frame (*note Frames::).  Often, even

  33182. when accessing global data, the target requires that a thread be

  33183. specified.  The CLI interface maintains the selected thread and frame,

  33184. and supplies them to target on each command.  This is convenient,

  33185. because a command line user would not want to specify that information

  33186. explicitly on each command, and because user interacts with GDB via a

  33187. single terminal, so no confusion is possible as to what thread and frame

  33188. are the current ones.

  33189. 

  33190.    In the case of MI, the concept of selected thread and frame is less

  33191. useful.  First, a frontend can easily remember this information itself.

  33192. Second, a graphical frontend can have more than one window, each one

  33193. used for debugging a different thread, and the frontend might want to

  33194. access additional threads for internal purposes.  This increases the

  33195. risk that by relying on implicitly selected thread, the frontend may be

  33196. operating on a wrong one.  Therefore, each MI command should explicitly

  33197. specify which thread and frame to operate on.  To make it possible, each

  33198. MI command accepts the '--thread' and '--frame' options, the value to

  33199. each is GDB global identifier for thread and frame to operate on.

  33200. 

  33201.    Usually, each top-level window in a frontend allows the user to

  33202. select a thread and a frame, and remembers the user selection for

  33203. further operations.  However, in some cases GDB may suggest that the

  33204. current thread or frame be changed.  For example, when stopping on a

  33205. breakpoint it is reasonable to switch to the thread where breakpoint is

  33206. hit.  For another example, if the user issues the CLI 'thread' or

  33207. 'frame' commands via the frontend, it is desirable to change the

  33208. frontend's selection to the one specified by user.  GDB communicates the

  33209. suggestion to change current thread and frame using the

  33210. '=thread-selected' notification.

  33211. 

  33212.    Note that historically, MI shares the selected thread with CLI, so

  33213. frontends used the '-thread-select' to execute commands in the right

  33214. context.  However, getting this to work right is cumbersome.  The

  33215. simplest way is for frontend to emit '-thread-select' command before

  33216. every command.  This doubles the number of commands that need to be

  33217. sent.  The alternative approach is to suppress '-thread-select' if the

  33218. selected thread in GDB is supposed to be identical to the thread the

  33219. frontend wants to operate on.  However, getting this optimization right

  33220. can be tricky.  In particular, if the frontend sends several commands to

  33221. GDB, and one of the commands changes the selected thread, then the

  33222. behaviour of subsequent commands will change.  So, a frontend should

  33223. either wait for response from such problematic commands, or explicitly

  33224. add '-thread-select' for all subsequent commands.  No frontend is known

  33225. to do this exactly right, so it is suggested to just always pass the

  33226. '--thread' and '--frame' options.

  33227. 

  33228. 27.1.1.2 Language

  33229. .................

  33230. 

  33231. The execution of several commands depends on which language is selected.

  33232. By default, the current language (*note show language::) is used.  But

  33233. for commands known to be language-sensitive, it is recommended to use

  33234. the '--language' option.  This option takes one argument, which is the

  33235. name of the language to use while executing the command.  For instance:

  33236. 

  33237.      -data-evaluate-expression --language c "sizeof (void*)"

  33238.      ^done,value="4"

  33239.      (gdb)

  33240. 

  33241.    The valid language names are the same names accepted by the 'set

  33242. language' command (*note Manually::), excluding 'auto', 'local' or

  33243. 'unknown'.

  33244. 

  33245. 

  33246. File: gdb.info,  Node: Asynchronous and non-stop modes,  Next: Thread groups,  Prev: Context management,  Up: GDB/MI General Design

  33247. 

  33248. 27.1.2 Asynchronous command execution and non-stop mode

  33249. -------------------------------------------------------

  33250. 

  33251. On some targets, GDB is capable of processing MI commands even while the

  33252. target is running.  This is called "asynchronous command execution"

  33253. (*note Background Execution::).  The frontend may specify a preference

  33254. for asynchronous execution using the '-gdb-set mi-async 1' command,

  33255. which should be emitted before either running the executable or

  33256. attaching to the target.  After the frontend has started the executable

  33257. or attached to the target, it can find if asynchronous execution is

  33258. enabled using the '-list-target-features' command.

  33259. 

  33260. '-gdb-set mi-async on'

  33261. '-gdb-set mi-async off'

  33262.      Set whether MI is in asynchronous mode.

  33263. 

  33264.      When 'off', which is the default, MI execution commands (e.g.,

  33265.      '-exec-continue') are foreground commands, and GDB waits for the

  33266.      program to stop before processing further commands.

  33267. 

  33268.      When 'on', MI execution commands are background execution commands

  33269.      (e.g., '-exec-continue' becomes the equivalent of the 'c&' CLI

  33270.      command), and so GDB is capable of processing MI commands even

  33271.      while the target is running.

  33272. 

  33273. '-gdb-show mi-async'

  33274.      Show whether MI asynchronous mode is enabled.

  33275. 

  33276.    Note: In GDB version 7.7 and earlier, this option was called

  33277. 'target-async' instead of 'mi-async', and it had the effect of both

  33278. putting MI in asynchronous mode and making CLI background commands

  33279. possible.  CLI background commands are now always possible "out of the

  33280. box" if the target supports them.  The old spelling is kept as a

  33281. deprecated alias for backwards compatibility.

  33282. 

  33283.    Even if GDB can accept a command while target is running, many

  33284. commands that access the target do not work when the target is running.

  33285. Therefore, asynchronous command execution is most useful when combined

  33286. with non-stop mode (*note Non-Stop Mode::).  Then, it is possible to

  33287. examine the state of one thread, while other threads are running.

  33288. 

  33289.    When a given thread is running, MI commands that try to access the

  33290. target in the context of that thread may not work, or may work only on

  33291. some targets.  In particular, commands that try to operate on thread's

  33292. stack will not work, on any target.  Commands that read memory, or

  33293. modify breakpoints, may work or not work, depending on the target.  Note

  33294. that even commands that operate on global state, such as 'print', 'set',

  33295. and breakpoint commands, still access the target in the context of a

  33296. specific thread, so frontend should try to find a stopped thread and

  33297. perform the operation on that thread (using the '--thread' option).

  33298. 

  33299.    Which commands will work in the context of a running thread is highly

  33300. target dependent.  However, the two commands '-exec-interrupt', to stop

  33301. a thread, and '-thread-info', to find the state of a thread, will always

  33302. work.

  33303. 

  33304. 

  33305. File: gdb.info,  Node: Thread groups,  Prev: Asynchronous and non-stop modes,  Up: GDB/MI General Design

  33306. 

  33307. 27.1.3 Thread groups

  33308. --------------------

  33309. 

  33310. GDB may be used to debug several processes at the same time.  On some

  33311. platforms, GDB may support debugging of several hardware systems, each

  33312. one having several cores with several different processes running on

  33313. each core.  This section describes the MI mechanism to support such

  33314. debugging scenarios.

  33315. 

  33316.    The key observation is that regardless of the structure of the

  33317. target, MI can have a global list of threads, because most commands that

  33318. accept the '--thread' option do not need to know what process that

  33319. thread belongs to.  Therefore, it is not necessary to introduce neither

  33320. additional '--process' option, nor an notion of the current process in

  33321. the MI interface.  The only strictly new feature that is required is the

  33322. ability to find how the threads are grouped into processes.

  33323. 

  33324.    To allow the user to discover such grouping, and to support arbitrary

  33325. hierarchy of machines/cores/processes, MI introduces the concept of a

  33326. "thread group".  Thread group is a collection of threads and other

  33327. thread groups.  A thread group always has a string identifier, a type,

  33328. and may have additional attributes specific to the type.  A new command,

  33329. '-list-thread-groups', returns the list of top-level thread groups,

  33330. which correspond to processes that GDB is debugging at the moment.  By

  33331. passing an identifier of a thread group to the '-list-thread-groups'

  33332. command, it is possible to obtain the members of specific thread group.

  33333. 

  33334.    To allow the user to easily discover processes, and other objects, he

  33335. wishes to debug, a concept of "available thread group" is introduced.

  33336. Available thread group is an thread group that GDB is not debugging, but

  33337. that can be attached to, using the '-target-attach' command.  The list

  33338. of available top-level thread groups can be obtained using

  33339. '-list-thread-groups --available'.  In general, the content of a thread

  33340. group may be only retrieved only after attaching to that thread group.

  33341. 

  33342.    Thread groups are related to inferiors (*note Inferiors Connections

  33343. and Programs::).  Each inferior corresponds to a thread group of a

  33344. special type 'process', and some additional operations are permitted on

  33345. such thread groups.

  33346. 

  33347. 

  33348. File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Prev: GDB/MI General Design,  Up: GDB/MI

  33349. 

  33350. 27.2 GDB/MI Command Syntax

  33351. ==========================

  33352. 

  33353. * Menu:

  33354. 

  33355. * GDB/MI Input Syntax::

  33356. * GDB/MI Output Syntax::

  33357. 

  33358. 

  33359. File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax

  33360. 

  33361. 27.2.1 GDB/MI Input Syntax

  33362. --------------------------

  33363. 

  33364. 'COMMAND ==>'

  33365.      'CLI-COMMAND | MI-COMMAND'

  33366. 

  33367. 'CLI-COMMAND ==>'

  33368.      '[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB

  33369.      CLI command.

  33370. 

  33371. 'MI-COMMAND ==>'

  33372.      '[ TOKEN ] "-" OPERATION ( " " OPTION )* [ " --" ] ( " " PARAMETER

  33373.      )* NL'

  33374. 

  33375. 'TOKEN ==>'

  33376.      "any sequence of digits"

  33377. 

  33378. 'OPTION ==>'

  33379.      '"-" PARAMETER [ " " PARAMETER ]'

  33380. 

  33381. 'PARAMETER ==>'

  33382.      'NON-BLANK-SEQUENCE | C-STRING'

  33383. 

  33384. 'OPERATION ==>'

  33385.      _any of the operations described in this chapter_

  33386. 

  33387. 'NON-BLANK-SEQUENCE ==>'

  33388.      _anything, provided it doesn't contain special characters such as

  33389.      "-", NL, """ and of course " "_

  33390. 

  33391. 'C-STRING ==>'

  33392.      '""" SEVEN-BIT-ISO-C-STRING-CONTENT """'

  33393. 

  33394. 'NL ==>'

  33395.      'CR | CR-LF'

  33396. 

  33397. Notes:

  33398. 

  33399.    * The CLI commands are still handled by the MI interpreter; their

  33400.      output is described below.

  33401. 

  33402.    * The 'TOKEN', when present, is passed back when the command

  33403.      finishes.

  33404. 

  33405.    * Some MI commands accept optional arguments as part of the parameter

  33406.      list.  Each option is identified by a leading '-' (dash) and may be

  33407.      followed by an optional argument parameter.  Options occur first in

  33408.      the parameter list and can be delimited from normal parameters

  33409.      using '--' (this is useful when some parameters begin with a dash).

  33410. 

  33411.    Pragmatics:

  33412. 

  33413.    * We want easy access to the existing CLI syntax (for debugging).

  33414. 

  33415.    * We want it to be easy to spot a MI operation.

  33416. 

  33417. 

  33418. File: gdb.info,  Node: GDB/MI Output Syntax,  Prev: GDB/MI Input Syntax,  Up: GDB/MI Command Syntax

  33419. 

  33420. 27.2.2 GDB/MI Output Syntax

  33421. ---------------------------

  33422. 

  33423. The output from GDB/MI consists of zero or more out-of-band records

  33424. followed, optionally, by a single result record.  This result record is

  33425. for the most recent command.  The sequence of output records is

  33426. terminated by '(gdb)'.

  33427. 

  33428.    If an input command was prefixed with a 'TOKEN' then the

  33429. corresponding output for that command will also be prefixed by that same

  33430. TOKEN.

  33431. 

  33432. 'OUTPUT ==>'

  33433.      '( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'

  33434. 

  33435. 'RESULT-RECORD ==>'

  33436.      ' [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'

  33437. 

  33438. 'OUT-OF-BAND-RECORD ==>'

  33439.      'ASYNC-RECORD | STREAM-RECORD'

  33440. 

  33441. 'ASYNC-RECORD ==>'

  33442.      'EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'

  33443. 

  33444. 'EXEC-ASYNC-OUTPUT ==>'

  33445.      '[ TOKEN ] "*" ASYNC-OUTPUT NL'

  33446. 

  33447. 'STATUS-ASYNC-OUTPUT ==>'

  33448.      '[ TOKEN ] "+" ASYNC-OUTPUT NL'

  33449. 

  33450. 'NOTIFY-ASYNC-OUTPUT ==>'

  33451.      '[ TOKEN ] "=" ASYNC-OUTPUT NL'

  33452. 

  33453. 'ASYNC-OUTPUT ==>'

  33454.      'ASYNC-CLASS ( "," RESULT )*'

  33455. 

  33456. 'RESULT-CLASS ==>'

  33457.      '"done" | "running" | "connected" | "error" | "exit"'

  33458. 

  33459. 'ASYNC-CLASS ==>'

  33460.      '"stopped" | OTHERS' (where OTHERS will be added depending on the

  33461.      needs--this is still in development).

  33462. 

  33463. 'RESULT ==>'

  33464.      ' VARIABLE "=" VALUE'

  33465. 

  33466. 'VARIABLE ==>'

  33467.      ' STRING '

  33468. 

  33469. 'VALUE ==>'

  33470.      ' CONST | TUPLE | LIST '

  33471. 

  33472. 'CONST ==>'

  33473.      'C-STRING'

  33474. 

  33475. 'TUPLE ==>'

  33476.      ' "{}" | "{" RESULT ( "," RESULT )* "}" '

  33477. 

  33478. 'LIST ==>'

  33479.      ' "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*

  33480.      "]" '

  33481. 

  33482. 'STREAM-RECORD ==>'

  33483.      'CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'

  33484. 

  33485. 'CONSOLE-STREAM-OUTPUT ==>'

  33486.      '"~" C-STRING NL'

  33487. 

  33488. 'TARGET-STREAM-OUTPUT ==>'

  33489.      '"@" C-STRING NL'

  33490. 

  33491. 'LOG-STREAM-OUTPUT ==>'

  33492.      '"&" C-STRING NL'

  33493. 

  33494. 'NL ==>'

  33495.      'CR | CR-LF'

  33496. 

  33497. 'TOKEN ==>'

  33498.      _any sequence of digits_.

  33499. 

  33500. Notes:

  33501. 

  33502.    * All output sequences end in a single line containing a period.

  33503. 

  33504.    * The 'TOKEN' is from the corresponding request.  Note that for all

  33505.      async output, while the token is allowed by the grammar and may be

  33506.      output by future versions of GDB for select async output messages,

  33507.      it is generally omitted.  Frontends should treat all async output

  33508.      as reporting general changes in the state of the target and there

  33509.      should be no need to associate async output to any prior command.

  33510. 

  33511.    * STATUS-ASYNC-OUTPUT contains on-going status information about the

  33512.      progress of a slow operation.  It can be discarded.  All status

  33513.      output is prefixed by '+'.

  33514. 

  33515.    * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target

  33516.      (stopped, started, disappeared).  All async output is prefixed by

  33517.      '*'.

  33518. 

  33519.    * NOTIFY-ASYNC-OUTPUT contains supplementary information that the

  33520.      client should handle (e.g., a new breakpoint information).  All

  33521.      notify output is prefixed by '='.

  33522. 

  33523.    * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in

  33524.      the console.  It is the textual response to a CLI command.  All the

  33525.      console output is prefixed by '~'.

  33526. 

  33527.    * TARGET-STREAM-OUTPUT is the output produced by the target program.

  33528.      All the target output is prefixed by '@'.

  33529. 

  33530.    * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for

  33531.      instance messages that should be displayed as part of an error log.

  33532.      All the log output is prefixed by '&'.

  33533. 

  33534.    * New GDB/MI commands should only output LISTS containing VALUES.

  33535. 

  33536.    *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details

  33537. about the various output records.

  33538. 

  33539. 

  33540. File: gdb.info,  Node: GDB/MI Compatibility with CLI,  Next: GDB/MI Development and Front Ends,  Prev: GDB/MI Command Syntax,  Up: GDB/MI

  33541. 

  33542. 27.3 GDB/MI Compatibility with CLI

  33543. ==================================

  33544. 

  33545. For the developers convenience CLI commands can be entered directly, but

  33546. there may be some unexpected behaviour.  For example, commands that

  33547. query the user will behave as if the user replied yes, breakpoint

  33548. command lists are not executed and some CLI commands, such as 'if',

  33549. 'when' and 'define', prompt for further input with '>', which is not

  33550. valid MI output.

  33551. 

  33552.    This feature may be removed at some stage in the future and it is

  33553. recommended that front ends use the '-interpreter-exec' command (*note

  33554. -interpreter-exec::).

  33555. 

  33556. 

  33557. File: gdb.info,  Node: GDB/MI Development and Front Ends,  Next: GDB/MI Output Records,  Prev: GDB/MI Compatibility with CLI,  Up: GDB/MI

  33558. 

  33559. 27.4 GDB/MI Development and Front Ends

  33560. ======================================

  33561. 

  33562. The application which takes the MI output and presents the state of the

  33563. program being debugged to the user is called a "front end".

  33564. 

  33565.    Since GDB/MI is used by a variety of front ends to GDB, changes to

  33566. the MI interface may break existing usage.  This section describes how

  33567. the protocol changes and how to request previous version of the protocol

  33568. when it does.

  33569. 

  33570.    Some changes in MI need not break a carefully designed front end, and

  33571. for these the MI version will remain unchanged.  The following is a list

  33572. of changes that may occur within one level, so front ends should parse

  33573. MI output in a way that can handle them:

  33574. 

  33575.    * New MI commands may be added.

  33576. 

  33577.    * New fields may be added to the output of any MI command.

  33578. 

  33579.    * The range of values for fields with specified values, e.g.,

  33580.      'in_scope' (*note -var-update::) may be extended.

  33581. 

  33582.    If the changes are likely to break front ends, the MI version level

  33583. will be increased by one.  The new versions of the MI protocol are not

  33584. compatible with the old versions.  Old versions of MI remain available,

  33585. allowing front ends to keep using them until they are modified to use

  33586. the latest MI version.

  33587. 

  33588.    Since '--interpreter=mi' always points to the latest MI version, it

  33589. is recommended that front ends request a specific version of MI when

  33590. launching GDB (e.g.  '--interpreter=mi2') to make sure they get an

  33591. interpreter with the MI version they expect.

  33592. 

  33593.    The following table gives a summary of the released versions of the

  33594. MI interface: the version number, the version of GDB in which it first

  33595. appeared and the breaking changes compared to the previous version.

  33596. 

  33597. MI   GDB  Breaking changes

  33598. versionversion

  33599. ----------------------------------------------------------------------------

  33600. 1    5.1  None

  33601.           

  33602. 2    6.0  

  33603.              * The '-environment-pwd', '-environment-directory' and

  33604.                '-environment-path' commands now returns values using the

  33605.                MI output syntax, rather than CLI output syntax.

  33606.           

  33607.              * '-var-list-children''s 'children' result field is now a

  33608.                list, rather than a tuple.

  33609.           

  33610.              * '-var-update''s 'changelist' result field is now a list,

  33611.                rather than a tuple.

  33612.           

  33613. 3    9.1  

  33614.              * The output of information about multi-location breakpoints

  33615.                has changed in the responses to the '-break-insert' and

  33616.                '-break-info' commands, as well as in the

  33617.                '=breakpoint-created' and '=breakpoint-modified' events.

  33618.                The multiple locations are now placed in a 'locations'

  33619.                field, whose value is a list.

  33620.           

  33621. 

  33622.    If your front end cannot yet migrate to a more recent version of the

  33623. MI protocol, you can nevertheless selectively enable specific features

  33624. available in those recent MI versions, using the following commands:

  33625. 

  33626. '-fix-multi-location-breakpoint-output'

  33627.      Use the output for multi-location breakpoints which was introduced

  33628.      by MI 3, even when using MI versions 2 or 1.  This command has no

  33629.      effect when using MI version 3 or later.

  33630. 

  33631.    The best way to avoid unexpected changes in MI that might break your

  33632. front end is to make your project known to GDB developers and follow

  33633. development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.

  33634. 

  33635. 

  33636. File: gdb.info,  Node: GDB/MI Output Records,  Next: GDB/MI Simple Examples,  Prev: GDB/MI Development and Front Ends,  Up: GDB/MI

  33637. 

  33638. 27.5 GDB/MI Output Records

  33639. ==========================

  33640. 

  33641. * Menu:

  33642. 

  33643. * GDB/MI Result Records::

  33644. * GDB/MI Stream Records::

  33645. * GDB/MI Async Records::

  33646. * GDB/MI Breakpoint Information::

  33647. * GDB/MI Frame Information::

  33648. * GDB/MI Thread Information::

  33649. * GDB/MI Ada Exception Information::

  33650. 

  33651. 

  33652. File: gdb.info,  Node: GDB/MI Result Records,  Next: GDB/MI Stream Records,  Up: GDB/MI Output Records

  33653. 

  33654. 27.5.1 GDB/MI Result Records

  33655. ----------------------------

  33656. 

  33657. In addition to a number of out-of-band notifications, the response to a

  33658. GDB/MI command includes one of the following result indications:

  33659. 

  33660. '"^done" [ "," RESULTS ]'

  33661.      The synchronous operation was successful, 'RESULTS' are the return

  33662.      values.

  33663. 

  33664. '"^running"'

  33665.      This result record is equivalent to '^done'.  Historically, it was

  33666.      output instead of '^done' if the command has resumed the target.

  33667.      This behaviour is maintained for backward compatibility, but all

  33668.      frontends should treat '^done' and '^running' identically and rely

  33669.      on the '*running' output record to determine which threads are

  33670.      resumed.

  33671. 

  33672. '"^connected"'

  33673.      GDB has connected to a remote target.

  33674. 

  33675. '"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]'

  33676.      The operation failed.  The 'msg=C-STRING' variable contains the

  33677.      corresponding error message.

  33678. 

  33679.      If present, the 'code=C-STRING' variable provides an error code on

  33680.      which consumers can rely on to detect the corresponding error

  33681.      condition.  At present, only one error code is defined:

  33682. 

  33683.      '"undefined-command"'

  33684.           Indicates that the command causing the error does not exist.

  33685. 

  33686. '"^exit"'

  33687.      GDB has terminated.

  33688. 

  33689. 

  33690. File: gdb.info,  Node: GDB/MI Stream Records,  Next: GDB/MI Async Records,  Prev: GDB/MI Result Records,  Up: GDB/MI Output Records

  33691. 

  33692. 27.5.2 GDB/MI Stream Records

  33693. ----------------------------

  33694. 

  33695. GDB internally maintains a number of output streams: the console, the

  33696. target, and the log.  The output intended for each of these streams is

  33697. funneled through the GDB/MI interface using "stream records".

  33698. 

  33699.    Each stream record begins with a unique "prefix character" which

  33700. identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output

  33701. Syntax.).  In addition to the prefix, each stream record contains a

  33702. 'STRING-OUTPUT'.  This is either raw text (with an implicit new line) or

  33703. a quoted C string (which does not contain an implicit newline).

  33704. 

  33705. '"~" STRING-OUTPUT'

  33706.      The console output stream contains text that should be displayed in

  33707.      the CLI console window.  It contains the textual responses to CLI

  33708.      commands.

  33709. 

  33710. '"@" STRING-OUTPUT'

  33711.      The target output stream contains any textual output from the

  33712.      running target.  This is only present when GDB's event loop is

  33713.      truly asynchronous, which is currently only the case for remote

  33714.      targets.

  33715. 

  33716. '"&" STRING-OUTPUT'

  33717.      The log stream contains debugging messages being produced by GDB's

  33718.      internals.

  33719. 

  33720. 

  33721. File: gdb.info,  Node: GDB/MI Async Records,  Next: GDB/MI Breakpoint Information,  Prev: GDB/MI Stream Records,  Up: GDB/MI Output Records

  33722. 

  33723. 27.5.3 GDB/MI Async Records

  33724. ---------------------------

  33725. 

  33726. "Async" records are used to notify the GDB/MI client of additional

  33727. changes that have occurred.  Those changes can either be a consequence

  33728. of GDB/MI commands (e.g., a breakpoint modified) or a result of target

  33729. activity (e.g., target stopped).

  33730. 

  33731.    The following is the list of possible async records:

  33732. 

  33733. '*running,thread-id="THREAD"'

  33734.      The target is now running.  The THREAD field can be the global

  33735.      thread ID of the thread that is now running, and it can be 'all' if

  33736.      all threads are running.  The frontend should assume that no

  33737.      interaction with a running thread is possible after this

  33738.      notification is produced.  The frontend should not assume that this

  33739.      notification is output only once for any command.  GDB may emit

  33740.      this notification several times, either for different threads,

  33741.      because it cannot resume all threads together, or even for a single

  33742.      thread, if the thread must be stepped though some code before

  33743.      letting it run freely.

  33744. 

  33745. '*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"'

  33746.      The target has stopped.  The REASON field can have one of the

  33747.      following values:

  33748. 

  33749.      'breakpoint-hit'

  33750.           A breakpoint was reached.

  33751.      'watchpoint-trigger'

  33752.           A watchpoint was triggered.

  33753.      'read-watchpoint-trigger'

  33754.           A read watchpoint was triggered.

  33755.      'access-watchpoint-trigger'

  33756.           An access watchpoint was triggered.

  33757.      'function-finished'

  33758.           An -exec-finish or similar CLI command was accomplished.

  33759.      'location-reached'

  33760.           An -exec-until or similar CLI command was accomplished.

  33761.      'watchpoint-scope'

  33762.           A watchpoint has gone out of scope.

  33763.      'end-stepping-range'

  33764.           An -exec-next, -exec-next-instruction, -exec-step,

  33765.           -exec-step-instruction or similar CLI command was

  33766.           accomplished.

  33767.      'exited-signalled'

  33768.           The inferior exited because of a signal.

  33769.      'exited'

  33770.           The inferior exited.

  33771.      'exited-normally'

  33772.           The inferior exited normally.

  33773.      'signal-received'

  33774.           A signal was received by the inferior.

  33775.      'solib-event'

  33776.           The inferior has stopped due to a library being loaded or

  33777.           unloaded.  This can happen when 'stop-on-solib-events' (*note

  33778.           Files::) is set or when a 'catch load' or 'catch unload'

  33779.           catchpoint is in use (*note Set Catchpoints::).

  33780.      'fork'

  33781.           The inferior has forked.  This is reported when 'catch fork'

  33782.           (*note Set Catchpoints::) has been used.

  33783.      'vfork'

  33784.           The inferior has vforked.  This is reported in when 'catch

  33785.           vfork' (*note Set Catchpoints::) has been used.

  33786.      'syscall-entry'

  33787.           The inferior entered a system call.  This is reported when

  33788.           'catch syscall' (*note Set Catchpoints::) has been used.

  33789.      'syscall-return'

  33790.           The inferior returned from a system call.  This is reported

  33791.           when 'catch syscall' (*note Set Catchpoints::) has been used.

  33792.      'exec'

  33793.           The inferior called 'exec'.  This is reported when 'catch

  33794.           exec' (*note Set Catchpoints::) has been used.

  33795. 

  33796.      The ID field identifies the global thread ID of the thread that

  33797.      directly caused the stop - for example by hitting a breakpoint.

  33798.      Depending on whether all-stop mode is in effect (*note All-Stop

  33799.      Mode::), GDB may either stop all threads, or only the thread that

  33800.      directly triggered the stop.  If all threads are stopped, the

  33801.      STOPPED field will have the value of '"all"'.  Otherwise, the value

  33802.      of the STOPPED field will be a list of thread identifiers.

  33803.      Presently, this list will always include a single thread, but

  33804.      frontend should be prepared to see several threads in the list.

  33805.      The CORE field reports the processor core on which the stop event

  33806.      has happened.  This field may be absent if such information is not

  33807.      available.

  33808. 

  33809. '=thread-group-added,id="ID"'

  33810. '=thread-group-removed,id="ID"'

  33811.      A thread group was either added or removed.  The ID field contains

  33812.      the GDB identifier of the thread group.  When a thread group is

  33813.      added, it generally might not be associated with a running process.

  33814.      When a thread group is removed, its id becomes invalid and cannot

  33815.      be used in any way.

  33816. 

  33817. '=thread-group-started,id="ID",pid="PID"'

  33818.      A thread group became associated with a running program, either

  33819.      because the program was just started or the thread group was

  33820.      attached to a program.  The ID field contains the GDB identifier of

  33821.      the thread group.  The PID field contains process identifier,

  33822.      specific to the operating system.

  33823. 

  33824. '=thread-group-exited,id="ID"[,exit-code="CODE"]'

  33825.      A thread group is no longer associated with a running program,

  33826.      either because the program has exited, or because it was detached

  33827.      from.  The ID field contains the GDB identifier of the thread

  33828.      group.  The CODE field is the exit code of the inferior; it exists

  33829.      only when the inferior exited with some code.

  33830. 

  33831. '=thread-created,id="ID",group-id="GID"'

  33832. '=thread-exited,id="ID",group-id="GID"'

  33833.      A thread either was created, or has exited.  The ID field contains

  33834.      the global GDB identifier of the thread.  The GID field identifies

  33835.      the thread group this thread belongs to.

  33836. 

  33837. '=thread-selected,id="ID"[,frame="FRAME"]'

  33838.      Informs that the selected thread or frame were changed.  This

  33839.      notification is not emitted as result of the '-thread-select' or

  33840.      '-stack-select-frame' commands, but is emitted whenever an MI

  33841.      command that is not documented to change the selected thread and

  33842.      frame actually changes them.  In particular, invoking, directly or

  33843.      indirectly (via user-defined command), the CLI 'thread' or 'frame'

  33844.      commands, will generate this notification.  Changing the thread or

  33845.      frame from another user interface (see *note Interpreters::) will

  33846.      also generate this notification.

  33847. 

  33848.      The FRAME field is only present if the newly selected thread is

  33849.      stopped.  See *note GDB/MI Frame Information:: for the format of

  33850.      its value.

  33851. 

  33852.      We suggest that in response to this notification, front ends

  33853.      highlight the selected thread and cause subsequent commands to

  33854.      apply to that thread.

  33855. 

  33856. '=library-loaded,...'

  33857.      Reports that a new library file was loaded by the program.  This

  33858.      notification has 5 fields--ID, TARGET-NAME, HOST-NAME,

  33859.      SYMBOLS-LOADED and RANGES.  The ID field is an opaque identifier of

  33860.      the library.  For remote debugging case, TARGET-NAME and HOST-NAME

  33861.      fields give the name of the library file on the target, and on the

  33862.      host respectively.  For native debugging, both those fields have

  33863.      the same value.  The SYMBOLS-LOADED field is emitted only for

  33864.      backward compatibility and should not be relied on to convey any

  33865.      useful information.  The THREAD-GROUP field, if present, specifies

  33866.      the id of the thread group in whose context the library was loaded.

  33867.      If the field is absent, it means the library was loaded in the

  33868.      context of all present thread groups.  The RANGES field specifies

  33869.      the ranges of addresses belonging to this library.

  33870. 

  33871. '=library-unloaded,...'

  33872.      Reports that a library was unloaded by the program.  This

  33873.      notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the

  33874.      same meaning as for the '=library-loaded' notification.  The

  33875.      THREAD-GROUP field, if present, specifies the id of the thread

  33876.      group in whose context the library was unloaded.  If the field is

  33877.      absent, it means the library was unloaded in the context of all

  33878.      present thread groups.

  33879. 

  33880. '=traceframe-changed,num=TFNUM,tracepoint=TPNUM'

  33881. '=traceframe-changed,end'

  33882.      Reports that the trace frame was changed and its new number is

  33883.      TFNUM.  The number of the tracepoint associated with this trace

  33884.      frame is TPNUM.

  33885. 

  33886. '=tsv-created,name=NAME,initial=INITIAL'

  33887.      Reports that the new trace state variable NAME is created with

  33888.      initial value INITIAL.

  33889. 

  33890. '=tsv-deleted,name=NAME'

  33891. '=tsv-deleted'

  33892.      Reports that the trace state variable NAME is deleted or all trace

  33893.      state variables are deleted.

  33894. 

  33895. '=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]'

  33896.      Reports that the trace state variable NAME is modified with the

  33897.      initial value INITIAL.  The current value CURRENT of trace state

  33898.      variable is optional and is reported if the current value of trace

  33899.      state variable is known.

  33900. 

  33901. '=breakpoint-created,bkpt={...}'

  33902. '=breakpoint-modified,bkpt={...}'

  33903. '=breakpoint-deleted,id=NUMBER'

  33904.      Reports that a breakpoint was created, modified, or deleted,

  33905.      respectively.  Only user-visible breakpoints are reported to the MI

  33906.      user.

  33907. 

  33908.      The BKPT argument is of the same form as returned by the various

  33909.      breakpoint commands; *Note GDB/MI Breakpoint Commands::.  The

  33910.      NUMBER is the ordinal number of the breakpoint.

  33911. 

  33912.      Note that if a breakpoint is emitted in the result record of a

  33913.      command, then it will not also be emitted in an async record.

  33914. 

  33915. '=record-started,thread-group="ID",method="METHOD"[,format="FORMAT"]'

  33916. '=record-stopped,thread-group="ID"'

  33917.      Execution log recording was either started or stopped on an

  33918.      inferior.  The ID is the GDB identifier of the thread group

  33919.      corresponding to the affected inferior.

  33920. 

  33921.      The METHOD field indicates the method used to record execution.  If

  33922.      the method in use supports multiple recording formats, FORMAT will

  33923.      be present and contain the currently used format.  *Note Process

  33924.      Record and Replay::, for existing method and format values.

  33925. 

  33926. '=cmd-param-changed,param=PARAM,value=VALUE'

  33927.      Reports that a parameter of the command 'set PARAM' is changed to

  33928.      VALUE.  In the multi-word 'set' command, the PARAM is the whole

  33929.      parameter list to 'set' command.  For example, In command 'set

  33930.      check type on', PARAM is 'check type' and VALUE is 'on'.

  33931. 

  33932. '=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]'

  33933.      Reports that bytes from ADDR to DATA + LEN were written in an

  33934.      inferior.  The ID is the identifier of the thread group

  33935.      corresponding to the affected inferior.  The optional 'type="code"'

  33936.      part is reported if the memory written to holds executable code.

  33937. 

  33938. 

  33939. File: gdb.info,  Node: GDB/MI Breakpoint Information,  Next: GDB/MI Frame Information,  Prev: GDB/MI Async Records,  Up: GDB/MI Output Records

  33940. 

  33941. 27.5.4 GDB/MI Breakpoint Information

  33942. ------------------------------------

  33943. 

  33944. When GDB reports information about a breakpoint, a tracepoint, a

  33945. watchpoint, or a catchpoint, it uses a tuple with the following fields:

  33946. 

  33947. 'number'

  33948.      The breakpoint number.

  33949. 

  33950. 'type'

  33951.      The type of the breakpoint.  For ordinary breakpoints this will be

  33952.      'breakpoint', but many values are possible.

  33953. 

  33954. 'catch-type'

  33955.      If the type of the breakpoint is 'catchpoint', then this indicates

  33956.      the exact type of catchpoint.

  33957. 

  33958. 'disp'

  33959.      This is the breakpoint disposition--either 'del', meaning that the

  33960.      breakpoint will be deleted at the next stop, or 'keep', meaning

  33961.      that the breakpoint will not be deleted.

  33962. 

  33963. 'enabled'

  33964.      This indicates whether the breakpoint is enabled, in which case the

  33965.      value is 'y', or disabled, in which case the value is 'n'.  Note

  33966.      that this is not the same as the field 'enable'.

  33967. 

  33968. 'addr'

  33969.      The address of the breakpoint.  This may be a hexidecimal number,

  33970.      giving the address; or the string '<PENDING>', for a pending

  33971.      breakpoint; or the string '<MULTIPLE>', for a breakpoint with

  33972.      multiple locations.  This field will not be present if no address

  33973.      can be determined.  For example, a watchpoint does not have an

  33974.      address.

  33975. 

  33976. 'addr_flags'

  33977.      Optional field containing any flags related to the address.  These

  33978.      flags are architecture-dependent; see *note Architectures:: for

  33979.      their meaning for a particular CPU.

  33980. 

  33981. 'func'

  33982.      If known, the function in which the breakpoint appears.  If not

  33983.      known, this field is not present.

  33984. 

  33985. 'filename'

  33986.      The name of the source file which contains this function, if known.

  33987.      If not known, this field is not present.

  33988. 

  33989. 'fullname'

  33990.      The full file name of the source file which contains this function,

  33991.      if known.  If not known, this field is not present.

  33992. 

  33993. 'line'

  33994.      The line number at which this breakpoint appears, if known.  If not

  33995.      known, this field is not present.

  33996. 

  33997. 'at'

  33998.      If the source file is not known, this field may be provided.  If

  33999.      provided, this holds the address of the breakpoint, possibly

  34000.      followed by a symbol name.

  34001. 

  34002. 'pending'

  34003.      If this breakpoint is pending, this field is present and holds the

  34004.      text used to set the breakpoint, as entered by the user.

  34005. 

  34006. 'evaluated-by'

  34007.      Where this breakpoint's condition is evaluated, either 'host' or

  34008.      'target'.

  34009. 

  34010. 'thread'

  34011.      If this is a thread-specific breakpoint, then this identifies the

  34012.      thread in which the breakpoint can trigger.

  34013. 

  34014. 'task'

  34015.      If this breakpoint is restricted to a particular Ada task, then

  34016.      this field will hold the task identifier.

  34017. 

  34018. 'cond'

  34019.      If the breakpoint is conditional, this is the condition expression.

  34020. 

  34021. 'ignore'

  34022.      The ignore count of the breakpoint.

  34023. 

  34024. 'enable'

  34025.      The enable count of the breakpoint.

  34026. 

  34027. 'traceframe-usage'

  34028.      FIXME.

  34029. 

  34030. 'static-tracepoint-marker-string-id'

  34031.      For a static tracepoint, the name of the static tracepoint marker.

  34032. 

  34033. 'mask'

  34034.      For a masked watchpoint, this is the mask.

  34035. 

  34036. 'pass'

  34037.      A tracepoint's pass count.

  34038. 

  34039. 'original-location'

  34040.      The location of the breakpoint as originally specified by the user.

  34041.      This field is optional.

  34042. 

  34043. 'times'

  34044.      The number of times the breakpoint has been hit.

  34045. 

  34046. 'installed'

  34047.      This field is only given for tracepoints.  This is either 'y',

  34048.      meaning that the tracepoint is installed, or 'n', meaning that it

  34049.      is not.

  34050. 

  34051. 'what'

  34052.      Some extra data, the exact contents of which are type-dependent.

  34053. 

  34054. 'locations'

  34055.      This field is present if the breakpoint has multiple locations.  It

  34056.      is also exceptionally present if the breakpoint is enabled and has

  34057.      a single, disabled location.

  34058. 

  34059.      The value is a list of locations.  The format of a location is

  34060.      described below.

  34061. 

  34062.    A location in a multi-location breakpoint is represented as a tuple

  34063. with the following fields:

  34064. 

  34065. 'number'

  34066.      The location number as a dotted pair, like '1.2'.  The first digit

  34067.      is the number of the parent breakpoint.  The second digit is the

  34068.      number of the location within that breakpoint.

  34069. 

  34070. 'enabled'

  34071.      This indicates whether the location is enabled, in which case the

  34072.      value is 'y', or disabled, in which case the value is 'n'.  Note

  34073.      that this is not the same as the field 'enable'.

  34074. 

  34075. 'addr'

  34076.      The address of this location as an hexidecimal number.

  34077. 

  34078. 'addr_flags'

  34079.      Optional field containing any flags related to the address.  These

  34080.      flags are architecture-dependent; see *note Architectures:: for

  34081.      their meaning for a particular CPU.

  34082. 

  34083. 'func'

  34084.      If known, the function in which the location appears.  If not

  34085.      known, this field is not present.

  34086. 

  34087. 'file'

  34088.      The name of the source file which contains this location, if known.

  34089.      If not known, this field is not present.

  34090. 

  34091. 'fullname'

  34092.      The full file name of the source file which contains this location,

  34093.      if known.  If not known, this field is not present.

  34094. 

  34095. 'line'

  34096.      The line number at which this location appears, if known.  If not

  34097.      known, this field is not present.

  34098. 

  34099. 'thread-groups'

  34100.      The thread groups this location is in.

  34101. 

  34102.    For example, here is what the output of '-break-insert' (*note GDB/MI

  34103. Breakpoint Commands::) might be:

  34104. 

  34105.      -> -break-insert main

  34106.      <- ^done,bkpt={number="1",type="breakpoint",disp="keep",

  34107.          enabled="y",addr="0x08048564",func="main",file="myprog.c",

  34108.          fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],

  34109.          times="0"}

  34110.      <- (gdb)

  34111. 

  34112. 

  34113. File: gdb.info,  Node: GDB/MI Frame Information,  Next: GDB/MI Thread Information,  Prev: GDB/MI Breakpoint Information,  Up: GDB/MI Output Records

  34114. 

  34115. 27.5.5 GDB/MI Frame Information

  34116. -------------------------------

  34117. 

  34118. Response from many MI commands includes an information about stack

  34119. frame.  This information is a tuple that may have the following fields:

  34120. 

  34121. 'level'

  34122.      The level of the stack frame.  The innermost frame has the level of

  34123.      zero.  This field is always present.

  34124. 

  34125. 'func'

  34126.      The name of the function corresponding to the frame.  This field

  34127.      may be absent if GDB is unable to determine the function name.

  34128. 

  34129. 'addr'

  34130.      The code address for the frame.  This field is always present.

  34131. 

  34132. 'addr_flags'

  34133.      Optional field containing any flags related to the address.  These

  34134.      flags are architecture-dependent; see *note Architectures:: for

  34135.      their meaning for a particular CPU.

  34136. 

  34137. 'file'

  34138.      The name of the source files that correspond to the frame's code

  34139.      address.  This field may be absent.

  34140. 

  34141. 'line'

  34142.      The source line corresponding to the frames' code address.  This

  34143.      field may be absent.

  34144. 

  34145. 'from'

  34146.      The name of the binary file (either executable or shared library)

  34147.      the corresponds to the frame's code address.  This field may be

  34148.      absent.

  34149. 

  34150. 

  34151. File: gdb.info,  Node: GDB/MI Thread Information,  Next: GDB/MI Ada Exception Information,  Prev: GDB/MI Frame Information,  Up: GDB/MI Output Records

  34152. 

  34153. 27.5.6 GDB/MI Thread Information

  34154. --------------------------------

  34155. 

  34156. Whenever GDB has to report an information about a thread, it uses a

  34157. tuple with the following fields.  The fields are always present unless

  34158. stated otherwise.

  34159. 

  34160. 'id'

  34161.      The global numeric id assigned to the thread by GDB.

  34162. 

  34163. 'target-id'

  34164.      The target-specific string identifying the thread.

  34165. 

  34166. 'details'

  34167.      Additional information about the thread provided by the target.  It

  34168.      is supposed to be human-readable and not interpreted by the

  34169.      frontend.  This field is optional.

  34170. 

  34171. 'name'

  34172.      The name of the thread.  If the user specified a name using the

  34173.      'thread name' command, then this name is given.  Otherwise, if GDB

  34174.      can extract the thread name from the target, then that name is

  34175.      given.  If GDB cannot find the thread name, then this field is

  34176.      omitted.

  34177. 

  34178. 'state'

  34179.      The execution state of the thread, either 'stopped' or 'running',

  34180.      depending on whether the thread is presently running.

  34181. 

  34182. 'frame'

  34183.      The stack frame currently executing in the thread.  This field is

  34184.      only present if the thread is stopped.  Its format is documented in

  34185.      *note GDB/MI Frame Information::.

  34186. 

  34187. 'core'

  34188.      The value of this field is an integer number of the processor core

  34189.      the thread was last seen on.  This field is optional.

  34190. 

  34191. 

  34192. File: gdb.info,  Node: GDB/MI Ada Exception Information,  Prev: GDB/MI Thread Information,  Up: GDB/MI Output Records

  34193. 

  34194. 27.5.7 GDB/MI Ada Exception Information

  34195. ---------------------------------------

  34196. 

  34197. Whenever a '*stopped' record is emitted because the program stopped

  34198. after hitting an exception catchpoint (*note Set Catchpoints::), GDB

  34199. provides the name of the exception that was raised via the

  34200. 'exception-name' field.  Also, for exceptions that were raised with an

  34201. exception message, GDB provides that message via the 'exception-message'

  34202. field.

  34203. 

  34204. 

  34205. File: gdb.info,  Node: GDB/MI Simple Examples,  Next: GDB/MI Command Description Format,  Prev: GDB/MI Output Records,  Up: GDB/MI

  34206. 

  34207. 27.6 Simple Examples of GDB/MI Interaction

  34208. ==========================================

  34209. 

  34210. This subsection presents several simple examples of interaction using

  34211. the GDB/MI interface.  In these examples, '->' means that the following

  34212. line is passed to GDB/MI as input, while '<-' means the output received

  34213. from GDB/MI.

  34214. 

  34215.    Note the line breaks shown in the examples are here only for

  34216. readability, they don't appear in the real output.

  34217. 

  34218. Setting a Breakpoint

  34219. --------------------

  34220. 

  34221. Setting a breakpoint generates synchronous output which contains

  34222. detailed information of the breakpoint.

  34223. 

  34224.      -> -break-insert main

  34225.      <- ^done,bkpt={number="1",type="breakpoint",disp="keep",

  34226.          enabled="y",addr="0x08048564",func="main",file="myprog.c",

  34227.          fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],

  34228.          times="0"}

  34229.      <- (gdb)

  34230. 

  34231. Program Execution

  34232. -----------------

  34233. 

  34234. Program execution generates asynchronous records and MI gives the reason

  34235. that execution stopped.

  34236. 

  34237.      -> -exec-run

  34238.      <- ^running

  34239.      <- (gdb)

  34240.      <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",

  34241.         frame={addr="0x08048564",func="main",

  34242.         args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],

  34243.         file="myprog.c",fullname="/home/nickrob/myprog.c",line="68",

  34244.         arch="i386:x86_64"}

  34245.      <- (gdb)

  34246.      -> -exec-continue

  34247.      <- ^running

  34248.      <- (gdb)

  34249.      <- *stopped,reason="exited-normally"

  34250.      <- (gdb)

  34251. 

  34252. Quitting GDB

  34253. ------------

  34254. 

  34255. Quitting GDB just prints the result class '^exit'.

  34256. 

  34257.      -> (gdb)

  34258.      <- -gdb-exit

  34259.      <- ^exit

  34260. 

  34261.    Please note that '^exit' is printed immediately, but it might take

  34262. some time for GDB to actually exit.  During that time, GDB performs

  34263. necessary cleanups, including killing programs being debugged or

  34264. disconnecting from debug hardware, so the frontend should wait till GDB

  34265. exits and should only forcibly kill GDB if it fails to exit in

  34266. reasonable time.

  34267. 

  34268. A Bad Command

  34269. -------------

  34270. 

  34271. Here's what happens if you pass a non-existent command:

  34272. 

  34273.      -> -rubbish

  34274.      <- ^error,msg="Undefined MI command: rubbish"

  34275.      <- (gdb)

  34276. 

  34277. 

  34278. File: gdb.info,  Node: GDB/MI Command Description Format,  Next: GDB/MI Breakpoint Commands,  Prev: GDB/MI Simple Examples,  Up: GDB/MI

  34279. 

  34280. 27.7 GDB/MI Command Description Format

  34281. ======================================

  34282. 

  34283. The remaining sections describe blocks of commands.  Each block of

  34284. commands is laid out in a fashion similar to this section.

  34285. 

  34286. Motivation

  34287. ----------

  34288. 

  34289. The motivation for this collection of commands.

  34290. 

  34291. Introduction

  34292. ------------

  34293. 

  34294. A brief introduction to this collection of commands as a whole.

  34295. 

  34296. Commands

  34297. --------

  34298. 

  34299. For each command in the block, the following is described:

  34300. 

  34301. Synopsis

  34302. ........

  34303. 

  34304.       -command ARGS...

  34305. 

  34306. Result

  34307. ......

  34308. 

  34309. GDB Command

  34310. ...........

  34311. 

  34312. The corresponding GDB CLI command(s), if any.

  34313. 

  34314. Example

  34315. .......

  34316. 

  34317. Example(s) formatted for readability.  Some of the described commands

  34318. have not been implemented yet and these are labeled N.A. (not

  34319. available).

  34320. 

  34321. 

  34322. File: gdb.info,  Node: GDB/MI Breakpoint Commands,  Next: GDB/MI Catchpoint Commands,  Prev: GDB/MI Command Description Format,  Up: GDB/MI

  34323. 

  34324. 27.8 GDB/MI Breakpoint Commands

  34325. ===============================

  34326. 

  34327. This section documents GDB/MI commands for manipulating breakpoints.

  34328. 

  34329. The '-break-after' Command

  34330. --------------------------

  34331. 

  34332. Synopsis

  34333. ........

  34334. 

  34335.       -break-after NUMBER COUNT

  34336. 

  34337.    The breakpoint number NUMBER is not in effect until it has been hit

  34338. COUNT times.  To see how this is reflected in the output of the

  34339. '-break-list' command, see the description of the '-break-list' command

  34340. below.

  34341. 

  34342. GDB Command

  34343. ...........

  34344. 

  34345. The corresponding GDB command is 'ignore'.

  34346. 

  34347. Example

  34348. .......

  34349. 

  34350.      (gdb)

  34351.      -break-insert main

  34352.      ^done,bkpt={number="1",type="breakpoint",disp="keep",

  34353.      enabled="y",addr="0x000100d0",func="main",file="hello.c",

  34354.      fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],

  34355.      times="0"}

  34356.      (gdb)

  34357.      -break-after 1 3

  34358.      ~

  34359.      ^done

  34360.      (gdb)

  34361.      -break-list

  34362.      ^done,BreakpointTable={nr_rows="1",nr_cols="6",

  34363.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34364.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34365.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34366.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34367.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34368.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34369.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34370.      addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",

  34371.      line="5",thread-groups=["i1"],times="0",ignore="3"}]}

  34372.      (gdb)

  34373. 

  34374. The '-break-commands' Command

  34375. -----------------------------

  34376. 

  34377. Synopsis

  34378. ........

  34379. 

  34380.       -break-commands NUMBER [ COMMAND1 ... COMMANDN ]

  34381. 

  34382.    Specifies the CLI commands that should be executed when breakpoint

  34383. NUMBER is hit.  The parameters COMMAND1 to COMMANDN are the commands.

  34384. If no command is specified, any previously-set commands are cleared.

  34385. *Note Break Commands::.  Typical use of this functionality is tracing a

  34386. program, that is, printing of values of some variables whenever

  34387. breakpoint is hit and then continuing.

  34388. 

  34389. GDB Command

  34390. ...........

  34391. 

  34392. The corresponding GDB command is 'commands'.

  34393. 

  34394. Example

  34395. .......

  34396. 

  34397.      (gdb)

  34398.      -break-insert main

  34399.      ^done,bkpt={number="1",type="breakpoint",disp="keep",

  34400.      enabled="y",addr="0x000100d0",func="main",file="hello.c",

  34401.      fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],

  34402.      times="0"}

  34403.      (gdb)

  34404.      -break-commands 1 "print v" "continue"

  34405.      ^done

  34406.      (gdb)

  34407. 

  34408. The '-break-condition' Command

  34409. ------------------------------

  34410. 

  34411. Synopsis

  34412. ........

  34413. 

  34414.       -break-condition NUMBER EXPR

  34415. 

  34416.    Breakpoint NUMBER will stop the program only if the condition in EXPR

  34417. is true.  The condition becomes part of the '-break-list' output (see

  34418. the description of the '-break-list' command below).

  34419. 

  34420. GDB Command

  34421. ...........

  34422. 

  34423. The corresponding GDB command is 'condition'.

  34424. 

  34425. Example

  34426. .......

  34427. 

  34428.      (gdb)

  34429.      -break-condition 1 1

  34430.      ^done

  34431.      (gdb)

  34432.      -break-list

  34433.      ^done,BreakpointTable={nr_rows="1",nr_cols="6",

  34434.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34435.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34436.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34437.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34438.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34439.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34440.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34441.      addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",

  34442.      line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}

  34443.      (gdb)

  34444. 

  34445. The '-break-delete' Command

  34446. ---------------------------

  34447. 

  34448. Synopsis

  34449. ........

  34450. 

  34451.       -break-delete ( BREAKPOINT )+

  34452. 

  34453.    Delete the breakpoint(s) whose number(s) are specified in the

  34454. argument list.  This is obviously reflected in the breakpoint list.

  34455. 

  34456. GDB Command

  34457. ...........

  34458. 

  34459. The corresponding GDB command is 'delete'.

  34460. 

  34461. Example

  34462. .......

  34463. 

  34464.      (gdb)

  34465.      -break-delete 1

  34466.      ^done

  34467.      (gdb)

  34468.      -break-list

  34469.      ^done,BreakpointTable={nr_rows="0",nr_cols="6",

  34470.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34471.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34472.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34473.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34474.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34475.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34476.      body=[]}

  34477.      (gdb)

  34478. 

  34479. The '-break-disable' Command

  34480. ----------------------------

  34481. 

  34482. Synopsis

  34483. ........

  34484. 

  34485.       -break-disable ( BREAKPOINT )+

  34486. 

  34487.    Disable the named BREAKPOINT(s).  The field 'enabled' in the break

  34488. list is now set to 'n' for the named BREAKPOINT(s).

  34489. 

  34490. GDB Command

  34491. ...........

  34492. 

  34493. The corresponding GDB command is 'disable'.

  34494. 

  34495. Example

  34496. .......

  34497. 

  34498.      (gdb)

  34499.      -break-disable 2

  34500.      ^done

  34501.      (gdb)

  34502.      -break-list

  34503.      ^done,BreakpointTable={nr_rows="1",nr_cols="6",

  34504.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34505.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34506.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34507.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34508.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34509.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34510.      body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",

  34511.      addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",

  34512.      line="5",thread-groups=["i1"],times="0"}]}

  34513.      (gdb)

  34514. 

  34515. The '-break-enable' Command

  34516. ---------------------------

  34517. 

  34518. Synopsis

  34519. ........

  34520. 

  34521.       -break-enable ( BREAKPOINT )+

  34522. 

  34523.    Enable (previously disabled) BREAKPOINT(s).

  34524. 

  34525. GDB Command

  34526. ...........

  34527. 

  34528. The corresponding GDB command is 'enable'.

  34529. 

  34530. Example

  34531. .......

  34532. 

  34533.      (gdb)

  34534.      -break-enable 2

  34535.      ^done

  34536.      (gdb)

  34537.      -break-list

  34538.      ^done,BreakpointTable={nr_rows="1",nr_cols="6",

  34539.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34540.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34541.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34542.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34543.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34544.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34545.      body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",

  34546.      addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",

  34547.      line="5",thread-groups=["i1"],times="0"}]}

  34548.      (gdb)

  34549. 

  34550. The '-break-info' Command

  34551. -------------------------

  34552. 

  34553. Synopsis

  34554. ........

  34555. 

  34556.       -break-info BREAKPOINT

  34557. 

  34558.    Get information about a single breakpoint.

  34559. 

  34560.    The result is a table of breakpoints.  *Note GDB/MI Breakpoint

  34561. Information::, for details on the format of each breakpoint in the

  34562. table.

  34563. 

  34564. GDB Command

  34565. ...........

  34566. 

  34567. The corresponding GDB command is 'info break BREAKPOINT'.

  34568. 

  34569. Example

  34570. .......

  34571. 

  34572. N.A.

  34573. 

  34574. The '-break-insert' Command

  34575. ---------------------------

  34576. 

  34577. Synopsis

  34578. ........

  34579. 

  34580.       -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]

  34581.          [ -c CONDITION ] [ -i IGNORE-COUNT ]

  34582.          [ -p THREAD-ID ] [ LOCATION ]

  34583. 

  34584. If specified, LOCATION, can be one of:

  34585. 

  34586. LINESPEC LOCATION

  34587.      A linespec location.  *Note Linespec Locations::.

  34588. 

  34589. EXPLICIT LOCATION

  34590.      An explicit location.  GDB/MI explicit locations are analogous to

  34591.      the CLI's explicit locations using the option names listed below.

  34592.      *Note Explicit Locations::.

  34593. 

  34594.      '--source FILENAME'

  34595.           The source file name of the location.  This option requires

  34596.           the use of either '--function' or '--line'.

  34597. 

  34598.      '--function FUNCTION'

  34599.           The name of a function or method.

  34600. 

  34601.      '--label LABEL'

  34602.           The name of a label.

  34603. 

  34604.      '--line LINEOFFSET'

  34605.           An absolute or relative line offset from the start of the

  34606.           location.

  34607. 

  34608. ADDRESS LOCATION

  34609.      An address location, *ADDRESS.  *Note Address Locations::.

  34610. 

  34611. The possible optional parameters of this command are:

  34612. 

  34613. '-t'

  34614.      Insert a temporary breakpoint.

  34615. '-h'

  34616.      Insert a hardware breakpoint.

  34617. '-f'

  34618.      If LOCATION cannot be parsed (for example if it refers to unknown

  34619.      files or functions), create a pending breakpoint.  Without this

  34620.      flag, GDB will report an error, and won't create a breakpoint, if

  34621.      LOCATION cannot be parsed.

  34622. '-d'

  34623.      Create a disabled breakpoint.

  34624. '-a'

  34625.      Create a tracepoint.  *Note Tracepoints::.  When this parameter is

  34626.      used together with '-h', a fast tracepoint is created.

  34627. '-c CONDITION'

  34628.      Make the breakpoint conditional on CONDITION.

  34629. '-i IGNORE-COUNT'

  34630.      Initialize the IGNORE-COUNT.

  34631. '-p THREAD-ID'

  34632.      Restrict the breakpoint to the thread with the specified global

  34633.      THREAD-ID.

  34634. 

  34635. Result

  34636. ......

  34637. 

  34638. *Note GDB/MI Breakpoint Information::, for details on the format of the

  34639. resulting breakpoint.

  34640. 

  34641.    Note: this format is open to change.

  34642. 

  34643. GDB Command

  34644. ...........

  34645. 

  34646. The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and

  34647. 'thbreak'.

  34648. 

  34649. Example

  34650. .......

  34651. 

  34652.      (gdb)

  34653.      -break-insert main

  34654.      ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",

  34655.      fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],

  34656.      times="0"}

  34657.      (gdb)

  34658.      -break-insert -t foo

  34659.      ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",

  34660.      fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],

  34661.      times="0"}

  34662.      (gdb)

  34663.      -break-list

  34664.      ^done,BreakpointTable={nr_rows="2",nr_cols="6",

  34665.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34666.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34667.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34668.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34669.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34670.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34671.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34672.      addr="0x0001072c", func="main",file="recursive2.c",

  34673.      fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],

  34674.      times="0"},

  34675.      bkpt={number="2",type="breakpoint",disp="del",enabled="y",

  34676.      addr="0x00010774",func="foo",file="recursive2.c",

  34677.      fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],

  34678.      times="0"}]}

  34679.      (gdb)

  34680. 

  34681. The '-dprintf-insert' Command

  34682. -----------------------------

  34683. 

  34684. Synopsis

  34685. ........

  34686. 

  34687.       -dprintf-insert [ -t ] [ -f ] [ -d ]

  34688.          [ -c CONDITION ] [ -i IGNORE-COUNT ]

  34689.          [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]

  34690.          [ ARGUMENT ]

  34691. 

  34692. If supplied, LOCATION may be specified the same way as for the

  34693. '-break-insert' command.  *Note -break-insert::.

  34694. 

  34695.    The possible optional parameters of this command are:

  34696. 

  34697. '-t'

  34698.      Insert a temporary breakpoint.

  34699. '-f'

  34700.      If LOCATION cannot be parsed (for example, if it refers to unknown

  34701.      files or functions), create a pending breakpoint.  Without this

  34702.      flag, GDB will report an error, and won't create a breakpoint, if

  34703.      LOCATION cannot be parsed.

  34704. '-d'

  34705.      Create a disabled breakpoint.

  34706. '-c CONDITION'

  34707.      Make the breakpoint conditional on CONDITION.

  34708. '-i IGNORE-COUNT'

  34709.      Set the ignore count of the breakpoint (*note ignore count:

  34710.      Conditions.) to IGNORE-COUNT.

  34711. '-p THREAD-ID'

  34712.      Restrict the breakpoint to the thread with the specified global

  34713.      THREAD-ID.

  34714. 

  34715. Result

  34716. ......

  34717. 

  34718. *Note GDB/MI Breakpoint Information::, for details on the format of the

  34719. resulting breakpoint.

  34720. 

  34721. GDB Command

  34722. ...........

  34723. 

  34724. The corresponding GDB command is 'dprintf'.

  34725. 

  34726. Example

  34727. .......

  34728. 

  34729.      (gdb)

  34730.      4-dprintf-insert foo "At foo entry\n"

  34731.      4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",

  34732.      addr="0x000000000040061b",func="foo",file="mi-dprintf.c",

  34733.      fullname="mi-dprintf.c",line="25",thread-groups=["i1"],

  34734.      times="0",script={"printf \"At foo entry\\n\"","continue"},

  34735.      original-location="foo"}

  34736.      (gdb)

  34737.      5-dprintf-insert 26 "arg=%d, g=%d\n" arg g

  34738.      5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",

  34739.      addr="0x000000000040062a",func="foo",file="mi-dprintf.c",

  34740.      fullname="mi-dprintf.c",line="26",thread-groups=["i1"],

  34741.      times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},

  34742.      original-location="mi-dprintf.c:26"}

  34743.      (gdb)

  34744. 

  34745. The '-break-list' Command

  34746. -------------------------

  34747. 

  34748. Synopsis

  34749. ........

  34750. 

  34751.       -break-list

  34752. 

  34753.    Displays the list of inserted breakpoints, showing the following

  34754. fields:

  34755. 

  34756. 'Number'

  34757.      number of the breakpoint

  34758. 'Type'

  34759.      type of the breakpoint: 'breakpoint' or 'watchpoint'

  34760. 'Disposition'

  34761.      should the breakpoint be deleted or disabled when it is hit: 'keep'

  34762.      or 'nokeep'

  34763. 'Enabled'

  34764.      is the breakpoint enabled or no: 'y' or 'n'

  34765. 'Address'

  34766.      memory location at which the breakpoint is set

  34767. 'What'

  34768.      logical location of the breakpoint, expressed by function name,

  34769.      file name, line number

  34770. 'Thread-groups'

  34771.      list of thread groups to which this breakpoint applies

  34772. 'Times'

  34773.      number of times the breakpoint has been hit

  34774. 

  34775.    If there are no breakpoints or watchpoints, the 'BreakpointTable'

  34776. 'body' field is an empty list.

  34777. 

  34778. GDB Command

  34779. ...........

  34780. 

  34781. The corresponding GDB command is 'info break'.

  34782. 

  34783. Example

  34784. .......

  34785. 

  34786.      (gdb)

  34787.      -break-list

  34788.      ^done,BreakpointTable={nr_rows="2",nr_cols="6",

  34789.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34790.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34791.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34792.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34793.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34794.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34795.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34796.      addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],

  34797.      times="0"},

  34798.      bkpt={number="2",type="breakpoint",disp="keep",enabled="y",

  34799.      addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",

  34800.      line="13",thread-groups=["i1"],times="0"}]}

  34801.      (gdb)

  34802. 

  34803.    Here's an example of the result when there are no breakpoints:

  34804. 

  34805.      (gdb)

  34806.      -break-list

  34807.      ^done,BreakpointTable={nr_rows="0",nr_cols="6",

  34808.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34809.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34810.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34811.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34812.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34813.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34814.      body=[]}

  34815.      (gdb)

  34816. 

  34817. The '-break-passcount' Command

  34818. ------------------------------

  34819. 

  34820. Synopsis

  34821. ........

  34822. 

  34823.       -break-passcount TRACEPOINT-NUMBER PASSCOUNT

  34824. 

  34825.    Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT.  If

  34826. the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,

  34827. error is emitted.  This corresponds to CLI command 'passcount'.

  34828. 

  34829. The '-break-watch' Command

  34830. --------------------------

  34831. 

  34832. Synopsis

  34833. ........

  34834. 

  34835.       -break-watch [ -a | -r ]

  34836. 

  34837.    Create a watchpoint.  With the '-a' option it will create an "access"

  34838. watchpoint, i.e., a watchpoint that triggers either on a read from or on

  34839. a write to the memory location.  With the '-r' option, the watchpoint

  34840. created is a "read" watchpoint, i.e., it will trigger only when the

  34841. memory location is accessed for reading.  Without either of the options,

  34842. the watchpoint created is a regular watchpoint, i.e., it will trigger

  34843. when the memory location is accessed for writing.  *Note Setting

  34844. Watchpoints: Set Watchpoints.

  34845. 

  34846.    Note that '-break-list' will report a single list of watchpoints and

  34847. breakpoints inserted.

  34848. 

  34849. GDB Command

  34850. ...........

  34851. 

  34852. The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'.

  34853. 

  34854. Example

  34855. .......

  34856. 

  34857. Setting a watchpoint on a variable in the 'main' function:

  34858. 

  34859.      (gdb)

  34860.      -break-watch x

  34861.      ^done,wpt={number="2",exp="x"}

  34862.      (gdb)

  34863.      -exec-continue

  34864.      ^running

  34865.      (gdb)

  34866.      *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},

  34867.      value={old="-268439212",new="55"},

  34868.      frame={func="main",args=[],file="recursive2.c",

  34869.      fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"}

  34870.      (gdb)

  34871. 

  34872.    Setting a watchpoint on a variable local to a function.  GDB will

  34873. stop the program execution twice: first for the variable changing value,

  34874. then for the watchpoint going out of scope.

  34875. 

  34876.      (gdb)

  34877.      -break-watch C

  34878.      ^done,wpt={number="5",exp="C"}

  34879.      (gdb)

  34880.      -exec-continue

  34881.      ^running

  34882.      (gdb)

  34883.      *stopped,reason="watchpoint-trigger",

  34884.      wpt={number="5",exp="C"},value={old="-276895068",new="3"},

  34885.      frame={func="callee4",args=[],

  34886.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34887.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",

  34888.      arch="i386:x86_64"}

  34889.      (gdb)

  34890.      -exec-continue

  34891.      ^running

  34892.      (gdb)

  34893.      *stopped,reason="watchpoint-scope",wpnum="5",

  34894.      frame={func="callee3",args=[{name="strarg",

  34895.      value="0x11940 \"A string argument.\""}],

  34896.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34897.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",

  34898.      arch="i386:x86_64"}

  34899.      (gdb)

  34900. 

  34901.    Listing breakpoints and watchpoints, at different points in the

  34902. program execution.  Note that once the watchpoint goes out of scope, it

  34903. is deleted.

  34904. 

  34905.      (gdb)

  34906.      -break-watch C

  34907.      ^done,wpt={number="2",exp="C"}

  34908.      (gdb)

  34909.      -break-list

  34910.      ^done,BreakpointTable={nr_rows="2",nr_cols="6",

  34911.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34912.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34913.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34914.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34915.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34916.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34917.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34918.      addr="0x00010734",func="callee4",

  34919.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34920.      fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],

  34921.      times="1"},

  34922.      bkpt={number="2",type="watchpoint",disp="keep",

  34923.      enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}

  34924.      (gdb)

  34925.      -exec-continue

  34926.      ^running

  34927.      (gdb)

  34928.      *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},

  34929.      value={old="-276895068",new="3"},

  34930.      frame={func="callee4",args=[],

  34931.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34932.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",

  34933.      arch="i386:x86_64"}

  34934.      (gdb)

  34935.      -break-list

  34936.      ^done,BreakpointTable={nr_rows="2",nr_cols="6",

  34937.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34938.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34939.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34940.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34941.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34942.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34943.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34944.      addr="0x00010734",func="callee4",

  34945.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34946.      fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],

  34947.      times="1"},

  34948.      bkpt={number="2",type="watchpoint",disp="keep",

  34949.      enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}

  34950.      (gdb)

  34951.      -exec-continue

  34952.      ^running

  34953.      ^done,reason="watchpoint-scope",wpnum="2",

  34954.      frame={func="callee3",args=[{name="strarg",

  34955.      value="0x11940 \"A string argument.\""}],

  34956.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34957.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",

  34958.      arch="i386:x86_64"}

  34959.      (gdb)

  34960.      -break-list

  34961.      ^done,BreakpointTable={nr_rows="1",nr_cols="6",

  34962.      hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},

  34963.      {width="14",alignment="-1",col_name="type",colhdr="Type"},

  34964.      {width="4",alignment="-1",col_name="disp",colhdr="Disp"},

  34965.      {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},

  34966.      {width="10",alignment="-1",col_name="addr",colhdr="Address"},

  34967.      {width="40",alignment="2",col_name="what",colhdr="What"}],

  34968.      body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  34969.      addr="0x00010734",func="callee4",

  34970.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  34971.      fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",

  34972.      thread-groups=["i1"],times="1"}]}

  34973.      (gdb)

  34974. 

  34975. 

  34976. File: gdb.info,  Node: GDB/MI Catchpoint Commands,  Next: GDB/MI Program Context,  Prev: GDB/MI Breakpoint Commands,  Up: GDB/MI

  34977. 

  34978. 27.9 GDB/MI Catchpoint Commands

  34979. ===============================

  34980. 

  34981. This section documents GDB/MI commands for manipulating catchpoints.

  34982. 

  34983. * Menu:

  34984. 

  34985. * Shared Library GDB/MI Catchpoint Commands::

  34986. * Ada Exception GDB/MI Catchpoint Commands::

  34987. * C++ Exception GDB/MI Catchpoint Commands::

  34988. 

  34989. 

  34990. File: gdb.info,  Node: Shared Library GDB/MI Catchpoint Commands,  Next: Ada Exception GDB/MI Catchpoint Commands,  Up: GDB/MI Catchpoint Commands

  34991. 

  34992. 27.9.1 Shared Library GDB/MI Catchpoints

  34993. ----------------------------------------

  34994. 

  34995. The '-catch-load' Command

  34996. -------------------------

  34997. 

  34998. Synopsis

  34999. ........

  35000. 

  35001.       -catch-load [ -t ] [ -d ] REGEXP

  35002. 

  35003.    Add a catchpoint for library load events.  If the '-t' option is

  35004. used, the catchpoint is a temporary one (*note Setting Breakpoints: Set

  35005. Breaks.).  If the '-d' option is used, the catchpoint is created in a

  35006. disabled state.  The 'regexp' argument is a regular expression used to

  35007. match the name of the loaded library.

  35008. 

  35009. GDB Command

  35010. ...........

  35011. 

  35012. The corresponding GDB command is 'catch load'.

  35013. 

  35014. Example

  35015. .......

  35016. 

  35017.      -catch-load -t foo.so

  35018.      ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y",

  35019.      what="load of library matching foo.so",catch-type="load",times="0"}

  35020.      (gdb)

  35021. 

  35022. The '-catch-unload' Command

  35023. ---------------------------

  35024. 

  35025. Synopsis

  35026. ........

  35027. 

  35028.       -catch-unload [ -t ] [ -d ] REGEXP

  35029. 

  35030.    Add a catchpoint for library unload events.  If the '-t' option is

  35031. used, the catchpoint is a temporary one (*note Setting Breakpoints: Set

  35032. Breaks.).  If the '-d' option is used, the catchpoint is created in a

  35033. disabled state.  The 'regexp' argument is a regular expression used to

  35034. match the name of the unloaded library.

  35035. 

  35036. GDB Command

  35037. ...........

  35038. 

  35039. The corresponding GDB command is 'catch unload'.

  35040. 

  35041. Example

  35042. .......

  35043. 

  35044.      -catch-unload -d bar.so

  35045.      ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n",

  35046.      what="load of library matching bar.so",catch-type="unload",times="0"}

  35047.      (gdb)

  35048. 

  35049. 

  35050. File: gdb.info,  Node: Ada Exception GDB/MI Catchpoint Commands,  Next: C++ Exception GDB/MI Catchpoint Commands,  Prev: Shared Library GDB/MI Catchpoint Commands,  Up: GDB/MI Catchpoint Commands

  35051. 

  35052. 27.9.2 Ada Exception GDB/MI Catchpoints

  35053. ---------------------------------------

  35054. 

  35055. The following GDB/MI commands can be used to create catchpoints that

  35056. stop the execution when Ada exceptions are being raised.

  35057. 

  35058. The '-catch-assert' Command

  35059. ---------------------------

  35060. 

  35061. Synopsis

  35062. ........

  35063. 

  35064.       -catch-assert [ -c CONDITION] [ -d ] [ -t ]

  35065. 

  35066.    Add a catchpoint for failed Ada assertions.

  35067. 

  35068.    The possible optional parameters for this command are:

  35069. 

  35070. '-c CONDITION'

  35071.      Make the catchpoint conditional on CONDITION.

  35072. '-d'

  35073.      Create a disabled catchpoint.

  35074. '-t'

  35075.      Create a temporary catchpoint.

  35076. 

  35077. GDB Command

  35078. ...........

  35079. 

  35080. The corresponding GDB command is 'catch assert'.

  35081. 

  35082. Example

  35083. .......

  35084. 

  35085.      -catch-assert

  35086.      ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep",

  35087.      enabled="y",addr="0x0000000000404888",what="failed Ada assertions",

  35088.      thread-groups=["i1"],times="0",

  35089.      original-location="__gnat_debug_raise_assert_failure"}

  35090.      (gdb)

  35091. 

  35092. The '-catch-exception' Command

  35093. ------------------------------

  35094. 

  35095. Synopsis

  35096. ........

  35097. 

  35098.       -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]

  35099.          [ -t ] [ -u ]

  35100. 

  35101.    Add a catchpoint stopping when Ada exceptions are raised.  By

  35102. default, the command stops the program when any Ada exception gets

  35103. raised.  But it is also possible, by using some of the optional

  35104. parameters described below, to create more selective catchpoints.

  35105. 

  35106.    The possible optional parameters for this command are:

  35107. 

  35108. '-c CONDITION'

  35109.      Make the catchpoint conditional on CONDITION.

  35110. '-d'

  35111.      Create a disabled catchpoint.

  35112. '-e EXCEPTION-NAME'

  35113.      Only stop when EXCEPTION-NAME is raised.  This option cannot be

  35114.      used combined with '-u'.

  35115. '-t'

  35116.      Create a temporary catchpoint.

  35117. '-u'

  35118.      Stop only when an unhandled exception gets raised.  This option

  35119.      cannot be used combined with '-e'.

  35120. 

  35121. GDB Command

  35122. ...........

  35123. 

  35124. The corresponding GDB commands are 'catch exception' and 'catch

  35125. exception unhandled'.

  35126. 

  35127. Example

  35128. .......

  35129. 

  35130.      -catch-exception -e Program_Error

  35131.      ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",

  35132.      enabled="y",addr="0x0000000000404874",

  35133.      what="`Program_Error' Ada exception", thread-groups=["i1"],

  35134.      times="0",original-location="__gnat_debug_raise_exception"}

  35135.      (gdb)

  35136. 

  35137. The '-catch-handlers' Command

  35138. -----------------------------

  35139. 

  35140. Synopsis

  35141. ........

  35142. 

  35143.       -catch-handlers [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]

  35144.          [ -t ]

  35145. 

  35146.    Add a catchpoint stopping when Ada exceptions are handled.  By

  35147. default, the command stops the program when any Ada exception gets

  35148. handled.  But it is also possible, by using some of the optional

  35149. parameters described below, to create more selective catchpoints.

  35150. 

  35151.    The possible optional parameters for this command are:

  35152. 

  35153. '-c CONDITION'

  35154.      Make the catchpoint conditional on CONDITION.

  35155. '-d'

  35156.      Create a disabled catchpoint.

  35157. '-e EXCEPTION-NAME'

  35158.      Only stop when EXCEPTION-NAME is handled.

  35159. '-t'

  35160.      Create a temporary catchpoint.

  35161. 

  35162. GDB Command

  35163. ...........

  35164. 

  35165. The corresponding GDB command is 'catch handlers'.

  35166. 

  35167. Example

  35168. .......

  35169. 

  35170.      -catch-handlers -e Constraint_Error

  35171.      ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",

  35172.      enabled="y",addr="0x0000000000402f68",

  35173.      what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"],

  35174.      times="0",original-location="__gnat_begin_handler"}

  35175.      (gdb)

  35176. 

  35177. 

  35178. File: gdb.info,  Node: C++ Exception GDB/MI Catchpoint Commands,  Prev: Ada Exception GDB/MI Catchpoint Commands,  Up: GDB/MI Catchpoint Commands

  35179. 

  35180. 27.9.3 C++ Exception GDB/MI Catchpoints

  35181. ---------------------------------------

  35182. 

  35183. The following GDB/MI commands can be used to create catchpoints that

  35184. stop the execution when C++ exceptions are being throw, rethrown, or

  35185. caught.

  35186. 

  35187. The '-catch-throw' Command

  35188. --------------------------

  35189. 

  35190. Synopsis

  35191. ........

  35192. 

  35193.       -catch-throw [ -t ] [ -r REGEXP]

  35194. 

  35195.    Stop when the debuggee throws a C++ exception.  If REGEXP is given,

  35196. then only exceptions whose type matches the regular expression will be

  35197. caught.

  35198. 

  35199.    If '-t' is given, then the catchpoint is enabled only for one stop,

  35200. the catchpoint is automatically deleted after stopping once for the

  35201. event.

  35202. 

  35203. GDB Command

  35204. ...........

  35205. 

  35206. The corresponding GDB commands are 'catch throw' and 'tcatch throw'

  35207. (*note Set Catchpoints::).

  35208. 

  35209. Example

  35210. .......

  35211. 

  35212.      -catch-throw -r exception_type

  35213.      ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y",

  35214.        what="exception throw",catch-type="throw",

  35215.        thread-groups=["i1"],

  35216.        regexp="exception_type",times="0"}

  35217.      (gdb)

  35218.      -exec-run

  35219.      ^running

  35220.      (gdb)

  35221.      ~"\n"

  35222.      ~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed

  35223.        in __cxa_throw () from /lib64/libstdc++.so.6\n"

  35224.      *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",

  35225.        frame={addr="0x00007ffff7ae00ed",func="__cxa_throw",

  35226.        args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"},

  35227.        thread-id="1",stopped-threads="all",core="6"

  35228.      (gdb)

  35229. 

  35230. The '-catch-rethrow' Command

  35231. ----------------------------

  35232. 

  35233. Synopsis

  35234. ........

  35235. 

  35236.       -catch-rethrow [ -t ] [ -r REGEXP]

  35237. 

  35238.    Stop when a C++ exception is re-thrown.  If REGEXP is given, then

  35239. only exceptions whose type matches the regular expression will be

  35240. caught.

  35241. 

  35242.    If '-t' is given, then the catchpoint is enabled only for one stop,

  35243. the catchpoint is automatically deleted after the first event is caught.

  35244. 

  35245. GDB Command

  35246. ...........

  35247. 

  35248. The corresponding GDB commands are 'catch rethrow' and 'tcatch rethrow'

  35249. (*note Set Catchpoints::).

  35250. 

  35251. Example

  35252. .......

  35253. 

  35254.      -catch-rethrow -r exception_type

  35255.      ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y",

  35256.        what="exception rethrow",catch-type="rethrow",

  35257.        thread-groups=["i1"],

  35258.        regexp="exception_type",times="0"}

  35259.      (gdb)

  35260.      -exec-run

  35261.      ^running

  35262.      (gdb)

  35263.      ~"\n"

  35264.      ~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed

  35265.        in __cxa_rethrow () from /lib64/libstdc++.so.6\n"

  35266.      *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",

  35267.        frame={addr="0x00007ffff7ae00ed",func="__cxa_rethrow",

  35268.        args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"},

  35269.        thread-id="1",stopped-threads="all",core="6"

  35270.      (gdb)

  35271. 

  35272. The '-catch-catch' Command

  35273. --------------------------

  35274. 

  35275. Synopsis

  35276. ........

  35277. 

  35278.       -catch-catch [ -t ] [ -r REGEXP]

  35279. 

  35280.    Stop when the debuggee catches a C++ exception.  If REGEXP is given,

  35281. then only exceptions whose type matches the regular expression will be

  35282. caught.

  35283. 

  35284.    If '-t' is given, then the catchpoint is enabled only for one stop,

  35285. the catchpoint is automatically deleted after the first event is caught.

  35286. 

  35287. GDB Command

  35288. ...........

  35289. 

  35290. The corresponding GDB commands are 'catch catch' and 'tcatch catch'

  35291. (*note Set Catchpoints::).

  35292. 

  35293. Example

  35294. .......

  35295. 

  35296.      -catch-catch -r exception_type

  35297.      ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y",

  35298.        what="exception catch",catch-type="catch",

  35299.        thread-groups=["i1"],

  35300.        regexp="exception_type",times="0"}

  35301.      (gdb)

  35302.      -exec-run

  35303.      ^running

  35304.      (gdb)

  35305.      ~"\n"

  35306.      ~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed

  35307.        in __cxa_begin_catch () from /lib64/libstdc++.so.6\n"

  35308.      *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",

  35309.        frame={addr="0x00007ffff7ae00ed",func="__cxa_begin_catch",

  35310.        args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"},

  35311.        thread-id="1",stopped-threads="all",core="6"

  35312.      (gdb)

  35313. 

  35314. 

  35315. File: gdb.info,  Node: GDB/MI Program Context,  Next: GDB/MI Thread Commands,  Prev: GDB/MI Catchpoint Commands,  Up: GDB/MI

  35316. 

  35317. 27.10 GDB/MI Program Context

  35318. ============================

  35319. 

  35320. The '-exec-arguments' Command

  35321. -----------------------------

  35322. 

  35323. Synopsis

  35324. ........

  35325. 

  35326.       -exec-arguments ARGS

  35327. 

  35328.    Set the inferior program arguments, to be used in the next

  35329. '-exec-run'.

  35330. 

  35331. GDB Command

  35332. ...........

  35333. 

  35334. The corresponding GDB command is 'set args'.

  35335. 

  35336. Example

  35337. .......

  35338. 

  35339.      (gdb)

  35340.      -exec-arguments -v word

  35341.      ^done

  35342.      (gdb)

  35343. 

  35344. The '-environment-cd' Command

  35345. -----------------------------

  35346. 

  35347. Synopsis

  35348. ........

  35349. 

  35350.       -environment-cd PATHDIR

  35351. 

  35352.    Set GDB's working directory.

  35353. 

  35354. GDB Command

  35355. ...........

  35356. 

  35357. The corresponding GDB command is 'cd'.

  35358. 

  35359. Example

  35360. .......

  35361. 

  35362.      (gdb)

  35363.      -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb

  35364.      ^done

  35365.      (gdb)

  35366. 

  35367. The '-environment-directory' Command

  35368. ------------------------------------

  35369. 

  35370. Synopsis

  35371. ........

  35372. 

  35373.       -environment-directory [ -r ] [ PATHDIR ]+

  35374. 

  35375.    Add directories PATHDIR to beginning of search path for source files.

  35376. If the '-r' option is used, the search path is reset to the default

  35377. search path.  If directories PATHDIR are supplied in addition to the

  35378. '-r' option, the search path is first reset and then addition occurs as

  35379. normal.  Multiple directories may be specified, separated by blanks.

  35380. Specifying multiple directories in a single command results in the

  35381. directories added to the beginning of the search path in the same order

  35382. they were presented in the command.  If blanks are needed as part of a

  35383. directory name, double-quotes should be used around the name.  In the

  35384. command output, the path will show up separated by the system

  35385. directory-separator character.  The directory-separator character must

  35386. not be used in any directory name.  If no directories are specified, the

  35387. current search path is displayed.

  35388. 

  35389. GDB Command

  35390. ...........

  35391. 

  35392. The corresponding GDB command is 'dir'.

  35393. 

  35394. Example

  35395. .......

  35396. 

  35397.      (gdb)

  35398.      -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb

  35399.      ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"

  35400.      (gdb)

  35401.      -environment-directory ""

  35402.      ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"

  35403.      (gdb)

  35404.      -environment-directory -r /home/jjohnstn/src/gdb /usr/src

  35405.      ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"

  35406.      (gdb)

  35407.      -environment-directory -r

  35408.      ^done,source-path="$cdir:$cwd"

  35409.      (gdb)

  35410. 

  35411. The '-environment-path' Command

  35412. -------------------------------

  35413. 

  35414. Synopsis

  35415. ........

  35416. 

  35417.       -environment-path [ -r ] [ PATHDIR ]+

  35418. 

  35419.    Add directories PATHDIR to beginning of search path for object files.

  35420. If the '-r' option is used, the search path is reset to the original

  35421. search path that existed at gdb start-up.  If directories PATHDIR are

  35422. supplied in addition to the '-r' option, the search path is first reset

  35423. and then addition occurs as normal.  Multiple directories may be

  35424. specified, separated by blanks.  Specifying multiple directories in a

  35425. single command results in the directories added to the beginning of the

  35426. search path in the same order they were presented in the command.  If

  35427. blanks are needed as part of a directory name, double-quotes should be

  35428. used around the name.  In the command output, the path will show up

  35429. separated by the system directory-separator character.  The

  35430. directory-separator character must not be used in any directory name.

  35431. If no directories are specified, the current path is displayed.

  35432. 

  35433. GDB Command

  35434. ...........

  35435. 

  35436. The corresponding GDB command is 'path'.

  35437. 

  35438. Example

  35439. .......

  35440. 

  35441.      (gdb)

  35442.      -environment-path

  35443.      ^done,path="/usr/bin"

  35444.      (gdb)

  35445.      -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin

  35446.      ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"

  35447.      (gdb)

  35448.      -environment-path -r /usr/local/bin

  35449.      ^done,path="/usr/local/bin:/usr/bin"

  35450.      (gdb)

  35451. 

  35452. The '-environment-pwd' Command

  35453. ------------------------------

  35454. 

  35455. Synopsis

  35456. ........

  35457. 

  35458.       -environment-pwd

  35459. 

  35460.    Show the current working directory.

  35461. 

  35462. GDB Command

  35463. ...........

  35464. 

  35465. The corresponding GDB command is 'pwd'.

  35466. 

  35467. Example

  35468. .......

  35469. 

  35470.      (gdb)

  35471.      -environment-pwd

  35472.      ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"

  35473.      (gdb)

  35474. 

  35475. 

  35476. File: gdb.info,  Node: GDB/MI Thread Commands,  Next: GDB/MI Ada Tasking Commands,  Prev: GDB/MI Program Context,  Up: GDB/MI

  35477. 

  35478. 27.11 GDB/MI Thread Commands

  35479. ============================

  35480. 

  35481. The '-thread-info' Command

  35482. --------------------------

  35483. 

  35484. Synopsis

  35485. ........

  35486. 

  35487.       -thread-info [ THREAD-ID ]

  35488. 

  35489.    Reports information about either a specific thread, if the THREAD-ID

  35490. parameter is present, or about all threads.  THREAD-ID is the thread's

  35491. global thread ID. When printing information about all threads, also

  35492. reports the global ID of the current thread.

  35493. 

  35494. GDB Command

  35495. ...........

  35496. 

  35497. The 'info thread' command prints the same information about all threads.

  35498. 

  35499. Result

  35500. ......

  35501. 

  35502. The result contains the following attributes:

  35503. 

  35504. 'threads'

  35505.      A list of threads.  The format of the elements of the list is

  35506.      described in *note GDB/MI Thread Information::.

  35507. 

  35508. 'current-thread-id'

  35509.      The global id of the currently selected thread.  This field is

  35510.      omitted if there is no selected thread (for example, when the

  35511.      selected inferior is not running, and therefore has no threads) or

  35512.      if a THREAD-ID argument was passed to the command.

  35513. 

  35514. Example

  35515. .......

  35516. 

  35517.      -thread-info

  35518.      ^done,threads=[

  35519.      {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",

  35520.         frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",

  35521.                 args=[]},state="running"},

  35522.      {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",

  35523.         frame={level="0",addr="0x0804891f",func="foo",

  35524.                 args=[{name="i",value="10"}],

  35525.                 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"},

  35526.                 state="running"}],

  35527.      current-thread-id="1"

  35528.      (gdb)

  35529. 

  35530. The '-thread-list-ids' Command

  35531. ------------------------------

  35532. 

  35533. Synopsis

  35534. ........

  35535. 

  35536.       -thread-list-ids

  35537. 

  35538.    Produces a list of the currently known global GDB thread ids.  At the

  35539. end of the list it also prints the total number of such threads.

  35540. 

  35541.    This command is retained for historical reasons, the '-thread-info'

  35542. command should be used instead.

  35543. 

  35544. GDB Command

  35545. ...........

  35546. 

  35547. Part of 'info threads' supplies the same information.

  35548. 

  35549. Example

  35550. .......

  35551. 

  35552.      (gdb)

  35553.      -thread-list-ids

  35554.      ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},

  35555.      current-thread-id="1",number-of-threads="3"

  35556.      (gdb)

  35557. 

  35558. The '-thread-select' Command

  35559. ----------------------------

  35560. 

  35561. Synopsis

  35562. ........

  35563. 

  35564.       -thread-select THREAD-ID

  35565. 

  35566.    Make thread with global thread number THREAD-ID the current thread.

  35567. It prints the number of the new current thread, and the topmost frame

  35568. for that thread.

  35569. 

  35570.    This command is deprecated in favor of explicitly using the

  35571. '--thread' option to each command.

  35572. 

  35573. GDB Command

  35574. ...........

  35575. 

  35576. The corresponding GDB command is 'thread'.

  35577. 

  35578. Example

  35579. .......

  35580. 

  35581.      (gdb)

  35582.      -exec-next

  35583.      ^running

  35584.      (gdb)

  35585.      *stopped,reason="end-stepping-range",thread-id="2",line="187",

  35586.      file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"

  35587.      (gdb)

  35588.      -thread-list-ids

  35589.      ^done,

  35590.      thread-ids={thread-id="3",thread-id="2",thread-id="1"},

  35591.      number-of-threads="3"

  35592.      (gdb)

  35593.      -thread-select 3

  35594.      ^done,new-thread-id="3",

  35595.      frame={level="0",func="vprintf",

  35596.      args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},

  35597.      {name="arg",value="0x2"}],file="vprintf.c",line="31",arch="i386:x86_64"}

  35598.      (gdb)

  35599. 

  35600. 

  35601. File: gdb.info,  Node: GDB/MI Ada Tasking Commands,  Next: GDB/MI Program Execution,  Prev: GDB/MI Thread Commands,  Up: GDB/MI

  35602. 

  35603. 27.12 GDB/MI Ada Tasking Commands

  35604. =================================

  35605. 

  35606. The '-ada-task-info' Command

  35607. ----------------------------

  35608. 

  35609. Synopsis

  35610. ........

  35611. 

  35612.       -ada-task-info [ TASK-ID ]

  35613. 

  35614.    Reports information about either a specific Ada task, if the TASK-ID

  35615. parameter is present, or about all Ada tasks.

  35616. 

  35617. GDB Command

  35618. ...........

  35619. 

  35620. The 'info tasks' command prints the same information about all Ada tasks

  35621. (*note Ada Tasks::).

  35622. 

  35623. Result

  35624. ......

  35625. 

  35626. The result is a table of Ada tasks.  The following columns are defined

  35627. for each Ada task:

  35628. 

  35629. 'current'

  35630.      This field exists only for the current thread.  It has the value

  35631.      '*'.

  35632. 

  35633. 'id'

  35634.      The identifier that GDB uses to refer to the Ada task.

  35635. 

  35636. 'task-id'

  35637.      The identifier that the target uses to refer to the Ada task.

  35638. 

  35639. 'thread-id'

  35640.      The global thread identifier of the thread corresponding to the Ada

  35641.      task.

  35642. 

  35643.      This field should always exist, as Ada tasks are always implemented

  35644.      on top of a thread.  But if GDB cannot find this corresponding

  35645.      thread for any reason, the field is omitted.

  35646. 

  35647. 'parent-id'

  35648.      This field exists only when the task was created by another task.

  35649.      In this case, it provides the ID of the parent task.

  35650. 

  35651. 'priority'

  35652.      The base priority of the task.

  35653. 

  35654. 'state'

  35655.      The current state of the task.  For a detailed description of the

  35656.      possible states, see *note Ada Tasks::.

  35657. 

  35658. 'name'

  35659.      The name of the task.

  35660. 

  35661. Example

  35662. .......

  35663. 

  35664.      -ada-task-info

  35665.      ^done,tasks={nr_rows="3",nr_cols="8",

  35666.      hdr=[{width="1",alignment="-1",col_name="current",colhdr=""},

  35667.      {width="3",alignment="1",col_name="id",colhdr="ID"},

  35668.      {width="9",alignment="1",col_name="task-id",colhdr="TID"},

  35669.      {width="4",alignment="1",col_name="thread-id",colhdr=""},

  35670.      {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"},

  35671.      {width="3",alignment="1",col_name="priority",colhdr="Pri"},

  35672.      {width="22",alignment="-1",col_name="state",colhdr="State"},

  35673.      {width="1",alignment="2",col_name="name",colhdr="Name"}],

  35674.      body=[{current="*",id="1",task-id="   644010",thread-id="1",priority="48",

  35675.      state="Child Termination Wait",name="main_task"}]}

  35676.      (gdb)

  35677. 

  35678. 

  35679. File: gdb.info,  Node: GDB/MI Program Execution,  Next: GDB/MI Stack Manipulation,  Prev: GDB/MI Ada Tasking Commands,  Up: GDB/MI

  35680. 

  35681. 27.13 GDB/MI Program Execution

  35682. ==============================

  35683. 

  35684. These are the asynchronous commands which generate the out-of-band

  35685. record '*stopped'.  Currently GDB only really executes asynchronously

  35686. with remote targets and this interaction is mimicked in other cases.

  35687. 

  35688. The '-exec-continue' Command

  35689. ----------------------------

  35690. 

  35691. Synopsis

  35692. ........

  35693. 

  35694.       -exec-continue [--reverse] [--all|--thread-group N]

  35695. 

  35696.    Resumes the execution of the inferior program, which will continue to

  35697. execute until it reaches a debugger stop event.  If the '--reverse'

  35698. option is specified, execution resumes in reverse until it reaches a

  35699. stop event.  Stop events may include

  35700.    * breakpoints or watchpoints

  35701.    * signals or exceptions

  35702.    * the end of the process (or its beginning under '--reverse')

  35703.    * the end or beginning of a replay log if one is being used.

  35704.    In all-stop mode (*note All-Stop Mode::), may resume only one thread,

  35705. or all threads, depending on the value of the 'scheduler-locking'

  35706. variable.  If '--all' is specified, all threads (in all inferiors) will

  35707. be resumed.  The '--all' option is ignored in all-stop mode.  If the

  35708. '--thread-group' options is specified, then all threads in that thread

  35709. group are resumed.

  35710. 

  35711. GDB Command

  35712. ...........

  35713. 

  35714. The corresponding GDB corresponding is 'continue'.

  35715. 

  35716. Example

  35717. .......

  35718. 

  35719.      -exec-continue

  35720.      ^running

  35721.      (gdb)

  35722.      @Hello world

  35723.      *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={

  35724.      func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",

  35725.      line="13",arch="i386:x86_64"}

  35726.      (gdb)

  35727. 

  35728. The '-exec-finish' Command

  35729. --------------------------

  35730. 

  35731. Synopsis

  35732. ........

  35733. 

  35734.       -exec-finish [--reverse]

  35735. 

  35736.    Resumes the execution of the inferior program until the current

  35737. function is exited.  Displays the results returned by the function.  If

  35738. the '--reverse' option is specified, resumes the reverse execution of

  35739. the inferior program until the point where current function was called.

  35740. 

  35741. GDB Command

  35742. ...........

  35743. 

  35744. The corresponding GDB command is 'finish'.

  35745. 

  35746. Example

  35747. .......

  35748. 

  35749. Function returning 'void'.

  35750. 

  35751.      -exec-finish

  35752.      ^running

  35753.      (gdb)

  35754.      @hello from foo

  35755.      *stopped,reason="function-finished",frame={func="main",args=[],

  35756.      file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"}

  35757.      (gdb)

  35758. 

  35759.    Function returning other than 'void'.  The name of the internal GDB

  35760. variable storing the result is printed, together with the value itself.

  35761. 

  35762.      -exec-finish

  35763.      ^running

  35764.      (gdb)

  35765.      *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",

  35766.      args=[{name="a",value="1"],{name="b",value="9"}},

  35767.      file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  35768.      arch="i386:x86_64"},

  35769.      gdb-result-var="$1",return-value="0"

  35770.      (gdb)

  35771. 

  35772. The '-exec-interrupt' Command

  35773. -----------------------------

  35774. 

  35775. Synopsis

  35776. ........

  35777. 

  35778.       -exec-interrupt [--all|--thread-group N]

  35779. 

  35780.    Interrupts the background execution of the target.  Note how the

  35781. token associated with the stop message is the one for the execution

  35782. command that has been interrupted.  The token for the interrupt itself

  35783. only appears in the '^done' output.  If the user is trying to interrupt

  35784. a non-running program, an error message will be printed.

  35785. 

  35786.    Note that when asynchronous execution is enabled, this command is

  35787. asynchronous just like other execution commands.  That is, first the

  35788. '^done' response will be printed, and the target stop will be reported

  35789. after that using the '*stopped' notification.

  35790. 

  35791.    In non-stop mode, only the context thread is interrupted by default.

  35792. All threads (in all inferiors) will be interrupted if the '--all' option

  35793. is specified.  If the '--thread-group' option is specified, all threads

  35794. in that group will be interrupted.

  35795. 

  35796. GDB Command

  35797. ...........

  35798. 

  35799. The corresponding GDB command is 'interrupt'.

  35800. 

  35801. Example

  35802. .......

  35803. 

  35804.      (gdb)

  35805.      111-exec-continue

  35806.      111^running

  35807. 

  35808.      (gdb)

  35809.      222-exec-interrupt

  35810.      222^done

  35811.      (gdb)

  35812.      111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",

  35813.      frame={addr="0x00010140",func="foo",args=[],file="try.c",

  35814.      fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"}

  35815.      (gdb)

  35816. 

  35817.      (gdb)

  35818.      -exec-interrupt

  35819.      ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."

  35820.      (gdb)

  35821. 

  35822. The '-exec-jump' Command

  35823. ------------------------

  35824. 

  35825. Synopsis

  35826. ........

  35827. 

  35828.       -exec-jump LOCATION

  35829. 

  35830.    Resumes execution of the inferior program at the location specified

  35831. by parameter.  *Note Specify Location::, for a description of the

  35832. different forms of LOCATION.

  35833. 

  35834. GDB Command

  35835. ...........

  35836. 

  35837. The corresponding GDB command is 'jump'.

  35838. 

  35839. Example

  35840. .......

  35841. 

  35842.      -exec-jump foo.c:10

  35843.      *running,thread-id="all"

  35844.      ^running

  35845. 

  35846. The '-exec-next' Command

  35847. ------------------------

  35848. 

  35849. Synopsis

  35850. ........

  35851. 

  35852.       -exec-next [--reverse]

  35853. 

  35854.    Resumes execution of the inferior program, stopping when the

  35855. beginning of the next source line is reached.

  35856. 

  35857.    If the '--reverse' option is specified, resumes reverse execution of

  35858. the inferior program, stopping at the beginning of the previous source

  35859. line.  If you issue this command on the first line of a function, it

  35860. will take you back to the caller of that function, to the source line

  35861. where the function was called.

  35862. 

  35863. GDB Command

  35864. ...........

  35865. 

  35866. The corresponding GDB command is 'next'.

  35867. 

  35868. Example

  35869. .......

  35870. 

  35871.      -exec-next

  35872.      ^running

  35873.      (gdb)

  35874.      *stopped,reason="end-stepping-range",line="8",file="hello.c"

  35875.      (gdb)

  35876. 

  35877. The '-exec-next-instruction' Command

  35878. ------------------------------------

  35879. 

  35880. Synopsis

  35881. ........

  35882. 

  35883.       -exec-next-instruction [--reverse]

  35884. 

  35885.    Executes one machine instruction.  If the instruction is a function

  35886. call, continues until the function returns.  If the program stops at an

  35887. instruction in the middle of a source line, the address will be printed

  35888. as well.

  35889. 

  35890.    If the '--reverse' option is specified, resumes reverse execution of

  35891. the inferior program, stopping at the previous instruction.  If the

  35892. previously executed instruction was a return from another function, it

  35893. will continue to execute in reverse until the call to that function

  35894. (from the current stack frame) is reached.

  35895. 

  35896. GDB Command

  35897. ...........

  35898. 

  35899. The corresponding GDB command is 'nexti'.

  35900. 

  35901. Example

  35902. .......

  35903. 

  35904.      (gdb)

  35905.      -exec-next-instruction

  35906.      ^running

  35907. 

  35908.      (gdb)

  35909.      *stopped,reason="end-stepping-range",

  35910.      addr="0x000100d4",line="5",file="hello.c"

  35911.      (gdb)

  35912. 

  35913. The '-exec-return' Command

  35914. --------------------------

  35915. 

  35916. Synopsis

  35917. ........

  35918. 

  35919.       -exec-return

  35920. 

  35921.    Makes current function return immediately.  Doesn't execute the

  35922. inferior.  Displays the new current frame.

  35923. 

  35924. GDB Command

  35925. ...........

  35926. 

  35927. The corresponding GDB command is 'return'.

  35928. 

  35929. Example

  35930. .......

  35931. 

  35932.      (gdb)

  35933.      200-break-insert callee4

  35934.      200^done,bkpt={number="1",addr="0x00010734",

  35935.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}

  35936.      (gdb)

  35937.      000-exec-run

  35938.      000^running

  35939.      (gdb)

  35940.      000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",

  35941.      frame={func="callee4",args=[],

  35942.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  35943.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",

  35944.      arch="i386:x86_64"}

  35945.      (gdb)

  35946.      205-break-delete

  35947.      205^done

  35948.      (gdb)

  35949.      111-exec-return

  35950.      111^done,frame={level="0",func="callee3",

  35951.      args=[{name="strarg",

  35952.      value="0x11940 \"A string argument.\""}],

  35953.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  35954.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",

  35955.      arch="i386:x86_64"}

  35956.      (gdb)

  35957. 

  35958. The '-exec-run' Command

  35959. -----------------------

  35960. 

  35961. Synopsis

  35962. ........

  35963. 

  35964.       -exec-run [ --all | --thread-group N ] [ --start ]

  35965. 

  35966.    Starts execution of the inferior from the beginning.  The inferior

  35967. executes until either a breakpoint is encountered or the program exits.

  35968. In the latter case the output will include an exit code, if the program

  35969. has exited exceptionally.

  35970. 

  35971.    When neither the '--all' nor the '--thread-group' option is

  35972. specified, the current inferior is started.  If the '--thread-group'

  35973. option is specified, it should refer to a thread group of type

  35974. 'process', and that thread group will be started.  If the '--all' option

  35975. is specified, then all inferiors will be started.

  35976. 

  35977.    Using the '--start' option instructs the debugger to stop the

  35978. execution at the start of the inferior's main subprogram, following the

  35979. same behavior as the 'start' command (*note Starting::).

  35980. 

  35981. GDB Command

  35982. ...........

  35983. 

  35984. The corresponding GDB command is 'run'.

  35985. 

  35986. Examples

  35987. ........

  35988. 

  35989.      (gdb)

  35990.      -break-insert main

  35991.      ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}

  35992.      (gdb)

  35993.      -exec-run

  35994.      ^running

  35995.      (gdb)

  35996.      *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",

  35997.      frame={func="main",args=[],file="recursive2.c",

  35998.      fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"}

  35999.      (gdb)

  36000. 

  36001. Program exited normally:

  36002. 

  36003.      (gdb)

  36004.      -exec-run

  36005.      ^running

  36006.      (gdb)

  36007.      x = 55

  36008.      *stopped,reason="exited-normally"

  36009.      (gdb)

  36010. 

  36011. Program exited exceptionally:

  36012. 

  36013.      (gdb)

  36014.      -exec-run

  36015.      ^running

  36016.      (gdb)

  36017.      x = 55

  36018.      *stopped,reason="exited",exit-code="01"

  36019.      (gdb)

  36020. 

  36021.    Another way the program can terminate is if it receives a signal such

  36022. as 'SIGINT'.  In this case, GDB/MI displays this:

  36023. 

  36024.      (gdb)

  36025.      *stopped,reason="exited-signalled",signal-name="SIGINT",

  36026.      signal-meaning="Interrupt"

  36027. 

  36028. The '-exec-step' Command

  36029. ------------------------

  36030. 

  36031. Synopsis

  36032. ........

  36033. 

  36034.       -exec-step [--reverse]

  36035. 

  36036.    Resumes execution of the inferior program, stopping when the

  36037. beginning of the next source line is reached, if the next source line is

  36038. not a function call.  If it is, stop at the first instruction of the

  36039. called function.  If the '--reverse' option is specified, resumes

  36040. reverse execution of the inferior program, stopping at the beginning of

  36041. the previously executed source line.

  36042. 

  36043. GDB Command

  36044. ...........

  36045. 

  36046. The corresponding GDB command is 'step'.

  36047. 

  36048. Example

  36049. .......

  36050. 

  36051. Stepping into a function:

  36052. 

  36053.      -exec-step

  36054.      ^running

  36055.      (gdb)

  36056.      *stopped,reason="end-stepping-range",

  36057.      frame={func="foo",args=[{name="a",value="10"},

  36058.      {name="b",value="0"}],file="recursive2.c",

  36059.      fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"}

  36060.      (gdb)

  36061. 

  36062.    Regular stepping:

  36063. 

  36064.      -exec-step

  36065.      ^running

  36066.      (gdb)

  36067.      *stopped,reason="end-stepping-range",line="14",file="recursive2.c"

  36068.      (gdb)

  36069. 

  36070. The '-exec-step-instruction' Command

  36071. ------------------------------------

  36072. 

  36073. Synopsis

  36074. ........

  36075. 

  36076.       -exec-step-instruction [--reverse]

  36077. 

  36078.    Resumes the inferior which executes one machine instruction.  If the

  36079. '--reverse' option is specified, resumes reverse execution of the

  36080. inferior program, stopping at the previously executed instruction.  The

  36081. output, once GDB has stopped, will vary depending on whether we have

  36082. stopped in the middle of a source line or not.  In the former case, the

  36083. address at which the program stopped will be printed as well.

  36084. 

  36085. GDB Command

  36086. ...........

  36087. 

  36088. The corresponding GDB command is 'stepi'.

  36089. 

  36090. Example

  36091. .......

  36092. 

  36093.      (gdb)

  36094.      -exec-step-instruction

  36095.      ^running

  36096. 

  36097.      (gdb)

  36098.      *stopped,reason="end-stepping-range",

  36099.      frame={func="foo",args=[],file="try.c",

  36100.      fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"}

  36101.      (gdb)

  36102.      -exec-step-instruction

  36103.      ^running

  36104. 

  36105.      (gdb)

  36106.      *stopped,reason="end-stepping-range",

  36107.      frame={addr="0x000100f4",func="foo",args=[],file="try.c",

  36108.      fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"}

  36109.      (gdb)

  36110. 

  36111. The '-exec-until' Command

  36112. -------------------------

  36113. 

  36114. Synopsis

  36115. ........

  36116. 

  36117.       -exec-until [ LOCATION ]

  36118. 

  36119.    Executes the inferior until the LOCATION specified in the argument is

  36120. reached.  If there is no argument, the inferior executes until a source

  36121. line greater than the current one is reached.  The reason for stopping

  36122. in this case will be 'location-reached'.

  36123. 

  36124. GDB Command

  36125. ...........

  36126. 

  36127. The corresponding GDB command is 'until'.

  36128. 

  36129. Example

  36130. .......

  36131. 

  36132.      (gdb)

  36133.      -exec-until recursive2.c:6

  36134.      ^running

  36135.      (gdb)

  36136.      x = 55

  36137.      *stopped,reason="location-reached",frame={func="main",args=[],

  36138.      file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6",

  36139.      arch="i386:x86_64"}

  36140.      (gdb)

  36141. 

  36142. 

  36143. File: gdb.info,  Node: GDB/MI Stack Manipulation,  Next: GDB/MI Variable Objects,  Prev: GDB/MI Program Execution,  Up: GDB/MI

  36144. 

  36145. 27.14 GDB/MI Stack Manipulation Commands

  36146. ========================================

  36147. 

  36148. The '-enable-frame-filters' Command

  36149. -----------------------------------

  36150. 

  36151.      -enable-frame-filters

  36152. 

  36153.    GDB allows Python-based frame filters to affect the output of the MI

  36154. commands relating to stack traces.  As there is no way to implement this

  36155. in a fully backward-compatible way, a front end must request that this

  36156. functionality be enabled.

  36157. 

  36158.    Once enabled, this feature cannot be disabled.

  36159. 

  36160.    Note that if Python support has not been compiled into GDB, this

  36161. command will still succeed (and do nothing).

  36162. 

  36163. The '-stack-info-frame' Command

  36164. -------------------------------

  36165. 

  36166. Synopsis

  36167. ........

  36168. 

  36169.       -stack-info-frame

  36170. 

  36171.    Get info on the selected frame.

  36172. 

  36173. GDB Command

  36174. ...........

  36175. 

  36176. The corresponding GDB command is 'info frame' or 'frame' (without

  36177. arguments).

  36178. 

  36179. Example

  36180. .......

  36181. 

  36182.      (gdb)

  36183.      -stack-info-frame

  36184.      ^done,frame={level="1",addr="0x0001076c",func="callee3",

  36185.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36186.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",

  36187.      arch="i386:x86_64"}

  36188.      (gdb)

  36189. 

  36190. The '-stack-info-depth' Command

  36191. -------------------------------

  36192. 

  36193. Synopsis

  36194. ........

  36195. 

  36196.       -stack-info-depth [ MAX-DEPTH ]

  36197. 

  36198.    Return the depth of the stack.  If the integer argument MAX-DEPTH is

  36199. specified, do not count beyond MAX-DEPTH frames.

  36200. 

  36201. GDB Command

  36202. ...........

  36203. 

  36204. There's no equivalent GDB command.

  36205. 

  36206. Example

  36207. .......

  36208. 

  36209. For a stack with frame levels 0 through 11:

  36210. 

  36211.      (gdb)

  36212.      -stack-info-depth

  36213.      ^done,depth="12"

  36214.      (gdb)

  36215.      -stack-info-depth 4

  36216.      ^done,depth="4"

  36217.      (gdb)

  36218.      -stack-info-depth 12

  36219.      ^done,depth="12"

  36220.      (gdb)

  36221.      -stack-info-depth 11

  36222.      ^done,depth="11"

  36223.      (gdb)

  36224.      -stack-info-depth 13

  36225.      ^done,depth="12"

  36226.      (gdb)

  36227. 

  36228. The '-stack-list-arguments' Command

  36229. -----------------------------------

  36230. 

  36231. Synopsis

  36232. ........

  36233. 

  36234.       -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES

  36235.          [ LOW-FRAME HIGH-FRAME ]

  36236. 

  36237.    Display a list of the arguments for the frames between LOW-FRAME and

  36238. HIGH-FRAME (inclusive).  If LOW-FRAME and HIGH-FRAME are not provided,

  36239. list the arguments for the whole call stack.  If the two arguments are

  36240. equal, show the single frame at the corresponding level.  It is an error

  36241. if LOW-FRAME is larger than the actual number of frames.  On the other

  36242. hand, HIGH-FRAME may be larger than the actual number of frames, in

  36243. which case only existing frames will be returned.

  36244. 

  36245.    If PRINT-VALUES is 0 or '--no-values', print only the names of the

  36246. variables; if it is 1 or '--all-values', print also their values; and if

  36247. it is 2 or '--simple-values', print the name, type and value for simple

  36248. data types, and the name and type for arrays, structures and unions.  If

  36249. the option '--no-frame-filters' is supplied, then Python frame filters

  36250. will not be executed.

  36251. 

  36252.    If the '--skip-unavailable' option is specified, arguments that are

  36253. not available are not listed.  Partially available arguments are still

  36254. displayed, however.

  36255. 

  36256.    Use of this command to obtain arguments in a single frame is

  36257. deprecated in favor of the '-stack-list-variables' command.

  36258. 

  36259. GDB Command

  36260. ...........

  36261. 

  36262. GDB does not have an equivalent command.  'gdbtk' has a 'gdb_get_args'

  36263. command which partially overlaps with the functionality of

  36264. '-stack-list-arguments'.

  36265. 

  36266. Example

  36267. .......

  36268. 

  36269.      (gdb)

  36270.      -stack-list-frames

  36271.      ^done,

  36272.      stack=[

  36273.      frame={level="0",addr="0x00010734",func="callee4",

  36274.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36275.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",

  36276.      arch="i386:x86_64"},

  36277.      frame={level="1",addr="0x0001076c",func="callee3",

  36278.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36279.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",

  36280.      arch="i386:x86_64"},

  36281.      frame={level="2",addr="0x0001078c",func="callee2",

  36282.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36283.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22",

  36284.      arch="i386:x86_64"},

  36285.      frame={level="3",addr="0x000107b4",func="callee1",

  36286.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36287.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27",

  36288.      arch="i386:x86_64"},

  36289.      frame={level="4",addr="0x000107e0",func="main",

  36290.      file="../../../devo/gdb/testsuite/gdb.mi/basics.c",

  36291.      fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32",

  36292.      arch="i386:x86_64"}]

  36293.      (gdb)

  36294.      -stack-list-arguments 0

  36295.      ^done,

  36296.      stack-args=[

  36297.      frame={level="0",args=[]},

  36298.      frame={level="1",args=[name="strarg"]},

  36299.      frame={level="2",args=[name="intarg",name="strarg"]},

  36300.      frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},

  36301.      frame={level="4",args=[]}]

  36302.      (gdb)

  36303.      -stack-list-arguments 1

  36304.      ^done,

  36305.      stack-args=[

  36306.      frame={level="0",args=[]},

  36307.      frame={level="1",

  36308.       args=[{name="strarg",value="0x11940 \"A string argument.\""}]},

  36309.      frame={level="2",args=[

  36310.      {name="intarg",value="2"},

  36311.      {name="strarg",value="0x11940 \"A string argument.\""}]},

  36312.      {frame={level="3",args=[

  36313.      {name="intarg",value="2"},

  36314.      {name="strarg",value="0x11940 \"A string argument.\""},

  36315.      {name="fltarg",value="3.5"}]},

  36316.      frame={level="4",args=[]}]

  36317.      (gdb)

  36318.      -stack-list-arguments 0 2 2

  36319.      ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]

  36320.      (gdb)

  36321.      -stack-list-arguments 1 2 2

  36322.      ^done,stack-args=[frame={level="2",

  36323.      args=[{name="intarg",value="2"},

  36324.      {name="strarg",value="0x11940 \"A string argument.\""}]}]

  36325.      (gdb)

  36326. 

  36327. The '-stack-list-frames' Command

  36328. --------------------------------

  36329. 

  36330. Synopsis

  36331. ........

  36332. 

  36333.       -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ]

  36334. 

  36335.    List the frames currently on the stack.  For each frame it displays

  36336. the following info:

  36337. 

  36338. 'LEVEL'

  36339.      The frame number, 0 being the topmost frame, i.e., the innermost

  36340.      function.

  36341. 'ADDR'

  36342.      The '$pc' value for that frame.

  36343. 'FUNC'

  36344.      Function name.

  36345. 'FILE'

  36346.      File name of the source file where the function lives.

  36347. 'FULLNAME'

  36348.      The full file name of the source file where the function lives.

  36349. 'LINE'

  36350.      Line number corresponding to the '$pc'.

  36351. 'FROM'

  36352.      The shared library where this function is defined.  This is only

  36353.      given if the frame's function is not known.

  36354. 'ARCH'

  36355.      Frame's architecture.

  36356. 

  36357.    If invoked without arguments, this command prints a backtrace for the

  36358. whole stack.  If given two integer arguments, it shows the frames whose

  36359. levels are between the two arguments (inclusive).  If the two arguments

  36360. are equal, it shows the single frame at the corresponding level.  It is

  36361. an error if LOW-FRAME is larger than the actual number of frames.  On

  36362. the other hand, HIGH-FRAME may be larger than the actual number of

  36363. frames, in which case only existing frames will be returned.  If the

  36364. option '--no-frame-filters' is supplied, then Python frame filters will

  36365. not be executed.

  36366. 

  36367. GDB Command

  36368. ...........

  36369. 

  36370. The corresponding GDB commands are 'backtrace' and 'where'.

  36371. 

  36372. Example

  36373. .......

  36374. 

  36375. Full stack backtrace:

  36376. 

  36377.      (gdb)

  36378.      -stack-list-frames

  36379.      ^done,stack=

  36380.      [frame={level="0",addr="0x0001076c",func="foo",

  36381.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11",

  36382.        arch="i386:x86_64"},

  36383.      frame={level="1",addr="0x000107a4",func="foo",

  36384.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36385.        arch="i386:x86_64"},

  36386.      frame={level="2",addr="0x000107a4",func="foo",

  36387.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36388.        arch="i386:x86_64"},

  36389.      frame={level="3",addr="0x000107a4",func="foo",

  36390.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36391.        arch="i386:x86_64"},

  36392.      frame={level="4",addr="0x000107a4",func="foo",

  36393.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36394.        arch="i386:x86_64"},

  36395.      frame={level="5",addr="0x000107a4",func="foo",

  36396.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36397.        arch="i386:x86_64"},

  36398.      frame={level="6",addr="0x000107a4",func="foo",

  36399.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36400.        arch="i386:x86_64"},

  36401.      frame={level="7",addr="0x000107a4",func="foo",

  36402.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36403.        arch="i386:x86_64"},

  36404.      frame={level="8",addr="0x000107a4",func="foo",

  36405.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36406.        arch="i386:x86_64"},

  36407.      frame={level="9",addr="0x000107a4",func="foo",

  36408.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36409.        arch="i386:x86_64"},

  36410.      frame={level="10",addr="0x000107a4",func="foo",

  36411.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36412.        arch="i386:x86_64"},

  36413.      frame={level="11",addr="0x00010738",func="main",

  36414.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4",

  36415.        arch="i386:x86_64"}]

  36416.      (gdb)

  36417. 

  36418.    Show frames between LOW_FRAME and HIGH_FRAME:

  36419. 

  36420.      (gdb)

  36421.      -stack-list-frames 3 5

  36422.      ^done,stack=

  36423.      [frame={level="3",addr="0x000107a4",func="foo",

  36424.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36425.        arch="i386:x86_64"},

  36426.      frame={level="4",addr="0x000107a4",func="foo",

  36427.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36428.        arch="i386:x86_64"},

  36429.      frame={level="5",addr="0x000107a4",func="foo",

  36430.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36431.        arch="i386:x86_64"}]

  36432.      (gdb)

  36433. 

  36434.    Show a single frame:

  36435. 

  36436.      (gdb)

  36437.      -stack-list-frames 3 3

  36438.      ^done,stack=

  36439.      [frame={level="3",addr="0x000107a4",func="foo",

  36440.        file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",

  36441.        arch="i386:x86_64"}]

  36442.      (gdb)

  36443. 

  36444. The '-stack-list-locals' Command

  36445. --------------------------------

  36446. 

  36447. Synopsis

  36448. ........

  36449. 

  36450.       -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES

  36451. 

  36452.    Display the local variable names for the selected frame.  If

  36453. PRINT-VALUES is 0 or '--no-values', print only the names of the

  36454. variables; if it is 1 or '--all-values', print also their values; and if

  36455. it is 2 or '--simple-values', print the name, type and value for simple

  36456. data types, and the name and type for arrays, structures and unions.  In

  36457. this last case, a frontend can immediately display the value of simple

  36458. data types and create variable objects for other data types when the

  36459. user wishes to explore their values in more detail.  If the option

  36460. '--no-frame-filters' is supplied, then Python frame filters will not be

  36461. executed.

  36462. 

  36463.    If the '--skip-unavailable' option is specified, local variables that

  36464. are not available are not listed.  Partially available local variables

  36465. are still displayed, however.

  36466. 

  36467.    This command is deprecated in favor of the '-stack-list-variables'

  36468. command.

  36469. 

  36470. GDB Command

  36471. ...........

  36472. 

  36473. 'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'.

  36474. 

  36475. Example

  36476. .......

  36477. 

  36478.      (gdb)

  36479.      -stack-list-locals 0

  36480.      ^done,locals=[name="A",name="B",name="C"]

  36481.      (gdb)

  36482.      -stack-list-locals --all-values

  36483.      ^done,locals=[{name="A",value="1"},{name="B",value="2"},

  36484.        {name="C",value="{1, 2, 3}"}]

  36485.      -stack-list-locals --simple-values

  36486.      ^done,locals=[{name="A",type="int",value="1"},

  36487.        {name="B",type="int",value="2"},{name="C",type="int [3]"}]

  36488.      (gdb)

  36489. 

  36490. The '-stack-list-variables' Command

  36491. -----------------------------------

  36492. 

  36493. Synopsis

  36494. ........

  36495. 

  36496.       -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES

  36497. 

  36498.    Display the names of local variables and function arguments for the

  36499. selected frame.  If PRINT-VALUES is 0 or '--no-values', print only the

  36500. names of the variables; if it is 1 or '--all-values', print also their

  36501. values; and if it is 2 or '--simple-values', print the name, type and

  36502. value for simple data types, and the name and type for arrays,

  36503. structures and unions.  If the option '--no-frame-filters' is supplied,

  36504. then Python frame filters will not be executed.

  36505. 

  36506.    If the '--skip-unavailable' option is specified, local variables and

  36507. arguments that are not available are not listed.  Partially available

  36508. arguments and local variables are still displayed, however.

  36509. 

  36510. Example

  36511. .......

  36512. 

  36513.      (gdb)

  36514.      -stack-list-variables --thread 1 --frame 0 --all-values

  36515.      ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]

  36516.      (gdb)

  36517. 

  36518. The '-stack-select-frame' Command

  36519. ---------------------------------

  36520. 

  36521. Synopsis

  36522. ........

  36523. 

  36524.       -stack-select-frame FRAMENUM

  36525. 

  36526.    Change the selected frame.  Select a different frame FRAMENUM on the

  36527. stack.

  36528. 

  36529.    This command in deprecated in favor of passing the '--frame' option

  36530. to every command.

  36531. 

  36532. GDB Command

  36533. ...........

  36534. 

  36535. The corresponding GDB commands are 'frame', 'up', 'down',

  36536. 'select-frame', 'up-silent', and 'down-silent'.

  36537. 

  36538. Example

  36539. .......

  36540. 

  36541.      (gdb)

  36542.      -stack-select-frame 2

  36543.      ^done

  36544.      (gdb)

  36545. 

  36546. 

  36547. File: gdb.info,  Node: GDB/MI Variable Objects,  Next: GDB/MI Data Manipulation,  Prev: GDB/MI Stack Manipulation,  Up: GDB/MI

  36548. 

  36549. 27.15 GDB/MI Variable Objects

  36550. =============================

  36551. 

  36552. Introduction to Variable Objects

  36553. --------------------------------

  36554. 

  36555. Variable objects are "object-oriented" MI interface for examining and

  36556. changing values of expressions.  Unlike some other MI interfaces that

  36557. work with expressions, variable objects are specifically designed for

  36558. simple and efficient presentation in the frontend.  A variable object is

  36559. identified by string name.  When a variable object is created, the

  36560. frontend specifies the expression for that variable object.  The

  36561. expression can be a simple variable, or it can be an arbitrary complex

  36562. expression, and can even involve CPU registers.  After creating a

  36563. variable object, the frontend can invoke other variable object

  36564. operations--for example to obtain or change the value of a variable

  36565. object, or to change display format.

  36566. 

  36567.    Variable objects have hierarchical tree structure.  Any variable

  36568. object that corresponds to a composite type, such as structure in C, has

  36569. a number of child variable objects, for example corresponding to each

  36570. element of a structure.  A child variable object can itself have

  36571. children, recursively.  Recursion ends when we reach leaf variable

  36572. objects, which always have built-in types.  Child variable objects are

  36573. created only by explicit request, so if a frontend is not interested in

  36574. the children of a particular variable object, no child will be created.

  36575. 

  36576.    For a leaf variable object it is possible to obtain its value as a

  36577. string, or set the value from a string.  String value can be also

  36578. obtained for a non-leaf variable object, but it's generally a string

  36579. that only indicates the type of the object, and does not list its

  36580. contents.  Assignment to a non-leaf variable object is not allowed.

  36581. 

  36582.    A frontend does not need to read the values of all variable objects

  36583. each time the program stops.  Instead, MI provides an update command

  36584. that lists all variable objects whose values has changed since the last

  36585. update operation.  This considerably reduces the amount of data that

  36586. must be transferred to the frontend.  As noted above, children variable

  36587. objects are created on demand, and only leaf variable objects have a

  36588. real value.  As result, gdb will read target memory only for leaf

  36589. variables that frontend has created.

  36590. 

  36591.    The automatic update is not always desirable.  For example, a

  36592. frontend might want to keep a value of some expression for future

  36593. reference, and never update it.  For another example, fetching memory is

  36594. relatively slow for embedded targets, so a frontend might want to

  36595. disable automatic update for the variables that are either not visible

  36596. on the screen, or "closed".  This is possible using so called "frozen

  36597. variable objects".  Such variable objects are never implicitly updated.

  36598. 

  36599.    Variable objects can be either "fixed" or "floating".  For the fixed

  36600. variable object, the expression is parsed when the variable object is

  36601. created, including associating identifiers to specific variables.  The

  36602. meaning of expression never changes.  For a floating variable object the

  36603. values of variables whose names appear in the expressions are

  36604. re-evaluated every time in the context of the current frame.  Consider

  36605. this example:

  36606. 

  36607.      void do_work(...)

  36608.      {

  36609.              struct work_state state;

  36610. 

  36611.              if (...)

  36612.                 do_work(...);

  36613.      }

  36614. 

  36615.    If a fixed variable object for the 'state' variable is created in

  36616. this function, and we enter the recursive call, the variable object will

  36617. report the value of 'state' in the top-level 'do_work' invocation.  On

  36618. the other hand, a floating variable object will report the value of

  36619. 'state' in the current frame.

  36620. 

  36621.    If an expression specified when creating a fixed variable object

  36622. refers to a local variable, the variable object becomes bound to the

  36623. thread and frame in which the variable object is created.  When such

  36624. variable object is updated, GDB makes sure that the thread/frame

  36625. combination the variable object is bound to still exists, and

  36626. re-evaluates the variable object in context of that thread/frame.

  36627. 

  36628.    The following is the complete set of GDB/MI operations defined to

  36629. access this functionality:

  36630. 

  36631. *Operation*                   *Description*

  36632.                               

  36633. '-enable-pretty-printing'     enable Python-based pretty-printing

  36634. '-var-create'                 create a variable object

  36635. '-var-delete'                 delete the variable object and/or its

  36636.                               children

  36637. '-var-set-format'             set the display format of this variable

  36638. '-var-show-format'            show the display format of this variable

  36639. '-var-info-num-children'      tells how many children this object has

  36640. '-var-list-children'          return a list of the object's children

  36641. '-var-info-type'              show the type of this variable object

  36642. '-var-info-expression'        print parent-relative expression that

  36643.                               this variable object represents

  36644. '-var-info-path-expression'   print full expression that this variable

  36645.                               object represents

  36646. '-var-show-attributes'        is this variable editable?  does it exist

  36647.                               here?

  36648. '-var-evaluate-expression'    get the value of this variable

  36649. '-var-assign'                 set the value of this variable

  36650. '-var-update'                 update the variable and its children

  36651. '-var-set-frozen'             set frozenness attribute

  36652. '-var-set-update-range'       set range of children to display on

  36653.                               update

  36654. 

  36655.    In the next subsection we describe each operation in detail and

  36656. suggest how it can be used.

  36657. 

  36658. Description And Use of Operations on Variable Objects

  36659. -----------------------------------------------------

  36660. 

  36661. The '-enable-pretty-printing' Command

  36662. -------------------------------------

  36663. 

  36664.      -enable-pretty-printing

  36665. 

  36666.    GDB allows Python-based visualizers to affect the output of the MI

  36667. variable object commands.  However, because there was no way to

  36668. implement this in a fully backward-compatible way, a front end must

  36669. request that this functionality be enabled.

  36670. 

  36671.    Once enabled, this feature cannot be disabled.

  36672. 

  36673.    Note that if Python support has not been compiled into GDB, this

  36674. command will still succeed (and do nothing).

  36675. 

  36676.    This feature is currently (as of GDB 7.0) experimental, and may work

  36677. differently in future versions of GDB.

  36678. 

  36679. The '-var-create' Command

  36680. -------------------------

  36681. 

  36682. Synopsis

  36683. ........

  36684. 

  36685.       -var-create {NAME | "-"}

  36686.          {FRAME-ADDR | "*" | "@"} EXPRESSION

  36687. 

  36688.    This operation creates a variable object, which allows the monitoring

  36689. of a variable, the result of an expression, a memory cell or a CPU

  36690. register.

  36691. 

  36692.    The NAME parameter is the string by which the object can be

  36693. referenced.  It must be unique.  If '-' is specified, the varobj system

  36694. will generate a string "varNNNNNN" automatically.  It will be unique

  36695. provided that one does not specify NAME of that format.  The command

  36696. fails if a duplicate name is found.

  36697. 

  36698.    The frame under which the expression should be evaluated can be

  36699. specified by FRAME-ADDR.  A '*' indicates that the current frame should

  36700. be used.  A '@' indicates that a floating variable object must be

  36701. created.

  36702. 

  36703.    EXPRESSION is any expression valid on the current language set (must

  36704. not begin with a '*'), or one of the following:

  36705. 

  36706.    * '*ADDR', where ADDR is the address of a memory cell

  36707. 

  36708.    * '*ADDR-ADDR' -- a memory address range (TBD)

  36709. 

  36710.    * '$REGNAME' -- a CPU register name

  36711. 

  36712.    A varobj's contents may be provided by a Python-based pretty-printer.

  36713. In this case the varobj is known as a "dynamic varobj".  Dynamic varobjs

  36714. have slightly different semantics in some cases.  If the

  36715. '-enable-pretty-printing' command is not sent, then GDB will never

  36716. create a dynamic varobj.  This ensures backward compatibility for

  36717. existing clients.

  36718. 

  36719. Result

  36720. ......

  36721. 

  36722. This operation returns attributes of the newly-created varobj.  These

  36723. are:

  36724. 

  36725. 'name'

  36726.      The name of the varobj.

  36727. 

  36728. 'numchild'

  36729.      The number of children of the varobj.  This number is not

  36730.      necessarily reliable for a dynamic varobj.  Instead, you must

  36731.      examine the 'has_more' attribute.

  36732. 

  36733. 'value'

  36734.      The varobj's scalar value.  For a varobj whose type is some sort of

  36735.      aggregate (e.g., a 'struct'), or for a dynamic varobj, this value

  36736.      will not be interesting.

  36737. 

  36738. 'type'

  36739.      The varobj's type.  This is a string representation of the type, as

  36740.      would be printed by the GDB CLI. If 'print object' (*note set print

  36741.      object: Print Settings.) is set to 'on', the _actual_ (derived)

  36742.      type of the object is shown rather than the _declared_ one.

  36743. 

  36744. 'thread-id'

  36745.      If a variable object is bound to a specific thread, then this is

  36746.      the thread's global identifier.

  36747. 

  36748. 'has_more'

  36749.      For a dynamic varobj, this indicates whether there appear to be any

  36750.      children available.  For a non-dynamic varobj, this will be 0.

  36751. 

  36752. 'dynamic'

  36753.      This attribute will be present and have the value '1' if the varobj

  36754.      is a dynamic varobj.  If the varobj is not a dynamic varobj, then

  36755.      this attribute will not be present.

  36756. 

  36757. 'displayhint'

  36758.      A dynamic varobj can supply a display hint to the front end.  The

  36759.      value comes directly from the Python pretty-printer object's

  36760.      'display_hint' method.  *Note Pretty Printing API::.

  36761. 

  36762.    Typical output will look like this:

  36763. 

  36764.       name="NAME",numchild="N",type="TYPE",thread-id="M",

  36765.        has_more="HAS_MORE"

  36766. 

  36767. The '-var-delete' Command

  36768. -------------------------

  36769. 

  36770. Synopsis

  36771. ........

  36772. 

  36773.       -var-delete [ -c ] NAME

  36774. 

  36775.    Deletes a previously created variable object and all of its children.

  36776. With the '-c' option, just deletes the children.

  36777. 

  36778.    Returns an error if the object NAME is not found.

  36779. 

  36780. The '-var-set-format' Command

  36781. -----------------------------

  36782. 

  36783. Synopsis

  36784. ........

  36785. 

  36786.       -var-set-format NAME FORMAT-SPEC

  36787. 

  36788.    Sets the output format for the value of the object NAME to be

  36789. FORMAT-SPEC.

  36790. 

  36791.    The syntax for the FORMAT-SPEC is as follows:

  36792. 

  36793.       FORMAT-SPEC ==>

  36794.       {binary | decimal | hexadecimal | octal | natural | zero-hexadecimal}

  36795. 

  36796.    The natural format is the default format choosen automatically based

  36797. on the variable type (like decimal for an 'int', hex for pointers,

  36798. etc.).

  36799. 

  36800.    The zero-hexadecimal format has a representation similar to

  36801. hexadecimal but with padding zeroes to the left of the value.  For

  36802. example, a 32-bit hexadecimal value of 0x1234 would be represented as

  36803. 0x00001234 in the zero-hexadecimal format.

  36804. 

  36805.    For a variable with children, the format is set only on the variable

  36806. itself, and the children are not affected.

  36807. 

  36808. The '-var-show-format' Command

  36809. ------------------------------

  36810. 

  36811. Synopsis

  36812. ........

  36813. 

  36814.       -var-show-format NAME

  36815. 

  36816.    Returns the format used to display the value of the object NAME.

  36817. 

  36818.       FORMAT ==>

  36819.       FORMAT-SPEC

  36820. 

  36821. The '-var-info-num-children' Command

  36822. ------------------------------------

  36823. 

  36824. Synopsis

  36825. ........

  36826. 

  36827.       -var-info-num-children NAME

  36828. 

  36829.    Returns the number of children of a variable object NAME:

  36830. 

  36831.       numchild=N

  36832. 

  36833.    Note that this number is not completely reliable for a dynamic

  36834. varobj.  It will return the current number of children, but more

  36835. children may be available.

  36836. 

  36837. The '-var-list-children' Command

  36838. --------------------------------

  36839. 

  36840. Synopsis

  36841. ........

  36842. 

  36843.       -var-list-children [PRINT-VALUES] NAME [FROM TO]

  36844. 

  36845.    Return a list of the children of the specified variable object and

  36846. create variable objects for them, if they do not already exist.  With a

  36847. single argument or if PRINT-VALUES has a value of 0 or '--no-values',

  36848. print only the names of the variables; if PRINT-VALUES is 1 or

  36849. '--all-values', also print their values; and if it is 2 or

  36850. '--simple-values' print the name and value for simple data types and

  36851. just the name for arrays, structures and unions.

  36852. 

  36853.    FROM and TO, if specified, indicate the range of children to report.

  36854. If FROM or TO is less than zero, the range is reset and all children

  36855. will be reported.  Otherwise, children starting at FROM (zero-based) and

  36856. up to and excluding TO will be reported.

  36857. 

  36858.    If a child range is requested, it will only affect the current call

  36859. to '-var-list-children', but not future calls to '-var-update'.  For

  36860. this, you must instead use '-var-set-update-range'.  The intent of this

  36861. approach is to enable a front end to implement any update approach it

  36862. likes; for example, scrolling a view may cause the front end to request

  36863. more children with '-var-list-children', and then the front end could

  36864. call '-var-set-update-range' with a different range to ensure that

  36865. future updates are restricted to just the visible items.

  36866. 

  36867.    For each child the following results are returned:

  36868. 

  36869. NAME

  36870.      Name of the variable object created for this child.

  36871. 

  36872. EXP

  36873.      The expression to be shown to the user by the front end to

  36874.      designate this child.  For example this may be the name of a

  36875.      structure member.

  36876. 

  36877.      For a dynamic varobj, this value cannot be used to form an

  36878.      expression.  There is no way to do this at all with a dynamic

  36879.      varobj.

  36880. 

  36881.      For C/C++ structures there are several pseudo children returned to

  36882.      designate access qualifiers.  For these pseudo children EXP is

  36883.      'public', 'private', or 'protected'.  In this case the type and

  36884.      value are not present.

  36885. 

  36886.      A dynamic varobj will not report the access qualifying

  36887.      pseudo-children, regardless of the language.  This information is

  36888.      not available at all with a dynamic varobj.

  36889. 

  36890. NUMCHILD

  36891.      Number of children this child has.  For a dynamic varobj, this will

  36892.      be 0.

  36893. 

  36894. TYPE

  36895.      The type of the child.  If 'print object' (*note set print object:

  36896.      Print Settings.) is set to 'on', the _actual_ (derived) type of the

  36897.      object is shown rather than the _declared_ one.

  36898. 

  36899. VALUE

  36900.      If values were requested, this is the value.

  36901. 

  36902. THREAD-ID

  36903.      If this variable object is associated with a thread, this is the

  36904.      thread's global thread id.  Otherwise this result is not present.

  36905. 

  36906. FROZEN

  36907.      If the variable object is frozen, this variable will be present

  36908.      with a value of 1.

  36909. 

  36910. DISPLAYHINT

  36911.      A dynamic varobj can supply a display hint to the front end.  The

  36912.      value comes directly from the Python pretty-printer object's

  36913.      'display_hint' method.  *Note Pretty Printing API::.

  36914. 

  36915. DYNAMIC

  36916.      This attribute will be present and have the value '1' if the varobj

  36917.      is a dynamic varobj.  If the varobj is not a dynamic varobj, then

  36918.      this attribute will not be present.

  36919. 

  36920.    The result may have its own attributes:

  36921. 

  36922. 'displayhint'

  36923.      A dynamic varobj can supply a display hint to the front end.  The

  36924.      value comes directly from the Python pretty-printer object's

  36925.      'display_hint' method.  *Note Pretty Printing API::.

  36926. 

  36927. 'has_more'

  36928.      This is an integer attribute which is nonzero if there are children

  36929.      remaining after the end of the selected range.

  36930. 

  36931. Example

  36932. .......

  36933. 

  36934.      (gdb)

  36935.       -var-list-children n

  36936.       ^done,numchild=N,children=[child={name=NAME,exp=EXP,

  36937.       numchild=N,type=TYPE},(repeats N times)]

  36938.      (gdb)

  36939.       -var-list-children --all-values n

  36940.       ^done,numchild=N,children=[child={name=NAME,exp=EXP,

  36941.       numchild=N,value=VALUE,type=TYPE},(repeats N times)]

  36942. 

  36943. The '-var-info-type' Command

  36944. ----------------------------

  36945. 

  36946. Synopsis

  36947. ........

  36948. 

  36949.       -var-info-type NAME

  36950. 

  36951.    Returns the type of the specified variable NAME.  The type is

  36952. returned as a string in the same format as it is output by the GDB CLI:

  36953. 

  36954.       type=TYPENAME

  36955. 

  36956. The '-var-info-expression' Command

  36957. ----------------------------------

  36958. 

  36959. Synopsis

  36960. ........

  36961. 

  36962.       -var-info-expression NAME

  36963. 

  36964.    Returns a string that is suitable for presenting this variable object

  36965. in user interface.  The string is generally not valid expression in the

  36966. current language, and cannot be evaluated.

  36967. 

  36968.    For example, if 'a' is an array, and variable object 'A' was created

  36969. for 'a', then we'll get this output:

  36970. 

  36971.      (gdb) -var-info-expression A.1

  36972.      ^done,lang="C",exp="1"

  36973. 

  36974. Here, the value of 'lang' is the language name, which can be found in

  36975. *note Supported Languages::.

  36976. 

  36977.    Note that the output of the '-var-list-children' command also

  36978. includes those expressions, so the '-var-info-expression' command is of

  36979. limited use.

  36980. 

  36981. The '-var-info-path-expression' Command

  36982. ---------------------------------------

  36983. 

  36984. Synopsis

  36985. ........

  36986. 

  36987.       -var-info-path-expression NAME

  36988. 

  36989.    Returns an expression that can be evaluated in the current context

  36990. and will yield the same value that a variable object has.  Compare this

  36991. with the '-var-info-expression' command, which result can be used only

  36992. for UI presentation.  Typical use of the '-var-info-path-expression'

  36993. command is creating a watchpoint from a variable object.

  36994. 

  36995.    This command is currently not valid for children of a dynamic varobj,

  36996. and will give an error when invoked on one.

  36997. 

  36998.    For example, suppose 'C' is a C++ class, derived from class 'Base',

  36999. and that the 'Base' class has a member called 'm_size'.  Assume a

  37000. variable 'c' is has the type of 'C' and a variable object 'C' was

  37001. created for variable 'c'.  Then, we'll get this output:

  37002.      (gdb) -var-info-path-expression C.Base.public.m_size

  37003.      ^done,path_expr=((Base)c).m_size)

  37004. 

  37005. The '-var-show-attributes' Command

  37006. ----------------------------------

  37007. 

  37008. Synopsis

  37009. ........

  37010. 

  37011.       -var-show-attributes NAME

  37012. 

  37013.    List attributes of the specified variable object NAME:

  37014. 

  37015.       status=ATTR [ ( ,ATTR )* ]

  37016. 

  37017. where ATTR is '{ { editable | noneditable } | TBD }'.

  37018. 

  37019. The '-var-evaluate-expression' Command

  37020. --------------------------------------

  37021. 

  37022. Synopsis

  37023. ........

  37024. 

  37025.       -var-evaluate-expression [-f FORMAT-SPEC] NAME

  37026. 

  37027.    Evaluates the expression that is represented by the specified

  37028. variable object and returns its value as a string.  The format of the

  37029. string can be specified with the '-f' option.  The possible values of

  37030. this option are the same as for '-var-set-format' (*note

  37031. -var-set-format::).  If the '-f' option is not specified, the current

  37032. display format will be used.  The current display format can be changed

  37033. using the '-var-set-format' command.

  37034. 

  37035.       value=VALUE

  37036. 

  37037.    Note that one must invoke '-var-list-children' for a variable before

  37038. the value of a child variable can be evaluated.

  37039. 

  37040. The '-var-assign' Command

  37041. -------------------------

  37042. 

  37043. Synopsis

  37044. ........

  37045. 

  37046.       -var-assign NAME EXPRESSION

  37047. 

  37048.    Assigns the value of EXPRESSION to the variable object specified by

  37049. NAME.  The object must be 'editable'.  If the variable's value is

  37050. altered by the assign, the variable will show up in any subsequent

  37051. '-var-update' list.

  37052. 

  37053. Example

  37054. .......

  37055. 

  37056.      (gdb)

  37057.      -var-assign var1 3

  37058.      ^done,value="3"

  37059.      (gdb)

  37060.      -var-update *

  37061.      ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]

  37062.      (gdb)

  37063. 

  37064. The '-var-update' Command

  37065. -------------------------

  37066. 

  37067. Synopsis

  37068. ........

  37069. 

  37070.       -var-update [PRINT-VALUES] {NAME | "*"}

  37071. 

  37072.    Reevaluate the expressions corresponding to the variable object NAME

  37073. and all its direct and indirect children, and return the list of

  37074. variable objects whose values have changed; NAME must be a root variable

  37075. object.  Here, "changed" means that the result of

  37076. '-var-evaluate-expression' before and after the '-var-update' is

  37077. different.  If '*' is used as the variable object names, all existing

  37078. variable objects are updated, except for frozen ones (*note

  37079. -var-set-frozen::).  The option PRINT-VALUES determines whether both

  37080. names and values, or just names are printed.  The possible values of

  37081. this option are the same as for '-var-list-children' (*note

  37082. -var-list-children::).  It is recommended to use the '--all-values'

  37083. option, to reduce the number of MI commands needed on each program stop.

  37084. 

  37085.    With the '*' parameter, if a variable object is bound to a currently

  37086. running thread, it will not be updated, without any diagnostic.

  37087. 

  37088.    If '-var-set-update-range' was previously used on a varobj, then only

  37089. the selected range of children will be reported.

  37090. 

  37091.    '-var-update' reports all the changed varobjs in a tuple named

  37092. 'changelist'.

  37093. 

  37094.    Each item in the change list is itself a tuple holding:

  37095. 

  37096. 'name'

  37097.      The name of the varobj.

  37098. 

  37099. 'value'

  37100.      If values were requested for this update, then this field will be

  37101.      present and will hold the value of the varobj.

  37102. 

  37103. 'in_scope'

  37104.      This field is a string which may take one of three values:

  37105. 

  37106.      '"true"'

  37107.           The variable object's current value is valid.

  37108. 

  37109.      '"false"'

  37110.           The variable object does not currently hold a valid value but

  37111.           it may hold one in the future if its associated expression

  37112.           comes back into scope.

  37113. 

  37114.      '"invalid"'

  37115.           The variable object no longer holds a valid value.  This can

  37116.           occur when the executable file being debugged has changed,

  37117.           either through recompilation or by using the GDB 'file'

  37118.           command.  The front end should normally choose to delete these

  37119.           variable objects.

  37120. 

  37121.      In the future new values may be added to this list so the front

  37122.      should be prepared for this possibility.  *Note GDB/MI Development

  37123.      and Front Ends: GDB/MI Development and Front Ends.

  37124. 

  37125. 'type_changed'

  37126.      This is only present if the varobj is still valid.  If the type

  37127.      changed, then this will be the string 'true'; otherwise it will be

  37128.      'false'.

  37129. 

  37130.      When a varobj's type changes, its children are also likely to have

  37131.      become incorrect.  Therefore, the varobj's children are

  37132.      automatically deleted when this attribute is 'true'.  Also, the

  37133.      varobj's update range, when set using the '-var-set-update-range'

  37134.      command, is unset.

  37135. 

  37136. 'new_type'

  37137.      If the varobj's type changed, then this field will be present and

  37138.      will hold the new type.

  37139. 

  37140. 'new_num_children'

  37141.      For a dynamic varobj, if the number of children changed, or if the

  37142.      type changed, this will be the new number of children.

  37143. 

  37144.      The 'numchild' field in other varobj responses is generally not

  37145.      valid for a dynamic varobj - it will show the number of children

  37146.      that GDB knows about, but because dynamic varobjs lazily

  37147.      instantiate their children, this will not reflect the number of

  37148.      children which may be available.

  37149. 

  37150.      The 'new_num_children' attribute only reports changes to the number

  37151.      of children known by GDB.  This is the only way to detect whether

  37152.      an update has removed children (which necessarily can only happen

  37153.      at the end of the update range).

  37154. 

  37155. 'displayhint'

  37156.      The display hint, if any.

  37157. 

  37158. 'has_more'

  37159.      This is an integer value, which will be 1 if there are more

  37160.      children available outside the varobj's update range.

  37161. 

  37162. 'dynamic'

  37163.      This attribute will be present and have the value '1' if the varobj

  37164.      is a dynamic varobj.  If the varobj is not a dynamic varobj, then

  37165.      this attribute will not be present.

  37166. 

  37167. 'new_children'

  37168.      If new children were added to a dynamic varobj within the selected

  37169.      update range (as set by '-var-set-update-range'), then they will be

  37170.      listed in this attribute.

  37171. 

  37172. Example

  37173. .......

  37174. 

  37175.      (gdb)

  37176.      -var-assign var1 3

  37177.      ^done,value="3"

  37178.      (gdb)

  37179.      -var-update --all-values var1

  37180.      ^done,changelist=[{name="var1",value="3",in_scope="true",

  37181.      type_changed="false"}]

  37182.      (gdb)

  37183. 

  37184. The '-var-set-frozen' Command

  37185. -----------------------------

  37186. 

  37187. Synopsis

  37188. ........

  37189. 

  37190.       -var-set-frozen NAME FLAG

  37191. 

  37192.    Set the frozenness flag on the variable object NAME.  The FLAG

  37193. parameter should be either '1' to make the variable frozen or '0' to

  37194. make it unfrozen.  If a variable object is frozen, then neither itself,

  37195. nor any of its children, are implicitly updated by '-var-update' of a

  37196. parent variable or by '-var-update *'.  Only '-var-update' of the

  37197. variable itself will update its value and values of its children.  After

  37198. a variable object is unfrozen, it is implicitly updated by all

  37199. subsequent '-var-update' operations.  Unfreezing a variable does not

  37200. update it, only subsequent '-var-update' does.

  37201. 

  37202. Example

  37203. .......

  37204. 

  37205.      (gdb)

  37206.      -var-set-frozen V 1

  37207.      ^done

  37208.      (gdb)

  37209. 

  37210. The '-var-set-update-range' command

  37211. -----------------------------------

  37212. 

  37213. Synopsis

  37214. ........

  37215. 

  37216.       -var-set-update-range NAME FROM TO

  37217. 

  37218.    Set the range of children to be returned by future invocations of

  37219. '-var-update'.

  37220. 

  37221.    FROM and TO indicate the range of children to report.  If FROM or TO

  37222. is less than zero, the range is reset and all children will be reported.

  37223. Otherwise, children starting at FROM (zero-based) and up to and

  37224. excluding TO will be reported.

  37225. 

  37226. Example

  37227. .......

  37228. 

  37229.      (gdb)

  37230.      -var-set-update-range V 1 2

  37231.      ^done

  37232. 

  37233. The '-var-set-visualizer' command

  37234. ---------------------------------

  37235. 

  37236. Synopsis

  37237. ........

  37238. 

  37239.       -var-set-visualizer NAME VISUALIZER

  37240. 

  37241.    Set a visualizer for the variable object NAME.

  37242. 

  37243.    VISUALIZER is the visualizer to use.  The special value 'None' means

  37244. to disable any visualizer in use.

  37245. 

  37246.    If not 'None', VISUALIZER must be a Python expression.  This

  37247. expression must evaluate to a callable object which accepts a single

  37248. argument.  GDB will call this object with the value of the varobj NAME

  37249. as an argument (this is done so that the same Python pretty-printing

  37250. code can be used for both the CLI and MI). When called, this object must

  37251. return an object which conforms to the pretty-printing interface (*note

  37252. Pretty Printing API::).

  37253. 

  37254.    The pre-defined function 'gdb.default_visualizer' may be used to

  37255. select a visualizer by following the built-in process (*note Selecting

  37256. Pretty-Printers::).  This is done automatically when a varobj is

  37257. created, and so ordinarily is not needed.

  37258. 

  37259.    This feature is only available if Python support is enabled.  The MI

  37260. command '-list-features' (*note GDB/MI Support Commands::) can be used

  37261. to check this.

  37262. 

  37263. Example

  37264. .......

  37265. 

  37266. Resetting the visualizer:

  37267. 

  37268.      (gdb)

  37269.      -var-set-visualizer V None

  37270.      ^done

  37271. 

  37272.    Reselecting the default (type-based) visualizer:

  37273. 

  37274.      (gdb)

  37275.      -var-set-visualizer V gdb.default_visualizer

  37276.      ^done

  37277. 

  37278.    Suppose 'SomeClass' is a visualizer class.  A lambda expression can

  37279. be used to instantiate this class for a varobj:

  37280. 

  37281.      (gdb)

  37282.      -var-set-visualizer V "lambda val: SomeClass()"

  37283.      ^done

  37284. 

  37285. 

  37286. File: gdb.info,  Node: GDB/MI Data Manipulation,  Next: GDB/MI Tracepoint Commands,  Prev: GDB/MI Variable Objects,  Up: GDB/MI

  37287. 

  37288. 27.16 GDB/MI Data Manipulation

  37289. ==============================

  37290. 

  37291. This section describes the GDB/MI commands that manipulate data: examine

  37292. memory and registers, evaluate expressions, etc.

  37293. 

  37294.    For details about what an addressable memory unit is, *note

  37295. addressable memory unit::.

  37296. 

  37297. The '-data-disassemble' Command

  37298. -------------------------------

  37299. 

  37300. Synopsis

  37301. ........

  37302. 

  37303.       -data-disassemble

  37304.          [ -s START-ADDR -e END-ADDR ]

  37305.        | [ -a ADDR ]

  37306.        | [ -f FILENAME -l LINENUM [ -n LINES ] ]

  37307.        -- MODE

  37308. 

  37309. Where:

  37310. 

  37311. 'START-ADDR'

  37312.      is the beginning address (or '$pc')

  37313. 'END-ADDR'

  37314.      is the end address

  37315. 'ADDR'

  37316.      is an address anywhere within (or the name of) the function to

  37317.      disassemble.  If an address is specified, the whole function

  37318.      surrounding that address will be disassembled.  If a name is

  37319.      specified, the whole function with that name will be disassembled.

  37320. 'FILENAME'

  37321.      is the name of the file to disassemble

  37322. 'LINENUM'

  37323.      is the line number to disassemble around

  37324. 'LINES'

  37325.      is the number of disassembly lines to be produced.  If it is -1,

  37326.      the whole function will be disassembled, in case no END-ADDR is

  37327.      specified.  If END-ADDR is specified as a non-zero value, and LINES

  37328.      is lower than the number of disassembly lines between START-ADDR

  37329.      and END-ADDR, only LINES lines are displayed; if LINES is higher

  37330.      than the number of lines between START-ADDR and END-ADDR, only the

  37331.      lines up to END-ADDR are displayed.

  37332. 'MODE'

  37333.      is one of:

  37334.         * 0 disassembly only

  37335.         * 1 mixed source and disassembly (deprecated)

  37336.         * 2 disassembly with raw opcodes

  37337.         * 3 mixed source and disassembly with raw opcodes (deprecated)

  37338.         * 4 mixed source and disassembly

  37339.         * 5 mixed source and disassembly with raw opcodes

  37340. 

  37341.      Modes 1 and 3 are deprecated.  The output is "source centric" which

  37342.      hasn't proved useful in practice.  *Note Machine Code::, for a

  37343.      discussion of the difference between '/m' and '/s' output of the

  37344.      'disassemble' command.

  37345. 

  37346. Result

  37347. ......

  37348. 

  37349. The result of the '-data-disassemble' command will be a list named

  37350. 'asm_insns', the contents of this list depend on the MODE used with the

  37351. '-data-disassemble' command.

  37352. 

  37353.    For modes 0 and 2 the 'asm_insns' list contains tuples with the

  37354. following fields:

  37355. 

  37356. 'address'

  37357.      The address at which this instruction was disassembled.

  37358. 

  37359. 'func-name'

  37360.      The name of the function this instruction is within.

  37361. 

  37362. 'offset'

  37363.      The decimal offset in bytes from the start of 'func-name'.

  37364. 

  37365. 'inst'

  37366.      The text disassembly for this 'address'.

  37367. 

  37368. 'opcodes'

  37369.      This field is only present for modes 2, 3 and 5.  This contains the

  37370.      raw opcode bytes for the 'inst' field.

  37371. 

  37372.    For modes 1, 3, 4 and 5 the 'asm_insns' list contains tuples named

  37373. 'src_and_asm_line', each of which has the following fields:

  37374. 

  37375. 'line'

  37376.      The line number within 'file'.

  37377. 

  37378. 'file'

  37379.      The file name from the compilation unit.  This might be an absolute

  37380.      file name or a relative file name depending on the compile command

  37381.      used.

  37382. 

  37383. 'fullname'

  37384.      Absolute file name of 'file'.  It is converted to a canonical form

  37385.      using the source file search path (*note Specifying Source

  37386.      Directories: Source Path.) and after resolving all the symbolic

  37387.      links.

  37388. 

  37389.      If the source file is not found this field will contain the path as

  37390.      present in the debug information.

  37391. 

  37392. 'line_asm_insn'

  37393.      This is a list of tuples containing the disassembly for 'line' in

  37394.      'file'.  The fields of each tuple are the same as for

  37395.      '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name',

  37396.      'offset', 'inst', and optionally 'opcodes'.

  37397. 

  37398.    Note that whatever included in the 'inst' field, is not manipulated

  37399. directly by GDB/MI, i.e., it is not possible to adjust its format.

  37400. 

  37401. GDB Command

  37402. ...........

  37403. 

  37404. The corresponding GDB command is 'disassemble'.

  37405. 

  37406. Example

  37407. .......

  37408. 

  37409. Disassemble from the current value of '$pc' to '$pc + 20':

  37410. 

  37411.      (gdb)

  37412.      -data-disassemble -s $pc -e "$pc + 20" -- 0

  37413.      ^done,

  37414.      asm_insns=[

  37415.      {address="0x000107c0",func-name="main",offset="4",

  37416.      inst="mov  2, %o0"},

  37417.      {address="0x000107c4",func-name="main",offset="8",

  37418.      inst="sethi  %hi(0x11800), %o2"},

  37419.      {address="0x000107c8",func-name="main",offset="12",

  37420.      inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},

  37421.      {address="0x000107cc",func-name="main",offset="16",

  37422.      inst="sethi  %hi(0x11800), %o2"},

  37423.      {address="0x000107d0",func-name="main",offset="20",

  37424.      inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]

  37425.      (gdb)

  37426. 

  37427.    Disassemble the whole 'main' function.  Line 32 is part of 'main'.

  37428. 

  37429.      -data-disassemble -f basics.c -l 32 -- 0

  37430.      ^done,asm_insns=[

  37431.      {address="0x000107bc",func-name="main",offset="0",

  37432.      inst="save  %sp, -112, %sp"},

  37433.      {address="0x000107c0",func-name="main",offset="4",

  37434.      inst="mov   2, %o0"},

  37435.      {address="0x000107c4",func-name="main",offset="8",

  37436.      inst="sethi %hi(0x11800), %o2"},

  37437.      [...]

  37438.      {address="0x0001081c",func-name="main",offset="96",inst="ret "},

  37439.      {address="0x00010820",func-name="main",offset="100",inst="restore "}]

  37440.      (gdb)

  37441. 

  37442.    Disassemble 3 instructions from the start of 'main':

  37443. 

  37444.      (gdb)

  37445.      -data-disassemble -f basics.c -l 32 -n 3 -- 0

  37446.      ^done,asm_insns=[

  37447.      {address="0x000107bc",func-name="main",offset="0",

  37448.      inst="save  %sp, -112, %sp"},

  37449.      {address="0x000107c0",func-name="main",offset="4",

  37450.      inst="mov  2, %o0"},

  37451.      {address="0x000107c4",func-name="main",offset="8",

  37452.      inst="sethi  %hi(0x11800), %o2"}]

  37453.      (gdb)

  37454. 

  37455.    Disassemble 3 instructions from the start of 'main' in mixed mode:

  37456. 

  37457.      (gdb)

  37458.      -data-disassemble -f basics.c -l 32 -n 3 -- 1

  37459.      ^done,asm_insns=[

  37460.      src_and_asm_line={line="31",

  37461.      file="../../../src/gdb/testsuite/gdb.mi/basics.c",

  37462.      fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",

  37463.      line_asm_insn=[{address="0x000107bc",

  37464.      func-name="main",offset="0",inst="save  %sp, -112, %sp"}]},

  37465.      src_and_asm_line={line="32",

  37466.      file="../../../src/gdb/testsuite/gdb.mi/basics.c",

  37467.      fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",

  37468.      line_asm_insn=[{address="0x000107c0",

  37469.      func-name="main",offset="4",inst="mov  2, %o0"},

  37470.      {address="0x000107c4",func-name="main",offset="8",

  37471.      inst="sethi  %hi(0x11800), %o2"}]}]

  37472.      (gdb)

  37473. 

  37474. The '-data-evaluate-expression' Command

  37475. ---------------------------------------

  37476. 

  37477. Synopsis

  37478. ........

  37479. 

  37480.       -data-evaluate-expression EXPR

  37481. 

  37482.    Evaluate EXPR as an expression.  The expression could contain an

  37483. inferior function call.  The function call will execute synchronously.

  37484. If the expression contains spaces, it must be enclosed in double quotes.

  37485. 

  37486. GDB Command

  37487. ...........

  37488. 

  37489. The corresponding GDB commands are 'print', 'output', and 'call'.  In

  37490. 'gdbtk' only, there's a corresponding 'gdb_eval' command.

  37491. 

  37492. Example

  37493. .......

  37494. 

  37495. In the following example, the numbers that precede the commands are the

  37496. "tokens" described in *note GDB/MI Command Syntax: GDB/MI Command

  37497. Syntax.  Notice how GDB/MI returns the same tokens in its output.

  37498. 

  37499.      211-data-evaluate-expression A

  37500.      211^done,value="1"

  37501.      (gdb)

  37502.      311-data-evaluate-expression &A

  37503.      311^done,value="0xefffeb7c"

  37504.      (gdb)

  37505.      411-data-evaluate-expression A+3

  37506.      411^done,value="4"

  37507.      (gdb)

  37508.      511-data-evaluate-expression "A + 3"

  37509.      511^done,value="4"

  37510.      (gdb)

  37511. 

  37512. The '-data-list-changed-registers' Command

  37513. ------------------------------------------

  37514. 

  37515. Synopsis

  37516. ........

  37517. 

  37518.       -data-list-changed-registers

  37519. 

  37520.    Display a list of the registers that have changed.

  37521. 

  37522. GDB Command

  37523. ...........

  37524. 

  37525. GDB doesn't have a direct analog for this command; 'gdbtk' has the

  37526. corresponding command 'gdb_changed_register_list'.

  37527. 

  37528. Example

  37529. .......

  37530. 

  37531. On a PPC MBX board:

  37532. 

  37533.      (gdb)

  37534.      -exec-continue

  37535.      ^running

  37536. 

  37537.      (gdb)

  37538.      *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={

  37539.      func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",

  37540.      line="5",arch="powerpc"}

  37541.      (gdb)

  37542.      -data-list-changed-registers

  37543.      ^done,changed-registers=["0","1","2","4","5","6","7","8","9",

  37544.      "10","11","13","14","15","16","17","18","19","20","21","22","23",

  37545.      "24","25","26","27","28","30","31","64","65","66","67","69"]

  37546.      (gdb)

  37547. 

  37548. The '-data-list-register-names' Command

  37549. ---------------------------------------

  37550. 

  37551. Synopsis

  37552. ........

  37553. 

  37554.       -data-list-register-names [ ( REGNO )+ ]

  37555. 

  37556.    Show a list of register names for the current target.  If no

  37557. arguments are given, it shows a list of the names of all the registers.

  37558. If integer numbers are given as arguments, it will print a list of the

  37559. names of the registers corresponding to the arguments.  To ensure

  37560. consistency between a register name and its number, the output list may

  37561. include empty register names.

  37562. 

  37563. GDB Command

  37564. ...........

  37565. 

  37566. GDB does not have a command which corresponds to

  37567. '-data-list-register-names'.  In 'gdbtk' there is a corresponding

  37568. command 'gdb_regnames'.

  37569. 

  37570. Example

  37571. .......

  37572. 

  37573. For the PPC MBX board:

  37574.      (gdb)

  37575.      -data-list-register-names

  37576.      ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",

  37577.      "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",

  37578.      "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",

  37579.      "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",

  37580.      "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",

  37581.      "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",

  37582.      "", "pc","ps","cr","lr","ctr","xer"]

  37583.      (gdb)

  37584.      -data-list-register-names 1 2 3

  37585.      ^done,register-names=["r1","r2","r3"]

  37586.      (gdb)

  37587. 

  37588. The '-data-list-register-values' Command

  37589. ----------------------------------------

  37590. 

  37591. Synopsis

  37592. ........

  37593. 

  37594.       -data-list-register-values

  37595.          [ --skip-unavailable ] FMT [ ( REGNO )*]

  37596. 

  37597.    Display the registers' contents.  The format according to which the

  37598. registers' contents are to be returned is given by FMT, followed by an

  37599. optional list of numbers specifying the registers to display.  A missing

  37600. list of numbers indicates that the contents of all the registers must be

  37601. returned.  The '--skip-unavailable' option indicates that only the

  37602. available registers are to be returned.

  37603. 

  37604.    Allowed formats for FMT are:

  37605. 

  37606. 'x'

  37607.      Hexadecimal

  37608. 'o'

  37609.      Octal

  37610. 't'

  37611.      Binary

  37612. 'd'

  37613.      Decimal

  37614. 'r'

  37615.      Raw

  37616. 'N'

  37617.      Natural

  37618. 

  37619. GDB Command

  37620. ...........

  37621. 

  37622. The corresponding GDB commands are 'info reg', 'info all-reg', and (in

  37623. 'gdbtk') 'gdb_fetch_registers'.

  37624. 

  37625. Example

  37626. .......

  37627. 

  37628. For a PPC MBX board (note: line breaks are for readability only, they

  37629. don't appear in the actual output):

  37630. 

  37631.      (gdb)

  37632.      -data-list-register-values r 64 65

  37633.      ^done,register-values=[{number="64",value="0xfe00a300"},

  37634.      {number="65",value="0x00029002"}]

  37635.      (gdb)

  37636.      -data-list-register-values x

  37637.      ^done,register-values=[{number="0",value="0xfe0043c8"},

  37638.      {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},

  37639.      {number="3",value="0x0"},{number="4",value="0xa"},

  37640.      {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},

  37641.      {number="7",value="0xfe011e98"},{number="8",value="0x2"},

  37642.      {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},

  37643.      {number="11",value="0x1"},{number="12",value="0x0"},

  37644.      {number="13",value="0x4544"},{number="14",value="0xffdfffff"},

  37645.      {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},

  37646.      {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},

  37647.      {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},

  37648.      {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},

  37649.      {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},

  37650.      {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},

  37651.      {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},

  37652.      {number="29",value="0x0"},{number="30",value="0xfe010000"},

  37653.      {number="31",value="0x0"},{number="32",value="0x0"},

  37654.      {number="33",value="0x0"},{number="34",value="0x0"},

  37655.      {number="35",value="0x0"},{number="36",value="0x0"},

  37656.      {number="37",value="0x0"},{number="38",value="0x0"},

  37657.      {number="39",value="0x0"},{number="40",value="0x0"},

  37658.      {number="41",value="0x0"},{number="42",value="0x0"},

  37659.      {number="43",value="0x0"},{number="44",value="0x0"},

  37660.      {number="45",value="0x0"},{number="46",value="0x0"},

  37661.      {number="47",value="0x0"},{number="48",value="0x0"},

  37662.      {number="49",value="0x0"},{number="50",value="0x0"},

  37663.      {number="51",value="0x0"},{number="52",value="0x0"},

  37664.      {number="53",value="0x0"},{number="54",value="0x0"},

  37665.      {number="55",value="0x0"},{number="56",value="0x0"},

  37666.      {number="57",value="0x0"},{number="58",value="0x0"},

  37667.      {number="59",value="0x0"},{number="60",value="0x0"},

  37668.      {number="61",value="0x0"},{number="62",value="0x0"},

  37669.      {number="63",value="0x0"},{number="64",value="0xfe00a300"},

  37670.      {number="65",value="0x29002"},{number="66",value="0x202f04b5"},

  37671.      {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},

  37672.      {number="69",value="0x20002b03"}]

  37673.      (gdb)

  37674. 

  37675. The '-data-read-memory' Command

  37676. -------------------------------

  37677. 

  37678. This command is deprecated, use '-data-read-memory-bytes' instead.

  37679. 

  37680. Synopsis

  37681. ........

  37682. 

  37683.       -data-read-memory [ -o BYTE-OFFSET ]

  37684.         ADDRESS WORD-FORMAT WORD-SIZE

  37685.         NR-ROWS NR-COLS [ ASCHAR ]

  37686. 

  37687. where:

  37688. 

  37689. 'ADDRESS'

  37690.      An expression specifying the address of the first memory word to be

  37691.      read.  Complex expressions containing embedded white space should

  37692.      be quoted using the C convention.

  37693. 

  37694. 'WORD-FORMAT'

  37695.      The format to be used to print the memory words.  The notation is

  37696.      the same as for GDB's 'print' command (*note Output Formats: Output

  37697.      Formats.).

  37698. 

  37699. 'WORD-SIZE'

  37700.      The size of each memory word in bytes.

  37701. 

  37702. 'NR-ROWS'

  37703.      The number of rows in the output table.

  37704. 

  37705. 'NR-COLS'

  37706.      The number of columns in the output table.

  37707. 

  37708. 'ASCHAR'

  37709.      If present, indicates that each row should include an ASCII dump.

  37710.      The value of ASCHAR is used as a padding character when a byte is

  37711.      not a member of the printable ASCII character set (printable ASCII

  37712.      characters are those whose code is between 32 and 126,

  37713.      inclusively).

  37714. 

  37715. 'BYTE-OFFSET'

  37716.      An offset to add to the ADDRESS before fetching memory.

  37717. 

  37718.    This command displays memory contents as a table of NR-ROWS by

  37719. NR-COLS words, each word being WORD-SIZE bytes.  In total, 'NR-ROWS *

  37720. NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes').  Should

  37721. less than the requested number of bytes be returned by the target, the

  37722. missing words are identified using 'N/A'.  The number of bytes read from

  37723. the target is returned in 'nr-bytes' and the starting address used to

  37724. read memory in 'addr'.

  37725. 

  37726.    The address of the next/previous row or page is available in

  37727. 'next-row' and 'prev-row', 'next-page' and 'prev-page'.

  37728. 

  37729. GDB Command

  37730. ...........

  37731. 

  37732. The corresponding GDB command is 'x'.  'gdbtk' has 'gdb_get_mem' memory

  37733. read command.

  37734. 

  37735. Example

  37736. .......

  37737. 

  37738. Read six bytes of memory starting at 'bytes+6' but then offset by '-6'

  37739. bytes.  Format as three rows of two columns.  One byte per word.

  37740. Display each word in hex.

  37741. 

  37742.      (gdb)

  37743.      9-data-read-memory -o -6 -- bytes+6 x 1 3 2

  37744.      9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",

  37745.      next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",

  37746.      prev-page="0x0000138a",memory=[

  37747.      {addr="0x00001390",data=["0x00","0x01"]},

  37748.      {addr="0x00001392",data=["0x02","0x03"]},

  37749.      {addr="0x00001394",data=["0x04","0x05"]}]

  37750.      (gdb)

  37751. 

  37752.    Read two bytes of memory starting at address 'shorts + 64' and

  37753. display as a single word formatted in decimal.

  37754. 

  37755.      (gdb)

  37756.      5-data-read-memory shorts+64 d 2 1 1

  37757.      5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",

  37758.      next-row="0x00001512",prev-row="0x0000150e",

  37759.      next-page="0x00001512",prev-page="0x0000150e",memory=[

  37760.      {addr="0x00001510",data=["128"]}]

  37761.      (gdb)

  37762. 

  37763.    Read thirty two bytes of memory starting at 'bytes+16' and format as

  37764. eight rows of four columns.  Include a string encoding with 'x' used as

  37765. the non-printable character.

  37766. 

  37767.      (gdb)

  37768.      4-data-read-memory bytes+16 x 1 8 4 x

  37769.      4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",

  37770.      next-row="0x000013c0",prev-row="0x0000139c",

  37771.      next-page="0x000013c0",prev-page="0x00001380",memory=[

  37772.      {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},

  37773.      {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},

  37774.      {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},

  37775.      {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},

  37776.      {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},

  37777.      {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},

  37778.      {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},

  37779.      {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]

  37780.      (gdb)

  37781. 

  37782. The '-data-read-memory-bytes' Command

  37783. -------------------------------------

  37784. 

  37785. Synopsis

  37786. ........

  37787. 

  37788.       -data-read-memory-bytes [ -o OFFSET ]

  37789.         ADDRESS COUNT

  37790. 

  37791. where:

  37792. 

  37793. 'ADDRESS'

  37794.      An expression specifying the address of the first addressable

  37795.      memory unit to be read.  Complex expressions containing embedded

  37796.      white space should be quoted using the C convention.

  37797. 

  37798. 'COUNT'

  37799.      The number of addressable memory units to read.  This should be an

  37800.      integer literal.

  37801. 

  37802. 'OFFSET'

  37803.      The offset relative to ADDRESS at which to start reading.  This

  37804.      should be an integer literal.  This option is provided so that a

  37805.      frontend is not required to first evaluate address and then perform

  37806.      address arithmetics itself.

  37807. 

  37808.    This command attempts to read all accessible memory regions in the

  37809. specified range.  First, all regions marked as unreadable in the memory

  37810. map (if one is defined) will be skipped.  *Note Memory Region

  37811. Attributes::.  Second, GDB will attempt to read the remaining regions.

  37812. For each one, if reading full region results in an errors, GDB will try

  37813. to read a subset of the region.

  37814. 

  37815.    In general, every single memory unit in the region may be readable or

  37816. not, and the only way to read every readable unit is to try a read at

  37817. every address, which is not practical.  Therefore, GDB will attempt to

  37818. read all accessible memory units at either beginning or the end of the

  37819. region, using a binary division scheme.  This heuristic works well for

  37820. reading across a memory map boundary.  Note that if a region has a

  37821. readable range that is neither at the beginning or the end, GDB will not

  37822. read it.

  37823. 

  37824.    The result record (*note GDB/MI Result Records::) that is output of

  37825. the command includes a field named 'memory' whose content is a list of

  37826. tuples.  Each tuple represent a successfully read memory block and has

  37827. the following fields:

  37828. 

  37829. 'begin'

  37830.      The start address of the memory block, as hexadecimal literal.

  37831. 

  37832. 'end'

  37833.      The end address of the memory block, as hexadecimal literal.

  37834. 

  37835. 'offset'

  37836.      The offset of the memory block, as hexadecimal literal, relative to

  37837.      the start address passed to '-data-read-memory-bytes'.

  37838. 

  37839. 'contents'

  37840.      The contents of the memory block, in hex.

  37841. 

  37842. GDB Command

  37843. ...........

  37844. 

  37845. The corresponding GDB command is 'x'.

  37846. 

  37847. Example

  37848. .......

  37849. 

  37850.      (gdb)

  37851.      -data-read-memory-bytes &a 10

  37852.      ^done,memory=[{begin="0xbffff154",offset="0x00000000",

  37853.                    end="0xbffff15e",

  37854.                    contents="01000000020000000300"}]

  37855.      (gdb)

  37856. 

  37857. The '-data-write-memory-bytes' Command

  37858. --------------------------------------

  37859. 

  37860. Synopsis

  37861. ........

  37862. 

  37863.       -data-write-memory-bytes ADDRESS CONTENTS

  37864.       -data-write-memory-bytes ADDRESS CONTENTS [COUNT]

  37865. 

  37866. where:

  37867. 

  37868. 'ADDRESS'

  37869.      An expression specifying the address of the first addressable

  37870.      memory unit to be written.  Complex expressions containing embedded

  37871.      white space should be quoted using the C convention.

  37872. 

  37873. 'CONTENTS'

  37874.      The hex-encoded data to write.  It is an error if CONTENTS does not

  37875.      represent an integral number of addressable memory units.

  37876. 

  37877. 'COUNT'

  37878.      Optional argument indicating the number of addressable memory units

  37879.      to be written.  If COUNT is greater than CONTENTS' length, GDB will

  37880.      repeatedly write CONTENTS until it fills COUNT memory units.

  37881. 

  37882. GDB Command

  37883. ...........

  37884. 

  37885. There's no corresponding GDB command.

  37886. 

  37887. Example

  37888. .......

  37889. 

  37890.      (gdb)

  37891.      -data-write-memory-bytes &a "aabbccdd"

  37892.      ^done

  37893.      (gdb)

  37894. 

  37895.      (gdb)

  37896.      -data-write-memory-bytes &a "aabbccdd" 16e

  37897.      ^done

  37898.      (gdb)

  37899. 

  37900. 

  37901. File: gdb.info,  Node: GDB/MI Tracepoint Commands,  Next: GDB/MI Symbol Query,  Prev: GDB/MI Data Manipulation,  Up: GDB/MI

  37902. 

  37903. 27.17 GDB/MI Tracepoint Commands

  37904. ================================

  37905. 

  37906. The commands defined in this section implement MI support for

  37907. tracepoints.  For detailed introduction, see *note Tracepoints::.

  37908. 

  37909. The '-trace-find' Command

  37910. -------------------------

  37911. 

  37912. Synopsis

  37913. ........

  37914. 

  37915.       -trace-find MODE [PARAMETERS...]

  37916. 

  37917.    Find a trace frame using criteria defined by MODE and PARAMETERS.

  37918. The following table lists permissible modes and their parameters.  For

  37919. details of operation, see *note tfind::.

  37920. 

  37921. 'none'

  37922.      No parameters are required.  Stops examining trace frames.

  37923. 

  37924. 'frame-number'

  37925.      An integer is required as parameter.  Selects tracepoint frame with

  37926.      that index.

  37927. 

  37928. 'tracepoint-number'

  37929.      An integer is required as parameter.  Finds next trace frame that

  37930.      corresponds to tracepoint with the specified number.

  37931. 

  37932. 'pc'

  37933.      An address is required as parameter.  Finds next trace frame that

  37934.      corresponds to any tracepoint at the specified address.

  37935. 

  37936. 'pc-inside-range'

  37937.      Two addresses are required as parameters.  Finds next trace frame

  37938.      that corresponds to a tracepoint at an address inside the specified

  37939.      range.  Both bounds are considered to be inside the range.

  37940. 

  37941. 'pc-outside-range'

  37942.      Two addresses are required as parameters.  Finds next trace frame

  37943.      that corresponds to a tracepoint at an address outside the

  37944.      specified range.  Both bounds are considered to be inside the

  37945.      range.

  37946. 

  37947. 'line'

  37948.      Line specification is required as parameter.  *Note Specify

  37949.      Location::.  Finds next trace frame that corresponds to a

  37950.      tracepoint at the specified location.

  37951. 

  37952.    If 'none' was passed as MODE, the response does not have fields.

  37953. Otherwise, the response may have the following fields:

  37954. 

  37955. 'found'

  37956.      This field has either '0' or '1' as the value, depending on whether

  37957.      a matching tracepoint was found.

  37958. 

  37959. 'traceframe'

  37960.      The index of the found traceframe.  This field is present iff the

  37961.      'found' field has value of '1'.

  37962. 

  37963. 'tracepoint'

  37964.      The index of the found tracepoint.  This field is present iff the

  37965.      'found' field has value of '1'.

  37966. 

  37967. 'frame'

  37968.      The information about the frame corresponding to the found trace

  37969.      frame.  This field is present only if a trace frame was found.

  37970.      *Note GDB/MI Frame Information::, for description of this field.

  37971. 

  37972. GDB Command

  37973. ...........

  37974. 

  37975. The corresponding GDB command is 'tfind'.

  37976. 

  37977. -trace-define-variable

  37978. ----------------------

  37979. 

  37980. Synopsis

  37981. ........

  37982. 

  37983.       -trace-define-variable NAME [ VALUE ]

  37984. 

  37985.    Create trace variable NAME if it does not exist.  If VALUE is

  37986. specified, sets the initial value of the specified trace variable to

  37987. that value.  Note that the NAME should start with the '$' character.

  37988. 

  37989. GDB Command

  37990. ...........

  37991. 

  37992. The corresponding GDB command is 'tvariable'.

  37993. 

  37994. The '-trace-frame-collected' Command

  37995. ------------------------------------

  37996. 

  37997. Synopsis

  37998. ........

  37999. 

  38000.       -trace-frame-collected

  38001.          [--var-print-values VAR_PVAL]

  38002.          [--comp-print-values COMP_PVAL]

  38003.          [--registers-format REGFORMAT]

  38004.          [--memory-contents]

  38005. 

  38006.    This command returns the set of collected objects, register names,

  38007. trace state variable names, memory ranges and computed expressions that

  38008. have been collected at a particular trace frame.  The optional

  38009. parameters to the command affect the output format in different ways.

  38010. See the output description table below for more details.

  38011. 

  38012.    The reported names can be used in the normal manner to create varobjs

  38013. and inspect the objects themselves.  The items returned by this command

  38014. are categorized so that it is clear which is a variable, which is a

  38015. register, which is a trace state variable, which is a memory range and

  38016. which is a computed expression.

  38017. 

  38018.    For instance, if the actions were

  38019.      collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2

  38020.      collect *(int*)0xaf02bef0@40

  38021. 

  38022. the object collected in its entirety would be 'myVar'.  The object

  38023. 'myArray' would be partially collected, because only the element at

  38024. index 'myIndex' would be collected.  The remaining objects would be

  38025. computed expressions.

  38026. 

  38027.    An example output would be:

  38028. 

  38029.      (gdb)

  38030.      -trace-frame-collected

  38031.      ^done,

  38032.        explicit-variables=[{name="myVar",value="1"}],

  38033.        computed-expressions=[{name="myArray[myIndex]",value="0"},

  38034.                              {name="myObj.field",value="0"},

  38035.                              {name="myPtr->field",value="1"},

  38036.                              {name="myCount + 2",value="3"},

  38037.                              {name="$tvar1 + 1",value="43970027"}],

  38038.        registers=[{number="0",value="0x7fe2c6e79ec8"},

  38039.                   {number="1",value="0x0"},

  38040.                   {number="2",value="0x4"},

  38041.                   ...

  38042.                   {number="125",value="0x0"}],

  38043.        tvars=[{name="$tvar1",current="43970026"}],

  38044.        memory=[{address="0x0000000000602264",length="4"},

  38045.                {address="0x0000000000615bc0",length="4"}]

  38046.      (gdb)

  38047. 

  38048.    Where:

  38049. 

  38050. 'explicit-variables'

  38051.      The set of objects that have been collected in their entirety (as

  38052.      opposed to collecting just a few elements of an array or a few

  38053.      struct members).  For each object, its name and value are printed.

  38054.      The '--var-print-values' option affects how or whether the value

  38055.      field is output.  If VAR_PVAL is 0, then print only the names; if

  38056.      it is 1, print also their values; and if it is 2, print the name,

  38057.      type and value for simple data types, and the name and type for

  38058.      arrays, structures and unions.

  38059. 

  38060. 'computed-expressions'

  38061.      The set of computed expressions that have been collected at the

  38062.      current trace frame.  The '--comp-print-values' option affects this

  38063.      set like the '--var-print-values' option affects the

  38064.      'explicit-variables' set.  See above.

  38065. 

  38066. 'registers'

  38067.      The registers that have been collected at the current trace frame.

  38068.      For each register collected, the name and current value are

  38069.      returned.  The value is formatted according to the

  38070.      '--registers-format' option.  See the '-data-list-register-values'

  38071.      command for a list of the allowed formats.  The default is 'x'.

  38072. 

  38073. 'tvars'

  38074.      The trace state variables that have been collected at the current

  38075.      trace frame.  For each trace state variable collected, the name and

  38076.      current value are returned.

  38077. 

  38078. 'memory'

  38079.      The set of memory ranges that have been collected at the current

  38080.      trace frame.  Its content is a list of tuples.  Each tuple

  38081.      represents a collected memory range and has the following fields:

  38082. 

  38083.      'address'

  38084.           The start address of the memory range, as hexadecimal literal.

  38085. 

  38086.      'length'

  38087.           The length of the memory range, as decimal literal.

  38088. 

  38089.      'contents'

  38090.           The contents of the memory block, in hex.  This field is only

  38091.           present if the '--memory-contents' option is specified.

  38092. 

  38093. GDB Command

  38094. ...........

  38095. 

  38096. There is no corresponding GDB command.

  38097. 

  38098. Example

  38099. .......

  38100. 

  38101. -trace-list-variables

  38102. ---------------------

  38103. 

  38104. Synopsis

  38105. ........

  38106. 

  38107.       -trace-list-variables

  38108. 

  38109.    Return a table of all defined trace variables.  Each element of the

  38110. table has the following fields:

  38111. 

  38112. 'name'

  38113.      The name of the trace variable.  This field is always present.

  38114. 

  38115. 'initial'

  38116.      The initial value.  This is a 64-bit signed integer.  This field is

  38117.      always present.

  38118. 

  38119. 'current'

  38120.      The value the trace variable has at the moment.  This is a 64-bit

  38121.      signed integer.  This field is absent iff current value is not

  38122.      defined, for example if the trace was never run, or is presently

  38123.      running.

  38124. 

  38125. GDB Command

  38126. ...........

  38127. 

  38128. The corresponding GDB command is 'tvariables'.

  38129. 

  38130. Example

  38131. .......

  38132. 

  38133.      (gdb)

  38134.      -trace-list-variables

  38135.      ^done,trace-variables={nr_rows="1",nr_cols="3",

  38136.      hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},

  38137.           {width="11",alignment="-1",col_name="initial",colhdr="Initial"},

  38138.           {width="11",alignment="-1",col_name="current",colhdr="Current"}],

  38139.      body=[variable={name="$trace_timestamp",initial="0"}

  38140.            variable={name="$foo",initial="10",current="15"}]}

  38141.      (gdb)

  38142. 

  38143. -trace-save

  38144. -----------

  38145. 

  38146. Synopsis

  38147. ........

  38148. 

  38149.       -trace-save [ -r ] [ -ctf ] FILENAME

  38150. 

  38151.    Saves the collected trace data to FILENAME.  Without the '-r' option,

  38152. the data is downloaded from the target and saved in a local file.  With

  38153. the '-r' option the target is asked to perform the save.

  38154. 

  38155.    By default, this command will save the trace in the tfile format.

  38156. You can supply the optional '-ctf' argument to save it the CTF format.

  38157. See *note Trace Files:: for more information about CTF.

  38158. 

  38159. GDB Command

  38160. ...........

  38161. 

  38162. The corresponding GDB command is 'tsave'.

  38163. 

  38164. -trace-start

  38165. ------------

  38166. 

  38167. Synopsis

  38168. ........

  38169. 

  38170.       -trace-start

  38171. 

  38172.    Starts a tracing experiment.  The result of this command does not

  38173. have any fields.

  38174. 

  38175. GDB Command

  38176. ...........

  38177. 

  38178. The corresponding GDB command is 'tstart'.

  38179. 

  38180. -trace-status

  38181. -------------

  38182. 

  38183. Synopsis

  38184. ........

  38185. 

  38186.       -trace-status

  38187. 

  38188.    Obtains the status of a tracing experiment.  The result may include

  38189. the following fields:

  38190. 

  38191. 'supported'

  38192.      May have a value of either '0', when no tracing operations are

  38193.      supported, '1', when all tracing operations are supported, or

  38194.      'file' when examining trace file.  In the latter case, examining of

  38195.      trace frame is possible but new tracing experiement cannot be

  38196.      started.  This field is always present.

  38197. 

  38198. 'running'

  38199.      May have a value of either '0' or '1' depending on whether tracing

  38200.      experiement is in progress on target.  This field is present if

  38201.      'supported' field is not '0'.

  38202. 

  38203. 'stop-reason'

  38204.      Report the reason why the tracing was stopped last time.  This

  38205.      field may be absent iff tracing was never stopped on target yet.

  38206.      The value of 'request' means the tracing was stopped as result of

  38207.      the '-trace-stop' command.  The value of 'overflow' means the

  38208.      tracing buffer is full.  The value of 'disconnection' means tracing

  38209.      was automatically stopped when GDB has disconnected.  The value of

  38210.      'passcount' means tracing was stopped when a tracepoint was passed

  38211.      a maximal number of times for that tracepoint.  This field is

  38212.      present if 'supported' field is not '0'.

  38213. 

  38214. 'stopping-tracepoint'

  38215.      The number of tracepoint whose passcount as exceeded.  This field

  38216.      is present iff the 'stop-reason' field has the value of

  38217.      'passcount'.

  38218. 

  38219. 'frames'

  38220. 'frames-created'

  38221.      The 'frames' field is a count of the total number of trace frames

  38222.      in the trace buffer, while 'frames-created' is the total created

  38223.      during the run, including ones that were discarded, such as when a

  38224.      circular trace buffer filled up.  Both fields are optional.

  38225. 

  38226. 'buffer-size'

  38227. 'buffer-free'

  38228.      These fields tell the current size of the tracing buffer and the

  38229.      remaining space.  These fields are optional.

  38230. 

  38231. 'circular'

  38232.      The value of the circular trace buffer flag.  '1' means that the

  38233.      trace buffer is circular and old trace frames will be discarded if

  38234.      necessary to make room, '0' means that the trace buffer is linear

  38235.      and may fill up.

  38236. 

  38237. 'disconnected'

  38238.      The value of the disconnected tracing flag.  '1' means that tracing

  38239.      will continue after GDB disconnects, '0' means that the trace run

  38240.      will stop.

  38241. 

  38242. 'trace-file'

  38243.      The filename of the trace file being examined.  This field is

  38244.      optional, and only present when examining a trace file.

  38245. 

  38246. GDB Command

  38247. ...........

  38248. 

  38249. The corresponding GDB command is 'tstatus'.

  38250. 

  38251. -trace-stop

  38252. -----------

  38253. 

  38254. Synopsis

  38255. ........

  38256. 

  38257.       -trace-stop

  38258. 

  38259.    Stops a tracing experiment.  The result of this command has the same

  38260. fields as '-trace-status', except that the 'supported' and 'running'

  38261. fields are not output.

  38262. 

  38263. GDB Command

  38264. ...........

  38265. 

  38266. The corresponding GDB command is 'tstop'.

  38267. 

  38268. 

  38269. File: gdb.info,  Node: GDB/MI Symbol Query,  Next: GDB/MI File Commands,  Prev: GDB/MI Tracepoint Commands,  Up: GDB/MI

  38270. 

  38271. 27.18 GDB/MI Symbol Query Commands

  38272. ==================================

  38273. 

  38274. The '-symbol-info-functions' Command

  38275. ------------------------------------

  38276. 

  38277. Synopsis

  38278. ........

  38279. 

  38280.       -symbol-info-functions [--include-nondebug]

  38281.                              [--type TYPE_REGEXP]

  38282.                              [--name NAME_REGEXP]

  38283.                              [--max-results LIMIT]

  38284. 

  38285. Return a list containing the names and types for all global functions

  38286. taken from the debug information.  The functions are grouped by source

  38287. file, and shown with the line number on which each function is defined.

  38288. 

  38289.    The '--include-nondebug' option causes the output to include code

  38290. symbols from the symbol table.

  38291. 

  38292.    The options '--type' and '--name' allow the symbols returned to be

  38293. filtered based on either the name of the function, or the type signature

  38294. of the function.

  38295. 

  38296.    The option '--max-results' restricts the command to return no more

  38297. than LIMIT results.  If exactly LIMIT results are returned then there

  38298. might be additional results available if a higher limit is used.

  38299. 

  38300. GDB Command

  38301. ...........

  38302. 

  38303. The corresponding GDB command is 'info functions'.

  38304. 

  38305. Example

  38306. .......

  38307. 

  38308.      (gdb)

  38309.      -symbol-info-functions

  38310.      ^done,symbols=

  38311.        {debug=

  38312.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38313.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38314.            symbols=[{line="36", name="f4", type="void (int *)",

  38315.                      description="void f4(int *);"},

  38316.                     {line="42", name="main", type="int ()",

  38317.                      description="int main();"},

  38318.                     {line="30", name="f1", type="my_int_t (int, int)",

  38319.                      description="static my_int_t f1(int, int);"}]},

  38320.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38321.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38322.            symbols=[{line="33", name="f2", type="float (another_float_t)",

  38323.                      description="float f2(another_float_t);"},

  38324.                     {line="39", name="f3", type="int (another_int_t)",

  38325.                      description="int f3(another_int_t);"},

  38326.                     {line="27", name="f1", type="another_float_t (int)",

  38327.                      description="static another_float_t f1(int);"}]}]}

  38328.      (gdb)

  38329.      -symbol-info-functions --name f1

  38330.      ^done,symbols=

  38331.        {debug=

  38332.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38333.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38334.            symbols=[{line="30", name="f1", type="my_int_t (int, int)",

  38335.                      description="static my_int_t f1(int, int);"}]},

  38336.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38337.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38338.            symbols=[{line="27", name="f1", type="another_float_t (int)",

  38339.                      description="static another_float_t f1(int);"}]}]}

  38340.      (gdb)

  38341.      -symbol-info-functions --type void

  38342.      ^done,symbols=

  38343.        {debug=

  38344.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38345.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38346.            symbols=[{line="36", name="f4", type="void (int *)",

  38347.                      description="void f4(int *);"}]}]}

  38348.      (gdb)

  38349.      -symbol-info-functions --include-nondebug

  38350.      ^done,symbols=

  38351.        {debug=

  38352.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38353.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38354.            symbols=[{line="36", name="f4", type="void (int *)",

  38355.                      description="void f4(int *);"},

  38356.                     {line="42", name="main", type="int ()",

  38357.                      description="int main();"},

  38358.                     {line="30", name="f1", type="my_int_t (int, int)",

  38359.                      description="static my_int_t f1(int, int);"}]},

  38360.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38361.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38362.            symbols=[{line="33", name="f2", type="float (another_float_t)",

  38363.                      description="float f2(another_float_t);"},

  38364.                     {line="39", name="f3", type="int (another_int_t)",

  38365.                      description="int f3(another_int_t);"},

  38366.                     {line="27", name="f1", type="another_float_t (int)",

  38367.                      description="static another_float_t f1(int);"}]}],

  38368.         nondebug=

  38369.          [{address="0x0000000000400398",name="_init"},

  38370.           {address="0x00000000004003b0",name="_start"},

  38371.            ...

  38372.          ]}

  38373. 

  38374. The '-symbol-info-module-functions' Command

  38375. -------------------------------------------

  38376. 

  38377. Synopsis

  38378. ........

  38379. 

  38380.       -symbol-info-module-functions [--module MODULE_REGEXP]

  38381.                                     [--name NAME_REGEXP]

  38382.                                     [--type TYPE_REGEXP]

  38383. 

  38384. Return a list containing the names of all known functions within all

  38385. know Fortran modules.  The functions are grouped by source file and

  38386. containing module, and shown with the line number on which each function

  38387. is defined.

  38388. 

  38389.    The option '--module' only returns results for modules matching

  38390. MODULE_REGEXP.  The option '--name' only returns functions whose name

  38391. matches NAME_REGEXP, and '--type' only returns functions whose type

  38392. matches TYPE_REGEXP.

  38393. 

  38394. GDB Command

  38395. ...........

  38396. 

  38397. The corresponding GDB command is 'info module functions'.

  38398. 

  38399. Example

  38400. .......

  38401. 

  38402.      (gdb)

  38403.      -symbol-info-module-functions

  38404.      ^done,symbols=

  38405.        [{module="mod1",

  38406.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38407.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38408.                  symbols=[{line="21",name="mod1::check_all",type="void (void)",

  38409.                            description="void mod1::check_all(void);"}]}]},

  38410.          {module="mod2",

  38411.           files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38412.                   fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38413.                   symbols=[{line="30",name="mod2::check_var_i",type="void (void)",

  38414.                             description="void mod2::check_var_i(void);"}]}]},

  38415.          {module="mod3",

  38416.           files=[{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38417.                   fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38418.                   symbols=[{line="21",name="mod3::check_all",type="void (void)",

  38419.                             description="void mod3::check_all(void);"},

  38420.                            {line="27",name="mod3::check_mod2",type="void (void)",

  38421.                             description="void mod3::check_mod2(void);"}]}]},

  38422.          {module="modmany",

  38423.           files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38424.                   fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38425.                   symbols=[{line="35",name="modmany::check_some",type="void (void)",

  38426.                             description="void modmany::check_some(void);"}]}]},

  38427.          {module="moduse",

  38428.           files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38429.                   fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38430.                   symbols=[{line="44",name="moduse::check_all",type="void (void)",

  38431.                             description="void moduse::check_all(void);"},

  38432.                            {line="49",name="moduse::check_var_x",type="void (void)",

  38433.                             description="void moduse::check_var_x(void);"}]}]}]

  38434. 

  38435. The '-symbol-info-module-variables' Command

  38436. -------------------------------------------

  38437. 

  38438. Synopsis

  38439. ........

  38440. 

  38441.       -symbol-info-module-variables [--module MODULE_REGEXP]

  38442.                                     [--name NAME_REGEXP]

  38443.                                     [--type TYPE_REGEXP]

  38444. 

  38445. Return a list containing the names of all known variables within all

  38446. know Fortran modules.  The variables are grouped by source file and

  38447. containing module, and shown with the line number on which each variable

  38448. is defined.

  38449. 

  38450.    The option '--module' only returns results for modules matching

  38451. MODULE_REGEXP.  The option '--name' only returns variables whose name

  38452. matches NAME_REGEXP, and '--type' only returns variables whose type

  38453. matches TYPE_REGEXP.

  38454. 

  38455. GDB Command

  38456. ...........

  38457. 

  38458. The corresponding GDB command is 'info module variables'.

  38459. 

  38460. Example

  38461. .......

  38462. 

  38463.      (gdb)

  38464.      -symbol-info-module-variables

  38465.      ^done,symbols=

  38466.        [{module="mod1",

  38467.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38468.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38469.                  symbols=[{line="18",name="mod1::var_const",type="integer(kind=4)",

  38470.                            description="integer(kind=4) mod1::var_const;"},

  38471.                           {line="17",name="mod1::var_i",type="integer(kind=4)",

  38472.                            description="integer(kind=4) mod1::var_i;"}]}]},

  38473.         {module="mod2",

  38474.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38475.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38476.                  symbols=[{line="28",name="mod2::var_i",type="integer(kind=4)",

  38477.                            description="integer(kind=4) mod2::var_i;"}]}]},

  38478.         {module="mod3",

  38479.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38480.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38481.                  symbols=[{line="18",name="mod3::mod1",type="integer(kind=4)",

  38482.                            description="integer(kind=4) mod3::mod1;"},

  38483.                           {line="17",name="mod3::mod2",type="integer(kind=4)",

  38484.                            description="integer(kind=4) mod3::mod2;"},

  38485.                           {line="19",name="mod3::var_i",type="integer(kind=4)",

  38486.                            description="integer(kind=4) mod3::var_i;"}]}]},

  38487.         {module="modmany",

  38488.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38489.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38490.                  symbols=[{line="33",name="modmany::var_a",type="integer(kind=4)",

  38491.                            description="integer(kind=4) modmany::var_a;"},

  38492.                           {line="33",name="modmany::var_b",type="integer(kind=4)",

  38493.                            description="integer(kind=4) modmany::var_b;"},

  38494.                           {line="33",name="modmany::var_c",type="integer(kind=4)",

  38495.                            description="integer(kind=4) modmany::var_c;"},

  38496.                           {line="33",name="modmany::var_i",type="integer(kind=4)",

  38497.                            description="integer(kind=4) modmany::var_i;"}]}]},

  38498.         {module="moduse",

  38499.          files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38500.                  fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38501.                  symbols=[{line="42",name="moduse::var_x",type="integer(kind=4)",

  38502.                            description="integer(kind=4) moduse::var_x;"},

  38503.                           {line="42",name="moduse::var_y",type="integer(kind=4)",

  38504.                            description="integer(kind=4) moduse::var_y;"}]}]}]

  38505. 

  38506. The '-symbol-info-modules' Command

  38507. ----------------------------------

  38508. 

  38509. Synopsis

  38510. ........

  38511. 

  38512.       -symbol-info-modules [--name NAME_REGEXP]

  38513.                            [--max-results LIMIT]

  38514. 

  38515. 

  38516. Return a list containing the names of all known Fortran modules.  The

  38517. modules are grouped by source file, and shown with the line number on

  38518. which each modules is defined.

  38519. 

  38520.    The option '--name' allows the modules returned to be filtered based

  38521. the name of the module.

  38522. 

  38523.    The option '--max-results' restricts the command to return no more

  38524. than LIMIT results.  If exactly LIMIT results are returned then there

  38525. might be additional results available if a higher limit is used.

  38526. 

  38527. GDB Command

  38528. ...........

  38529. 

  38530. The corresponding GDB command is 'info modules'.

  38531. 

  38532. Example

  38533. .......

  38534. 

  38535.      (gdb)

  38536.      -symbol-info-modules

  38537.      ^done,symbols=

  38538.        {debug=

  38539.          [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38540.            fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38541.            symbols=[{line="16",name="mod1"},

  38542.                     {line="22",name="mod2"}]},

  38543.           {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38544.            fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38545.            symbols=[{line="16",name="mod3"},

  38546.                     {line="22",name="modmany"},

  38547.                     {line="26",name="moduse"}]}]}

  38548.      (gdb)

  38549.      -symbol-info-modules --name mod[123]

  38550.      ^done,symbols=

  38551.        {debug=

  38552.          [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38553.            fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",

  38554.            symbols=[{line="16",name="mod1"},

  38555.                     {line="22",name="mod2"}]},

  38556.           {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38557.            fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",

  38558.            symbols=[{line="16",name="mod3"}]}]}

  38559. 

  38560. The '-symbol-info-types' Command

  38561. --------------------------------

  38562. 

  38563. Synopsis

  38564. ........

  38565. 

  38566.       -symbol-info-types [--name NAME_REGEXP]

  38567.                          [--max-results LIMIT]

  38568. 

  38569. 

  38570. Return a list of all defined types.  The types are grouped by source

  38571. file, and shown with the line number on which each user defined type is

  38572. defined.  Some base types are not defined in the source code but are

  38573. added to the debug information by the compiler, for example 'int',

  38574. 'float', etc.; these types do not have an associated line number.

  38575. 

  38576.    The option '--name' allows the list of types returned to be filtered

  38577. by name.

  38578. 

  38579.    The option '--max-results' restricts the command to return no more

  38580. than LIMIT results.  If exactly LIMIT results are returned then there

  38581. might be additional results available if a higher limit is used.

  38582. 

  38583. GDB Command

  38584. ...........

  38585. 

  38586. The corresponding GDB command is 'info types'.

  38587. 

  38588. Example

  38589. .......

  38590. 

  38591.      (gdb)

  38592.      -symbol-info-types

  38593.      ^done,symbols=

  38594.        {debug=

  38595.           [{filename="gdb.mi/mi-sym-info-1.c",

  38596.             fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38597.             symbols=[{name="float"},

  38598.                      {name="int"},

  38599.                      {line="27",name="typedef int my_int_t;"}]},

  38600.            {filename="gdb.mi/mi-sym-info-2.c",

  38601.             fullname="/project/gdb.mi/mi-sym-info-2.c",

  38602.             symbols=[{line="24",name="typedef float another_float_t;"},

  38603.                      {line="23",name="typedef int another_int_t;"},

  38604.                      {name="float"},

  38605.                      {name="int"}]}]}

  38606.      (gdb)

  38607.      -symbol-info-types --name _int_

  38608.      ^done,symbols=

  38609.        {debug=

  38610.           [{filename="gdb.mi/mi-sym-info-1.c",

  38611.             fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38612.             symbols=[{line="27",name="typedef int my_int_t;"}]},

  38613.            {filename="gdb.mi/mi-sym-info-2.c",

  38614.             fullname="/project/gdb.mi/mi-sym-info-2.c",

  38615.             symbols=[{line="23",name="typedef int another_int_t;"}]}]}

  38616. 

  38617. The '-symbol-info-variables' Command

  38618. ------------------------------------

  38619. 

  38620. Synopsis

  38621. ........

  38622. 

  38623.       -symbol-info-variables [--include-nondebug]

  38624.                              [--type TYPE_REGEXP]

  38625.                              [--name NAME_REGEXP]

  38626.                              [--max-results LIMIT]

  38627. 

  38628. 

  38629. Return a list containing the names and types for all global variables

  38630. taken from the debug information.  The variables are grouped by source

  38631. file, and shown with the line number on which each variable is defined.

  38632. 

  38633.    The '--include-nondebug' option causes the output to include data

  38634. symbols from the symbol table.

  38635. 

  38636.    The options '--type' and '--name' allow the symbols returned to be

  38637. filtered based on either the name of the variable, or the type of the

  38638. variable.

  38639. 

  38640.    The option '--max-results' restricts the command to return no more

  38641. than LIMIT results.  If exactly LIMIT results are returned then there

  38642. might be additional results available if a higher limit is used.

  38643. 

  38644. GDB Command

  38645. ...........

  38646. 

  38647. The corresponding GDB command is 'info variables'.

  38648. 

  38649. Example

  38650. .......

  38651. 

  38652.      (gdb)

  38653.      -symbol-info-variables

  38654.      ^done,symbols=

  38655.        {debug=

  38656.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38657.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38658.            symbols=[{line="25",name="global_f1",type="float",

  38659.                      description="static float global_f1;"},

  38660.                     {line="24",name="global_i1",type="int",

  38661.                      description="static int global_i1;"}]},

  38662.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38663.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38664.            symbols=[{line="21",name="global_f2",type="int",

  38665.                      description="int global_f2;"},

  38666.                     {line="20",name="global_i2",type="int",

  38667.                      description="int global_i2;"},

  38668.                     {line="19",name="global_f1",type="float",

  38669.                      description="static float global_f1;"},

  38670.                     {line="18",name="global_i1",type="int",

  38671.                      description="static int global_i1;"}]}]}

  38672.      (gdb)

  38673.      -symbol-info-variables --name f1

  38674.      ^done,symbols=

  38675.        {debug=

  38676.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38677.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38678.            symbols=[{line="25",name="global_f1",type="float",

  38679.                      description="static float global_f1;"}]},

  38680.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38681.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38682.            symbols=[{line="19",name="global_f1",type="float",

  38683.                      description="static float global_f1;"}]}]}

  38684.      (gdb)

  38685.      -symbol-info-variables --type float

  38686.      ^done,symbols=

  38687.        {debug=

  38688.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38689.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38690.            symbols=[{line="25",name="global_f1",type="float",

  38691.                      description="static float global_f1;"}]},

  38692.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38693.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38694.            symbols=[{line="19",name="global_f1",type="float",

  38695.                      description="static float global_f1;"}]}]}

  38696.      (gdb)

  38697.      -symbol-info-variables --include-nondebug

  38698.      ^done,symbols=

  38699.        {debug=

  38700.          [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38701.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",

  38702.            symbols=[{line="25",name="global_f1",type="float",

  38703.                      description="static float global_f1;"},

  38704.                     {line="24",name="global_i1",type="int",

  38705.                      description="static int global_i1;"}]},

  38706.           {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38707.            fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",

  38708.            symbols=[{line="21",name="global_f2",type="int",

  38709.                      description="int global_f2;"},

  38710.                     {line="20",name="global_i2",type="int",

  38711.                      description="int global_i2;"},

  38712.                     {line="19",name="global_f1",type="float",

  38713.                      description="static float global_f1;"},

  38714.                     {line="18",name="global_i1",type="int",

  38715.                      description="static int global_i1;"}]}],

  38716.         nondebug=

  38717.          [{address="0x00000000004005d0",name="_IO_stdin_used"},

  38718.           {address="0x00000000004005d8",name="__dso_handle"}

  38719.            ...

  38720.          ]}

  38721. 

  38722. The '-symbol-list-lines' Command

  38723. --------------------------------

  38724. 

  38725. Synopsis

  38726. ........

  38727. 

  38728.       -symbol-list-lines FILENAME

  38729. 

  38730.    Print the list of lines that contain code and their associated

  38731. program addresses for the given source filename.  The entries are sorted

  38732. in ascending PC order.

  38733. 

  38734. GDB Command

  38735. ...........

  38736. 

  38737. There is no corresponding GDB command.

  38738. 

  38739. Example

  38740. .......

  38741. 

  38742.      (gdb)

  38743.      -symbol-list-lines basics.c

  38744.      ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]

  38745.      (gdb)

  38746. 

  38747. 

  38748. File: gdb.info,  Node: GDB/MI File Commands,  Next: GDB/MI Target Manipulation,  Prev: GDB/MI Symbol Query,  Up: GDB/MI

  38749. 

  38750. 27.19 GDB/MI File Commands

  38751. ==========================

  38752. 

  38753. This section describes the GDB/MI commands to specify executable file

  38754. names and to read in and obtain symbol table information.

  38755. 

  38756. The '-file-exec-and-symbols' Command

  38757. ------------------------------------

  38758. 

  38759. Synopsis

  38760. ........

  38761. 

  38762.       -file-exec-and-symbols FILE

  38763. 

  38764.    Specify the executable file to be debugged.  This file is the one

  38765. from which the symbol table is also read.  If no file is specified, the

  38766. command clears the executable and symbol information.  If breakpoints

  38767. are set when using this command with no arguments, GDB will produce

  38768. error messages.  Otherwise, no output is produced, except a completion

  38769. notification.

  38770. 

  38771. GDB Command

  38772. ...........

  38773. 

  38774. The corresponding GDB command is 'file'.

  38775. 

  38776. Example

  38777. .......

  38778. 

  38779.      (gdb)

  38780.      -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx

  38781.      ^done

  38782.      (gdb)

  38783. 

  38784. The '-file-exec-file' Command

  38785. -----------------------------

  38786. 

  38787. Synopsis

  38788. ........

  38789. 

  38790.       -file-exec-file FILE

  38791. 

  38792.    Specify the executable file to be debugged.  Unlike

  38793. '-file-exec-and-symbols', the symbol table is _not_ read from this file.

  38794. If used without argument, GDB clears the information about the

  38795. executable file.  No output is produced, except a completion

  38796. notification.

  38797. 

  38798. GDB Command

  38799. ...........

  38800. 

  38801. The corresponding GDB command is 'exec-file'.

  38802. 

  38803. Example

  38804. .......

  38805. 

  38806.      (gdb)

  38807.      -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx

  38808.      ^done

  38809.      (gdb)

  38810. 

  38811. The '-file-list-exec-source-file' Command

  38812. -----------------------------------------

  38813. 

  38814. Synopsis

  38815. ........

  38816. 

  38817.       -file-list-exec-source-file

  38818. 

  38819.    List the line number, the current source file, and the absolute path

  38820. to the current source file for the current executable.  The macro

  38821. information field has a value of '1' or '0' depending on whether or not

  38822. the file includes preprocessor macro information.

  38823. 

  38824. GDB Command

  38825. ...........

  38826. 

  38827. The GDB equivalent is 'info source'

  38828. 

  38829. Example

  38830. .......

  38831. 

  38832.      (gdb)

  38833.      123-file-list-exec-source-file

  38834.      123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"

  38835.      (gdb)

  38836. 

  38837. The '-file-list-exec-source-files' Command

  38838. ------------------------------------------

  38839. 

  38840. Synopsis

  38841. ........

  38842. 

  38843.       -file-list-exec-source-files

  38844. 

  38845.    List the source files for the current executable.

  38846. 

  38847.    It will always output both the filename and fullname (absolute file

  38848. name) of a source file.

  38849. 

  38850. GDB Command

  38851. ...........

  38852. 

  38853. The GDB equivalent is 'info sources'.  'gdbtk' has an analogous command

  38854. 'gdb_listfiles'.

  38855. 

  38856. Example

  38857. .......

  38858. 

  38859.      (gdb)

  38860.      -file-list-exec-source-files

  38861.      ^done,files=[

  38862.      {file=foo.c,fullname=/home/foo.c},

  38863.      {file=/home/bar.c,fullname=/home/bar.c},

  38864.      {file=gdb_could_not_find_fullpath.c}]

  38865.      (gdb)

  38866. 

  38867. The '-file-list-shared-libraries' Command

  38868. -----------------------------------------

  38869. 

  38870. Synopsis

  38871. ........

  38872. 

  38873.       -file-list-shared-libraries [ REGEXP ]

  38874. 

  38875.    List the shared libraries in the program.  With a regular expression

  38876. REGEXP, only those libraries whose names match REGEXP are listed.

  38877. 

  38878. GDB Command

  38879. ...........

  38880. 

  38881. The corresponding GDB command is 'info shared'.  The fields have a

  38882. similar meaning to the '=library-loaded' notification.  The 'ranges'

  38883. field specifies the multiple segments belonging to this library.  Each

  38884. range has the following fields:

  38885. 

  38886. 'from'

  38887.      The address defining the inclusive lower bound of the segment.

  38888. 'to'

  38889.      The address defining the exclusive upper bound of the segment.

  38890. 

  38891. Example

  38892. .......

  38893. 

  38894.      (gdb)

  38895.      -file-list-exec-source-files

  38896.      ^done,shared-libraries=[

  38897.      {id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x72815989",to="0x728162c0"}]},

  38898.      {id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x76ee48c0",to="0x76ee9160"}]}]

  38899.      (gdb)

  38900. 

  38901. The '-file-symbol-file' Command

  38902. -------------------------------

  38903. 

  38904. Synopsis

  38905. ........

  38906. 

  38907.       -file-symbol-file FILE

  38908. 

  38909.    Read symbol table info from the specified FILE argument.  When used

  38910. without arguments, clears GDB's symbol table info.  No output is

  38911. produced, except for a completion notification.

  38912. 

  38913. GDB Command

  38914. ...........

  38915. 

  38916. The corresponding GDB command is 'symbol-file'.

  38917. 

  38918. Example

  38919. .......

  38920. 

  38921.      (gdb)

  38922.      -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx

  38923.      ^done

  38924.      (gdb)

  38925. 

  38926. 

  38927. File: gdb.info,  Node: GDB/MI Target Manipulation,  Next: GDB/MI File Transfer Commands,  Prev: GDB/MI File Commands,  Up: GDB/MI

  38928. 

  38929. 27.20 GDB/MI Target Manipulation Commands

  38930. =========================================

  38931. 

  38932. The '-target-attach' Command

  38933. ----------------------------

  38934. 

  38935. Synopsis

  38936. ........

  38937. 

  38938.       -target-attach PID | GID | FILE

  38939. 

  38940.    Attach to a process PID or a file FILE outside of GDB, or a thread

  38941. group GID.  If attaching to a thread group, the id previously returned

  38942. by '-list-thread-groups --available' must be used.

  38943. 

  38944. GDB Command

  38945. ...........

  38946. 

  38947. The corresponding GDB command is 'attach'.

  38948. 

  38949. Example

  38950. .......

  38951. 

  38952.      (gdb)

  38953.      -target-attach 34

  38954.      =thread-created,id="1"

  38955.      *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}

  38956.      ^done

  38957.      (gdb)

  38958. 

  38959. The '-target-detach' Command

  38960. ----------------------------

  38961. 

  38962. Synopsis

  38963. ........

  38964. 

  38965.       -target-detach [ PID | GID ]

  38966. 

  38967.    Detach from the remote target which normally resumes its execution.

  38968. If either PID or GID is specified, detaches from either the specified

  38969. process, or specified thread group.  There's no output.

  38970. 

  38971. GDB Command

  38972. ...........

  38973. 

  38974. The corresponding GDB command is 'detach'.

  38975. 

  38976. Example

  38977. .......

  38978. 

  38979.      (gdb)

  38980.      -target-detach

  38981.      ^done

  38982.      (gdb)

  38983. 

  38984. The '-target-disconnect' Command

  38985. --------------------------------

  38986. 

  38987. Synopsis

  38988. ........

  38989. 

  38990.       -target-disconnect

  38991. 

  38992.    Disconnect from the remote target.  There's no output and the target

  38993. is generally not resumed.

  38994. 

  38995. GDB Command

  38996. ...........

  38997. 

  38998. The corresponding GDB command is 'disconnect'.

  38999. 

  39000. Example

  39001. .......

  39002. 

  39003.      (gdb)

  39004.      -target-disconnect

  39005.      ^done

  39006.      (gdb)

  39007. 

  39008. The '-target-download' Command

  39009. ------------------------------

  39010. 

  39011. Synopsis

  39012. ........

  39013. 

  39014.       -target-download

  39015. 

  39016.    Loads the executable onto the remote target.  It prints out an update

  39017. message every half second, which includes the fields:

  39018. 

  39019. 'section'

  39020.      The name of the section.

  39021. 'section-sent'

  39022.      The size of what has been sent so far for that section.

  39023. 'section-size'

  39024.      The size of the section.

  39025. 'total-sent'

  39026.      The total size of what was sent so far (the current and the

  39027.      previous sections).

  39028. 'total-size'

  39029.      The size of the overall executable to download.

  39030. 

  39031. Each message is sent as status record (*note GDB/MI Output Syntax:

  39032. GDB/MI Output Syntax.).

  39033. 

  39034.    In addition, it prints the name and size of the sections, as they are

  39035. downloaded.  These messages include the following fields:

  39036. 

  39037. 'section'

  39038.      The name of the section.

  39039. 'section-size'

  39040.      The size of the section.

  39041. 'total-size'

  39042.      The size of the overall executable to download.

  39043. 

  39044. At the end, a summary is printed.

  39045. 

  39046. GDB Command

  39047. ...........

  39048. 

  39049. The corresponding GDB command is 'load'.

  39050. 

  39051. Example

  39052. .......

  39053. 

  39054. Note: each status message appears on a single line.  Here the messages

  39055. have been broken down so that they can fit onto a page.

  39056. 

  39057.      (gdb)

  39058.      -target-download

  39059.      +download,{section=".text",section-size="6668",total-size="9880"}

  39060.      +download,{section=".text",section-sent="512",section-size="6668",

  39061.      total-sent="512",total-size="9880"}

  39062.      +download,{section=".text",section-sent="1024",section-size="6668",

  39063.      total-sent="1024",total-size="9880"}

  39064.      +download,{section=".text",section-sent="1536",section-size="6668",

  39065.      total-sent="1536",total-size="9880"}

  39066.      +download,{section=".text",section-sent="2048",section-size="6668",

  39067.      total-sent="2048",total-size="9880"}

  39068.      +download,{section=".text",section-sent="2560",section-size="6668",

  39069.      total-sent="2560",total-size="9880"}

  39070.      +download,{section=".text",section-sent="3072",section-size="6668",

  39071.      total-sent="3072",total-size="9880"}

  39072.      +download,{section=".text",section-sent="3584",section-size="6668",

  39073.      total-sent="3584",total-size="9880"}

  39074.      +download,{section=".text",section-sent="4096",section-size="6668",

  39075.      total-sent="4096",total-size="9880"}

  39076.      +download,{section=".text",section-sent="4608",section-size="6668",

  39077.      total-sent="4608",total-size="9880"}

  39078.      +download,{section=".text",section-sent="5120",section-size="6668",

  39079.      total-sent="5120",total-size="9880"}

  39080.      +download,{section=".text",section-sent="5632",section-size="6668",

  39081.      total-sent="5632",total-size="9880"}

  39082.      +download,{section=".text",section-sent="6144",section-size="6668",

  39083.      total-sent="6144",total-size="9880"}

  39084.      +download,{section=".text",section-sent="6656",section-size="6668",

  39085.      total-sent="6656",total-size="9880"}

  39086.      +download,{section=".init",section-size="28",total-size="9880"}

  39087.      +download,{section=".fini",section-size="28",total-size="9880"}

  39088.      +download,{section=".data",section-size="3156",total-size="9880"}

  39089.      +download,{section=".data",section-sent="512",section-size="3156",

  39090.      total-sent="7236",total-size="9880"}

  39091.      +download,{section=".data",section-sent="1024",section-size="3156",

  39092.      total-sent="7748",total-size="9880"}

  39093.      +download,{section=".data",section-sent="1536",section-size="3156",

  39094.      total-sent="8260",total-size="9880"}

  39095.      +download,{section=".data",section-sent="2048",section-size="3156",

  39096.      total-sent="8772",total-size="9880"}

  39097.      +download,{section=".data",section-sent="2560",section-size="3156",

  39098.      total-sent="9284",total-size="9880"}

  39099.      +download,{section=".data",section-sent="3072",section-size="3156",

  39100.      total-sent="9796",total-size="9880"}

  39101.      ^done,address="0x10004",load-size="9880",transfer-rate="6586",

  39102.      write-rate="429"

  39103.      (gdb)

  39104. 

  39105. GDB Command

  39106. ...........

  39107. 

  39108. No equivalent.

  39109. 

  39110. Example

  39111. .......

  39112. 

  39113. N.A.

  39114. 

  39115. The '-target-flash-erase' Command

  39116. ---------------------------------

  39117. 

  39118. Synopsis

  39119. ........

  39120. 

  39121.       -target-flash-erase

  39122. 

  39123.    Erases all known flash memory regions on the target.

  39124. 

  39125.    The corresponding GDB command is 'flash-erase'.

  39126. 

  39127.    The output is a list of flash regions that have been erased, with

  39128. starting addresses and memory region sizes.

  39129. 

  39130.      (gdb)

  39131.      -target-flash-erase

  39132.      ^done,erased-regions={address="0x0",size="0x40000"}

  39133.      (gdb)

  39134. 

  39135. The '-target-select' Command

  39136. ----------------------------

  39137. 

  39138. Synopsis

  39139. ........

  39140. 

  39141.       -target-select TYPE PARAMETERS ...

  39142. 

  39143.    Connect GDB to the remote target.  This command takes two args:

  39144. 

  39145. 'TYPE'

  39146.      The type of target, for instance 'remote', etc.

  39147. 'PARAMETERS'

  39148.      Device names, host names and the like.  *Note Commands for Managing

  39149.      Targets: Target Commands, for more details.

  39150. 

  39151.    The output is a connection notification, followed by the address at

  39152. which the target program is, in the following form:

  39153. 

  39154.      ^connected,addr="ADDRESS",func="FUNCTION NAME",

  39155.        args=[ARG LIST]

  39156. 

  39157. GDB Command

  39158. ...........

  39159. 

  39160. The corresponding GDB command is 'target'.

  39161. 

  39162. Example

  39163. .......

  39164. 

  39165.      (gdb)

  39166.      -target-select remote /dev/ttya

  39167.      ^connected,addr="0xfe00a300",func="??",args=[]

  39168.      (gdb)

  39169. 

  39170. 

  39171. File: gdb.info,  Node: GDB/MI File Transfer Commands,  Next: GDB/MI Ada Exceptions Commands,  Prev: GDB/MI Target Manipulation,  Up: GDB/MI

  39172. 

  39173. 27.21 GDB/MI File Transfer Commands

  39174. ===================================

  39175. 

  39176. The '-target-file-put' Command

  39177. ------------------------------

  39178. 

  39179. Synopsis

  39180. ........

  39181. 

  39182.       -target-file-put HOSTFILE TARGETFILE

  39183. 

  39184.    Copy file HOSTFILE from the host system (the machine running GDB) to

  39185. TARGETFILE on the target system.

  39186. 

  39187. GDB Command

  39188. ...........

  39189. 

  39190. The corresponding GDB command is 'remote put'.

  39191. 

  39192. Example

  39193. .......

  39194. 

  39195.      (gdb)

  39196.      -target-file-put localfile remotefile

  39197.      ^done

  39198.      (gdb)

  39199. 

  39200. The '-target-file-get' Command

  39201. ------------------------------

  39202. 

  39203. Synopsis

  39204. ........

  39205. 

  39206.       -target-file-get TARGETFILE HOSTFILE

  39207. 

  39208.    Copy file TARGETFILE from the target system to HOSTFILE on the host

  39209. system.

  39210. 

  39211. GDB Command

  39212. ...........

  39213. 

  39214. The corresponding GDB command is 'remote get'.

  39215. 

  39216. Example

  39217. .......

  39218. 

  39219.      (gdb)

  39220.      -target-file-get remotefile localfile

  39221.      ^done

  39222.      (gdb)

  39223. 

  39224. The '-target-file-delete' Command

  39225. ---------------------------------

  39226. 

  39227. Synopsis

  39228. ........

  39229. 

  39230.       -target-file-delete TARGETFILE

  39231. 

  39232.    Delete TARGETFILE from the target system.

  39233. 

  39234. GDB Command

  39235. ...........

  39236. 

  39237. The corresponding GDB command is 'remote delete'.

  39238. 

  39239. Example

  39240. .......

  39241. 

  39242.      (gdb)

  39243.      -target-file-delete remotefile

  39244.      ^done

  39245.      (gdb)

  39246. 

  39247. 

  39248. File: gdb.info,  Node: GDB/MI Ada Exceptions Commands,  Next: GDB/MI Support Commands,  Prev: GDB/MI File Transfer Commands,  Up: GDB/MI

  39249. 

  39250. 27.22 Ada Exceptions GDB/MI Commands

  39251. ====================================

  39252. 

  39253. The '-info-ada-exceptions' Command

  39254. ----------------------------------

  39255. 

  39256. Synopsis

  39257. ........

  39258. 

  39259.       -info-ada-exceptions [ REGEXP]

  39260. 

  39261.    List all Ada exceptions defined within the program being debugged.

  39262. With a regular expression REGEXP, only those exceptions whose names

  39263. match REGEXP are listed.

  39264. 

  39265. GDB Command

  39266. ...........

  39267. 

  39268. The corresponding GDB command is 'info exceptions'.

  39269. 

  39270. Result

  39271. ......

  39272. 

  39273. The result is a table of Ada exceptions.  The following columns are

  39274. defined for each exception:

  39275. 

  39276. 'name'

  39277.      The name of the exception.

  39278. 

  39279. 'address'

  39280.      The address of the exception.

  39281. 

  39282. Example

  39283. .......

  39284. 

  39285.      -info-ada-exceptions aint

  39286.      ^done,ada-exceptions={nr_rows="2",nr_cols="2",

  39287.      hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"},

  39288.      {width="1",alignment="-1",col_name="address",colhdr="Address"}],

  39289.      body=[{name="constraint_error",address="0x0000000000613da0"},

  39290.      {name="const.aint_global_e",address="0x0000000000613b00"}]}

  39291. 

  39292. Catching Ada Exceptions

  39293. -----------------------

  39294. 

  39295. The commands describing how to ask GDB to stop when a program raises an

  39296. exception are described at *note Ada Exception GDB/MI Catchpoint

  39297. Commands::.

  39298. 

  39299. 

  39300. File: gdb.info,  Node: GDB/MI Support Commands,  Next: GDB/MI Miscellaneous Commands,  Prev: GDB/MI Ada Exceptions Commands,  Up: GDB/MI

  39301. 

  39302. 27.23 GDB/MI Support Commands

  39303. =============================

  39304. 

  39305. Since new commands and features get regularly added to GDB/MI, some

  39306. commands are available to help front-ends query the debugger about

  39307. support for these capabilities.  Similarly, it is also possible to query

  39308. GDB about target support of certain features.

  39309. 

  39310. The '-info-gdb-mi-command' Command

  39311. ----------------------------------

  39312. 

  39313. Synopsis

  39314. ........

  39315. 

  39316.       -info-gdb-mi-command CMD_NAME

  39317. 

  39318.    Query support for the GDB/MI command named CMD_NAME.

  39319. 

  39320.    Note that the dash ('-') starting all GDB/MI commands is technically

  39321. not part of the command name (*note GDB/MI Input Syntax::), and thus

  39322. should be omitted in CMD_NAME.  However, for ease of use, this command

  39323. also accepts the form with the leading dash.

  39324. 

  39325. GDB Command

  39326. ...........

  39327. 

  39328. There is no corresponding GDB command.

  39329. 

  39330. Result

  39331. ......

  39332. 

  39333. The result is a tuple.  There is currently only one field:

  39334. 

  39335. 'exists'

  39336.      This field is equal to '"true"' if the GDB/MI command exists,

  39337.      '"false"' otherwise.

  39338. 

  39339. Example

  39340. .......

  39341. 

  39342. Here is an example where the GDB/MI command does not exist:

  39343. 

  39344.      -info-gdb-mi-command unsupported-command

  39345.      ^done,command={exists="false"}

  39346. 

  39347. And here is an example where the GDB/MI command is known to the

  39348. debugger:

  39349. 

  39350.      -info-gdb-mi-command symbol-list-lines

  39351.      ^done,command={exists="true"}

  39352. 

  39353. The '-list-features' Command

  39354. ----------------------------

  39355. 

  39356. Returns a list of particular features of the MI protocol that this

  39357. version of gdb implements.  A feature can be a command, or a new field

  39358. in an output of some command, or even an important bugfix.  While a

  39359. frontend can sometimes detect presence of a feature at runtime, it is

  39360. easier to perform detection at debugger startup.

  39361. 

  39362.    The command returns a list of strings, with each string naming an

  39363. available feature.  Each returned string is just a name, it does not

  39364. have any internal structure.  The list of possible feature names is

  39365. given below.

  39366. 

  39367.    Example output:

  39368. 

  39369.      (gdb) -list-features

  39370.      ^done,result=["feature1","feature2"]

  39371. 

  39372.    The current list of features is:

  39373. 

  39374. 'frozen-varobjs'

  39375.      Indicates support for the '-var-set-frozen' command, as well as

  39376.      possible presence of the 'frozen' field in the output of

  39377.      '-varobj-create'.

  39378. 'pending-breakpoints'

  39379.      Indicates support for the '-f' option to the '-break-insert'

  39380.      command.

  39381. 'python'

  39382.      Indicates Python scripting support, Python-based pretty-printing

  39383.      commands, and possible presence of the 'display_hint' field in the

  39384.      output of '-var-list-children'

  39385. 'thread-info'

  39386.      Indicates support for the '-thread-info' command.

  39387. 'data-read-memory-bytes'

  39388.      Indicates support for the '-data-read-memory-bytes' and the

  39389.      '-data-write-memory-bytes' commands.

  39390. 'breakpoint-notifications'

  39391.      Indicates that changes to breakpoints and breakpoints created via

  39392.      the CLI will be announced via async records.

  39393. 'ada-task-info'

  39394.      Indicates support for the '-ada-task-info' command.

  39395. 'language-option'

  39396.      Indicates that all GDB/MI commands accept the '--language' option

  39397.      (*note Context management::).

  39398. 'info-gdb-mi-command'

  39399.      Indicates support for the '-info-gdb-mi-command' command.

  39400. 'undefined-command-error-code'

  39401.      Indicates support for the "undefined-command" error code in error

  39402.      result records, produced when trying to execute an undefined GDB/MI

  39403.      command (*note GDB/MI Result Records::).

  39404. 'exec-run-start-option'

  39405.      Indicates that the '-exec-run' command supports the '--start'

  39406.      option (*note GDB/MI Program Execution::).

  39407. 'data-disassemble-a-option'

  39408.      Indicates that the '-data-disassemble' command supports the '-a'

  39409.      option (*note GDB/MI Data Manipulation::).

  39410. 

  39411. The '-list-target-features' Command

  39412. -----------------------------------

  39413. 

  39414. Returns a list of particular features that are supported by the target.

  39415. Those features affect the permitted MI commands, but unlike the features

  39416. reported by the '-list-features' command, the features depend on which

  39417. target GDB is using at the moment.  Whenever a target can change, due to

  39418. commands such as '-target-select', '-target-attach' or '-exec-run', the

  39419. list of target features may change, and the frontend should obtain it

  39420. again.  Example output:

  39421. 

  39422.      (gdb) -list-target-features

  39423.      ^done,result=["async"]

  39424. 

  39425.    The current list of features is:

  39426. 

  39427. 'async'

  39428.      Indicates that the target is capable of asynchronous command

  39429.      execution, which means that GDB will accept further commands while

  39430.      the target is running.

  39431. 

  39432. 'reverse'

  39433.      Indicates that the target is capable of reverse execution.  *Note

  39434.      Reverse Execution::, for more information.

  39435. 

  39436. 

  39437. File: gdb.info,  Node: GDB/MI Miscellaneous Commands,  Prev: GDB/MI Support Commands,  Up: GDB/MI

  39438. 

  39439. 27.24 Miscellaneous GDB/MI Commands

  39440. ===================================

  39441. 

  39442. The '-gdb-exit' Command

  39443. -----------------------

  39444. 

  39445. Synopsis

  39446. ........

  39447. 

  39448.       -gdb-exit

  39449. 

  39450.    Exit GDB immediately.

  39451. 

  39452. GDB Command

  39453. ...........

  39454. 

  39455. Approximately corresponds to 'quit'.

  39456. 

  39457. Example

  39458. .......

  39459. 

  39460.      (gdb)

  39461.      -gdb-exit

  39462.      ^exit

  39463. 

  39464. The '-gdb-set' Command

  39465. ----------------------

  39466. 

  39467. Synopsis

  39468. ........

  39469. 

  39470.       -gdb-set

  39471. 

  39472.    Set an internal GDB variable.

  39473. 

  39474. GDB Command

  39475. ...........

  39476. 

  39477. The corresponding GDB command is 'set'.

  39478. 

  39479. Example

  39480. .......

  39481. 

  39482.      (gdb)

  39483.      -gdb-set $foo=3

  39484.      ^done

  39485.      (gdb)

  39486. 

  39487. The '-gdb-show' Command

  39488. -----------------------

  39489. 

  39490. Synopsis

  39491. ........

  39492. 

  39493.       -gdb-show

  39494. 

  39495.    Show the current value of a GDB variable.

  39496. 

  39497. GDB Command

  39498. ...........

  39499. 

  39500. The corresponding GDB command is 'show'.

  39501. 

  39502. Example

  39503. .......

  39504. 

  39505.      (gdb)

  39506.      -gdb-show annotate

  39507.      ^done,value="0"

  39508.      (gdb)

  39509. 

  39510. The '-gdb-version' Command

  39511. --------------------------

  39512. 

  39513. Synopsis

  39514. ........

  39515. 

  39516.       -gdb-version

  39517. 

  39518.    Show version information for GDB.  Used mostly in testing.

  39519. 

  39520. GDB Command

  39521. ...........

  39522. 

  39523. The GDB equivalent is 'show version'.  GDB by default shows this

  39524. information when you start an interactive session.

  39525. 

  39526. Example

  39527. .......

  39528. 

  39529.      (gdb)

  39530.      -gdb-version

  39531.      ~GNU gdb 5.2.1

  39532.      ~Copyright 2000 Free Software Foundation, Inc.

  39533.      ~GDB is free software, covered by the GNU General Public License, and

  39534.      ~you are welcome to change it and/or distribute copies of it under

  39535.      ~ certain conditions.

  39536.      ~Type "show copying" to see the conditions.

  39537.      ~There is absolutely no warranty for GDB.  Type "show warranty" for

  39538.      ~ details.

  39539.      ~This GDB was configured as

  39540.       "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".

  39541.      ^done

  39542.      (gdb)

  39543. 

  39544. The '-list-thread-groups' Command

  39545. ---------------------------------

  39546. 

  39547. Synopsis

  39548. --------

  39549. 

  39550.      -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]

  39551. 

  39552.    Lists thread groups (*note Thread groups::).  When a single thread

  39553. group is passed as the argument, lists the children of that group.  When

  39554. several thread group are passed, lists information about those thread

  39555. groups.  Without any parameters, lists information about all top-level

  39556. thread groups.

  39557. 

  39558.    Normally, thread groups that are being debugged are reported.  With

  39559. the '--available' option, GDB reports thread groups available on the

  39560. target.

  39561. 

  39562.    The output of this command may have either a 'threads' result or a

  39563. 'groups' result.  The 'thread' result has a list of tuples as value,

  39564. with each tuple describing a thread (*note GDB/MI Thread Information::).

  39565. The 'groups' result has a list of tuples as value, each tuple describing

  39566. a thread group.  If top-level groups are requested (that is, no

  39567. parameter is passed), or when several groups are passed, the output

  39568. always has a 'groups' result.  The format of the 'group' result is

  39569. described below.

  39570. 

  39571.    To reduce the number of roundtrips it's possible to list thread

  39572. groups together with their children, by passing the '--recurse' option

  39573. and the recursion depth.  Presently, only recursion depth of 1 is

  39574. permitted.  If this option is present, then every reported thread group

  39575. will also include its children, either as 'group' or 'threads' field.

  39576. 

  39577.    In general, any combination of option and parameters is permitted,

  39578. with the following caveats:

  39579. 

  39580.    * When a single thread group is passed, the output will typically be

  39581.      the 'threads' result.  Because threads may not contain anything,

  39582.      the 'recurse' option will be ignored.

  39583. 

  39584.    * When the '--available' option is passed, limited information may be

  39585.      available.  In particular, the list of threads of a process might

  39586.      be inaccessible.  Further, specifying specific thread groups might

  39587.      not give any performance advantage over listing all thread groups.

  39588.      The frontend should assume that '-list-thread-groups --available'

  39589.      is always an expensive operation and cache the results.

  39590. 

  39591.    The 'groups' result is a list of tuples, where each tuple may have

  39592. the following fields:

  39593. 

  39594. 'id'

  39595.      Identifier of the thread group.  This field is always present.  The

  39596.      identifier is an opaque string; frontends should not try to convert

  39597.      it to an integer, even though it might look like one.

  39598. 

  39599. 'type'

  39600.      The type of the thread group.  At present, only 'process' is a

  39601.      valid type.

  39602. 

  39603. 'pid'

  39604.      The target-specific process identifier.  This field is only present

  39605.      for thread groups of type 'process' and only if the process exists.

  39606. 

  39607. 'exit-code'

  39608.      The exit code of this group's last exited thread, formatted in

  39609.      octal.  This field is only present for thread groups of type

  39610.      'process' and only if the process is not running.

  39611. 

  39612. 'num_children'

  39613.      The number of children this thread group has.  This field may be

  39614.      absent for an available thread group.

  39615. 

  39616. 'threads'

  39617.      This field has a list of tuples as value, each tuple describing a

  39618.      thread.  It may be present if the '--recurse' option is specified,

  39619.      and it's actually possible to obtain the threads.

  39620. 

  39621. 'cores'

  39622.      This field is a list of integers, each identifying a core that one

  39623.      thread of the group is running on.  This field may be absent if

  39624.      such information is not available.

  39625. 

  39626. 'executable'

  39627.      The name of the executable file that corresponds to this thread

  39628.      group.  The field is only present for thread groups of type

  39629.      'process', and only if there is a corresponding executable file.

  39630. 

  39631. Example

  39632. -------

  39633. 

  39634.      gdb

  39635.      -list-thread-groups

  39636.      ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]

  39637.      -list-thread-groups 17

  39638.      ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",

  39639.         frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},

  39640.      {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",

  39641.         frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],

  39642.                 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"},state="running"}]]

  39643.      -list-thread-groups --available

  39644.      ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]

  39645.      -list-thread-groups --available --recurse 1

  39646.       ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],

  39647.                      threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},

  39648.                               {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]

  39649.      -list-thread-groups --available --recurse 1 17 18

  39650.      ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],

  39651.                     threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},

  39652.                              {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]

  39653. 

  39654. The '-info-os' Command

  39655. ----------------------

  39656. 

  39657. Synopsis

  39658. ........

  39659. 

  39660.      -info-os [ TYPE ]

  39661. 

  39662.    If no argument is supplied, the command returns a table of available

  39663. operating-system-specific information types.  If one of these types is

  39664. supplied as an argument TYPE, then the command returns a table of data

  39665. of that type.

  39666. 

  39667.    The types of information available depend on the target operating

  39668. system.

  39669. 

  39670. GDB Command

  39671. ...........

  39672. 

  39673. The corresponding GDB command is 'info os'.

  39674. 

  39675. Example

  39676. .......

  39677. 

  39678. When run on a GNU/Linux system, the output will look something like

  39679. this:

  39680. 

  39681.      gdb

  39682.      -info-os

  39683.      ^done,OSDataTable={nr_rows="10",nr_cols="3",

  39684.      hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},

  39685.           {width="10",alignment="-1",col_name="col1",colhdr="Description"},

  39686.           {width="10",alignment="-1",col_name="col2",colhdr="Title"}],

  39687.      body=[item={col0="cpus",col1="Listing of all cpus/cores on the system",

  39688.                  col2="CPUs"},

  39689.            item={col0="files",col1="Listing of all file descriptors",

  39690.                  col2="File descriptors"},

  39691.            item={col0="modules",col1="Listing of all loaded kernel modules",

  39692.                  col2="Kernel modules"},

  39693.            item={col0="msg",col1="Listing of all message queues",

  39694.                  col2="Message queues"},

  39695.            item={col0="processes",col1="Listing of all processes",

  39696.                  col2="Processes"},

  39697.            item={col0="procgroups",col1="Listing of all process groups",

  39698.                  col2="Process groups"},

  39699.            item={col0="semaphores",col1="Listing of all semaphores",

  39700.                  col2="Semaphores"},

  39701.            item={col0="shm",col1="Listing of all shared-memory regions",

  39702.                  col2="Shared-memory regions"},

  39703.            item={col0="sockets",col1="Listing of all internet-domain sockets",

  39704.                  col2="Sockets"},

  39705.            item={col0="threads",col1="Listing of all threads",

  39706.                  col2="Threads"}]

  39707.      gdb

  39708.      -info-os processes

  39709.      ^done,OSDataTable={nr_rows="190",nr_cols="4",

  39710.      hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},

  39711.           {width="10",alignment="-1",col_name="col1",colhdr="user"},

  39712.           {width="10",alignment="-1",col_name="col2",colhdr="command"},

  39713.           {width="10",alignment="-1",col_name="col3",colhdr="cores"}],

  39714.      body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},

  39715.            item={col0="2",col1="root",col2="[kthreadd]",col3="1"},

  39716.            item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},

  39717.            ...

  39718.            item={col0="26446",col1="stan",col2="bash",col3="0"},

  39719.            item={col0="28152",col1="stan",col2="bash",col3="1"}]}

  39720.      (gdb)

  39721. 

  39722.    (Note that the MI output here includes a '"Title"' column that does

  39723. not appear in command-line 'info os'; this column is useful for MI

  39724. clients that want to enumerate the types of data, such as in a popup

  39725. menu, but is needless clutter on the command line, and 'info os' omits

  39726. it.)

  39727. 

  39728. The '-add-inferior' Command

  39729. ---------------------------

  39730. 

  39731. Synopsis

  39732. --------

  39733. 

  39734.      -add-inferior

  39735. 

  39736.    Creates a new inferior (*note Inferiors Connections and Programs::).

  39737. The created inferior is not associated with any executable.  Such

  39738. association may be established with the '-file-exec-and-symbols' command

  39739. (*note GDB/MI File Commands::).  The command response has a single

  39740. field, 'inferior', whose value is the identifier of the thread group

  39741. corresponding to the new inferior.

  39742. 

  39743. Example

  39744. -------

  39745. 

  39746.      gdb

  39747.      -add-inferior

  39748.      ^done,inferior="i3"

  39749. 

  39750. The '-interpreter-exec' Command

  39751. -------------------------------

  39752. 

  39753. Synopsis

  39754. --------

  39755. 

  39756.      -interpreter-exec INTERPRETER COMMAND

  39757. 

  39758.    Execute the specified COMMAND in the given INTERPRETER.

  39759. 

  39760. GDB Command

  39761. -----------

  39762. 

  39763. The corresponding GDB command is 'interpreter-exec'.

  39764. 

  39765. Example

  39766. -------

  39767. 

  39768.      (gdb)

  39769.      -interpreter-exec console "break main"

  39770.      &"During symbol reading, couldn't parse type; debugger out of date?.\n"

  39771.      &"During symbol reading, bad structure-type format.\n"

  39772.      ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"

  39773.      ^done

  39774.      (gdb)

  39775. 

  39776. The '-inferior-tty-set' Command

  39777. -------------------------------

  39778. 

  39779. Synopsis

  39780. --------

  39781. 

  39782.      -inferior-tty-set /dev/pts/1

  39783. 

  39784.    Set terminal for future runs of the program being debugged.

  39785. 

  39786. GDB Command

  39787. -----------

  39788. 

  39789. The corresponding GDB command is 'set inferior-tty' /dev/pts/1.

  39790. 

  39791. Example

  39792. -------

  39793. 

  39794.      (gdb)

  39795.      -inferior-tty-set /dev/pts/1

  39796.      ^done

  39797.      (gdb)

  39798. 

  39799. The '-inferior-tty-show' Command

  39800. --------------------------------

  39801. 

  39802. Synopsis

  39803. --------

  39804. 

  39805.      -inferior-tty-show

  39806. 

  39807.    Show terminal for future runs of program being debugged.

  39808. 

  39809. GDB Command

  39810. -----------

  39811. 

  39812. The corresponding GDB command is 'show inferior-tty'.

  39813. 

  39814. Example

  39815. -------

  39816. 

  39817.      (gdb)

  39818.      -inferior-tty-set /dev/pts/1

  39819.      ^done

  39820.      (gdb)

  39821.      -inferior-tty-show

  39822.      ^done,inferior_tty_terminal="/dev/pts/1"

  39823.      (gdb)

  39824. 

  39825. The '-enable-timings' Command

  39826. -----------------------------

  39827. 

  39828. Synopsis

  39829. --------

  39830. 

  39831.      -enable-timings [yes | no]

  39832. 

  39833.    Toggle the printing of the wallclock, user and system times for an MI

  39834. command as a field in its output.  This command is to help frontend

  39835. developers optimize the performance of their code.  No argument is

  39836. equivalent to 'yes'.

  39837. 

  39838. GDB Command

  39839. -----------

  39840. 

  39841. No equivalent.

  39842. 

  39843. Example

  39844. -------

  39845. 

  39846.      (gdb)

  39847.      -enable-timings

  39848.      ^done

  39849.      (gdb)

  39850.      -break-insert main

  39851.      ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",

  39852.      addr="0x080484ed",func="main",file="myprog.c",

  39853.      fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],

  39854.      times="0"},

  39855.      time={wallclock="0.05185",user="0.00800",system="0.00000"}

  39856.      (gdb)

  39857.      -enable-timings no

  39858.      ^done

  39859.      (gdb)

  39860.      -exec-run

  39861.      ^running

  39862.      (gdb)

  39863.      *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",

  39864.      frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},

  39865.      {name="argv",value="0xbfb60364"}],file="myprog.c",

  39866.      fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"}

  39867.      (gdb)

  39868. 

  39869. The '-complete' Command

  39870. -----------------------

  39871. 

  39872. Synopsis

  39873. --------

  39874. 

  39875.      -complete COMMAND

  39876. 

  39877.    Show a list of completions for partially typed CLI COMMAND.

  39878. 

  39879.    This command is intended for GDB/MI frontends that cannot use two

  39880. separate CLI and MI channels -- for example: because of lack of PTYs

  39881. like on Windows or because GDB is used remotely via a SSH connection.

  39882. 

  39883. Result

  39884. ------

  39885. 

  39886. The result consists of two or three fields:

  39887. 

  39888. 'completion'

  39889.      This field contains the completed COMMAND.  If COMMAND has no known

  39890.      completions, this field is omitted.

  39891. 

  39892. 'matches'

  39893.      This field contains a (possibly empty) array of matches.  It is

  39894.      always present.

  39895. 

  39896. 'max_completions_reached'

  39897.      This field contains '1' if number of known completions is above

  39898.      'max-completions' limit (*note Completion::), otherwise it contains

  39899.      '0'.  It is always present.

  39900. 

  39901. GDB Command

  39902. -----------

  39903. 

  39904. The corresponding GDB command is 'complete'.

  39905. 

  39906. Example

  39907. -------

  39908. 

  39909.      (gdb)

  39910.      -complete br

  39911.      ^done,completion="break",

  39912.            matches=["break","break-range"],

  39913.            max_completions_reached="0"

  39914.      (gdb)

  39915.      -complete "b ma"

  39916.      ^done,completion="b ma",

  39917.            matches=["b madvise","b main"],max_completions_reached="0"

  39918.      (gdb)

  39919.      -complete "b push_b"

  39920.      ^done,completion="b push_back(",

  39921.            matches=[

  39922.             "b A::push_back(void*)",

  39923.             "b std::string::push_back(char)",

  39924.             "b std::vector<int, std::allocator<int> >::push_back(int&&)"],

  39925.            max_completions_reached="0"

  39926.      (gdb)

  39927.      -complete "nonexist"

  39928.      ^done,matches=[],max_completions_reached="0"

  39929.      (gdb)

  39930. 

  39931. 

  39932. 

  39933. File: gdb.info,  Node: Annotations,  Next: JIT Interface,  Prev: GDB/MI,  Up: Top

  39934. 

  39935. 28 GDB Annotations

  39936. ******************

  39937. 

  39938. This chapter describes annotations in GDB.  Annotations were designed to

  39939. interface GDB to graphical user interfaces or other similar programs

  39940. which want to interact with GDB at a relatively high level.

  39941. 

  39942.    The annotation mechanism has largely been superseded by GDB/MI (*note

  39943. GDB/MI::).

  39944. 

  39945. * Menu:

  39946. 

  39947. * Annotations Overview::  What annotations are; the general syntax.

  39948. * Server Prefix::       Issuing a command without affecting user state.

  39949. * Prompting::           Annotations marking GDB's need for input.

  39950. * Errors::              Annotations for error messages.

  39951. * Invalidation::        Some annotations describe things now invalid.

  39952. * Annotations for Running::

  39953.                         Whether the program is running, how it stopped, etc.

  39954. * Source Annotations::  Annotations describing source code.

  39955. 

  39956. 

  39957. File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations

  39958. 

  39959. 28.1 What is an Annotation?

  39960. ===========================

  39961. 

  39962. Annotations start with a newline character, two 'control-z' characters,

  39963. and the name of the annotation.  If there is no additional information

  39964. associated with this annotation, the name of the annotation is followed

  39965. immediately by a newline.  If there is additional information, the name

  39966. of the annotation is followed by a space, the additional information,

  39967. and a newline.  The additional information cannot contain newline

  39968. characters.

  39969. 

  39970.    Any output not beginning with a newline and two 'control-z'

  39971. characters denotes literal output from GDB.  Currently there is no need

  39972. for GDB to output a newline followed by two 'control-z' characters, but

  39973. if there was such a need, the annotations could be extended with an

  39974. 'escape' annotation which means those three characters as output.

  39975. 

  39976.    The annotation LEVEL, which is specified using the '--annotate'

  39977. command line option (*note Mode Options::), controls how much

  39978. information GDB prints together with its prompt, values of expressions,

  39979. source lines, and other types of output.  Level 0 is for no annotations,

  39980. level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3

  39981. is the maximum annotation suitable for programs that control GDB, and

  39982. level 2 annotations have been made obsolete (*note Limitations of the

  39983. Annotation Interface: (annotate)Limitations.).

  39984. 

  39985. 'set annotate LEVEL'

  39986.      The GDB command 'set annotate' sets the level of annotations to the

  39987.      specified LEVEL.

  39988. 

  39989. 'show annotate'

  39990.      Show the current annotation level.

  39991. 

  39992.    This chapter describes level 3 annotations.

  39993. 

  39994.    A simple example of starting up GDB with annotations is:

  39995. 

  39996.      $ gdb --annotate=3

  39997.      GNU gdb 6.0

  39998.      Copyright 2003 Free Software Foundation, Inc.

  39999.      GDB is free software, covered by the GNU General Public License,

  40000.      and you are welcome to change it and/or distribute copies of it

  40001.      under certain conditions.

  40002.      Type "show copying" to see the conditions.

  40003.      There is absolutely no warranty for GDB.  Type "show warranty"

  40004.      for details.

  40005.      This GDB was configured as "i386-pc-linux-gnu"

  40006. 

  40007.      ^Z^Zpre-prompt

  40008.      (gdb)

  40009.      ^Z^Zprompt

  40010.      quit

  40011. 

  40012.      ^Z^Zpost-prompt

  40013.      $

  40014. 

  40015.    Here 'quit' is input to GDB; the rest is output from GDB.  The three

  40016. lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are

  40017. annotations; the rest is output from GDB.

  40018. 

  40019. 

  40020. File: gdb.info,  Node: Server Prefix,  Next: Prompting,  Prev: Annotations Overview,  Up: Annotations

  40021. 

  40022. 28.2 The Server Prefix

  40023. ======================

  40024. 

  40025. If you prefix a command with 'server ' then it will not affect the

  40026. command history, nor will it affect GDB's notion of which command to

  40027. repeat if <RET> is pressed on a line by itself.  This means that

  40028. commands can be run behind a user's back by a front-end in a transparent

  40029. manner.

  40030. 

  40031.    The 'server ' prefix does not affect the recording of values into the

  40032. value history; to print a value without recording it into the value

  40033. history, use the 'output' command instead of the 'print' command.

  40034. 

  40035.    Using this prefix also disables confirmation requests (*note

  40036. confirmation requests::).

  40037. 

  40038. 

  40039. File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Server Prefix,  Up: Annotations

  40040. 

  40041. 28.3 Annotation for GDB Input

  40042. =============================

  40043. 

  40044. When GDB prompts for input, it annotates this fact so it is possible to

  40045. know when to send output, when the output from a given command is over,

  40046. etc.

  40047. 

  40048.    Different kinds of input each have a different "input type".  Each

  40049. input type has three annotations: a 'pre-' annotation, which denotes the

  40050. beginning of any prompt which is being output, a plain annotation, which

  40051. denotes the end of the prompt, and then a 'post-' annotation which

  40052. denotes the end of any echo which may (or may not) be associated with

  40053. the input.  For example, the 'prompt' input type features the following

  40054. annotations:

  40055. 

  40056.      ^Z^Zpre-prompt

  40057.      ^Z^Zprompt

  40058.      ^Z^Zpost-prompt

  40059. 

  40060.    The input types are

  40061. 

  40062. 'prompt'

  40063.      When GDB is prompting for a command (the main GDB prompt).

  40064. 

  40065. 'commands'

  40066.      When GDB prompts for a set of commands, like in the 'commands'

  40067.      command.  The annotations are repeated for each command which is

  40068.      input.

  40069. 

  40070. 'overload-choice'

  40071.      When GDB wants the user to select between various overloaded

  40072.      functions.

  40073. 

  40074. 'query'

  40075.      When GDB wants the user to confirm a potentially dangerous

  40076.      operation.

  40077. 

  40078. 'prompt-for-continue'

  40079.      When GDB is asking the user to press return to continue.  Note:

  40080.      Don't expect this to work well; instead use 'set height 0' to

  40081.      disable prompting.  This is because the counting of lines is buggy

  40082.      in the presence of annotations.

  40083. 

  40084. 

  40085. File: gdb.info,  Node: Errors,  Next: Invalidation,  Prev: Prompting,  Up: Annotations

  40086. 

  40087. 28.4 Errors

  40088. ===========

  40089. 

  40090.      ^Z^Zquit

  40091. 

  40092.    This annotation occurs right before GDB responds to an interrupt.

  40093. 

  40094.      ^Z^Zerror

  40095. 

  40096.    This annotation occurs right before GDB responds to an error.

  40097. 

  40098.    Quit and error annotations indicate that any annotations which GDB

  40099. was in the middle of may end abruptly.  For example, if a

  40100. 'value-history-begin' annotation is followed by a 'error', one cannot

  40101. expect to receive the matching 'value-history-end'.  One cannot expect

  40102. not to receive it either, however; an error annotation does not

  40103. necessarily mean that GDB is immediately returning all the way to the

  40104. top level.

  40105. 

  40106.    A quit or error annotation may be preceded by

  40107. 

  40108.      ^Z^Zerror-begin

  40109. 

  40110.    Any output between that and the quit or error annotation is the error

  40111. message.

  40112. 

  40113.    Warning messages are not yet annotated.

  40114. 

  40115. 

  40116. File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Errors,  Up: Annotations

  40117. 

  40118. 28.5 Invalidation Notices

  40119. =========================

  40120. 

  40121. The following annotations say that certain pieces of state may have

  40122. changed.

  40123. 

  40124. '^Z^Zframes-invalid'

  40125. 

  40126.      The frames (for example, output from the 'backtrace' command) may

  40127.      have changed.

  40128. 

  40129. '^Z^Zbreakpoints-invalid'

  40130. 

  40131.      The breakpoints may have changed.  For example, the user just added

  40132.      or deleted a breakpoint.

  40133. 

  40134. 

  40135. File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations

  40136. 

  40137. 28.6 Running the Program

  40138. ========================

  40139. 

  40140. When the program starts executing due to a GDB command such as 'step' or

  40141. 'continue',

  40142. 

  40143.      ^Z^Zstarting

  40144. 

  40145.    is output.  When the program stops,

  40146. 

  40147.      ^Z^Zstopped

  40148. 

  40149.    is output.  Before the 'stopped' annotation, a variety of annotations

  40150. describe how the program stopped.

  40151. 

  40152. '^Z^Zexited EXIT-STATUS'

  40153.      The program exited, and EXIT-STATUS is the exit status (zero for

  40154.      successful exit, otherwise nonzero).

  40155. 

  40156. '^Z^Zsignalled'

  40157.      The program exited with a signal.  After the '^Z^Zsignalled', the

  40158.      annotation continues:

  40159. 

  40160.           INTRO-TEXT

  40161.           ^Z^Zsignal-name

  40162.           NAME

  40163.           ^Z^Zsignal-name-end

  40164.           MIDDLE-TEXT

  40165.           ^Z^Zsignal-string

  40166.           STRING

  40167.           ^Z^Zsignal-string-end

  40168.           END-TEXT

  40169. 

  40170.      where NAME is the name of the signal, such as 'SIGILL' or

  40171.      'SIGSEGV', and STRING is the explanation of the signal, such as

  40172.      'Illegal Instruction' or 'Segmentation fault'.  The arguments

  40173.      INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit

  40174.      and have no particular format.

  40175. 

  40176. '^Z^Zsignal'

  40177.      The syntax of this annotation is just like 'signalled', but GDB is

  40178.      just saying that the program received the signal, not that it was

  40179.      terminated with it.

  40180. 

  40181. '^Z^Zbreakpoint NUMBER'

  40182.      The program hit breakpoint number NUMBER.

  40183. 

  40184. '^Z^Zwatchpoint NUMBER'

  40185.      The program hit watchpoint number NUMBER.

  40186. 

  40187. 

  40188. File: gdb.info,  Node: Source Annotations,  Prev: Annotations for Running,  Up: Annotations

  40189. 

  40190. 28.7 Displaying Source

  40191. ======================

  40192. 

  40193. The following annotation is used instead of displaying source code:

  40194. 

  40195.      ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR

  40196. 

  40197.    where FILENAME is an absolute file name indicating which source file,

  40198. LINE is the line number within that file (where 1 is the first line in

  40199. the file), CHARACTER is the character position within the file (where 0

  40200. is the first character in the file) (for most debug formats this will

  40201. necessarily point to the beginning of a line), MIDDLE is 'middle' if

  40202. ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning

  40203. of the line, and ADDR is the address in the target program associated

  40204. with the source which is being displayed.  The ADDR is in the form '0x'

  40205. followed by one or more lowercase hex digits (note that this does not

  40206. depend on the language).

  40207. 

  40208. 

  40209. File: gdb.info,  Node: JIT Interface,  Next: In-Process Agent,  Prev: Annotations,  Up: Top

  40210. 

  40211. 29 JIT Compilation Interface

  40212. ****************************

  40213. 

  40214. This chapter documents GDB's "just-in-time" (JIT) compilation interface.

  40215. A JIT compiler is a program or library that generates native executable

  40216. code at runtime and executes it, usually in order to achieve good

  40217. performance while maintaining platform independence.

  40218. 

  40219.    Programs that use JIT compilation are normally difficult to debug

  40220. because portions of their code are generated at runtime, instead of

  40221. being loaded from object files, which is where GDB normally finds the

  40222. program's symbols and debug information.  In order to debug programs

  40223. that use JIT compilation, GDB has an interface that allows the program

  40224. to register in-memory symbol files with GDB at runtime.

  40225. 

  40226.    If you are using GDB to debug a program that uses this interface,

  40227. then it should work transparently so long as you have not stripped the

  40228. binary.  If you are developing a JIT compiler, then the interface is

  40229. documented in the rest of this chapter.  At this time, the only known

  40230. client of this interface is the LLVM JIT.

  40231. 

  40232.    Broadly speaking, the JIT interface mirrors the dynamic loader

  40233. interface.  The JIT compiler communicates with GDB by writing data into

  40234. a global variable and calling a function at a well-known symbol.  When

  40235. GDB attaches, it reads a linked list of symbol files from the global

  40236. variable to find existing code, and puts a breakpoint in the function so

  40237. that it can find out about additional code.

  40238. 

  40239. * Menu:

  40240. 

  40241. * Declarations::                Relevant C struct declarations

  40242. * Registering Code::            Steps to register code

  40243. * Unregistering Code::          Steps to unregister code

  40244. * Custom Debug Info::           Emit debug information in a custom format

  40245. 

  40246. 

  40247. File: gdb.info,  Node: Declarations,  Next: Registering Code,  Up: JIT Interface

  40248. 

  40249. 29.1 JIT Declarations

  40250. =====================

  40251. 

  40252. These are the relevant struct declarations that a C program should

  40253. include to implement the interface:

  40254. 

  40255.      typedef enum

  40256.      {

  40257.        JIT_NOACTION = 0,

  40258.        JIT_REGISTER_FN,

  40259.        JIT_UNREGISTER_FN

  40260.      } jit_actions_t;

  40261. 

  40262.      struct jit_code_entry

  40263.      {

  40264.        struct jit_code_entry *next_entry;

  40265.        struct jit_code_entry *prev_entry;

  40266.        const char *symfile_addr;

  40267.        uint64_t symfile_size;

  40268.      };

  40269. 

  40270.      struct jit_descriptor

  40271.      {

  40272.        uint32_t version;

  40273.        /* This type should be jit_actions_t, but we use uint32_t

  40274.           to be explicit about the bitwidth.  */

  40275.        uint32_t action_flag;

  40276.        struct jit_code_entry *relevant_entry;

  40277.        struct jit_code_entry *first_entry;

  40278.      };

  40279. 

  40280.      /* GDB puts a breakpoint in this function.  */

  40281.      void __attribute__((noinline)) __jit_debug_register_code() { };

  40282. 

  40283.      /* Make sure to specify the version statically, because the

  40284.         debugger may check the version before we can set it.  */

  40285.      struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };

  40286. 

  40287.    If the JIT is multi-threaded, then it is important that the JIT

  40288. synchronize any modifications to this global data properly, which can

  40289. easily be done by putting a global mutex around modifications to these

  40290. structures.

  40291. 

  40292. 

  40293. File: gdb.info,  Node: Registering Code,  Next: Unregistering Code,  Prev: Declarations,  Up: JIT Interface

  40294. 

  40295. 29.2 Registering Code

  40296. =====================

  40297. 

  40298. To register code with GDB, the JIT should follow this protocol:

  40299. 

  40300.    * Generate an object file in memory with symbols and other desired

  40301.      debug information.  The file must include the virtual addresses of

  40302.      the sections.

  40303. 

  40304.    * Create a code entry for the file, which gives the start and size of

  40305.      the symbol file.

  40306. 

  40307.    * Add it to the linked list in the JIT descriptor.

  40308. 

  40309.    * Point the relevant_entry field of the descriptor at the entry.

  40310. 

  40311.    * Set 'action_flag' to 'JIT_REGISTER' and call

  40312.      '__jit_debug_register_code'.

  40313. 

  40314.    When GDB is attached and the breakpoint fires, GDB uses the

  40315. 'relevant_entry' pointer so it doesn't have to walk the list looking for

  40316. new code.  However, the linked list must still be maintained in order to

  40317. allow GDB to attach to a running process and still find the symbol

  40318. files.

  40319. 

  40320. 

  40321. File: gdb.info,  Node: Unregistering Code,  Next: Custom Debug Info,  Prev: Registering Code,  Up: JIT Interface

  40322. 

  40323. 29.3 Unregistering Code

  40324. =======================

  40325. 

  40326. If code is freed, then the JIT should use the following protocol:

  40327. 

  40328.    * Remove the code entry corresponding to the code from the linked

  40329.      list.

  40330. 

  40331.    * Point the 'relevant_entry' field of the descriptor at the code

  40332.      entry.

  40333. 

  40334.    * Set 'action_flag' to 'JIT_UNREGISTER' and call

  40335.      '__jit_debug_register_code'.

  40336. 

  40337.    If the JIT frees or recompiles code without unregistering it, then

  40338. GDB and the JIT will leak the memory used for the associated symbol

  40339. files.

  40340. 

  40341. 

  40342. File: gdb.info,  Node: Custom Debug Info,  Prev: Unregistering Code,  Up: JIT Interface

  40343. 

  40344. 29.4 Custom Debug Info

  40345. ======================

  40346. 

  40347. Generating debug information in platform-native file formats (like ELF

  40348. or COFF) may be an overkill for JIT compilers; especially if all the

  40349. debug info is used for is displaying a meaningful backtrace.  The issue

  40350. can be resolved by having the JIT writers decide on a debug info format

  40351. and also provide a reader that parses the debug info generated by the

  40352. JIT compiler.  This section gives a brief overview on writing such a

  40353. parser.  More specific details can be found in the source file

  40354. 'gdb/jit-reader.in', which is also installed as a header at

  40355. 'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.

  40356. 

  40357.    The reader is implemented as a shared object (so this functionality

  40358. is not available on platforms which don't allow loading shared objects

  40359. at runtime).  Two GDB commands, 'jit-reader-load' and

  40360. 'jit-reader-unload' are provided, to be used to load and unload the

  40361. readers from a preconfigured directory.  Once loaded, the shared object

  40362. is used the parse the debug information emitted by the JIT compiler.

  40363. 

  40364. * Menu:

  40365. 

  40366. * Using JIT Debug Info Readers::       How to use supplied readers correctly

  40367. * Writing JIT Debug Info Readers::     Creating a debug-info reader

  40368. 

  40369. 

  40370. File: gdb.info,  Node: Using JIT Debug Info Readers,  Next: Writing JIT Debug Info Readers,  Up: Custom Debug Info

  40371. 

  40372. 29.4.1 Using JIT Debug Info Readers

  40373. -----------------------------------

  40374. 

  40375. Readers can be loaded and unloaded using the 'jit-reader-load' and

  40376. 'jit-reader-unload' commands.

  40377. 

  40378. 'jit-reader-load READER'

  40379.      Load the JIT reader named READER, which is a shared object

  40380.      specified as either an absolute or a relative file name.  In the

  40381.      latter case, GDB will try to load the reader from a pre-configured

  40382.      directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is

  40383.      the system library directory, often '/usr/local/lib').

  40384. 

  40385.      Only one reader can be active at a time; trying to load a second

  40386.      reader when one is already loaded will result in GDB reporting an

  40387.      error.  A new JIT reader can be loaded by first unloading the

  40388.      current one using 'jit-reader-unload' and then invoking

  40389.      'jit-reader-load'.

  40390. 

  40391. 'jit-reader-unload'

  40392.      Unload the currently loaded JIT reader.

  40393. 

  40394. 

  40395. File: gdb.info,  Node: Writing JIT Debug Info Readers,  Prev: Using JIT Debug Info Readers,  Up: Custom Debug Info

  40396. 

  40397. 29.4.2 Writing JIT Debug Info Readers

  40398. -------------------------------------

  40399. 

  40400. As mentioned, a reader is essentially a shared object conforming to a

  40401. certain ABI. This ABI is described in 'jit-reader.h'.

  40402. 

  40403.    'jit-reader.h' defines the structures, macros and functions required

  40404. to write a reader.  It is installed (along with GDB), in

  40405. 'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.

  40406. 

  40407.    Readers need to be released under a GPL compatible license.  A reader

  40408. can be declared as released under such a license by placing the macro

  40409. 'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.

  40410. 

  40411.    The entry point for readers is the symbol 'gdb_init_reader', which is

  40412. expected to be a function with the prototype

  40413. 

  40414.      extern struct gdb_reader_funcs *gdb_init_reader (void);

  40415. 

  40416.    'struct gdb_reader_funcs' contains a set of pointers to callback

  40417. functions.  These functions are executed to read the debug info

  40418. generated by the JIT compiler ('read'), to unwind stack frames

  40419. ('unwind') and to create canonical frame IDs ('get_frame_id').  It also

  40420. has a callback that is called when the reader is being unloaded

  40421. ('destroy').  The struct looks like this

  40422. 

  40423.      struct gdb_reader_funcs

  40424.      {

  40425.        /* Must be set to GDB_READER_INTERFACE_VERSION.  */

  40426.        int reader_version;

  40427. 

  40428.        /* For use by the reader.  */

  40429.        void *priv_data;

  40430. 

  40431.        gdb_read_debug_info *read;

  40432.        gdb_unwind_frame *unwind;

  40433.        gdb_get_frame_id *get_frame_id;

  40434.        gdb_destroy_reader *destroy;

  40435.      };

  40436. 

  40437.    The callbacks are provided with another set of callbacks by GDB to do

  40438. their job.  For 'read', these callbacks are passed in a 'struct

  40439. gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct

  40440. gdb_unwind_callbacks'.  'struct gdb_symbol_callbacks' has callbacks to

  40441. create new object files and new symbol tables inside those object files.

  40442. 'struct gdb_unwind_callbacks' has callbacks to read registers off the

  40443. current frame and to write out the values of the registers in the

  40444. previous frame.  Both have a callback ('target_read') to read bytes off

  40445. the target's address space.

  40446. 

  40447. 

  40448. File: gdb.info,  Node: In-Process Agent,  Next: GDB Bugs,  Prev: JIT Interface,  Up: Top

  40449. 

  40450. 30 In-Process Agent

  40451. *******************

  40452. 

  40453. The traditional debugging model is conceptually low-speed, but works

  40454. fine, because most bugs can be reproduced in debugging-mode execution.

  40455. However, as multi-core or many-core processors are becoming mainstream,

  40456. and multi-threaded programs become more and more popular, there should

  40457. be more and more bugs that only manifest themselves at normal-mode

  40458. execution, for example, thread races, because debugger's interference

  40459. with the program's timing may conceal the bugs.  On the other hand, in

  40460. some applications, it is not feasible for the debugger to interrupt the

  40461. program's execution long enough for the developer to learn anything

  40462. helpful about its behavior.  If the program's correctness depends on its

  40463. real-time behavior, delays introduced by a debugger might cause the

  40464. program to fail, even when the code itself is correct.  It is useful to

  40465. be able to observe the program's behavior without interrupting it.

  40466. 

  40467.    Therefore, traditional debugging model is too intrusive to reproduce

  40468. some bugs.  In order to reduce the interference with the program, we can

  40469. reduce the number of operations performed by debugger.  The "In-Process

  40470. Agent", a shared library, is running within the same process with

  40471. inferior, and is able to perform some debugging operations itself.  As a

  40472. result, debugger is only involved when necessary, and performance of

  40473. debugging can be improved accordingly.  Note that interference with

  40474. program can be reduced but can't be removed completely, because the

  40475. in-process agent will still stop or slow down the program.

  40476. 

  40477.    The in-process agent can interpret and execute Agent Expressions

  40478. (*note Agent Expressions::) during performing debugging operations.  The

  40479. agent expressions can be used for different purposes, such as collecting

  40480. data in tracepoints, and condition evaluation in breakpoints.

  40481. 

  40482.    You can control whether the in-process agent is used as an aid for

  40483. debugging with the following commands:

  40484. 

  40485. 'set agent on'

  40486.      Causes the in-process agent to perform some operations on behalf of

  40487.      the debugger.  Just which operations requested by the user will be

  40488.      done by the in-process agent depends on the its capabilities.  For

  40489.      example, if you request to evaluate breakpoint conditions in the

  40490.      in-process agent, and the in-process agent has such capability as

  40491.      well, then breakpoint conditions will be evaluated in the

  40492.      in-process agent.

  40493. 

  40494. 'set agent off'

  40495.      Disables execution of debugging operations by the in-process agent.

  40496.      All of the operations will be performed by GDB.

  40497. 

  40498. 'show agent'

  40499.      Display the current setting of execution of debugging operations by

  40500.      the in-process agent.

  40501. 

  40502. * Menu:

  40503. 

  40504. * In-Process Agent Protocol::

  40505. 

  40506. 

  40507. File: gdb.info,  Node: In-Process Agent Protocol,  Up: In-Process Agent

  40508. 

  40509. 30.1 In-Process Agent Protocol

  40510. ==============================

  40511. 

  40512. The in-process agent is able to communicate with both GDB and GDBserver

  40513. (*note In-Process Agent::).  This section documents the protocol used

  40514. for communications between GDB or GDBserver and the IPA. In general, GDB

  40515. or GDBserver sends commands (*note IPA Protocol Commands::) and data to

  40516. in-process agent, and then in-process agent replies back with the return

  40517. result of the command, or some other information.  The data sent to

  40518. in-process agent is composed of primitive data types, such as 4-byte or

  40519. 8-byte type, and composite types, which are called objects (*note IPA

  40520. Protocol Objects::).

  40521. 

  40522. * Menu:

  40523. 

  40524. * IPA Protocol Objects::

  40525. * IPA Protocol Commands::

  40526. 

  40527. 

  40528. File: gdb.info,  Node: IPA Protocol Objects,  Next: IPA Protocol Commands,  Up: In-Process Agent Protocol

  40529. 

  40530. 30.1.1 IPA Protocol Objects

  40531. ---------------------------

  40532. 

  40533. The commands sent to and results received from agent may contain some

  40534. complex data types called "objects".

  40535. 

  40536.    The in-process agent is running on the same machine with GDB or

  40537. GDBserver, so it doesn't have to handle as much differences between two

  40538. ends as remote protocol (*note Remote Protocol::) tries to handle.

  40539. However, there are still some differences of two ends in two processes:

  40540. 

  40541.   1. word size.  On some 64-bit machines, GDB or GDBserver can be

  40542.      compiled as a 64-bit executable, while in-process agent is a 32-bit

  40543.      one.

  40544.   2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver

  40545.      is compiled with one, and in-process agent is compiled with the

  40546.      other one.

  40547. 

  40548.    Here are the IPA Protocol Objects:

  40549. 

  40550.   1. agent expression object.  It represents an agent expression (*note

  40551.      Agent Expressions::).

  40552.   2. tracepoint action object.  It represents a tracepoint action (*note

  40553.      Tracepoint Action Lists: Tracepoint Actions.) to collect registers,

  40554.      memory, static trace data and to evaluate expression.

  40555.   3. tracepoint object.  It represents a tracepoint (*note

  40556.      Tracepoints::).

  40557. 

  40558.    The following table describes important attributes of each IPA

  40559. protocol object:

  40560. 

  40561. Name                   Size           Description

  40562. ---------------------------------------------------------------------------

  40563. _agent expression

  40564. object_

  40565. length                 4              length of bytes code

  40566. byte code              LENGTH         contents of byte code

  40567. _tracepoint action

  40568. for collecting

  40569. memory_

  40570. 'M'                    1              type of tracepoint action

  40571. addr                   8              if BASEREG is '-1', ADDR is the

  40572.                                       address of the lowest byte to

  40573.                                       collect, otherwise ADDR is the

  40574.                                       offset of BASEREG for memory

  40575.                                       collecting.

  40576. len                    8              length of memory for collecting

  40577. basereg                4              the register number containing the

  40578.                                       starting memory address for

  40579.                                       collecting.

  40580. _tracepoint action

  40581. for collecting

  40582. registers_

  40583. 'R'                    1              type of tracepoint action

  40584. _tracepoint action

  40585. for collecting

  40586. static trace data_

  40587. 'L'                    1              type of tracepoint action

  40588. _tracepoint action

  40589. for expression

  40590. evaluation_

  40591. 'X'                    1              type of tracepoint action

  40592. agent expression       length of      *note agent expression object::

  40593. _tracepoint object_

  40594. number                 4              number of tracepoint

  40595. address                8              address of tracepoint inserted on

  40596. type                   4              type of tracepoint

  40597. enabled                1              enable or disable of tracepoint

  40598. step_count             8              step

  40599. pass_count             8              pass

  40600. numactions             4              number of tracepoint actions

  40601. hit count              8              hit count

  40602. trace frame usage      8              trace frame usage

  40603. compiled_cond          8              compiled condition

  40604. orig_size              8              orig size

  40605. condition              4 if           zero if condition is NULL,

  40606.                        condition is   otherwise is

  40607.                        NULL           *note agent expression object::

  40608.                        otherwise

  40609.                        length of

  40610.                        *note agent expression object::

  40611. actions                variable       numactions number of

  40612.                                       *note tracepoint action object::

  40613. 

  40614. 

  40615. File: gdb.info,  Node: IPA Protocol Commands,  Prev: IPA Protocol Objects,  Up: In-Process Agent Protocol

  40616. 

  40617. 30.1.2 IPA Protocol Commands

  40618. ----------------------------

  40619. 

  40620. The spaces in each command are delimiters to ease reading this commands

  40621. specification.  They don't exist in real commands.

  40622. 

  40623. 'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'

  40624.      Installs a new fast tracepoint described by TRACEPOINT_OBJECT

  40625.      (*note tracepoint object::).  The GDB_JUMP_PAD_HEAD, 8-byte long,

  40626.      is the head of "jumppad", which is used to jump to data collection

  40627.      routine in IPA finally.

  40628. 

  40629.      Replies:

  40630.      'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'

  40631.           TARGET_ADDRESS is address of tracepoint in the inferior.  The

  40632.           GDB_JUMP_PAD_HEAD is updated head of jumppad.  Both of

  40633.           TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long.  The

  40634.           FJUMP contains a sequence of instructions jump to jumppad

  40635.           entry.  The FJUMP_SIZE, 4-byte long, is the size of FJUMP.

  40636.      'E NN'

  40637.           for an error

  40638. 

  40639. 'close'

  40640.      Closes the in-process agent.  This command is sent when GDB or

  40641.      GDBserver is about to kill inferiors.

  40642. 

  40643. 'qTfSTM'

  40644.      *Note qTfSTM::.

  40645. 'qTsSTM'

  40646.      *Note qTsSTM::.

  40647. 'qTSTMat'

  40648.      *Note qTSTMat::.

  40649. 'probe_marker_at:ADDRESS'

  40650.      Asks in-process agent to probe the marker at ADDRESS.

  40651. 

  40652.      Replies:

  40653.      'E NN'

  40654.           for an error

  40655. 'unprobe_marker_at:ADDRESS'

  40656.      Asks in-process agent to unprobe the marker at ADDRESS.

  40657. 

  40658. 

  40659. File: gdb.info,  Node: GDB Bugs,  Next: Command Line Editing,  Prev: In-Process Agent,  Up: Top

  40660. 

  40661. 31 Reporting Bugs in GDB

  40662. ************************

  40663. 

  40664. Your bug reports play an essential role in making GDB reliable.

  40665. 

  40666.    Reporting a bug may help you by bringing a solution to your problem,

  40667. or it may not.  But in any case the principal function of a bug report

  40668. is to help the entire community by making the next version of GDB work

  40669. better.  Bug reports are your contribution to the maintenance of GDB.

  40670. 

  40671.    In order for a bug report to serve its purpose, you must include the

  40672. information that enables us to fix the bug.

  40673. 

  40674. * Menu:

  40675. 

  40676. * Bug Criteria::                Have you found a bug?

  40677. * Bug Reporting::               How to report bugs

  40678. 

  40679. 

  40680. File: gdb.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: GDB Bugs

  40681. 

  40682. 31.1 Have You Found a Bug?

  40683. ==========================

  40684. 

  40685. If you are not sure whether you have found a bug, here are some

  40686. guidelines:

  40687. 

  40688.    * If the debugger gets a fatal signal, for any input whatever, that

  40689.      is a GDB bug.  Reliable debuggers never crash.

  40690. 

  40691.    * If GDB produces an error message for valid input, that is a bug.

  40692.      (Note that if you're cross debugging, the problem may also be

  40693.      somewhere in the connection to the target.)

  40694. 

  40695.    * If GDB does not produce an error message for invalid input, that is

  40696.      a bug.  However, you should note that your idea of "invalid input"

  40697.      might be our idea of "an extension" or "support for traditional

  40698.      practice".

  40699. 

  40700.    * If you are an experienced user of debugging tools, your suggestions

  40701.      for improvement of GDB are welcome in any case.

  40702. 

  40703. 

  40704. File: gdb.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: GDB Bugs

  40705. 

  40706. 31.2 How to Report Bugs

  40707. =======================

  40708. 

  40709. A number of companies and individuals offer support for GNU products.

  40710. If you obtained GDB from a support organization, we recommend you

  40711. contact that organization first.

  40712. 

  40713.    You can find contact information for many support companies and

  40714. individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.

  40715. 

  40716.    In any event, we also recommend that you submit bug reports for GDB

  40717. to <https://www.gnu.org/software/gdb/bugs/>.

  40718. 

  40719.    The fundamental principle of reporting bugs usefully is this: *report

  40720. all the facts*.  If you are not sure whether to state a fact or leave it

  40721. out, state it!

  40722. 

  40723.    Often people omit facts because they think they know what causes the

  40724. problem and assume that some details do not matter.  Thus, you might

  40725. assume that the name of the variable you use in an example does not

  40726. matter.  Well, probably it does not, but one cannot be sure.  Perhaps

  40727. the bug is a stray memory reference which happens to fetch from the

  40728. location where that name is stored in memory; perhaps, if the name were

  40729. different, the contents of that location would fool the debugger into

  40730. doing the right thing despite the bug.  Play it safe and give a

  40731. specific, complete example.  That is the easiest thing for you to do,

  40732. and the most helpful.

  40733. 

  40734.    Keep in mind that the purpose of a bug report is to enable us to fix

  40735. the bug.  It may be that the bug has been reported previously, but

  40736. neither you nor we can know that unless your bug report is complete and

  40737. self-contained.

  40738. 

  40739.    Sometimes people give a few sketchy facts and ask, "Does this ring a

  40740. bell?"  Those bug reports are useless, and we urge everyone to _refuse

  40741. to respond to them_ except to chide the sender to report bugs properly.

  40742. 

  40743.    To enable us to fix the bug, you should include all these things:

  40744. 

  40745.    * The version of GDB.  GDB announces it if you start with no

  40746.      arguments; you can also print it at any time using 'show version'.

  40747. 

  40748.      Without this, we will not know whether there is any point in

  40749.      looking for the bug in the current version of GDB.

  40750. 

  40751.    * The type of machine you are using, and the operating system name

  40752.      and version number.

  40753. 

  40754.    * The details of the GDB build-time configuration.  GDB shows these

  40755.      details if you invoke it with the '--configuration' command-line

  40756.      option, or if you type 'show configuration' at GDB's prompt.

  40757. 

  40758.    * What compiler (and its version) was used to compile GDB--e.g.

  40759.      "gcc-2.8.1".

  40760. 

  40761.    * What compiler (and its version) was used to compile the program you

  40762.      are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C

  40763.      Compiler".  For GCC, you can say 'gcc --version' to get this

  40764.      information; for other compilers, see the documentation for those

  40765.      compilers.

  40766. 

  40767.    * The command arguments you gave the compiler to compile your example

  40768.      and observe the bug.  For example, did you use '-O'?  To guarantee

  40769.      you will not omit something important, list them all.  A copy of

  40770.      the Makefile (or the output from make) is sufficient.

  40771. 

  40772.      If we were to try to guess the arguments, we would probably guess

  40773.      wrong and then we might not encounter the bug.

  40774. 

  40775.    * A complete input script, and all necessary source files, that will

  40776.      reproduce the bug.

  40777. 

  40778.    * A description of what behavior you observe that you believe is

  40779.      incorrect.  For example, "It gets a fatal signal."

  40780. 

  40781.      Of course, if the bug is that GDB gets a fatal signal, then we will

  40782.      certainly notice it.  But if the bug is incorrect output, we might

  40783.      not notice unless it is glaringly wrong.  You might as well not

  40784.      give us a chance to make a mistake.

  40785. 

  40786.      Even if the problem you experience is a fatal signal, you should

  40787.      still say so explicitly.  Suppose something strange is going on,

  40788.      such as, your copy of GDB is out of synch, or you have encountered

  40789.      a bug in the C library on your system.  (This has happened!)  Your

  40790.      copy might crash and ours would not.  If you told us to expect a

  40791.      crash, then when ours fails to crash, we would know that the bug

  40792.      was not happening for us.  If you had not told us to expect a

  40793.      crash, then we would not be able to draw any conclusion from our

  40794.      observations.

  40795. 

  40796.      To collect all this information, you can use a session recording

  40797.      program such as 'script', which is available on many Unix systems.

  40798.      Just run your GDB session inside 'script' and then include the

  40799.      'typescript' file with your bug report.

  40800. 

  40801.      Another way to record a GDB session is to run GDB inside Emacs and

  40802.      then save the entire buffer to a file.

  40803. 

  40804.    * If you wish to suggest changes to the GDB source, send us context

  40805.      diffs.  If you even discuss something in the GDB source, refer to

  40806.      it by context, not by line number.

  40807. 

  40808.      The line numbers in our development sources will not match those in

  40809.      your sources.  Your line numbers would convey no useful information

  40810.      to us.

  40811. 

  40812.    Here are some things that are not necessary:

  40813. 

  40814.    * A description of the envelope of the bug.

  40815. 

  40816.      Often people who encounter a bug spend a lot of time investigating

  40817.      which changes to the input file will make the bug go away and which

  40818.      changes will not affect it.

  40819. 

  40820.      This is often time consuming and not very useful, because the way

  40821.      we will find the bug is by running a single example under the

  40822.      debugger with breakpoints, not by pure deduction from a series of

  40823.      examples.  We recommend that you save your time for something else.

  40824. 

  40825.      Of course, if you can find a simpler example to report _instead_ of

  40826.      the original one, that is a convenience for us.  Errors in the

  40827.      output will be easier to spot, running under the debugger will take

  40828.      less time, and so on.

  40829. 

  40830.      However, simplification is not vital; if you do not want to do

  40831.      this, report the bug anyway and send us the entire test case you

  40832.      used.

  40833. 

  40834.    * A patch for the bug.

  40835. 

  40836.      A patch for the bug does help us if it is a good one.  But do not

  40837.      omit the necessary information, such as the test case, on the

  40838.      assumption that a patch is all we need.  We might see problems with

  40839.      your patch and decide to fix the problem another way, or we might

  40840.      not understand it at all.

  40841. 

  40842.      Sometimes with a program as complicated as GDB it is very hard to

  40843.      construct an example that will make the program follow a certain

  40844.      path through the code.  If you do not send us the example, we will

  40845.      not be able to construct one, so we will not be able to verify that

  40846.      the bug is fixed.

  40847. 

  40848.      And if we cannot understand what bug you are trying to fix, or why

  40849.      your patch should be an improvement, we will not install it.  A

  40850.      test case will help us to understand.

  40851. 

  40852.    * A guess about what the bug is or what it depends on.

  40853. 

  40854.      Such guesses are usually wrong.  Even we cannot guess right about

  40855.      such things without first using the debugger to find the facts.

  40856. 

  40857. 

  40858. File: gdb.info,  Node: Command Line Editing,  Next: Using History Interactively,  Prev: GDB Bugs,  Up: Top

  40859. 

  40860. 32 Command Line Editing

  40861. ***********************

  40862. 

  40863. This chapter describes the basic features of the GNU command line

  40864. editing interface.

  40865. 

  40866. * Menu:

  40867. 

  40868. * Introduction and Notation::	Notation used in this text.

  40869. * Readline Interaction::	The minimum set of commands for editing a line.

  40870. * Readline Init File::		Customizing Readline from a user's view.

  40871. * Bindable Readline Commands::	A description of most of the Readline commands

  40872. 				available for binding

  40873. * Readline vi Mode::		A short description of how to make Readline

  40874. 				behave like the vi editor.

  40875. 

  40876. 

  40877. File: gdb.info,  Node: Introduction and Notation,  Next: Readline Interaction,  Up: Command Line Editing

  40878. 

  40879. 32.1 Introduction to Line Editing

  40880. =================================

  40881. 

  40882. The following paragraphs describe the notation used to represent

  40883. keystrokes.

  40884. 

  40885.    The text 'C-k' is read as 'Control-K' and describes the character

  40886. produced when the <k> key is pressed while the Control key is depressed.

  40887. 

  40888.    The text 'M-k' is read as 'Meta-K' and describes the character

  40889. produced when the Meta key (if you have one) is depressed, and the <k>

  40890. key is pressed.  The Meta key is labeled <ALT> on many keyboards.  On

  40891. keyboards with two keys labeled <ALT> (usually to either side of the

  40892. space bar), the <ALT> on the left side is generally set to work as a

  40893. Meta key.  The <ALT> key on the right may also be configured to work as

  40894. a Meta key or may be configured as some other modifier, such as a

  40895. Compose key for typing accented characters.

  40896. 

  40897.    If you do not have a Meta or <ALT> key, or another key working as a

  40898. Meta key, the identical keystroke can be generated by typing <ESC>

  40899. _first_, and then typing <k>.  Either process is known as "metafying"

  40900. the <k> key.

  40901. 

  40902.    The text 'M-C-k' is read as 'Meta-Control-k' and describes the

  40903. character produced by "metafying" 'C-k'.

  40904. 

  40905.    In addition, several keys have their own names.  Specifically, <DEL>,

  40906. <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen

  40907. in this text, or in an init file (*note Readline Init File::).  If your

  40908. keyboard lacks a <LFD> key, typing <C-j> will produce the desired

  40909. character.  The <RET> key may be labeled <Return> or <Enter> on some

  40910. keyboards.

  40911. 

  40912. 

  40913. File: gdb.info,  Node: Readline Interaction,  Next: Readline Init File,  Prev: Introduction and Notation,  Up: Command Line Editing

  40914. 

  40915. 32.2 Readline Interaction

  40916. =========================

  40917. 

  40918. Often during an interactive session you type in a long line of text,

  40919. only to notice that the first word on the line is misspelled.  The

  40920. Readline library gives you a set of commands for manipulating the text

  40921. as you type it in, allowing you to just fix your typo, and not forcing

  40922. you to retype the majority of the line.  Using these editing commands,

  40923. you move the cursor to the place that needs correction, and delete or

  40924. insert the text of the corrections.  Then, when you are satisfied with

  40925. the line, you simply press <RET>.  You do not have to be at the end of

  40926. the line to press <RET>; the entire line is accepted regardless of the

  40927. location of the cursor within the line.

  40928. 

  40929. * Menu:

  40930. 

  40931. * Readline Bare Essentials::	The least you need to know about Readline.

  40932. * Readline Movement Commands::	Moving about the input line.

  40933. * Readline Killing Commands::	How to delete text, and how to get it back!

  40934. * Readline Arguments::		Giving numeric arguments to commands.

  40935. * Searching::			Searching through previous lines.

  40936. 

  40937. 

  40938. File: gdb.info,  Node: Readline Bare Essentials,  Next: Readline Movement Commands,  Up: Readline Interaction

  40939. 

  40940. 32.2.1 Readline Bare Essentials

  40941. -------------------------------

  40942. 

  40943. In order to enter characters into the line, simply type them.  The typed

  40944. character appears where the cursor was, and then the cursor moves one

  40945. space to the right.  If you mistype a character, you can use your erase

  40946. character to back up and delete the mistyped character.

  40947. 

  40948.    Sometimes you may mistype a character, and not notice the error until

  40949. you have typed several other characters.  In that case, you can type

  40950. 'C-b' to move the cursor to the left, and then correct your mistake.

  40951. Afterwards, you can move the cursor to the right with 'C-f'.

  40952. 

  40953.    When you add text in the middle of a line, you will notice that

  40954. characters to the right of the cursor are 'pushed over' to make room for

  40955. the text that you have inserted.  Likewise, when you delete text behind

  40956. the cursor, characters to the right of the cursor are 'pulled back' to

  40957. fill in the blank space created by the removal of the text.  A list of

  40958. the bare essentials for editing the text of an input line follows.

  40959. 

  40960. 'C-b'

  40961.      Move back one character.

  40962. 'C-f'

  40963.      Move forward one character.

  40964. <DEL> or <Backspace>

  40965.      Delete the character to the left of the cursor.

  40966. 'C-d'

  40967.      Delete the character underneath the cursor.

  40968. Printing characters

  40969.      Insert the character into the line at the cursor.

  40970. 'C-_' or 'C-x C-u'

  40971.      Undo the last editing command.  You can undo all the way back to an

  40972.      empty line.

  40973. 

  40974. (Depending on your configuration, the <Backspace> key be set to delete

  40975. the character to the left of the cursor and the <DEL> key set to delete

  40976. the character underneath the cursor, like 'C-d', rather than the

  40977. character to the left of the cursor.)

  40978. 

  40979. 

  40980. File: gdb.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction

  40981. 

  40982. 32.2.2 Readline Movement Commands

  40983. ---------------------------------

  40984. 

  40985. The above table describes the most basic keystrokes that you need in

  40986. order to do editing of the input line.  For your convenience, many other

  40987. commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>.

  40988. Here are some commands for moving more rapidly about the line.

  40989. 

  40990. 'C-a'

  40991.      Move to the start of the line.

  40992. 'C-e'

  40993.      Move to the end of the line.

  40994. 'M-f'

  40995.      Move forward a word, where a word is composed of letters and

  40996.      digits.

  40997. 'M-b'

  40998.      Move backward a word.

  40999. 'C-l'

  41000.      Clear the screen, reprinting the current line at the top.

  41001. 

  41002.    Notice how 'C-f' moves forward a character, while 'M-f' moves forward

  41003. a word.  It is a loose convention that control keystrokes operate on

  41004. characters while meta keystrokes operate on words.

  41005. 

  41006. 

  41007. File: gdb.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction

  41008. 

  41009. 32.2.3 Readline Killing Commands

  41010. --------------------------------

  41011. 

  41012. "Killing" text means to delete the text from the line, but to save it

  41013. away for later use, usually by "yanking" (re-inserting) it back into the

  41014. line.  ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.)

  41015. 

  41016.    If the description for a command says that it 'kills' text, then you

  41017. can be sure that you can get the text back in a different (or the same)

  41018. place later.

  41019. 

  41020.    When you use a kill command, the text is saved in a "kill-ring".  Any

  41021. number of consecutive kills save all of the killed text together, so

  41022. that when you yank it back, you get it all.  The kill ring is not line

  41023. specific; the text that you killed on a previously typed line is

  41024. available to be yanked back later, when you are typing another line.

  41025. 

  41026.    Here is the list of commands for killing text.

  41027. 

  41028. 'C-k'

  41029.      Kill the text from the current cursor position to the end of the

  41030.      line.

  41031. 

  41032. 'M-d'

  41033.      Kill from the cursor to the end of the current word, or, if between

  41034.      words, to the end of the next word.  Word boundaries are the same

  41035.      as those used by 'M-f'.

  41036. 

  41037. 'M-<DEL>'

  41038.      Kill from the cursor the start of the current word, or, if between

  41039.      words, to the start of the previous word.  Word boundaries are the

  41040.      same as those used by 'M-b'.

  41041. 

  41042. 'C-w'

  41043.      Kill from the cursor to the previous whitespace.  This is different

  41044.      than 'M-<DEL>' because the word boundaries differ.

  41045. 

  41046.    Here is how to "yank" the text back into the line.  Yanking means to

  41047. copy the most-recently-killed text from the kill buffer.

  41048. 

  41049. 'C-y'

  41050.      Yank the most recently killed text back into the buffer at the

  41051.      cursor.

  41052. 

  41053. 'M-y'

  41054.      Rotate the kill-ring, and yank the new top.  You can only do this

  41055.      if the prior command is 'C-y' or 'M-y'.

  41056. 

  41057. 

  41058. File: gdb.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction

  41059. 

  41060. 32.2.4 Readline Arguments

  41061. -------------------------

  41062. 

  41063. You can pass numeric arguments to Readline commands.  Sometimes the

  41064. argument acts as a repeat count, other times it is the sign of the

  41065. argument that is significant.  If you pass a negative argument to a

  41066. command which normally acts in a forward direction, that command will

  41067. act in a backward direction.  For example, to kill text back to the

  41068. start of the line, you might type 'M-- C-k'.

  41069. 

  41070.    The general way to pass numeric arguments to a command is to type

  41071. meta digits before the command.  If the first 'digit' typed is a minus

  41072. sign ('-'), then the sign of the argument will be negative.  Once you

  41073. have typed one meta digit to get the argument started, you can type the

  41074. remainder of the digits, and then the command.  For example, to give the

  41075. 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will

  41076. delete the next ten characters on the input line.

  41077. 

  41078. 

  41079. File: gdb.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction

  41080. 

  41081. 32.2.5 Searching for Commands in the History

  41082. --------------------------------------------

  41083. 

  41084. Readline provides commands for searching through the command history for

  41085. lines containing a specified string.  There are two search modes:

  41086. "incremental" and "non-incremental".

  41087. 

  41088.    Incremental searches begin before the user has finished typing the

  41089. search string.  As each character of the search string is typed,

  41090. Readline displays the next entry from the history matching the string

  41091. typed so far.  An incremental search requires only as many characters as

  41092. needed to find the desired history entry.  To search backward in the

  41093. history for a particular string, type 'C-r'.  Typing 'C-s' searches

  41094. forward through the history.  The characters present in the value of the

  41095. 'isearch-terminators' variable are used to terminate an incremental

  41096. search.  If that variable has not been assigned a value, the <ESC> and

  41097. 'C-J' characters will terminate an incremental search.  'C-g' will abort

  41098. an incremental search and restore the original line.  When the search is

  41099. terminated, the history entry containing the search string becomes the

  41100. current line.

  41101. 

  41102.    To find other matching entries in the history list, type 'C-r' or

  41103. 'C-s' as appropriate.  This will search backward or forward in the

  41104. history for the next entry matching the search string typed so far.  Any

  41105. other key sequence bound to a Readline command will terminate the search

  41106. and execute that command.  For instance, a <RET> will terminate the

  41107. search and accept the line, thereby executing the command from the

  41108. history list.  A movement command will terminate the search, make the

  41109. last line found the current line, and begin editing.

  41110. 

  41111.    Readline remembers the last incremental search string.  If two 'C-r's

  41112. are typed without any intervening characters defining a new search

  41113. string, any remembered search string is used.

  41114. 

  41115.    Non-incremental searches read the entire search string before

  41116. starting to search for matching history lines.  The search string may be

  41117. typed by the user or be part of the contents of the current line.

  41118. 

  41119. 

  41120. File: gdb.info,  Node: Readline Init File,  Next: Bindable Readline Commands,  Prev: Readline Interaction,  Up: Command Line Editing

  41121. 

  41122. 32.3 Readline Init File

  41123. =======================

  41124. 

  41125. Although the Readline library comes with a set of Emacs-like keybindings

  41126. installed by default, it is possible to use a different set of

  41127. keybindings.  Any user can customize programs that use Readline by

  41128. putting commands in an "inputrc" file, conventionally in his home

  41129. directory.  The name of this file is taken from the value of the

  41130. environment variable 'INPUTRC'.  If that variable is unset, the default

  41131. is '~/.inputrc'.  If that file does not exist or cannot be read, the

  41132. ultimate default is '/etc/inputrc'.

  41133. 

  41134.    When a program which uses the Readline library starts up, the init

  41135. file is read, and the key bindings are set.

  41136. 

  41137.    In addition, the 'C-x C-r' command re-reads this init file, thus

  41138. incorporating any changes that you might have made to it.

  41139. 

  41140. * Menu:

  41141. 

  41142. * Readline Init File Syntax::	Syntax for the commands in the inputrc file.

  41143. 

  41144. * Conditional Init Constructs::	Conditional key bindings in the inputrc file.

  41145. 

  41146. * Sample Init File::		An example inputrc file.

  41147. 

  41148. 

  41149. File: gdb.info,  Node: Readline Init File Syntax,  Next: Conditional Init Constructs,  Up: Readline Init File

  41150. 

  41151. 32.3.1 Readline Init File Syntax

  41152. --------------------------------

  41153. 

  41154. There are only a few basic constructs allowed in the Readline init file.

  41155. Blank lines are ignored.  Lines beginning with a '#' are comments.

  41156. Lines beginning with a '$' indicate conditional constructs (*note

  41157. Conditional Init Constructs::).  Other lines denote variable settings

  41158. and key bindings.

  41159. 

  41160. Variable Settings

  41161.      You can modify the run-time behavior of Readline by altering the

  41162.      values of variables in Readline using the 'set' command within the

  41163.      init file.  The syntax is simple:

  41164. 

  41165.           set VARIABLE VALUE

  41166. 

  41167.      Here, for example, is how to change from the default Emacs-like key

  41168.      binding to use 'vi' line editing commands:

  41169. 

  41170.           set editing-mode vi

  41171. 

  41172.      Variable names and values, where appropriate, are recognized

  41173.      without regard to case.  Unrecognized variable names are ignored.

  41174. 

  41175.      Boolean variables (those that can be set to on or off) are set to

  41176.      on if the value is null or empty, ON (case-insensitive), or 1.  Any

  41177.      other value results in the variable being set to off.

  41178. 

  41179.      A great deal of run-time behavior is changeable with the following

  41180.      variables.

  41181. 

  41182.      'bell-style'

  41183.           Controls what happens when Readline wants to ring the terminal

  41184.           bell.  If set to 'none', Readline never rings the bell.  If

  41185.           set to 'visible', Readline uses a visible bell if one is

  41186.           available.  If set to 'audible' (the default), Readline

  41187.           attempts to ring the terminal's bell.

  41188. 

  41189.      'bind-tty-special-chars'

  41190.           If set to 'on' (the default), Readline attempts to bind the

  41191.           control characters treated specially by the kernel's terminal

  41192.           driver to their Readline equivalents.

  41193. 

  41194.      'blink-matching-paren'

  41195.           If set to 'on', Readline attempts to briefly move the cursor

  41196.           to an opening parenthesis when a closing parenthesis is

  41197.           inserted.  The default is 'off'.

  41198. 

  41199.      'colored-completion-prefix'

  41200.           If set to 'on', when listing completions, Readline displays

  41201.           the common prefix of the set of possible completions using a

  41202.           different color.  The color definitions are taken from the

  41203.           value of the 'LS_COLORS' environment variable.  The default is

  41204.           'off'.

  41205. 

  41206.      'colored-stats'

  41207.           If set to 'on', Readline displays possible completions using

  41208.           different colors to indicate their file type.  The color

  41209.           definitions are taken from the value of the 'LS_COLORS'

  41210.           environment variable.  The default is 'off'.

  41211. 

  41212.      'comment-begin'

  41213.           The string to insert at the beginning of the line when the

  41214.           'insert-comment' command is executed.  The default value is

  41215.           '"#"'.

  41216. 

  41217.      'completion-display-width'

  41218.           The number of screen columns used to display possible matches

  41219.           when performing completion.  The value is ignored if it is

  41220.           less than 0 or greater than the terminal screen width.  A

  41221.           value of 0 will cause matches to be displayed one per line.

  41222.           The default value is -1.

  41223. 

  41224.      'completion-ignore-case'

  41225.           If set to 'on', Readline performs filename matching and

  41226.           completion in a case-insensitive fashion.  The default value

  41227.           is 'off'.

  41228. 

  41229.      'completion-map-case'

  41230.           If set to 'on', and COMPLETION-IGNORE-CASE is enabled,

  41231.           Readline treats hyphens ('-') and underscores ('_') as

  41232.           equivalent when performing case-insensitive filename matching

  41233.           and completion.  The default value is 'off'.

  41234. 

  41235.      'completion-prefix-display-length'

  41236.           The length in characters of the common prefix of a list of

  41237.           possible completions that is displayed without modification.

  41238.           When set to a value greater than zero, common prefixes longer

  41239.           than this value are replaced with an ellipsis when displaying

  41240.           possible completions.

  41241. 

  41242.      'completion-query-items'

  41243.           The number of possible completions that determines when the

  41244.           user is asked whether the list of possibilities should be

  41245.           displayed.  If the number of possible completions is greater

  41246.           than this value, Readline will ask the user whether or not he

  41247.           wishes to view them; otherwise, they are simply listed.  This

  41248.           variable must be set to an integer value greater than or equal

  41249.           to 0.  A negative value means Readline should never ask.  The

  41250.           default limit is '100'.

  41251. 

  41252.      'convert-meta'

  41253.           If set to 'on', Readline will convert characters with the

  41254.           eighth bit set to an ASCII key sequence by stripping the

  41255.           eighth bit and prefixing an <ESC> character, converting them

  41256.           to a meta-prefixed key sequence.  The default value is 'on',

  41257.           but will be set to 'off' if the locale is one that contains

  41258.           eight-bit characters.

  41259. 

  41260.      'disable-completion'

  41261.           If set to 'On', Readline will inhibit word completion.

  41262.           Completion characters will be inserted into the line as if

  41263.           they had been mapped to 'self-insert'.  The default is 'off'.

  41264. 

  41265.      'echo-control-characters'

  41266.           When set to 'on', on operating systems that indicate they

  41267.           support it, readline echoes a character corresponding to a

  41268.           signal generated from the keyboard.  The default is 'on'.

  41269. 

  41270.      'editing-mode'

  41271.           The 'editing-mode' variable controls which default set of key

  41272.           bindings is used.  By default, Readline starts up in Emacs

  41273.           editing mode, where the keystrokes are most similar to Emacs.

  41274.           This variable can be set to either 'emacs' or 'vi'.

  41275. 

  41276.      'emacs-mode-string'

  41277.           If the SHOW-MODE-IN-PROMPT variable is enabled, this string is

  41278.           displayed immediately before the last line of the primary

  41279.           prompt when emacs editing mode is active.  The value is

  41280.           expanded like a key binding, so the standard set of meta- and

  41281.           control prefixes and backslash escape sequences is available.

  41282.           Use the '\1' and '\2' escapes to begin and end sequences of

  41283.           non-printing characters, which can be used to embed a terminal

  41284.           control sequence into the mode string.  The default is '@'.

  41285. 

  41286.      'enable-bracketed-paste'

  41287.           When set to 'On', Readline will configure the terminal in a

  41288.           way that will enable it to insert each paste into the editing

  41289.           buffer as a single string of characters, instead of treating

  41290.           each character as if it had been read from the keyboard.  This

  41291.           can prevent pasted characters from being interpreted as

  41292.           editing commands.  The default is 'off'.

  41293. 

  41294.      'enable-keypad'

  41295.           When set to 'on', Readline will try to enable the application

  41296.           keypad when it is called.  Some systems need this to enable

  41297.           the arrow keys.  The default is 'off'.

  41298. 

  41299.      'enable-meta-key'

  41300.           When set to 'on', Readline will try to enable any meta

  41301.           modifier key the terminal claims to support when it is called.

  41302.           On many terminals, the meta key is used to send eight-bit

  41303.           characters.  The default is 'on'.

  41304. 

  41305.      'expand-tilde'

  41306.           If set to 'on', tilde expansion is performed when Readline

  41307.           attempts word completion.  The default is 'off'.

  41308. 

  41309.      'history-preserve-point'

  41310.           If set to 'on', the history code attempts to place the point

  41311.           (the current cursor position) at the same location on each

  41312.           history line retrieved with 'previous-history' or

  41313.           'next-history'.  The default is 'off'.

  41314. 

  41315.      'history-size'

  41316.           Set the maximum number of history entries saved in the history

  41317.           list.  If set to zero, any existing history entries are

  41318.           deleted and no new entries are saved.  If set to a value less

  41319.           than zero, the number of history entries is not limited.  By

  41320.           default, the number of history entries is not limited.  If an

  41321.           attempt is made to set HISTORY-SIZE to a non-numeric value,

  41322.           the maximum number of history entries will be set to 500.

  41323. 

  41324.      'horizontal-scroll-mode'

  41325.           This variable can be set to either 'on' or 'off'.  Setting it

  41326.           to 'on' means that the text of the lines being edited will

  41327.           scroll horizontally on a single screen line when they are

  41328.           longer than the width of the screen, instead of wrapping onto

  41329.           a new screen line.  By default, this variable is set to 'off'.

  41330. 

  41331.      'input-meta'

  41332.           If set to 'on', Readline will enable eight-bit input (it will

  41333.           not clear the eighth bit in the characters it reads),

  41334.           regardless of what the terminal claims it can support.  The

  41335.           default value is 'off', but Readline will set it to 'on' if

  41336.           the locale contains eight-bit characters.  The name

  41337.           'meta-flag' is a synonym for this variable.

  41338. 

  41339.      'isearch-terminators'

  41340.           The string of characters that should terminate an incremental

  41341.           search without subsequently executing the character as a

  41342.           command (*note Searching::).  If this variable has not been

  41343.           given a value, the characters <ESC> and 'C-J' will terminate

  41344.           an incremental search.

  41345. 

  41346.      'keymap'

  41347.           Sets Readline's idea of the current keymap for key binding

  41348.           commands.  Built-in 'keymap' names are 'emacs',

  41349.           'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',

  41350.           'vi-command', and 'vi-insert'.  'vi' is equivalent to

  41351.           'vi-command' ('vi-move' is also a synonym); 'emacs' is

  41352.           equivalent to 'emacs-standard'.  Applications may add

  41353.           additional names.  The default value is 'emacs'.  The value of

  41354.           the 'editing-mode' variable also affects the default keymap.

  41355. 

  41356.      'keyseq-timeout'

  41357.           Specifies the duration Readline will wait for a character when

  41358.           reading an ambiguous key sequence (one that can form a

  41359.           complete key sequence using the input read so far, or can take

  41360.           additional input to complete a longer key sequence).  If no

  41361.           input is received within the timeout, Readline will use the

  41362.           shorter but complete key sequence.  Readline uses this value

  41363.           to determine whether or not input is available on the current

  41364.           input source ('rl_instream' by default).  The value is

  41365.           specified in milliseconds, so a value of 1000 means that

  41366.           Readline will wait one second for additional input.  If this

  41367.           variable is set to a value less than or equal to zero, or to a

  41368.           non-numeric value, Readline will wait until another key is

  41369.           pressed to decide which key sequence to complete.  The default

  41370.           value is '500'.

  41371. 

  41372.      'mark-directories'

  41373.           If set to 'on', completed directory names have a slash

  41374.           appended.  The default is 'on'.

  41375. 

  41376.      'mark-modified-lines'

  41377.           This variable, when set to 'on', causes Readline to display an

  41378.           asterisk ('*') at the start of history lines which have been

  41379.           modified.  This variable is 'off' by default.

  41380. 

  41381.      'mark-symlinked-directories'

  41382.           If set to 'on', completed names which are symbolic links to

  41383.           directories have a slash appended (subject to the value of

  41384.           'mark-directories').  The default is 'off'.

  41385. 

  41386.      'match-hidden-files'

  41387.           This variable, when set to 'on', causes Readline to match

  41388.           files whose names begin with a '.' (hidden files) when

  41389.           performing filename completion.  If set to 'off', the leading

  41390.           '.' must be supplied by the user in the filename to be

  41391.           completed.  This variable is 'on' by default.

  41392. 

  41393.      'menu-complete-display-prefix'

  41394.           If set to 'on', menu completion displays the common prefix of

  41395.           the list of possible completions (which may be empty) before

  41396.           cycling through the list.  The default is 'off'.

  41397. 

  41398.      'output-meta'

  41399.           If set to 'on', Readline will display characters with the

  41400.           eighth bit set directly rather than as a meta-prefixed escape

  41401.           sequence.  The default is 'off', but Readline will set it to

  41402.           'on' if the locale contains eight-bit characters.

  41403. 

  41404.      'page-completions'

  41405.           If set to 'on', Readline uses an internal 'more'-like pager to

  41406.           display a screenful of possible completions at a time.  This

  41407.           variable is 'on' by default.

  41408. 

  41409.      'print-completions-horizontally'

  41410.           If set to 'on', Readline will display completions with matches

  41411.           sorted horizontally in alphabetical order, rather than down

  41412.           the screen.  The default is 'off'.

  41413. 

  41414.      'revert-all-at-newline'

  41415.           If set to 'on', Readline will undo all changes to history

  41416.           lines before returning when 'accept-line' is executed.  By

  41417.           default, history lines may be modified and retain individual

  41418.           undo lists across calls to 'readline'.  The default is 'off'.

  41419. 

  41420.      'show-all-if-ambiguous'

  41421.           This alters the default behavior of the completion functions.

  41422.           If set to 'on', words which have more than one possible

  41423.           completion cause the matches to be listed immediately instead

  41424.           of ringing the bell.  The default value is 'off'.

  41425. 

  41426.      'show-all-if-unmodified'

  41427.           This alters the default behavior of the completion functions

  41428.           in a fashion similar to SHOW-ALL-IF-AMBIGUOUS.  If set to

  41429.           'on', words which have more than one possible completion

  41430.           without any possible partial completion (the possible

  41431.           completions don't share a common prefix) cause the matches to

  41432.           be listed immediately instead of ringing the bell.  The

  41433.           default value is 'off'.

  41434. 

  41435.      'show-mode-in-prompt'

  41436.           If set to 'on', add a string to the beginning of the prompt

  41437.           indicating the editing mode: emacs, vi command, or vi

  41438.           insertion.  The mode strings are user-settable (e.g.,

  41439.           EMACS-MODE-STRING).  The default value is 'off'.

  41440. 

  41441.      'skip-completed-text'

  41442.           If set to 'on', this alters the default completion behavior

  41443.           when inserting a single match into the line.  It's only active

  41444.           when performing completion in the middle of a word.  If

  41445.           enabled, readline does not insert characters from the

  41446.           completion that match characters after point in the word being

  41447.           completed, so portions of the word following the cursor are

  41448.           not duplicated.  For instance, if this is enabled, attempting

  41449.           completion when the cursor is after the 'e' in 'Makefile' will

  41450.           result in 'Makefile' rather than 'Makefilefile', assuming

  41451.           there is a single possible completion.  The default value is

  41452.           'off'.

  41453. 

  41454.      'vi-cmd-mode-string'

  41455.           If the SHOW-MODE-IN-PROMPT variable is enabled, this string is

  41456.           displayed immediately before the last line of the primary

  41457.           prompt when vi editing mode is active and in command mode.

  41458.           The value is expanded like a key binding, so the standard set

  41459.           of meta- and control prefixes and backslash escape sequences

  41460.           is available.  Use the '\1' and '\2' escapes to begin and end

  41461.           sequences of non-printing characters, which can be used to

  41462.           embed a terminal control sequence into the mode string.  The

  41463.           default is '(cmd)'.

  41464. 

  41465.      'vi-ins-mode-string'

  41466.           If the SHOW-MODE-IN-PROMPT variable is enabled, this string is

  41467.           displayed immediately before the last line of the primary

  41468.           prompt when vi editing mode is active and in insertion mode.

  41469.           The value is expanded like a key binding, so the standard set

  41470.           of meta- and control prefixes and backslash escape sequences

  41471.           is available.  Use the '\1' and '\2' escapes to begin and end

  41472.           sequences of non-printing characters, which can be used to

  41473.           embed a terminal control sequence into the mode string.  The

  41474.           default is '(ins)'.

  41475. 

  41476.      'visible-stats'

  41477.           If set to 'on', a character denoting a file's type is appended

  41478.           to the filename when listing possible completions.  The

  41479.           default is 'off'.

  41480. 

  41481. Key Bindings

  41482.      The syntax for controlling key bindings in the init file is simple.

  41483.      First you need to find the name of the command that you want to

  41484.      change.  The following sections contain tables of the command name,

  41485.      the default keybinding, if any, and a short description of what the

  41486.      command does.

  41487. 

  41488.      Once you know the name of the command, simply place on a line in

  41489.      the init file the name of the key you wish to bind the command to,

  41490.      a colon, and then the name of the command.  There can be no space

  41491.      between the key name and the colon - that will be interpreted as

  41492.      part of the key name.  The name of the key can be expressed in

  41493.      different ways, depending on what you find most comfortable.

  41494. 

  41495.      In addition to command names, readline allows keys to be bound to a

  41496.      string that is inserted when the key is pressed (a MACRO).

  41497. 

  41498.      KEYNAME: FUNCTION-NAME or MACRO

  41499.           KEYNAME is the name of a key spelled out in English.  For

  41500.           example:

  41501.                Control-u: universal-argument

  41502.                Meta-Rubout: backward-kill-word

  41503.                Control-o: "> output"

  41504. 

  41505.           In the example above, 'C-u' is bound to the function

  41506.           'universal-argument', 'M-DEL' is bound to the function

  41507.           'backward-kill-word', and 'C-o' is bound to run the macro

  41508.           expressed on the right hand side (that is, to insert the text

  41509.           '> output' into the line).

  41510. 

  41511.           A number of symbolic character names are recognized while

  41512.           processing this key binding syntax: DEL, ESC, ESCAPE, LFD,

  41513.           NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.

  41514. 

  41515.      "KEYSEQ": FUNCTION-NAME or MACRO

  41516.           KEYSEQ differs from KEYNAME above in that strings denoting an

  41517.           entire key sequence can be specified, by placing the key

  41518.           sequence in double quotes.  Some GNU Emacs style key escapes

  41519.           can be used, as in the following example, but the special

  41520.           character names are not recognized.

  41521. 

  41522.                "\C-u": universal-argument

  41523.                "\C-x\C-r": re-read-init-file

  41524.                "\e[11~": "Function Key 1"

  41525. 

  41526.           In the above example, 'C-u' is again bound to the function

  41527.           'universal-argument' (just as it was in the first example),

  41528.           ''C-x' 'C-r'' is bound to the function 're-read-init-file',

  41529.           and '<ESC> <[> <1> <1> <~>' is bound to insert the text

  41530.           'Function Key 1'.

  41531. 

  41532.      The following GNU Emacs style escape sequences are available when

  41533.      specifying key sequences:

  41534. 

  41535.      '\C-'

  41536.           control prefix

  41537.      '\M-'

  41538.           meta prefix

  41539.      '\e'

  41540.           an escape character

  41541.      '\\'

  41542.           backslash

  41543.      '\"'

  41544.           <">, a double quotation mark

  41545.      '\''

  41546.           <'>, a single quote or apostrophe

  41547. 

  41548.      In addition to the GNU Emacs style escape sequences, a second set

  41549.      of backslash escapes is available:

  41550. 

  41551.      '\a'

  41552.           alert (bell)

  41553.      '\b'

  41554.           backspace

  41555.      '\d'

  41556.           delete

  41557.      '\f'

  41558.           form feed

  41559.      '\n'

  41560.           newline

  41561.      '\r'

  41562.           carriage return

  41563.      '\t'

  41564.           horizontal tab

  41565.      '\v'

  41566.           vertical tab

  41567.      '\NNN'

  41568.           the eight-bit character whose value is the octal value NNN

  41569.           (one to three digits)

  41570.      '\xHH'

  41571.           the eight-bit character whose value is the hexadecimal value

  41572.           HH (one or two hex digits)

  41573. 

  41574.      When entering the text of a macro, single or double quotes must be

  41575.      used to indicate a macro definition.  Unquoted text is assumed to

  41576.      be a function name.  In the macro body, the backslash escapes

  41577.      described above are expanded.  Backslash will quote any other

  41578.      character in the macro text, including '"' and '''.  For example,

  41579.      the following binding will make ''C-x' \' insert a single '\' into

  41580.      the line:

  41581.           "\C-x\\": "\\"

  41582. 

  41583. 

  41584. File: gdb.info,  Node: Conditional Init Constructs,  Next: Sample Init File,  Prev: Readline Init File Syntax,  Up: Readline Init File

  41585. 

  41586. 32.3.2 Conditional Init Constructs

  41587. ----------------------------------

  41588. 

  41589. Readline implements a facility similar in spirit to the conditional

  41590. compilation features of the C preprocessor which allows key bindings and

  41591. variable settings to be performed as the result of tests.  There are

  41592. four parser directives used.

  41593. 

  41594. '$if'

  41595.      The '$if' construct allows bindings to be made based on the editing

  41596.      mode, the terminal being used, or the application using Readline.

  41597.      The text of the test, after any comparison operator, extends to the

  41598.      end of the line; unless otherwise noted, no characters are required

  41599.      to isolate it.

  41600. 

  41601.      'mode'

  41602.           The 'mode=' form of the '$if' directive is used to test

  41603.           whether Readline is in 'emacs' or 'vi' mode.  This may be used

  41604.           in conjunction with the 'set keymap' command, for instance, to

  41605.           set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps

  41606.           only if Readline is starting out in 'emacs' mode.

  41607. 

  41608.      'term'

  41609.           The 'term=' form may be used to include terminal-specific key

  41610.           bindings, perhaps to bind the key sequences output by the

  41611.           terminal's function keys.  The word on the right side of the

  41612.           '=' is tested against both the full name of the terminal and

  41613.           the portion of the terminal name before the first '-'.  This

  41614.           allows 'sun' to match both 'sun' and 'sun-cmd', for instance.

  41615. 

  41616.      'version'

  41617.           The 'version' test may be used to perform comparisons against

  41618.           specific Readline versions.  The 'version' expands to the

  41619.           current Readline version.  The set of comparison operators

  41620.           includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'.  The

  41621.           version number supplied on the right side of the operator

  41622.           consists of a major version number, an optional decimal point,

  41623.           and an optional minor version (e.g., '7.1').  If the minor

  41624.           version is omitted, it is assumed to be '0'.  The operator may

  41625.           be separated from the string 'version' and from the version

  41626.           number argument by whitespace.  The following example sets a

  41627.           variable if the Readline version being used is 7.0 or newer:

  41628.                $if version >= 7.0

  41629.                set show-mode-in-prompt on

  41630.                $endif

  41631. 

  41632.      'application'

  41633.           The APPLICATION construct is used to include

  41634.           application-specific settings.  Each program using the

  41635.           Readline library sets the APPLICATION NAME, and you can test

  41636.           for a particular value.  This could be used to bind key

  41637.           sequences to functions useful for a specific program.  For

  41638.           instance, the following command adds a key sequence that

  41639.           quotes the current or previous word in Bash:

  41640.                $if Bash

  41641.                # Quote the current or previous word

  41642.                "\C-xq": "\eb\"\ef\""

  41643.                $endif

  41644. 

  41645.      'variable'

  41646.           The VARIABLE construct provides simple equality tests for

  41647.           Readline variables and values.  The permitted comparison

  41648.           operators are '=', '==', and '!='.  The variable name must be

  41649.           separated from the comparison operator by whitespace; the

  41650.           operator may be separated from the value on the right hand

  41651.           side by whitespace.  Both string and boolean variables may be

  41652.           tested.  Boolean variables must be tested against the values

  41653.           ON and OFF.  The following example is equivalent to the

  41654.           'mode=emacs' test described above:

  41655.                $if editing-mode == emacs

  41656.                set show-mode-in-prompt on

  41657.                $endif

  41658. 

  41659. '$endif'

  41660.      This command, as seen in the previous example, terminates an '$if'

  41661.      command.

  41662. 

  41663. '$else'

  41664.      Commands in this branch of the '$if' directive are executed if the

  41665.      test fails.

  41666. 

  41667. '$include'

  41668.      This directive takes a single filename as an argument and reads

  41669.      commands and bindings from that file.  For example, the following

  41670.      directive reads from '/etc/inputrc':

  41671.           $include /etc/inputrc

  41672. 

  41673. 

  41674. File: gdb.info,  Node: Sample Init File,  Prev: Conditional Init Constructs,  Up: Readline Init File

  41675. 

  41676. 32.3.3 Sample Init File

  41677. -----------------------

  41678. 

  41679. Here is an example of an INPUTRC file.  This illustrates key binding,

  41680. variable assignment, and conditional syntax.

  41681. 

  41682.      # This file controls the behaviour of line input editing for

  41683.      # programs that use the GNU Readline library.  Existing

  41684.      # programs include FTP, Bash, and GDB.

  41685.      #

  41686.      # You can re-read the inputrc file with C-x C-r.

  41687.      # Lines beginning with '#' are comments.

  41688.      #

  41689.      # First, include any system-wide bindings and variable

  41690.      # assignments from /etc/Inputrc

  41691.      $include /etc/Inputrc

  41692. 

  41693.      #

  41694.      # Set various bindings for emacs mode.

  41695. 

  41696.      set editing-mode emacs

  41697. 

  41698.      $if mode=emacs

  41699. 

  41700.      Meta-Control-h:	backward-kill-word	Text after the function name is ignored

  41701. 

  41702.      #

  41703.      # Arrow keys in keypad mode

  41704.      #

  41705.      #"\M-OD":        backward-char

  41706.      #"\M-OC":        forward-char

  41707.      #"\M-OA":        previous-history

  41708.      #"\M-OB":        next-history

  41709.      #

  41710.      # Arrow keys in ANSI mode

  41711.      #

  41712.      "\M-[D":        backward-char

  41713.      "\M-[C":        forward-char

  41714.      "\M-[A":        previous-history

  41715.      "\M-[B":        next-history

  41716.      #

  41717.      # Arrow keys in 8 bit keypad mode

  41718.      #

  41719.      #"\M-\C-OD":       backward-char

  41720.      #"\M-\C-OC":       forward-char

  41721.      #"\M-\C-OA":       previous-history

  41722.      #"\M-\C-OB":       next-history

  41723.      #

  41724.      # Arrow keys in 8 bit ANSI mode

  41725.      #

  41726.      #"\M-\C-[D":       backward-char

  41727.      #"\M-\C-[C":       forward-char

  41728.      #"\M-\C-[A":       previous-history

  41729.      #"\M-\C-[B":       next-history

  41730. 

  41731.      C-q: quoted-insert

  41732. 

  41733.      $endif

  41734. 

  41735.      # An old-style binding.  This happens to be the default.

  41736.      TAB: complete

  41737. 

  41738.      # Macros that are convenient for shell interaction

  41739.      $if Bash

  41740.      # edit the path

  41741.      "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"

  41742.      # prepare to type a quoted word --

  41743.      # insert open and close double quotes

  41744.      # and move to just after the open quote

  41745.      "\C-x\"": "\"\"\C-b"

  41746.      # insert a backslash (testing backslash escapes

  41747.      # in sequences and macros)

  41748.      "\C-x\\": "\\"

  41749.      # Quote the current or previous word

  41750.      "\C-xq": "\eb\"\ef\""

  41751.      # Add a binding to refresh the line, which is unbound

  41752.      "\C-xr": redraw-current-line

  41753.      # Edit variable on current line.

  41754.      "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="

  41755.      $endif

  41756. 

  41757.      # use a visible bell if one is available

  41758.      set bell-style visible

  41759. 

  41760.      # don't strip characters to 7 bits when reading

  41761.      set input-meta on

  41762. 

  41763.      # allow iso-latin1 characters to be inserted rather

  41764.      # than converted to prefix-meta sequences

  41765.      set convert-meta off

  41766. 

  41767.      # display characters with the eighth bit set directly

  41768.      # rather than as meta-prefixed characters

  41769.      set output-meta on

  41770. 

  41771.      # if there are more than 150 possible completions for

  41772.      # a word, ask the user if he wants to see all of them

  41773.      set completion-query-items 150

  41774. 

  41775.      # For FTP

  41776.      $if Ftp

  41777.      "\C-xg": "get \M-?"

  41778.      "\C-xt": "put \M-?"

  41779.      "\M-.": yank-last-arg

  41780.      $endif

  41781. 

  41782. 

  41783. File: gdb.info,  Node: Bindable Readline Commands,  Next: Readline vi Mode,  Prev: Readline Init File,  Up: Command Line Editing

  41784. 

  41785. 32.4 Bindable Readline Commands

  41786. ===============================

  41787. 

  41788. * Menu:

  41789. 

  41790. * Commands For Moving::		Moving about the line.

  41791. * Commands For History::	Getting at previous lines.

  41792. * Commands For Text::		Commands for changing text.

  41793. * Commands For Killing::	Commands for killing and yanking.

  41794. * Numeric Arguments::		Specifying numeric arguments, repeat counts.

  41795. * Commands For Completion::	Getting Readline to do the typing for you.

  41796. * Keyboard Macros::		Saving and re-executing typed characters

  41797. * Miscellaneous Commands::	Other miscellaneous commands.

  41798. 

  41799. This section describes Readline commands that may be bound to key

  41800. sequences.  Command names without an accompanying key sequence are

  41801. unbound by default.

  41802. 

  41803.    In the following descriptions, "point" refers to the current cursor

  41804. position, and "mark" refers to a cursor position saved by the 'set-mark'

  41805. command.  The text between the point and mark is referred to as the

  41806. "region".

  41807. 

  41808. 

  41809. File: gdb.info,  Node: Commands For Moving,  Next: Commands For History,  Up: Bindable Readline Commands

  41810. 

  41811. 32.4.1 Commands For Moving

  41812. --------------------------

  41813. 

  41814. 'beginning-of-line (C-a)'

  41815.      Move to the start of the current line.

  41816. 

  41817. 'end-of-line (C-e)'

  41818.      Move to the end of the line.

  41819. 

  41820. 'forward-char (C-f)'

  41821.      Move forward a character.

  41822. 

  41823. 'backward-char (C-b)'

  41824.      Move back a character.

  41825. 

  41826. 'forward-word (M-f)'

  41827.      Move forward to the end of the next word.  Words are composed of

  41828.      letters and digits.

  41829. 

  41830. 'backward-word (M-b)'

  41831.      Move back to the start of the current or previous word.  Words are

  41832.      composed of letters and digits.

  41833. 

  41834. 'previous-screen-line ()'

  41835.      Attempt to move point to the same physical screen column on the

  41836.      previous physical screen line.  This will not have the desired

  41837.      effect if the current Readline line does not take up more than one

  41838.      physical line or if point is not greater than the length of the

  41839.      prompt plus the screen width.

  41840. 

  41841. 'next-screen-line ()'

  41842.      Attempt to move point to the same physical screen column on the

  41843.      next physical screen line.  This will not have the desired effect

  41844.      if the current Readline line does not take up more than one

  41845.      physical line or if the length of the current Readline line is not

  41846.      greater than the length of the prompt plus the screen width.

  41847. 

  41848. 'clear-screen (C-l)'

  41849.      Clear the screen and redraw the current line, leaving the current

  41850.      line at the top of the screen.

  41851. 

  41852. 'redraw-current-line ()'

  41853.      Refresh the current line.  By default, this is unbound.

  41854. 

  41855. 

  41856. File: gdb.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands

  41857. 

  41858. 32.4.2 Commands For Manipulating The History

  41859. --------------------------------------------

  41860. 

  41861. 'accept-line (Newline or Return)'

  41862.      Accept the line regardless of where the cursor is.  If this line is

  41863.      non-empty, it may be added to the history list for future recall

  41864.      with 'add_history()'.  If this line is a modified history line, the

  41865.      history line is restored to its original state.

  41866. 

  41867. 'previous-history (C-p)'

  41868.      Move 'back' through the history list, fetching the previous

  41869.      command.

  41870. 

  41871. 'next-history (C-n)'

  41872.      Move 'forward' through the history list, fetching the next command.

  41873. 

  41874. 'beginning-of-history (M-<)'

  41875.      Move to the first line in the history.

  41876. 

  41877. 'end-of-history (M->)'

  41878.      Move to the end of the input history, i.e., the line currently

  41879.      being entered.

  41880. 

  41881. 'reverse-search-history (C-r)'

  41882.      Search backward starting at the current line and moving 'up'

  41883.      through the history as necessary.  This is an incremental search.

  41884. 

  41885. 'forward-search-history (C-s)'

  41886.      Search forward starting at the current line and moving 'down'

  41887.      through the history as necessary.  This is an incremental search.

  41888. 

  41889. 'non-incremental-reverse-search-history (M-p)'

  41890.      Search backward starting at the current line and moving 'up'

  41891.      through the history as necessary using a non-incremental search for

  41892.      a string supplied by the user.  The search string may match

  41893.      anywhere in a history line.

  41894. 

  41895. 'non-incremental-forward-search-history (M-n)'

  41896.      Search forward starting at the current line and moving 'down'

  41897.      through the history as necessary using a non-incremental search for

  41898.      a string supplied by the user.  The search string may match

  41899.      anywhere in a history line.

  41900. 

  41901. 'history-search-forward ()'

  41902.      Search forward through the history for the string of characters

  41903.      between the start of the current line and the point.  The search

  41904.      string must match at the beginning of a history line.  This is a

  41905.      non-incremental search.  By default, this command is unbound.

  41906. 

  41907. 'history-search-backward ()'

  41908.      Search backward through the history for the string of characters

  41909.      between the start of the current line and the point.  The search

  41910.      string must match at the beginning of a history line.  This is a

  41911.      non-incremental search.  By default, this command is unbound.

  41912. 

  41913. 'history-substring-search-forward ()'

  41914.      Search forward through the history for the string of characters

  41915.      between the start of the current line and the point.  The search

  41916.      string may match anywhere in a history line.  This is a

  41917.      non-incremental search.  By default, this command is unbound.

  41918. 

  41919. 'history-substring-search-backward ()'

  41920.      Search backward through the history for the string of characters

  41921.      between the start of the current line and the point.  The search

  41922.      string may match anywhere in a history line.  This is a

  41923.      non-incremental search.  By default, this command is unbound.

  41924. 

  41925. 'yank-nth-arg (M-C-y)'

  41926.      Insert the first argument to the previous command (usually the

  41927.      second word on the previous line) at point.  With an argument N,

  41928.      insert the Nth word from the previous command (the words in the

  41929.      previous command begin with word 0).  A negative argument inserts

  41930.      the Nth word from the end of the previous command.  Once the

  41931.      argument N is computed, the argument is extracted as if the '!N'

  41932.      history expansion had been specified.

  41933. 

  41934. 'yank-last-arg (M-. or M-_)'

  41935.      Insert last argument to the previous command (the last word of the

  41936.      previous history entry).  With a numeric argument, behave exactly

  41937.      like 'yank-nth-arg'.  Successive calls to 'yank-last-arg' move back

  41938.      through the history list, inserting the last word (or the word

  41939.      specified by the argument to the first call) of each line in turn.

  41940.      Any numeric argument supplied to these successive calls determines

  41941.      the direction to move through the history.  A negative argument

  41942.      switches the direction through the history (back or forward).  The

  41943.      history expansion facilities are used to extract the last argument,

  41944.      as if the '!$' history expansion had been specified.

  41945. 

  41946. 

  41947. File: gdb.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands

  41948. 

  41949. 32.4.3 Commands For Changing Text

  41950. ---------------------------------

  41951. 

  41952. 'end-of-file (usually C-d)'

  41953.      The character indicating end-of-file as set, for example, by

  41954.      'stty'.  If this character is read when there are no characters on

  41955.      the line, and point is at the beginning of the line, Readline

  41956.      interprets it as the end of input and returns EOF.

  41957. 

  41958. 'delete-char (C-d)'

  41959.      Delete the character at point.  If this function is bound to the

  41960.      same character as the tty EOF character, as 'C-d' commonly is, see

  41961.      above for the effects.

  41962. 

  41963. 'backward-delete-char (Rubout)'

  41964.      Delete the character behind the cursor.  A numeric argument means

  41965.      to kill the characters instead of deleting them.

  41966. 

  41967. 'forward-backward-delete-char ()'

  41968.      Delete the character under the cursor, unless the cursor is at the

  41969.      end of the line, in which case the character behind the cursor is

  41970.      deleted.  By default, this is not bound to a key.

  41971. 

  41972. 'quoted-insert (C-q or C-v)'

  41973.      Add the next character typed to the line verbatim.  This is how to

  41974.      insert key sequences like 'C-q', for example.

  41975. 

  41976. 'tab-insert (M-<TAB>)'

  41977.      Insert a tab character.

  41978. 

  41979. 'self-insert (a, b, A, 1, !, ...)'

  41980.      Insert yourself.

  41981. 

  41982. 'bracketed-paste-begin ()'

  41983.      This function is intended to be bound to the "bracketed paste"

  41984.      escape sequence sent by some terminals, and such a binding is

  41985.      assigned by default.  It allows Readline to insert the pasted text

  41986.      as a single unit without treating each character as if it had been

  41987.      read from the keyboard.  The characters are inserted as if each one

  41988.      was bound to 'self-insert' instead of executing any editing

  41989.      commands.

  41990. 

  41991. 'transpose-chars (C-t)'

  41992.      Drag the character before the cursor forward over the character at

  41993.      the cursor, moving the cursor forward as well.  If the insertion

  41994.      point is at the end of the line, then this transposes the last two

  41995.      characters of the line.  Negative arguments have no effect.

  41996. 

  41997. 'transpose-words (M-t)'

  41998.      Drag the word before point past the word after point, moving point

  41999.      past that word as well.  If the insertion point is at the end of

  42000.      the line, this transposes the last two words on the line.

  42001. 

  42002. 'upcase-word (M-u)'

  42003.      Uppercase the current (or following) word.  With a negative

  42004.      argument, uppercase the previous word, but do not move the cursor.

  42005. 

  42006. 'downcase-word (M-l)'

  42007.      Lowercase the current (or following) word.  With a negative

  42008.      argument, lowercase the previous word, but do not move the cursor.

  42009. 

  42010. 'capitalize-word (M-c)'

  42011.      Capitalize the current (or following) word.  With a negative

  42012.      argument, capitalize the previous word, but do not move the cursor.

  42013. 

  42014. 'overwrite-mode ()'

  42015.      Toggle overwrite mode.  With an explicit positive numeric argument,

  42016.      switches to overwrite mode.  With an explicit non-positive numeric

  42017.      argument, switches to insert mode.  This command affects only

  42018.      'emacs' mode; 'vi' mode does overwrite differently.  Each call to

  42019.      'readline()' starts in insert mode.

  42020. 

  42021.      In overwrite mode, characters bound to 'self-insert' replace the

  42022.      text at point rather than pushing the text to the right.

  42023.      Characters bound to 'backward-delete-char' replace the character

  42024.      before point with a space.

  42025. 

  42026.      By default, this command is unbound.

  42027. 

  42028. 

  42029. File: gdb.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands

  42030. 

  42031. 32.4.4 Killing And Yanking

  42032. --------------------------

  42033. 

  42034. 'kill-line (C-k)'

  42035.      Kill the text from point to the end of the line.

  42036. 

  42037. 'backward-kill-line (C-x Rubout)'

  42038.      Kill backward from the cursor to the beginning of the current line.

  42039. 

  42040. 'unix-line-discard (C-u)'

  42041.      Kill backward from the cursor to the beginning of the current line.

  42042. 

  42043. 'kill-whole-line ()'

  42044.      Kill all characters on the current line, no matter where point is.

  42045.      By default, this is unbound.

  42046. 

  42047. 'kill-word (M-d)'

  42048.      Kill from point to the end of the current word, or if between

  42049.      words, to the end of the next word.  Word boundaries are the same

  42050.      as 'forward-word'.

  42051. 

  42052. 'backward-kill-word (M-<DEL>)'

  42053.      Kill the word behind point.  Word boundaries are the same as

  42054.      'backward-word'.

  42055. 

  42056. 'unix-word-rubout (C-w)'

  42057.      Kill the word behind point, using white space as a word boundary.

  42058.      The killed text is saved on the kill-ring.

  42059. 

  42060. 'unix-filename-rubout ()'

  42061.      Kill the word behind point, using white space and the slash

  42062.      character as the word boundaries.  The killed text is saved on the

  42063.      kill-ring.

  42064. 

  42065. 'delete-horizontal-space ()'

  42066.      Delete all spaces and tabs around point.  By default, this is

  42067.      unbound.

  42068. 

  42069. 'kill-region ()'

  42070.      Kill the text in the current region.  By default, this command is

  42071.      unbound.

  42072. 

  42073. 'copy-region-as-kill ()'

  42074.      Copy the text in the region to the kill buffer, so it can be yanked

  42075.      right away.  By default, this command is unbound.

  42076. 

  42077. 'copy-backward-word ()'

  42078.      Copy the word before point to the kill buffer.  The word boundaries

  42079.      are the same as 'backward-word'.  By default, this command is

  42080.      unbound.

  42081. 

  42082. 'copy-forward-word ()'

  42083.      Copy the word following point to the kill buffer.  The word

  42084.      boundaries are the same as 'forward-word'.  By default, this

  42085.      command is unbound.

  42086. 

  42087. 'yank (C-y)'

  42088.      Yank the top of the kill ring into the buffer at point.

  42089. 

  42090. 'yank-pop (M-y)'

  42091.      Rotate the kill-ring, and yank the new top.  You can only do this

  42092.      if the prior command is 'yank' or 'yank-pop'.

  42093. 

  42094. 

  42095. File: gdb.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands

  42096. 

  42097. 32.4.5 Specifying Numeric Arguments

  42098. -----------------------------------

  42099. 

  42100. 'digit-argument (M-0, M-1, ... M--)'

  42101.      Add this digit to the argument already accumulating, or start a new

  42102.      argument.  'M--' starts a negative argument.

  42103. 

  42104. 'universal-argument ()'

  42105.      This is another way to specify an argument.  If this command is

  42106.      followed by one or more digits, optionally with a leading minus

  42107.      sign, those digits define the argument.  If the command is followed

  42108.      by digits, executing 'universal-argument' again ends the numeric

  42109.      argument, but is otherwise ignored.  As a special case, if this

  42110.      command is immediately followed by a character that is neither a

  42111.      digit nor minus sign, the argument count for the next command is

  42112.      multiplied by four.  The argument count is initially one, so

  42113.      executing this function the first time makes the argument count

  42114.      four, a second time makes the argument count sixteen, and so on.

  42115.      By default, this is not bound to a key.

  42116. 

  42117. 

  42118. File: gdb.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands

  42119. 

  42120. 32.4.6 Letting Readline Type For You

  42121. ------------------------------------

  42122. 

  42123. 'complete (<TAB>)'

  42124.      Attempt to perform completion on the text before point.  The actual

  42125.      completion performed is application-specific.  The default is

  42126.      filename completion.

  42127. 

  42128. 'possible-completions (M-?)'

  42129.      List the possible completions of the text before point.  When

  42130.      displaying completions, Readline sets the number of columns used

  42131.      for display to the value of 'completion-display-width', the value

  42132.      of the environment variable 'COLUMNS', or the screen width, in that

  42133.      order.

  42134. 

  42135. 'insert-completions (M-*)'

  42136.      Insert all completions of the text before point that would have

  42137.      been generated by 'possible-completions'.

  42138. 

  42139. 'menu-complete ()'

  42140.      Similar to 'complete', but replaces the word to be completed with a

  42141.      single match from the list of possible completions.  Repeated

  42142.      execution of 'menu-complete' steps through the list of possible

  42143.      completions, inserting each match in turn.  At the end of the list

  42144.      of completions, the bell is rung (subject to the setting of

  42145.      'bell-style') and the original text is restored.  An argument of N

  42146.      moves N positions forward in the list of matches; a negative

  42147.      argument may be used to move backward through the list.  This

  42148.      command is intended to be bound to <TAB>, but is unbound by

  42149.      default.

  42150. 

  42151. 'menu-complete-backward ()'

  42152.      Identical to 'menu-complete', but moves backward through the list

  42153.      of possible completions, as if 'menu-complete' had been given a

  42154.      negative argument.

  42155. 

  42156. 'delete-char-or-list ()'

  42157.      Deletes the character under the cursor if not at the beginning or

  42158.      end of the line (like 'delete-char').  If at the end of the line,

  42159.      behaves identically to 'possible-completions'.  This command is

  42160.      unbound by default.

  42161. 

  42162. 

  42163. File: gdb.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands

  42164. 

  42165. 32.4.7 Keyboard Macros

  42166. ----------------------

  42167. 

  42168. 'start-kbd-macro (C-x ()'

  42169.      Begin saving the characters typed into the current keyboard macro.

  42170. 

  42171. 'end-kbd-macro (C-x ))'

  42172.      Stop saving the characters typed into the current keyboard macro

  42173.      and save the definition.

  42174. 

  42175. 'call-last-kbd-macro (C-x e)'

  42176.      Re-execute the last keyboard macro defined, by making the

  42177.      characters in the macro appear as if typed at the keyboard.

  42178. 

  42179. 'print-last-kbd-macro ()'

  42180.      Print the last keboard macro defined in a format suitable for the

  42181.      INPUTRC file.

  42182. 

  42183. 

  42184. File: gdb.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands

  42185. 

  42186. 32.4.8 Some Miscellaneous Commands

  42187. ----------------------------------

  42188. 

  42189. 're-read-init-file (C-x C-r)'

  42190.      Read in the contents of the INPUTRC file, and incorporate any

  42191.      bindings or variable assignments found there.

  42192. 

  42193. 'abort (C-g)'

  42194.      Abort the current editing command and ring the terminal's bell

  42195.      (subject to the setting of 'bell-style').

  42196. 

  42197. 'do-lowercase-version (M-A, M-B, M-X, ...)'

  42198.      If the metafied character X is upper case, run the command that is

  42199.      bound to the corresponding metafied lower case character.  The

  42200.      behavior is undefined if X is already lower case.

  42201. 

  42202. 'prefix-meta (<ESC>)'

  42203.      Metafy the next character typed.  This is for keyboards without a

  42204.      meta key.  Typing '<ESC> f' is equivalent to typing 'M-f'.

  42205. 

  42206. 'undo (C-_ or C-x C-u)'

  42207.      Incremental undo, separately remembered for each line.

  42208. 

  42209. 'revert-line (M-r)'

  42210.      Undo all changes made to this line.  This is like executing the

  42211.      'undo' command enough times to get back to the beginning.

  42212. 

  42213. 'tilde-expand (M-~)'

  42214.      Perform tilde expansion on the current word.

  42215. 

  42216. 'set-mark (C-@)'

  42217.      Set the mark to the point.  If a numeric argument is supplied, the

  42218.      mark is set to that position.

  42219. 

  42220. 'exchange-point-and-mark (C-x C-x)'

  42221.      Swap the point with the mark.  The current cursor position is set

  42222.      to the saved position, and the old cursor position is saved as the

  42223.      mark.

  42224. 

  42225. 'character-search (C-])'

  42226.      A character is read and point is moved to the next occurrence of

  42227.      that character.  A negative count searches for previous

  42228.      occurrences.

  42229. 

  42230. 'character-search-backward (M-C-])'

  42231.      A character is read and point is moved to the previous occurrence

  42232.      of that character.  A negative count searches for subsequent

  42233.      occurrences.

  42234. 

  42235. 'skip-csi-sequence ()'

  42236.      Read enough characters to consume a multi-key sequence such as

  42237.      those defined for keys like Home and End.  Such sequences begin

  42238.      with a Control Sequence Indicator (CSI), usually ESC-[.  If this

  42239.      sequence is bound to "\e[", keys producing such sequences will have

  42240.      no effect unless explicitly bound to a readline command, instead of

  42241.      inserting stray characters into the editing buffer.  This is

  42242.      unbound by default, but usually bound to ESC-[.

  42243. 

  42244. 'insert-comment (M-#)'

  42245.      Without a numeric argument, the value of the 'comment-begin'

  42246.      variable is inserted at the beginning of the current line.  If a

  42247.      numeric argument is supplied, this command acts as a toggle: if the

  42248.      characters at the beginning of the line do not match the value of

  42249.      'comment-begin', the value is inserted, otherwise the characters in

  42250.      'comment-begin' are deleted from the beginning of the line.  In

  42251.      either case, the line is accepted as if a newline had been typed.

  42252. 

  42253. 'dump-functions ()'

  42254.      Print all of the functions and their key bindings to the Readline

  42255.      output stream.  If a numeric argument is supplied, the output is

  42256.      formatted in such a way that it can be made part of an INPUTRC

  42257.      file.  This command is unbound by default.

  42258. 

  42259. 'dump-variables ()'

  42260.      Print all of the settable variables and their values to the

  42261.      Readline output stream.  If a numeric argument is supplied, the

  42262.      output is formatted in such a way that it can be made part of an

  42263.      INPUTRC file.  This command is unbound by default.

  42264. 

  42265. 'dump-macros ()'

  42266.      Print all of the Readline key sequences bound to macros and the

  42267.      strings they output.  If a numeric argument is supplied, the output

  42268.      is formatted in such a way that it can be made part of an INPUTRC

  42269.      file.  This command is unbound by default.

  42270. 

  42271. 'emacs-editing-mode (C-e)'

  42272.      When in 'vi' command mode, this causes a switch to 'emacs' editing

  42273.      mode.

  42274. 

  42275. 'vi-editing-mode (M-C-j)'

  42276.      When in 'emacs' editing mode, this causes a switch to 'vi' editing

  42277.      mode.

  42278. 

  42279. 

  42280. File: gdb.info,  Node: Readline vi Mode,  Prev: Bindable Readline Commands,  Up: Command Line Editing

  42281. 

  42282. 32.5 Readline vi Mode

  42283. =====================

  42284. 

  42285. While the Readline library does not have a full set of 'vi' editing

  42286. functions, it does contain enough to allow simple editing of the line.

  42287. The Readline 'vi' mode behaves as specified in the POSIX standard.

  42288. 

  42289.    In order to switch interactively between 'emacs' and 'vi' editing

  42290. modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi'

  42291. mode and to vi-editing-mode in 'emacs' mode).  The Readline default is

  42292. 'emacs' mode.

  42293. 

  42294.    When you enter a line in 'vi' mode, you are already placed in

  42295. 'insertion' mode, as if you had typed an 'i'.  Pressing <ESC> switches

  42296. you into 'command' mode, where you can edit the text of the line with

  42297. the standard 'vi' movement keys, move to previous history lines with 'k'

  42298. and subsequent lines with 'j', and so forth.

  42299. 

  42300. 

  42301. File: gdb.info,  Node: Using History Interactively,  Next: In Memoriam,  Prev: Command Line Editing,  Up: Top

  42302. 

  42303. 33 Using History Interactively

  42304. ******************************

  42305. 

  42306. This chapter describes how to use the GNU History Library interactively,

  42307. from a user's standpoint.  It should be considered a user's guide.  For

  42308. information on using the GNU History Library in your own programs, *note

  42309. (history)Programming with GNU History::.

  42310. 

  42311. * Menu:

  42312. 

  42313. * History Interaction::		What it feels like using History as a user.

  42314. 

  42315. 

  42316. File: gdb.info,  Node: History Interaction,  Up: Using History Interactively

  42317. 

  42318. 33.1 History Expansion

  42319. ======================

  42320. 

  42321. The History library provides a history expansion feature that is similar

  42322. to the history expansion provided by 'csh'.  This section describes the

  42323. syntax used to manipulate the history information.

  42324. 

  42325.    History expansions introduce words from the history list into the

  42326. input stream, making it easy to repeat commands, insert the arguments to

  42327. a previous command into the current input line, or fix errors in

  42328. previous commands quickly.

  42329. 

  42330.    History expansion takes place in two parts.  The first is to

  42331. determine which line from the history list should be used during

  42332. substitution.  The second is to select portions of that line for

  42333. inclusion into the current one.  The line selected from the history is

  42334. called the "event", and the portions of that line that are acted upon

  42335. are called "words".  Various "modifiers" are available to manipulate the

  42336. selected words.  The line is broken into words in the same fashion that

  42337. Bash does, so that several words surrounded by quotes are considered one

  42338. word.  History expansions are introduced by the appearance of the

  42339. history expansion character, which is '!' by default.

  42340. 

  42341.    History expansion implements shell-like quoting conventions: a

  42342. backslash can be used to remove the special handling for the next

  42343. character; single quotes enclose verbatim sequences of characters, and

  42344. can be used to inhibit history expansion; and characters enclosed within

  42345. double quotes may be subject to history expansion, since backslash can

  42346. escape the history expansion character, but single quotes may not, since

  42347. they are not treated specially within double quotes.

  42348. 

  42349. * Menu:

  42350. 

  42351. * Event Designators::	How to specify which history line to use.

  42352. * Word Designators::	Specifying which words are of interest.

  42353. * Modifiers::		Modifying the results of substitution.

  42354. 

  42355. 

  42356. File: gdb.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction

  42357. 

  42358. 33.1.1 Event Designators

  42359. ------------------------

  42360. 

  42361. An event designator is a reference to a command line entry in the

  42362. history list.  Unless the reference is absolute, events are relative to

  42363. the current position in the history list.

  42364. 

  42365. '!'

  42366.      Start a history substitution, except when followed by a space, tab,

  42367.      the end of the line, or '='.

  42368. 

  42369. '!N'

  42370.      Refer to command line N.

  42371. 

  42372. '!-N'

  42373.      Refer to the command N lines back.

  42374. 

  42375. '!!'

  42376.      Refer to the previous command.  This is a synonym for '!-1'.

  42377. 

  42378. '!STRING'

  42379.      Refer to the most recent command preceding the current position in

  42380.      the history list starting with STRING.

  42381. 

  42382. '!?STRING[?]'

  42383.      Refer to the most recent command preceding the current position in

  42384.      the history list containing STRING.  The trailing '?' may be

  42385.      omitted if the STRING is followed immediately by a newline.

  42386. 

  42387. '^STRING1^STRING2^'

  42388.      Quick Substitution.  Repeat the last command, replacing STRING1

  42389.      with STRING2.  Equivalent to '!!:s/STRING1/STRING2/'.

  42390. 

  42391. '!#'

  42392.      The entire command line typed so far.

  42393. 

  42394. 

  42395. File: gdb.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction

  42396. 

  42397. 33.1.2 Word Designators

  42398. -----------------------

  42399. 

  42400. Word designators are used to select desired words from the event.  A ':'

  42401. separates the event specification from the word designator.  It may be

  42402. omitted if the word designator begins with a '^', '$', '*', '-', or '%'.

  42403. Words are numbered from the beginning of the line, with the first word

  42404. being denoted by 0 (zero).  Words are inserted into the current line

  42405. separated by single spaces.

  42406. 

  42407.    For example,

  42408. 

  42409. '!!'

  42410.      designates the preceding command.  When you type this, the

  42411.      preceding command is repeated in toto.

  42412. 

  42413. '!!:$'

  42414.      designates the last argument of the preceding command.  This may be

  42415.      shortened to '!$'.

  42416. 

  42417. '!fi:2'

  42418.      designates the second argument of the most recent command starting

  42419.      with the letters 'fi'.

  42420. 

  42421.    Here are the word designators:

  42422. 

  42423. '0 (zero)'

  42424.      The '0'th word.  For many applications, this is the command word.

  42425. 

  42426. 'N'

  42427.      The Nth word.

  42428. 

  42429. '^'

  42430.      The first argument; that is, word 1.

  42431. 

  42432. '$'

  42433.      The last argument.

  42434. 

  42435. '%'

  42436.      The word matched by the most recent '?STRING?' search.

  42437. 

  42438. 'X-Y'

  42439.      A range of words; '-Y' abbreviates '0-Y'.

  42440. 

  42441. '*'

  42442.      All of the words, except the '0'th.  This is a synonym for '1-$'.

  42443.      It is not an error to use '*' if there is just one word in the

  42444.      event; the empty string is returned in that case.

  42445. 

  42446. 'X*'

  42447.      Abbreviates 'X-$'

  42448. 

  42449. 'X-'

  42450.      Abbreviates 'X-$' like 'X*', but omits the last word.

  42451. 

  42452.    If a word designator is supplied without an event specification, the

  42453. previous command is used as the event.

  42454. 

  42455. 

  42456. File: gdb.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction

  42457. 

  42458. 33.1.3 Modifiers

  42459. ----------------

  42460. 

  42461. After the optional word designator, you can add a sequence of one or

  42462. more of the following modifiers, each preceded by a ':'.

  42463. 

  42464. 'h'

  42465.      Remove a trailing pathname component, leaving only the head.

  42466. 

  42467. 't'

  42468.      Remove all leading pathname components, leaving the tail.

  42469. 

  42470. 'r'

  42471.      Remove a trailing suffix of the form '.SUFFIX', leaving the

  42472.      basename.

  42473. 

  42474. 'e'

  42475.      Remove all but the trailing suffix.

  42476. 

  42477. 'p'

  42478.      Print the new command but do not execute it.

  42479. 

  42480. 's/OLD/NEW/'

  42481.      Substitute NEW for the first occurrence of OLD in the event line.

  42482.      Any delimiter may be used in place of '/'.  The delimiter may be

  42483.      quoted in OLD and NEW with a single backslash.  If '&' appears in

  42484.      NEW, it is replaced by OLD.  A single backslash will quote the '&'.

  42485.      The final delimiter is optional if it is the last character on the

  42486.      input line.

  42487. 

  42488. '&'

  42489.      Repeat the previous substitution.

  42490. 

  42491. 'g'

  42492. 'a'

  42493.      Cause changes to be applied over the entire event line.  Used in

  42494.      conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.

  42495. 

  42496. 'G'

  42497.      Apply the following 's' modifier once to each word in the event.

  42498. 

  42499. 

  42500. File: gdb.info,  Node: In Memoriam,  Next: Formatting Documentation,  Prev: Using History Interactively,  Up: Top

  42501. 

  42502. Appendix A In Memoriam

  42503. **********************

  42504. 

  42505. The GDB project mourns the loss of the following long-time contributors:

  42506. 

  42507. 'Fred Fish'

  42508.      Fred was a long-standing contributor to GDB (1991-2006), and to

  42509.      Free Software in general.  Outside of GDB, he was known in the

  42510.      Amiga world for his series of Fish Disks, and the GeekGadget

  42511.      project.

  42512. 

  42513. 'Michael Snyder'

  42514.      Michael was one of the Global Maintainers of the GDB project, with

  42515.      contributions recorded as early as 1996, until 2011.  In addition

  42516.      to his day to day participation, he was a large driving force

  42517.      behind adding Reverse Debugging to GDB.

  42518. 

  42519.    Beyond their technical contributions to the project, they were also

  42520. enjoyable members of the Free Software Community.  We will miss them.

  42521. 

  42522. 

  42523. File: gdb.info,  Node: Formatting Documentation,  Next: Installing GDB,  Prev: In Memoriam,  Up: Top

  42524. 

  42525. Appendix B Formatting Documentation

  42526. ***********************************

  42527. 

  42528. The GDB 4 release includes an already-formatted reference card, ready

  42529. for printing with PostScript or Ghostscript, in the 'gdb' subdirectory

  42530. of the main source directory(1).  If you can use PostScript or

  42531. Ghostscript with your printer, you can print the reference card

  42532. immediately with 'refcard.ps'.

  42533. 

  42534.    The release also includes the source for the reference card.  You can

  42535. format it, using TeX, by typing:

  42536. 

  42537.      make refcard.dvi

  42538. 

  42539.    The GDB reference card is designed to print in "landscape" mode on US

  42540. "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches

  42541. high.  You will need to specify this form of printing as an option to

  42542. your DVI output program.

  42543. 

  42544.    All the documentation for GDB comes as part of the machine-readable

  42545. distribution.  The documentation is written in Texinfo format, which is

  42546. a documentation system that uses a single source file to produce both

  42547. on-line information and a printed manual.  You can use one of the Info

  42548. formatting commands to create the on-line version of the documentation

  42549. and TeX (or 'texi2roff') to typeset the printed version.

  42550. 

  42551.    GDB includes an already formatted copy of the on-line Info version of

  42552. this manual in the 'gdb' subdirectory.  The main Info file is

  42553. 'gdb-10.1.90.20201028-git/gdb/gdb.info', and it refers to subordinate

  42554. files matching 'gdb.info*' in the same directory.  If necessary, you can

  42555. print out these files, or read them with any editor; but they are easier

  42556. to read using the 'info' subsystem in GNU Emacs or the standalone 'info'

  42557. program, available as part of the GNU Texinfo distribution.

  42558. 

  42559.    If you want to format these Info files yourself, you need one of the

  42560. Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'.

  42561. 

  42562.    If you have 'makeinfo' installed, and are in the top level GDB source

  42563. directory ('gdb-10.1.90.20201028-git', in the case of version

  42564. 10.1.90.20201028-git), you can make the Info file by typing:

  42565. 

  42566.      cd gdb

  42567.      make gdb.info

  42568. 

  42569.    If you want to typeset and print copies of this manual, you need TeX,

  42570. a program to print its DVI output files, and 'texinfo.tex', the Texinfo

  42571. definitions file.

  42572. 

  42573.    TeX is a typesetting program; it does not print files directly, but

  42574. produces output files called DVI files.  To print a typeset document,

  42575. you need a program to print DVI files.  If your system has TeX

  42576. installed, chances are it has such a program.  The precise command to

  42577. use depends on your system; 'lpr -d' is common; another (for PostScript

  42578. devices) is 'dvips'.  The DVI print command may require a file name

  42579. without any extension or a '.dvi' extension.

  42580. 

  42581.    TeX also requires a macro definitions file called 'texinfo.tex'.

  42582. This file tells TeX how to typeset a document written in Texinfo format.

  42583. On its own, TeX cannot either read or typeset a Texinfo file.

  42584. 'texinfo.tex' is distributed with GDB and is located in the

  42585. 'gdb-VERSION-NUMBER/texinfo' directory.

  42586. 

  42587.    If you have TeX and a DVI printer program installed, you can typeset

  42588. and print this manual.  First switch to the 'gdb' subdirectory of the

  42589. main source directory (for example, to 'gdb-10.1.90.20201028-git/gdb')

  42590. and type:

  42591. 

  42592.      make gdb.dvi

  42593. 

  42594.    Then give 'gdb.dvi' to your DVI printing program.

  42595. 

  42596.    ---------- Footnotes ----------

  42597. 

  42598.    (1) In 'gdb-10.1.90.20201028-git/gdb/refcard.ps' of the version

  42599. 10.1.90.20201028-git release.

  42600. 

  42601. 

  42602. File: gdb.info,  Node: Installing GDB,  Next: Maintenance Commands,  Prev: Formatting Documentation,  Up: Top

  42603. 

  42604. Appendix C Installing GDB

  42605. *************************

  42606. 

  42607. * Menu:

  42608. 

  42609. * Requirements::                Requirements for building GDB

  42610. * Running Configure::           Invoking the GDB 'configure' script

  42611. * Separate Objdir::             Compiling GDB in another directory

  42612. * Config Names::                Specifying names for hosts and targets

  42613. * Configure Options::           Summary of options for configure

  42614. * System-wide configuration::   Having a system-wide init file

  42615. 

  42616. 

  42617. File: gdb.info,  Node: Requirements,  Next: Running Configure,  Up: Installing GDB

  42618. 

  42619. C.1 Requirements for Building GDB

  42620. =================================

  42621. 

  42622. Building GDB requires various tools and packages to be available.  Other

  42623. packages will be used only if they are found.

  42624. 

  42625. Tools/Packages Necessary for Building GDB

  42626. =========================================

  42627. 

  42628. C++11 compiler

  42629.      GDB is written in C++11.  It should be buildable with any recent

  42630.      C++11 compiler, e.g. GCC.

  42631. 

  42632. GNU make

  42633.      GDB's build system relies on features only found in the GNU make

  42634.      program.  Other variants of 'make' will not work.

  42635. 

  42636. Tools/Packages Optional for Building GDB

  42637. ========================================

  42638. 

  42639. Expat

  42640.      GDB can use the Expat XML parsing library.  This library may be

  42641.      included with your operating system distribution; if it is not, you

  42642.      can get the latest version from <http://expat.sourceforge.net>.

  42643.      The 'configure' script will search for this library in several

  42644.      standard locations; if it is installed in an unusual path, you can

  42645.      use the '--with-libexpat-prefix' option to specify its location.

  42646. 

  42647.      Expat is used for:

  42648. 

  42649.         * Remote protocol memory maps (*note Memory Map Format::)

  42650.         * Target descriptions (*note Target Descriptions::)

  42651.         * Remote shared library lists (*Note Library List Format::, or

  42652.           alternatively *note Library List Format for SVR4 Targets::)

  42653.         * MS-Windows shared libraries (*note Shared Libraries::)

  42654.         * Traceframe info (*note Traceframe Info Format::)

  42655.         * Branch trace (*note Branch Trace Format::, *note Branch Trace

  42656.           Configuration Format::)

  42657. 

  42658. Guile

  42659.      GDB can be scripted using GNU Guile.  *Note Guile::.  By default,

  42660.      GDB will be compiled if the Guile libraries are installed and are

  42661.      found by 'configure'.  You can use the '--with-guile' option to

  42662.      request Guile, and pass either the Guile version number or the file

  42663.      name of the relevant 'pkg-config' program to choose a particular

  42664.      version of Guile.

  42665. 

  42666. iconv

  42667.      GDB's features related to character sets (*note Character Sets::)

  42668.      require a functioning 'iconv' implementation.  If you are on a GNU

  42669.      system, then this is provided by the GNU C Library.  Some other

  42670.      systems also provide a working 'iconv'.

  42671. 

  42672.      If GDB is using the 'iconv' program which is installed in a

  42673.      non-standard place, you will need to tell GDB where to find it.

  42674.      This is done with '--with-iconv-bin' which specifies the directory

  42675.      that contains the 'iconv' program.  This program is run in order to

  42676.      make a list of the available character sets.

  42677. 

  42678.      On systems without 'iconv', you can install GNU Libiconv.  If

  42679.      Libiconv is installed in a standard place, GDB will automatically

  42680.      use it if it is needed.  If you have previously installed Libiconv

  42681.      in a non-standard place, you can use the '--with-libiconv-prefix'

  42682.      option to 'configure'.

  42683. 

  42684.      GDB's top-level 'configure' and 'Makefile' will arrange to build

  42685.      Libiconv if a directory named 'libiconv' appears in the top-most

  42686.      source directory.  If Libiconv is built this way, and if the

  42687.      operating system does not provide a suitable 'iconv'

  42688.      implementation, then the just-built library will automatically be

  42689.      used by GDB.  One easy way to set this up is to download GNU

  42690.      Libiconv, unpack it inside the top-level directory of the GDB

  42691.      source tree, and then rename the directory holding the Libiconv

  42692.      source code to 'libiconv'.

  42693. 

  42694. lzma

  42695.      GDB can support debugging sections that are compressed with the

  42696.      LZMA library.  *Note MiniDebugInfo::.  If this library is not

  42697.      included with your operating system, you can find it in the xz

  42698.      package at <http://tukaani.org/xz/>.  If the LZMA library is

  42699.      available in the usual place, then the 'configure' script will use

  42700.      it automatically.  If it is installed in an unusual path, you can

  42701.      use the '--with-lzma-prefix' option to specify its location.

  42702. 

  42703. MPFR

  42704.      GDB can use the GNU MPFR multiple-precision floating-point library.

  42705.      This library may be included with your operating system

  42706.      distribution; if it is not, you can get the latest version from

  42707.      <http://www.mpfr.org>.  The 'configure' script will search for this

  42708.      library in several standard locations; if it is installed in an

  42709.      unusual path, you can use the '--with-libmpfr-prefix' option to

  42710.      specify its location.

  42711. 

  42712.      GNU MPFR is used to emulate target floating-point arithmetic during

  42713.      expression evaluation when the target uses different floating-point

  42714.      formats than the host.  If GNU MPFR it is not available, GDB will

  42715.      fall back to using host floating-point arithmetic.

  42716. 

  42717. Python

  42718.      GDB can be scripted using Python language.  *Note Python::.  By

  42719.      default, GDB will be compiled if the Python libraries are installed

  42720.      and are found by 'configure'.  You can use the '--with-python'

  42721.      option to request Python, and pass either the file name of the

  42722.      relevant 'python' executable, or the name of the directory in which

  42723.      Python is installed, to choose a particular installation of Python.

  42724. 

  42725. zlib

  42726.      GDB will use the 'zlib' library, if available, to read compressed

  42727.      debug sections.  Some linkers, such as GNU gold, are capable of

  42728.      producing binaries with compressed debug sections.  If GDB is

  42729.      compiled with 'zlib', it will be able to read the debug information

  42730.      in such binaries.

  42731. 

  42732.      The 'zlib' library is likely included with your operating system

  42733.      distribution; if it is not, you can get the latest version from

  42734.      <http://zlib.net>.

  42735. 

  42736. 

  42737. File: gdb.info,  Node: Running Configure,  Next: Separate Objdir,  Prev: Requirements,  Up: Installing GDB

  42738. 

  42739. C.2 Invoking the GDB 'configure' Script

  42740. =======================================

  42741. 

  42742. GDB comes with a 'configure' script that automates the process of

  42743. preparing GDB for installation; you can then use 'make' to build the

  42744. 'gdb' program.

  42745. 

  42746.    The GDB distribution includes all the source code you need for GDB in

  42747. a single directory, whose name is usually composed by appending the

  42748. version number to 'gdb'.

  42749. 

  42750.    For example, the GDB version 10.1.90.20201028-git distribution is in

  42751. the 'gdb-10.1.90.20201028-git' directory.  That directory contains:

  42752. 

  42753. 'gdb-10.1.90.20201028-git/configure (and supporting files)'

  42754.      script for configuring GDB and all its supporting libraries

  42755. 

  42756. 'gdb-10.1.90.20201028-git/gdb'

  42757.      the source specific to GDB itself

  42758. 

  42759. 'gdb-10.1.90.20201028-git/bfd'

  42760.      source for the Binary File Descriptor library

  42761. 

  42762. 'gdb-10.1.90.20201028-git/include'

  42763.      GNU include files

  42764. 

  42765. 'gdb-10.1.90.20201028-git/libiberty'

  42766.      source for the '-liberty' free software library

  42767. 

  42768. 'gdb-10.1.90.20201028-git/opcodes'

  42769.      source for the library of opcode tables and disassemblers

  42770. 

  42771. 'gdb-10.1.90.20201028-git/readline'

  42772.      source for the GNU command-line interface

  42773. 

  42774.    There may be other subdirectories as well.

  42775. 

  42776.    The simplest way to configure and build GDB is to run 'configure'

  42777. from the 'gdb-VERSION-NUMBER' source directory, which in this example is

  42778. the 'gdb-10.1.90.20201028-git' directory.

  42779. 

  42780.    First switch to the 'gdb-VERSION-NUMBER' source directory if you are

  42781. not already in it; then run 'configure'.  Pass the identifier for the

  42782. platform on which GDB will run as an argument.

  42783. 

  42784.    For example:

  42785. 

  42786.      cd gdb-10.1.90.20201028-git

  42787.      ./configure

  42788.      make

  42789. 

  42790.    Running 'configure' and then running 'make' builds the included

  42791. supporting libraries, then 'gdb' itself.  The configured source files,

  42792. and the binaries, are left in the corresponding source directories.

  42793. 

  42794.    'configure' is a Bourne-shell ('/bin/sh') script; if your system does

  42795. not recognize this automatically when you run a different shell, you may

  42796. need to run 'sh' on it explicitly:

  42797. 

  42798.      sh configure

  42799. 

  42800.    You should run the 'configure' script from the top directory in the

  42801. source tree, the 'gdb-VERSION-NUMBER' directory.  If you run 'configure'

  42802. from one of the subdirectories, you will configure only that

  42803. subdirectory.  That is usually not what you want.  In particular, if you

  42804. run the first 'configure' from the 'gdb' subdirectory of the

  42805. 'gdb-VERSION-NUMBER' directory, you will omit the configuration of

  42806. 'bfd', 'readline', and other sibling directories of the 'gdb'

  42807. subdirectory.  This leads to build errors about missing include files

  42808. such as 'bfd/bfd.h'.

  42809. 

  42810.    You can install 'GDB' anywhere.  The best way to do this is to pass

  42811. the '--prefix' option to 'configure', and then install it with 'make

  42812. install'.

  42813. 

  42814. 

  42815. File: gdb.info,  Node: Separate Objdir,  Next: Config Names,  Prev: Running Configure,  Up: Installing GDB

  42816. 

  42817. C.3 Compiling GDB in Another Directory

  42818. ======================================

  42819. 

  42820. If you want to run GDB versions for several host or target machines, you

  42821. need a different 'gdb' compiled for each combination of host and target.

  42822. 'configure' is designed to make this easy by allowing you to generate

  42823. each configuration in a separate subdirectory, rather than in the source

  42824. directory.  If your 'make' program handles the 'VPATH' feature (GNU

  42825. 'make' does), running 'make' in each of these directories builds the

  42826. 'gdb' program specified there.

  42827. 

  42828.    To build 'gdb' in a separate directory, run 'configure' with the

  42829. '--srcdir' option to specify where to find the source.  (You also need

  42830. to specify a path to find 'configure' itself from your working

  42831. directory.  If the path to 'configure' would be the same as the argument

  42832. to '--srcdir', you can leave out the '--srcdir' option; it is assumed.)

  42833. 

  42834.    For example, with version 10.1.90.20201028-git, you can build GDB in

  42835. a separate directory for a Sun 4 like this:

  42836. 

  42837.      cd gdb-10.1.90.20201028-git

  42838.      mkdir ../gdb-sun4

  42839.      cd ../gdb-sun4

  42840.      ../gdb-10.1.90.20201028-git/configure

  42841.      make

  42842. 

  42843.    When 'configure' builds a configuration using a remote source

  42844. directory, it creates a tree for the binaries with the same structure

  42845. (and using the same names) as the tree under the source directory.  In

  42846. the example, you'd find the Sun 4 library 'libiberty.a' in the directory

  42847. 'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'.

  42848. 

  42849.    Make sure that your path to the 'configure' script has just one

  42850. instance of 'gdb' in it.  If your path to 'configure' looks like

  42851. '../gdb-10.1.90.20201028-git/gdb/configure', you are configuring only

  42852. one subdirectory of GDB, not the whole package.  This leads to build

  42853. errors about missing include files such as 'bfd/bfd.h'.

  42854. 

  42855.    One popular reason to build several GDB configurations in separate

  42856. directories is to configure GDB for cross-compiling (where GDB runs on

  42857. one machine--the "host"--while debugging programs that run on another

  42858. machine--the "target").  You specify a cross-debugging target by giving

  42859. the '--target=TARGET' option to 'configure'.

  42860. 

  42861.    When you run 'make' to build a program or library, you must run it in

  42862. a configured directory--whatever directory you were in when you called

  42863. 'configure' (or one of its subdirectories).

  42864. 

  42865.    The 'Makefile' that 'configure' generates in each source directory

  42866. also runs recursively.  If you type 'make' in a source directory such as

  42867. 'gdb-10.1.90.20201028-git' (or in a separate configured directory

  42868. configured with '--srcdir=DIRNAME/gdb-10.1.90.20201028-git'), you will

  42869. build all the required libraries, and then build GDB.

  42870. 

  42871.    When you have multiple hosts or targets configured in separate

  42872. directories, you can run 'make' on them in parallel (for example, if

  42873. they are NFS-mounted on each of the hosts); they will not interfere with

  42874. each other.

  42875. 

  42876. 

  42877. File: gdb.info,  Node: Config Names,  Next: Configure Options,  Prev: Separate Objdir,  Up: Installing GDB

  42878. 

  42879. C.4 Specifying Names for Hosts and Targets

  42880. ==========================================

  42881. 

  42882. The specifications used for hosts and targets in the 'configure' script

  42883. are based on a three-part naming scheme, but some short predefined

  42884. aliases are also supported.  The full naming scheme encodes three pieces

  42885. of information in the following pattern:

  42886. 

  42887.      ARCHITECTURE-VENDOR-OS

  42888. 

  42889.    For example, you can use the alias 'sun4' as a HOST argument, or as

  42890. the value for TARGET in a '--target=TARGET' option.  The equivalent full

  42891. name is 'sparc-sun-sunos4'.

  42892. 

  42893.    The 'configure' script accompanying GDB does not provide any query

  42894. facility to list all supported host and target names or aliases.

  42895. 'configure' calls the Bourne shell script 'config.sub' to map

  42896. abbreviations to full names; you can read the script, if you wish, or

  42897. you can use it to test your guesses on abbreviations--for example:

  42898. 

  42899.      % sh config.sub i386-linux

  42900.      i386-pc-linux-gnu

  42901.      % sh config.sub alpha-linux

  42902.      alpha-unknown-linux-gnu

  42903.      % sh config.sub hp9k700

  42904.      hppa1.1-hp-hpux

  42905.      % sh config.sub sun4

  42906.      sparc-sun-sunos4.1.1

  42907.      % sh config.sub sun3

  42908.      m68k-sun-sunos4.1.1

  42909.      % sh config.sub i986v

  42910.      Invalid configuration `i986v': machine `i986v' not recognized

  42911. 

  42912. 'config.sub' is also distributed in the GDB source directory

  42913. ('gdb-10.1.90.20201028-git', for version 10.1.90.20201028-git).

  42914. 

  42915. 

  42916. File: gdb.info,  Node: Configure Options,  Next: System-wide configuration,  Prev: Config Names,  Up: Installing GDB

  42917. 

  42918. C.5 'configure' Options

  42919. =======================

  42920. 

  42921. Here is a summary of the 'configure' options and arguments that are most

  42922. often useful for building GDB.  'configure' also has several other

  42923. options not listed here.  *note (autoconf.info)Running configure

  42924. scripts::, for a full explanation of 'configure'.

  42925. 

  42926.      configure [--help]

  42927.                [--prefix=DIR]

  42928.                [--exec-prefix=DIR]

  42929.                [--srcdir=DIRNAME]

  42930.                [--target=TARGET]

  42931. 

  42932. You may introduce options with a single '-' rather than '--' if you

  42933. prefer; but you may abbreviate option names if you use '--'.

  42934. 

  42935. '--help'

  42936.      Display a quick summary of how to invoke 'configure'.

  42937. 

  42938. '--prefix=DIR'

  42939.      Configure the source to install programs and files under directory

  42940.      'DIR'.

  42941. 

  42942. '--exec-prefix=DIR'

  42943.      Configure the source to install programs under directory 'DIR'.

  42944. 

  42945. '--srcdir=DIRNAME'

  42946.      Use this option to make configurations in directories separate from

  42947.      the GDB source directories.  Among other things, you can use this

  42948.      to build (or maintain) several configurations simultaneously, in

  42949.      separate directories.  'configure' writes configuration-specific

  42950.      files in the current directory, but arranges for them to use the

  42951.      source in the directory DIRNAME.  'configure' creates directories

  42952.      under the working directory in parallel to the source directories

  42953.      below DIRNAME.

  42954. 

  42955. '--target=TARGET'

  42956.      Configure GDB for cross-debugging programs running on the specified

  42957.      TARGET.  Without this option, GDB is configured to debug programs

  42958.      that run on the same machine (HOST) as GDB itself.

  42959. 

  42960.      There is no convenient way to generate a list of all available

  42961.      targets.  Also see the '--enable-targets' option, below.

  42962. 

  42963.    There are many other options that are specific to GDB.  This lists

  42964. just the most common ones; there are some very specialized options not

  42965. described here.

  42966. 

  42967. '--enable-targets=[TARGET]...'

  42968. '--enable-targets=all'

  42969.      Configure GDB for cross-debugging programs running on the specified

  42970.      list of targets.  The special value 'all' configures GDB for

  42971.      debugging programs running on any target it supports.

  42972. 

  42973. '--with-gdb-datadir=PATH'

  42974.      Set the GDB-specific data directory.  GDB will look here for

  42975.      certain supporting files or scripts.  This defaults to the 'gdb'

  42976.      subdirectory of 'datadir' (which can be set using '--datadir').

  42977. 

  42978. '--with-relocated-sources=DIR'

  42979.      Sets up the default source path substitution rule so that directory

  42980.      names recorded in debug information will be automatically adjusted

  42981.      for any directory under DIR.  DIR should be a subdirectory of GDB's

  42982.      configured prefix, the one mentioned in the '--prefix' or

  42983.      '--exec-prefix' options to configure.  This option is useful if GDB

  42984.      is supposed to be moved to a different place after it is built.

  42985. 

  42986. '--enable-64-bit-bfd'

  42987.      Enable 64-bit support in BFD on 32-bit hosts.

  42988. 

  42989. '--disable-gdbmi'

  42990.      Build GDB without the GDB/MI machine interface (*note GDB/MI::).

  42991. 

  42992. '--enable-tui'

  42993.      Build GDB with the text-mode full-screen user interface (TUI).

  42994.      Requires a curses library (ncurses and cursesX are also supported).

  42995. 

  42996. '--with-curses'

  42997.      Use the curses library instead of the termcap library, for

  42998.      text-mode terminal operations.

  42999. 

  43000. '--with-debuginfod'

  43001.      Build GDB with libdebuginfod, the debuginfod client library.  Used

  43002.      to automatically fetch source files and separate debug files from

  43003.      debuginfod servers using the associated executable's build ID.

  43004.      Enabled by default if libdebuginfod is installed and found at

  43005.      configure time.  debuginfod is packaged with elfutils, starting

  43006.      with version 0.178.  You can get the latest version from

  43007.      'https://sourceware.org/elfutils/'.

  43008. 

  43009. '--with-libunwind-ia64'

  43010.      Use the libunwind library for unwinding function call stack on ia64

  43011.      target platforms.  See http://www.nongnu.org/libunwind/index.html

  43012.      for details.

  43013. 

  43014. '--with-system-readline'

  43015.      Use the readline library installed on the host, rather than the

  43016.      library supplied as part of GDB.  Readline 7 or newer is required;

  43017.      this is enforced by the build system.

  43018. 

  43019. '--with-system-zlib'

  43020.      Use the zlib library installed on the host, rather than the library

  43021.      supplied as part of GDB.

  43022. 

  43023. '--with-expat'

  43024.      Build GDB with Expat, a library for XML parsing.  (Done by default

  43025.      if libexpat is installed and found at configure time.)  This

  43026.      library is used to read XML files supplied with GDB.  If it is

  43027.      unavailable, some features, such as remote protocol memory maps,

  43028.      target descriptions, and shared library lists, that are based on

  43029.      XML files, will not be available in GDB.  If your host does not

  43030.      have libexpat installed, you can get the latest version from

  43031.      'http://expat.sourceforge.net'.

  43032. 

  43033. '--with-libiconv-prefix[=DIR]'

  43034. 

  43035.      Build GDB with GNU libiconv, a character set encoding conversion

  43036.      library.  This is not done by default, as on GNU systems the

  43037.      'iconv' that is built in to the C library is sufficient.  If your

  43038.      host does not have a working 'iconv', you can get the latest

  43039.      version of GNU iconv from 'https://www.gnu.org/software/libiconv/'.

  43040. 

  43041.      GDB's build system also supports building GNU libiconv as part of

  43042.      the overall build.  *Note Requirements::.

  43043. 

  43044. '--with-lzma'

  43045.      Build GDB with LZMA, a compression library.  (Done by default if

  43046.      liblzma is installed and found at configure time.)  LZMA is used by

  43047.      GDB's "mini debuginfo" feature, which is only useful on platforms

  43048.      using the ELF object file format.  If your host does not have

  43049.      liblzma installed, you can get the latest version from

  43050.      'https://tukaani.org/xz/'.

  43051. 

  43052. '--with-mpfr'

  43053.      Build GDB with GNU MPFR, a library for multiple-precision

  43054.      floating-point computation with correct rounding.  (Done by default

  43055.      if GNU MPFR is installed and found at configure time.)  This

  43056.      library is used to emulate target floating-point arithmetic during

  43057.      expression evaluation when the target uses different floating-point

  43058.      formats than the host.  If GNU MPFR is not available, GDB will fall

  43059.      back to using host floating-point arithmetic.  If your host does

  43060.      not have GNU MPFR installed, you can get the latest version from

  43061.      'http://www.mpfr.org'.

  43062. 

  43063. '--with-python[=PYTHON]'

  43064.      Build GDB with Python scripting support.  (Done by default if

  43065.      libpython is present and found at configure time.)  Python makes

  43066.      GDB scripting much more powerful than the restricted CLI scripting

  43067.      language.  If your host does not have Python installed, you can

  43068.      find it on 'http://www.python.org/download/'.  The oldest version

  43069.      of Python supported by GDB is 2.6.  The optional argument PYTHON is

  43070.      used to find the Python headers and libraries.  It can be either

  43071.      the name of a Python executable, or the name of the directory in

  43072.      which Python is installed.

  43073. 

  43074. '--with-guile[=GUILE]''

  43075.      Build GDB with GNU Guile scripting support.  (Done by default if

  43076.      libguile is present and found at configure time.)  If your host

  43077.      does not have Guile installed, you can find it at

  43078.      'https://www.gnu.org/software/guile/'.  The optional argument GUILE

  43079.      can be a version number, which will cause 'configure' to try to use

  43080.      that version of Guile; or the file name of a 'pkg-config'

  43081.      executable, which will be queried to find the information needed to

  43082.      compile and link against Guile.

  43083. 

  43084. '--without-included-regex'

  43085.      Don't use the regex library included with GDB (as part of the

  43086.      libiberty library).  This is the default on hosts with version 2 of

  43087.      the GNU C library.

  43088. 

  43089. '--with-sysroot=DIR'

  43090.      Use DIR as the default system root directory for libraries whose

  43091.      file names begin with '/lib'' or '/usr/lib''.  (The value of DIR

  43092.      can be modified at run time by using the 'set sysroot' command.)

  43093.      If DIR is under the GDB configured prefix (set with '--prefix' or

  43094.      '--exec-prefix options', the default system root will be

  43095.      automatically adjusted if and when GDB is moved to a different

  43096.      location.

  43097. 

  43098. '--with-system-gdbinit=FILE'

  43099.      Configure GDB to automatically load a system-wide init file.  FILE

  43100.      should be an absolute file name.  If FILE is in a directory under

  43101.      the configured prefix, and GDB is moved to another location after

  43102.      being built, the location of the system-wide init file will be

  43103.      adjusted accordingly.

  43104. 

  43105. '--with-system-gdbinit-dir=DIRECTORY'

  43106.      Configure GDB to automatically load init files from a system-wide

  43107.      directory.  DIRECTORY should be an absolute directory name.  If

  43108.      DIRECTORY is in a directory under the configured prefix, and GDB is

  43109.      moved to another location after being built, the location of the

  43110.      system-wide init directory will be adjusted accordingly.

  43111. 

  43112. '--enable-build-warnings'

  43113.      When building the GDB sources, ask the compiler to warn about any

  43114.      code which looks even vaguely suspicious.  It passes many different

  43115.      warning flags, depending on the exact version of the compiler you

  43116.      are using.

  43117. 

  43118. '--enable-werror'

  43119.      Treat compiler warnings as werrors.  It adds the '-Werror' flag to

  43120.      the compiler, which will fail the compilation if the compiler

  43121.      outputs any warning messages.

  43122. 

  43123. '--enable-ubsan'

  43124.      Enable the GCC undefined behavior sanitizer.  This is disabled by

  43125.      default, but passing '--enable-ubsan=yes' or '--enable-ubsan=auto'

  43126.      to 'configure' will enable it.  The undefined behavior sanitizer

  43127.      checks for C++ undefined behavior.  It has a performance cost, so

  43128.      if you are looking at GDB's performance, you should disable it.

  43129.      The undefined behavior sanitizer was first introduced in GCC 4.9.

  43130. 

  43131. 

  43132. File: gdb.info,  Node: System-wide configuration,  Prev: Configure Options,  Up: Installing GDB

  43133. 

  43134. C.6 System-wide configuration and settings

  43135. ==========================================

  43136. 

  43137. GDB can be configured to have a system-wide init file and a system-wide

  43138. init file directory; this file and files in that directory (if they have

  43139. a recognized file extension) will be read and executed at startup (*note

  43140. What GDB does during startup: Startup.).

  43141. 

  43142.    Here are the corresponding configure options:

  43143. 

  43144. '--with-system-gdbinit=FILE'

  43145.      Specify that the default location of the system-wide init file is

  43146.      FILE.

  43147. '--with-system-gdbinit-dir=DIRECTORY'

  43148.      Specify that the default location of the system-wide init file

  43149.      directory is DIRECTORY.

  43150. 

  43151.    If GDB has been configured with the option '--prefix=$prefix', they

  43152. may be subject to relocation.  Two possible cases:

  43153. 

  43154.    * If the default location of this init file/directory contains

  43155.      '$prefix', it will be subject to relocation.  Suppose that the

  43156.      configure options are '--prefix=$prefix

  43157.      --with-system-gdbinit=$prefix/etc/gdbinit'; if GDB is moved from

  43158.      '$prefix' to '$install', the system init file is looked for as

  43159.      '$install/etc/gdbinit' instead of '$prefix/etc/gdbinit'.

  43160. 

  43161.    * By contrast, if the default location does not contain the prefix,

  43162.      it will not be relocated.  E.g. if GDB has been configured with

  43163.      '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',

  43164.      then GDB will always look for '/usr/share/gdb/gdbinit', wherever

  43165.      GDB is installed.

  43166. 

  43167.    If the configured location of the system-wide init file (as given by

  43168. the '--with-system-gdbinit' option at configure time) is in the

  43169. data-directory (as specified by '--with-gdb-datadir' at configure time)

  43170. or in one of its subdirectories, then GDB will look for the system-wide

  43171. init file in the directory specified by the '--data-directory'

  43172. command-line option.  Note that the system-wide init file is only read

  43173. once, during GDB initialization.  If the data-directory is changed after

  43174. GDB has started with the 'set data-directory' command, the file will not

  43175. be reread.

  43176. 

  43177.    This applies similarly to the system-wide directory specified in

  43178. '--with-system-gdbinit-dir'.

  43179. 

  43180.    Any supported scripting language can be used for these init files, as

  43181. long as the file extension matches the scripting language.  To be

  43182. interpreted as regular GDB commands, the files needs to have a '.gdb'

  43183. extension.

  43184. 

  43185. * Menu:

  43186. 

  43187. * System-wide Configuration Scripts::  Installed System-wide Configuration Scripts

  43188. 

  43189. 

  43190. File: gdb.info,  Node: System-wide Configuration Scripts,  Up: System-wide configuration

  43191. 

  43192. C.6.1 Installed System-wide Configuration Scripts

  43193. -------------------------------------------------

  43194. 

  43195. The 'system-gdbinit' directory, located inside the data-directory (as

  43196. specified by '--with-gdb-datadir' at configure time) contains a number

  43197. of scripts which can be used as system-wide init files.  To

  43198. automatically source those scripts at startup, GDB should be configured

  43199. with '--with-system-gdbinit'.  Otherwise, any user should be able to

  43200. source them by hand as needed.

  43201. 

  43202.    The following scripts are currently available:

  43203. 

  43204.    * 'elinos.py' This script is useful when debugging a program on an

  43205.      ELinOS target.  It takes advantage of the environment variables

  43206.      defined in a standard ELinOS environment in order to determine the

  43207.      location of the system shared libraries, and then sets the

  43208.      'solib-absolute-prefix' and 'solib-search-path' variables

  43209.      appropriately.

  43210. 

  43211.    * 'wrs-linux.py' This script is useful when debugging a program on a

  43212.      target running Wind River Linux.  It expects the 'ENV_PREFIX' to be

  43213.      set to the host-side sysroot used by the target system.

  43214. 

  43215. 

  43216. File: gdb.info,  Node: Maintenance Commands,  Next: Remote Protocol,  Prev: Installing GDB,  Up: Top

  43217. 

  43218. Appendix D Maintenance Commands

  43219. *******************************

  43220. 

  43221. In addition to commands intended for GDB users, GDB includes a number of

  43222. commands intended for GDB developers, that are not documented elsewhere

  43223. in this manual.  These commands are provided here for reference.  (For

  43224. commands that turn on debugging messages, see *note Debugging Output::.)

  43225. 

  43226. 'maint agent [-at LOCATION,] EXPRESSION'

  43227. 'maint agent-eval [-at LOCATION,] EXPRESSION'

  43228.      Translate the given EXPRESSION into remote agent bytecodes.  This

  43229.      command is useful for debugging the Agent Expression mechanism

  43230.      (*note Agent Expressions::).  The 'agent' version produces an

  43231.      expression useful for data collection, such as by tracepoints,

  43232.      while 'maint agent-eval' produces an expression that evaluates

  43233.      directly to a result.  For instance, a collection expression for

  43234.      'globa + globb' will include bytecodes to record four bytes of

  43235.      memory at each of the addresses of 'globa' and 'globb', while

  43236.      discarding the result of the addition, while an evaluation

  43237.      expression will do the addition and return the sum.  If '-at' is

  43238.      given, generate remote agent bytecode for LOCATION.  If not,

  43239.      generate remote agent bytecode for current frame PC address.

  43240. 

  43241. 'maint agent-printf FORMAT,EXPR,...'

  43242.      Translate the given format string and list of argument expressions

  43243.      into remote agent bytecodes and display them as a disassembled

  43244.      list.  This command is useful for debugging the agent version of

  43245.      dynamic printf (*note Dynamic Printf::).

  43246. 

  43247. 'maint info breakpoints'

  43248.      Using the same format as 'info breakpoints', display both the

  43249.      breakpoints you've set explicitly, and those GDB is using for

  43250.      internal purposes.  Internal breakpoints are shown with negative

  43251.      breakpoint numbers.  The type column identifies what kind of

  43252.      breakpoint is shown:

  43253. 

  43254.      'breakpoint'

  43255.           Normal, explicitly set breakpoint.

  43256. 

  43257.      'watchpoint'

  43258.           Normal, explicitly set watchpoint.

  43259. 

  43260.      'longjmp'

  43261.           Internal breakpoint, used to handle correctly stepping through

  43262.           'longjmp' calls.

  43263. 

  43264.      'longjmp resume'

  43265.           Internal breakpoint at the target of a 'longjmp'.

  43266. 

  43267.      'until'

  43268.           Temporary internal breakpoint used by the GDB 'until' command.

  43269. 

  43270.      'finish'

  43271.           Temporary internal breakpoint used by the GDB 'finish'

  43272.           command.

  43273. 

  43274.      'shlib events'

  43275.           Shared library events.

  43276. 

  43277. 'maint info btrace'

  43278.      Pint information about raw branch tracing data.

  43279. 

  43280. 'maint btrace packet-history'

  43281.      Print the raw branch trace packets that are used to compute the

  43282.      execution history for the 'record btrace' command.  Both the

  43283.      information and the format in which it is printed depend on the

  43284.      btrace recording format.

  43285. 

  43286.      'bts'

  43287.           For the BTS recording format, print a list of blocks of

  43288.           sequential code.  For each block, the following information is

  43289.           printed:

  43290. 

  43291.           Block number

  43292.                Newer blocks have higher numbers.  The oldest block has

  43293.                number zero.

  43294.           Lowest 'PC'

  43295.           Highest 'PC'

  43296. 

  43297.      'pt'

  43298.           For the Intel Processor Trace recording format, print a list

  43299.           of Intel Processor Trace packets.  For each packet, the

  43300.           following information is printed:

  43301. 

  43302.           Packet number

  43303.                Newer packets have higher numbers.  The oldest packet has

  43304.                number zero.

  43305.           Trace offset

  43306.                The packet's offset in the trace stream.

  43307.           Packet opcode and payload

  43308. 

  43309. 'maint btrace clear-packet-history'

  43310.      Discards the cached packet history printed by the 'maint btrace

  43311.      packet-history' command.  The history will be computed again when

  43312.      needed.

  43313. 

  43314. 'maint btrace clear'

  43315.      Discard the branch trace data.  The data will be fetched anew and

  43316.      the branch trace will be recomputed when needed.

  43317. 

  43318.      This implicitly truncates the branch trace to a single branch trace

  43319.      buffer.  When updating branch trace incrementally, the branch trace

  43320.      available to GDB may be bigger than a single branch trace buffer.

  43321. 

  43322. 'maint set btrace pt skip-pad'

  43323. 'maint show btrace pt skip-pad'

  43324.      Control whether GDB will skip PAD packets when computing the packet

  43325.      history.

  43326. 

  43327. 'set displaced-stepping'

  43328. 'show displaced-stepping'

  43329.      Control whether or not GDB will do "displaced stepping" if the

  43330.      target supports it.  Displaced stepping is a way to single-step

  43331.      over breakpoints without removing them from the inferior, by

  43332.      executing an out-of-line copy of the instruction that was

  43333.      originally at the breakpoint location.  It is also known as

  43334.      out-of-line single-stepping.

  43335. 

  43336.      'set displaced-stepping on'

  43337.           If the target architecture supports it, GDB will use displaced

  43338.           stepping to step over breakpoints.

  43339. 

  43340.      'set displaced-stepping off'

  43341.           GDB will not use displaced stepping to step over breakpoints,

  43342.           even if such is supported by the target architecture.

  43343. 

  43344.      'set displaced-stepping auto'

  43345.           This is the default mode.  GDB will use displaced stepping

  43346.           only if non-stop mode is active (*note Non-Stop Mode::) and

  43347.           the target architecture supports displaced stepping.

  43348. 

  43349. 'maint check-psymtabs'

  43350.      Check the consistency of currently expanded psymtabs versus

  43351.      symtabs.  Use this to check, for example, whether a symbol is in

  43352.      one but not the other.

  43353. 

  43354. 'maint check-symtabs'

  43355.      Check the consistency of currently expanded symtabs.

  43356. 

  43357. 'maint expand-symtabs [REGEXP]'

  43358.      Expand symbol tables.  If REGEXP is specified, only expand symbol

  43359.      tables for file names matching REGEXP.

  43360. 

  43361. 'maint set catch-demangler-crashes [on|off]'

  43362. 'maint show catch-demangler-crashes'

  43363.      Control whether GDB should attempt to catch crashes in the symbol

  43364.      name demangler.  The default is to attempt to catch crashes.  If

  43365.      enabled, the first time a crash is caught, a core file is created,

  43366.      the offending symbol is displayed and the user is presented with

  43367.      the option to terminate the current session.

  43368. 

  43369. 'maint cplus first_component NAME'

  43370.      Print the first C++ class/namespace component of NAME.

  43371. 

  43372. 'maint cplus namespace'

  43373.      Print the list of possible C++ namespaces.

  43374. 

  43375. 'maint deprecate COMMAND [REPLACEMENT]'

  43376. 'maint undeprecate COMMAND'

  43377.      Deprecate or undeprecate the named COMMAND.  Deprecated commands

  43378.      cause GDB to issue a warning when you use them.  The optional

  43379.      argument REPLACEMENT says which newer command should be used in

  43380.      favor of the deprecated one; if it is given, GDB will mention the

  43381.      replacement as part of the warning.

  43382. 

  43383. 'maint dump-me'

  43384.      Cause a fatal signal in the debugger and force it to dump its core.

  43385.      This is supported only on systems which support aborting a program

  43386.      with the 'SIGQUIT' signal.

  43387. 

  43388. 'maint internal-error [MESSAGE-TEXT]'

  43389. 'maint internal-warning [MESSAGE-TEXT]'

  43390. 'maint demangler-warning [MESSAGE-TEXT]'

  43391. 

  43392.      Cause GDB to call the internal function 'internal_error',

  43393.      'internal_warning' or 'demangler_warning' and hence behave as

  43394.      though an internal problem has been detected.  In addition to

  43395.      reporting the internal problem, these functions give the user the

  43396.      opportunity to either quit GDB or (for 'internal_error' and

  43397.      'internal_warning') create a core file of the current GDB session.

  43398. 

  43399.      These commands take an optional parameter MESSAGE-TEXT that is used

  43400.      as the text of the error or warning message.

  43401. 

  43402.      Here's an example of using 'internal-error':

  43403. 

  43404.           (gdb) maint internal-error testing, 1, 2

  43405.           .../maint.c:121: internal-error: testing, 1, 2

  43406.           A problem internal to GDB has been detected.  Further

  43407.           debugging may prove unreliable.

  43408.           Quit this debugging session? (y or n) n

  43409.           Create a core file? (y or n) n

  43410.           (gdb)

  43411. 

  43412. 'maint set internal-error ACTION [ask|yes|no]'

  43413. 'maint show internal-error ACTION'

  43414. 'maint set internal-warning ACTION [ask|yes|no]'

  43415. 'maint show internal-warning ACTION'

  43416. 'maint set demangler-warning ACTION [ask|yes|no]'

  43417. 'maint show demangler-warning ACTION'

  43418.      When GDB reports an internal problem (error or warning) it gives

  43419.      the user the opportunity to both quit GDB and create a core file of

  43420.      the current GDB session.  These commands let you override the

  43421.      default behaviour for each particular ACTION, described in the

  43422.      table below.

  43423. 

  43424.      'quit'

  43425.           You can specify that GDB should always (yes) or never (no)

  43426.           quit.  The default is to ask the user what to do.

  43427. 

  43428.      'corefile'

  43429.           You can specify that GDB should always (yes) or never (no)

  43430.           create a core file.  The default is to ask the user what to

  43431.           do.  Note that there is no 'corefile' option for

  43432.           'demangler-warning': demangler warnings always create a core

  43433.           file and this cannot be disabled.

  43434. 

  43435. 'maint packet TEXT'

  43436.      If GDB is talking to an inferior via the serial protocol, then this

  43437.      command sends the string TEXT to the inferior, and displays the

  43438.      response packet.  GDB supplies the initial '$' character, the

  43439.      terminating '#' character, and the checksum.

  43440. 

  43441. 'maint print architecture [FILE]'

  43442.      Print the entire architecture configuration.  The optional argument

  43443.      FILE names the file where the output goes.

  43444. 

  43445. 'maint print c-tdesc'

  43446.      Print the target description (*note Target Descriptions::) as a C

  43447.      source file.  By default, the target description is for the current

  43448.      target, but if the optional argument FILE is provided, that file is

  43449.      used to produce the description.  The FILE should be an XML

  43450.      document, of the form described in *note Target Description

  43451.      Format::.  The created source file is built into GDB when GDB is

  43452.      built again.  This command is used by developers after they add or

  43453.      modify XML target descriptions.

  43454. 

  43455. 'maint print xml-tdesc [FILE]'

  43456.      Print the target description (*note Target Descriptions::) as an

  43457.      XML file.  By default print the target description for the current

  43458.      target, but if the optional argument FILE is provided, then that

  43459.      file is read in by GDB and then used to produce the description.

  43460.      The FILE should be an XML document, of the form described in *note

  43461.      Target Description Format::.

  43462. 

  43463. 'maint check xml-descriptions DIR'

  43464.      Check that the target descriptions dynamically created by GDB equal

  43465.      the descriptions created from XML files found in DIR.

  43466. 

  43467. 'maint check libthread-db'

  43468.      Run integrity checks on the current inferior's thread debugging

  43469.      library.  This exercises all 'libthread_db' functionality used by

  43470.      GDB on GNU/Linux systems, and by extension also exercises the

  43471.      'proc_service' functions provided by GDB that 'libthread_db' uses.

  43472.      Note that parts of the test may be skipped on some platforms when

  43473.      debugging core files.

  43474. 

  43475. 'maint print core-file-backed-mappings'

  43476.      Print the file-backed mappings which were loaded from a core file

  43477.      note.  This output represents state internal to GDB and should be

  43478.      similar to the mappings displayed by the 'info proc mappings'

  43479.      command.

  43480. 

  43481. 'maint print dummy-frames'

  43482.      Prints the contents of GDB's internal dummy-frame stack.

  43483. 

  43484.           (gdb) b add

  43485.           ...

  43486.           (gdb) print add(2,3)

  43487.           Breakpoint 2, add (a=2, b=3) at ...

  43488.           58	  return (a + b);

  43489.           The program being debugged stopped while in a function called from GDB.

  43490.           ...

  43491.           (gdb) maint print dummy-frames

  43492.           0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353

  43493.           (gdb)

  43494. 

  43495.      Takes an optional file parameter.

  43496. 

  43497. 'maint print registers [FILE]'

  43498. 'maint print raw-registers [FILE]'

  43499. 'maint print cooked-registers [FILE]'

  43500. 'maint print register-groups [FILE]'

  43501. 'maint print remote-registers [FILE]'

  43502.      Print GDB's internal register data structures.

  43503. 

  43504.      The command 'maint print raw-registers' includes the contents of

  43505.      the raw register cache; the command 'maint print cooked-registers'

  43506.      includes the (cooked) value of all registers, including registers

  43507.      which aren't available on the target nor visible to user; the

  43508.      command 'maint print register-groups' includes the groups that each

  43509.      register is a member of; and the command 'maint print

  43510.      remote-registers' includes the remote target's register numbers and

  43511.      offsets in the 'G' packets.

  43512. 

  43513.      These commands take an optional parameter, a file name to which to

  43514.      write the information.

  43515. 

  43516. 'maint print reggroups [FILE]'

  43517.      Print GDB's internal register group data structures.  The optional

  43518.      argument FILE tells to what file to write the information.

  43519. 

  43520.      The register groups info looks like this:

  43521. 

  43522.           (gdb) maint print reggroups

  43523.            Group      Type

  43524.            general    user

  43525.            float      user

  43526.            all        user

  43527.            vector     user

  43528.            system     user

  43529.            save       internal

  43530.            restore    internal

  43531. 

  43532. 'flushregs'

  43533.      This command forces GDB to flush its internal register cache.

  43534. 

  43535. 'maint print objfiles [REGEXP]'

  43536.      Print a dump of all known object files.  If REGEXP is specified,

  43537.      only print object files whose names match REGEXP.  For each object

  43538.      file, this command prints its name, address in memory, and all of

  43539.      its psymtabs and symtabs.

  43540. 

  43541. 'maint print user-registers'

  43542.      List all currently available "user registers".  User registers

  43543.      typically provide alternate names for actual hardware registers.

  43544.      They include the four "standard" registers '$fp', '$pc', '$sp', and

  43545.      '$ps'.  *Note standard registers::.  User registers can be used in

  43546.      expressions in the same way as the canonical register names, but

  43547.      only the latter are listed by the 'info registers' and 'maint print

  43548.      registers' commands.

  43549. 

  43550. 'maint print section-scripts [REGEXP]'

  43551.      Print a dump of scripts specified in the '.debug_gdb_section'

  43552.      section.  If REGEXP is specified, only print scripts loaded by

  43553.      object files matching REGEXP.  For each script, this command prints

  43554.      its name as specified in the objfile, and the full path if known.

  43555.      *Note dotdebug_gdb_scripts section::.

  43556. 

  43557. 'maint print statistics'

  43558.      This command prints, for each object file in the program, various

  43559.      data about that object file followed by the byte cache ("bcache")

  43560.      statistics for the object file.  The objfile data includes the

  43561.      number of minimal, partial, full, and stabs symbols, the number of

  43562.      types defined by the objfile, the number of as yet unexpanded psym

  43563.      tables, the number of line tables and string tables, and the amount

  43564.      of memory used by the various tables.  The bcache statistics

  43565.      include the counts, sizes, and counts of duplicates of all and

  43566.      unique objects, max, average, and median entry size, total memory

  43567.      used and its overhead and savings, and various measures of the hash

  43568.      table size and chain lengths.

  43569. 

  43570. 'maint print target-stack'

  43571.      A "target" is an interface between the debugger and a particular

  43572.      kind of file or process.  Targets can be stacked in "strata", so

  43573.      that more than one target can potentially respond to a request.  In

  43574.      particular, memory accesses will walk down the stack of targets

  43575.      until they find a target that is interested in handling that

  43576.      particular address.

  43577. 

  43578.      This command prints a short description of each layer that was

  43579.      pushed on the "target stack", starting from the top layer down to

  43580.      the bottom one.

  43581. 

  43582. 'maint print type EXPR'

  43583.      Print the type chain for a type specified by EXPR.  The argument

  43584.      can be either a type name or a symbol.  If it is a symbol, the type

  43585.      of that symbol is described.  The type chain produced by this

  43586.      command is a recursive definition of the data type as stored in

  43587.      GDB's data structures, including its flags and contained types.

  43588. 

  43589. 'maint selftest [FILTER]'

  43590.      Run any self tests that were compiled in to GDB.  This will print a

  43591.      message showing how many tests were run, and how many failed.  If a

  43592.      FILTER is passed, only the tests with FILTER in their name will by

  43593.      ran.

  43594. 

  43595. 'maint info selftests'

  43596.      List the selftests compiled in to GDB.

  43597. 

  43598. 'maint set dwarf always-disassemble'

  43599. 'maint show dwarf always-disassemble'

  43600.      Control the behavior of 'info address' when using DWARF debugging

  43601.      information.

  43602. 

  43603.      The default is 'off', which means that GDB should try to describe a

  43604.      variable's location in an easily readable format.  When 'on', GDB

  43605.      will instead display the DWARF location expression in an

  43606.      assembly-like format.  Note that some locations are too complex for

  43607.      GDB to describe simply; in this case you will always see the

  43608.      disassembly form.

  43609. 

  43610.      Here is an example of the resulting disassembly:

  43611. 

  43612.           (gdb) info addr argc

  43613.           Symbol "argc" is a complex DWARF expression:

  43614.                1: DW_OP_fbreg 0

  43615. 

  43616.      For more information on these expressions, see the DWARF standard

  43617.      (http://www.dwarfstd.org/).

  43618. 

  43619. 'maint set dwarf max-cache-age'

  43620. 'maint show dwarf max-cache-age'

  43621.      Control the DWARF compilation unit cache.

  43622. 

  43623.      In object files with inter-compilation-unit references, such as

  43624.      those produced by the GCC option '-feliminate-dwarf2-dups', the

  43625.      DWARF reader needs to frequently refer to previously read

  43626.      compilation units.  This setting controls how long a compilation

  43627.      unit will remain in the cache if it is not referenced.  A higher

  43628.      limit means that cached compilation units will be stored in memory

  43629.      longer, and more total memory will be used.  Setting it to zero

  43630.      disables caching, which will slow down GDB startup, but reduce

  43631.      memory consumption.

  43632. 

  43633. 'maint set dwarf unwinders'

  43634. 'maint show dwarf unwinders'

  43635.      Control use of the DWARF frame unwinders.

  43636. 

  43637.      Many targets that support DWARF debugging use GDB's DWARF frame

  43638.      unwinders to build the backtrace.  Many of these targets will also

  43639.      have a second mechanism for building the backtrace for use in cases

  43640.      where DWARF information is not available, this second mechanism is

  43641.      often an analysis of a function's prologue.

  43642. 

  43643.      In order to extend testing coverage of the second level stack

  43644.      unwinding mechanisms it is helpful to be able to disable the DWARF

  43645.      stack unwinders, this can be done with this switch.

  43646. 

  43647.      In normal use of GDB disabling the DWARF unwinders is not

  43648.      advisable, there are cases that are better handled through DWARF

  43649.      than prologue analysis, and the debug experience is likely to be

  43650.      better with the DWARF frame unwinders enabled.

  43651. 

  43652.      If DWARF frame unwinders are not supported for a particular target

  43653.      architecture, then enabling this flag does not cause them to be

  43654.      used.

  43655. 

  43656. 'maint set worker-threads'

  43657. 'maint show worker-threads'

  43658.      Control the number of worker threads that may be used by GDB.  On

  43659.      capable hosts, GDB may use multiple threads to speed up certain

  43660.      CPU-intensive operations, such as demangling symbol names.  While

  43661.      the number of threads used by GDB may vary, this command can be

  43662.      used to set an upper bound on this number.  The default is

  43663.      'unlimited', which lets GDB choose a reasonable number.  Note that

  43664.      this only controls worker threads started by GDB itself; libraries

  43665.      used by GDB may start threads of their own.

  43666. 

  43667. 'maint set profile'

  43668. 'maint show profile'

  43669.      Control profiling of GDB.

  43670. 

  43671.      Profiling will be disabled until you use the 'maint set profile'

  43672.      command to enable it.  When you enable profiling, the system will

  43673.      begin collecting timing and execution count data; when you disable

  43674.      profiling or exit GDB, the results will be written to a log file.

  43675.      Remember that if you use profiling, GDB will overwrite the

  43676.      profiling log file (often called 'gmon.out').  If you have a record

  43677.      of important profiling data in a 'gmon.out' file, be sure to move

  43678.      it to a safe location.

  43679. 

  43680.      Configuring with '--enable-profiling' arranges for GDB to be

  43681.      compiled with the '-pg' compiler option.

  43682. 

  43683. 'maint set show-debug-regs'

  43684. 'maint show show-debug-regs'

  43685.      Control whether to show variables that mirror the hardware debug

  43686.      registers.  Use 'on' to enable, 'off' to disable.  If enabled, the

  43687.      debug registers values are shown when GDB inserts or removes a

  43688.      hardware breakpoint or watchpoint, and when the inferior triggers a

  43689.      hardware-assisted breakpoint or watchpoint.

  43690. 

  43691. 'maint set show-all-tib'

  43692. 'maint show show-all-tib'

  43693.      Control whether to show all non zero areas within a 1k block

  43694.      starting at thread local base, when using the 'info w32

  43695.      thread-information-block' command.

  43696. 

  43697. 'maint set target-async'

  43698. 'maint show target-async'

  43699.      This controls whether GDB targets operate in synchronous or

  43700.      asynchronous mode (*note Background Execution::).  Normally the

  43701.      default is asynchronous, if it is available; but this can be

  43702.      changed to more easily debug problems occurring only in synchronous

  43703.      mode.

  43704. 

  43705. 'maint set target-non-stop'

  43706. 'maint show target-non-stop'

  43707. 

  43708.      This controls whether GDB targets always operate in non-stop mode

  43709.      even if 'set non-stop' is 'off' (*note Non-Stop Mode::).  The

  43710.      default is 'auto', meaning non-stop mode is enabled if supported by

  43711.      the target.

  43712. 

  43713.      'maint set target-non-stop auto'

  43714.           This is the default mode.  GDB controls the target in non-stop

  43715.           mode if the target supports it.

  43716. 

  43717.      'maint set target-non-stop on'

  43718.           GDB controls the target in non-stop mode even if the target

  43719.           does not indicate support.

  43720. 

  43721.      'maint set target-non-stop off'

  43722.           GDB does not control the target in non-stop mode even if the

  43723.           target supports it.

  43724. 

  43725. 'maint set tui-resize-message'

  43726. 'maint show tui-resize-message'

  43727.      Control whether GDB displays a message each time the terminal is

  43728.      resized when in TUI mode.  The default is 'off', which means that

  43729.      GDB is silent during resizes.  When 'on', GDB will display a

  43730.      message after a resize is completed; the message will include a

  43731.      number indicating how many times the terminal has been resized.

  43732.      This setting is intended for use by the test suite, where it would

  43733.      otherwise be difficult to determine when a resize and refresh has

  43734.      been completed.

  43735. 

  43736. 'maint set per-command'

  43737. 'maint show per-command'

  43738. 

  43739.      GDB can display the resources used by each command.  This is useful

  43740.      in debugging performance problems.

  43741. 

  43742.      'maint set per-command space [on|off]'

  43743.      'maint show per-command space'

  43744.           Enable or disable the printing of the memory used by GDB for

  43745.           each command.  If enabled, GDB will display how much memory

  43746.           each command took, following the command's own output.  This

  43747.           can also be requested by invoking GDB with the '--statistics'

  43748.           command-line switch (*note Mode Options::).

  43749. 

  43750.      'maint set per-command time [on|off]'

  43751.      'maint show per-command time'

  43752.           Enable or disable the printing of the execution time of GDB

  43753.           for each command.  If enabled, GDB will display how much time

  43754.           it took to execute each command, following the command's own

  43755.           output.  Both CPU time and wallclock time are printed.

  43756.           Printing both is useful when trying to determine whether the

  43757.           cost is CPU or, e.g., disk/network latency.  Note that the CPU

  43758.           time printed is for GDB only, it does not include the

  43759.           execution time of the inferior because there's no mechanism

  43760.           currently to compute how much time was spent by GDB and how

  43761.           much time was spent by the program been debugged.  This can

  43762.           also be requested by invoking GDB with the '--statistics'

  43763.           command-line switch (*note Mode Options::).

  43764. 

  43765.      'maint set per-command symtab [on|off]'

  43766.      'maint show per-command symtab'

  43767.           Enable or disable the printing of basic symbol table

  43768.           statistics for each command.  If enabled, GDB will display the

  43769.           following information:

  43770. 

  43771.             a. number of symbol tables

  43772.             b. number of primary symbol tables

  43773.             c. number of blocks in the blockvector

  43774. 

  43775. 'maint set check-libthread-db [on|off]'

  43776. 'maint show check-libthread-db'

  43777.      Control whether GDB should run integrity checks on inferior

  43778.      specific thread debugging libraries as they are loaded.  The

  43779.      default is not to perform such checks.  If any check fails GDB will

  43780.      unload the library and continue searching for a suitable candidate

  43781.      as described in *note set libthread-db-search-path::.  For more

  43782.      information about the tests, see *note maint check libthread-db::.

  43783. 

  43784. 'maint space VALUE'

  43785.      An alias for 'maint set per-command space'.  A non-zero value

  43786.      enables it, zero disables it.

  43787. 

  43788. 'maint time VALUE'

  43789.      An alias for 'maint set per-command time'.  A non-zero value

  43790.      enables it, zero disables it.

  43791. 

  43792. 'maint translate-address [SECTION] ADDR'

  43793.      Find the symbol stored at the location specified by the address

  43794.      ADDR and an optional section name SECTION.  If found, GDB prints

  43795.      the name of the closest symbol and an offset from the symbol's

  43796.      location to the specified address.  This is similar to the 'info

  43797.      address' command (*note Symbols::), except that this command also

  43798.      allows to find symbols in other sections.

  43799. 

  43800.      If section was not specified, the section in which the symbol was

  43801.      found is also printed.  For dynamically linked executables, the

  43802.      name of executable or shared library containing the symbol is

  43803.      printed as well.

  43804. 

  43805. 'maint test-options require-delimiter'

  43806. 'maint test-options unknown-is-error'

  43807. 'maint test-options unknown-is-operand'

  43808.      These commands are used by the testsuite to validate the command

  43809.      options framework.  The 'require-delimiter' variant requires a

  43810.      double-dash delimiter to indicate end of options.  The

  43811.      'unknown-is-error' and 'unknown-is-operand' do not.  The

  43812.      'unknown-is-error' variant throws an error on unknown option, while

  43813.      'unknown-is-operand' treats unknown options as the start of the

  43814.      command's operands.  When run, the commands output the result of

  43815.      the processed options.  When completed, the commands store the

  43816.      internal result of completion in a variable exposed by the 'maint

  43817.      show test-options-completion-result' command.

  43818. 

  43819. 'maint show test-options-completion-result'

  43820.      Shows the result of completing the 'maint test-options'

  43821.      subcommands.  This is used by the testsuite to validate completion

  43822.      support in the command options framework.

  43823. 

  43824. 'maint set test-settings KIND'

  43825. 'maint show test-settings KIND'

  43826.      These are representative commands for each KIND of setting type GDB

  43827.      supports.  They are used by the testsuite for exercising the

  43828.      settings infrastructure.

  43829. 

  43830. 'maint with SETTING [VALUE] [-- COMMAND]'

  43831.      Like the 'with' command, but works with 'maintenance set'

  43832.      variables.  This is used by the testsuite to exercise the 'with'

  43833.      command's infrastructure.

  43834. 

  43835.    The following command is useful for non-interactive invocations of

  43836. GDB, such as in the test suite.

  43837. 

  43838. 'set watchdog NSEC'

  43839.      Set the maximum number of seconds GDB will wait for the target

  43840.      operation to finish.  If this time expires, GDB reports and error

  43841.      and the command is aborted.

  43842. 

  43843. 'show watchdog'

  43844.      Show the current setting of the target wait timeout.

  43845. 

  43846. 

  43847. File: gdb.info,  Node: Remote Protocol,  Next: Agent Expressions,  Prev: Maintenance Commands,  Up: Top

  43848. 

  43849. Appendix E GDB Remote Serial Protocol

  43850. *************************************

  43851. 

  43852. * Menu:

  43853. 

  43854. * Overview::

  43855. * Packets::

  43856. * Stop Reply Packets::

  43857. * General Query Packets::

  43858. * Architecture-Specific Protocol Details::

  43859. * Tracepoint Packets::

  43860. * Host I/O Packets::

  43861. * Interrupts::

  43862. * Notification Packets::

  43863. * Remote Non-Stop::

  43864. * Packet Acknowledgment::

  43865. * Examples::

  43866. * File-I/O Remote Protocol Extension::

  43867. * Library List Format::

  43868. * Library List Format for SVR4 Targets::

  43869. * Memory Map Format::

  43870. * Thread List Format::

  43871. * Traceframe Info Format::

  43872. * Branch Trace Format::

  43873. * Branch Trace Configuration Format::

  43874. 

  43875. 

  43876. File: gdb.info,  Node: Overview,  Next: Packets,  Up: Remote Protocol

  43877. 

  43878. E.1 Overview

  43879. ============

  43880. 

  43881. There may be occasions when you need to know something about the

  43882. protocol--for example, if there is only one serial port to your target

  43883. machine, you might want your program to do something special if it

  43884. recognizes a packet meant for GDB.

  43885. 

  43886.    In the examples below, '->' and '<-' are used to indicate transmitted

  43887. and received data, respectively.

  43888. 

  43889.    All GDB commands and responses (other than acknowledgments and

  43890. notifications, see *note Notification Packets::) are sent as a PACKET.

  43891. A PACKET is introduced with the character '$', the actual PACKET-DATA,

  43892. and the terminating character '#' followed by a two-digit CHECKSUM:

  43893. 

  43894.      $PACKET-DATA#CHECKSUM

  43895. 

  43896. The two-digit CHECKSUM is computed as the modulo 256 sum of all

  43897. characters between the leading '$' and the trailing '#' (an eight bit

  43898. unsigned checksum).

  43899. 

  43900.    Implementors should note that prior to GDB 5.0 the protocol

  43901. specification also included an optional two-digit SEQUENCE-ID:

  43902. 

  43903.      $SEQUENCE-ID:PACKET-DATA#CHECKSUM

  43904. 

  43905. That SEQUENCE-ID was appended to the acknowledgment.  GDB has never

  43906. output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0 must

  43907. not accept SEQUENCE-ID.

  43908. 

  43909.    When either the host or the target machine receives a packet, the

  43910. first response expected is an acknowledgment: either '+' (to indicate

  43911. the package was received correctly) or '-' (to request retransmission):

  43912. 

  43913.      -> $PACKET-DATA#CHECKSUM

  43914.      <- +

  43915. 

  43916.    The '+'/'-' acknowledgments can be disabled once a connection is

  43917. established.  *Note Packet Acknowledgment::, for details.

  43918. 

  43919.    The host (GDB) sends COMMANDs, and the target (the debugging stub

  43920. incorporated in your program) sends a RESPONSE.  In the case of step and

  43921. continue COMMANDs, the response is only sent when the operation has

  43922. completed, and the target has again stopped all threads in all attached

  43923. processes.  This is the default all-stop mode behavior, but the remote

  43924. protocol also supports GDB's non-stop execution mode; see *note Remote

  43925. Non-Stop::, for details.

  43926. 

  43927.    PACKET-DATA consists of a sequence of characters with the exception

  43928. of '#' and '$' (see 'X' packet for additional exceptions).

  43929. 

  43930.    Fields within the packet should be separated using ',' ';' or ':'.

  43931. Except where otherwise noted all numbers are represented in HEX with

  43932. leading zeros suppressed.

  43933. 

  43934.    Implementors should note that prior to GDB 5.0, the character ':'

  43935. could not appear as the third character in a packet (as it would

  43936. potentially conflict with the SEQUENCE-ID).

  43937. 

  43938.    Binary data in most packets is encoded either as two hexadecimal

  43939. digits per byte of binary data.  This allowed the traditional remote

  43940. protocol to work over connections which were only seven-bit clean.  Some

  43941. packets designed more recently assume an eight-bit clean connection, and

  43942. use a more efficient encoding to send and receive binary data.

  43943. 

  43944.    The binary data representation uses '7d' (ASCII '}') as an escape

  43945. character.  Any escaped byte is transmitted as the escape character

  43946. followed by the original character XORed with '0x20'.  For example, the

  43947. byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'.  The

  43948. bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}')

  43949. must always be escaped.  Responses sent by the stub must also escape

  43950. '0x2a' (ASCII '*'), so that it is not interpreted as the start of a

  43951. run-length encoded sequence (described next).

  43952. 

  43953.    Response DATA can be run-length encoded to save space.  Run-length

  43954. encoding replaces runs of identical characters with one instance of the

  43955. repeated character, followed by a '*' and a repeat count.  The repeat

  43956. count is itself sent encoded, to avoid binary characters in DATA: a

  43957. value of N is sent as 'N+29'.  For a repeat count greater or equal to 3,

  43958. this produces a printable ASCII character, e.g. a space (ASCII code 32)

  43959. for a repeat count of 3.  (This is because run-length encoding starts to

  43960. win for counts 3 or more.)  Thus, for example, '0* ' is a run-length

  43961. encoding of "0000": the space character after '*' means repeat the

  43962. leading '0' '32 - 29 = 3' more times.

  43963. 

  43964.    The printable characters '#' and '$' or with a numeric value greater

  43965. than 126 must not be used.  Runs of six repeats ('#') or seven repeats

  43966. ('$') can be expanded using a repeat count of only five ('"').  For

  43967. example, '00000000' can be encoded as '0*"00'.

  43968. 

  43969.    The error response returned for some packets includes a two character

  43970. error number.  That number is not well defined.

  43971. 

  43972.    For any COMMAND not supported by the stub, an empty response ('$#00')

  43973. should be returned.  That way it is possible to extend the protocol.  A

  43974. newer GDB can tell if a packet is supported based on that response.

  43975. 

  43976.    At a minimum, a stub is required to support the '?' command to tell

  43977. GDB the reason for halting, 'g' and 'G' commands for register access,

  43978. and the 'm' and 'M' commands for memory access.  Stubs that only control

  43979. single-threaded targets can implement run control with the 'c'

  43980. (continue) command, and if the target architecture supports

  43981. hardware-assisted single-stepping, the 's' (step) command.  Stubs that

  43982. support multi-threading targets should support the 'vCont' command.  All

  43983. other commands are optional.

  43984. 

  43985. 

  43986. File: gdb.info,  Node: Packets,  Next: Stop Reply Packets,  Prev: Overview,  Up: Remote Protocol

  43987. 

  43988. E.2 Packets

  43989. ===========

  43990. 

  43991. The following table provides a complete list of all currently defined

  43992. COMMANDs and their corresponding response DATA.  *Note File-I/O Remote

  43993. Protocol Extension::, for details about the File I/O extension of the

  43994. remote protocol.

  43995. 

  43996.    Each packet's description has a template showing the packet's overall

  43997. syntax, followed by an explanation of the packet's meaning.  We include

  43998. spaces in some of the templates for clarity; these are not part of the

  43999. packet's syntax.  No GDB packet uses spaces to separate its components.

  44000. For example, a template like 'foo BAR BAZ' describes a packet beginning

  44001. with the three ASCII bytes 'foo', followed by a BAR, followed directly

  44002. by a BAZ.  GDB does not transmit a space character between the 'foo' and

  44003. the BAR, or between the BAR and the BAZ.

  44004. 

  44005.    Several packets and replies include a THREAD-ID field to identify a

  44006. thread.  Normally these are positive numbers with a target-specific

  44007. interpretation, formatted as big-endian hex strings.  A THREAD-ID can

  44008. also be a literal '-1' to indicate all threads, or '0' to pick any

  44009. thread.

  44010. 

  44011.    In addition, the remote protocol supports a multiprocess feature in

  44012. which the THREAD-ID syntax is extended to optionally include both

  44013. process and thread ID fields, as 'pPID.TID'.  The PID (process) and TID

  44014. (thread) components each have the format described above: a positive

  44015. number with target-specific interpretation formatted as a big-endian hex

  44016. string, literal '-1' to indicate all processes or threads

  44017. (respectively), or '0' to indicate an arbitrary process or thread.

  44018. Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'.  It is

  44019. an error to specify all processes but a specific thread, such as

  44020. 'p-1.TID'.  Note that the 'p' prefix is _not_ used for those packets and

  44021. replies explicitly documented to include a process ID, rather than a

  44022. THREAD-ID.

  44023. 

  44024.    The multiprocess THREAD-ID syntax extensions are only used if both

  44025. GDB and the stub report support for the 'multiprocess' feature using

  44026. 'qSupported'.  *Note multiprocess extensions::, for more information.

  44027. 

  44028.    Note that all packet forms beginning with an upper- or lower-case

  44029. letter, other than those described here, are reserved for future use.

  44030. 

  44031.    Here are the packet descriptions.

  44032. 

  44033. '!'

  44034.      Enable extended mode.  In extended mode, the remote server is made

  44035.      persistent.  The 'R' packet is used to restart the program being

  44036.      debugged.

  44037. 

  44038.      Reply:

  44039.      'OK'

  44040.           The remote target both supports and has enabled extended mode.

  44041. 

  44042. '?'

  44043.      Indicate the reason the target halted.  The reply is the same as

  44044.      for step and continue.  This packet has a special interpretation

  44045.      when the target is in non-stop mode; see *note Remote Non-Stop::.

  44046. 

  44047.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44048. 

  44049. 'A ARGLEN,ARGNUM,ARG,...'

  44050.      Initialized 'argv[]' array passed into program.  ARGLEN specifies

  44051.      the number of bytes in the hex encoded byte stream ARG.  See

  44052.      'gdbserver' for more details.

  44053. 

  44054.      Reply:

  44055.      'OK'

  44056.           The arguments were set.

  44057.      'E NN'

  44058.           An error occurred.

  44059. 

  44060. 'b BAUD'

  44061.      (Don't use this packet; its behavior is not well-defined.)  Change

  44062.      the serial line speed to BAUD.

  44063. 

  44064.      JTC: _When does the transport layer state change?  When it's

  44065.      received, or after the ACK is transmitted.  In either case, there

  44066.      are problems if the command or the acknowledgment packet is

  44067.      dropped._

  44068. 

  44069.      Stan: _If people really wanted to add something like this, and get

  44070.      it working for the first time, they ought to modify ser-unix.c to

  44071.      send some kind of out-of-band message to a specially-setup stub and

  44072.      have the switch happen "in between" packets, so that from remote

  44073.      protocol's point of view, nothing actually happened._

  44074. 

  44075. 'B ADDR,MODE'

  44076.      Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR.

  44077. 

  44078.      Don't use this packet.  Use the 'Z' and 'z' packets instead (*note

  44079.      insert breakpoint or watchpoint packet::).

  44080. 

  44081. 'bc'

  44082.      Backward continue.  Execute the target system in reverse.  No

  44083.      parameter.  *Note Reverse Execution::, for more information.

  44084. 

  44085.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44086. 

  44087. 'bs'

  44088.      Backward single step.  Execute one instruction in reverse.  No

  44089.      parameter.  *Note Reverse Execution::, for more information.

  44090. 

  44091.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44092. 

  44093. 'c [ADDR]'

  44094.      Continue at ADDR, which is the address to resume.  If ADDR is

  44095.      omitted, resume at current address.

  44096. 

  44097.      This packet is deprecated for multi-threading support.  *Note vCont

  44098.      packet::.

  44099. 

  44100.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44101. 

  44102. 'C SIG[;ADDR]'

  44103.      Continue with signal SIG (hex signal number).  If ';ADDR' is

  44104.      omitted, resume at same address.

  44105. 

  44106.      This packet is deprecated for multi-threading support.  *Note vCont

  44107.      packet::.

  44108. 

  44109.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44110. 

  44111. 'd'

  44112.      Toggle debug flag.

  44113. 

  44114.      Don't use this packet; instead, define a general set packet (*note

  44115.      General Query Packets::).

  44116. 

  44117. 'D'

  44118. 'D;PID'

  44119.      The first form of the packet is used to detach GDB from the remote

  44120.      system.  It is sent to the remote target before GDB disconnects via

  44121.      the 'detach' command.

  44122. 

  44123.      The second form, including a process ID, is used when multiprocess

  44124.      protocol extensions are enabled (*note multiprocess extensions::),

  44125.      to detach only a specific process.  The PID is specified as a

  44126.      big-endian hex string.

  44127. 

  44128.      Reply:

  44129.      'OK'

  44130.           for success

  44131.      'E NN'

  44132.           for an error

  44133. 

  44134. 'F RC,EE,CF;XX'

  44135.      A reply from GDB to an 'F' packet sent by the target.  This is part

  44136.      of the File-I/O protocol extension.  *Note File-I/O Remote Protocol

  44137.      Extension::, for the specification.

  44138. 

  44139. 'g'

  44140.      Read general registers.

  44141. 

  44142.      Reply:

  44143.      'XX...'

  44144.           Each byte of register data is described by two hex digits.

  44145.           The bytes with the register are transmitted in target byte

  44146.           order.  The size of each register and their position within

  44147.           the 'g' packet are determined by the GDB internal gdbarch

  44148.           functions 'DEPRECATED_REGISTER_RAW_SIZE' and

  44149.           'gdbarch_register_name'.

  44150. 

  44151.           When reading registers from a trace frame (*note Using the

  44152.           Collected Data: Analyze Collected Data.), the stub may also

  44153.           return a string of literal 'x''s in place of the register data

  44154.           digits, to indicate that the corresponding register has not

  44155.           been collected, thus its value is unavailable.  For example,

  44156.           for an architecture with 4 registers of 4 bytes each, the

  44157.           following reply indicates to GDB that registers 0 and 2 have

  44158.           not been collected, while registers 1 and 3 have been

  44159.           collected, and both have zero value:

  44160. 

  44161.                -> g

  44162.                <- xxxxxxxx00000000xxxxxxxx00000000

  44163. 

  44164.      'E NN'

  44165.           for an error.

  44166. 

  44167. 'G XX...'

  44168.      Write general registers.  *Note read registers packet::, for a

  44169.      description of the XX... data.

  44170. 

  44171.      Reply:

  44172.      'OK'

  44173.           for success

  44174.      'E NN'

  44175.           for an error

  44176. 

  44177. 'H OP THREAD-ID'

  44178.      Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.).

  44179.      Depending on the operation to be performed, OP should be 'c' for

  44180.      step and continue operations (note that this is deprecated,

  44181.      supporting the 'vCont' command is a better option), and 'g' for

  44182.      other operations.  The thread designator THREAD-ID has the format

  44183.      and interpretation described in *note thread-id syntax::.

  44184. 

  44185.      Reply:

  44186.      'OK'

  44187.           for success

  44188.      'E NN'

  44189.           for an error

  44190. 

  44191. 'i [ADDR[,NNN]]'

  44192.      Step the remote target by a single clock cycle.  If ',NNN' is

  44193.      present, cycle step NNN cycles.  If ADDR is present, cycle step

  44194.      starting at that address.

  44195. 

  44196. 'I'

  44197.      Signal, then cycle step.  *Note step with signal packet::.  *Note

  44198.      cycle step packet::.

  44199. 

  44200. 'k'

  44201.      Kill request.

  44202. 

  44203.      The exact effect of this packet is not specified.

  44204. 

  44205.      For a bare-metal target, it may power cycle or reset the target

  44206.      system.  For that reason, the 'k' packet has no reply.

  44207. 

  44208.      For a single-process target, it may kill that process if possible.

  44209. 

  44210.      A multiple-process target may choose to kill just one process, or

  44211.      all that are under GDB's control.  For more precise control, use

  44212.      the vKill packet (*note vKill packet::).

  44213. 

  44214.      If the target system immediately closes the connection in response

  44215.      to 'k', GDB does not consider the lack of packet acknowledgment to

  44216.      be an error, and assumes the kill was successful.

  44217. 

  44218.      If connected using 'target extended-remote', and the target does

  44219.      not close the connection in response to a kill request, GDB probes

  44220.      the target state as if a new connection was opened (*note ?

  44221.      packet::).

  44222. 

  44223. 'm ADDR,LENGTH'

  44224.      Read LENGTH addressable memory units starting at address ADDR

  44225.      (*note addressable memory unit::).  Note that ADDR may not be

  44226.      aligned to any particular boundary.

  44227. 

  44228.      The stub need not use any particular size or alignment when

  44229.      gathering data from memory for the response; even if ADDR is

  44230.      word-aligned and LENGTH is a multiple of the word size, the stub is

  44231.      free to use byte accesses, or not.  For this reason, this packet

  44232.      may not be suitable for accessing memory-mapped I/O devices.

  44233. 

  44234.      Reply:

  44235.      'XX...'

  44236.           Memory contents; each byte is transmitted as a two-digit

  44237.           hexadecimal number.  The reply may contain fewer addressable

  44238.           memory units than requested if the server was able to read

  44239.           only part of the region of memory.

  44240.      'E NN'

  44241.           NN is errno

  44242. 

  44243. 'M ADDR,LENGTH:XX...'

  44244.      Write LENGTH addressable memory units starting at address ADDR

  44245.      (*note addressable memory unit::).  The data is given by XX...;

  44246.      each byte is transmitted as a two-digit hexadecimal number.

  44247. 

  44248.      Reply:

  44249.      'OK'

  44250.           for success

  44251.      'E NN'

  44252.           for an error (this includes the case where only part of the

  44253.           data was written).

  44254. 

  44255. 'p N'

  44256.      Read the value of register N; N is in hex.  *Note read registers

  44257.      packet::, for a description of how the returned register value is

  44258.      encoded.

  44259. 

  44260.      Reply:

  44261.      'XX...'

  44262.           the register's value

  44263.      'E NN'

  44264.           for an error

  44265.      ''

  44266.           Indicating an unrecognized QUERY.

  44267. 

  44268. 'P N...=R...'

  44269.      Write register N... with value R....  The register number N is in

  44270.      hexadecimal, and R... contains two hex digits for each byte in the

  44271.      register (target byte order).

  44272. 

  44273.      Reply:

  44274.      'OK'

  44275.           for success

  44276.      'E NN'

  44277.           for an error

  44278. 

  44279. 'q NAME PARAMS...'

  44280. 'Q NAME PARAMS...'

  44281.      General query ('q') and set ('Q').  These packets are described

  44282.      fully in *note General Query Packets::.

  44283. 

  44284. 'r'

  44285.      Reset the entire system.

  44286. 

  44287.      Don't use this packet; use the 'R' packet instead.

  44288. 

  44289. 'R XX'

  44290.      Restart the program being debugged.  The XX, while needed, is

  44291.      ignored.  This packet is only available in extended mode (*note

  44292.      extended mode::).

  44293. 

  44294.      The 'R' packet has no reply.

  44295. 

  44296. 's [ADDR]'

  44297.      Single step, resuming at ADDR.  If ADDR is omitted, resume at same

  44298.      address.

  44299. 

  44300.      This packet is deprecated for multi-threading support.  *Note vCont

  44301.      packet::.

  44302. 

  44303.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44304. 

  44305. 'S SIG[;ADDR]'

  44306.      Step with signal.  This is analogous to the 'C' packet, but

  44307.      requests a single-step, rather than a normal resumption of

  44308.      execution.

  44309. 

  44310.      This packet is deprecated for multi-threading support.  *Note vCont

  44311.      packet::.

  44312. 

  44313.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44314. 

  44315. 't ADDR:PP,MM'

  44316.      Search backwards starting at address ADDR for a match with pattern

  44317.      PP and mask MM, both of which are are 4 byte long.  There must be

  44318.      at least 3 digits in ADDR.

  44319. 

  44320. 'T THREAD-ID'

  44321.      Find out if the thread THREAD-ID is alive.  *Note thread-id

  44322.      syntax::.

  44323. 

  44324.      Reply:

  44325.      'OK'

  44326.           thread is still alive

  44327.      'E NN'

  44328.           thread is dead

  44329. 

  44330. 'v'

  44331.      Packets starting with 'v' are identified by a multi-letter name, up

  44332.      to the first ';' or '?' (or the end of the packet).

  44333. 

  44334. 'vAttach;PID'

  44335.      Attach to a new process with the specified process ID PID.  The

  44336.      process ID is a hexadecimal integer identifying the process.  In

  44337.      all-stop mode, all threads in the attached process are stopped; in

  44338.      non-stop mode, it may be attached without being stopped if that is

  44339.      supported by the target.

  44340. 

  44341.      This packet is only available in extended mode (*note extended

  44342.      mode::).

  44343. 

  44344.      Reply:

  44345.      'E NN'

  44346.           for an error

  44347.      'Any stop packet'

  44348.           for success in all-stop mode (*note Stop Reply Packets::)

  44349.      'OK'

  44350.           for success in non-stop mode (*note Remote Non-Stop::)

  44351. 

  44352. 'vCont[;ACTION[:THREAD-ID]]...'

  44353.      Resume the inferior, specifying different actions for each thread.

  44354. 

  44355.      For each inferior thread, the leftmost action with a matching

  44356.      THREAD-ID is applied.  Threads that don't match any action remain

  44357.      in their current state.  Thread IDs are specified using the syntax

  44358.      described in *note thread-id syntax::.  If multiprocess extensions

  44359.      (*note multiprocess extensions::) are supported, actions can be

  44360.      specified to match all threads in a process by using the 'pPID.-1'

  44361.      form of the THREAD-ID.  An action with no THREAD-ID matches all

  44362.      threads.  Specifying no actions is an error.

  44363. 

  44364.      Currently supported actions are:

  44365. 

  44366.      'c'

  44367.           Continue.

  44368.      'C SIG'

  44369.           Continue with signal SIG.  The signal SIG should be two hex

  44370.           digits.

  44371.      's'

  44372.           Step.

  44373.      'S SIG'

  44374.           Step with signal SIG.  The signal SIG should be two hex

  44375.           digits.

  44376.      't'

  44377.           Stop.

  44378.      'r START,END'

  44379.           Step once, and then keep stepping as long as the thread stops

  44380.           at addresses between START (inclusive) and END (exclusive).

  44381.           The remote stub reports a stop reply when either the thread

  44382.           goes out of the range or is stopped due to an unrelated

  44383.           reason, such as hitting a breakpoint.  *Note range stepping::.

  44384. 

  44385.           If the range is empty (START == END), then the action becomes

  44386.           equivalent to the 's' action.  In other words, single-step

  44387.           once, and report the stop (even if the stepped instruction

  44388.           jumps to START).

  44389. 

  44390.           (A stop reply may be sent at any point even if the PC is still

  44391.           within the stepping range; for example, it is valid to

  44392.           implement this packet in a degenerate way as a single

  44393.           instruction step operation.)

  44394. 

  44395.      The optional argument ADDR normally associated with the 'c', 'C',

  44396.      's', and 'S' packets is not supported in 'vCont'.

  44397. 

  44398.      The 't' action is only relevant in non-stop mode (*note Remote

  44399.      Non-Stop::) and may be ignored by the stub otherwise.  A stop reply

  44400.      should be generated for any affected thread not already stopped.

  44401.      When a thread is stopped by means of a 't' action, the

  44402.      corresponding stop reply should indicate that the thread has

  44403.      stopped with signal '0', regardless of whether the target uses some

  44404.      other signal as an implementation detail.

  44405. 

  44406.      The server must ignore 'c', 'C', 's', 'S', and 'r' actions for

  44407.      threads that are already running.  Conversely, the server must

  44408.      ignore 't' actions for threads that are already stopped.

  44409. 

  44410.      _Note:_ In non-stop mode, a thread is considered running until GDB

  44411.      acknowledges an asynchronous stop notification for it with the

  44412.      'vStopped' packet (*note Remote Non-Stop::).

  44413. 

  44414.      The stub must support 'vCont' if it reports support for

  44415.      multiprocess extensions (*note multiprocess extensions::).

  44416. 

  44417.      Reply: *Note Stop Reply Packets::, for the reply specifications.

  44418. 

  44419. 'vCont?'

  44420.      Request a list of actions supported by the 'vCont' packet.

  44421. 

  44422.      Reply:

  44423.      'vCont[;ACTION...]'

  44424.           The 'vCont' packet is supported.  Each ACTION is a supported

  44425.           command in the 'vCont' packet.

  44426.      ''

  44427.           The 'vCont' packet is not supported.

  44428. 

  44429. 'vCtrlC'

  44430.      Interrupt remote target as if a control-C was pressed on the remote

  44431.      terminal.  This is the equivalent to reacting to the '^C' ('\003',

  44432.      the control-C character) character in all-stop mode while the

  44433.      target is running, except this works in non-stop mode.  *Note

  44434.      interrupting remote targets::, for more info on the all-stop

  44435.      variant.

  44436. 

  44437.      Reply:

  44438.      'E NN'

  44439.           for an error

  44440.      'OK'

  44441.           for success

  44442. 

  44443. 'vFile:OPERATION:PARAMETER...'

  44444.      Perform a file operation on the target system.  For details, see

  44445.      *note Host I/O Packets::.

  44446. 

  44447. 'vFlashErase:ADDR,LENGTH'

  44448.      Direct the stub to erase LENGTH bytes of flash starting at ADDR.

  44449.      The region may enclose any number of flash blocks, but its start

  44450.      and end must fall on block boundaries, as indicated by the flash

  44451.      block size appearing in the memory map (*note Memory Map Format::).

  44452.      GDB groups flash memory programming operations together, and sends

  44453.      a 'vFlashDone' request after each group; the stub is allowed to

  44454.      delay erase operation until the 'vFlashDone' packet is received.

  44455. 

  44456.      Reply:

  44457.      'OK'

  44458.           for success

  44459.      'E NN'

  44460.           for an error

  44461. 

  44462. 'vFlashWrite:ADDR:XX...'

  44463.      Direct the stub to write data to flash address ADDR.  The data is

  44464.      passed in binary form using the same encoding as for the 'X' packet

  44465.      (*note Binary Data::).  The memory ranges specified by

  44466.      'vFlashWrite' packets preceding a 'vFlashDone' packet must not

  44467.      overlap, and must appear in order of increasing addresses (although

  44468.      'vFlashErase' packets for higher addresses may already have been

  44469.      received; the ordering is guaranteed only between 'vFlashWrite'

  44470.      packets).  If a packet writes to an address that was neither erased

  44471.      by a preceding 'vFlashErase' packet nor by some other

  44472.      target-specific method, the results are unpredictable.

  44473. 

  44474.      Reply:

  44475.      'OK'

  44476.           for success

  44477.      'E.memtype'

  44478.           for vFlashWrite addressing non-flash memory

  44479.      'E NN'

  44480.           for an error

  44481. 

  44482. 'vFlashDone'

  44483.      Indicate to the stub that flash programming operation is finished.

  44484.      The stub is permitted to delay or batch the effects of a group of

  44485.      'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet

  44486.      is received.  The contents of the affected regions of flash memory

  44487.      are unpredictable until the 'vFlashDone' request is completed.

  44488. 

  44489. 'vKill;PID'

  44490.      Kill the process with the specified process ID PID, which is a

  44491.      hexadecimal integer identifying the process.  This packet is used

  44492.      in preference to 'k' when multiprocess protocol extensions are

  44493.      supported; see *note multiprocess extensions::.

  44494. 

  44495.      Reply:

  44496.      'E NN'

  44497.           for an error

  44498.      'OK'

  44499.           for success

  44500. 

  44501. 'vMustReplyEmpty'

  44502.      The correct reply to an unknown 'v' packet is to return the empty

  44503.      string, however, some older versions of 'gdbserver' would

  44504.      incorrectly return 'OK' for unknown 'v' packets.

  44505. 

  44506.      The 'vMustReplyEmpty' is used as a feature test to check how

  44507.      'gdbserver' handles unknown packets, it is important that this

  44508.      packet be handled in the same way as other unknown 'v' packets.  If

  44509.      this packet is handled differently to other unknown 'v' packets

  44510.      then it is possible that GDB may run into problems in other areas,

  44511.      specifically around use of 'vFile:setfs:'.

  44512. 

  44513. 'vRun;FILENAME[;ARGUMENT]...'

  44514.      Run the program FILENAME, passing it each ARGUMENT on its command

  44515.      line.  The file and arguments are hex-encoded strings.  If FILENAME

  44516.      is an empty string, the stub may use a default program (e.g. the

  44517.      last program run).  The program is created in the stopped state.

  44518. 

  44519.      This packet is only available in extended mode (*note extended

  44520.      mode::).

  44521. 

  44522.      Reply:

  44523.      'E NN'

  44524.           for an error

  44525.      'Any stop packet'

  44526.           for success (*note Stop Reply Packets::)

  44527. 

  44528. 'vStopped'

  44529.      *Note Notification Packets::.

  44530. 

  44531. 'X ADDR,LENGTH:XX...'

  44532.      Write data to memory, where the data is transmitted in binary.

  44533.      Memory is specified by its address ADDR and number of addressable

  44534.      memory units LENGTH (*note addressable memory unit::); 'XX...' is

  44535.      binary data (*note Binary Data::).

  44536. 

  44537.      Reply:

  44538.      'OK'

  44539.           for success

  44540.      'E NN'

  44541.           for an error

  44542. 

  44543. 'z TYPE,ADDR,KIND'

  44544. 'Z TYPE,ADDR,KIND'

  44545.      Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint

  44546.      starting at address ADDRESS of kind KIND.

  44547. 

  44548.      Each breakpoint and watchpoint packet TYPE is documented

  44549.      separately.

  44550. 

  44551.      _Implementation notes: A remote target shall return an empty string

  44552.      for an unrecognized breakpoint or watchpoint packet TYPE.  A remote

  44553.      target shall support either both or neither of a given 'ZTYPE...'

  44554.      and 'zTYPE...' packet pair.  To avoid potential problems with

  44555.      duplicate packets, the operations should be implemented in an

  44556.      idempotent way._

  44557. 

  44558. 'z0,ADDR,KIND'

  44559. 'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'

  44560.      Insert ('Z0') or remove ('z0') a software breakpoint at address

  44561.      ADDR of type KIND.

  44562. 

  44563.      A software breakpoint is implemented by replacing the instruction

  44564.      at ADDR with a software breakpoint or trap instruction.  The KIND

  44565.      is target-specific and typically indicates the size of the

  44566.      breakpoint in bytes that should be inserted.  E.g., the ARM and

  44567.      MIPS can insert either a 2 or 4 byte breakpoint.  Some

  44568.      architectures have additional meanings for KIND (*note

  44569.      Architecture-Specific Protocol Details::); if no

  44570.      architecture-specific value is being used, it should be '0'.  KIND

  44571.      is hex-encoded.  COND_LIST is an optional list of conditional

  44572.      expressions in bytecode form that should be evaluated on the

  44573.      target's side.  These are the conditions that should be taken into

  44574.      consideration when deciding if the breakpoint trigger should be

  44575.      reported back to GDB.

  44576. 

  44577.      See also the 'swbreak' stop reason (*note swbreak stop reason::)

  44578.      for how to best report a software breakpoint event to GDB.

  44579. 

  44580.      The COND_LIST parameter is comprised of a series of expressions,

  44581.      concatenated without separators.  Each expression has the following

  44582.      form:

  44583. 

  44584.      'X LEN,EXPR'

  44585.           LEN is the length of the bytecode expression and EXPR is the

  44586.           actual conditional expression in bytecode form.

  44587. 

  44588.      The optional CMD_LIST parameter introduces commands that may be run

  44589.      on the target, rather than being reported back to GDB.  The

  44590.      parameter starts with a numeric flag PERSIST; if the flag is

  44591.      nonzero, then the breakpoint may remain active and the commands

  44592.      continue to be run even when GDB disconnects from the target.

  44593.      Following this flag is a series of expressions concatenated with no

  44594.      separators.  Each expression has the following form:

  44595. 

  44596.      'X LEN,EXPR'

  44597.           LEN is the length of the bytecode expression and EXPR is the

  44598.           actual commands expression in bytecode form.

  44599. 

  44600.      _Implementation note: It is possible for a target to copy or move

  44601.      code that contains software breakpoints (e.g., when implementing

  44602.      overlays).  The behavior of this packet, in the presence of such a

  44603.      target, is not defined._

  44604. 

  44605.      Reply:

  44606.      'OK'

  44607.           success

  44608.      ''

  44609.           not supported

  44610.      'E NN'

  44611.           for an error

  44612. 

  44613. 'z1,ADDR,KIND'

  44614. 'Z1,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'

  44615.      Insert ('Z1') or remove ('z1') a hardware breakpoint at address

  44616.      ADDR.

  44617. 

  44618.      A hardware breakpoint is implemented using a mechanism that is not

  44619.      dependent on being able to modify the target's memory.  The KIND,

  44620.      COND_LIST, and CMD_LIST arguments have the same meaning as in 'Z0'

  44621.      packets.

  44622. 

  44623.      _Implementation note: A hardware breakpoint is not affected by code

  44624.      movement._

  44625. 

  44626.      Reply:

  44627.      'OK'

  44628.           success

  44629.      ''

  44630.           not supported

  44631.      'E NN'

  44632.           for an error

  44633. 

  44634. 'z2,ADDR,KIND'

  44635. 'Z2,ADDR,KIND'

  44636.      Insert ('Z2') or remove ('z2') a write watchpoint at ADDR.  The

  44637.      number of bytes to watch is specified by KIND.

  44638. 

  44639.      Reply:

  44640.      'OK'

  44641.           success

  44642.      ''

  44643.           not supported

  44644.      'E NN'

  44645.           for an error

  44646. 

  44647. 'z3,ADDR,KIND'

  44648. 'Z3,ADDR,KIND'

  44649.      Insert ('Z3') or remove ('z3') a read watchpoint at ADDR.  The

  44650.      number of bytes to watch is specified by KIND.

  44651. 

  44652.      Reply:

  44653.      'OK'

  44654.           success

  44655.      ''

  44656.           not supported

  44657.      'E NN'

  44658.           for an error

  44659. 

  44660. 'z4,ADDR,KIND'

  44661. 'Z4,ADDR,KIND'

  44662.      Insert ('Z4') or remove ('z4') an access watchpoint at ADDR.  The

  44663.      number of bytes to watch is specified by KIND.

  44664. 

  44665.      Reply:

  44666.      'OK'

  44667.           success

  44668.      ''

  44669.           not supported

  44670.      'E NN'

  44671.           for an error

  44672. 

  44673. 

  44674. File: gdb.info,  Node: Stop Reply Packets,  Next: General Query Packets,  Prev: Packets,  Up: Remote Protocol

  44675. 

  44676. E.3 Stop Reply Packets

  44677. ======================

  44678. 

  44679. The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?'

  44680. packets can receive any of the below as a reply.  Except for '?' and

  44681. 'vStopped', that reply is only returned when the target halts.  In the

  44682. below the exact meaning of "signal number" is defined by the header

  44683. 'include/gdb/signals.h' in the GDB source code.

  44684. 

  44685.    In non-stop mode, the server will simply reply 'OK' to commands such

  44686. as 'vCont'; any stop will be the subject of a future notification.

  44687. *Note Remote Non-Stop::.

  44688. 

  44689.    As in the description of request packets, we include spaces in the

  44690. reply templates for clarity; these are not part of the reply packet's

  44691. syntax.  No GDB stop reply packet uses spaces to separate its

  44692. components.

  44693. 

  44694. 'S AA'

  44695.      The program received signal number AA (a two-digit hexadecimal

  44696.      number).  This is equivalent to a 'T' response with no N:R pairs.

  44697. 

  44698. 'T AA N1:R1;N2:R2;...'

  44699.      The program received signal number AA (a two-digit hexadecimal

  44700.      number).  This is equivalent to an 'S' response, except that the

  44701.      'N:R' pairs can carry values of important registers and other

  44702.      information directly in the stop reply packet, reducing round-trip

  44703.      latency.  Single-step and breakpoint traps are reported this way.

  44704.      Each 'N:R' pair is interpreted as follows:

  44705. 

  44706.         * If N is a hexadecimal number, it is a register number, and the

  44707.           corresponding R gives that register's value.  The data R is a

  44708.           series of bytes in target byte order, with each byte given by

  44709.           a two-digit hex number.

  44710. 

  44711.         * If N is 'thread', then R is the THREAD-ID of the stopped

  44712.           thread, as specified in *note thread-id syntax::.

  44713. 

  44714.         * If N is 'core', then R is the hexadecimal number of the core

  44715.           on which the stop event was detected.

  44716. 

  44717.         * If N is a recognized "stop reason", it describes a more

  44718.           specific event that stopped the target.  The currently defined

  44719.           stop reasons are listed below.  The AA should be '05', the

  44720.           trap signal.  At most one stop reason should be present.

  44721. 

  44722.         * Otherwise, GDB should ignore this 'N:R' pair and go on to the

  44723.           next; this allows us to extend the protocol in the future.

  44724. 

  44725.      The currently defined stop reasons are:

  44726. 

  44727.      'watch'

  44728.      'rwatch'

  44729.      'awatch'

  44730.           The packet indicates a watchpoint hit, and R is the data

  44731.           address, in hex.

  44732. 

  44733.      'syscall_entry'

  44734.      'syscall_return'

  44735.           The packet indicates a syscall entry or return, and R is the

  44736.           syscall number, in hex.

  44737. 

  44738.      'library'

  44739.           The packet indicates that the loaded libraries have changed.

  44740.           GDB should use 'qXfer:libraries:read' to fetch a new list of

  44741.           loaded libraries.  The R part is ignored.

  44742. 

  44743.      'replaylog'

  44744.           The packet indicates that the target cannot continue replaying

  44745.           logged execution events, because it has reached the end (or

  44746.           the beginning when executing backward) of the log.  The value

  44747.           of R will be either 'begin' or 'end'.  *Note Reverse

  44748.           Execution::, for more information.

  44749. 

  44750.      'swbreak'

  44751.           The packet indicates a software breakpoint instruction was

  44752.           executed, irrespective of whether it was GDB that planted the

  44753.           breakpoint or the breakpoint is hardcoded in the program.  The

  44754.           R part must be left empty.

  44755. 

  44756.           On some architectures, such as x86, at the architecture level,

  44757.           when a breakpoint instruction executes the program counter

  44758.           points at the breakpoint address plus an offset.  On such

  44759.           targets, the stub is responsible for adjusting the PC to point

  44760.           back at the breakpoint address.

  44761. 

  44762.           This packet should not be sent by default; older GDB versions

  44763.           did not support it.  GDB requests it, by supplying an

  44764.           appropriate 'qSupported' feature (*note qSupported::).  The

  44765.           remote stub must also supply the appropriate 'qSupported'

  44766.           feature indicating support.

  44767. 

  44768.           This packet is required for correct non-stop mode operation.

  44769. 

  44770.      'hwbreak'

  44771.           The packet indicates the target stopped for a hardware

  44772.           breakpoint.  The R part must be left empty.

  44773. 

  44774.           The same remarks about 'qSupported' and non-stop mode above

  44775.           apply.

  44776. 

  44777.      'fork'

  44778.           The packet indicates that 'fork' was called, and R is the

  44779.           thread ID of the new child process.  Refer to *note thread-id

  44780.           syntax:: for the format of the THREAD-ID field.  This packet

  44781.           is only applicable to targets that support fork events.

  44782. 

  44783.           This packet should not be sent by default; older GDB versions

  44784.           did not support it.  GDB requests it, by supplying an

  44785.           appropriate 'qSupported' feature (*note qSupported::).  The

  44786.           remote stub must also supply the appropriate 'qSupported'

  44787.           feature indicating support.

  44788. 

  44789.      'vfork'

  44790.           The packet indicates that 'vfork' was called, and R is the

  44791.           thread ID of the new child process.  Refer to *note thread-id

  44792.           syntax:: for the format of the THREAD-ID field.  This packet

  44793.           is only applicable to targets that support vfork events.

  44794. 

  44795.           This packet should not be sent by default; older GDB versions

  44796.           did not support it.  GDB requests it, by supplying an

  44797.           appropriate 'qSupported' feature (*note qSupported::).  The

  44798.           remote stub must also supply the appropriate 'qSupported'

  44799.           feature indicating support.

  44800. 

  44801.      'vforkdone'

  44802.           The packet indicates that a child process created by a vfork

  44803.           has either called 'exec' or terminated, so that the address

  44804.           spaces of the parent and child process are no longer shared.

  44805.           The R part is ignored.  This packet is only applicable to

  44806.           targets that support vforkdone events.

  44807. 

  44808.           This packet should not be sent by default; older GDB versions

  44809.           did not support it.  GDB requests it, by supplying an

  44810.           appropriate 'qSupported' feature (*note qSupported::).  The

  44811.           remote stub must also supply the appropriate 'qSupported'

  44812.           feature indicating support.

  44813. 

  44814.      'exec'

  44815.           The packet indicates that 'execve' was called, and R is the

  44816.           absolute pathname of the file that was executed, in hex.  This

  44817.           packet is only applicable to targets that support exec events.

  44818. 

  44819.           This packet should not be sent by default; older GDB versions

  44820.           did not support it.  GDB requests it, by supplying an

  44821.           appropriate 'qSupported' feature (*note qSupported::).  The

  44822.           remote stub must also supply the appropriate 'qSupported'

  44823.           feature indicating support.

  44824. 

  44825.      'create'

  44826.           The packet indicates that the thread was just created.  The

  44827.           new thread is stopped until GDB sets it running with a

  44828.           resumption packet (*note vCont packet::).  This packet should

  44829.           not be sent by default; GDB requests it with the *note

  44830.           QThreadEvents:: packet.  See also the 'w' (*note thread exit

  44831.           event::) remote reply below.  The R part is ignored.

  44832. 

  44833. 'W AA'

  44834. 'W AA ; process:PID'

  44835.      The process exited, and AA is the exit status.  This is only

  44836.      applicable to certain targets.

  44837. 

  44838.      The second form of the response, including the process ID of the

  44839.      exited process, can be used only when GDB has reported support for

  44840.      multiprocess protocol extensions; see *note multiprocess

  44841.      extensions::.  Both AA and PID are formatted as big-endian hex

  44842.      strings.

  44843. 

  44844. 'X AA'

  44845. 'X AA ; process:PID'

  44846.      The process terminated with signal AA.

  44847. 

  44848.      The second form of the response, including the process ID of the

  44849.      terminated process, can be used only when GDB has reported support

  44850.      for multiprocess protocol extensions; see *note multiprocess

  44851.      extensions::.  Both AA and PID are formatted as big-endian hex

  44852.      strings.

  44853. 

  44854. 'w AA ; TID'

  44855. 

  44856.      The thread exited, and AA is the exit status.  This response should

  44857.      not be sent by default; GDB requests it with the *note

  44858.      QThreadEvents:: packet.  See also *note thread create event::

  44859.      above.  AA is formatted as a big-endian hex string.

  44860. 

  44861. 'N'

  44862.      There are no resumed threads left in the target.  In other words,

  44863.      even though the process is alive, the last resumed thread has

  44864.      exited.  For example, say the target process has two threads:

  44865.      thread 1 and thread 2.  The client leaves thread 1 stopped, and

  44866.      resumes thread 2, which subsequently exits.  At this point, even

  44867.      though the process is still alive, and thus no 'W' stop reply is

  44868.      sent, no thread is actually executing either.  The 'N' stop reply

  44869.      thus informs the client that it can stop waiting for stop replies.

  44870.      This packet should not be sent by default; older GDB versions did

  44871.      not support it.  GDB requests it, by supplying an appropriate

  44872.      'qSupported' feature (*note qSupported::).  The remote stub must

  44873.      also supply the appropriate 'qSupported' feature indicating

  44874.      support.

  44875. 

  44876. 'O XX...'

  44877.      'XX...' is hex encoding of ASCII data, to be written as the

  44878.      program's console output.  This can happen at any time while the

  44879.      program is running and the debugger should continue to wait for

  44880.      'W', 'T', etc.  This reply is not permitted in non-stop mode.

  44881. 

  44882. 'F CALL-ID,PARAMETER...'

  44883.      CALL-ID is the identifier which says which host system call should

  44884.      be called.  This is just the name of the function.  Translation

  44885.      into the correct system call is only applicable as it's defined in

  44886.      GDB.  *Note File-I/O Remote Protocol Extension::, for a list of

  44887.      implemented system calls.

  44888. 

  44889.      'PARAMETER...' is a list of parameters as defined for this very

  44890.      system call.

  44891. 

  44892.      The target replies with this packet when it expects GDB to call a

  44893.      host system call on behalf of the target.  GDB replies with an

  44894.      appropriate 'F' packet and keeps up waiting for the next reply

  44895.      packet from the target.  The latest 'C', 'c', 'S' or 's' action is

  44896.      expected to be continued.  *Note File-I/O Remote Protocol

  44897.      Extension::, for more details.

  44898. 

  44899. 

  44900. File: gdb.info,  Node: General Query Packets,  Next: Architecture-Specific Protocol Details,  Prev: Stop Reply Packets,  Up: Remote Protocol

  44901. 

  44902. E.4 General Query Packets

  44903. =========================

  44904. 

  44905. Packets starting with 'q' are "general query packets"; packets starting

  44906. with 'Q' are "general set packets".  General query and set packets are a

  44907. semi-unified form for retrieving and sending information to and from the

  44908. stub.

  44909. 

  44910.    The initial letter of a query or set packet is followed by a name

  44911. indicating what sort of thing the packet applies to.  For example, GDB

  44912. may use a 'qSymbol' packet to exchange symbol definitions with the stub.

  44913. These packet names follow some conventions:

  44914. 

  44915.    * The name must not contain commas, colons or semicolons.

  44916.    * Most GDB query and set packets have a leading upper case letter.

  44917.    * The names of custom vendor packets should use a company prefix, in

  44918.      lower case, followed by a period.  For example, packets designed at

  44919.      the Acme Corporation might begin with 'qacme.foo' (for querying

  44920.      foos) or 'Qacme.bar' (for setting bars).

  44921. 

  44922.    The name of a query or set packet should be separated from any

  44923. parameters by a ':'; the parameters themselves should be separated by

  44924. ',' or ';'.  Stubs must be careful to match the full packet name, and

  44925. check for a separator or the end of the packet, in case two packet names

  44926. share a common prefix.  New packets should not begin with 'qC', 'qP', or

  44927. 'qL'(1).

  44928. 

  44929.    Like the descriptions of the other packets, each description here has

  44930. a template showing the packet's overall syntax, followed by an

  44931. explanation of the packet's meaning.  We include spaces in some of the

  44932. templates for clarity; these are not part of the packet's syntax.  No

  44933. GDB packet uses spaces to separate its components.

  44934. 

  44935.    Here are the currently defined query and set packets:

  44936. 

  44937. 'QAgent:1'

  44938. 'QAgent:0'

  44939.      Turn on or off the agent as a helper to perform some debugging

  44940.      operations delegated from GDB (*note Control Agent::).

  44941. 

  44942. 'QAllow:OP:VAL...'

  44943.      Specify which operations GDB expects to request of the target, as a

  44944.      semicolon-separated list of operation name and value pairs.

  44945.      Possible values for OP include 'WriteReg', 'WriteMem',

  44946.      'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'.  VAL

  44947.      is either 0, indicating that GDB will not request the operation, or

  44948.      1, indicating that it may.  (The target can then use this to set up

  44949.      its own internals optimally, for instance if the debugger never

  44950.      expects to insert breakpoints, it may not need to install its own

  44951.      trap handler.)

  44952. 

  44953. 'qC'

  44954.      Return the current thread ID.

  44955. 

  44956.      Reply:

  44957.      'QC THREAD-ID'

  44958.           Where THREAD-ID is a thread ID as documented in *note

  44959.           thread-id syntax::.

  44960.      '(anything else)'

  44961.           Any other reply implies the old thread ID.

  44962. 

  44963. 'qCRC:ADDR,LENGTH'

  44964.      Compute the CRC checksum of a block of memory using CRC-32 defined

  44965.      in IEEE 802.3.  The CRC is computed byte at a time, taking the most

  44966.      significant bit of each byte first.  The initial pattern code

  44967.      '0xffffffff' is used to ensure leading zeros affect the CRC.

  44968. 

  44969.      _Note:_ This is the same CRC used in validating separate debug

  44970.      files (*note Debugging Information in Separate Files: Separate

  44971.      Debug Files.).  However the algorithm is slightly different.  When

  44972.      validating separate debug files, the CRC is computed taking the

  44973.      _least_ significant bit of each byte first, and the final result is

  44974.      inverted to detect trailing zeros.

  44975. 

  44976.      Reply:

  44977.      'E NN'

  44978.           An error (such as memory fault)

  44979.      'C CRC32'

  44980.           The specified memory region's checksum is CRC32.

  44981. 

  44982. 'QDisableRandomization:VALUE'

  44983.      Some target operating systems will randomize the virtual address

  44984.      space of the inferior process as a security feature, but provide a

  44985.      feature to disable such randomization, e.g. to allow for a more

  44986.      deterministic debugging experience.  On such systems, this packet

  44987.      with a VALUE of 1 directs the target to disable address space

  44988.      randomization for processes subsequently started via 'vRun'

  44989.      packets, while a packet with a VALUE of 0 tells the target to

  44990.      enable address space randomization.

  44991. 

  44992.      This packet is only available in extended mode (*note extended

  44993.      mode::).

  44994. 

  44995.      Reply:

  44996.      'OK'

  44997.           The request succeeded.

  44998. 

  44999.      'E NN'

  45000.           An error occurred.  The error number NN is given as hex

  45001.           digits.

  45002. 

  45003.      ''

  45004.           An empty reply indicates that 'QDisableRandomization' is not

  45005.           supported by the stub.

  45006. 

  45007.      This packet is not probed by default; the remote stub must request

  45008.      it, by supplying an appropriate 'qSupported' response (*note

  45009.      qSupported::).  This should only be done on targets that actually

  45010.      support disabling address space randomization.

  45011. 

  45012. 'QStartupWithShell:VALUE'

  45013.      On UNIX-like targets, it is possible to start the inferior using a

  45014.      shell program.  This is the default behavior on both GDB and

  45015.      'gdbserver' (*note set startup-with-shell::).  This packet is used

  45016.      to inform 'gdbserver' whether it should start the inferior using a

  45017.      shell or not.

  45018. 

  45019.      If VALUE is '0', 'gdbserver' will not use a shell to start the

  45020.      inferior.  If VALUE is '1', 'gdbserver' will use a shell to start

  45021.      the inferior.  All other values are considered an error.

  45022. 

  45023.      This packet is only available in extended mode (*note extended

  45024.      mode::).

  45025. 

  45026.      Reply:

  45027.      'OK'

  45028.           The request succeeded.

  45029. 

  45030.      'E NN'

  45031.           An error occurred.  The error number NN is given as hex

  45032.           digits.

  45033. 

  45034.      This packet is not probed by default; the remote stub must request

  45035.      it, by supplying an appropriate 'qSupported' response (*note

  45036.      qSupported::).  This should only be done on targets that actually

  45037.      support starting the inferior using a shell.

  45038. 

  45039.      Use of this packet is controlled by the 'set startup-with-shell'

  45040.      command; *note set startup-with-shell::.

  45041. 

  45042. 'QEnvironmentHexEncoded:HEX-VALUE'

  45043.      On UNIX-like targets, it is possible to set environment variables

  45044.      that will be passed to the inferior during the startup process.

  45045.      This packet is used to inform 'gdbserver' of an environment

  45046.      variable that has been defined by the user on GDB (*note set

  45047.      environment::).

  45048. 

  45049.      The packet is composed by HEX-VALUE, an hex encoded representation

  45050.      of the NAME=VALUE format representing an environment variable.  The

  45051.      name of the environment variable is represented by NAME, and the

  45052.      value to be assigned to the environment variable is represented by

  45053.      VALUE.  If the variable has no value (i.e., the value is 'null'),

  45054.      then VALUE will not be present.

  45055. 

  45056.      This packet is only available in extended mode (*note extended

  45057.      mode::).

  45058. 

  45059.      Reply:

  45060.      'OK'

  45061.           The request succeeded.

  45062. 

  45063.      This packet is not probed by default; the remote stub must request

  45064.      it, by supplying an appropriate 'qSupported' response (*note

  45065.      qSupported::).  This should only be done on targets that actually

  45066.      support passing environment variables to the starting inferior.

  45067. 

  45068.      This packet is related to the 'set environment' command; *note set

  45069.      environment::.

  45070. 

  45071. 'QEnvironmentUnset:HEX-VALUE'

  45072.      On UNIX-like targets, it is possible to unset environment variables

  45073.      before starting the inferior in the remote target.  This packet is

  45074.      used to inform 'gdbserver' of an environment variable that has been

  45075.      unset by the user on GDB (*note unset environment::).

  45076. 

  45077.      The packet is composed by HEX-VALUE, an hex encoded representation

  45078.      of the name of the environment variable to be unset.

  45079. 

  45080.      This packet is only available in extended mode (*note extended

  45081.      mode::).

  45082. 

  45083.      Reply:

  45084.      'OK'

  45085.           The request succeeded.

  45086. 

  45087.      This packet is not probed by default; the remote stub must request

  45088.      it, by supplying an appropriate 'qSupported' response (*note

  45089.      qSupported::).  This should only be done on targets that actually

  45090.      support passing environment variables to the starting inferior.

  45091. 

  45092.      This packet is related to the 'unset environment' command; *note

  45093.      unset environment::.

  45094. 

  45095. 'QEnvironmentReset'

  45096.      On UNIX-like targets, this packet is used to reset the state of

  45097.      environment variables in the remote target before starting the

  45098.      inferior.  In this context, reset means unsetting all environment

  45099.      variables that were previously set by the user (i.e., were not

  45100.      initially present in the environment).  It is sent to 'gdbserver'

  45101.      before the 'QEnvironmentHexEncoded' (*note

  45102.      QEnvironmentHexEncoded::) and the 'QEnvironmentUnset' (*note

  45103.      QEnvironmentUnset::) packets.

  45104. 

  45105.      This packet is only available in extended mode (*note extended

  45106.      mode::).

  45107. 

  45108.      Reply:

  45109.      'OK'

  45110.           The request succeeded.

  45111. 

  45112.      This packet is not probed by default; the remote stub must request

  45113.      it, by supplying an appropriate 'qSupported' response (*note

  45114.      qSupported::).  This should only be done on targets that actually

  45115.      support passing environment variables to the starting inferior.

  45116. 

  45117. 'QSetWorkingDir:[DIRECTORY]'

  45118.      This packet is used to inform the remote server of the intended

  45119.      current working directory for programs that are going to be

  45120.      executed.

  45121. 

  45122.      The packet is composed by DIRECTORY, an hex encoded representation

  45123.      of the directory that the remote inferior will use as its current

  45124.      working directory.  If DIRECTORY is an empty string, the remote

  45125.      server should reset the inferior's current working directory to its

  45126.      original, empty value.

  45127. 

  45128.      This packet is only available in extended mode (*note extended

  45129.      mode::).

  45130. 

  45131.      Reply:

  45132.      'OK'

  45133.           The request succeeded.

  45134. 

  45135. 'qfThreadInfo'

  45136. 'qsThreadInfo'

  45137.      Obtain a list of all active thread IDs from the target (OS). Since

  45138.      there may be too many active threads to fit into one reply packet,

  45139.      this query works iteratively: it may require more than one

  45140.      query/reply sequence to obtain the entire list of threads.  The

  45141.      first query of the sequence will be the 'qfThreadInfo' query;

  45142.      subsequent queries in the sequence will be the 'qsThreadInfo'

  45143.      query.

  45144. 

  45145.      NOTE: This packet replaces the 'qL' query (see below).

  45146. 

  45147.      Reply:

  45148.      'm THREAD-ID'

  45149.           A single thread ID

  45150.      'm THREAD-ID,THREAD-ID...'

  45151.           a comma-separated list of thread IDs

  45152.      'l'

  45153.           (lower case letter 'L') denotes end of list.

  45154. 

  45155.      In response to each query, the target will reply with a list of one

  45156.      or more thread IDs, separated by commas.  GDB will respond to each

  45157.      reply with a request for more thread ids (using the 'qs' form of

  45158.      the query), until the target responds with 'l' (lower-case ell, for

  45159.      "last").  Refer to *note thread-id syntax::, for the format of the

  45160.      THREAD-ID fields.

  45161. 

  45162.      _Note: GDB will send the 'qfThreadInfo' query during the initial

  45163.      connection with the remote target, and the very first thread ID

  45164.      mentioned in the reply will be stopped by GDB in a subsequent

  45165.      message.  Therefore, the stub should ensure that the first thread

  45166.      ID in the 'qfThreadInfo' reply is suitable for being stopped by

  45167.      GDB._

  45168. 

  45169. 'qGetTLSAddr:THREAD-ID,OFFSET,LM'

  45170.      Fetch the address associated with thread local storage specified by

  45171.      THREAD-ID, OFFSET, and LM.

  45172. 

  45173.      THREAD-ID is the thread ID associated with the thread for which to

  45174.      fetch the TLS address.  *Note thread-id syntax::.

  45175. 

  45176.      OFFSET is the (big endian, hex encoded) offset associated with the

  45177.      thread local variable.  (This offset is obtained from the debug

  45178.      information associated with the variable.)

  45179. 

  45180.      LM is the (big endian, hex encoded) OS/ABI-specific encoding of the

  45181.      load module associated with the thread local storage.  For example,

  45182.      a GNU/Linux system will pass the link map address of the shared

  45183.      object associated with the thread local storage under

  45184.      consideration.  Other operating environments may choose to

  45185.      represent the load module differently, so the precise meaning of

  45186.      this parameter will vary.

  45187. 

  45188.      Reply:

  45189.      'XX...'

  45190.           Hex encoded (big endian) bytes representing the address of the

  45191.           thread local storage requested.

  45192. 

  45193.      'E NN'

  45194.           An error occurred.  The error number NN is given as hex

  45195.           digits.

  45196. 

  45197.      ''

  45198.           An empty reply indicates that 'qGetTLSAddr' is not supported

  45199.           by the stub.

  45200. 

  45201. 'qGetTIBAddr:THREAD-ID'

  45202.      Fetch address of the Windows OS specific Thread Information Block.

  45203. 

  45204.      THREAD-ID is the thread ID associated with the thread.

  45205. 

  45206.      Reply:

  45207.      'XX...'

  45208.           Hex encoded (big endian) bytes representing the linear address

  45209.           of the thread information block.

  45210. 

  45211.      'E NN'

  45212.           An error occured.  This means that either the thread was not

  45213.           found, or the address could not be retrieved.

  45214. 

  45215.      ''

  45216.           An empty reply indicates that 'qGetTIBAddr' is not supported

  45217.           by the stub.

  45218. 

  45219. 'qL STARTFLAG THREADCOUNT NEXTTHREAD'

  45220.      Obtain thread information from RTOS. Where: STARTFLAG (one hex

  45221.      digit) is one to indicate the first query and zero to indicate a

  45222.      subsequent query; THREADCOUNT (two hex digits) is the maximum

  45223.      number of threads the response packet can contain; and NEXTTHREAD

  45224.      (eight hex digits), for subsequent queries (STARTFLAG is zero), is

  45225.      returned in the response as ARGTHREAD.

  45226. 

  45227.      Don't use this packet; use the 'qfThreadInfo' query instead (see

  45228.      above).

  45229. 

  45230.      Reply:

  45231.      'qM COUNT DONE ARGTHREAD THREAD...'

  45232.           Where: COUNT (two hex digits) is the number of threads being

  45233.           returned; DONE (one hex digit) is zero to indicate more

  45234.           threads and one indicates no further threads; ARGTHREADID

  45235.           (eight hex digits) is NEXTTHREAD from the request packet;

  45236.           THREAD... is a sequence of thread IDs, THREADID (eight hex

  45237.           digits), from the target.  See

  45238.           'remote.c:parse_threadlist_response()'.

  45239. 

  45240. 'qOffsets'

  45241.      Get section offsets that the target used when relocating the

  45242.      downloaded image.

  45243. 

  45244.      Reply:

  45245.      'Text=XXX;Data=YYY[;Bss=ZZZ]'

  45246.           Relocate the 'Text' section by XXX from its original address.

  45247.           Relocate the 'Data' section by YYY from its original address.

  45248.           If the object file format provides segment information (e.g.

  45249.           ELF 'PT_LOAD' program headers), GDB will relocate entire

  45250.           segments by the supplied offsets.

  45251. 

  45252.           _Note: while a 'Bss' offset may be included in the response,

  45253.           GDB ignores this and instead applies the 'Data' offset to the

  45254.           'Bss' section._

  45255. 

  45256.      'TextSeg=XXX[;DataSeg=YYY]'

  45257.           Relocate the first segment of the object file, which

  45258.           conventionally contains program code, to a starting address of

  45259.           XXX.  If 'DataSeg' is specified, relocate the second segment,

  45260.           which conventionally contains modifiable data, to a starting

  45261.           address of YYY.  GDB will report an error if the object file

  45262.           does not contain segment information, or does not contain at

  45263.           least as many segments as mentioned in the reply.  Extra

  45264.           segments are kept at fixed offsets relative to the last

  45265.           relocated segment.

  45266. 

  45267. 'qP MODE THREAD-ID'

  45268.      Returns information on THREAD-ID.  Where: MODE is a hex encoded 32

  45269.      bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).

  45270. 

  45271.      Don't use this packet; use the 'qThreadExtraInfo' query instead

  45272.      (see below).

  45273. 

  45274.      Reply: see 'remote.c:remote_unpack_thread_info_response()'.

  45275. 

  45276. 'QNonStop:1'

  45277. 'QNonStop:0'

  45278.      Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode.

  45279.      *Note Remote Non-Stop::, for more information.

  45280. 

  45281.      Reply:

  45282.      'OK'

  45283.           The request succeeded.

  45284. 

  45285.      'E NN'

  45286.           An error occurred.  The error number NN is given as hex

  45287.           digits.

  45288. 

  45289.      ''

  45290.           An empty reply indicates that 'QNonStop' is not supported by

  45291.           the stub.

  45292. 

  45293.      This packet is not probed by default; the remote stub must request

  45294.      it, by supplying an appropriate 'qSupported' response (*note

  45295.      qSupported::).  Use of this packet is controlled by the 'set

  45296.      non-stop' command; *note Non-Stop Mode::.

  45297. 

  45298. 'QCatchSyscalls:1 [;SYSNO]...'

  45299. 'QCatchSyscalls:0'

  45300.      Enable ('QCatchSyscalls:1') or disable ('QCatchSyscalls:0')

  45301.      catching syscalls from the inferior process.

  45302. 

  45303.      For 'QCatchSyscalls:1', each listed syscall SYSNO (encoded in hex)

  45304.      should be reported to GDB.  If no syscall SYSNO is listed, every

  45305.      system call should be reported.

  45306. 

  45307.      Note that if a syscall not in the list is reported, GDB will still

  45308.      filter the event according to its own list from all corresponding

  45309.      'catch syscall' commands.  However, it is more efficient to only

  45310.      report the requested syscalls.

  45311. 

  45312.      Multiple 'QCatchSyscalls:1' packets do not combine; any earlier

  45313.      'QCatchSyscalls:1' list is completely replaced by the new list.

  45314. 

  45315.      If the inferior process execs, the state of 'QCatchSyscalls' is

  45316.      kept for the new process too.  On targets where exec may affect

  45317.      syscall numbers, for example with exec between 32 and 64-bit

  45318.      processes, the client should send a new packet with the new syscall

  45319.      list.

  45320. 

  45321.      Reply:

  45322.      'OK'

  45323.           The request succeeded.

  45324. 

  45325.      'E NN'

  45326.           An error occurred.  NN are hex digits.

  45327. 

  45328.      ''

  45329.           An empty reply indicates that 'QCatchSyscalls' is not

  45330.           supported by the stub.

  45331. 

  45332.      Use of this packet is controlled by the 'set remote catch-syscalls'

  45333.      command (*note set remote catch-syscalls: Remote Configuration.).

  45334.      This packet is not probed by default; the remote stub must request

  45335.      it, by supplying an appropriate 'qSupported' response (*note

  45336.      qSupported::).

  45337. 

  45338. 'QPassSignals: SIGNAL [;SIGNAL]...'

  45339.      Each listed SIGNAL should be passed directly to the inferior

  45340.      process.  Signals are numbered identically to continue packets and

  45341.      stop replies (*note Stop Reply Packets::).  Each SIGNAL list item

  45342.      should be strictly greater than the previous item.  These signals

  45343.      do not need to stop the inferior, or be reported to GDB.  All other

  45344.      signals should be reported to GDB.  Multiple 'QPassSignals' packets

  45345.      do not combine; any earlier 'QPassSignals' list is completely

  45346.      replaced by the new list.  This packet improves performance when

  45347.      using 'handle SIGNAL nostop noprint pass'.

  45348. 

  45349.      Reply:

  45350.      'OK'

  45351.           The request succeeded.

  45352. 

  45353.      'E NN'

  45354.           An error occurred.  The error number NN is given as hex

  45355.           digits.

  45356. 

  45357.      ''

  45358.           An empty reply indicates that 'QPassSignals' is not supported

  45359.           by the stub.

  45360. 

  45361.      Use of this packet is controlled by the 'set remote pass-signals'

  45362.      command (*note set remote pass-signals: Remote Configuration.).

  45363.      This packet is not probed by default; the remote stub must request

  45364.      it, by supplying an appropriate 'qSupported' response (*note

  45365.      qSupported::).

  45366. 

  45367. 'QProgramSignals: SIGNAL [;SIGNAL]...'

  45368.      Each listed SIGNAL may be delivered to the inferior process.

  45369.      Others should be silently discarded.

  45370. 

  45371.      In some cases, the remote stub may need to decide whether to

  45372.      deliver a signal to the program or not without GDB involvement.

  45373.      One example of that is while detaching -- the program's threads may

  45374.      have stopped for signals that haven't yet had a chance of being

  45375.      reported to GDB, and so the remote stub can use the signal list

  45376.      specified by this packet to know whether to deliver or ignore those

  45377.      pending signals.

  45378. 

  45379.      This does not influence whether to deliver a signal as requested by

  45380.      a resumption packet (*note vCont packet::).

  45381. 

  45382.      Signals are numbered identically to continue packets and stop

  45383.      replies (*note Stop Reply Packets::).  Each SIGNAL list item should

  45384.      be strictly greater than the previous item.  Multiple

  45385.      'QProgramSignals' packets do not combine; any earlier

  45386.      'QProgramSignals' list is completely replaced by the new list.

  45387. 

  45388.      Reply:

  45389.      'OK'

  45390.           The request succeeded.

  45391. 

  45392.      'E NN'

  45393.           An error occurred.  The error number NN is given as hex

  45394.           digits.

  45395. 

  45396.      ''

  45397.           An empty reply indicates that 'QProgramSignals' is not

  45398.           supported by the stub.

  45399. 

  45400.      Use of this packet is controlled by the 'set remote

  45401.      program-signals' command (*note set remote program-signals: Remote

  45402.      Configuration.).  This packet is not probed by default; the remote

  45403.      stub must request it, by supplying an appropriate 'qSupported'

  45404.      response (*note qSupported::).

  45405. 

  45406. 'QThreadEvents:1'

  45407. 'QThreadEvents:0'

  45408. 

  45409.      Enable ('QThreadEvents:1') or disable ('QThreadEvents:0') reporting

  45410.      of thread create and exit events.  *Note thread create event::, for

  45411.      the reply specifications.  For example, this is used in non-stop

  45412.      mode when GDB stops a set of threads and synchronously waits for

  45413.      the their corresponding stop replies.  Without exit events, if one

  45414.      of the threads exits, GDB would hang forever not knowing that it

  45415.      should no longer expect a stop for that same thread.  GDB does not

  45416.      enable this feature unless the stub reports that it supports it by

  45417.      including 'QThreadEvents+' in its 'qSupported' reply.

  45418. 

  45419.      Reply:

  45420.      'OK'

  45421.           The request succeeded.

  45422. 

  45423.      'E NN'

  45424.           An error occurred.  The error number NN is given as hex

  45425.           digits.

  45426. 

  45427.      ''

  45428.           An empty reply indicates that 'QThreadEvents' is not supported

  45429.           by the stub.

  45430. 

  45431.      Use of this packet is controlled by the 'set remote thread-events'

  45432.      command (*note set remote thread-events: Remote Configuration.).

  45433. 

  45434. 'qRcmd,COMMAND'

  45435.      COMMAND (hex encoded) is passed to the local interpreter for

  45436.      execution.  Invalid commands should be reported using the output

  45437.      string.  Before the final result packet, the target may also

  45438.      respond with a number of intermediate 'OOUTPUT' console output

  45439.      packets.  _Implementors should note that providing access to a

  45440.      stubs's interpreter may have security implications_.

  45441. 

  45442.      Reply:

  45443.      'OK'

  45444.           A command response with no output.

  45445.      'OUTPUT'

  45446.           A command response with the hex encoded output string OUTPUT.

  45447.      'E NN'

  45448.           Indicate a badly formed request.

  45449.      ''

  45450.           An empty reply indicates that 'qRcmd' is not recognized.

  45451. 

  45452.      (Note that the 'qRcmd' packet's name is separated from the command

  45453.      by a ',', not a ':', contrary to the naming conventions above.

  45454.      Please don't use this packet as a model for new packets.)

  45455. 

  45456. 'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'

  45457.      Search LENGTH bytes at ADDRESS for SEARCH-PATTERN.  Both ADDRESS

  45458.      and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of

  45459.      bytes, also hex encoded.

  45460. 

  45461.      Reply:

  45462.      '0'

  45463.           The pattern was not found.

  45464.      '1,address'

  45465.           The pattern was found at ADDRESS.

  45466.      'E NN'

  45467.           A badly formed request or an error was encountered while

  45468.           searching memory.

  45469.      ''

  45470.           An empty reply indicates that 'qSearch:memory' is not

  45471.           recognized.

  45472. 

  45473. 'QStartNoAckMode'

  45474.      Request that the remote stub disable the normal '+'/'-' protocol

  45475.      acknowledgments (*note Packet Acknowledgment::).

  45476. 

  45477.      Reply:

  45478.      'OK'

  45479.           The stub has switched to no-acknowledgment mode.  GDB

  45480.           acknowledges this response, but neither the stub nor GDB shall

  45481.           send or expect further '+'/'-' acknowledgments in the current

  45482.           connection.

  45483.      ''

  45484.           An empty reply indicates that the stub does not support

  45485.           no-acknowledgment mode.

  45486. 

  45487. 'qSupported [:GDBFEATURE [;GDBFEATURE]... ]'

  45488.      Tell the remote stub about features supported by GDB, and query the

  45489.      stub for features it supports.  This packet allows GDB and the

  45490.      remote stub to take advantage of each others' features.

  45491.      'qSupported' also consolidates multiple feature probes at startup,

  45492.      to improve GDB performance--a single larger packet performs better

  45493.      than multiple smaller probe packets on high-latency links.  Some

  45494.      features may enable behavior which must not be on by default, e.g.

  45495.      because it would confuse older clients or stubs.  Other features

  45496.      may describe packets which could be automatically probed for, but

  45497.      are not.  These features must be reported before GDB will use them.

  45498.      This "default unsupported" behavior is not appropriate for all

  45499.      packets, but it helps to keep the initial connection time under

  45500.      control with new versions of GDB which support increasing numbers

  45501.      of packets.

  45502. 

  45503.      Reply:

  45504.      'STUBFEATURE [;STUBFEATURE]...'

  45505.           The stub supports or does not support each returned

  45506.           STUBFEATURE, depending on the form of each STUBFEATURE (see

  45507.           below for the possible forms).

  45508.      ''

  45509.           An empty reply indicates that 'qSupported' is not recognized,

  45510.           or that no features needed to be reported to GDB.

  45511. 

  45512.      The allowed forms for each feature (either a GDBFEATURE in the

  45513.      'qSupported' packet, or a STUBFEATURE in the response) are:

  45514. 

  45515.      'NAME=VALUE'

  45516.           The remote protocol feature NAME is supported, and associated

  45517.           with the specified VALUE.  The format of VALUE depends on the

  45518.           feature, but it must not include a semicolon.

  45519.      'NAME+'

  45520.           The remote protocol feature NAME is supported, and does not

  45521.           need an associated value.

  45522.      'NAME-'

  45523.           The remote protocol feature NAME is not supported.

  45524.      'NAME?'

  45525.           The remote protocol feature NAME may be supported, and GDB

  45526.           should auto-detect support in some other way when it is

  45527.           needed.  This form will not be used for GDBFEATURE

  45528.           notifications, but may be used for STUBFEATURE responses.

  45529. 

  45530.      Whenever the stub receives a 'qSupported' request, the supplied set

  45531.      of GDB features should override any previous request.  This allows

  45532.      GDB to put the stub in a known state, even if the stub had

  45533.      previously been communicating with a different version of GDB.

  45534. 

  45535.      The following values of GDBFEATURE (for the packet sent by GDB) are

  45536.      defined:

  45537. 

  45538.      'multiprocess'

  45539.           This feature indicates whether GDB supports multiprocess

  45540.           extensions to the remote protocol.  GDB does not use such

  45541.           extensions unless the stub also reports that it supports them

  45542.           by including 'multiprocess+' in its 'qSupported' reply.  *Note

  45543.           multiprocess extensions::, for details.

  45544. 

  45545.      'xmlRegisters'

  45546.           This feature indicates that GDB supports the XML target

  45547.           description.  If the stub sees 'xmlRegisters=' with target

  45548.           specific strings separated by a comma, it will report register

  45549.           description.

  45550. 

  45551.      'qRelocInsn'

  45552.           This feature indicates whether GDB supports the 'qRelocInsn'

  45553.           packet (*note Relocate instruction reply packet: Tracepoint

  45554.           Packets.).

  45555. 

  45556.      'swbreak'

  45557.           This feature indicates whether GDB supports the swbreak stop

  45558.           reason in stop replies.  *Note swbreak stop reason::, for

  45559.           details.

  45560. 

  45561.      'hwbreak'

  45562.           This feature indicates whether GDB supports the hwbreak stop

  45563.           reason in stop replies.  *Note swbreak stop reason::, for

  45564.           details.

  45565. 

  45566.      'fork-events'

  45567.           This feature indicates whether GDB supports fork event

  45568.           extensions to the remote protocol.  GDB does not use such

  45569.           extensions unless the stub also reports that it supports them

  45570.           by including 'fork-events+' in its 'qSupported' reply.

  45571. 

  45572.      'vfork-events'

  45573.           This feature indicates whether GDB supports vfork event

  45574.           extensions to the remote protocol.  GDB does not use such

  45575.           extensions unless the stub also reports that it supports them

  45576.           by including 'vfork-events+' in its 'qSupported' reply.

  45577. 

  45578.      'exec-events'

  45579.           This feature indicates whether GDB supports exec event

  45580.           extensions to the remote protocol.  GDB does not use such

  45581.           extensions unless the stub also reports that it supports them

  45582.           by including 'exec-events+' in its 'qSupported' reply.

  45583. 

  45584.      'vContSupported'

  45585.           This feature indicates whether GDB wants to know the supported

  45586.           actions in the reply to 'vCont?' packet.

  45587. 

  45588.      Stubs should ignore any unknown values for GDBFEATURE.  Any GDB

  45589.      which sends a 'qSupported' packet supports receiving packets of

  45590.      unlimited length (earlier versions of GDB may reject overly long

  45591.      responses).  Additional values for GDBFEATURE may be defined in the

  45592.      future to let the stub take advantage of new features in GDB, e.g.

  45593.      incompatible improvements in the remote protocol--the

  45594.      'multiprocess' feature is an example of such a feature.  The stub's

  45595.      reply should be independent of the GDBFEATURE entries sent by GDB;

  45596.      first GDB describes all the features it supports, and then the stub

  45597.      replies with all the features it supports.

  45598. 

  45599.      Similarly, GDB will silently ignore unrecognized stub feature

  45600.      responses, as long as each response uses one of the standard forms.

  45601. 

  45602.      Some features are flags.  A stub which supports a flag feature

  45603.      should respond with a '+' form response.  Other features require

  45604.      values, and the stub should respond with an '=' form response.

  45605. 

  45606.      Each feature has a default value, which GDB will use if

  45607.      'qSupported' is not available or if the feature is not mentioned in

  45608.      the 'qSupported' response.  The default values are fixed; a stub is

  45609.      free to omit any feature responses that match the defaults.

  45610. 

  45611.      Not all features can be probed, but for those which can, the

  45612.      probing mechanism is useful: in some cases, a stub's internal

  45613.      architecture may not allow the protocol layer to know some

  45614.      information about the underlying target in advance.  This is

  45615.      especially common in stubs which may be configured for multiple

  45616.      targets.

  45617. 

  45618.      These are the currently defined stub features and their properties:

  45619. 

  45620.      Feature Name              Value          Default   Probe

  45621.                                Required                 Allowed

  45622.                                                         

  45623.      'PacketSize'              Yes            '-'       No

  45624.                                                         

  45625.      'qXfer:auxv:read'         No             '-'       Yes

  45626.                                                         

  45627.      'qXfer:btrace:read'       No             '-'       Yes

  45628.                                                         

  45629.      'qXfer:btrace-conf:read'  No             '-'       Yes

  45630.                                                         

  45631.      'qXfer:exec-file:read'    No             '-'       Yes

  45632.                                                         

  45633.      'qXfer:features:read'     No             '-'       Yes

  45634.                                                         

  45635.      'qXfer:libraries:read'    No             '-'       Yes

  45636.                                                         

  45637.      'qXfer:libraries-svr4:read'No            '-'       Yes

  45638.                                                         

  45639.      'augmented-libraries-svr4-read'No        '-'       No

  45640.                                                         

  45641.      'qXfer:memory-map:read'   No             '-'       Yes

  45642.                                                         

  45643.      'qXfer:sdata:read'        No             '-'       Yes

  45644.                                                         

  45645.      'qXfer:siginfo:read'      No             '-'       Yes

  45646.                                                         

  45647.      'qXfer:siginfo:write'     No             '-'       Yes

  45648.                                                         

  45649.      'qXfer:threads:read'      No             '-'       Yes

  45650.                                                         

  45651.      'qXfer:traceframe-info:read'No           '-'       Yes

  45652.                                                         

  45653.      'qXfer:uib:read'          No             '-'       Yes

  45654.                                                         

  45655.      'qXfer:fdpic:read'        No             '-'       Yes

  45656.                                                         

  45657.      'Qbtrace:off'             Yes            '-'       Yes

  45658.                                                         

  45659.      'Qbtrace:bts'             Yes            '-'       Yes

  45660.                                                         

  45661.      'Qbtrace:pt'              Yes            '-'       Yes

  45662.                                                         

  45663.      'Qbtrace-conf:bts:size'   Yes            '-'       Yes

  45664.                                                         

  45665.      'Qbtrace-conf:pt:size'    Yes            '-'       Yes

  45666.                                                         

  45667.      'QNonStop'                No             '-'       Yes

  45668.                                                         

  45669.      'QCatchSyscalls'          No             '-'       Yes

  45670.                                                         

  45671.      'QPassSignals'            No             '-'       Yes

  45672.                                                         

  45673.      'QStartNoAckMode'         No             '-'       Yes

  45674.                                                         

  45675.      'multiprocess'            No             '-'       No

  45676.                                                         

  45677.      'ConditionalBreakpoints'  No             '-'       No

  45678.                                                         

  45679.      'ConditionalTracepoints'  No             '-'       No

  45680.                                                         

  45681.      'ReverseContinue'         No             '-'       No

  45682.                                                         

  45683.      'ReverseStep'             No             '-'       No

  45684.                                                         

  45685.      'TracepointSource'        No             '-'       No

  45686.                                                         

  45687.      'QAgent'                  No             '-'       No

  45688.                                                         

  45689.      'QAllow'                  No             '-'       No

  45690.                                                         

  45691.      'QDisableRandomization'   No             '-'       No

  45692.                                                         

  45693.      'EnableDisableTracepoints'No             '-'       No

  45694.                                                         

  45695.      'QTBuffer:size'           No             '-'       No

  45696.                                                         

  45697.      'tracenz'                 No             '-'       No

  45698.                                                         

  45699.      'BreakpointCommands'      No             '-'       No

  45700.                                                         

  45701.      'swbreak'                 No             '-'       No

  45702.                                                         

  45703.      'hwbreak'                 No             '-'       No

  45704.                                                         

  45705.      'fork-events'             No             '-'       No

  45706.                                                         

  45707.      'vfork-events'            No             '-'       No

  45708.                                                         

  45709.      'exec-events'             No             '-'       No

  45710.                                                         

  45711.      'QThreadEvents'           No             '-'       No

  45712.                                                         

  45713.      'no-resumed'              No             '-'       No

  45714.                                                         

  45715. 

  45716.      These are the currently defined stub features, in more detail:

  45717. 

  45718.      'PacketSize=BYTES'

  45719.           The remote stub can accept packets up to at least BYTES in

  45720.           length.  GDB will send packets up to this size for bulk

  45721.           transfers, and will never send larger packets.  This is a

  45722.           limit on the data characters in the packet, including the

  45723.           frame and checksum.  There is no trailing NUL byte in a remote

  45724.           protocol packet; if the stub stores packets in a

  45725.           NUL-terminated format, it should allow an extra byte in its

  45726.           buffer for the NUL. If this stub feature is not supported, GDB

  45727.           guesses based on the size of the 'g' packet response.

  45728. 

  45729.      'qXfer:auxv:read'

  45730.           The remote stub understands the 'qXfer:auxv:read' packet

  45731.           (*note qXfer auxiliary vector read::).

  45732. 

  45733.      'qXfer:btrace:read'

  45734.           The remote stub understands the 'qXfer:btrace:read' packet

  45735.           (*note qXfer btrace read::).

  45736. 

  45737.      'qXfer:btrace-conf:read'

  45738.           The remote stub understands the 'qXfer:btrace-conf:read'

  45739.           packet (*note qXfer btrace-conf read::).

  45740. 

  45741.      'qXfer:exec-file:read'

  45742.           The remote stub understands the 'qXfer:exec-file:read' packet

  45743.           (*note qXfer executable filename read::).

  45744. 

  45745.      'qXfer:features:read'

  45746.           The remote stub understands the 'qXfer:features:read' packet

  45747.           (*note qXfer target description read::).

  45748. 

  45749.      'qXfer:libraries:read'

  45750.           The remote stub understands the 'qXfer:libraries:read' packet

  45751.           (*note qXfer library list read::).

  45752. 

  45753.      'qXfer:libraries-svr4:read'

  45754.           The remote stub understands the 'qXfer:libraries-svr4:read'

  45755.           packet (*note qXfer svr4 library list read::).

  45756. 

  45757.      'augmented-libraries-svr4-read'

  45758.           The remote stub understands the augmented form of the

  45759.           'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library

  45760.           list read::).

  45761. 

  45762.      'qXfer:memory-map:read'

  45763.           The remote stub understands the 'qXfer:memory-map:read' packet

  45764.           (*note qXfer memory map read::).

  45765. 

  45766.      'qXfer:sdata:read'

  45767.           The remote stub understands the 'qXfer:sdata:read' packet

  45768.           (*note qXfer sdata read::).

  45769. 

  45770.      'qXfer:siginfo:read'

  45771.           The remote stub understands the 'qXfer:siginfo:read' packet

  45772.           (*note qXfer siginfo read::).

  45773. 

  45774.      'qXfer:siginfo:write'

  45775.           The remote stub understands the 'qXfer:siginfo:write' packet

  45776.           (*note qXfer siginfo write::).

  45777. 

  45778.      'qXfer:threads:read'

  45779.           The remote stub understands the 'qXfer:threads:read' packet

  45780.           (*note qXfer threads read::).

  45781. 

  45782.      'qXfer:traceframe-info:read'

  45783.           The remote stub understands the 'qXfer:traceframe-info:read'

  45784.           packet (*note qXfer traceframe info read::).

  45785. 

  45786.      'qXfer:uib:read'

  45787.           The remote stub understands the 'qXfer:uib:read' packet (*note

  45788.           qXfer unwind info block::).

  45789. 

  45790.      'qXfer:fdpic:read'

  45791.           The remote stub understands the 'qXfer:fdpic:read' packet

  45792.           (*note qXfer fdpic loadmap read::).

  45793. 

  45794.      'QNonStop'

  45795.           The remote stub understands the 'QNonStop' packet (*note

  45796.           QNonStop::).

  45797. 

  45798.      'QCatchSyscalls'

  45799.           The remote stub understands the 'QCatchSyscalls' packet (*note

  45800.           QCatchSyscalls::).

  45801. 

  45802.      'QPassSignals'

  45803.           The remote stub understands the 'QPassSignals' packet (*note

  45804.           QPassSignals::).

  45805. 

  45806.      'QStartNoAckMode'

  45807.           The remote stub understands the 'QStartNoAckMode' packet and

  45808.           prefers to operate in no-acknowledgment mode.  *Note Packet

  45809.           Acknowledgment::.

  45810. 

  45811.      'multiprocess'

  45812.           The remote stub understands the multiprocess extensions to the

  45813.           remote protocol syntax.  The multiprocess extensions affect

  45814.           the syntax of thread IDs in both packets and replies (*note

  45815.           thread-id syntax::), and add process IDs to the 'D' packet and

  45816.           'W' and 'X' replies.  Note that reporting this feature

  45817.           indicates support for the syntactic extensions only, not that

  45818.           the stub necessarily supports debugging of more than one

  45819.           process at a time.  The stub must not use multiprocess

  45820.           extensions in packet replies unless GDB has also indicated it

  45821.           supports them in its 'qSupported' request.

  45822. 

  45823.      'qXfer:osdata:read'

  45824.           The remote stub understands the 'qXfer:osdata:read' packet

  45825.           ((*note qXfer osdata read::).

  45826. 

  45827.      'ConditionalBreakpoints'

  45828.           The target accepts and implements evaluation of conditional

  45829.           expressions defined for breakpoints.  The target will only

  45830.           report breakpoint triggers when such conditions are true

  45831.           (*note Break Conditions: Conditions.).

  45832. 

  45833.      'ConditionalTracepoints'

  45834.           The remote stub accepts and implements conditional expressions

  45835.           defined for tracepoints (*note Tracepoint Conditions::).

  45836. 

  45837.      'ReverseContinue'

  45838.           The remote stub accepts and implements the reverse continue

  45839.           packet (*note bc::).

  45840. 

  45841.      'ReverseStep'

  45842.           The remote stub accepts and implements the reverse step packet

  45843.           (*note bs::).

  45844. 

  45845.      'TracepointSource'

  45846.           The remote stub understands the 'QTDPsrc' packet that supplies

  45847.           the source form of tracepoint definitions.

  45848. 

  45849.      'QAgent'

  45850.           The remote stub understands the 'QAgent' packet.

  45851. 

  45852.      'QAllow'

  45853.           The remote stub understands the 'QAllow' packet.

  45854. 

  45855.      'QDisableRandomization'

  45856.           The remote stub understands the 'QDisableRandomization'

  45857.           packet.

  45858. 

  45859.      'StaticTracepoint'

  45860.           The remote stub supports static tracepoints.

  45861. 

  45862.      'InstallInTrace'

  45863.           The remote stub supports installing tracepoint in tracing.

  45864. 

  45865.      'EnableDisableTracepoints'

  45866.           The remote stub supports the 'QTEnable' (*note QTEnable::) and

  45867.           'QTDisable' (*note QTDisable::) packets that allow tracepoints

  45868.           to be enabled and disabled while a trace experiment is

  45869.           running.

  45870. 

  45871.      'QTBuffer:size'

  45872.           The remote stub supports the 'QTBuffer:size' (*note

  45873.           QTBuffer-size::) packet that allows to change the size of the

  45874.           trace buffer.

  45875. 

  45876.      'tracenz'

  45877.           The remote stub supports the 'tracenz' bytecode for collecting

  45878.           strings.  See *note Bytecode Descriptions:: for details about

  45879.           the bytecode.

  45880. 

  45881.      'BreakpointCommands'

  45882.           The remote stub supports running a breakpoint's command list

  45883.           itself, rather than reporting the hit to GDB.

  45884. 

  45885.      'Qbtrace:off'

  45886.           The remote stub understands the 'Qbtrace:off' packet.

  45887. 

  45888.      'Qbtrace:bts'

  45889.           The remote stub understands the 'Qbtrace:bts' packet.

  45890. 

  45891.      'Qbtrace:pt'

  45892.           The remote stub understands the 'Qbtrace:pt' packet.

  45893. 

  45894.      'Qbtrace-conf:bts:size'

  45895.           The remote stub understands the 'Qbtrace-conf:bts:size'

  45896.           packet.

  45897. 

  45898.      'Qbtrace-conf:pt:size'

  45899.           The remote stub understands the 'Qbtrace-conf:pt:size' packet.

  45900. 

  45901.      'swbreak'

  45902.           The remote stub reports the 'swbreak' stop reason for memory

  45903.           breakpoints.

  45904. 

  45905.      'hwbreak'

  45906.           The remote stub reports the 'hwbreak' stop reason for hardware

  45907.           breakpoints.

  45908. 

  45909.      'fork-events'

  45910.           The remote stub reports the 'fork' stop reason for fork

  45911.           events.

  45912. 

  45913.      'vfork-events'

  45914.           The remote stub reports the 'vfork' stop reason for vfork

  45915.           events and vforkdone events.

  45916. 

  45917.      'exec-events'

  45918.           The remote stub reports the 'exec' stop reason for exec

  45919.           events.

  45920. 

  45921.      'vContSupported'

  45922.           The remote stub reports the supported actions in the reply to

  45923.           'vCont?' packet.

  45924. 

  45925.      'QThreadEvents'

  45926.           The remote stub understands the 'QThreadEvents' packet.

  45927. 

  45928.      'no-resumed'

  45929.           The remote stub reports the 'N' stop reply.

  45930. 

  45931. 'qSymbol::'

  45932.      Notify the target that GDB is prepared to serve symbol lookup

  45933.      requests.  Accept requests from the target for the values of

  45934.      symbols.

  45935. 

  45936.      Reply:

  45937.      'OK'

  45938.           The target does not need to look up any (more) symbols.

  45939.      'qSymbol:SYM_NAME'

  45940.           The target requests the value of symbol SYM_NAME (hex

  45941.           encoded).  GDB may provide the value by using the

  45942.           'qSymbol:SYM_VALUE:SYM_NAME' message, described below.

  45943. 

  45944. 'qSymbol:SYM_VALUE:SYM_NAME'

  45945.      Set the value of SYM_NAME to SYM_VALUE.

  45946. 

  45947.      SYM_NAME (hex encoded) is the name of a symbol whose value the

  45948.      target has previously requested.

  45949. 

  45950.      SYM_VALUE (hex) is the value for symbol SYM_NAME.  If GDB cannot

  45951.      supply a value for SYM_NAME, then this field will be empty.

  45952. 

  45953.      Reply:

  45954.      'OK'

  45955.           The target does not need to look up any (more) symbols.

  45956.      'qSymbol:SYM_NAME'

  45957.           The target requests the value of a new symbol SYM_NAME (hex

  45958.           encoded).  GDB will continue to supply the values of symbols

  45959.           (if available), until the target ceases to request them.

  45960. 

  45961. 'qTBuffer'

  45962. 'QTBuffer'

  45963. 'QTDisconnected'

  45964. 'QTDP'

  45965. 'QTDPsrc'

  45966. 'QTDV'

  45967. 'qTfP'

  45968. 'qTfV'

  45969. 'QTFrame'

  45970. 'qTMinFTPILen'

  45971. 

  45972.      *Note Tracepoint Packets::.

  45973. 

  45974. 'qThreadExtraInfo,THREAD-ID'

  45975.      Obtain from the target OS a printable string description of thread

  45976.      attributes for the thread THREAD-ID; see *note thread-id syntax::,

  45977.      for the forms of THREAD-ID.  This string may contain anything that

  45978.      the target OS thinks is interesting for GDB to tell the user about

  45979.      the thread.  The string is displayed in GDB's 'info threads'

  45980.      display.  Some examples of possible thread extra info strings are

  45981.      'Runnable', or 'Blocked on Mutex'.

  45982. 

  45983.      Reply:

  45984.      'XX...'

  45985.           Where 'XX...' is a hex encoding of ASCII data, comprising the

  45986.           printable string containing the extra information about the

  45987.           thread's attributes.

  45988. 

  45989.      (Note that the 'qThreadExtraInfo' packet's name is separated from

  45990.      the command by a ',', not a ':', contrary to the naming conventions

  45991.      above.  Please don't use this packet as a model for new packets.)

  45992. 

  45993. 'QTNotes'

  45994. 'qTP'

  45995. 'QTSave'

  45996. 'qTsP'

  45997. 'qTsV'

  45998. 'QTStart'

  45999. 'QTStop'

  46000. 'QTEnable'

  46001. 'QTDisable'

  46002. 'QTinit'

  46003. 'QTro'

  46004. 'qTStatus'

  46005. 'qTV'

  46006. 'qTfSTM'

  46007. 'qTsSTM'

  46008. 'qTSTMat'

  46009.      *Note Tracepoint Packets::.

  46010. 

  46011. 'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'

  46012.      Read uninterpreted bytes from the target's special data area

  46013.      identified by the keyword OBJECT.  Request LENGTH bytes starting at

  46014.      OFFSET bytes into the data.  The content and encoding of ANNEX is

  46015.      specific to OBJECT; it can supply additional details about what

  46016.      data to access.

  46017. 

  46018.      Reply:

  46019.      'm DATA'

  46020.           Data DATA (*note Binary Data::) has been read from the target.

  46021.           There may be more data at a higher address (although it is

  46022.           permitted to return 'm' even for the last valid block of data,

  46023.           as long as at least one byte of data was read).  It is

  46024.           possible for DATA to have fewer bytes than the LENGTH in the

  46025.           request.

  46026. 

  46027.      'l DATA'

  46028.           Data DATA (*note Binary Data::) has been read from the target.

  46029.           There is no more data to be read.  It is possible for DATA to

  46030.           have fewer bytes than the LENGTH in the request.

  46031. 

  46032.      'l'

  46033.           The OFFSET in the request is at the end of the data.  There is

  46034.           no more data to be read.

  46035. 

  46036.      'E00'

  46037.           The request was malformed, or ANNEX was invalid.

  46038. 

  46039.      'E NN'

  46040.           The offset was invalid, or there was an error encountered

  46041.           reading the data.  The NN part is a hex-encoded 'errno' value.

  46042. 

  46043.      ''

  46044.           An empty reply indicates the OBJECT string was not recognized

  46045.           by the stub, or that the object does not support reading.

  46046. 

  46047.      Here are the specific requests of this form defined so far.  All

  46048.      the 'qXfer:OBJECT:read:...' requests use the same reply formats,

  46049.      listed above.

  46050. 

  46051.      'qXfer:auxv:read::OFFSET,LENGTH'

  46052.           Access the target's "auxiliary vector".  *Note auxiliary

  46053.           vector: OS Information.  Note ANNEX must be empty.

  46054. 

  46055.           This packet is not probed by default; the remote stub must

  46056.           request it, by supplying an appropriate 'qSupported' response

  46057.           (*note qSupported::).

  46058. 

  46059.      'qXfer:btrace:read:ANNEX:OFFSET,LENGTH'

  46060. 

  46061.           Return a description of the current branch trace.  *Note

  46062.           Branch Trace Format::.  The annex part of the generic 'qXfer'

  46063.           packet may have one of the following values:

  46064. 

  46065.           'all'

  46066.                Returns all available branch trace.

  46067. 

  46068.           'new'

  46069.                Returns all available branch trace if the branch trace

  46070.                changed since the last read request.

  46071. 

  46072.           'delta'

  46073.                Returns the new branch trace since the last read request.

  46074.                Adds a new block to the end of the trace that begins at

  46075.                zero and ends at the source location of the first branch

  46076.                in the trace buffer.  This extra block is used to stitch

  46077.                traces together.

  46078. 

  46079.                If the trace buffer overflowed, returns an error

  46080.                indicating the overflow.

  46081. 

  46082.           This packet is not probed by default; the remote stub must

  46083.           request it by supplying an appropriate 'qSupported' response

  46084.           (*note qSupported::).

  46085. 

  46086.      'qXfer:btrace-conf:read::OFFSET,LENGTH'

  46087. 

  46088.           Return a description of the current branch trace

  46089.           configuration.  *Note Branch Trace Configuration Format::.

  46090. 

  46091.           This packet is not probed by default; the remote stub must

  46092.           request it by supplying an appropriate 'qSupported' response

  46093.           (*note qSupported::).

  46094. 

  46095.      'qXfer:exec-file:read:ANNEX:OFFSET,LENGTH'

  46096.           Return the full absolute name of the file that was executed to

  46097.           create a process running on the remote system.  The annex

  46098.           specifies the numeric process ID of the process to query,

  46099.           encoded as a hexadecimal number.  If the annex part is empty

  46100.           the remote stub should return the filename corresponding to

  46101.           the currently executing process.

  46102. 

  46103.           This packet is not probed by default; the remote stub must

  46104.           request it, by supplying an appropriate 'qSupported' response

  46105.           (*note qSupported::).

  46106. 

  46107.      'qXfer:features:read:ANNEX:OFFSET,LENGTH'

  46108.           Access the "target description".  *Note Target Descriptions::.

  46109.           The annex specifies which XML document to access.  The main

  46110.           description is always loaded from the 'target.xml' annex.

  46111. 

  46112.           This packet is not probed by default; the remote stub must

  46113.           request it, by supplying an appropriate 'qSupported' response

  46114.           (*note qSupported::).

  46115. 

  46116.      'qXfer:libraries:read:ANNEX:OFFSET,LENGTH'

  46117.           Access the target's list of loaded libraries.  *Note Library

  46118.           List Format::.  The annex part of the generic 'qXfer' packet

  46119.           must be empty (*note qXfer read::).

  46120. 

  46121.           Targets which maintain a list of libraries in the program's

  46122.           memory do not need to implement this packet; it is designed

  46123.           for platforms where the operating system manages the list of

  46124.           loaded libraries.

  46125. 

  46126.           This packet is not probed by default; the remote stub must

  46127.           request it, by supplying an appropriate 'qSupported' response

  46128.           (*note qSupported::).

  46129. 

  46130.      'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'

  46131.           Access the target's list of loaded libraries when the target

  46132.           is an SVR4 platform.  *Note Library List Format for SVR4

  46133.           Targets::.  The annex part of the generic 'qXfer' packet must

  46134.           be empty unless the remote stub indicated it supports the

  46135.           augmented form of this packet by supplying an appropriate

  46136.           'qSupported' response (*note qXfer read::, *note

  46137.           qSupported::).

  46138. 

  46139.           This packet is optional for better performance on SVR4

  46140.           targets.  GDB uses memory read packets to read the SVR4

  46141.           library list otherwise.

  46142. 

  46143.           This packet is not probed by default; the remote stub must

  46144.           request it, by supplying an appropriate 'qSupported' response

  46145.           (*note qSupported::).

  46146. 

  46147.           If the remote stub indicates it supports the augmented form of

  46148.           this packet then the annex part of the generic 'qXfer' packet

  46149.           may contain a semicolon-separated list of 'NAME=VALUE'

  46150.           arguments.  The currently supported arguments are:

  46151. 

  46152.           'start=ADDRESS'

  46153.                A hexadecimal number specifying the address of the

  46154.                'struct link_map' to start reading the library list from.

  46155.                If unset or zero then the first 'struct link_map' in the

  46156.                library list will be chosen as the starting point.

  46157. 

  46158.           'prev=ADDRESS'

  46159.                A hexadecimal number specifying the address of the

  46160.                'struct link_map' immediately preceding the 'struct

  46161.                link_map' specified by the 'start' argument.  If unset or

  46162.                zero then the remote stub will expect that no 'struct

  46163.                link_map' exists prior to the starting point.

  46164. 

  46165.           Arguments that are not understood by the remote stub will be

  46166.           silently ignored.

  46167. 

  46168.      'qXfer:memory-map:read::OFFSET,LENGTH'

  46169.           Access the target's "memory-map".  *Note Memory Map Format::.

  46170.           The annex part of the generic 'qXfer' packet must be empty

  46171.           (*note qXfer read::).

  46172. 

  46173.           This packet is not probed by default; the remote stub must

  46174.           request it, by supplying an appropriate 'qSupported' response

  46175.           (*note qSupported::).

  46176. 

  46177.      'qXfer:sdata:read::OFFSET,LENGTH'

  46178. 

  46179.           Read contents of the extra collected static tracepoint marker

  46180.           information.  The annex part of the generic 'qXfer' packet

  46181.           must be empty (*note qXfer read::).  *Note Tracepoint Action

  46182.           Lists: Tracepoint Actions.

  46183. 

  46184.           This packet is not probed by default; the remote stub must

  46185.           request it, by supplying an appropriate 'qSupported' response

  46186.           (*note qSupported::).

  46187. 

  46188.      'qXfer:siginfo:read::OFFSET,LENGTH'

  46189.           Read contents of the extra signal information on the target

  46190.           system.  The annex part of the generic 'qXfer' packet must be

  46191.           empty (*note qXfer read::).

  46192. 

  46193.           This packet is not probed by default; the remote stub must

  46194.           request it, by supplying an appropriate 'qSupported' response

  46195.           (*note qSupported::).

  46196. 

  46197.      'qXfer:threads:read::OFFSET,LENGTH'

  46198.           Access the list of threads on target.  *Note Thread List

  46199.           Format::.  The annex part of the generic 'qXfer' packet must

  46200.           be empty (*note qXfer read::).

  46201. 

  46202.           This packet is not probed by default; the remote stub must

  46203.           request it, by supplying an appropriate 'qSupported' response

  46204.           (*note qSupported::).

  46205. 

  46206.      'qXfer:traceframe-info:read::OFFSET,LENGTH'

  46207. 

  46208.           Return a description of the current traceframe's contents.

  46209.           *Note Traceframe Info Format::.  The annex part of the generic

  46210.           'qXfer' packet must be empty (*note qXfer read::).

  46211. 

  46212.           This packet is not probed by default; the remote stub must

  46213.           request it, by supplying an appropriate 'qSupported' response

  46214.           (*note qSupported::).

  46215. 

  46216.      'qXfer:uib:read:PC:OFFSET,LENGTH'

  46217. 

  46218.           Return the unwind information block for PC.  This packet is

  46219.           used on OpenVMS/ia64 to ask the kernel unwind information.

  46220. 

  46221.           This packet is not probed by default.

  46222. 

  46223.      'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'

  46224.           Read contents of 'loadmap's on the target system.  The annex,

  46225.           either 'exec' or 'interp', specifies which 'loadmap',

  46226.           executable 'loadmap' or interpreter 'loadmap' to read.

  46227. 

  46228.           This packet is not probed by default; the remote stub must

  46229.           request it, by supplying an appropriate 'qSupported' response

  46230.           (*note qSupported::).

  46231. 

  46232.      'qXfer:osdata:read::OFFSET,LENGTH'

  46233.           Access the target's "operating system information".  *Note

  46234.           Operating System Information::.

  46235. 

  46236. 'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'

  46237.      Write uninterpreted bytes into the target's special data area

  46238.      identified by the keyword OBJECT, starting at OFFSET bytes into the

  46239.      data.  The binary-encoded data (*note Binary Data::) to be written

  46240.      is given by DATA....  The content and encoding of ANNEX is specific

  46241.      to OBJECT; it can supply additional details about what data to

  46242.      access.

  46243. 

  46244.      Reply:

  46245.      'NN'

  46246.           NN (hex encoded) is the number of bytes written.  This may be

  46247.           fewer bytes than supplied in the request.

  46248. 

  46249.      'E00'

  46250.           The request was malformed, or ANNEX was invalid.

  46251. 

  46252.      'E NN'

  46253.           The offset was invalid, or there was an error encountered

  46254.           writing the data.  The NN part is a hex-encoded 'errno' value.

  46255. 

  46256.      ''

  46257.           An empty reply indicates the OBJECT string was not recognized

  46258.           by the stub, or that the object does not support writing.

  46259. 

  46260.      Here are the specific requests of this form defined so far.  All

  46261.      the 'qXfer:OBJECT:write:...' requests use the same reply formats,

  46262.      listed above.

  46263. 

  46264.      'qXfer:siginfo:write::OFFSET:DATA...'

  46265.           Write DATA to the extra signal information on the target

  46266.           system.  The annex part of the generic 'qXfer' packet must be

  46267.           empty (*note qXfer write::).

  46268. 

  46269.           This packet is not probed by default; the remote stub must

  46270.           request it, by supplying an appropriate 'qSupported' response

  46271.           (*note qSupported::).

  46272. 

  46273. 'qXfer:OBJECT:OPERATION:...'

  46274.      Requests of this form may be added in the future.  When a stub does

  46275.      not recognize the OBJECT keyword, or its support for OBJECT does

  46276.      not recognize the OPERATION keyword, the stub must respond with an

  46277.      empty packet.

  46278. 

  46279. 'qAttached:PID'

  46280.      Return an indication of whether the remote server attached to an

  46281.      existing process or created a new process.  When the multiprocess

  46282.      protocol extensions are supported (*note multiprocess

  46283.      extensions::), PID is an integer in hexadecimal format identifying

  46284.      the target process.  Otherwise, GDB will omit the PID field and the

  46285.      query packet will be simplified as 'qAttached'.

  46286. 

  46287.      This query is used, for example, to know whether the remote process

  46288.      should be detached or killed when a GDB session is ended with the

  46289.      'quit' command.

  46290. 

  46291.      Reply:

  46292.      '1'

  46293.           The remote server attached to an existing process.

  46294.      '0'

  46295.           The remote server created a new process.

  46296.      'E NN'

  46297.           A badly formed request or an error was encountered.

  46298. 

  46299. 'Qbtrace:bts'

  46300.      Enable branch tracing for the current thread using Branch Trace

  46301.      Store.

  46302. 

  46303.      Reply:

  46304.      'OK'

  46305.           Branch tracing has been enabled.

  46306.      'E.errtext'

  46307.           A badly formed request or an error was encountered.

  46308. 

  46309. 'Qbtrace:pt'

  46310.      Enable branch tracing for the current thread using Intel Processor

  46311.      Trace.

  46312. 

  46313.      Reply:

  46314.      'OK'

  46315.           Branch tracing has been enabled.

  46316.      'E.errtext'

  46317.           A badly formed request or an error was encountered.

  46318. 

  46319. 'Qbtrace:off'

  46320.      Disable branch tracing for the current thread.

  46321. 

  46322.      Reply:

  46323.      'OK'

  46324.           Branch tracing has been disabled.

  46325.      'E.errtext'

  46326.           A badly formed request or an error was encountered.

  46327. 

  46328. 'Qbtrace-conf:bts:size=VALUE'

  46329.      Set the requested ring buffer size for new threads that use the

  46330.      btrace recording method in bts format.

  46331. 

  46332.      Reply:

  46333.      'OK'

  46334.           The ring buffer size has been set.

  46335.      'E.errtext'

  46336.           A badly formed request or an error was encountered.

  46337. 

  46338. 'Qbtrace-conf:pt:size=VALUE'

  46339.      Set the requested ring buffer size for new threads that use the

  46340.      btrace recording method in pt format.

  46341. 

  46342.      Reply:

  46343.      'OK'

  46344.           The ring buffer size has been set.

  46345.      'E.errtext'

  46346.           A badly formed request or an error was encountered.

  46347. 

  46348.    ---------- Footnotes ----------

  46349. 

  46350.    (1) The 'qP' and 'qL' packets predate these conventions, and have

  46351. arguments without any terminator for the packet name; we suspect they

  46352. are in widespread use in places that are difficult to upgrade.  The 'qC'

  46353. packet has no arguments, but some existing stubs (e.g. RedBoot) are

  46354. known to not check for the end of the packet.

  46355. 

  46356. 

  46357. File: gdb.info,  Node: Architecture-Specific Protocol Details,  Next: Tracepoint Packets,  Prev: General Query Packets,  Up: Remote Protocol

  46358. 

  46359. E.5 Architecture-Specific Protocol Details

  46360. ==========================================

  46361. 

  46362. This section describes how the remote protocol is applied to specific

  46363. target architectures.  Also see *note Standard Target Features::, for

  46364. details of XML target descriptions for each architecture.

  46365. 

  46366. * Menu:

  46367. 

  46368. * ARM-Specific Protocol Details::

  46369. * MIPS-Specific Protocol Details::

  46370. 

  46371. 

  46372. File: gdb.info,  Node: ARM-Specific Protocol Details,  Next: MIPS-Specific Protocol Details,  Up: Architecture-Specific Protocol Details

  46373. 

  46374. E.5.1 ARM-specific Protocol Details

  46375. -----------------------------------

  46376. 

  46377. * Menu:

  46378. 

  46379. * ARM Breakpoint Kinds::

  46380. 

  46381. 

  46382. File: gdb.info,  Node: ARM Breakpoint Kinds,  Up: ARM-Specific Protocol Details

  46383. 

  46384. E.5.1.1 ARM Breakpoint Kinds

  46385. ............................

  46386. 

  46387. These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.

  46388. 

  46389. 2

  46390.      16-bit Thumb mode breakpoint.

  46391. 

  46392. 3

  46393.      32-bit Thumb mode (Thumb-2) breakpoint.

  46394. 

  46395. 4

  46396.      32-bit ARM mode breakpoint.

  46397. 

  46398. 

  46399. File: gdb.info,  Node: MIPS-Specific Protocol Details,  Prev: ARM-Specific Protocol Details,  Up: Architecture-Specific Protocol Details

  46400. 

  46401. E.5.2 MIPS-specific Protocol Details

  46402. ------------------------------------

  46403. 

  46404. * Menu:

  46405. 

  46406. * MIPS Register packet Format::

  46407. * MIPS Breakpoint Kinds::

  46408. 

  46409. 

  46410. File: gdb.info,  Node: MIPS Register packet Format,  Next: MIPS Breakpoint Kinds,  Up: MIPS-Specific Protocol Details

  46411. 

  46412. E.5.2.1 MIPS Register Packet Format

  46413. ...................................

  46414. 

  46415. The following 'g'/'G' packets have previously been defined.  In the

  46416. below, some thirty-two bit registers are transferred as sixty-four bits.

  46417. Those registers should be zero/sign extended (which?)  to fill the space

  46418. allocated.  Register bytes are transferred in target byte order.  The

  46419. two nibbles within a register byte are transferred most-significant -

  46420. least-significant.

  46421. 

  46422. MIPS32

  46423.      All registers are transferred as thirty-two bit quantities in the

  46424.      order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32

  46425.      floating-point registers; fsr; fir; fp.

  46426. 

  46427. MIPS64

  46428.      All registers are transferred as sixty-four bit quantities

  46429.      (including thirty-two bit registers such as 'sr').  The ordering is

  46430.      the same as 'MIPS32'.

  46431. 

  46432. 

  46433. File: gdb.info,  Node: MIPS Breakpoint Kinds,  Prev: MIPS Register packet Format,  Up: MIPS-Specific Protocol Details

  46434. 

  46435. E.5.2.2 MIPS Breakpoint Kinds

  46436. .............................

  46437. 

  46438. These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.

  46439. 

  46440. 2

  46441.      16-bit MIPS16 mode breakpoint.

  46442. 

  46443. 3

  46444.      16-bit microMIPS mode breakpoint.

  46445. 

  46446. 4

  46447.      32-bit standard MIPS mode breakpoint.

  46448. 

  46449. 5

  46450.      32-bit microMIPS mode breakpoint.

  46451. 

  46452. 

  46453. File: gdb.info,  Node: Tracepoint Packets,  Next: Host I/O Packets,  Prev: Architecture-Specific Protocol Details,  Up: Remote Protocol

  46454. 

  46455. E.6 Tracepoint Packets

  46456. ======================

  46457. 

  46458. Here we describe the packets GDB uses to implement tracepoints (*note

  46459. Tracepoints::).

  46460. 

  46461. 'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'

  46462.      Create a new tracepoint, number N, at ADDR.  If ENA is 'E', then

  46463.      the tracepoint is enabled; if it is 'D', then the tracepoint is

  46464.      disabled.  The STEP gives the tracepoint's step count, and PASS

  46465.      gives its pass count.  If an 'F' is present, then the tracepoint is

  46466.      to be a fast tracepoint, and the FLEN is the number of bytes that

  46467.      the target should copy elsewhere to make room for the tracepoint.

  46468.      If an 'X' is present, it introduces a tracepoint condition, which

  46469.      consists of a hexadecimal length, followed by a comma and

  46470.      hex-encoded bytes, in a manner similar to action encodings as

  46471.      described below.  If the trailing '-' is present, further 'QTDP'

  46472.      packets will follow to specify this tracepoint's actions.

  46473. 

  46474.      Replies:

  46475.      'OK'

  46476.           The packet was understood and carried out.

  46477.      'qRelocInsn'

  46478.           *Note Relocate instruction reply packet: Tracepoint Packets.

  46479.      ''

  46480.           The packet was not recognized.

  46481. 

  46482. 'QTDP:-N:ADDR:[S]ACTION...[-]'

  46483.      Define actions to be taken when a tracepoint is hit.  The N and

  46484.      ADDR must be the same as in the initial 'QTDP' packet for this

  46485.      tracepoint.  This packet may only be sent immediately after another

  46486.      'QTDP' packet that ended with a '-'.  If the trailing '-' is

  46487.      present, further 'QTDP' packets will follow, specifying more

  46488.      actions for this tracepoint.

  46489. 

  46490.      In the series of action packets for a given tracepoint, at most one

  46491.      can have an 'S' before its first ACTION.  If such a packet is sent,

  46492.      it and the following packets define "while-stepping" actions.  Any

  46493.      prior packets define ordinary actions -- that is, those taken when

  46494.      the tracepoint is first hit.  If no action packet has an 'S', then

  46495.      all the packets in the series specify ordinary tracepoint actions.

  46496. 

  46497.      The 'ACTION...' portion of the packet is a series of actions,

  46498.      concatenated without separators.  Each action has one of the

  46499.      following forms:

  46500. 

  46501.      'R MASK'

  46502.           Collect the registers whose bits are set in MASK, a

  46503.           hexadecimal number whose I'th bit is set if register number I

  46504.           should be collected.  (The least significant bit is numbered

  46505.           zero.)  Note that MASK may be any number of digits long; it

  46506.           may not fit in a 32-bit word.

  46507. 

  46508.      'M BASEREG,OFFSET,LEN'

  46509.           Collect LEN bytes of memory starting at the address in

  46510.           register number BASEREG, plus OFFSET.  If BASEREG is '-1',

  46511.           then the range has a fixed address: OFFSET is the address of

  46512.           the lowest byte to collect.  The BASEREG, OFFSET, and LEN

  46513.           parameters are all unsigned hexadecimal values (the '-1' value

  46514.           for BASEREG is a special case).

  46515. 

  46516.      'X LEN,EXPR'

  46517.           Evaluate EXPR, whose length is LEN, and collect memory as it

  46518.           directs.  The agent expression EXPR is as described in *note

  46519.           Agent Expressions::.  Each byte of the expression is encoded

  46520.           as a two-digit hex number in the packet; LEN is the number of

  46521.           bytes in the expression (and thus one-half the number of hex

  46522.           digits in the packet).

  46523. 

  46524.      Any number of actions may be packed together in a single 'QTDP'

  46525.      packet, as long as the packet does not exceed the maximum packet

  46526.      length (400 bytes, for many stubs).  There may be only one 'R'

  46527.      action per tracepoint, and it must precede any 'M' or 'X' actions.

  46528.      Any registers referred to by 'M' and 'X' actions must be collected

  46529.      by a preceding 'R' action.  (The "while-stepping" actions are

  46530.      treated as if they were attached to a separate tracepoint, as far

  46531.      as these restrictions are concerned.)

  46532. 

  46533.      Replies:

  46534.      'OK'

  46535.           The packet was understood and carried out.

  46536.      'qRelocInsn'

  46537.           *Note Relocate instruction reply packet: Tracepoint Packets.

  46538.      ''

  46539.           The packet was not recognized.

  46540. 

  46541. 'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'

  46542.      Specify a source string of tracepoint N at address ADDR.  This is

  46543.      useful to get accurate reproduction of the tracepoints originally

  46544.      downloaded at the beginning of the trace run.  The TYPE is the name

  46545.      of the tracepoint part, such as 'cond' for the tracepoint's

  46546.      conditional expression (see below for a list of types), while BYTES

  46547.      is the string, encoded in hexadecimal.

  46548. 

  46549.      START is the offset of the BYTES within the overall source string,

  46550.      while SLEN is the total length of the source string.  This is

  46551.      intended for handling source strings that are longer than will fit

  46552.      in a single packet.

  46553. 

  46554.      The available string types are 'at' for the location, 'cond' for

  46555.      the conditional, and 'cmd' for an action command.  GDB sends a

  46556.      separate packet for each command in the action list, in the same

  46557.      order in which the commands are stored in the list.

  46558. 

  46559.      The target does not need to do anything with source strings except

  46560.      report them back as part of the replies to the 'qTfP'/'qTsP' query

  46561.      packets.

  46562. 

  46563.      Although this packet is optional, and GDB will only send it if the

  46564.      target replies with 'TracepointSource' *Note General Query

  46565.      Packets::, it makes both disconnected tracing and trace files much

  46566.      easier to use.  Otherwise the user must be careful that the

  46567.      tracepoints in effect while looking at trace frames are identical

  46568.      to the ones in effect during the trace run; even a small

  46569.      discrepancy could cause 'tdump' not to work, or a particular trace

  46570.      frame not be found.

  46571. 

  46572. 'QTDV:N:VALUE:BUILTIN:NAME'

  46573.      Create a new trace state variable, number N, with an initial value

  46574.      of VALUE, which is a 64-bit signed integer.  Both N and VALUE are

  46575.      encoded as hexadecimal values.  GDB has the option of not using

  46576.      this packet for initial values of zero; the target should simply

  46577.      create the trace state variables as they are mentioned in

  46578.      expressions.  The value BUILTIN should be 1 (one) if the trace

  46579.      state variable is builtin and 0 (zero) if it is not builtin.  GDB

  46580.      only sets BUILTIN to 1 if a previous 'qTfV' or 'qTsV' packet had it

  46581.      set.  The contents of NAME is the hex-encoded name (without the

  46582.      leading '$') of the trace state variable.

  46583. 

  46584. 'QTFrame:N'

  46585.      Select the N'th tracepoint frame from the buffer, and use the

  46586.      register and memory contents recorded there to answer subsequent

  46587.      request packets from GDB.

  46588. 

  46589.      A successful reply from the stub indicates that the stub has found

  46590.      the requested frame.  The response is a series of parts,

  46591.      concatenated without separators, describing the frame we selected.

  46592.      Each part has one of the following forms:

  46593. 

  46594.      'F F'

  46595.           The selected frame is number N in the trace frame buffer; F is

  46596.           a hexadecimal number.  If F is '-1', then there was no frame

  46597.           matching the criteria in the request packet.

  46598. 

  46599.      'T T'

  46600.           The selected trace frame records a hit of tracepoint number T;

  46601.           T is a hexadecimal number.

  46602. 

  46603. 'QTFrame:pc:ADDR'

  46604.      Like 'QTFrame:N', but select the first tracepoint frame after the

  46605.      currently selected frame whose PC is ADDR; ADDR is a hexadecimal

  46606.      number.

  46607. 

  46608. 'QTFrame:tdp:T'

  46609.      Like 'QTFrame:N', but select the first tracepoint frame after the

  46610.      currently selected frame that is a hit of tracepoint T; T is a

  46611.      hexadecimal number.

  46612. 

  46613. 'QTFrame:range:START:END'

  46614.      Like 'QTFrame:N', but select the first tracepoint frame after the

  46615.      currently selected frame whose PC is between START (inclusive) and

  46616.      END (inclusive); START and END are hexadecimal numbers.

  46617. 

  46618. 'QTFrame:outside:START:END'

  46619.      Like 'QTFrame:range:START:END', but select the first frame

  46620.      _outside_ the given range of addresses (exclusive).

  46621. 

  46622. 'qTMinFTPILen'

  46623.      This packet requests the minimum length of instruction at which a

  46624.      fast tracepoint (*note Set Tracepoints::) may be placed.  For

  46625.      instance, on the 32-bit x86 architecture, it is possible to use a

  46626.      4-byte jump, but it depends on the target system being able to

  46627.      create trampolines in the first 64K of memory, which might or might

  46628.      not be possible for that system.  So the reply to this packet will

  46629.      be 4 if it is able to arrange for that.

  46630. 

  46631.      Replies:

  46632. 

  46633.      '0'

  46634.           The minimum instruction length is currently unknown.

  46635.      'LENGTH'

  46636.           The minimum instruction length is LENGTH, where LENGTH is a

  46637.           hexadecimal number greater or equal to 1.  A reply of 1 means

  46638.           that a fast tracepoint may be placed on any instruction

  46639.           regardless of size.

  46640.      'E'

  46641.           An error has occurred.

  46642.      ''

  46643.           An empty reply indicates that the request is not supported by

  46644.           the stub.

  46645. 

  46646. 'QTStart'

  46647.      Begin the tracepoint experiment.  Begin collecting data from

  46648.      tracepoint hits in the trace frame buffer.  This packet supports

  46649.      the 'qRelocInsn' reply (*note Relocate instruction reply packet:

  46650.      Tracepoint Packets.).

  46651. 

  46652. 'QTStop'

  46653.      End the tracepoint experiment.  Stop collecting trace frames.

  46654. 

  46655. 'QTEnable:N:ADDR'

  46656.      Enable tracepoint N at address ADDR in a started tracepoint

  46657.      experiment.  If the tracepoint was previously disabled, then

  46658.      collection of data from it will resume.

  46659. 

  46660. 'QTDisable:N:ADDR'

  46661.      Disable tracepoint N at address ADDR in a started tracepoint

  46662.      experiment.  No more data will be collected from the tracepoint

  46663.      unless 'QTEnable:N:ADDR' is subsequently issued.

  46664. 

  46665. 'QTinit'

  46666.      Clear the table of tracepoints, and empty the trace frame buffer.

  46667. 

  46668. 'QTro:START1,END1:START2,END2:...'

  46669.      Establish the given ranges of memory as "transparent".  The stub

  46670.      will answer requests for these ranges from memory's current

  46671.      contents, if they were not collected as part of the tracepoint hit.

  46672. 

  46673.      GDB uses this to mark read-only regions of memory, like those

  46674.      containing program code.  Since these areas never change, they

  46675.      should still have the same contents they did when the tracepoint

  46676.      was hit, so there's no reason for the stub to refuse to provide

  46677.      their contents.

  46678. 

  46679. 'QTDisconnected:VALUE'

  46680.      Set the choice to what to do with the tracing run when GDB

  46681.      disconnects from the target.  A VALUE of 1 directs the target to

  46682.      continue the tracing run, while 0 tells the target to stop tracing

  46683.      if GDB is no longer in the picture.

  46684. 

  46685. 'qTStatus'

  46686.      Ask the stub if there is a trace experiment running right now.

  46687. 

  46688.      The reply has the form:

  46689. 

  46690.      'TRUNNING[;FIELD]...'

  46691.           RUNNING is a single digit '1' if the trace is presently

  46692.           running, or '0' if not.  It is followed by semicolon-separated

  46693.           optional fields that an agent may use to report additional

  46694.           status.

  46695. 

  46696.      If the trace is not running, the agent may report any of several

  46697.      explanations as one of the optional fields:

  46698. 

  46699.      'tnotrun:0'

  46700.           No trace has been run yet.

  46701. 

  46702.      'tstop[:TEXT]:0'

  46703.           The trace was stopped by a user-originated stop command.  The

  46704.           optional TEXT field is a user-supplied string supplied as part

  46705.           of the stop command (for instance, an explanation of why the

  46706.           trace was stopped manually).  It is hex-encoded.

  46707. 

  46708.      'tfull:0'

  46709.           The trace stopped because the trace buffer filled up.

  46710. 

  46711.      'tdisconnected:0'

  46712.           The trace stopped because GDB disconnected from the target.

  46713. 

  46714.      'tpasscount:TPNUM'

  46715.           The trace stopped because tracepoint TPNUM exceeded its pass

  46716.           count.

  46717. 

  46718.      'terror:TEXT:TPNUM'

  46719.           The trace stopped because tracepoint TPNUM had an error.  The

  46720.           string TEXT is available to describe the nature of the error

  46721.           (for instance, a divide by zero in the condition expression);

  46722.           it is hex encoded.

  46723. 

  46724.      'tunknown:0'

  46725.           The trace stopped for some other reason.

  46726. 

  46727.      Additional optional fields supply statistical and other

  46728.      information.  Although not required, they are extremely useful for

  46729.      users monitoring the progress of a trace run.  If a trace has

  46730.      stopped, and these numbers are reported, they must reflect the

  46731.      state of the just-stopped trace.

  46732. 

  46733.      'tframes:N'

  46734.           The number of trace frames in the buffer.

  46735. 

  46736.      'tcreated:N'

  46737.           The total number of trace frames created during the run.  This

  46738.           may be larger than the trace frame count, if the buffer is

  46739.           circular.

  46740. 

  46741.      'tsize:N'

  46742.           The total size of the trace buffer, in bytes.

  46743. 

  46744.      'tfree:N'

  46745.           The number of bytes still unused in the buffer.

  46746. 

  46747.      'circular:N'

  46748.           The value of the circular trace buffer flag.  '1' means that

  46749.           the trace buffer is circular and old trace frames will be

  46750.           discarded if necessary to make room, '0' means that the trace

  46751.           buffer is linear and may fill up.

  46752. 

  46753.      'disconn:N'

  46754.           The value of the disconnected tracing flag.  '1' means that

  46755.           tracing will continue after GDB disconnects, '0' means that

  46756.           the trace run will stop.

  46757. 

  46758. 'qTP:TP:ADDR'

  46759.      Ask the stub for the current state of tracepoint number TP at

  46760.      address ADDR.

  46761. 

  46762.      Replies:

  46763.      'VHITS:USAGE'

  46764.           The tracepoint has been hit HITS times so far during the trace

  46765.           run, and accounts for USAGE in the trace buffer.  Note that

  46766.           'while-stepping' steps are not counted as separate hits, but

  46767.           the steps' space consumption is added into the usage number.

  46768. 

  46769. 'qTV:VAR'

  46770.      Ask the stub for the value of the trace state variable number VAR.

  46771. 

  46772.      Replies:

  46773.      'VVALUE'

  46774.           The value of the variable is VALUE.  This will be the current

  46775.           value of the variable if the user is examining a running

  46776.           target, or a saved value if the variable was collected in the

  46777.           trace frame that the user is looking at.  Note that multiple

  46778.           requests may result in different reply values, such as when

  46779.           requesting values while the program is running.

  46780. 

  46781.      'U'

  46782.           The value of the variable is unknown.  This would occur, for

  46783.           example, if the user is examining a trace frame in which the

  46784.           requested variable was not collected.

  46785. 

  46786. 'qTfP'

  46787. 'qTsP'

  46788.      These packets request data about tracepoints that are being used by

  46789.      the target.  GDB sends 'qTfP' to get the first piece of data, and

  46790.      multiple 'qTsP' to get additional pieces.  Replies to these packets

  46791.      generally take the form of the 'QTDP' packets that define

  46792.      tracepoints.  (FIXME add detailed syntax)

  46793. 

  46794. 'qTfV'

  46795. 'qTsV'

  46796.      These packets request data about trace state variables that are on

  46797.      the target.  GDB sends 'qTfV' to get the first vari of data, and

  46798.      multiple 'qTsV' to get additional variables.  Replies to these

  46799.      packets follow the syntax of the 'QTDV' packets that define trace

  46800.      state variables.

  46801. 

  46802. 'qTfSTM'

  46803. 'qTsSTM'

  46804.      These packets request data about static tracepoint markers that

  46805.      exist in the target program.  GDB sends 'qTfSTM' to get the first

  46806.      piece of data, and multiple 'qTsSTM' to get additional pieces.

  46807.      Replies to these packets take the following form:

  46808. 

  46809.      Reply:

  46810.      'm ADDRESS:ID:EXTRA'

  46811.           A single marker

  46812.      'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'

  46813.           a comma-separated list of markers

  46814.      'l'

  46815.           (lower case letter 'L') denotes end of list.

  46816.      'E NN'

  46817.           An error occurred.  The error number NN is given as hex

  46818.           digits.

  46819.      ''

  46820.           An empty reply indicates that the request is not supported by

  46821.           the stub.

  46822. 

  46823.      The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in

  46824.      hex.

  46825. 

  46826.      In response to each query, the target will reply with a list of one

  46827.      or more markers, separated by commas.  GDB will respond to each

  46828.      reply with a request for more markers (using the 'qs' form of the

  46829.      query), until the target responds with 'l' (lower-case ell, for

  46830.      "last").

  46831. 

  46832. 'qTSTMat:ADDRESS'

  46833.      This packets requests data about static tracepoint markers in the

  46834.      target program at ADDRESS.  Replies to this packet follow the

  46835.      syntax of the 'qTfSTM' and 'qTsSTM' packets that list static

  46836.      tracepoint markers.

  46837. 

  46838. 'QTSave:FILENAME'

  46839.      This packet directs the target to save trace data to the file name

  46840.      FILENAME in the target's filesystem.  The FILENAME is encoded as a

  46841.      hex string; the interpretation of the file name (relative vs

  46842.      absolute, wild cards, etc) is up to the target.

  46843. 

  46844. 'qTBuffer:OFFSET,LEN'

  46845.      Return up to LEN bytes of the current contents of trace buffer,

  46846.      starting at OFFSET.  The trace buffer is treated as if it were a

  46847.      contiguous collection of traceframes, as per the trace file format.

  46848.      The reply consists as many hex-encoded bytes as the target can

  46849.      deliver in a packet; it is not an error to return fewer than were

  46850.      asked for.  A reply consisting of just 'l' indicates that no bytes

  46851.      are available.

  46852. 

  46853. 'QTBuffer:circular:VALUE'

  46854.      This packet directs the target to use a circular trace buffer if

  46855.      VALUE is 1, or a linear buffer if the value is 0.

  46856. 

  46857. 'QTBuffer:size:SIZE'

  46858.      This packet directs the target to make the trace buffer be of size

  46859.      SIZE if possible.  A value of '-1' tells the target to use whatever

  46860.      size it prefers.

  46861. 

  46862. 'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'

  46863.      This packet adds optional textual notes to the trace run.

  46864.      Allowable types include 'user', 'notes', and 'tstop', the TEXT

  46865.      fields are arbitrary strings, hex-encoded.

  46866. 

  46867. E.6.1 Relocate instruction reply packet

  46868. ---------------------------------------

  46869. 

  46870. When installing fast tracepoints in memory, the target may need to

  46871. relocate the instruction currently at the tracepoint address to a

  46872. different address in memory.  For most instructions, a simple copy is

  46873. enough, but, for example, call instructions that implicitly push the

  46874. return address on the stack, and relative branches or other PC-relative

  46875. instructions require offset adjustment, so that the effect of executing

  46876. the instruction at a different address is the same as if it had executed

  46877. in the original location.

  46878. 

  46879.    In response to several of the tracepoint packets, the target may also

  46880. respond with a number of intermediate 'qRelocInsn' request packets

  46881. before the final result packet, to have GDB handle this relocation

  46882. operation.  If a packet supports this mechanism, its documentation will

  46883. explicitly say so.  See for example the above descriptions for the

  46884. 'QTStart' and 'QTDP' packets.  The format of the request is:

  46885. 

  46886. 'qRelocInsn:FROM;TO'

  46887. 

  46888.      This requests GDB to copy instruction at address FROM to address

  46889.      TO, possibly adjusted so that executing the instruction at TO has

  46890.      the same effect as executing it at FROM.  GDB writes the adjusted

  46891.      instruction to target memory starting at TO.

  46892. 

  46893.    Replies:

  46894. 'qRelocInsn:ADJUSTED_SIZE'

  46895.      Informs the stub the relocation is complete.  The ADJUSTED_SIZE is

  46896.      the length in bytes of resulting relocated instruction sequence.

  46897. 'E NN'

  46898.      A badly formed request was detected, or an error was encountered

  46899.      while relocating the instruction.

  46900. 

  46901. 

  46902. File: gdb.info,  Node: Host I/O Packets,  Next: Interrupts,  Prev: Tracepoint Packets,  Up: Remote Protocol

  46903. 

  46904. E.7 Host I/O Packets

  46905. ====================

  46906. 

  46907. The "Host I/O" packets allow GDB to perform I/O operations on the far

  46908. side of a remote link.  For example, Host I/O is used to upload and

  46909. download files to a remote target with its own filesystem.  Host I/O

  46910. uses the same constant values and data structure layout as the

  46911. target-initiated File-I/O protocol.  However, the Host I/O packets are

  46912. structured differently.  The target-initiated protocol relies on target

  46913. memory to store parameters and buffers.  Host I/O requests are initiated

  46914. by GDB, and the target's memory is not involved.  *Note File-I/O Remote

  46915. Protocol Extension::, for more details on the target-initiated protocol.

  46916. 

  46917.    The Host I/O request packets all encode a single operation along with

  46918. its arguments.  They have this format:

  46919. 

  46920. 'vFile:OPERATION: PARAMETER...'

  46921.      OPERATION is the name of the particular request; the target should

  46922.      compare the entire packet name up to the second colon when checking

  46923.      for a supported operation.  The format of PARAMETER depends on the

  46924.      operation.  Numbers are always passed in hexadecimal.  Negative

  46925.      numbers have an explicit minus sign (i.e. two's complement is not

  46926.      used).  Strings (e.g. filenames) are encoded as a series of

  46927.      hexadecimal bytes.  The last argument to a system call may be a

  46928.      buffer of escaped binary data (*note Binary Data::).

  46929. 

  46930.    The valid responses to Host I/O packets are:

  46931. 

  46932. 'F RESULT [, ERRNO] [; ATTACHMENT]'

  46933.      RESULT is the integer value returned by this operation, usually

  46934.      non-negative for success and -1 for errors.  If an error has

  46935.      occured, ERRNO will be included in the result specifying a value

  46936.      defined by the File-I/O protocol (*note Errno Values::).  For

  46937.      operations which return data, ATTACHMENT supplies the data as a

  46938.      binary buffer.  Binary buffers in response packets are escaped in

  46939.      the normal way (*note Binary Data::).  See the individual packet

  46940.      documentation for the interpretation of RESULT and ATTACHMENT.

  46941. 

  46942. ''

  46943.      An empty response indicates that this operation is not recognized.

  46944. 

  46945.    These are the supported Host I/O operations:

  46946. 

  46947. 'vFile:open: FILENAME, FLAGS, MODE'

  46948.      Open a file at FILENAME and return a file descriptor for it, or

  46949.      return -1 if an error occurs.  The FILENAME is a string, FLAGS is

  46950.      an integer indicating a mask of open flags (*note Open Flags::),

  46951.      and MODE is an integer indicating a mask of mode bits to use if the

  46952.      file is created (*note mode_t Values::).  *Note open::, for details

  46953.      of the open flags and mode values.

  46954. 

  46955. 'vFile:close: FD'

  46956.      Close the open file corresponding to FD and return 0, or -1 if an

  46957.      error occurs.

  46958. 

  46959. 'vFile:pread: FD, COUNT, OFFSET'

  46960.      Read data from the open file corresponding to FD.  Up to COUNT

  46961.      bytes will be read from the file, starting at OFFSET relative to

  46962.      the start of the file.  The target may read fewer bytes; common

  46963.      reasons include packet size limits and an end-of-file condition.

  46964.      The number of bytes read is returned.  Zero should only be returned

  46965.      for a successful read at the end of the file, or if COUNT was zero.

  46966. 

  46967.      The data read should be returned as a binary attachment on success.

  46968.      If zero bytes were read, the response should include an empty

  46969.      binary attachment (i.e. a trailing semicolon).  The return value is

  46970.      the number of target bytes read; the binary attachment may be

  46971.      longer if some characters were escaped.

  46972. 

  46973. 'vFile:pwrite: FD, OFFSET, DATA'

  46974.      Write DATA (a binary buffer) to the open file corresponding to FD.

  46975.      Start the write at OFFSET from the start of the file.  Unlike many

  46976.      'write' system calls, there is no separate COUNT argument; the

  46977.      length of DATA in the packet is used.  'vFile:pwrite' returns the

  46978.      number of bytes written, which may be shorter than the length of

  46979.      DATA, or -1 if an error occurred.

  46980. 

  46981. 'vFile:fstat: FD'

  46982.      Get information about the open file corresponding to FD.  On

  46983.      success the information is returned as a binary attachment and the

  46984.      return value is the size of this attachment in bytes.  If an error

  46985.      occurs the return value is -1.  The format of the returned binary

  46986.      attachment is as described in *note struct stat::.

  46987. 

  46988. 'vFile:unlink: FILENAME'

  46989.      Delete the file at FILENAME on the target.  Return 0, or -1 if an

  46990.      error occurs.  The FILENAME is a string.

  46991. 

  46992. 'vFile:readlink: FILENAME'

  46993.      Read value of symbolic link FILENAME on the target.  Return the

  46994.      number of bytes read, or -1 if an error occurs.

  46995. 

  46996.      The data read should be returned as a binary attachment on success.

  46997.      If zero bytes were read, the response should include an empty

  46998.      binary attachment (i.e. a trailing semicolon).  The return value is

  46999.      the number of target bytes read; the binary attachment may be

  47000.      longer if some characters were escaped.

  47001. 

  47002. 'vFile:setfs: PID'

  47003.      Select the filesystem on which 'vFile' operations with FILENAME

  47004.      arguments will operate.  This is required for GDB to be able to

  47005.      access files on remote targets where the remote stub does not share

  47006.      a common filesystem with the inferior(s).

  47007. 

  47008.      If PID is nonzero, select the filesystem as seen by process PID.

  47009.      If PID is zero, select the filesystem as seen by the remote stub.

  47010.      Return 0 on success, or -1 if an error occurs.  If 'vFile:setfs:'

  47011.      indicates success, the selected filesystem remains selected until

  47012.      the next successful 'vFile:setfs:' operation.

  47013. 

  47014. 

  47015. File: gdb.info,  Node: Interrupts,  Next: Notification Packets,  Prev: Host I/O Packets,  Up: Remote Protocol

  47016. 

  47017. E.8 Interrupts

  47018. ==============

  47019. 

  47020. In all-stop mode, when a program on the remote target is running, GDB

  47021. may attempt to interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK'

  47022. followed by 'g', control of which is specified via GDB's

  47023. 'interrupt-sequence'.

  47024. 

  47025.    The precise meaning of 'BREAK' is defined by the transport mechanism

  47026. and may, in fact, be undefined.  GDB does not currently define a 'BREAK'

  47027. mechanism for any of the network interfaces except for TCP, in which

  47028. case GDB sends the 'telnet' BREAK sequence.

  47029. 

  47030.    'Ctrl-C', on the other hand, is defined and implemented for all

  47031. transport mechanisms.  It is represented by sending the single byte

  47032. '0x03' without any of the usual packet overhead described in the

  47033. Overview section (*note Overview::).  When a '0x03' byte is transmitted

  47034. as part of a packet, it is considered to be packet data and does _not_

  47035. represent an interrupt.  E.g., an 'X' packet (*note X packet::), used

  47036. for binary downloads, may include an unescaped '0x03' as part of its

  47037. packet.

  47038. 

  47039.    'BREAK' followed by 'g' is also known as Magic SysRq g.  When Linux

  47040. kernel receives this sequence from serial port, it stops execution and

  47041. connects to gdb.

  47042. 

  47043.    In non-stop mode, because packet resumptions are asynchronous (*note

  47044. vCont packet::), GDB is always free to send a remote command to the

  47045. remote stub, even when the target is running.  For that reason, GDB

  47046. instead sends a regular packet (*note vCtrlC packet::) with the usual

  47047. packet framing instead of the single byte '0x03'.

  47048. 

  47049.    Stubs are not required to recognize these interrupt mechanisms and

  47050. the precise meaning associated with receipt of the interrupt is

  47051. implementation defined.  If the target supports debugging of multiple

  47052. threads and/or processes, it should attempt to interrupt all

  47053. currently-executing threads and processes.  If the stub is successful at

  47054. interrupting the running program, it should send one of the stop reply

  47055. packets (*note Stop Reply Packets::) to GDB as a result of successfully

  47056. stopping the program in all-stop mode, and a stop reply for each stopped

  47057. thread in non-stop mode.  Interrupts received while the program is

  47058. stopped are queued and the program will be interrupted when it is

  47059. resumed next time.

  47060. 

  47061. 

  47062. File: gdb.info,  Node: Notification Packets,  Next: Remote Non-Stop,  Prev: Interrupts,  Up: Remote Protocol

  47063. 

  47064. E.9 Notification Packets

  47065. ========================

  47066. 

  47067. The GDB remote serial protocol includes "notifications", packets that

  47068. require no acknowledgment.  Both the GDB and the stub may send

  47069. notifications (although the only notifications defined at present are

  47070. sent by the stub).  Notifications carry information without incurring

  47071. the round-trip latency of an acknowledgment, and so are useful for

  47072. low-impact communications where occasional packet loss is not a problem.

  47073. 

  47074.    A notification packet has the form '% DATA # CHECKSUM', where DATA is

  47075. the content of the notification, and CHECKSUM is a checksum of DATA,

  47076. computed and formatted as for ordinary GDB packets.  A notification's

  47077. DATA never contains '$', '%' or '#' characters.  Upon receiving a

  47078. notification, the recipient sends no '+' or '-' to acknowledge the

  47079. notification's receipt or to report its corruption.

  47080. 

  47081.    Every notification's DATA begins with a name, which contains no colon

  47082. characters, followed by a colon character.

  47083. 

  47084.    Recipients should silently ignore corrupted notifications and

  47085. notifications they do not understand.  Recipients should restart timeout

  47086. periods on receipt of a well-formed notification, whether or not they

  47087. understand it.

  47088. 

  47089.    Senders should only send the notifications described here when this

  47090. protocol description specifies that they are permitted.  In the future,

  47091. we may extend the protocol to permit existing notifications in new

  47092. contexts; this rule helps older senders avoid confusing newer

  47093. recipients.

  47094. 

  47095.    (Older versions of GDB ignore bytes received until they see the '$'

  47096. byte that begins an ordinary packet, so new stubs may transmit

  47097. notifications without fear of confusing older clients.  There are no

  47098. notifications defined for GDB to send at the moment, but we assume that

  47099. most older stubs would ignore them, as well.)

  47100. 

  47101.    Each notification is comprised of three parts:

  47102. 'NAME:EVENT'

  47103.      The notification packet is sent by the side that initiates the

  47104.      exchange (currently, only the stub does that), with EVENT carrying

  47105.      the specific information about the notification, and NAME

  47106.      specifying the name of the notification.

  47107. 'ACK'

  47108.      The acknowledge sent by the other side, usually GDB, to acknowledge

  47109.      the exchange and request the event.

  47110. 

  47111.    The purpose of an asynchronous notification mechanism is to report to

  47112. GDB that something interesting happened in the remote stub.

  47113. 

  47114.    The remote stub may send notification NAME:EVENT at any time, but GDB

  47115. acknowledges the notification when appropriate.  The notification event

  47116. is pending before GDB acknowledges.  Only one notification at a time may

  47117. be pending; if additional events occur before GDB has acknowledged the

  47118. previous notification, they must be queued by the stub for later

  47119. synchronous transmission in response to ACK packets from GDB.  Because

  47120. the notification mechanism is unreliable, the stub is permitted to

  47121. resend a notification if it believes GDB may not have received it.

  47122. 

  47123.    Specifically, notifications may appear when GDB is not otherwise

  47124. reading input from the stub, or when GDB is expecting to read a normal

  47125. synchronous response or a '+'/'-' acknowledgment to a packet it has

  47126. sent.  Notification packets are distinct from any other communication

  47127. from the stub so there is no ambiguity.

  47128. 

  47129.    After receiving a notification, GDB shall acknowledge it by sending a

  47130. ACK packet as a regular, synchronous request to the stub.  Such

  47131. acknowledgment is not required to happen immediately, as GDB is

  47132. permitted to send other, unrelated packets to the stub first, which the

  47133. stub should process normally.

  47134. 

  47135.    Upon receiving a ACK packet, if the stub has other queued events to

  47136. report to GDB, it shall respond by sending a normal EVENT.  GDB shall

  47137. then send another ACK packet to solicit further responses; again, it is

  47138. permitted to send other, unrelated packets as well which the stub should

  47139. process normally.

  47140. 

  47141.    If the stub receives a ACK packet and there are no additional EVENT

  47142. to report, the stub shall return an 'OK' response.  At this point, GDB

  47143. has finished processing a notification and the stub has completed

  47144. sending any queued events.  GDB won't accept any new notifications until

  47145. the final 'OK' is received .  If further notification events occur, the

  47146. stub shall send a new notification, GDB shall accept the notification,

  47147. and the process shall be repeated.

  47148. 

  47149.    The process of asynchronous notification can be illustrated by the

  47150. following example:

  47151.      <- %Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;

  47152.      ...

  47153.      -> vStopped

  47154.      <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;

  47155.      -> vStopped

  47156.      <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;

  47157.      -> vStopped

  47158.      <- OK

  47159. 

  47160.    The following notifications are defined:

  47161. 

  47162. NotificationAck     Event                       Description

  47163.                                                 

  47164. Stop      vStopped  REPLY.  The REPLY has the   Report an asynchronous

  47165.                     form of a stop reply, as    stop event in non-stop

  47166.                     described in                mode.

  47167.                     *note Stop Reply Packets::. 

  47168.                     Refer to

  47169.                     *note Remote Non-Stop::,

  47170.                     for information on how

  47171.                     these notifications are

  47172.                     acknowledged by GDB.

  47173. 

  47174. 

  47175. File: gdb.info,  Node: Remote Non-Stop,  Next: Packet Acknowledgment,  Prev: Notification Packets,  Up: Remote Protocol

  47176. 

  47177. E.10 Remote Protocol Support for Non-Stop Mode

  47178. ==============================================

  47179. 

  47180. GDB's remote protocol supports non-stop debugging of multi-threaded

  47181. programs, as described in *note Non-Stop Mode::.  If the stub supports

  47182. non-stop mode, it should report that to GDB by including 'QNonStop+' in

  47183. its 'qSupported' response (*note qSupported::).

  47184. 

  47185.    GDB typically sends a 'QNonStop' packet only when establishing a new

  47186. connection with the stub.  Entering non-stop mode does not alter the

  47187. state of any currently-running threads, but targets must stop all

  47188. threads in any already-attached processes when entering all-stop mode.

  47189. GDB uses the '?' packet as necessary to probe the target state after a

  47190. mode change.

  47191. 

  47192.    In non-stop mode, when an attached process encounters an event that

  47193. would otherwise be reported with a stop reply, it uses the asynchronous

  47194. notification mechanism (*note Notification Packets::) to inform GDB.  In

  47195. contrast to all-stop mode, where all threads in all processes are

  47196. stopped when a stop reply is sent, in non-stop mode only the thread

  47197. reporting the stop event is stopped.  That is, when reporting a 'S' or

  47198. 'T' response to indicate completion of a step operation, hitting a

  47199. breakpoint, or a fault, only the affected thread is stopped; any other

  47200. still-running threads continue to run.  When reporting a 'W' or 'X'

  47201. response, all running threads belonging to other attached processes

  47202. continue to run.

  47203. 

  47204.    In non-stop mode, the target shall respond to the '?' packet as

  47205. follows.  First, any incomplete stop reply notification/'vStopped'

  47206. sequence in progress is abandoned.  The target must begin a new sequence

  47207. reporting stop events for all stopped threads, whether or not it has

  47208. previously reported those events to GDB.  The first stop reply is sent

  47209. as a synchronous reply to the '?' packet, and subsequent stop replies

  47210. are sent as responses to 'vStopped' packets using the mechanism

  47211. described above.  The target must not send asynchronous stop reply

  47212. notifications until the sequence is complete.  If all threads are

  47213. running when the target receives the '?' packet, or if the target is not

  47214. attached to any process, it shall respond 'OK'.

  47215. 

  47216.    If the stub supports non-stop mode, it should also support the

  47217. 'swbreak' stop reason if software breakpoints are supported, and the

  47218. 'hwbreak' stop reason if hardware breakpoints are supported (*note

  47219. swbreak stop reason::).  This is because given the asynchronous nature

  47220. of non-stop mode, between the time a thread hits a breakpoint and the

  47221. time the event is finally processed by GDB, the breakpoint may have

  47222. already been removed from the target.  Due to this, GDB needs to be able

  47223. to tell whether a trap stop was caused by a delayed breakpoint event,

  47224. which should be ignored, as opposed to a random trap signal, which

  47225. should be reported to the user.  Note the 'swbreak' feature implies that

  47226. the target is responsible for adjusting the PC when a software

  47227. breakpoint triggers, if necessary, such as on the x86 architecture.

  47228. 

  47229. 

  47230. File: gdb.info,  Node: Packet Acknowledgment,  Next: Examples,  Prev: Remote Non-Stop,  Up: Remote Protocol

  47231. 

  47232. E.11 Packet Acknowledgment

  47233. ==========================

  47234. 

  47235. By default, when either the host or the target machine receives a

  47236. packet, the first response expected is an acknowledgment: either '+' (to

  47237. indicate the package was received correctly) or '-' (to request

  47238. retransmission).  This mechanism allows the GDB remote protocol to

  47239. operate over unreliable transport mechanisms, such as a serial line.

  47240. 

  47241.    In cases where the transport mechanism is itself reliable (such as a

  47242. pipe or TCP connection), the '+'/'-' acknowledgments are redundant.  It

  47243. may be desirable to disable them in that case to reduce communication

  47244. overhead, or for other reasons.  This can be accomplished by means of

  47245. the 'QStartNoAckMode' packet; *note QStartNoAckMode::.

  47246. 

  47247.    When in no-acknowledgment mode, neither the stub nor GDB shall send

  47248. or expect '+'/'-' protocol acknowledgments.  The packet and response

  47249. format still includes the normal checksum, as described in *note

  47250. Overview::, but the checksum may be ignored by the receiver.

  47251. 

  47252.    If the stub supports 'QStartNoAckMode' and prefers to operate in

  47253. no-acknowledgment mode, it should report that to GDB by including

  47254. 'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::.

  47255. If GDB also supports 'QStartNoAckMode' and it has not been disabled via

  47256. the 'set remote noack-packet off' command (*note Remote

  47257. Configuration::), GDB may then send a 'QStartNoAckMode' packet to the

  47258. stub.  Only then may the stub actually turn off packet acknowledgments.

  47259. GDB sends a final '+' acknowledgment of the stub's 'OK' response, which

  47260. can be safely ignored by the stub.

  47261. 

  47262.    Note that 'set remote noack-packet' command only affects negotiation

  47263. between GDB and the stub when subsequent connections are made; it does

  47264. not affect the protocol acknowledgment state for any current connection.

  47265. Since '+'/'-' acknowledgments are enabled by default when a new

  47266. connection is established, there is also no protocol request to

  47267. re-enable the acknowledgments for the current connection, once disabled.

  47268. 

  47269. 

  47270. File: gdb.info,  Node: Examples,  Next: File-I/O Remote Protocol Extension,  Prev: Packet Acknowledgment,  Up: Remote Protocol

  47271. 

  47272. E.12 Examples

  47273. =============

  47274. 

  47275. Example sequence of a target being re-started.  Notice how the restart

  47276. does not get any direct output:

  47277. 

  47278.      -> R00

  47279.      <- +

  47280.      _target restarts_

  47281.      -> ?

  47282.      <- +

  47283.      <- T001:1234123412341234

  47284.      -> +

  47285. 

  47286.    Example sequence of a target being stepped by a single instruction:

  47287. 

  47288.      -> G1445...

  47289.      <- +

  47290.      -> s

  47291.      <- +

  47292.      _time passes_

  47293.      <- T001:1234123412341234

  47294.      -> +

  47295.      -> g

  47296.      <- +

  47297.      <- 1455...

  47298.      -> +

  47299. 

  47300. 

  47301. File: gdb.info,  Node: File-I/O Remote Protocol Extension,  Next: Library List Format,  Prev: Examples,  Up: Remote Protocol

  47302. 

  47303. E.13 File-I/O Remote Protocol Extension

  47304. =======================================

  47305. 

  47306. * Menu:

  47307. 

  47308. * File-I/O Overview::

  47309. * Protocol Basics::

  47310. * The F Request Packet::

  47311. * The F Reply Packet::

  47312. * The Ctrl-C Message::

  47313. * Console I/O::

  47314. * List of Supported Calls::

  47315. * Protocol-specific Representation of Datatypes::

  47316. * Constants::

  47317. * File-I/O Examples::

  47318. 

  47319. 

  47320. File: gdb.info,  Node: File-I/O Overview,  Next: Protocol Basics,  Up: File-I/O Remote Protocol Extension

  47321. 

  47322. E.13.1 File-I/O Overview

  47323. ------------------------

  47324. 

  47325. The "File I/O remote protocol extension" (short: File-I/O) allows the

  47326. target to use the host's file system and console I/O to perform various

  47327. system calls.  System calls on the target system are translated into a

  47328. remote protocol packet to the host system, which then performs the

  47329. needed actions and returns a response packet to the target system.  This

  47330. simulates file system operations even on targets that lack file systems.

  47331. 

  47332.    The protocol is defined to be independent of both the host and target

  47333. systems.  It uses its own internal representation of datatypes and

  47334. values.  Both GDB and the target's GDB stub are responsible for

  47335. translating the system-dependent value representations into the internal

  47336. protocol representations when data is transmitted.

  47337. 

  47338.    The communication is synchronous.  A system call is possible only

  47339. when GDB is waiting for a response from the 'C', 'c', 'S' or 's'

  47340. packets.  While GDB handles the request for a system call, the target is

  47341. stopped to allow deterministic access to the target's memory.  Therefore

  47342. File-I/O is not interruptible by target signals.  On the other hand, it

  47343. is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within

  47344. GDB.

  47345. 

  47346.    The target's request to perform a host system call does not finish

  47347. the latest 'C', 'c', 'S' or 's' action.  That means, after finishing the

  47348. system call, the target returns to continuing the previous activity

  47349. (continue, step).  No additional continue or step request from GDB is

  47350. required.

  47351. 

  47352.      (gdb) continue

  47353.        <- target requests 'system call X'

  47354.        target is stopped, GDB executes system call

  47355.        -> GDB returns result

  47356.        ... target continues, GDB returns to wait for the target

  47357.        <- target hits breakpoint and sends a Txx packet

  47358. 

  47359.    The protocol only supports I/O on the console and to regular files on

  47360. the host file system.  Character or block special devices, pipes, named

  47361. pipes, sockets or any other communication method on the host system are

  47362. not supported by this protocol.

  47363. 

  47364.    File I/O is not supported in non-stop mode.

  47365. 

  47366. 

  47367. File: gdb.info,  Node: Protocol Basics,  Next: The F Request Packet,  Prev: File-I/O Overview,  Up: File-I/O Remote Protocol Extension

  47368. 

  47369. E.13.2 Protocol Basics

  47370. ----------------------

  47371. 

  47372. The File-I/O protocol uses the 'F' packet as the request as well as

  47373. reply packet.  Since a File-I/O system call can only occur when GDB is

  47374. waiting for a response from the continuing or stepping target, the

  47375. File-I/O request is a reply that GDB has to expect as a result of a

  47376. previous 'C', 'c', 'S' or 's' packet.  This 'F' packet contains all

  47377. information needed to allow GDB to call the appropriate host system

  47378. call:

  47379. 

  47380.    * A unique identifier for the requested system call.

  47381. 

  47382.    * All parameters to the system call.  Pointers are given as addresses

  47383.      in the target memory address space.  Pointers to strings are given

  47384.      as pointer/length pair.  Numerical values are given as they are.

  47385.      Numerical control flags are given in a protocol-specific

  47386.      representation.

  47387. 

  47388.    At this point, GDB has to perform the following actions.

  47389. 

  47390.    * If the parameters include pointer values to data needed as input to

  47391.      a system call, GDB requests this data from the target with a

  47392.      standard 'm' packet request.  This additional communication has to

  47393.      be expected by the target implementation and is handled as any

  47394.      other 'm' packet.

  47395. 

  47396.    * GDB translates all value from protocol representation to host

  47397.      representation as needed.  Datatypes are coerced into the host

  47398.      types.

  47399. 

  47400.    * GDB calls the system call.

  47401. 

  47402.    * It then coerces datatypes back to protocol representation.

  47403. 

  47404.    * If the system call is expected to return data in buffer space

  47405.      specified by pointer parameters to the call, the data is

  47406.      transmitted to the target using a 'M' or 'X' packet.  This packet

  47407.      has to be expected by the target implementation and is handled as

  47408.      any other 'M' or 'X' packet.

  47409. 

  47410.    Eventually GDB replies with another 'F' packet which contains all

  47411. necessary information for the target to continue.  This at least

  47412. contains

  47413. 

  47414.    * Return value.

  47415. 

  47416.    * 'errno', if has been changed by the system call.

  47417. 

  47418.    * "Ctrl-C" flag.

  47419. 

  47420.    After having done the needed type and value coercion, the target

  47421. continues the latest continue or step action.

  47422. 

  47423. 

  47424. File: gdb.info,  Node: The F Request Packet,  Next: The F Reply Packet,  Prev: Protocol Basics,  Up: File-I/O Remote Protocol Extension

  47425. 

  47426. E.13.3 The 'F' Request Packet

  47427. -----------------------------

  47428. 

  47429. The 'F' request packet has the following format:

  47430. 

  47431. 'FCALL-ID,PARAMETER...'

  47432. 

  47433.      CALL-ID is the identifier to indicate the host system call to be

  47434.      called.  This is just the name of the function.

  47435. 

  47436.      PARAMETER... are the parameters to the system call.  Parameters are

  47437.      hexadecimal integer values, either the actual values in case of

  47438.      scalar datatypes, pointers to target buffer space in case of

  47439.      compound datatypes and unspecified memory areas, or pointer/length

  47440.      pairs in case of string parameters.  These are appended to the

  47441.      CALL-ID as a comma-delimited list.  All values are transmitted in

  47442.      ASCII string representation, pointer/length pairs separated by a

  47443.      slash.

  47444. 

  47445. 

  47446. File: gdb.info,  Node: The F Reply Packet,  Next: The Ctrl-C Message,  Prev: The F Request Packet,  Up: File-I/O Remote Protocol Extension

  47447. 

  47448. E.13.4 The 'F' Reply Packet

  47449. ---------------------------

  47450. 

  47451. The 'F' reply packet has the following format:

  47452. 

  47453. 'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'

  47454. 

  47455.      RETCODE is the return code of the system call as hexadecimal value.

  47456. 

  47457.      ERRNO is the 'errno' set by the call, in protocol-specific

  47458.      representation.  This parameter can be omitted if the call was

  47459.      successful.

  47460. 

  47461.      CTRL-C FLAG is only sent if the user requested a break.  In this

  47462.      case, ERRNO must be sent as well, even if the call was successful.

  47463.      The CTRL-C FLAG itself consists of the character 'C':

  47464. 

  47465.           F0,0,C

  47466. 

  47467.      or, if the call was interrupted before the host call has been

  47468.      performed:

  47469. 

  47470.           F-1,4,C

  47471. 

  47472.      assuming 4 is the protocol-specific representation of 'EINTR'.

  47473. 

  47474. 

  47475. File: gdb.info,  Node: The Ctrl-C Message,  Next: Console I/O,  Prev: The F Reply Packet,  Up: File-I/O Remote Protocol Extension

  47476. 

  47477. E.13.5 The 'Ctrl-C' Message

  47478. ---------------------------

  47479. 

  47480. If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply

  47481. Packet::), the target should behave as if it had gotten a break message.

  47482. The meaning for the target is "system call interrupted by 'SIGINT'".

  47483. Consequentially, the target should actually stop (as with a break

  47484. message) and return to GDB with a 'T02' packet.

  47485. 

  47486.    It's important for the target to know in which state the system call

  47487. was interrupted.  There are two possible cases:

  47488. 

  47489.    * The system call hasn't been performed on the host yet.

  47490. 

  47491.    * The system call on the host has been finished.

  47492. 

  47493.    These two states can be distinguished by the target by the value of

  47494. the returned 'errno'.  If it's the protocol representation of 'EINTR',

  47495. the system call hasn't been performed.  This is equivalent to the

  47496. 'EINTR' handling on POSIX systems.  In any other case, the target may

  47497. presume that the system call has been finished -- successfully or not --

  47498. and should behave as if the break message arrived right after the system

  47499. call.

  47500. 

  47501.    GDB must behave reliably.  If the system call has not been called

  47502. yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno'

  47503. in the packet.  If the system call on the host has been finished before

  47504. the user requests a break, the full action must be finished by GDB.

  47505. This requires sending 'M' or 'X' packets as necessary.  The 'F' packet

  47506. may only be sent when either nothing has happened or the full action has

  47507. been completed.

  47508. 

  47509. 

  47510. File: gdb.info,  Node: Console I/O,  Next: List of Supported Calls,  Prev: The Ctrl-C Message,  Up: File-I/O Remote Protocol Extension

  47511. 

  47512. E.13.6 Console I/O

  47513. ------------------

  47514. 

  47515. By default and if not explicitly closed by the target system, the file

  47516. descriptors 0, 1 and 2 are connected to the GDB console.  Output on the

  47517. GDB console is handled as any other file output operation ('write(1,

  47518. ...)' or 'write(2, ...)').  Console input is handled by GDB so that

  47519. after the target read request from file descriptor 0 all following

  47520. typing is buffered until either one of the following conditions is met:

  47521. 

  47522.    * The user types 'Ctrl-c'.  The behaviour is as explained above, and

  47523.      the 'read' system call is treated as finished.

  47524. 

  47525.    * The user presses <RET>.  This is treated as end of input with a

  47526.      trailing newline.

  47527. 

  47528.    * The user types 'Ctrl-d'.  This is treated as end of input.  No

  47529.      trailing character (neither newline nor 'Ctrl-D') is appended to

  47530.      the input.

  47531. 

  47532.    If the user has typed more characters than fit in the buffer given to

  47533. the 'read' call, the trailing characters are buffered in GDB until

  47534. either another 'read(0, ...)' is requested by the target, or debugging

  47535. is stopped at the user's request.

  47536. 

  47537. 

  47538. File: gdb.info,  Node: List of Supported Calls,  Next: Protocol-specific Representation of Datatypes,  Prev: Console I/O,  Up: File-I/O Remote Protocol Extension

  47539. 

  47540. E.13.7 List of Supported Calls

  47541. ------------------------------

  47542. 

  47543. * Menu:

  47544. 

  47545. * open::

  47546. * close::

  47547. * read::

  47548. * write::

  47549. * lseek::

  47550. * rename::

  47551. * unlink::

  47552. * stat/fstat::

  47553. * gettimeofday::

  47554. * isatty::

  47555. * system::

  47556. 

  47557. 

  47558. File: gdb.info,  Node: open,  Next: close,  Up: List of Supported Calls

  47559. 

  47560. open

  47561. ....

  47562. 

  47563. Synopsis:

  47564.           int open(const char *pathname, int flags);

  47565.           int open(const char *pathname, int flags, mode_t mode);

  47566. 

  47567. Request:

  47568.      'Fopen,PATHPTR/LEN,FLAGS,MODE'

  47569. 

  47570.      FLAGS is the bitwise 'OR' of the following values:

  47571. 

  47572.      'O_CREAT'

  47573.           If the file does not exist it will be created.  The host rules

  47574.           apply as far as file ownership and time stamps are concerned.

  47575. 

  47576.      'O_EXCL'

  47577.           When used with 'O_CREAT', if the file already exists it is an

  47578.           error and open() fails.

  47579. 

  47580.      'O_TRUNC'

  47581.           If the file already exists and the open mode allows writing

  47582.           ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero

  47583.           length.

  47584. 

  47585.      'O_APPEND'

  47586.           The file is opened in append mode.

  47587. 

  47588.      'O_RDONLY'

  47589.           The file is opened for reading only.

  47590. 

  47591.      'O_WRONLY'

  47592.           The file is opened for writing only.

  47593. 

  47594.      'O_RDWR'

  47595.           The file is opened for reading and writing.

  47596. 

  47597.      Other bits are silently ignored.

  47598. 

  47599.      MODE is the bitwise 'OR' of the following values:

  47600. 

  47601.      'S_IRUSR'

  47602.           User has read permission.

  47603. 

  47604.      'S_IWUSR'

  47605.           User has write permission.

  47606. 

  47607.      'S_IRGRP'

  47608.           Group has read permission.

  47609. 

  47610.      'S_IWGRP'

  47611.           Group has write permission.

  47612. 

  47613.      'S_IROTH'

  47614.           Others have read permission.

  47615. 

  47616.      'S_IWOTH'

  47617.           Others have write permission.

  47618. 

  47619.      Other bits are silently ignored.

  47620. 

  47621. Return value:

  47622.      'open' returns the new file descriptor or -1 if an error occurred.

  47623. 

  47624. Errors:

  47625. 

  47626.      'EEXIST'

  47627.           PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used.

  47628. 

  47629.      'EISDIR'

  47630.           PATHNAME refers to a directory.

  47631. 

  47632.      'EACCES'

  47633.           The requested access is not allowed.

  47634. 

  47635.      'ENAMETOOLONG'

  47636.           PATHNAME was too long.

  47637. 

  47638.      'ENOENT'

  47639.           A directory component in PATHNAME does not exist.

  47640. 

  47641.      'ENODEV'

  47642.           PATHNAME refers to a device, pipe, named pipe or socket.

  47643. 

  47644.      'EROFS'

  47645.           PATHNAME refers to a file on a read-only filesystem and write

  47646.           access was requested.

  47647. 

  47648.      'EFAULT'

  47649.           PATHNAME is an invalid pointer value.

  47650. 

  47651.      'ENOSPC'

  47652.           No space on device to create the file.

  47653. 

  47654.      'EMFILE'

  47655.           The process already has the maximum number of files open.

  47656. 

  47657.      'ENFILE'

  47658.           The limit on the total number of files open on the system has

  47659.           been reached.

  47660. 

  47661.      'EINTR'

  47662.           The call was interrupted by the user.

  47663. 

  47664. 

  47665. File: gdb.info,  Node: close,  Next: read,  Prev: open,  Up: List of Supported Calls

  47666. 

  47667. close

  47668. .....

  47669. 

  47670. Synopsis:

  47671.           int close(int fd);

  47672. 

  47673. Request:

  47674.      'Fclose,FD'

  47675. 

  47676. Return value:

  47677.      'close' returns zero on success, or -1 if an error occurred.

  47678. 

  47679. Errors:

  47680. 

  47681.      'EBADF'

  47682.           FD isn't a valid open file descriptor.

  47683. 

  47684.      'EINTR'

  47685.           The call was interrupted by the user.

  47686. 

  47687. 

  47688. File: gdb.info,  Node: read,  Next: write,  Prev: close,  Up: List of Supported Calls

  47689. 

  47690. read

  47691. ....

  47692. 

  47693. Synopsis:

  47694.           int read(int fd, void *buf, unsigned int count);

  47695. 

  47696. Request:

  47697.      'Fread,FD,BUFPTR,COUNT'

  47698. 

  47699. Return value:

  47700.      On success, the number of bytes read is returned.  Zero indicates

  47701.      end of file.  If count is zero, read returns zero as well.  On

  47702.      error, -1 is returned.

  47703. 

  47704. Errors:

  47705. 

  47706.      'EBADF'

  47707.           FD is not a valid file descriptor or is not open for reading.

  47708. 

  47709.      'EFAULT'

  47710.           BUFPTR is an invalid pointer value.

  47711. 

  47712.      'EINTR'

  47713.           The call was interrupted by the user.

  47714. 

  47715. 

  47716. File: gdb.info,  Node: write,  Next: lseek,  Prev: read,  Up: List of Supported Calls

  47717. 

  47718. write

  47719. .....

  47720. 

  47721. Synopsis:

  47722.           int write(int fd, const void *buf, unsigned int count);

  47723. 

  47724. Request:

  47725.      'Fwrite,FD,BUFPTR,COUNT'

  47726. 

  47727. Return value:

  47728.      On success, the number of bytes written are returned.  Zero

  47729.      indicates nothing was written.  On error, -1 is returned.

  47730. 

  47731. Errors:

  47732. 

  47733.      'EBADF'

  47734.           FD is not a valid file descriptor or is not open for writing.

  47735. 

  47736.      'EFAULT'

  47737.           BUFPTR is an invalid pointer value.

  47738. 

  47739.      'EFBIG'

  47740.           An attempt was made to write a file that exceeds the

  47741.           host-specific maximum file size allowed.

  47742. 

  47743.      'ENOSPC'

  47744.           No space on device to write the data.

  47745. 

  47746.      'EINTR'

  47747.           The call was interrupted by the user.

  47748. 

  47749. 

  47750. File: gdb.info,  Node: lseek,  Next: rename,  Prev: write,  Up: List of Supported Calls

  47751. 

  47752. lseek

  47753. .....

  47754. 

  47755. Synopsis:

  47756.           long lseek (int fd, long offset, int flag);

  47757. 

  47758. Request:

  47759.      'Flseek,FD,OFFSET,FLAG'

  47760. 

  47761.      FLAG is one of:

  47762. 

  47763.      'SEEK_SET'

  47764.           The offset is set to OFFSET bytes.

  47765. 

  47766.      'SEEK_CUR'

  47767.           The offset is set to its current location plus OFFSET bytes.

  47768. 

  47769.      'SEEK_END'

  47770.           The offset is set to the size of the file plus OFFSET bytes.

  47771. 

  47772. Return value:

  47773.      On success, the resulting unsigned offset in bytes from the

  47774.      beginning of the file is returned.  Otherwise, a value of -1 is

  47775.      returned.

  47776. 

  47777. Errors:

  47778. 

  47779.      'EBADF'

  47780.           FD is not a valid open file descriptor.

  47781. 

  47782.      'ESPIPE'

  47783.           FD is associated with the GDB console.

  47784. 

  47785.      'EINVAL'

  47786.           FLAG is not a proper value.

  47787. 

  47788.      'EINTR'

  47789.           The call was interrupted by the user.

  47790. 

  47791. 

  47792. File: gdb.info,  Node: rename,  Next: unlink,  Prev: lseek,  Up: List of Supported Calls

  47793. 

  47794. rename

  47795. ......

  47796. 

  47797. Synopsis:

  47798.           int rename(const char *oldpath, const char *newpath);

  47799. 

  47800. Request:

  47801.      'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'

  47802. 

  47803. Return value:

  47804.      On success, zero is returned.  On error, -1 is returned.

  47805. 

  47806. Errors:

  47807. 

  47808.      'EISDIR'

  47809.           NEWPATH is an existing directory, but OLDPATH is not a

  47810.           directory.

  47811. 

  47812.      'EEXIST'

  47813.           NEWPATH is a non-empty directory.

  47814. 

  47815.      'EBUSY'

  47816.           OLDPATH or NEWPATH is a directory that is in use by some

  47817.           process.

  47818. 

  47819.      'EINVAL'

  47820.           An attempt was made to make a directory a subdirectory of

  47821.           itself.

  47822. 

  47823.      'ENOTDIR'

  47824.           A component used as a directory in OLDPATH or new path is not

  47825.           a directory.  Or OLDPATH is a directory and NEWPATH exists but

  47826.           is not a directory.

  47827. 

  47828.      'EFAULT'

  47829.           OLDPATHPTR or NEWPATHPTR are invalid pointer values.

  47830. 

  47831.      'EACCES'

  47832.           No access to the file or the path of the file.

  47833. 

  47834.      'ENAMETOOLONG'

  47835. 

  47836.           OLDPATH or NEWPATH was too long.

  47837. 

  47838.      'ENOENT'

  47839.           A directory component in OLDPATH or NEWPATH does not exist.

  47840. 

  47841.      'EROFS'

  47842.           The file is on a read-only filesystem.

  47843. 

  47844.      'ENOSPC'

  47845.           The device containing the file has no room for the new

  47846.           directory entry.

  47847. 

  47848.      'EINTR'

  47849.           The call was interrupted by the user.

  47850. 

  47851. 

  47852. File: gdb.info,  Node: unlink,  Next: stat/fstat,  Prev: rename,  Up: List of Supported Calls

  47853. 

  47854. unlink

  47855. ......

  47856. 

  47857. Synopsis:

  47858.           int unlink(const char *pathname);

  47859. 

  47860. Request:

  47861.      'Funlink,PATHNAMEPTR/LEN'

  47862. 

  47863. Return value:

  47864.      On success, zero is returned.  On error, -1 is returned.

  47865. 

  47866. Errors:

  47867. 

  47868.      'EACCES'

  47869.           No access to the file or the path of the file.

  47870. 

  47871.      'EPERM'

  47872.           The system does not allow unlinking of directories.

  47873. 

  47874.      'EBUSY'

  47875.           The file PATHNAME cannot be unlinked because it's being used

  47876.           by another process.

  47877. 

  47878.      'EFAULT'

  47879.           PATHNAMEPTR is an invalid pointer value.

  47880. 

  47881.      'ENAMETOOLONG'

  47882.           PATHNAME was too long.

  47883. 

  47884.      'ENOENT'

  47885.           A directory component in PATHNAME does not exist.

  47886. 

  47887.      'ENOTDIR'

  47888.           A component of the path is not a directory.

  47889. 

  47890.      'EROFS'

  47891.           The file is on a read-only filesystem.

  47892. 

  47893.      'EINTR'

  47894.           The call was interrupted by the user.

  47895. 

  47896. 

  47897. File: gdb.info,  Node: stat/fstat,  Next: gettimeofday,  Prev: unlink,  Up: List of Supported Calls

  47898. 

  47899. stat/fstat

  47900. ..........

  47901. 

  47902. Synopsis:

  47903.           int stat(const char *pathname, struct stat *buf);

  47904.           int fstat(int fd, struct stat *buf);

  47905. 

  47906. Request:

  47907.      'Fstat,PATHNAMEPTR/LEN,BUFPTR'

  47908.      'Ffstat,FD,BUFPTR'

  47909. 

  47910. Return value:

  47911.      On success, zero is returned.  On error, -1 is returned.

  47912. 

  47913. Errors:

  47914. 

  47915.      'EBADF'

  47916.           FD is not a valid open file.

  47917. 

  47918.      'ENOENT'

  47919.           A directory component in PATHNAME does not exist or the path

  47920.           is an empty string.

  47921. 

  47922.      'ENOTDIR'

  47923.           A component of the path is not a directory.

  47924. 

  47925.      'EFAULT'

  47926.           PATHNAMEPTR is an invalid pointer value.

  47927. 

  47928.      'EACCES'

  47929.           No access to the file or the path of the file.

  47930. 

  47931.      'ENAMETOOLONG'

  47932.           PATHNAME was too long.

  47933. 

  47934.      'EINTR'

  47935.           The call was interrupted by the user.

  47936. 

  47937. 

  47938. File: gdb.info,  Node: gettimeofday,  Next: isatty,  Prev: stat/fstat,  Up: List of Supported Calls

  47939. 

  47940. gettimeofday

  47941. ............

  47942. 

  47943. Synopsis:

  47944.           int gettimeofday(struct timeval *tv, void *tz);

  47945. 

  47946. Request:

  47947.      'Fgettimeofday,TVPTR,TZPTR'

  47948. 

  47949. Return value:

  47950.      On success, 0 is returned, -1 otherwise.

  47951. 

  47952. Errors:

  47953. 

  47954.      'EINVAL'

  47955.           TZ is a non-NULL pointer.

  47956. 

  47957.      'EFAULT'

  47958.           TVPTR and/or TZPTR is an invalid pointer value.

  47959. 

  47960. 

  47961. File: gdb.info,  Node: isatty,  Next: system,  Prev: gettimeofday,  Up: List of Supported Calls

  47962. 

  47963. isatty

  47964. ......

  47965. 

  47966. Synopsis:

  47967.           int isatty(int fd);

  47968. 

  47969. Request:

  47970.      'Fisatty,FD'

  47971. 

  47972. Return value:

  47973.      Returns 1 if FD refers to the GDB console, 0 otherwise.

  47974. 

  47975. Errors:

  47976. 

  47977.      'EINTR'

  47978.           The call was interrupted by the user.

  47979. 

  47980.    Note that the 'isatty' call is treated as a special case: it returns

  47981. 1 to the target if the file descriptor is attached to the GDB console, 0

  47982. otherwise.  Implementing through system calls would require implementing

  47983. 'ioctl' and would be more complex than needed.

  47984. 

  47985. 

  47986. File: gdb.info,  Node: system,  Prev: isatty,  Up: List of Supported Calls

  47987. 

  47988. system

  47989. ......

  47990. 

  47991. Synopsis:

  47992.           int system(const char *command);

  47993. 

  47994. Request:

  47995.      'Fsystem,COMMANDPTR/LEN'

  47996. 

  47997. Return value:

  47998.      If LEN is zero, the return value indicates whether a shell is

  47999.      available.  A zero return value indicates a shell is not available.

  48000.      For non-zero LEN, the value returned is -1 on error and the return

  48001.      status of the command otherwise.  Only the exit status of the

  48002.      command is returned, which is extracted from the host's 'system'

  48003.      return value by calling 'WEXITSTATUS(retval)'.  In case '/bin/sh'

  48004.      could not be executed, 127 is returned.

  48005. 

  48006. Errors:

  48007. 

  48008.      'EINTR'

  48009.           The call was interrupted by the user.

  48010. 

  48011.    GDB takes over the full task of calling the necessary host calls to

  48012. perform the 'system' call.  The return value of 'system' on the host is

  48013. simplified before it's returned to the target.  Any termination signal

  48014. information from the child process is discarded, and the return value

  48015. consists entirely of the exit status of the called command.

  48016. 

  48017.    Due to security concerns, the 'system' call is by default refused by

  48018. GDB.  The user has to allow this call explicitly with the 'set remote

  48019. system-call-allowed 1' command.

  48020. 

  48021. 'set remote system-call-allowed'

  48022.      Control whether to allow the 'system' calls in the File I/O

  48023.      protocol for the remote target.  The default is zero (disabled).

  48024. 

  48025. 'show remote system-call-allowed'

  48026.      Show whether the 'system' calls are allowed in the File I/O

  48027.      protocol.

  48028. 

  48029. 

  48030. File: gdb.info,  Node: Protocol-specific Representation of Datatypes,  Next: Constants,  Prev: List of Supported Calls,  Up: File-I/O Remote Protocol Extension

  48031. 

  48032. E.13.8 Protocol-specific Representation of Datatypes

  48033. ----------------------------------------------------

  48034. 

  48035. * Menu:

  48036. 

  48037. * Integral Datatypes::

  48038. * Pointer Values::

  48039. * Memory Transfer::

  48040. * struct stat::

  48041. * struct timeval::

  48042. 

  48043. 

  48044. File: gdb.info,  Node: Integral Datatypes,  Next: Pointer Values,  Up: Protocol-specific Representation of Datatypes

  48045. 

  48046. Integral Datatypes

  48047. ..................

  48048. 

  48049. The integral datatypes used in the system calls are 'int', 'unsigned

  48050. int', 'long', 'unsigned long', 'mode_t', and 'time_t'.

  48051. 

  48052.    'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32

  48053. bit values in this protocol.

  48054. 

  48055.    'long' and 'unsigned long' are implemented as 64 bit types.

  48056. 

  48057.    *Note Limits::, for corresponding MIN and MAX values (similar to

  48058. those in 'limits.h') to allow range checking on host and target.

  48059. 

  48060.    'time_t' datatypes are defined as seconds since the Epoch.

  48061. 

  48062.    All integral datatypes transferred as part of a memory read or write

  48063. of a structured datatype e.g. a 'struct stat' have to be given in big

  48064. endian byte order.

  48065. 

  48066. 

  48067. File: gdb.info,  Node: Pointer Values,  Next: Memory Transfer,  Prev: Integral Datatypes,  Up: Protocol-specific Representation of Datatypes

  48068. 

  48069. Pointer Values

  48070. ..............

  48071. 

  48072. Pointers to target data are transmitted as they are.  An exception is

  48073. made for pointers to buffers for which the length isn't transmitted as

  48074. part of the function call, namely strings.  Strings are transmitted as a

  48075. pointer/length pair, both as hex values, e.g.

  48076. 

  48077.      1aaf/12

  48078. 

  48079. which is a pointer to data of length 18 bytes at position 0x1aaf.  The

  48080. length is defined as the full string length in bytes, including the

  48081. trailing null byte.  For example, the string '"hello world"' at address

  48082. 0x123456 is transmitted as

  48083. 

  48084.      123456/d

  48085. 

  48086. 

  48087. File: gdb.info,  Node: Memory Transfer,  Next: struct stat,  Prev: Pointer Values,  Up: Protocol-specific Representation of Datatypes

  48088. 

  48089. Memory Transfer

  48090. ...............

  48091. 

  48092. Structured data which is transferred using a memory read or write (for

  48093. example, a 'struct stat') is expected to be in a protocol-specific

  48094. format with all scalar multibyte datatypes being big endian.

  48095. Translation to this representation needs to be done both by the target

  48096. before the 'F' packet is sent, and by GDB before it transfers memory to

  48097. the target.  Transferred pointers to structured data should point to the

  48098. already-coerced data at any time.

  48099. 

  48100. 

  48101. File: gdb.info,  Node: struct stat,  Next: struct timeval,  Prev: Memory Transfer,  Up: Protocol-specific Representation of Datatypes

  48102. 

  48103. struct stat

  48104. ...........

  48105. 

  48106. The buffer of type 'struct stat' used by the target and GDB is defined

  48107. as follows:

  48108. 

  48109.      struct stat {

  48110.          unsigned int  st_dev;      /* device */

  48111.          unsigned int  st_ino;      /* inode */

  48112.          mode_t        st_mode;     /* protection */

  48113.          unsigned int  st_nlink;    /* number of hard links */

  48114.          unsigned int  st_uid;      /* user ID of owner */

  48115.          unsigned int  st_gid;      /* group ID of owner */

  48116.          unsigned int  st_rdev;     /* device type (if inode device) */

  48117.          unsigned long st_size;     /* total size, in bytes */

  48118.          unsigned long st_blksize;  /* blocksize for filesystem I/O */

  48119.          unsigned long st_blocks;   /* number of blocks allocated */

  48120.          time_t        st_atime;    /* time of last access */

  48121.          time_t        st_mtime;    /* time of last modification */

  48122.          time_t        st_ctime;    /* time of last change */

  48123.      };

  48124. 

  48125.    The integral datatypes conform to the definitions given in the

  48126. appropriate section (see *note Integral Datatypes::, for details) so

  48127. this structure is of size 64 bytes.

  48128. 

  48129.    The values of several fields have a restricted meaning and/or range

  48130. of values.

  48131. 

  48132. 'st_dev'

  48133.      A value of 0 represents a file, 1 the console.

  48134. 

  48135. 'st_ino'

  48136.      No valid meaning for the target.  Transmitted unchanged.

  48137. 

  48138. 'st_mode'

  48139.      Valid mode bits are described in *note Constants::.  Any other bits

  48140.      have currently no meaning for the target.

  48141. 

  48142. 'st_uid'

  48143. 'st_gid'

  48144. 'st_rdev'

  48145.      No valid meaning for the target.  Transmitted unchanged.

  48146. 

  48147. 'st_atime'

  48148. 'st_mtime'

  48149. 'st_ctime'

  48150.      These values have a host and file system dependent accuracy.

  48151.      Especially on Windows hosts, the file system may not support exact

  48152.      timing values.

  48153. 

  48154.    The target gets a 'struct stat' of the above representation and is

  48155. responsible for coercing it to the target representation before

  48156. continuing.

  48157. 

  48158.    Note that due to size differences between the host, target, and

  48159. protocol representations of 'struct stat' members, these members could

  48160. eventually get truncated on the target.

  48161. 

  48162. 

  48163. File: gdb.info,  Node: struct timeval,  Prev: struct stat,  Up: Protocol-specific Representation of Datatypes

  48164. 

  48165. struct timeval

  48166. ..............

  48167. 

  48168. The buffer of type 'struct timeval' used by the File-I/O protocol is

  48169. defined as follows:

  48170. 

  48171.      struct timeval {

  48172.          time_t tv_sec;  /* second */

  48173.          long   tv_usec; /* microsecond */

  48174.      };

  48175. 

  48176.    The integral datatypes conform to the definitions given in the

  48177. appropriate section (see *note Integral Datatypes::, for details) so

  48178. this structure is of size 8 bytes.

  48179. 

  48180. 

  48181. File: gdb.info,  Node: Constants,  Next: File-I/O Examples,  Prev: Protocol-specific Representation of Datatypes,  Up: File-I/O Remote Protocol Extension

  48182. 

  48183. E.13.9 Constants

  48184. ----------------

  48185. 

  48186. The following values are used for the constants inside of the protocol.

  48187. GDB and target are responsible for translating these values before and

  48188. after the call as needed.

  48189. 

  48190. * Menu:

  48191. 

  48192. * Open Flags::

  48193. * mode_t Values::

  48194. * Errno Values::

  48195. * Lseek Flags::

  48196. * Limits::

  48197. 

  48198. 

  48199. File: gdb.info,  Node: Open Flags,  Next: mode_t Values,  Up: Constants

  48200. 

  48201. Open Flags

  48202. ..........

  48203. 

  48204. All values are given in hexadecimal representation.

  48205. 

  48206.        O_RDONLY        0x0

  48207.        O_WRONLY        0x1

  48208.        O_RDWR          0x2

  48209.        O_APPEND        0x8

  48210.        O_CREAT       0x200

  48211.        O_TRUNC       0x400

  48212.        O_EXCL        0x800

  48213. 

  48214. 

  48215. File: gdb.info,  Node: mode_t Values,  Next: Errno Values,  Prev: Open Flags,  Up: Constants

  48216. 

  48217. mode_t Values

  48218. .............

  48219. 

  48220. All values are given in octal representation.

  48221. 

  48222.        S_IFREG       0100000

  48223.        S_IFDIR        040000

  48224.        S_IRUSR          0400

  48225.        S_IWUSR          0200

  48226.        S_IXUSR          0100

  48227.        S_IRGRP           040

  48228.        S_IWGRP           020

  48229.        S_IXGRP           010

  48230.        S_IROTH            04

  48231.        S_IWOTH            02

  48232.        S_IXOTH            01

  48233. 

  48234. 

  48235. File: gdb.info,  Node: Errno Values,  Next: Lseek Flags,  Prev: mode_t Values,  Up: Constants

  48236. 

  48237. Errno Values

  48238. ............

  48239. 

  48240. All values are given in decimal representation.

  48241. 

  48242.        EPERM           1

  48243.        ENOENT          2

  48244.        EINTR           4

  48245.        EBADF           9

  48246.        EACCES         13

  48247.        EFAULT         14

  48248.        EBUSY          16

  48249.        EEXIST         17

  48250.        ENODEV         19

  48251.        ENOTDIR        20

  48252.        EISDIR         21

  48253.        EINVAL         22

  48254.        ENFILE         23

  48255.        EMFILE         24

  48256.        EFBIG          27

  48257.        ENOSPC         28

  48258.        ESPIPE         29

  48259.        EROFS          30

  48260.        ENAMETOOLONG   91

  48261.        EUNKNOWN       9999

  48262. 

  48263.    'EUNKNOWN' is used as a fallback error value if a host system returns

  48264. any error value not in the list of supported error numbers.

  48265. 

  48266. 

  48267. File: gdb.info,  Node: Lseek Flags,  Next: Limits,  Prev: Errno Values,  Up: Constants

  48268. 

  48269. Lseek Flags

  48270. ...........

  48271. 

  48272.        SEEK_SET      0

  48273.        SEEK_CUR      1

  48274.        SEEK_END      2

  48275. 

  48276. 

  48277. File: gdb.info,  Node: Limits,  Prev: Lseek Flags,  Up: Constants

  48278. 

  48279. Limits

  48280. ......

  48281. 

  48282. All values are given in decimal representation.

  48283. 

  48284.        INT_MIN       -2147483648

  48285.        INT_MAX        2147483647

  48286.        UINT_MAX       4294967295

  48287.        LONG_MIN      -9223372036854775808

  48288.        LONG_MAX       9223372036854775807

  48289.        ULONG_MAX      18446744073709551615

  48290. 

  48291. 

  48292. File: gdb.info,  Node: File-I/O Examples,  Prev: Constants,  Up: File-I/O Remote Protocol Extension

  48293. 

  48294. E.13.10 File-I/O Examples

  48295. -------------------------

  48296. 

  48297. Example sequence of a write call, file descriptor 3, buffer is at target

  48298. address 0x1234, 6 bytes should be written:

  48299. 

  48300.      <- Fwrite,3,1234,6

  48301.      _request memory read from target_

  48302.      -> m1234,6

  48303.      <- XXXXXX

  48304.      _return "6 bytes written"_

  48305.      -> F6

  48306. 

  48307.    Example sequence of a read call, file descriptor 3, buffer is at

  48308. target address 0x1234, 6 bytes should be read:

  48309. 

  48310.      <- Fread,3,1234,6

  48311.      _request memory write to target_

  48312.      -> X1234,6:XXXXXX

  48313.      _return "6 bytes read"_

  48314.      -> F6

  48315. 

  48316.    Example sequence of a read call, call fails on the host due to

  48317. invalid file descriptor ('EBADF'):

  48318. 

  48319.      <- Fread,3,1234,6

  48320.      -> F-1,9

  48321. 

  48322.    Example sequence of a read call, user presses 'Ctrl-c' before syscall

  48323. on host is called:

  48324. 

  48325.      <- Fread,3,1234,6

  48326.      -> F-1,4,C

  48327.      <- T02

  48328. 

  48329.    Example sequence of a read call, user presses 'Ctrl-c' after syscall

  48330. on host is called:

  48331. 

  48332.      <- Fread,3,1234,6

  48333.      -> X1234,6:XXXXXX

  48334.      <- T02

  48335. 

  48336. 

  48337. File: gdb.info,  Node: Library List Format,  Next: Library List Format for SVR4 Targets,  Prev: File-I/O Remote Protocol Extension,  Up: Remote Protocol

  48338. 

  48339. E.14 Library List Format

  48340. ========================

  48341. 

  48342. On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same

  48343. process as your application to manage libraries.  In this case, GDB can

  48344. use the loader's symbol table and normal memory operations to maintain a

  48345. list of shared libraries.  On other platforms, the operating system

  48346. manages loaded libraries.  GDB can not retrieve the list of currently

  48347. loaded libraries through memory operations, so it uses the

  48348. 'qXfer:libraries:read' packet (*note qXfer library list read::) instead.

  48349. The remote stub queries the target's operating system and reports which

  48350. libraries are loaded.

  48351. 

  48352.    The 'qXfer:libraries:read' packet returns an XML document which lists

  48353. loaded libraries and their offsets.  Each library has an associated name

  48354. and one or more segment or section base addresses, which report where

  48355. the library was loaded in memory.

  48356. 

  48357.    For the common case of libraries that are fully linked binaries, the

  48358. library should have a list of segments.  If the target supports dynamic

  48359. linking of a relocatable object file, its library XML element should

  48360. instead include a list of allocated sections.  The segment or section

  48361. bases are start addresses, not relocation offsets; they do not depend on

  48362. the library's link-time base addresses.

  48363. 

  48364.    GDB must be linked with the Expat library to support XML library

  48365. lists.  *Note Expat::.

  48366. 

  48367.    A simple memory map, with one loaded library relocated by a single

  48368. offset, looks like this:

  48369. 

  48370.      <library-list>

  48371.        <library name="/lib/libc.so.6">

  48372.          <segment address="0x10000000"/>

  48373.        </library>

  48374.      </library-list>

  48375. 

  48376.    Another simple memory map, with one loaded library with three

  48377. allocated sections (.text, .data, .bss), looks like this:

  48378. 

  48379.      <library-list>

  48380.        <library name="sharedlib.o">

  48381.          <section address="0x10000000"/>

  48382.          <section address="0x20000000"/>

  48383.          <section address="0x30000000"/>

  48384.        </library>

  48385.      </library-list>

  48386. 

  48387.    The format of a library list is described by this DTD:

  48388. 

  48389.      <!-- library-list: Root element with versioning -->

  48390.      <!ELEMENT library-list  (library)*>

  48391.      <!ATTLIST library-list  version CDATA   #FIXED  "1.0">

  48392.      <!ELEMENT library       (segment*, section*)>

  48393.      <!ATTLIST library       name    CDATA   #REQUIRED>

  48394.      <!ELEMENT segment       EMPTY>

  48395.      <!ATTLIST segment       address CDATA   #REQUIRED>

  48396.      <!ELEMENT section       EMPTY>

  48397.      <!ATTLIST section       address CDATA   #REQUIRED>

  48398. 

  48399.    In addition, segments and section descriptors cannot be mixed within

  48400. a single library element, and you must supply at least one segment or

  48401. section for each library.

  48402. 

  48403. 

  48404. File: gdb.info,  Node: Library List Format for SVR4 Targets,  Next: Memory Map Format,  Prev: Library List Format,  Up: Remote Protocol

  48405. 

  48406. E.15 Library List Format for SVR4 Targets

  48407. =========================================

  48408. 

  48409. On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g.

  48410. 'ld.so') and normal memory operations to maintain a list of shared

  48411. libraries.  Still a special library list provided by this packet is more

  48412. efficient for the GDB remote protocol.

  48413. 

  48414.    The 'qXfer:libraries-svr4:read' packet returns an XML document which

  48415. lists loaded libraries and their SVR4 linker parameters.  For each

  48416. library on SVR4 target, the following parameters are reported:

  48417. 

  48418.    - 'name', the absolute file name from the 'l_name' field of 'struct

  48419.      link_map'.

  48420.    - 'lm' with address of 'struct link_map' used for TLS (Thread Local

  48421.      Storage) access.

  48422.    - 'l_addr', the displacement as read from the field 'l_addr' of

  48423.      'struct link_map'.  For prelinked libraries this is not an absolute

  48424.      memory address.  It is a displacement of absolute memory address

  48425.      against address the file was prelinked to during the library load.

  48426.    - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment

  48427. 

  48428.    Additionally the single 'main-lm' attribute specifies address of

  48429. 'struct link_map' used for the main executable.  This parameter is used

  48430. for TLS access and its presence is optional.

  48431. 

  48432.    GDB must be linked with the Expat library to support XML SVR4 library

  48433. lists.  *Note Expat::.

  48434. 

  48435.    A simple memory map, with two loaded libraries (which do not use

  48436. prelink), looks like this:

  48437. 

  48438.      <library-list-svr4 version="1.0" main-lm="0xe4f8f8">

  48439.        <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"

  48440.                 l_ld="0xe4eefc"/>

  48441.        <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"

  48442.                 l_ld="0x152350"/>

  48443.      </library-list-svr>

  48444. 

  48445.    The format of an SVR4 library list is described by this DTD:

  48446. 

  48447.      <!-- library-list-svr4: Root element with versioning -->

  48448.      <!ELEMENT library-list-svr4  (library)*>

  48449.      <!ATTLIST library-list-svr4  version CDATA   #FIXED  "1.0">

  48450.      <!ATTLIST library-list-svr4  main-lm CDATA   #IMPLIED>

  48451.      <!ELEMENT library            EMPTY>

  48452.      <!ATTLIST library            name    CDATA   #REQUIRED>

  48453.      <!ATTLIST library            lm      CDATA   #REQUIRED>

  48454.      <!ATTLIST library            l_addr  CDATA   #REQUIRED>

  48455.      <!ATTLIST library            l_ld    CDATA   #REQUIRED>

  48456. 

  48457. 

  48458. File: gdb.info,  Node: Memory Map Format,  Next: Thread List Format,  Prev: Library List Format for SVR4 Targets,  Up: Remote Protocol

  48459. 

  48460. E.16 Memory Map Format

  48461. ======================

  48462. 

  48463. To be able to write into flash memory, GDB needs to obtain a memory map

  48464. from the target.  This section describes the format of the memory map.

  48465. 

  48466.    The memory map is obtained using the 'qXfer:memory-map:read' (*note

  48467. qXfer memory map read::) packet and is an XML document that lists memory

  48468. regions.

  48469. 

  48470.    GDB must be linked with the Expat library to support XML memory maps.

  48471. *Note Expat::.

  48472. 

  48473.    The top-level structure of the document is shown below:

  48474. 

  48475.      <?xml version="1.0"?>

  48476.      <!DOCTYPE memory-map

  48477.                PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"

  48478.                       "http://sourceware.org/gdb/gdb-memory-map.dtd">

  48479.      <memory-map>

  48480.          region...

  48481.      </memory-map>

  48482. 

  48483.    Each region can be either:

  48484. 

  48485.    * A region of RAM starting at ADDR and extending for LENGTH bytes

  48486.      from there:

  48487. 

  48488.           <memory type="ram" start="ADDR" length="LENGTH"/>

  48489. 

  48490.    * A region of read-only memory:

  48491. 

  48492.           <memory type="rom" start="ADDR" length="LENGTH"/>

  48493. 

  48494.    * A region of flash memory, with erasure blocks BLOCKSIZE bytes in

  48495.      length:

  48496. 

  48497.           <memory type="flash" start="ADDR" length="LENGTH">

  48498.             <property name="blocksize">BLOCKSIZE</property>

  48499.           </memory>

  48500. 

  48501.    Regions must not overlap.  GDB assumes that areas of memory not

  48502. covered by the memory map are RAM, and uses the ordinary 'M' and 'X'

  48503. packets to write to addresses in such ranges.

  48504. 

  48505.    The formal DTD for memory map format is given below:

  48506. 

  48507.      <!-- ................................................... -->

  48508.      <!-- Memory Map XML DTD ................................ -->

  48509.      <!-- File: memory-map.dtd .............................. -->

  48510.      <!-- .................................... .............. -->

  48511.      <!-- memory-map.dtd -->

  48512.      <!-- memory-map: Root element with versioning -->

  48513.      <!ELEMENT memory-map (memory)*>

  48514.      <!ATTLIST memory-map    version CDATA   #FIXED  "1.0.0">

  48515.      <!ELEMENT memory (property)*>

  48516.      <!-- memory: Specifies a memory region,

  48517.                   and its type, or device. -->

  48518.      <!ATTLIST memory        type    (ram|rom|flash) #REQUIRED

  48519.                              start   CDATA   #REQUIRED

  48520.                              length  CDATA   #REQUIRED>

  48521.      <!-- property: Generic attribute tag -->

  48522.      <!ELEMENT property (#PCDATA | property)*>

  48523.      <!ATTLIST property      name    (blocksize) #REQUIRED>

  48524. 

  48525. 

  48526. File: gdb.info,  Node: Thread List Format,  Next: Traceframe Info Format,  Prev: Memory Map Format,  Up: Remote Protocol

  48527. 

  48528. E.17 Thread List Format

  48529. =======================

  48530. 

  48531. To efficiently update the list of threads and their attributes, GDB

  48532. issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and

  48533. obtains the XML document with the following structure:

  48534. 

  48535.      <?xml version="1.0"?>

  48536.      <threads>

  48537.          <thread id="id" core="0" name="name">

  48538.          ... description ...

  48539.          </thread>

  48540.      </threads>

  48541. 

  48542.    Each 'thread' element must have the 'id' attribute that identifies

  48543. the thread (*note thread-id syntax::).  The 'core' attribute, if

  48544. present, specifies which processor core the thread was last executing

  48545. on.  The 'name' attribute, if present, specifies the human-readable name

  48546. of the thread.  The content of the of 'thread' element is interpreted as

  48547. human-readable auxiliary information.  The 'handle' attribute, if

  48548. present, is a hex encoded representation of the thread handle.

  48549. 

  48550. 

  48551. File: gdb.info,  Node: Traceframe Info Format,  Next: Branch Trace Format,  Prev: Thread List Format,  Up: Remote Protocol

  48552. 

  48553. E.18 Traceframe Info Format

  48554. ===========================

  48555. 

  48556. To be able to know which objects in the inferior can be examined when

  48557. inspecting a tracepoint hit, GDB needs to obtain the list of memory

  48558. ranges, registers and trace state variables that have been collected in

  48559. a traceframe.

  48560. 

  48561.    This list is obtained using the 'qXfer:traceframe-info:read' (*note

  48562. qXfer traceframe info read::) packet and is an XML document.

  48563. 

  48564.    GDB must be linked with the Expat library to support XML traceframe

  48565. info discovery.  *Note Expat::.

  48566. 

  48567.    The top-level structure of the document is shown below:

  48568. 

  48569.      <?xml version="1.0"?>

  48570.      <!DOCTYPE traceframe-info

  48571.                PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"

  48572.                       "http://sourceware.org/gdb/gdb-traceframe-info.dtd">

  48573.      <traceframe-info>

  48574.         block...

  48575.      </traceframe-info>

  48576. 

  48577.    Each traceframe block can be either:

  48578. 

  48579.    * A region of collected memory starting at ADDR and extending for

  48580.      LENGTH bytes from there:

  48581. 

  48582.           <memory start="ADDR" length="LENGTH"/>

  48583. 

  48584.    * A block indicating trace state variable numbered NUMBER has been

  48585.      collected:

  48586. 

  48587.           <tvar id="NUMBER"/>

  48588. 

  48589.    The formal DTD for the traceframe info format is given below:

  48590. 

  48591.      <!ELEMENT traceframe-info  (memory | tvar)* >

  48592.      <!ATTLIST traceframe-info  version CDATA   #FIXED  "1.0">

  48593. 

  48594.      <!ELEMENT memory        EMPTY>

  48595.      <!ATTLIST memory        start   CDATA   #REQUIRED

  48596.                              length  CDATA   #REQUIRED>

  48597.      <!ELEMENT tvar>

  48598.      <!ATTLIST tvar          id      CDATA   #REQUIRED>

  48599. 

  48600. 

  48601. File: gdb.info,  Node: Branch Trace Format,  Next: Branch Trace Configuration Format,  Prev: Traceframe Info Format,  Up: Remote Protocol

  48602. 

  48603. E.19 Branch Trace Format

  48604. ========================

  48605. 

  48606. In order to display the branch trace of an inferior thread, GDB needs to

  48607. obtain the list of branches.  This list is represented as list of

  48608. sequential code blocks that are connected via branches.  The code in

  48609. each block has been executed sequentially.

  48610. 

  48611.    This list is obtained using the 'qXfer:btrace:read' (*note qXfer

  48612. btrace read::) packet and is an XML document.

  48613. 

  48614.    GDB must be linked with the Expat library to support XML traceframe

  48615. info discovery.  *Note Expat::.

  48616. 

  48617.    The top-level structure of the document is shown below:

  48618. 

  48619.      <?xml version="1.0"?>

  48620.      <!DOCTYPE btrace

  48621.                PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"

  48622.                       "http://sourceware.org/gdb/gdb-btrace.dtd">

  48623.      <btrace>

  48624.         block...

  48625.      </btrace>

  48626. 

  48627.    * A block of sequentially executed instructions starting at BEGIN and

  48628.      ending at END:

  48629. 

  48630.           <block begin="BEGIN" end="END"/>

  48631. 

  48632.    The formal DTD for the branch trace format is given below:

  48633. 

  48634.      <!ELEMENT btrace  (block* | pt) >

  48635.      <!ATTLIST btrace  version CDATA   #FIXED "1.0">

  48636. 

  48637.      <!ELEMENT block        EMPTY>

  48638.      <!ATTLIST block        begin  CDATA   #REQUIRED

  48639.                             end    CDATA   #REQUIRED>

  48640. 

  48641.      <!ELEMENT pt (pt-config?, raw?)>

  48642. 

  48643.      <!ELEMENT pt-config (cpu?)>

  48644. 

  48645.      <!ELEMENT cpu EMPTY>

  48646.      <!ATTLIST cpu vendor   CDATA #REQUIRED

  48647.                    family   CDATA #REQUIRED

  48648.                    model    CDATA #REQUIRED

  48649.                    stepping CDATA #REQUIRED>

  48650. 

  48651.      <!ELEMENT raw (#PCDATA)>

  48652. 

  48653. 

  48654. File: gdb.info,  Node: Branch Trace Configuration Format,  Prev: Branch Trace Format,  Up: Remote Protocol

  48655. 

  48656. E.20 Branch Trace Configuration Format

  48657. ======================================

  48658. 

  48659. For each inferior thread, GDB can obtain the branch trace configuration

  48660. using the 'qXfer:btrace-conf:read' (*note qXfer btrace-conf read::)

  48661. packet.

  48662. 

  48663.    The configuration describes the branch trace format and configuration

  48664. settings for that format.  The following information is described:

  48665. 

  48666. 'bts'

  48667.      This thread uses the "Branch Trace Store" (BTS) format.

  48668.      'size'

  48669.           The size of the BTS ring buffer in bytes.

  48670. 'pt'

  48671.      This thread uses the "Intel Processor Trace" (Intel PT) format.

  48672.      'size'

  48673.           The size of the Intel PT ring buffer in bytes.

  48674. 

  48675.    GDB must be linked with the Expat library to support XML branch trace

  48676. configuration discovery.  *Note Expat::.

  48677. 

  48678.    The formal DTD for the branch trace configuration format is given

  48679. below:

  48680. 

  48681.      <!ELEMENT btrace-conf	(bts?, pt?)>

  48682.      <!ATTLIST btrace-conf	version	CDATA	#FIXED "1.0">

  48683. 

  48684.      <!ELEMENT bts	EMPTY>

  48685.      <!ATTLIST bts	size	CDATA	#IMPLIED>

  48686. 

  48687.      <!ELEMENT pt	EMPTY>

  48688.      <!ATTLIST pt	size	CDATA	#IMPLIED>

  48689. 

  48690. 

  48691. File: gdb.info,  Node: Agent Expressions,  Next: Target Descriptions,  Prev: Remote Protocol,  Up: Top

  48692. 

  48693. Appendix F The GDB Agent Expression Mechanism

  48694. *********************************************

  48695. 

  48696. In some applications, it is not feasible for the debugger to interrupt

  48697. the program's execution long enough for the developer to learn anything

  48698. helpful about its behavior.  If the program's correctness depends on its

  48699. real-time behavior, delays introduced by a debugger might cause the

  48700. program to fail, even when the code itself is correct.  It is useful to

  48701. be able to observe the program's behavior without interrupting it.

  48702. 

  48703.    Using GDB's 'trace' and 'collect' commands, the user can specify

  48704. locations in the program, and arbitrary expressions to evaluate when

  48705. those locations are reached.  Later, using the 'tfind' command, she can

  48706. examine the values those expressions had when the program hit the trace

  48707. points.  The expressions may also denote objects in memory -- structures

  48708. or arrays, for example -- whose values GDB should record; while visiting

  48709. a particular tracepoint, the user may inspect those objects as if they

  48710. were in memory at that moment.  However, because GDB records these

  48711. values without interacting with the user, it can do so quickly and

  48712. unobtrusively, hopefully not disturbing the program's behavior.

  48713. 

  48714.    When GDB is debugging a remote target, the GDB "agent" code running

  48715. on the target computes the values of the expressions itself.  To avoid

  48716. having a full symbolic expression evaluator on the agent, GDB translates

  48717. expressions in the source language into a simpler bytecode language, and

  48718. then sends the bytecode to the agent; the agent then executes the

  48719. bytecode, and records the values for GDB to retrieve later.

  48720. 

  48721.    The bytecode language is simple; there are forty-odd opcodes, the

  48722. bulk of which are the usual vocabulary of C operands (addition,

  48723. subtraction, shifts, and so on) and various sizes of literals and memory

  48724. reference operations.  The bytecode interpreter operates strictly on

  48725. machine-level values -- various sizes of integers and floating point

  48726. numbers -- and requires no information about types or symbols; thus, the

  48727. interpreter's internal data structures are simple, and each bytecode

  48728. requires only a few native machine instructions to implement it.  The

  48729. interpreter is small, and strict limits on the memory and time required

  48730. to evaluate an expression are easy to determine, making it suitable for

  48731. use by the debugging agent in real-time applications.

  48732. 

  48733. * Menu:

  48734. 

  48735. * General Bytecode Design::     Overview of the interpreter.

  48736. * Bytecode Descriptions::       What each one does.

  48737. * Using Agent Expressions::     How agent expressions fit into the big picture.

  48738. * Varying Target Capabilities:: How to discover what the target can do.

  48739. * Rationale::                   Why we did it this way.

  48740. 

  48741. 

  48742. File: gdb.info,  Node: General Bytecode Design,  Next: Bytecode Descriptions,  Up: Agent Expressions

  48743. 

  48744. F.1 General Bytecode Design

  48745. ===========================

  48746. 

  48747. The agent represents bytecode expressions as an array of bytes.  Each

  48748. instruction is one byte long (thus the term "bytecode").  Some

  48749. instructions are followed by operand bytes; for example, the 'goto'

  48750. instruction is followed by a destination for the jump.

  48751. 

  48752.    The bytecode interpreter is a stack-based machine; most instructions

  48753. pop their operands off the stack, perform some operation, and push the

  48754. result back on the stack for the next instruction to consume.  Each

  48755. element of the stack may contain either a integer or a floating point

  48756. value; these values are as many bits wide as the largest integer that

  48757. can be directly manipulated in the source language.  Stack elements

  48758. carry no record of their type; bytecode could push a value as an

  48759. integer, then pop it as a floating point value.  However, GDB will not

  48760. generate code which does this.  In C, one might define the type of a

  48761. stack element as follows:

  48762.      union agent_val {

  48763.        LONGEST l;

  48764.        DOUBLEST d;

  48765.      };

  48766. where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest

  48767. integer and floating point types on the machine.

  48768. 

  48769.    By the time the bytecode interpreter reaches the end of the

  48770. expression, the value of the expression should be the only value left on

  48771. the stack.  For tracing applications, 'trace' bytecodes in the

  48772. expression will have recorded the necessary data, and the value on the

  48773. stack may be discarded.  For other applications, like conditional

  48774. breakpoints, the value may be useful.

  48775. 

  48776.    Separate from the stack, the interpreter has two registers:

  48777. 'pc'

  48778.      The address of the next bytecode to execute.

  48779. 

  48780. 'start'

  48781.      The address of the start of the bytecode expression, necessary for

  48782.      interpreting the 'goto' and 'if_goto' instructions.

  48783. 

  48784. Neither of these registers is directly visible to the bytecode language

  48785. itself, but they are useful for defining the meanings of the bytecode

  48786. operations.

  48787. 

  48788.    There are no instructions to perform side effects on the running

  48789. program, or call the program's functions; we assume that these

  48790. expressions are only used for unobtrusive debugging, not for patching

  48791. the running code.

  48792. 

  48793.    Most bytecode instructions do not distinguish between the various

  48794. sizes of values, and operate on full-width values; the upper bits of the

  48795. values are simply ignored, since they do not usually make a difference

  48796. to the value computed.  The exceptions to this rule are:

  48797. 

  48798. memory reference instructions ('ref'N)

  48799.      There are distinct instructions to fetch different word sizes from

  48800.      memory.  Once on the stack, however, the values are treated as

  48801.      full-size integers.  They may need to be sign-extended; the 'ext'

  48802.      instruction exists for this purpose.

  48803. 

  48804. the sign-extension instruction ('ext' N)

  48805.      These clearly need to know which portion of their operand is to be

  48806.      extended to occupy the full length of the word.

  48807. 

  48808.    If the interpreter is unable to evaluate an expression completely for

  48809. some reason (a memory location is inaccessible, or a divisor is zero,

  48810. for example), we say that interpretation "terminates with an error".

  48811. This means that the problem is reported back to the interpreter's caller

  48812. in some helpful way.  In general, code using agent expressions should

  48813. assume that they may attempt to divide by zero, fetch arbitrary memory

  48814. locations, and misbehave in other ways.

  48815. 

  48816.    Even complicated C expressions compile to a few bytecode

  48817. instructions; for example, the expression 'x + y * z' would typically

  48818. produce code like the following, assuming that 'x' and 'y' live in

  48819. registers, and 'z' is a global variable holding a 32-bit 'int':

  48820.      reg 1

  48821.      reg 2

  48822.      const32 address of z

  48823.      ref32

  48824.      ext 32

  48825.      mul

  48826.      add

  48827.      end

  48828. 

  48829.    In detail, these mean:

  48830. 

  48831. 'reg 1'

  48832.      Push the value of register 1 (presumably holding 'x') onto the

  48833.      stack.

  48834. 

  48835. 'reg 2'

  48836.      Push the value of register 2 (holding 'y').

  48837. 

  48838. 'const32 address of z'

  48839.      Push the address of 'z' onto the stack.

  48840. 

  48841. 'ref32'

  48842.      Fetch a 32-bit word from the address at the top of the stack;

  48843.      replace the address on the stack with the value.  Thus, we replace

  48844.      the address of 'z' with 'z''s value.

  48845. 

  48846. 'ext 32'

  48847.      Sign-extend the value on the top of the stack from 32 bits to full

  48848.      length.  This is necessary because 'z' is a signed integer.

  48849. 

  48850. 'mul'

  48851.      Pop the top two numbers on the stack, multiply them, and push their

  48852.      product.  Now the top of the stack contains the value of the

  48853.      expression 'y * z'.

  48854. 

  48855. 'add'

  48856.      Pop the top two numbers, add them, and push the sum.  Now the top

  48857.      of the stack contains the value of 'x + y * z'.

  48858. 

  48859. 'end'

  48860.      Stop executing; the value left on the stack top is the value to be

  48861.      recorded.

  48862. 

  48863. 

  48864. File: gdb.info,  Node: Bytecode Descriptions,  Next: Using Agent Expressions,  Prev: General Bytecode Design,  Up: Agent Expressions

  48865. 

  48866. F.2 Bytecode Descriptions

  48867. =========================

  48868. 

  48869. Each bytecode description has the following form:

  48870. 

  48871. 'add' (0x02): A B => A+B

  48872. 

  48873.      Pop the top two stack items, A and B, as integers; push their sum,

  48874.      as an integer.

  48875. 

  48876.    In this example, 'add' is the name of the bytecode, and '(0x02)' is

  48877. the one-byte value used to encode the bytecode, in hexadecimal.  The

  48878. phrase "A B => A+B" shows the stack before and after the bytecode

  48879. executes.  Beforehand, the stack must contain at least two values, A and

  48880. B; since the top of the stack is to the right, B is on the top of the

  48881. stack, and A is underneath it.  After execution, the bytecode will have

  48882. popped A and B from the stack, and replaced them with a single value,

  48883. A+B.  There may be other values on the stack below those shown, but the

  48884. bytecode affects only those shown.

  48885. 

  48886.    Here is another example:

  48887. 

  48888. 'const8' (0x22) N: => N

  48889.      Push the 8-bit integer constant N on the stack, without sign

  48890.      extension.

  48891. 

  48892.    In this example, the bytecode 'const8' takes an operand N directly

  48893. from the bytecode stream; the operand follows the 'const8' bytecode

  48894. itself.  We write any such operands immediately after the name of the

  48895. bytecode, before the colon, and describe the exact encoding of the

  48896. operand in the bytecode stream in the body of the bytecode description.

  48897. 

  48898.    For the 'const8' bytecode, there are no stack items given before the

  48899. =>; this simply means that the bytecode consumes no values from the

  48900. stack.  If a bytecode consumes no values, or produces no values, the

  48901. list on either side of the => may be empty.

  48902. 

  48903.    If a value is written as A, B, or N, then the bytecode treats it as

  48904. an integer.  If a value is written is ADDR, then the bytecode treats it

  48905. as an address.

  48906. 

  48907.    We do not fully describe the floating point operations here; although

  48908. this design can be extended in a clean way to handle floating point

  48909. values, they are not of immediate interest to the customer, so we avoid

  48910. describing them, to save time.

  48911. 

  48912. 'float' (0x01): =>

  48913. 

  48914.      Prefix for floating-point bytecodes.  Not implemented yet.

  48915. 

  48916. 'add' (0x02): A B => A+B

  48917.      Pop two integers from the stack, and push their sum, as an integer.

  48918. 

  48919. 'sub' (0x03): A B => A-B

  48920.      Pop two integers from the stack, subtract the top value from the

  48921.      next-to-top value, and push the difference.

  48922. 

  48923. 'mul' (0x04): A B => A*B

  48924.      Pop two integers from the stack, multiply them, and push the

  48925.      product on the stack.  Note that, when one multiplies two N-bit

  48926.      numbers yielding another N-bit number, it is irrelevant whether the

  48927.      numbers are signed or not; the results are the same.

  48928. 

  48929. 'div_signed' (0x05): A B => A/B

  48930.      Pop two signed integers from the stack; divide the next-to-top

  48931.      value by the top value, and push the quotient.  If the divisor is

  48932.      zero, terminate with an error.

  48933. 

  48934. 'div_unsigned' (0x06): A B => A/B

  48935.      Pop two unsigned integers from the stack; divide the next-to-top

  48936.      value by the top value, and push the quotient.  If the divisor is

  48937.      zero, terminate with an error.

  48938. 

  48939. 'rem_signed' (0x07): A B => A MODULO B

  48940.      Pop two signed integers from the stack; divide the next-to-top

  48941.      value by the top value, and push the remainder.  If the divisor is

  48942.      zero, terminate with an error.

  48943. 

  48944. 'rem_unsigned' (0x08): A B => A MODULO B

  48945.      Pop two unsigned integers from the stack; divide the next-to-top

  48946.      value by the top value, and push the remainder.  If the divisor is

  48947.      zero, terminate with an error.

  48948. 

  48949. 'lsh' (0x09): A B => A<<B

  48950.      Pop two integers from the stack; let A be the next-to-top value,

  48951.      and B be the top value.  Shift A left by B bits, and push the

  48952.      result.

  48953. 

  48954. 'rsh_signed' (0x0a): A B => '(signed)'A>>B

  48955.      Pop two integers from the stack; let A be the next-to-top value,

  48956.      and B be the top value.  Shift A right by B bits, inserting copies

  48957.      of the top bit at the high end, and push the result.

  48958. 

  48959. 'rsh_unsigned' (0x0b): A B => A>>B

  48960.      Pop two integers from the stack; let A be the next-to-top value,

  48961.      and B be the top value.  Shift A right by B bits, inserting zero

  48962.      bits at the high end, and push the result.

  48963. 

  48964. 'log_not' (0x0e): A => !A

  48965.      Pop an integer from the stack; if it is zero, push the value one;

  48966.      otherwise, push the value zero.

  48967. 

  48968. 'bit_and' (0x0f): A B => A&B

  48969.      Pop two integers from the stack, and push their bitwise 'and'.

  48970. 

  48971. 'bit_or' (0x10): A B => A|B

  48972.      Pop two integers from the stack, and push their bitwise 'or'.

  48973. 

  48974. 'bit_xor' (0x11): A B => A^B

  48975.      Pop two integers from the stack, and push their bitwise

  48976.      exclusive-'or'.

  48977. 

  48978. 'bit_not' (0x12): A => ~A

  48979.      Pop an integer from the stack, and push its bitwise complement.

  48980. 

  48981. 'equal' (0x13): A B => A=B

  48982.      Pop two integers from the stack; if they are equal, push the value

  48983.      one; otherwise, push the value zero.

  48984. 

  48985. 'less_signed' (0x14): A B => A<B

  48986.      Pop two signed integers from the stack; if the next-to-top value is

  48987.      less than the top value, push the value one; otherwise, push the

  48988.      value zero.

  48989. 

  48990. 'less_unsigned' (0x15): A B => A<B

  48991.      Pop two unsigned integers from the stack; if the next-to-top value

  48992.      is less than the top value, push the value one; otherwise, push the

  48993.      value zero.

  48994. 

  48995. 'ext' (0x16) N: A => A, sign-extended from N bits

  48996.      Pop an unsigned value from the stack; treating it as an N-bit

  48997.      twos-complement value, extend it to full length.  This means that

  48998.      all bits to the left of bit N-1 (where the least significant bit is

  48999.      bit 0) are set to the value of bit N-1.  Note that N may be larger

  49000.      than or equal to the width of the stack elements of the bytecode

  49001.      engine; in this case, the bytecode should have no effect.

  49002. 

  49003.      The number of source bits to preserve, N, is encoded as a single

  49004.      byte unsigned integer following the 'ext' bytecode.

  49005. 

  49006. 'zero_ext' (0x2a) N: A => A, zero-extended from N bits

  49007.      Pop an unsigned value from the stack; zero all but the bottom N

  49008.      bits.

  49009. 

  49010.      The number of source bits to preserve, N, is encoded as a single

  49011.      byte unsigned integer following the 'zero_ext' bytecode.

  49012. 

  49013. 'ref8' (0x17): ADDR => A

  49014. 'ref16' (0x18): ADDR => A

  49015. 'ref32' (0x19): ADDR => A

  49016. 'ref64' (0x1a): ADDR => A

  49017.      Pop an address ADDR from the stack.  For bytecode 'ref'N, fetch an

  49018.      N-bit value from ADDR, using the natural target endianness.  Push

  49019.      the fetched value as an unsigned integer.

  49020. 

  49021.      Note that ADDR may not be aligned in any particular way; the 'refN'

  49022.      bytecodes should operate correctly for any address.

  49023. 

  49024.      If attempting to access memory at ADDR would cause a processor

  49025.      exception of some sort, terminate with an error.

  49026. 

  49027. 'ref_float' (0x1b): ADDR => D

  49028. 'ref_double' (0x1c): ADDR => D

  49029. 'ref_long_double' (0x1d): ADDR => D

  49030. 'l_to_d' (0x1e): A => D

  49031. 'd_to_l' (0x1f): D => A

  49032.      Not implemented yet.

  49033. 

  49034. 'dup' (0x28): A => A A

  49035.      Push another copy of the stack's top element.

  49036. 

  49037. 'swap' (0x2b): A B => B A

  49038.      Exchange the top two items on the stack.

  49039. 

  49040. 'pop' (0x29): A =>

  49041.      Discard the top value on the stack.

  49042. 

  49043. 'pick' (0x32) N: A ... B => A ... B A

  49044.      Duplicate an item from the stack and push it on the top of the

  49045.      stack.  N, a single byte, indicates the stack item to copy.  If N

  49046.      is zero, this is the same as 'dup'; if N is one, it copies the item

  49047.      under the top item, etc.  If N exceeds the number of items on the

  49048.      stack, terminate with an error.

  49049. 

  49050. 'rot' (0x33): A B C => C A B

  49051.      Rotate the top three items on the stack.  The top item (c) becomes

  49052.      the third item, the next-to-top item (b) becomes the top item and

  49053.      the third item (a) from the top becomes the next-to-top item.

  49054. 

  49055. 'if_goto' (0x20) OFFSET: A =>

  49056.      Pop an integer off the stack; if it is non-zero, branch to the

  49057.      given offset in the bytecode string.  Otherwise, continue to the

  49058.      next instruction in the bytecode stream.  In other words, if A is

  49059.      non-zero, set the 'pc' register to 'start' + OFFSET.  Thus, an

  49060.      offset of zero denotes the beginning of the expression.

  49061. 

  49062.      The OFFSET is stored as a sixteen-bit unsigned value, stored

  49063.      immediately following the 'if_goto' bytecode.  It is always stored

  49064.      most significant byte first, regardless of the target's normal

  49065.      endianness.  The offset is not guaranteed to fall at any particular

  49066.      alignment within the bytecode stream; thus, on machines where

  49067.      fetching a 16-bit on an unaligned address raises an exception, you

  49068.      should fetch the offset one byte at a time.

  49069. 

  49070. 'goto' (0x21) OFFSET: =>

  49071.      Branch unconditionally to OFFSET; in other words, set the 'pc'

  49072.      register to 'start' + OFFSET.

  49073. 

  49074.      The offset is stored in the same way as for the 'if_goto' bytecode.

  49075. 

  49076. 'const8' (0x22) N: => N

  49077. 'const16' (0x23) N: => N

  49078. 'const32' (0x24) N: => N

  49079. 'const64' (0x25) N: => N

  49080.      Push the integer constant N on the stack, without sign extension.

  49081.      To produce a small negative value, push a small twos-complement

  49082.      value, and then sign-extend it using the 'ext' bytecode.

  49083. 

  49084.      The constant N is stored in the appropriate number of bytes

  49085.      following the 'const'B bytecode.  The constant N is always stored

  49086.      most significant byte first, regardless of the target's normal

  49087.      endianness.  The constant is not guaranteed to fall at any

  49088.      particular alignment within the bytecode stream; thus, on machines

  49089.      where fetching a 16-bit on an unaligned address raises an

  49090.      exception, you should fetch N one byte at a time.

  49091. 

  49092. 'reg' (0x26) N: => A

  49093.      Push the value of register number N, without sign extension.  The

  49094.      registers are numbered following GDB's conventions.

  49095. 

  49096.      The register number N is encoded as a 16-bit unsigned integer

  49097.      immediately following the 'reg' bytecode.  It is always stored most

  49098.      significant byte first, regardless of the target's normal

  49099.      endianness.  The register number is not guaranteed to fall at any

  49100.      particular alignment within the bytecode stream; thus, on machines

  49101.      where fetching a 16-bit on an unaligned address raises an

  49102.      exception, you should fetch the register number one byte at a time.

  49103. 

  49104. 'getv' (0x2c) N: => V

  49105.      Push the value of trace state variable number N, without sign

  49106.      extension.

  49107. 

  49108.      The variable number N is encoded as a 16-bit unsigned integer

  49109.      immediately following the 'getv' bytecode.  It is always stored

  49110.      most significant byte first, regardless of the target's normal

  49111.      endianness.  The variable number is not guaranteed to fall at any

  49112.      particular alignment within the bytecode stream; thus, on machines

  49113.      where fetching a 16-bit on an unaligned address raises an

  49114.      exception, you should fetch the register number one byte at a time.

  49115. 

  49116. 'setv' (0x2d) N: V => V

  49117.      Set trace state variable number N to the value found on the top of

  49118.      the stack.  The stack is unchanged, so that the value is readily

  49119.      available if the assignment is part of a larger expression.  The

  49120.      handling of N is as described for 'getv'.

  49121. 

  49122. 'trace' (0x0c): ADDR SIZE =>

  49123.      Record the contents of the SIZE bytes at ADDR in a trace buffer,

  49124.      for later retrieval by GDB.

  49125. 

  49126. 'trace_quick' (0x0d) SIZE: ADDR => ADDR

  49127.      Record the contents of the SIZE bytes at ADDR in a trace buffer,

  49128.      for later retrieval by GDB. SIZE is a single byte unsigned integer

  49129.      following the 'trace' opcode.

  49130. 

  49131.      This bytecode is equivalent to the sequence 'dup const8 SIZE

  49132.      trace', but we provide it anyway to save space in bytecode strings.

  49133. 

  49134. 'trace16' (0x30) SIZE: ADDR => ADDR

  49135.      Identical to trace_quick, except that SIZE is a 16-bit big-endian

  49136.      unsigned integer, not a single byte.  This should probably have

  49137.      been named 'trace_quick16', for consistency.

  49138. 

  49139. 'tracev' (0x2e) N: => A

  49140.      Record the value of trace state variable number N in the trace

  49141.      buffer.  The handling of N is as described for 'getv'.

  49142. 

  49143. 'tracenz' (0x2f) ADDR SIZE =>

  49144.      Record the bytes at ADDR in a trace buffer, for later retrieval by

  49145.      GDB. Stop at either the first zero byte, or when SIZE bytes have

  49146.      been recorded, whichever occurs first.

  49147. 

  49148. 'printf' (0x34) NUMARGS STRING =>

  49149.      Do a formatted print, in the style of the C function 'printf').

  49150.      The value of NUMARGS is the number of arguments to expect on the

  49151.      stack, while STRING is the format string, prefixed with a two-byte

  49152.      length.  The last byte of the string must be zero, and is included

  49153.      in the length.  The format string includes escaped sequences just

  49154.      as it appears in C source, so for instance the format string

  49155.      '"\t%d\n"' is six characters long, and the output will consist of a

  49156.      tab character, a decimal number, and a newline.  At the top of the

  49157.      stack, above the values to be printed, this bytecode will pop a

  49158.      "function" and "channel".  If the function is nonzero, then the

  49159.      target may treat it as a function and call it, passing the channel

  49160.      as a first argument, as with the C function 'fprintf'.  If the

  49161.      function is zero, then the target may simply call a standard

  49162.      formatted print function of its choice.  In all, this bytecode pops

  49163.      2 + NUMARGS stack elements, and pushes nothing.

  49164. 

  49165. 'end' (0x27): =>

  49166.      Stop executing bytecode; the result should be the top element of

  49167.      the stack.  If the purpose of the expression was to compute an

  49168.      lvalue or a range of memory, then the next-to-top of the stack is

  49169.      the lvalue's address, and the top of the stack is the lvalue's

  49170.      size, in bytes.

  49171. 

  49172. 

  49173. File: gdb.info,  Node: Using Agent Expressions,  Next: Varying Target Capabilities,  Prev: Bytecode Descriptions,  Up: Agent Expressions

  49174. 

  49175. F.3 Using Agent Expressions

  49176. ===========================

  49177. 

  49178. Agent expressions can be used in several different ways by GDB, and the

  49179. debugger can generate different bytecode sequences as appropriate.

  49180. 

  49181.    One possibility is to do expression evaluation on the target rather

  49182. than the host, such as for the conditional of a conditional tracepoint.

  49183. In such a case, GDB compiles the source expression into a bytecode

  49184. sequence that simply gets values from registers or memory, does

  49185. arithmetic, and returns a result.

  49186. 

  49187.    Another way to use agent expressions is for tracepoint data

  49188. collection.  GDB generates a different bytecode sequence for collection;

  49189. in addition to bytecodes that do the calculation, GDB adds 'trace'

  49190. bytecodes to save the pieces of memory that were used.

  49191. 

  49192.    * The user selects trace points in the program's code at which GDB

  49193.      should collect data.

  49194. 

  49195.    * The user specifies expressions to evaluate at each trace point.

  49196.      These expressions may denote objects in memory, in which case those

  49197.      objects' contents are recorded as the program runs, or computed

  49198.      values, in which case the values themselves are recorded.

  49199. 

  49200.    * GDB transmits the tracepoints and their associated expressions to

  49201.      the GDB agent, running on the debugging target.

  49202. 

  49203.    * The agent arranges to be notified when a trace point is hit.

  49204. 

  49205.    * When execution on the target reaches a trace point, the agent

  49206.      evaluates the expressions associated with that trace point, and

  49207.      records the resulting values and memory ranges.

  49208. 

  49209.    * Later, when the user selects a given trace event and inspects the

  49210.      objects and expression values recorded, GDB talks to the agent to

  49211.      retrieve recorded data as necessary to meet the user's requests.

  49212.      If the user asks to see an object whose contents have not been

  49213.      recorded, GDB reports an error.

  49214. 

  49215. 

  49216. File: gdb.info,  Node: Varying Target Capabilities,  Next: Rationale,  Prev: Using Agent Expressions,  Up: Agent Expressions

  49217. 

  49218. F.4 Varying Target Capabilities

  49219. ===============================

  49220. 

  49221. Some targets don't support floating-point, and some would rather not

  49222. have to deal with 'long long' operations.  Also, different targets will

  49223. have different stack sizes, and different bytecode buffer lengths.

  49224. 

  49225.    Thus, GDB needs a way to ask the target about itself.  We haven't

  49226. worked out the details yet, but in general, GDB should be able to send

  49227. the target a packet asking it to describe itself.  The reply should be a

  49228. packet whose length is explicit, so we can add new information to the

  49229. packet in future revisions of the agent, without confusing old versions

  49230. of GDB, and it should contain a version number.  It should contain at

  49231. least the following information:

  49232. 

  49233.    * whether floating point is supported

  49234. 

  49235.    * whether 'long long' is supported

  49236. 

  49237.    * maximum acceptable size of bytecode stack

  49238. 

  49239.    * maximum acceptable length of bytecode expressions

  49240. 

  49241.    * which registers are actually available for collection

  49242. 

  49243.    * whether the target supports disabled tracepoints

  49244. 

  49245. 

  49246. File: gdb.info,  Node: Rationale,  Prev: Varying Target Capabilities,  Up: Agent Expressions

  49247. 

  49248. F.5 Rationale

  49249. =============

  49250. 

  49251. Some of the design decisions apparent above are arguable.

  49252. 

  49253. What about stack overflow/underflow?

  49254.      GDB should be able to query the target to discover its stack size.

  49255.      Given that information, GDB can determine at translation time

  49256.      whether a given expression will overflow the stack.  But this spec

  49257.      isn't about what kinds of error-checking GDB ought to do.

  49258. 

  49259. Why are you doing everything in LONGEST?

  49260. 

  49261.      Speed isn't important, but agent code size is; using LONGEST brings

  49262.      in a bunch of support code to do things like division, etc.  So

  49263.      this is a serious concern.

  49264. 

  49265.      First, note that you don't need different bytecodes for different

  49266.      operand sizes.  You can generate code without _knowing_ how big the

  49267.      stack elements actually are on the target.  If the target only

  49268.      supports 32-bit ints, and you don't send any 64-bit bytecodes,

  49269.      everything just works.  The observation here is that the MIPS and

  49270.      the Alpha have only fixed-size registers, and you can still get C's

  49271.      semantics even though most instructions only operate on full-sized

  49272.      words.  You just need to make sure everything is properly

  49273.      sign-extended at the right times.  So there is no need for 32- and

  49274.      64-bit variants of the bytecodes.  Just implement everything using

  49275.      the largest size you support.

  49276. 

  49277.      GDB should certainly check to see what sizes the target supports,

  49278.      so the user can get an error earlier, rather than later.  But this

  49279.      information is not necessary for correctness.

  49280. 

  49281. Why don't you have '>' or '<=' operators?

  49282.      I want to keep the interpreter small, and we don't need them.  We

  49283.      can combine the 'less_' opcodes with 'log_not', and swap the order

  49284.      of the operands, yielding all four asymmetrical comparison

  49285.      operators.  For example, '(x <= y)' is '! (x > y)', which is '! (y

  49286.      < x)'.

  49287. 

  49288. Why do you have 'log_not'?

  49289. Why do you have 'ext'?

  49290. Why do you have 'zero_ext'?

  49291.      These are all easily synthesized from other instructions, but I

  49292.      expect them to be used frequently, and they're simple, so I include

  49293.      them to keep bytecode strings short.

  49294. 

  49295.      'log_not' is equivalent to 'const8 0 equal'; it's used in half the

  49296.      relational operators.

  49297. 

  49298.      'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed',

  49299.      where S is the size of the stack elements; it follows 'refM' and

  49300.      REG bytecodes when the value should be signed.  See the next

  49301.      bulleted item.

  49302. 

  49303.      'zero_ext N' is equivalent to 'constM MASK log_and'; it's used

  49304.      whenever we push the value of a register, because we can't assume

  49305.      the upper bits of the register aren't garbage.

  49306. 

  49307. Why not have sign-extending variants of the 'ref' operators?

  49308.      Because that would double the number of 'ref' operators, and we

  49309.      need the 'ext' bytecode anyway for accessing bitfields.

  49310. 

  49311. Why not have constant-address variants of the 'ref' operators?

  49312.      Because that would double the number of 'ref' operators again, and

  49313.      'const32 ADDRESS ref32' is only one byte longer.

  49314. 

  49315. Why do the 'refN' operators have to support unaligned fetches?

  49316.      GDB will generate bytecode that fetches multi-byte values at

  49317.      unaligned addresses whenever the executable's debugging information

  49318.      tells it to.  Furthermore, GDB does not know the value the pointer

  49319.      will have when GDB generates the bytecode, so it cannot determine

  49320.      whether a particular fetch will be aligned or not.

  49321. 

  49322.      In particular, structure bitfields may be several bytes long, but

  49323.      follow no alignment rules; members of packed structures are not

  49324.      necessarily aligned either.

  49325. 

  49326.      In general, there are many cases where unaligned references occur

  49327.      in correct C code, either at the programmer's explicit request, or

  49328.      at the compiler's discretion.  Thus, it is simpler to make the GDB

  49329.      agent bytecodes work correctly in all circumstances than to make

  49330.      GDB guess in each case whether the compiler did the usual thing.

  49331. 

  49332. Why are there no side-effecting operators?

  49333.      Because our current client doesn't want them?  That's a cheap

  49334.      answer.  I think the real answer is that I'm afraid of implementing

  49335.      function calls.  We should re-visit this issue after the present

  49336.      contract is delivered.

  49337. 

  49338. Why aren't the 'goto' ops PC-relative?

  49339.      The interpreter has the base address around anyway for PC bounds

  49340.      checking, and it seemed simpler.

  49341. 

  49342. Why is there only one offset size for the 'goto' ops?

  49343.      Offsets are currently sixteen bits.  I'm not happy with this

  49344.      situation either:

  49345. 

  49346.      Suppose we have multiple branch ops with different offset sizes.

  49347.      As I generate code left-to-right, all my jumps are forward jumps

  49348.      (there are no loops in expressions), so I never know the target

  49349.      when I emit the jump opcode.  Thus, I have to either always assume

  49350.      the largest offset size, or do jump relaxation on the code after I

  49351.      generate it, which seems like a big waste of time.

  49352. 

  49353.      I can imagine a reasonable expression being longer than 256 bytes.

  49354.      I can't imagine one being longer than 64k.  Thus, we need 16-bit

  49355.      offsets.  This kind of reasoning is so bogus, but relaxation is

  49356.      pathetic.

  49357. 

  49358.      The other approach would be to generate code right-to-left.  Then

  49359.      I'd always know my offset size.  That might be fun.

  49360. 

  49361. Where is the function call bytecode?

  49362. 

  49363.      When we add side-effects, we should add this.

  49364. 

  49365. Why does the 'reg' bytecode take a 16-bit register number?

  49366. 

  49367.      Intel's IA-64 architecture has 128 general-purpose registers, and

  49368.      128 floating-point registers, and I'm sure it has some random

  49369.      control registers.

  49370. 

  49371. Why do we need 'trace' and 'trace_quick'?

  49372.      Because GDB needs to record all the memory contents and registers

  49373.      an expression touches.  If the user wants to evaluate an expression

  49374.      'x->y->z', the agent must record the values of 'x' and 'x->y' as

  49375.      well as the value of 'x->y->z'.

  49376. 

  49377. Don't the 'trace' bytecodes make the interpreter less general?

  49378.      They do mean that the interpreter contains special-purpose code,

  49379.      but that doesn't mean the interpreter can only be used for that

  49380.      purpose.  If an expression doesn't use the 'trace' bytecodes, they

  49381.      don't get in its way.

  49382. 

  49383. Why doesn't 'trace_quick' consume its arguments the way everything else does?

  49384.      In general, you do want your operators to consume their arguments;

  49385.      it's consistent, and generally reduces the amount of stack

  49386.      rearrangement necessary.  However, 'trace_quick' is a kludge to

  49387.      save space; it only exists so we needn't write 'dup const8 SIZE

  49388.      trace' before every memory reference.  Therefore, it's okay for it

  49389.      not to consume its arguments; it's meant for a specific context in

  49390.      which we know exactly what it should do with the stack.  If we're

  49391.      going to have a kludge, it should be an effective kludge.

  49392. 

  49393. Why does 'trace16' exist?

  49394.      That opcode was added by the customer that contracted Cygnus for

  49395.      the data tracing work.  I personally think it is unnecessary;

  49396.      objects that large will be quite rare, so it is okay to use 'dup

  49397.      const16 SIZE trace' in those cases.

  49398. 

  49399.      Whatever we decide to do with 'trace16', we should at least leave

  49400.      opcode 0x30 reserved, to remain compatible with the customer who

  49401.      added it.

  49402. 

  49403. 

  49404. File: gdb.info,  Node: Target Descriptions,  Next: Operating System Information,  Prev: Agent Expressions,  Up: Top

  49405. 

  49406. Appendix G Target Descriptions

  49407. ******************************

  49408. 

  49409. One of the challenges of using GDB to debug embedded systems is that

  49410. there are so many minor variants of each processor architecture in use.

  49411. It is common practice for vendors to start with a standard processor

  49412. core -- ARM, PowerPC, or MIPS, for example -- and then make changes to

  49413. adapt it to a particular market niche.  Some architectures have hundreds

  49414. of variants, available from dozens of vendors.  This leads to a number

  49415. of problems:

  49416. 

  49417.    * With so many different customized processors, it is difficult for

  49418.      the GDB maintainers to keep up with the changes.

  49419.    * Since individual variants may have short lifetimes or limited

  49420.      audiences, it may not be worthwhile to carry information about

  49421.      every variant in the GDB source tree.

  49422.    * When GDB does support the architecture of the embedded system at

  49423.      hand, the task of finding the correct architecture name to give the

  49424.      'set architecture' command can be error-prone.

  49425. 

  49426.    To address these problems, the GDB remote protocol allows a target

  49427. system to not only identify itself to GDB, but to actually describe its

  49428. own features.  This lets GDB support processor variants it has never

  49429. seen before -- to the extent that the descriptions are accurate, and

  49430. that GDB understands them.

  49431. 

  49432.    GDB must be linked with the Expat library to support XML target

  49433. descriptions.  *Note Expat::.

  49434. 

  49435. * Menu:

  49436. 

  49437. * Retrieving Descriptions::         How descriptions are fetched from a target.

  49438. * Target Description Format::       The contents of a target description.

  49439. * Predefined Target Types::         Standard types available for target

  49440.                                     descriptions.

  49441. * Enum Target Types::               How to define enum target types.

  49442. * Standard Target Features::        Features GDB knows about.

  49443. 

  49444. 

  49445. File: gdb.info,  Node: Retrieving Descriptions,  Next: Target Description Format,  Up: Target Descriptions

  49446. 

  49447. G.1 Retrieving Descriptions

  49448. ===========================

  49449. 

  49450. Target descriptions can be read from the target automatically, or

  49451. specified by the user manually.  The default behavior is to read the

  49452. description from the target.  GDB retrieves it via the remote protocol

  49453. using 'qXfer' requests (*note qXfer: General Query Packets.).  The ANNEX

  49454. in the 'qXfer' packet will be 'target.xml'.  The contents of the

  49455. 'target.xml' annex are an XML document, of the form described in *note

  49456. Target Description Format::.

  49457. 

  49458.    Alternatively, you can specify a file to read for the target

  49459. description.  If a file is set, the target will not be queried.  The

  49460. commands to specify a file are:

  49461. 

  49462. 'set tdesc filename PATH'

  49463.      Read the target description from PATH.

  49464. 

  49465. 'unset tdesc filename'

  49466.      Do not read the XML target description from a file.  GDB will use

  49467.      the description supplied by the current target.

  49468. 

  49469. 'show tdesc filename'

  49470.      Show the filename to read for a target description, if any.

  49471. 

  49472. 

  49473. File: gdb.info,  Node: Target Description Format,  Next: Predefined Target Types,  Prev: Retrieving Descriptions,  Up: Target Descriptions

  49474. 

  49475. G.2 Target Description Format

  49476. =============================

  49477. 

  49478. A target description annex is an XML (http://www.w3.org/XML/) document

  49479. which complies with the Document Type Definition provided in the GDB

  49480. sources in 'gdb/features/gdb-target.dtd'.  This means you can use

  49481. generally available tools like 'xmllint' to check that your feature

  49482. descriptions are well-formed and valid.  However, to help people

  49483. unfamiliar with XML write descriptions for their targets, we also

  49484. describe the grammar here.

  49485. 

  49486.    Target descriptions can identify the architecture of the remote

  49487. target and (for some architectures) provide information about custom

  49488. register sets.  They can also identify the OS ABI of the remote target.

  49489. GDB can use this information to autoconfigure for your target, or to

  49490. warn you if you connect to an unsupported target.

  49491. 

  49492.    Here is a simple target description:

  49493. 

  49494.      <target version="1.0">

  49495.        <architecture>i386:x86-64</architecture>

  49496.      </target>

  49497. 

  49498. This minimal description only says that the target uses the x86-64

  49499. architecture.

  49500. 

  49501.    A target description has the following overall form, with [ ] marking

  49502. optional elements and ... marking repeatable elements.  The elements are

  49503. explained further below.

  49504. 

  49505.      <?xml version="1.0"?>

  49506.      <!DOCTYPE target SYSTEM "gdb-target.dtd">

  49507.      <target version="1.0">

  49508.        [ARCHITECTURE]

  49509.        [OSABI]

  49510.        [COMPATIBLE]

  49511.        [FEATURE...]

  49512.      </target>

  49513. 

  49514. The description is generally insensitive to whitespace and line breaks,

  49515. under the usual common-sense rules.  The XML version declaration and

  49516. document type declaration can generally be omitted (GDB does not require

  49517. them), but specifying them may be useful for XML validation tools.  The

  49518. 'version' attribute for '<target>' may also be omitted, but we recommend

  49519. including it; if future versions of GDB use an incompatible revision of

  49520. 'gdb-target.dtd', they will detect and report the version mismatch.

  49521. 

  49522. G.2.1 Inclusion

  49523. ---------------

  49524. 

  49525. It can sometimes be valuable to split a target description up into

  49526. several different annexes, either for organizational purposes, or to

  49527. share files between different possible target descriptions.  You can

  49528. divide a description into multiple files by replacing any element of the

  49529. target description with an inclusion directive of the form:

  49530. 

  49531.      <xi:include href="DOCUMENT"/>

  49532. 

  49533. When GDB encounters an element of this form, it will retrieve the named

  49534. XML DOCUMENT, and replace the inclusion directive with the contents of

  49535. that document.  If the current description was read using 'qXfer', then

  49536. so will be the included document; DOCUMENT will be interpreted as the

  49537. name of an annex.  If the current description was read from a file, GDB

  49538. will look for DOCUMENT as a file in the same directory where it found

  49539. the original description.

  49540. 

  49541. G.2.2 Architecture

  49542. ------------------

  49543. 

  49544. An '<architecture>' element has this form:

  49545. 

  49546.        <architecture>ARCH</architecture>

  49547. 

  49548.    ARCH is one of the architectures from the set accepted by 'set

  49549. architecture' (*note Specifying a Debugging Target: Targets.).

  49550. 

  49551. G.2.3 OS ABI

  49552. ------------

  49553. 

  49554. This optional field was introduced in GDB version 7.0.  Previous

  49555. versions of GDB ignore it.

  49556. 

  49557.    An '<osabi>' element has this form:

  49558. 

  49559.        <osabi>ABI-NAME</osabi>

  49560. 

  49561.    ABI-NAME is an OS ABI name from the same selection accepted by

  49562. 'set osabi' (*note Configuring the Current ABI: ABI.).

  49563. 

  49564. G.2.4 Compatible Architecture

  49565. -----------------------------

  49566. 

  49567. This optional field was introduced in GDB version 7.0.  Previous

  49568. versions of GDB ignore it.

  49569. 

  49570.    A '<compatible>' element has this form:

  49571. 

  49572.        <compatible>ARCH</compatible>

  49573. 

  49574.    ARCH is one of the architectures from the set accepted by 'set

  49575. architecture' (*note Specifying a Debugging Target: Targets.).

  49576. 

  49577.    A '<compatible>' element is used to specify that the target is able

  49578. to run binaries in some other than the main target architecture given by

  49579. the '<architecture>' element.  For example, on the Cell Broadband

  49580. Engine, the main architecture is 'powerpc:common' or 'powerpc:common64',

  49581. but the system is able to run binaries in the 'spu' architecture as

  49582. well.  The way to describe this capability with '<compatible>' is as

  49583. follows:

  49584. 

  49585.        <architecture>powerpc:common</architecture>

  49586.        <compatible>spu</compatible>

  49587. 

  49588. G.2.5 Features

  49589. --------------

  49590. 

  49591. Each '<feature>' describes some logical portion of the target system.

  49592. Features are currently used to describe available CPU registers and the

  49593. types of their contents.  A '<feature>' element has this form:

  49594. 

  49595.      <feature name="NAME">

  49596.        [TYPE...]

  49597.        REG...

  49598.      </feature>

  49599. 

  49600. Each feature's name should be unique within the description.  The name

  49601. of a feature does not matter unless GDB has some special knowledge of

  49602. the contents of that feature; if it does, the feature should have its

  49603. standard name.  *Note Standard Target Features::.

  49604. 

  49605. G.2.6 Types

  49606. -----------

  49607. 

  49608. Any register's value is a collection of bits which GDB must interpret.

  49609. The default interpretation is a two's complement integer, but other

  49610. types can be requested by name in the register description.  Some

  49611. predefined types are provided by GDB (*note Predefined Target Types::),

  49612. and the description can define additional composite and enum types.

  49613. 

  49614.    Each type element must have an 'id' attribute, which gives a unique

  49615. (within the containing '<feature>') name to the type.  Types must be

  49616. defined before they are used.

  49617. 

  49618.    Some targets offer vector registers, which can be treated as arrays

  49619. of scalar elements.  These types are written as '<vector>' elements,

  49620. specifying the array element type, TYPE, and the number of elements,

  49621. COUNT:

  49622. 

  49623.      <vector id="ID" type="TYPE" count="COUNT"/>

  49624. 

  49625.    If a register's value is usefully viewed in multiple ways, define it

  49626. with a union type containing the useful representations.  The '<union>'

  49627. element contains one or more '<field>' elements, each of which has a

  49628. NAME and a TYPE:

  49629. 

  49630.      <union id="ID">

  49631.        <field name="NAME" type="TYPE"/>

  49632.        ...

  49633.      </union>

  49634. 

  49635.    If a register's value is composed from several separate values,

  49636. define it with either a structure type or a flags type.  A flags type

  49637. may only contain bitfields.  A structure type may either contain only

  49638. bitfields or contain no bitfields.  If the value contains only

  49639. bitfields, its total size in bytes must be specified.

  49640. 

  49641.    Non-bitfield values have a NAME and TYPE.

  49642. 

  49643.      <struct id="ID">

  49644.        <field name="NAME" type="TYPE"/>

  49645.        ...

  49646.      </struct>

  49647. 

  49648.    Both NAME and TYPE values are required.  No implicit padding is

  49649. added.

  49650. 

  49651.    Bitfield values have a NAME, START, END and TYPE.

  49652. 

  49653.      <struct id="ID" size="SIZE">

  49654.        <field name="NAME" start="START" end="END" type="TYPE"/>

  49655.        ...

  49656.      </struct>

  49657. 

  49658.      <flags id="ID" size="SIZE">

  49659.        <field name="NAME" start="START" end="END" type="TYPE"/>

  49660.        ...

  49661.      </flags>

  49662. 

  49663.    The NAME value is required.  Bitfield values may be named with the

  49664. empty string, '""', in which case the field is "filler" and its value is

  49665. not printed.  Not all bits need to be specified, so "filler" fields are

  49666. optional.

  49667. 

  49668.    The START and END values are required, and TYPE is optional.  The

  49669. field's START must be less than or equal to its END, and zero represents

  49670. the least significant bit.

  49671. 

  49672.    The default value of TYPE is 'bool' for single bit fields, and an

  49673. unsigned integer otherwise.

  49674. 

  49675.    Which to choose?  Structures or flags?

  49676. 

  49677.    Registers defined with 'flags' have these advantages over defining

  49678. them with 'struct':

  49679. 

  49680.    * Arithmetic may be performed on them as if they were integers.

  49681.    * They are printed in a more readable fashion.

  49682. 

  49683.    Registers defined with 'struct' have one advantage over defining them

  49684. with 'flags':

  49685. 

  49686.    * One can fetch individual fields like in 'C'.

  49687. 

  49688.           (gdb) print $my_struct_reg.field3

  49689.           $1 = 42

  49690. 

  49691. G.2.7 Registers

  49692. ---------------

  49693. 

  49694. Each register is represented as an element with this form:

  49695. 

  49696.      <reg name="NAME"

  49697.           bitsize="SIZE"

  49698.           [regnum="NUM"]

  49699.           [save-restore="SAVE-RESTORE"]

  49700.           [type="TYPE"]

  49701.           [group="GROUP"]/>

  49702. 

  49703. The components are as follows:

  49704. 

  49705. NAME

  49706.      The register's name; it must be unique within the target

  49707.      description.

  49708. 

  49709. BITSIZE

  49710.      The register's size, in bits.

  49711. 

  49712. REGNUM

  49713.      The register's number.  If omitted, a register's number is one

  49714.      greater than that of the previous register (either in the current

  49715.      feature or in a preceding feature); the first register in the

  49716.      target description defaults to zero.  This register number is used

  49717.      to read or write the register; e.g. it is used in the remote 'p'

  49718.      and 'P' packets, and registers appear in the 'g' and 'G' packets in

  49719.      order of increasing register number.

  49720. 

  49721. SAVE-RESTORE

  49722.      Whether the register should be preserved across inferior function

  49723.      calls; this must be either 'yes' or 'no'.  The default is 'yes',

  49724.      which is appropriate for most registers except for some system

  49725.      control registers; this is not related to the target's ABI.

  49726. 

  49727. TYPE

  49728.      The type of the register.  It may be a predefined type, a type

  49729.      defined in the current feature, or one of the special types 'int'

  49730.      and 'float'.  'int' is an integer type of the correct size for

  49731.      BITSIZE, and 'float' is a floating point type (in the

  49732.      architecture's normal floating point format) of the correct size

  49733.      for BITSIZE.  The default is 'int'.

  49734. 

  49735. GROUP

  49736.      The register group to which this register belongs.  It can be one

  49737.      of the standard register groups 'general', 'float', 'vector' or an

  49738.      arbitrary string.  Group names should be limited to alphanumeric

  49739.      characters.  If a group name is made up of multiple words the words

  49740.      may be separated by hyphens; e.g. 'special-group' or

  49741.      'ultra-special-group'.  If no GROUP is specified, GDB will not

  49742.      display the register in 'info registers'.

  49743. 

  49744. 

  49745. File: gdb.info,  Node: Predefined Target Types,  Next: Enum Target Types,  Prev: Target Description Format,  Up: Target Descriptions

  49746. 

  49747. G.3 Predefined Target Types

  49748. ===========================

  49749. 

  49750. Type definitions in the self-description can build up composite types

  49751. from basic building blocks, but can not define fundamental types.

  49752. Instead, standard identifiers are provided by GDB for the fundamental

  49753. types.  The currently supported types are:

  49754. 

  49755. 'bool'

  49756.      Boolean type, occupying a single bit.

  49757. 

  49758. 'int8'

  49759. 'int16'

  49760. 'int24'

  49761. 'int32'

  49762. 'int64'

  49763. 'int128'

  49764.      Signed integer types holding the specified number of bits.

  49765. 

  49766. 'uint8'

  49767. 'uint16'

  49768. 'uint24'

  49769. 'uint32'

  49770. 'uint64'

  49771. 'uint128'

  49772.      Unsigned integer types holding the specified number of bits.

  49773. 

  49774. 'code_ptr'

  49775. 'data_ptr'

  49776.      Pointers to unspecified code and data.  The program counter and any

  49777.      dedicated return address register may be marked as code pointers;

  49778.      printing a code pointer converts it into a symbolic address.  The

  49779.      stack pointer and any dedicated address registers may be marked as

  49780.      data pointers.

  49781. 

  49782. 'ieee_single'

  49783.      Single precision IEEE floating point.

  49784. 

  49785. 'ieee_double'

  49786.      Double precision IEEE floating point.

  49787. 

  49788. 'arm_fpa_ext'

  49789.      The 12-byte extended precision format used by ARM FPA registers.

  49790. 

  49791. 'i387_ext'

  49792.      The 10-byte extended precision format used by x87 registers.

  49793. 

  49794. 'i386_eflags'

  49795.      32bit EFLAGS register used by x86.

  49796. 

  49797. 'i386_mxcsr'

  49798.      32bit MXCSR register used by x86.

  49799. 

  49800. 

  49801. File: gdb.info,  Node: Enum Target Types,  Next: Standard Target Features,  Prev: Predefined Target Types,  Up: Target Descriptions

  49802. 

  49803. G.4 Enum Target Types

  49804. =====================

  49805. 

  49806. Enum target types are useful in 'struct' and 'flags' register

  49807. descriptions.  *Note Target Description Format::.

  49808. 

  49809.    Enum types have a name, size and a list of name/value pairs.

  49810. 

  49811.      <enum id="ID" size="SIZE">

  49812.        <evalue name="NAME" value="VALUE"/>

  49813.        ...

  49814.      </enum>

  49815. 

  49816.    Enums must be defined before they are used.

  49817. 

  49818.      <enum id="levels_type" size="4">

  49819.        <evalue name="low" value="0"/>

  49820.        <evalue name="high" value="1"/>

  49821.      </enum>

  49822.      <flags id="flags_type" size="4">

  49823.        <field name="X" start="0"/>

  49824.        <field name="LEVEL" start="1" end="1" type="levels_type"/>

  49825.      </flags>

  49826.      <reg name="flags" bitsize="32" type="flags_type"/>

  49827. 

  49828.    Given that description, a value of 3 for the 'flags' register would

  49829. be printed as:

  49830. 

  49831.      (gdb) info register flags

  49832.      flags 0x3 [ X LEVEL=high ]

  49833. 

  49834. 

  49835. File: gdb.info,  Node: Standard Target Features,  Prev: Enum Target Types,  Up: Target Descriptions

  49836. 

  49837. G.5 Standard Target Features

  49838. ============================

  49839. 

  49840. A target description must contain either no registers or all the

  49841. target's registers.  If the description contains no registers, then GDB

  49842. will assume a default register layout, selected based on the

  49843. architecture.  If the description contains any registers, the default

  49844. layout will not be used; the standard registers must be described in the

  49845. target description, in such a way that GDB can recognize them.

  49846. 

  49847.    This is accomplished by giving specific names to feature elements

  49848. which contain standard registers.  GDB will look for features with those

  49849. names and verify that they contain the expected registers; if any known

  49850. feature is missing required registers, or if any required feature is

  49851. missing, GDB will reject the target description.  You can add additional

  49852. registers to any of the standard features -- GDB will display them just

  49853. as if they were added to an unrecognized feature.

  49854. 

  49855.    This section lists the known features and their expected contents.

  49856. Sample XML documents for these features are included in the GDB source

  49857. tree, in the directory 'gdb/features'.

  49858. 

  49859.    Names recognized by GDB should include the name of the company or

  49860. organization which selected the name, and the overall architecture to

  49861. which the feature applies; so e.g. the feature containing ARM core

  49862. registers is named 'org.gnu.gdb.arm.core'.

  49863. 

  49864.    The names of registers are not case sensitive for the purpose of

  49865. recognizing standard features, but GDB will only display registers using

  49866. the capitalization used in the description.

  49867. 

  49868. * Menu:

  49869. 

  49870. * AArch64 Features::

  49871. * ARC Features::

  49872. * ARM Features::

  49873. * i386 Features::

  49874. * MicroBlaze Features::

  49875. * MIPS Features::

  49876. * M68K Features::

  49877. * NDS32 Features::

  49878. * Nios II Features::

  49879. * OpenRISC 1000 Features::

  49880. * PowerPC Features::

  49881. * RISC-V Features::

  49882. * RX Features::

  49883. * S/390 and System z Features::

  49884. * Sparc Features::

  49885. * TIC6x Features::

  49886. 

  49887. 

  49888. File: gdb.info,  Node: AArch64 Features,  Next: ARC Features,  Up: Standard Target Features

  49889. 

  49890. G.5.1 AArch64 Features

  49891. ----------------------

  49892. 

  49893. The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets.

  49894. It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'.

  49895. 

  49896.    The 'org.gnu.gdb.aarch64.fpu' feature is optional.  If present, it

  49897. should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'.

  49898. 

  49899.    The 'org.gnu.gdb.aarch64.sve' feature is optional.  If present, it

  49900. should contain registers 'z0' through 'z31', 'p0' through 'p15', 'ffr'

  49901. and 'vg'.

  49902. 

  49903.    The 'org.gnu.gdb.aarch64.pauth' feature is optional.  If present, it

  49904. should contain registers 'pauth_dmask' and 'pauth_cmask'.

  49905. 

  49906. 

  49907. File: gdb.info,  Node: ARC Features,  Next: ARM Features,  Prev: AArch64 Features,  Up: Standard Target Features

  49908. 

  49909. G.5.2 ARC Features

  49910. ------------------

  49911. 

  49912. ARC processors are so configurable that even core registers and their

  49913. numbers are not predetermined completely.  Moreover, _flags_ and _PC_

  49914. registers, which are important to GDB, are not "core" registers in ARC.

  49915. Therefore, there are two features that their presence is mandatory:

  49916. 'org.gnu.gdb.arc.core' and 'org.gnu.gdb.arc.aux'.

  49917. 

  49918.    The 'org.gnu.gdb.arc.core' feature is required for all targets.  It

  49919. must contain registers:

  49920. 

  49921.    - 'r0' through 'r25' for normal register file targets.

  49922.    - 'r0' through 'r3', and 'r10' through 'r15' for reduced register

  49923.      file targets.

  49924.    - 'gp', 'fp', 'sp', 'r30'(1), 'blink', 'lp_count', 'pcl'.

  49925. 

  49926.    In case of an ARCompact target (ARCv1 ISA), the

  49927. 'org.gnu.gdb.arc.core' feature may contain registers 'ilink1' and

  49928. 'ilink2'.  While in case of ARC EM and ARC HS targets (ARCv2 ISA),

  49929. register 'ilink' may be present.  The difference between ARCv1 and ARCv2

  49930. is the naming of registers _29th_ and _30th_.  They are called 'ilink1'

  49931. and 'ilink2' for ARCv1 and are optional.  For ARCv2, they are called

  49932. 'ilink' and 'r30' and only 'ilink' is optional.  The optionality of

  49933. 'ilink*' registers is because of their inaccessibility during user space

  49934. debugging sessions.

  49935. 

  49936.    Extension core registers 'r32' through 'r59' are optional and their

  49937. existence depends on the configuration.  When debugging GNU/Linux

  49938. applications, i.e. user space debugging, these core registers are not

  49939. available.

  49940. 

  49941.    The 'org.gnu.gdb.arc.aux' feature is required for all ARC targets.

  49942. Here is the list of registers pertinent to this feature:

  49943. 

  49944.    - mandatory: 'pc' and 'status32'.

  49945.    - optional: 'lp_start', 'lp_end', and 'bta'.

  49946. 

  49947.    ---------- Footnotes ----------

  49948. 

  49949.    (1) Not necessary for ARCv1.

  49950. 

  49951. 

  49952. File: gdb.info,  Node: ARM Features,  Next: i386 Features,  Prev: ARC Features,  Up: Standard Target Features

  49953. 

  49954. G.5.3 ARM Features

  49955. ------------------

  49956. 

  49957. The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM

  49958. targets.  It should contain registers 'r0' through 'r13', 'sp', 'lr',

  49959. 'pc', and 'cpsr'.

  49960. 

  49961.    For M-profile targets (e.g.  Cortex-M3), the 'org.gnu.gdb.arm.core'

  49962. feature is replaced by 'org.gnu.gdb.arm.m-profile'.  It should contain

  49963. registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'.

  49964. 

  49965.    The 'org.gnu.gdb.arm.fpa' feature is optional.  If present, it should

  49966. contain registers 'f0' through 'f7' and 'fps'.

  49967. 

  49968.    The 'org.gnu.gdb.xscale.iwmmxt' feature is optional.  If present, it

  49969. should contain at least registers 'wR0' through 'wR15' and 'wCGR0'

  49970. through 'wCGR3'.  The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are

  49971. optional.

  49972. 

  49973.    The 'org.gnu.gdb.arm.vfp' feature is optional.  If present, it should

  49974. contain at least registers 'd0' through 'd15'.  If they are present,

  49975. 'd16' through 'd31' should also be included.  GDB will synthesize the

  49976. single-precision registers from halves of the double-precision

  49977. registers.

  49978. 

  49979.    The 'org.gnu.gdb.arm.neon' feature is optional.  It does not need to

  49980. contain registers; it instructs GDB to display the VFP double-precision

  49981. registers as vectors and to synthesize the quad-precision registers from

  49982. pairs of double-precision registers.  If this feature is present,

  49983. 'org.gnu.gdb.arm.vfp' must also be present and include 32

  49984. double-precision registers.

  49985. 

  49986. 

  49987. File: gdb.info,  Node: i386 Features,  Next: MicroBlaze Features,  Prev: ARM Features,  Up: Standard Target Features

  49988. 

  49989. G.5.4 i386 Features

  49990. -------------------

  49991. 

  49992. The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.

  49993. It should describe the following registers:

  49994. 

  49995.    - 'eax' through 'edi' plus 'eip' for i386

  49996.    - 'rax' through 'r15' plus 'rip' for amd64

  49997.    - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs'

  49998.    - 'st0' through 'st7'

  49999.    - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and

  50000.      'fop'

  50001. 

  50002.    The register sets may be different, depending on the target.

  50003. 

  50004.    The 'org.gnu.gdb.i386.sse' feature is optional.  It should describe

  50005. registers:

  50006. 

  50007.    - 'xmm0' through 'xmm7' for i386

  50008.    - 'xmm0' through 'xmm15' for amd64

  50009.    - 'mxcsr'

  50010. 

  50011.    The 'org.gnu.gdb.i386.avx' feature is optional and requires the

  50012. 'org.gnu.gdb.i386.sse' feature.  It should describe the upper 128 bits

  50013. of YMM registers:

  50014. 

  50015.    - 'ymm0h' through 'ymm7h' for i386

  50016.    - 'ymm0h' through 'ymm15h' for amd64

  50017. 

  50018.    The 'org.gnu.gdb.i386.mpx' is an optional feature representing Intel

  50019. Memory Protection Extension (MPX). It should describe the following

  50020. registers:

  50021. 

  50022.    - 'bnd0raw' through 'bnd3raw' for i386 and amd64.

  50023.    - 'bndcfgu' and 'bndstatus' for i386 and amd64.

  50024. 

  50025.    The 'org.gnu.gdb.i386.linux' feature is optional.  It should describe

  50026. a single register, 'orig_eax'.

  50027. 

  50028.    The 'org.gnu.gdb.i386.segments' feature is optional.  It should

  50029. describe two system registers: 'fs_base' and 'gs_base'.

  50030. 

  50031.    The 'org.gnu.gdb.i386.avx512' feature is optional and requires the

  50032. 'org.gnu.gdb.i386.avx' feature.  It should describe additional XMM

  50033. registers:

  50034. 

  50035.    - 'xmm16h' through 'xmm31h', only valid for amd64.

  50036. 

  50037.    It should describe the upper 128 bits of additional YMM registers:

  50038. 

  50039.    - 'ymm16h' through 'ymm31h', only valid for amd64.

  50040. 

  50041.    It should describe the upper 256 bits of ZMM registers:

  50042. 

  50043.    - 'zmm0h' through 'zmm7h' for i386.

  50044.    - 'zmm0h' through 'zmm15h' for amd64.

  50045. 

  50046.    It should describe the additional ZMM registers:

  50047. 

  50048.    - 'zmm16h' through 'zmm31h', only valid for amd64.

  50049. 

  50050.    The 'org.gnu.gdb.i386.pkeys' feature is optional.  It should describe

  50051. a single register, 'pkru'.  It is a 32-bit register valid for i386 and

  50052. amd64.

  50053. 

  50054. 

  50055. File: gdb.info,  Node: MicroBlaze Features,  Next: MIPS Features,  Prev: i386 Features,  Up: Standard Target Features

  50056. 

  50057. G.5.5 MicroBlaze Features

  50058. -------------------------

  50059. 

  50060. The 'org.gnu.gdb.microblaze.core' feature is required for MicroBlaze

  50061. targets.  It should contain registers 'r0' through 'r31', 'rpc', 'rmsr',

  50062. 'rear', 'resr', 'rfsr', 'rbtr', 'rpvr', 'rpvr1' through 'rpvr11',

  50063. 'redr', 'rpid', 'rzpr', 'rtlbx', 'rtlbsx', 'rtlblo', and 'rtlbhi'.

  50064. 

  50065.    The 'org.gnu.gdb.microblaze.stack-protect' feature is optional.  If

  50066. present, it should contain registers 'rshr' and 'rslr'

  50067. 

  50068. 

  50069. File: gdb.info,  Node: MIPS Features,  Next: M68K Features,  Prev: MicroBlaze Features,  Up: Standard Target Features

  50070. 

  50071. G.5.6 MIPS Features

  50072. -------------------

  50073. 

  50074. The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets.  It

  50075. should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'.  They

  50076. may be 32-bit or 64-bit depending on the target.

  50077. 

  50078.    The 'org.gnu.gdb.mips.cp0' feature is also required.  It should

  50079. contain at least the 'status', 'badvaddr', and 'cause' registers.  They

  50080. may be 32-bit or 64-bit depending on the target.

  50081. 

  50082.    The 'org.gnu.gdb.mips.fpu' feature is currently required, though it

  50083. may be optional in a future version of GDB.  It should contain registers

  50084. 'f0' through 'f31', 'fcsr', and 'fir'.  They may be 32-bit or 64-bit

  50085. depending on the target.

  50086. 

  50087.    The 'org.gnu.gdb.mips.dsp' feature is optional.  It should contain

  50088. registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'.  The

  50089. 'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit

  50090. depending on the target.

  50091. 

  50092.    The 'org.gnu.gdb.mips.linux' feature is optional.  It should contain

  50093. a single register, 'restart', which is used by the Linux kernel to

  50094. control restartable syscalls.

  50095. 

  50096. 

  50097. File: gdb.info,  Node: M68K Features,  Next: NDS32 Features,  Prev: MIPS Features,  Up: Standard Target Features

  50098. 

  50099. G.5.7 M68K Features

  50100. -------------------

  50101. 

  50102. ''org.gnu.gdb.m68k.core''

  50103. ''org.gnu.gdb.coldfire.core''

  50104. ''org.gnu.gdb.fido.core''

  50105.      One of those features must be always present.  The feature that is

  50106.      present determines which flavor of m68k is used.  The feature that

  50107.      is present should contain registers 'd0' through 'd7', 'a0' through

  50108.      'a5', 'fp', 'sp', 'ps' and 'pc'.

  50109. 

  50110. ''org.gnu.gdb.coldfire.fp''

  50111.      This feature is optional.  If present, it should contain registers

  50112.      'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'.

  50113. 

  50114.      Note that, despite the fact that this feature's name says

  50115.      'coldfire', it is used to describe any floating point registers.

  50116.      The size of the registers must match the main m68k flavor; so, for

  50117.      example, if the primary feature is reported as 'coldfire', then

  50118.      64-bit floating point registers are required.

  50119. 

  50120. 

  50121. File: gdb.info,  Node: NDS32 Features,  Next: Nios II Features,  Prev: M68K Features,  Up: Standard Target Features

  50122. 

  50123. G.5.8 NDS32 Features

  50124. --------------------

  50125. 

  50126. The 'org.gnu.gdb.nds32.core' feature is required for NDS32 targets.  It

  50127. should contain at least registers 'r0' through 'r10', 'r15', 'fp', 'gp',

  50128. 'lp', 'sp', and 'pc'.

  50129. 

  50130.    The 'org.gnu.gdb.nds32.fpu' feature is optional.  If present, it

  50131. should contain 64-bit double-precision floating-point registers 'fd0'

  50132. through _fdN_, which should be 'fd3', 'fd7', 'fd15', or 'fd31' based on

  50133. the FPU configuration implemented.

  50134. 

  50135.    _Note:_ The first sixteen 64-bit double-precision floating-point

  50136. registers are overlapped with the thirty-two 32-bit single-precision

  50137. floating-point registers.  The 32-bit single-precision registers, if not

  50138. being listed explicitly, will be synthesized from halves of the

  50139. overlapping 64-bit double-precision registers.  Listing 32-bit

  50140. single-precision registers explicitly is deprecated, and the support to

  50141. it could be totally removed some day.

  50142. 

  50143. 

  50144. File: gdb.info,  Node: Nios II Features,  Next: OpenRISC 1000 Features,  Prev: NDS32 Features,  Up: Standard Target Features

  50145. 

  50146. G.5.9 Nios II Features

  50147. ----------------------

  50148. 

  50149. The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets.  It

  50150. should contain the 32 core registers ('zero', 'at', 'r2' through 'r23',

  50151. 'et' through 'ra'), 'pc', and the 16 control registers ('status' through

  50152. 'mpuacc').

  50153. 

  50154. 

  50155. File: gdb.info,  Node: OpenRISC 1000 Features,  Next: PowerPC Features,  Prev: Nios II Features,  Up: Standard Target Features

  50156. 

  50157. G.5.10 Openrisc 1000 Features

  50158. -----------------------------

  50159. 

  50160. The 'org.gnu.gdb.or1k.group0' feature is required for OpenRISC 1000

  50161. targets.  It should contain the 32 general purpose registers ('r0'

  50162. through 'r31'), 'ppc', 'npc' and 'sr'.

  50163. 

  50164. 

  50165. File: gdb.info,  Node: PowerPC Features,  Next: RISC-V Features,  Prev: OpenRISC 1000 Features,  Up: Standard Target Features

  50166. 

  50167. G.5.11 PowerPC Features

  50168. -----------------------

  50169. 

  50170. The 'org.gnu.gdb.power.core' feature is required for PowerPC targets.

  50171. It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr',

  50172. 'ctr', and 'xer'.  They may be 32-bit or 64-bit depending on the target.

  50173. 

  50174.    The 'org.gnu.gdb.power.fpu' feature is optional.  It should contain

  50175. registers 'f0' through 'f31' and 'fpscr'.

  50176. 

  50177.    The 'org.gnu.gdb.power.altivec' feature is optional.  It should

  50178. contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'.  GDB will

  50179. define pseudo-registers 'v0' through 'v31' as aliases for the

  50180. corresponding 'vrX' registers.

  50181. 

  50182.    The 'org.gnu.gdb.power.vsx' feature is optional.  It should contain

  50183. registers 'vs0h' through 'vs31h'.  GDB will combine these registers with

  50184. the floating point registers ('f0' through 'f31') and the altivec

  50185. registers ('vr0' through 'vr31') to present the 128-bit wide registers

  50186. 'vs0' through 'vs63', the set of vector-scalar registers for POWER7.

  50187. Therefore, this feature requires both 'org.gnu.gdb.power.fpu' and

  50188. 'org.gnu.gdb.power.altivec'.

  50189. 

  50190.    The 'org.gnu.gdb.power.spe' feature is optional.  It should contain

  50191. registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'.  SPE targets

  50192. should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide

  50193. the upper halves in 'ev0h' through 'ev31h'.  GDB will combine these to

  50194. present registers 'ev0' through 'ev31' to the user.

  50195. 

  50196.    The 'org.gnu.gdb.power.ppr' feature is optional.  It should contain

  50197. the 64-bit register 'ppr'.

  50198. 

  50199.    The 'org.gnu.gdb.power.dscr' feature is optional.  It should contain

  50200. the 64-bit register 'dscr'.

  50201. 

  50202.    The 'org.gnu.gdb.power.tar' feature is optional.  It should contain

  50203. the 64-bit register 'tar'.

  50204. 

  50205.    The 'org.gnu.gdb.power.ebb' feature is optional.  It should contain

  50206. registers 'bescr', 'ebbhr' and 'ebbrr', all 64-bit wide.

  50207. 

  50208.    The 'org.gnu.gdb.power.linux.pmu' feature is optional.  It should

  50209. contain registers 'mmcr0', 'mmcr2', 'siar', 'sdar' and 'sier', all

  50210. 64-bit wide.  This is the subset of the isa 2.07 server PMU registers

  50211. provided by GNU/Linux.

  50212. 

  50213.    The 'org.gnu.gdb.power.htm.spr' feature is optional.  It should

  50214. contain registers 'tfhar', 'texasr' and 'tfiar', all 64-bit wide.

  50215. 

  50216.    The 'org.gnu.gdb.power.htm.core' feature is optional.  It should

  50217. contain the checkpointed general-purpose registers 'cr0' through 'cr31',

  50218. as well as the checkpointed registers 'clr' and 'cctr'.  These registers

  50219. may all be either 32-bit or 64-bit depending on the target.  It should

  50220. also contain the checkpointed registers 'ccr' and 'cxer', which should

  50221. both be 32-bit wide.

  50222. 

  50223.    The 'org.gnu.gdb.power.htm.fpu' feature is optional.  It should

  50224. contain the checkpointed 64-bit floating-point registers 'cf0' through

  50225. 'cf31', as well as the checkpointed 64-bit register 'cfpscr'.

  50226. 

  50227.    The 'org.gnu.gdb.power.htm.altivec' feature is optional.  It should

  50228. contain the checkpointed altivec registers 'cvr0' through 'cvr31', all

  50229. 128-bit wide.  It should also contain the checkpointed registers 'cvscr'

  50230. and 'cvrsave', both 32-bit wide.

  50231. 

  50232.    The 'org.gnu.gdb.power.htm.vsx' feature is optional.  It should

  50233. contain registers 'cvs0h' through 'cvs31h'.  GDB will combine these

  50234. registers with the checkpointed floating point registers ('cf0' through

  50235. 'cf31') and the checkpointed altivec registers ('cvr0' through 'cvr31')

  50236. to present the 128-bit wide checkpointed vector-scalar registers 'cvs0'

  50237. through 'cvs63'.  Therefore, this feature requires both

  50238. 'org.gnu.gdb.power.htm.altivec' and 'org.gnu.gdb.power.htm.fpu'.

  50239. 

  50240.    The 'org.gnu.gdb.power.htm.ppr' feature is optional.  It should

  50241. contain the 64-bit checkpointed register 'cppr'.

  50242. 

  50243.    The 'org.gnu.gdb.power.htm.dscr' feature is optional.  It should

  50244. contain the 64-bit checkpointed register 'cdscr'.

  50245. 

  50246.    The 'org.gnu.gdb.power.htm.tar' feature is optional.  It should

  50247. contain the 64-bit checkpointed register 'ctar'.

  50248. 

  50249. 

  50250. File: gdb.info,  Node: RISC-V Features,  Next: RX Features,  Prev: PowerPC Features,  Up: Standard Target Features

  50251. 

  50252. G.5.12 RISC-V Features

  50253. ----------------------

  50254. 

  50255. The 'org.gnu.gdb.riscv.cpu' feature is required for RISC-V targets.  It

  50256. should contain the registers 'x0' through 'x31', and 'pc'.  Either the

  50257. architectural names ('x0', 'x1', etc) can be used, or the ABI names

  50258. ('zero', 'ra', etc).

  50259. 

  50260.    The 'org.gnu.gdb.riscv.fpu' feature is optional.  If present, it

  50261. should contain registers 'f0' through 'f31', 'fflags', 'frm', and

  50262. 'fcsr'.  As with the cpu feature, either the architectural register

  50263. names, or the ABI names can be used.

  50264. 

  50265.    The 'org.gnu.gdb.riscv.virtual' feature is optional.  If present, it

  50266. should contain registers that are not backed by real registers on the

  50267. target, but are instead virtual, where the register value is derived

  50268. from other target state.  In many ways these are like GDBs

  50269. pseudo-registers, except implemented by the target.  Currently the only

  50270. register expected in this set is the one byte 'priv' register that

  50271. contains the target's privilege level in the least significant two bits.

  50272. 

  50273.    The 'org.gnu.gdb.riscv.csr' feature is optional.  If present, it

  50274. should contain all of the target's standard CSRs.  Standard CSRs are

  50275. those defined in the RISC-V specification documents.  There is some

  50276. overlap between this feature and the fpu feature; the 'fflags', 'frm',

  50277. and 'fcsr' registers could be in either feature.  The expectation is

  50278. that these registers will be in the fpu feature if the target has

  50279. floating point hardware, but can be moved into the csr feature if the

  50280. target has the floating point control registers, but no other floating

  50281. point hardware.

  50282. 

  50283. 

  50284. File: gdb.info,  Node: RX Features,  Next: S/390 and System z Features,  Prev: RISC-V Features,  Up: Standard Target Features

  50285. 

  50286. G.5.13 RX Features

  50287. ------------------

  50288. 

  50289. The 'org.gnu.gdb.rx.core' feature is required for RX targets.  It should

  50290. contain the registers 'r0' through 'r15', 'usp', 'isp', 'psw', 'pc',

  50291. 'intb', 'bpsw', 'bpc', 'fintv', 'fpsw', and 'acc'.

  50292. 

  50293. 

  50294. File: gdb.info,  Node: S/390 and System z Features,  Next: Sparc Features,  Prev: RX Features,  Up: Standard Target Features

  50295. 

  50296. G.5.14 S/390 and System z Features

  50297. ----------------------------------

  50298. 

  50299. The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z

  50300. targets.  It should contain the PSW and the 16 general registers.  In

  50301. particular, System z targets should provide the 64-bit registers 'pswm',

  50302. 'pswa', and 'r0' through 'r15'.  S/390 targets should provide the 32-bit

  50303. versions of these registers.  A System z target that runs in 31-bit

  50304. addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as

  50305. well as the general register's upper halves 'r0h' through 'r15h', and

  50306. their lower halves 'r0l' through 'r15l'.

  50307. 

  50308.    The 'org.gnu.gdb.s390.fpr' feature is required.  It should contain

  50309. the 64-bit registers 'f0' through 'f15', and 'fpc'.

  50310. 

  50311.    The 'org.gnu.gdb.s390.acr' feature is required.  It should contain

  50312. the 32-bit registers 'acr0' through 'acr15'.

  50313. 

  50314.    The 'org.gnu.gdb.s390.linux' feature is optional.  It should contain

  50315. the register 'orig_r2', which is 64-bit wide on System z targets and

  50316. 32-bit otherwise.  In addition, the feature may contain the 'last_break'

  50317. register, whose width depends on the addressing mode, as well as the

  50318. 'system_call' register, which is always 32-bit wide.

  50319. 

  50320.    The 'org.gnu.gdb.s390.tdb' feature is optional.  It should contain

  50321. the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through

  50322. 'tr15'.

  50323. 

  50324.    The 'org.gnu.gdb.s390.vx' feature is optional.  It should contain

  50325. 64-bit wide registers 'v0l' through 'v15l', which will be combined by

  50326. GDB with the floating point registers 'f0' through 'f15' to present the

  50327. 128-bit wide vector registers 'v0' through 'v15'.  In addition, this

  50328. feature should contain the 128-bit wide vector registers 'v16' through

  50329. 'v31'.

  50330. 

  50331.    The 'org.gnu.gdb.s390.gs' feature is optional.  It should contain the

  50332. 64-bit wide guarded-storage-control registers 'gsd', 'gssm', and

  50333. 'gsepla'.

  50334. 

  50335.    The 'org.gnu.gdb.s390.gsbc' feature is optional.  It should contain

  50336. the 64-bit wide guarded-storage broadcast control registers 'bc_gsd',

  50337. 'bc_gssm', and 'bc_gsepla'.

  50338. 

  50339. 

  50340. File: gdb.info,  Node: Sparc Features,  Next: TIC6x Features,  Prev: S/390 and System z Features,  Up: Standard Target Features

  50341. 

  50342. G.5.15 Sparc Features

  50343. ---------------------

  50344. 

  50345. The 'org.gnu.gdb.sparc.cpu' feature is required for sparc32/sparc64

  50346. targets.  It should describe the following registers:

  50347. 

  50348.    - 'g0' through 'g7'

  50349.    - 'o0' through 'o7'

  50350.    - 'l0' through 'l7'

  50351.    - 'i0' through 'i7'

  50352. 

  50353.    They may be 32-bit or 64-bit depending on the target.

  50354. 

  50355.    Also the 'org.gnu.gdb.sparc.fpu' feature is required for

  50356. sparc32/sparc64 targets.  It should describe the following registers:

  50357. 

  50358.    - 'f0' through 'f31'

  50359.    - 'f32' through 'f62' for sparc64

  50360. 

  50361.    The 'org.gnu.gdb.sparc.cp0' feature is required for sparc32/sparc64

  50362. targets.  It should describe the following registers:

  50363. 

  50364.    - 'y', 'psr', 'wim', 'tbr', 'pc', 'npc', 'fsr', and 'csr' for sparc32

  50365.    - 'pc', 'npc', 'state', 'fsr', 'fprs', and 'y' for sparc64

  50366. 

  50367. 

  50368. File: gdb.info,  Node: TIC6x Features,  Prev: Sparc Features,  Up: Standard Target Features

  50369. 

  50370. G.5.16 TMS320C6x Features

  50371. -------------------------

  50372. 

  50373. The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.

  50374. It should contain registers 'A0' through 'A15', registers 'B0' through

  50375. 'B15', 'CSR' and 'PC'.

  50376. 

  50377.    The 'org.gnu.gdb.tic6x.gp' feature is optional.  It should contain

  50378. registers 'A16' through 'A31' and 'B16' through 'B31'.

  50379. 

  50380.    The 'org.gnu.gdb.tic6x.c6xp' feature is optional.  It should contain

  50381. registers 'TSR', 'ILC' and 'RILC'.

  50382. 

  50383. 

  50384. File: gdb.info,  Node: Operating System Information,  Next: Trace File Format,  Prev: Target Descriptions,  Up: Top

  50385. 

  50386. Appendix H Operating System Information

  50387. ***************************************

  50388. 

  50389. * Menu:

  50390. 

  50391. * Process list::

  50392. 

  50393. Users of GDB often wish to obtain information about the state of the

  50394. operating system running on the target--for example the list of

  50395. processes, or the list of open files.  This section describes the

  50396. mechanism that makes it possible.  This mechanism is similar to the

  50397. target features mechanism (*note Target Descriptions::), but focuses on

  50398. a different aspect of target.

  50399. 

  50400.    Operating system information is retrieved from the target via the

  50401. remote protocol, using 'qXfer' requests (*note qXfer osdata read::).

  50402. The object name in the request should be 'osdata', and the ANNEX

  50403. identifies the data to be fetched.

  50404. 

  50405. 

  50406. File: gdb.info,  Node: Process list,  Up: Operating System Information

  50407. 

  50408. H.1 Process list

  50409. ================

  50410. 

  50411. When requesting the process list, the ANNEX field in the 'qXfer' request

  50412. should be 'processes'.  The returned data is an XML document.  The

  50413. formal syntax of this document is defined in 'gdb/features/osdata.dtd'.

  50414. 

  50415.    An example document is:

  50416. 

  50417.      <?xml version="1.0"?>

  50418.      <!DOCTYPE target SYSTEM "osdata.dtd">

  50419.      <osdata type="processes">

  50420.        <item>

  50421.          <column name="pid">1</column>

  50422.          <column name="user">root</column>

  50423.          <column name="command">/sbin/init</column>

  50424.          <column name="cores">1,2,3</column>

  50425.        </item>

  50426.      </osdata>

  50427. 

  50428.    Each item should include a column whose name is 'pid'.  The value of

  50429. that column should identify the process on the target.  The 'user' and

  50430. 'command' columns are optional, and will be displayed by GDB.  The

  50431. 'cores' column, if present, should contain a comma-separated list of

  50432. cores that this process is running on.  Target may provide additional

  50433. columns, which GDB currently ignores.

  50434. 

  50435. 

  50436. File: gdb.info,  Node: Trace File Format,  Next: Index Section Format,  Prev: Operating System Information,  Up: Top

  50437. 

  50438. Appendix I Trace File Format

  50439. ****************************

  50440. 

  50441. The trace file comes in three parts: a header, a textual description

  50442. section, and a trace frame section with binary data.

  50443. 

  50444.    The header has the form '\x7fTRACE0\n'.  The first byte is '0x7f' so

  50445. as to indicate that the file contains binary data, while the '0' is a

  50446. version number that may have different values in the future.

  50447. 

  50448.    The description section consists of multiple lines of ASCII text

  50449. separated by newline characters ('0xa').  The lines may include a

  50450. variety of optional descriptive or context-setting information, such as

  50451. tracepoint definitions or register set size.  GDB will ignore any line

  50452. that it does not recognize.  An empty line marks the end of this

  50453. section.

  50454. 

  50455. 'R SIZE'

  50456.      Specifies the size of a register block in bytes.  This is equal to

  50457.      the size of a 'g' packet payload in the remote protocol.  SIZE is

  50458.      an ascii decimal number.  There should be only one such line in a

  50459.      single trace file.

  50460. 

  50461. 'status STATUS'

  50462.      Trace status.  STATUS has the same format as a 'qTStatus' remote

  50463.      packet reply.  There should be only one such line in a single trace

  50464.      file.

  50465. 

  50466. 'tp PAYLOAD'

  50467.      Tracepoint definition.  The PAYLOAD has the same format as

  50468.      'qTfP'/'qTsP' remote packet reply payload.  A single tracepoint may

  50469.      take multiple lines of definition, corresponding to the multiple

  50470.      reply packets.

  50471. 

  50472. 'tsv PAYLOAD'

  50473.      Trace state variable definition.  The PAYLOAD has the same format

  50474.      as 'qTfV'/'qTsV' remote packet reply payload.  A single variable

  50475.      may take multiple lines of definition, corresponding to the

  50476.      multiple reply packets.

  50477. 

  50478. 'tdesc PAYLOAD'

  50479.      Target description in XML format.  The PAYLOAD is a single line of

  50480.      the XML file.  All such lines should be concatenated together to

  50481.      get the original XML file.  This file is in the same format as

  50482.      'qXfer' 'features' payload, and corresponds to the main

  50483.      'target.xml' file.  Includes are not allowed.

  50484. 

  50485.    The trace frame section consists of a number of consecutive frames.

  50486. Each frame begins with a two-byte tracepoint number, followed by a

  50487. four-byte size giving the amount of data in the frame.  The data in the

  50488. frame consists of a number of blocks, each introduced by a character

  50489. indicating its type (at least register, memory, and trace state

  50490. variable).  The data in this section is raw binary, not a hexadecimal or

  50491. other encoding; its endianness matches the target's endianness.

  50492. 

  50493. 'R BYTES'

  50494.      Register block.  The number and ordering of bytes matches that of a

  50495.      'g' packet in the remote protocol.  Note that these are the actual

  50496.      bytes, in target order, not a hexadecimal encoding.

  50497. 

  50498. 'M ADDRESS LENGTH BYTES...'

  50499.      Memory block.  This is a contiguous block of memory, at the 8-byte

  50500.      address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH

  50501.      bytes.

  50502. 

  50503. 'V NUMBER VALUE'

  50504.      Trace state variable block.  This records the 8-byte signed value

  50505.      VALUE of trace state variable numbered NUMBER.

  50506. 

  50507.    Future enhancements of the trace file format may include additional

  50508. types of blocks.

  50509. 

  50510. 

  50511. File: gdb.info,  Node: Index Section Format,  Next: Man Pages,  Prev: Trace File Format,  Up: Top

  50512. 

  50513. Appendix J '.gdb_index' section format

  50514. **************************************

  50515. 

  50516. This section documents the index section that is created by 'save

  50517. gdb-index' (*note Index Files::).  The index section is DWARF-specific;

  50518. some knowledge of DWARF is assumed in this description.

  50519. 

  50520.    The mapped index file format is designed to be directly 'mmap'able on

  50521. any architecture.  In most cases, a datum is represented using a

  50522. little-endian 32-bit integer value, called an 'offset_type'.  Big endian

  50523. machines must byte-swap the values before using them.  Exceptions to

  50524. this rule are noted.  The data is laid out such that alignment is always

  50525. respected.

  50526. 

  50527.    A mapped index consists of several areas, laid out in order.

  50528. 

  50529.   1. The file header.  This is a sequence of values, of 'offset_type'

  50530.      unless otherwise noted:

  50531. 

  50532.        1. The version number, currently 8.  Versions 1, 2 and 3 are

  50533.           obsolete.  Version 4 uses a different hashing function from

  50534.           versions 5 and 6.  Version 6 includes symbols for inlined

  50535.           functions, whereas versions 4 and 5 do not.  Version 7 adds

  50536.           attributes to the CU indices in the symbol table.  Version 8

  50537.           specifies that symbols from DWARF type units

  50538.           ('DW_TAG_type_unit') refer to the type unit's symbol table and

  50539.           not the compilation unit ('DW_TAG_comp_unit') using the type.

  50540. 

  50541.           GDB will only read version 4, 5, or 6 indices by specifying

  50542.           'set use-deprecated-index-sections on'.  GDB has a workaround

  50543.           for potentially broken version 7 indices so it is currently

  50544.           not flagged as deprecated.

  50545. 

  50546.        2. The offset, from the start of the file, of the CU list.

  50547. 

  50548.        3. The offset, from the start of the file, of the types CU list.

  50549.           Note that this area can be empty, in which case this offset

  50550.           will be equal to the next offset.

  50551. 

  50552.        4. The offset, from the start of the file, of the address area.

  50553. 

  50554.        5. The offset, from the start of the file, of the symbol table.

  50555. 

  50556.        6. The offset, from the start of the file, of the constant pool.

  50557. 

  50558.   2. The CU list.  This is a sequence of pairs of 64-bit little-endian

  50559.      values, sorted by the CU offset.  The first element in each pair is

  50560.      the offset of a CU in the '.debug_info' section.  The second

  50561.      element in each pair is the length of that CU. References to a CU

  50562.      elsewhere in the map are done using a CU index, which is just the

  50563.      0-based index into this table.  Note that if there are type CUs,

  50564.      then conceptually CUs and type CUs form a single list for the

  50565.      purposes of CU indices.

  50566. 

  50567.   3. The types CU list.  This is a sequence of triplets of 64-bit

  50568.      little-endian values.  In a triplet, the first value is the CU

  50569.      offset, the second value is the type offset in the CU, and the

  50570.      third value is the type signature.  The types CU list is not

  50571.      sorted.

  50572. 

  50573.   4. The address area.  The address area consists of a sequence of

  50574.      address entries.  Each address entry has three elements:

  50575. 

  50576.        1. The low address.  This is a 64-bit little-endian value.

  50577. 

  50578.        2. The high address.  This is a 64-bit little-endian value.  Like

  50579.           'DW_AT_high_pc', the value is one byte beyond the end.

  50580. 

  50581.        3. The CU index.  This is an 'offset_type' value.

  50582. 

  50583.   5. The symbol table.  This is an open-addressed hash table.  The size

  50584.      of the hash table is always a power of 2.

  50585. 

  50586.      Each slot in the hash table consists of a pair of 'offset_type'

  50587.      values.  The first value is the offset of the symbol's name in the

  50588.      constant pool.  The second value is the offset of the CU vector in

  50589.      the constant pool.

  50590. 

  50591.      If both values are 0, then this slot in the hash table is empty.

  50592.      This is ok because while 0 is a valid constant pool index, it

  50593.      cannot be a valid index for both a string and a CU vector.

  50594. 

  50595.      The hash value for a table entry is computed by applying an

  50596.      iterative hash function to the symbol's name.  Starting with an

  50597.      initial value of 'r = 0', each (unsigned) character 'c' in the

  50598.      string is incorporated into the hash using the formula depending on

  50599.      the index version:

  50600. 

  50601.      Version 4

  50602.           The formula is 'r = r * 67 + c - 113'.

  50603. 

  50604.      Versions 5 to 7

  50605.           The formula is 'r = r * 67 + tolower (c) - 113'.

  50606. 

  50607.      The terminating '\0' is not incorporated into the hash.

  50608. 

  50609.      The step size used in the hash table is computed via '((hash * 17)

  50610.      & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is

  50611.      the size of the hash table.  The step size is used to find the next

  50612.      candidate slot when handling a hash collision.

  50613. 

  50614.      The names of C++ symbols in the hash table are canonicalized.  We

  50615.      don't currently have a simple description of the canonicalization

  50616.      algorithm; if you intend to create new index sections, you must

  50617.      read the code.

  50618. 

  50619.   6. The constant pool.  This is simply a bunch of bytes.  It is

  50620.      organized so that alignment is correct: CU vectors are stored

  50621.      first, followed by strings.

  50622. 

  50623.      A CU vector in the constant pool is a sequence of 'offset_type'

  50624.      values.  The first value is the number of CU indices in the vector.

  50625.      Each subsequent value is the index and symbol attributes of a CU in

  50626.      the CU list.  This element in the hash table is used to indicate

  50627.      which CUs define the symbol and how the symbol is used.  See below

  50628.      for the format of each CU index+attributes entry.

  50629. 

  50630.      A string in the constant pool is zero-terminated.

  50631. 

  50632.    Attributes were added to CU index values in '.gdb_index' version 7.

  50633. If a symbol has multiple uses within a CU then there is one CU

  50634. index+attributes value for each use.

  50635. 

  50636.    The format of each CU index+attributes entry is as follows (bit 0 =

  50637. LSB):

  50638. 

  50639. Bits 0-23

  50640.      This is the index of the CU in the CU list.

  50641. Bits 24-27

  50642.      These bits are reserved for future purposes and must be zero.

  50643. Bits 28-30

  50644.      The kind of the symbol in the CU.

  50645. 

  50646.      0

  50647.           This value is reserved and should not be used.  By reserving

  50648.           zero the full 'offset_type' value is backwards compatible with

  50649.           previous versions of the index.

  50650.      1

  50651.           The symbol is a type.

  50652.      2

  50653.           The symbol is a variable or an enum value.

  50654.      3

  50655.           The symbol is a function.

  50656.      4

  50657.           Any other kind of symbol.

  50658.      5,6,7

  50659.           These values are reserved.

  50660. 

  50661. Bit 31

  50662.      This bit is zero if the value is global and one if it is static.

  50663. 

  50664.      The determination of whether a symbol is global or static is

  50665.      complicated.  The authorative reference is the file 'dwarf2read.c'

  50666.      in GDB sources.

  50667. 

  50668.    This pseudo-code describes the computation of a symbol's kind and

  50669. global/static attributes in the index.

  50670. 

  50671.      is_external = get_attribute (die, DW_AT_external);

  50672.      language = get_attribute (cu_die, DW_AT_language);

  50673.      switch (die->tag)

  50674.        {

  50675.        case DW_TAG_typedef:

  50676.        case DW_TAG_base_type:

  50677.        case DW_TAG_subrange_type:

  50678.          kind = TYPE;

  50679.          is_static = 1;

  50680.          break;

  50681.        case DW_TAG_enumerator:

  50682.          kind = VARIABLE;

  50683.          is_static = language != CPLUS;

  50684.          break;

  50685.        case DW_TAG_subprogram:

  50686.          kind = FUNCTION;

  50687.          is_static = ! (is_external || language == ADA);

  50688.          break;

  50689.        case DW_TAG_constant:

  50690.          kind = VARIABLE;

  50691.          is_static = ! is_external;

  50692.          break;

  50693.        case DW_TAG_variable:

  50694.          kind = VARIABLE;

  50695.          is_static = ! is_external;

  50696.          break;

  50697.        case DW_TAG_namespace:

  50698.          kind = TYPE;

  50699.          is_static = 0;

  50700.          break;

  50701.        case DW_TAG_class_type:

  50702.        case DW_TAG_interface_type:

  50703.        case DW_TAG_structure_type:

  50704.        case DW_TAG_union_type:

  50705.        case DW_TAG_enumeration_type:

  50706.          kind = TYPE;

  50707.          is_static = language != CPLUS;

  50708.          break;

  50709.        default:

  50710.          assert (0);

  50711.        }

  50712. 

  50713. 

  50714. File: gdb.info,  Node: Man Pages,  Next: Copying,  Prev: Index Section Format,  Up: Top

  50715. 

  50716. Appendix K Manual pages

  50717. ***********************

  50718. 

  50719. * Menu:

  50720. 

  50721. * gdb man::                     The GNU Debugger man page

  50722. * gdbserver man::               Remote Server for the GNU Debugger man page

  50723. * gcore man::                   Generate a core file of a running program

  50724. * gdbinit man::                 gdbinit scripts

  50725. * gdb-add-index man::           Add index files to speed up GDB

  50726. 

  50727. 

  50728. File: gdb.info,  Node: gdb man,  Next: gdbserver man,  Up: Man Pages

  50729. 

  50730. gdb man

  50731. =======

  50732. 

  50733. gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f']

  50734. ['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG]

  50735. ['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG

  50736. CORE]

  50737. 

  50738.    The purpose of a debugger such as GDB is to allow you to see what is

  50739. going on "inside" another program while it executes - or what another

  50740. program was doing at the moment it crashed.

  50741. 

  50742.    GDB can do four main kinds of things (plus other things in support of

  50743. these) to help you catch bugs in the act:

  50744. 

  50745.    * Start your program, specifying anything that might affect its

  50746.      behavior.

  50747. 

  50748.    * Make your program stop on specified conditions.

  50749. 

  50750.    * Examine what has happened, when your program has stopped.

  50751. 

  50752.    * Change things in your program, so you can experiment with

  50753.      correcting the effects of one bug and go on to learn about another.

  50754. 

  50755.    You can use GDB to debug programs written in C, C++, Fortran and

  50756. Modula-2.

  50757. 

  50758.    GDB is invoked with the shell command 'gdb'.  Once started, it reads

  50759. commands from the terminal until you tell it to exit with the GDB

  50760. command 'quit'.  You can get online help from GDB itself by using the

  50761. command 'help'.

  50762. 

  50763.    You can run 'gdb' with no arguments or options; but the most usual

  50764. way to start GDB is with one argument or two, specifying an executable

  50765. program as the argument:

  50766. 

  50767.      gdb program

  50768. 

  50769.    You can also start with both an executable program and a core file

  50770. specified:

  50771. 

  50772.      gdb program core

  50773. 

  50774.    You can, instead, specify a process ID as a second argument or use

  50775. option '-p', if you want to debug a running process:

  50776. 

  50777.      gdb program 1234

  50778.      gdb -p 1234

  50779. 

  50780. would attach GDB to process '1234'.  With option '-p' you can omit the

  50781. PROGRAM filename.

  50782. 

  50783.    Here are some of the most frequently needed GDB commands:

  50784. 

  50785. 'break [FILE:]FUNCTION'

  50786.      Set a breakpoint at FUNCTION (in FILE).

  50787. 

  50788. 'run [ARGLIST]'

  50789.      Start your program (with ARGLIST, if specified).

  50790. 

  50791. 'bt'

  50792.      Backtrace: display the program stack.

  50793. 

  50794. 'print EXPR'

  50795.      Display the value of an expression.

  50796. 

  50797. 'c'

  50798.      Continue running your program (after stopping, e.g.  at a

  50799.      breakpoint).

  50800. 

  50801. 'next'

  50802.      Execute next program line (after stopping); step _over_ any

  50803.      function calls in the line.

  50804. 

  50805. 'edit [FILE:]FUNCTION'

  50806.      look at the program line where it is presently stopped.

  50807. 

  50808. 'list [FILE:]FUNCTION'

  50809.      type the text of the program in the vicinity of where it is

  50810.      presently stopped.

  50811. 

  50812. 'step'

  50813.      Execute next program line (after stopping); step _into_ any

  50814.      function calls in the line.

  50815. 

  50816. 'help [NAME]'

  50817.      Show information about GDB command NAME, or general information

  50818.      about using GDB.

  50819. 

  50820. 'quit'

  50821.      Exit from GDB.

  50822. 

  50823.    Any arguments other than options specify an executable file and core

  50824. file (or process ID); that is, the first argument encountered with no

  50825. associated option flag is equivalent to a '-se' option, and the second,

  50826. if any, is equivalent to a '-c' option if it's the name of a file.  Many

  50827. options have both long and short forms; both are shown here.  The long

  50828. forms are also recognized if you truncate them, so long as enough of the

  50829. option is present to be unambiguous.  (If you prefer, you can flag

  50830. option arguments with '+' rather than '-', though we illustrate the more

  50831. usual convention.)

  50832. 

  50833.    All the options and command line arguments you give are processed in

  50834. sequential order.  The order makes a difference when the '-x' option is

  50835. used.

  50836. 

  50837. '-help'

  50838. '-h'

  50839.      List all options, with brief explanations.

  50840. 

  50841. '-symbols=FILE'

  50842. '-s FILE'

  50843.      Read symbol table from file FILE.

  50844. 

  50845. '-write'

  50846.      Enable writing into executable and core files.

  50847. 

  50848. '-exec=FILE'

  50849. '-e FILE'

  50850.      Use file FILE as the executable file to execute when appropriate,

  50851.      and for examining pure data in conjunction with a core dump.

  50852. 

  50853. '-se=FILE'

  50854.      Read symbol table from file FILE and use it as the executable file.

  50855. 

  50856. '-core=FILE'

  50857. '-c FILE'

  50858.      Use file FILE as a core dump to examine.

  50859. 

  50860. '-command=FILE'

  50861. '-x FILE'

  50862.      Execute GDB commands from file FILE.

  50863. 

  50864. '-ex COMMAND'

  50865.      Execute given GDB COMMAND.

  50866. 

  50867. '-directory=DIRECTORY'

  50868. '-d DIRECTORY'

  50869.      Add DIRECTORY to the path to search for source files.

  50870. 

  50871. '-nh'

  50872.      Do not execute commands from '~/.gdbinit'.

  50873. 

  50874. '-nx'

  50875. '-n'

  50876.      Do not execute commands from any '.gdbinit' initialization files.

  50877. 

  50878. '-quiet'

  50879. '-q'

  50880.      "Quiet".  Do not print the introductory and copyright messages.

  50881.      These messages are also suppressed in batch mode.

  50882. 

  50883. '-batch'

  50884.      Run in batch mode.  Exit with status '0' after processing all the

  50885.      command files specified with '-x' (and '.gdbinit', if not

  50886.      inhibited).  Exit with nonzero status if an error occurs in

  50887.      executing the GDB commands in the command files.

  50888. 

  50889.      Batch mode may be useful for running GDB as a filter, for example

  50890.      to download and run a program on another computer; in order to make

  50891.      this more useful, the message

  50892. 

  50893.           Program exited normally.

  50894. 

  50895.      (which is ordinarily issued whenever a program running under GDB

  50896.      control terminates) is not issued when running in batch mode.

  50897. 

  50898. '-cd=DIRECTORY'

  50899.      Run GDB using DIRECTORY as its working directory, instead of the

  50900.      current directory.

  50901. 

  50902. '-fullname'

  50903. '-f'

  50904.      Emacs sets this option when it runs GDB as a subprocess.  It tells

  50905.      GDB to output the full file name and line number in a standard,

  50906.      recognizable fashion each time a stack frame is displayed (which

  50907.      includes each time the program stops).  This recognizable format

  50908.      looks like two '\032' characters, followed by the file name, line

  50909.      number and character position separated by colons, and a newline.

  50910.      The Emacs-to-GDB interface program uses the two '\032' characters

  50911.      as a signal to display the source code for the frame.

  50912. 

  50913. '-b BPS'

  50914.      Set the line speed (baud rate or bits per second) of any serial

  50915.      interface used by GDB for remote debugging.

  50916. 

  50917. '-tty=DEVICE'

  50918.      Run using DEVICE for your program's standard input and output.

  50919. 

  50920. 

  50921. File: gdb.info,  Node: gdbserver man,  Next: gcore man,  Prev: gdb man,  Up: Man Pages

  50922. 

  50923. gdbserver man

  50924. =============

  50925. 

  50926. gdbserver COMM PROG [ARGS...]

  50927. 

  50928. gdbserver -attach COMM PID

  50929. 

  50930. gdbserver -multi COMM

  50931. 

  50932.    'gdbserver' is a program that allows you to run GDB on a different

  50933. machine than the one which is running the program being debugged.

  50934. 

  50935. Usage (server (target) side)

  50936. ----------------------------

  50937. 

  50938. First, you need to have a copy of the program you want to debug put onto

  50939. the target system.  The program can be stripped to save space if needed,

  50940. as 'gdbserver' doesn't care about symbols.  All symbol handling is taken

  50941. care of by the GDB running on the host system.

  50942. 

  50943.    To use the server, you log on to the target system, and run the

  50944. 'gdbserver' program.  You must tell it (a) how to communicate with GDB,

  50945. (b) the name of your program, and (c) its arguments.  The general syntax

  50946. is:

  50947. 

  50948.      target> gdbserver COMM PROGRAM [ARGS ...]

  50949. 

  50950.    For example, using a serial port, you might say:

  50951. 

  50952.      target> gdbserver /dev/com1 emacs foo.txt

  50953. 

  50954.    This tells 'gdbserver' to debug emacs with an argument of foo.txt,

  50955. and to communicate with GDB via '/dev/com1'.  'gdbserver' now waits

  50956. patiently for the host GDB to communicate with it.

  50957. 

  50958.    To use a TCP connection, you could say:

  50959. 

  50960.      target> gdbserver host:2345 emacs foo.txt

  50961. 

  50962.    This says pretty much the same thing as the last example, except that

  50963. we are going to communicate with the 'host' GDB via TCP. The 'host:2345'

  50964. argument means that we are expecting to see a TCP connection from 'host'

  50965. to local TCP port 2345.  (Currently, the 'host' part is ignored.)  You

  50966. can choose any number you want for the port number as long as it does

  50967. not conflict with any existing TCP ports on the target system.  This

  50968. same port number must be used in the host GDBs 'target remote' command,

  50969. which will be described shortly.  Note that if you chose a port number

  50970. that conflicts with another service, 'gdbserver' will print an error

  50971. message and exit.

  50972. 

  50973.    'gdbserver' can also attach to running programs.  This is

  50974. accomplished via the '--attach' argument.  The syntax is:

  50975. 

  50976.      target> gdbserver --attach COMM PID

  50977. 

  50978.    PID is the process ID of a currently running process.  It isn't

  50979. necessary to point 'gdbserver' at a binary for the running process.

  50980. 

  50981.    To start 'gdbserver' without supplying an initial command to run or

  50982. process ID to attach, use the '--multi' command line option.  In such

  50983. case you should connect using 'target extended-remote' to start the

  50984. program you want to debug.

  50985. 

  50986.      target> gdbserver --multi COMM

  50987. 

  50988. Usage (host side)

  50989. -----------------

  50990. 

  50991. You need an unstripped copy of the target program on your host system,

  50992. since GDB needs to examine its symbol tables and such.  Start up GDB as

  50993. you normally would, with the target program as the first argument.  (You

  50994. may need to use the '--baud' option if the serial line is running at

  50995. anything except 9600 baud.)  That is 'gdb TARGET-PROG', or 'gdb --baud

  50996. BAUD TARGET-PROG'.  After that, the only new command you need to know

  50997. about is 'target remote' (or 'target extended-remote').  Its argument is

  50998. either a device name (usually a serial device, like '/dev/ttyb'), or a

  50999. 'HOST:PORT' descriptor.  For example:

  51000. 

  51001.      (gdb) target remote /dev/ttyb

  51002. 

  51003. communicates with the server via serial line '/dev/ttyb', and:

  51004. 

  51005.      (gdb) target remote the-target:2345

  51006. 

  51007. communicates via a TCP connection to port 2345 on host 'the-target',

  51008. where you previously started up 'gdbserver' with the same port number.

  51009. Note that for TCP connections, you must start up 'gdbserver' prior to

  51010. using the 'target remote' command, otherwise you may get an error that

  51011. looks something like 'Connection refused'.

  51012. 

  51013.    'gdbserver' can also debug multiple inferiors at once, described in

  51014. *note Inferiors Connections and Programs::.  In such case use the

  51015. 'extended-remote' GDB command variant:

  51016. 

  51017.      (gdb) target extended-remote the-target:2345

  51018. 

  51019.    The 'gdbserver' option '--multi' may or may not be used in such case.

  51020. 

  51021.    There are three different modes for invoking 'gdbserver':

  51022. 

  51023.    * Debug a specific program specified by its program name:

  51024. 

  51025.           gdbserver COMM PROG [ARGS...]

  51026. 

  51027.      The COMM parameter specifies how should the server communicate with

  51028.      GDB; it is either a device name (to use a serial line), a TCP port

  51029.      number (':1234'), or '-' or 'stdio' to use stdin/stdout of

  51030.      'gdbserver'.  Specify the name of the program to debug in PROG.

  51031.      Any remaining arguments will be passed to the program verbatim.

  51032.      When the program exits, GDB will close the connection, and

  51033.      'gdbserver' will exit.

  51034. 

  51035.    * Debug a specific program by specifying the process ID of a running

  51036.      program:

  51037. 

  51038.           gdbserver --attach COMM PID

  51039. 

  51040.      The COMM parameter is as described above.  Supply the process ID of

  51041.      a running program in PID; GDB will do everything else.  Like with

  51042.      the previous mode, when the process PID exits, GDB will close the

  51043.      connection, and 'gdbserver' will exit.

  51044. 

  51045.    * Multi-process mode - debug more than one program/process:

  51046. 

  51047.           gdbserver --multi COMM

  51048. 

  51049.      In this mode, GDB can instruct 'gdbserver' which command(s) to run.

  51050.      Unlike the other 2 modes, GDB will not close the connection when a

  51051.      process being debugged exits, so you can debug several processes in

  51052.      the same session.

  51053. 

  51054.    In each of the modes you may specify these options:

  51055. 

  51056. '--help'

  51057.      List all options, with brief explanations.

  51058. 

  51059. '--version'

  51060.      This option causes 'gdbserver' to print its version number and

  51061.      exit.

  51062. 

  51063. '--attach'

  51064.      'gdbserver' will attach to a running program.  The syntax is:

  51065. 

  51066.           target> gdbserver --attach COMM PID

  51067. 

  51068.      PID is the process ID of a currently running process.  It isn't

  51069.      necessary to point 'gdbserver' at a binary for the running process.

  51070. 

  51071. '--multi'

  51072.      To start 'gdbserver' without supplying an initial command to run or

  51073.      process ID to attach, use this command line option.  Then you can

  51074.      connect using 'target extended-remote' and start the program you

  51075.      want to debug.  The syntax is:

  51076. 

  51077.           target> gdbserver --multi COMM

  51078. 

  51079. '--debug'

  51080.      Instruct 'gdbserver' to display extra status information about the

  51081.      debugging process.  This option is intended for 'gdbserver'

  51082.      development and for bug reports to the developers.

  51083. 

  51084. '--remote-debug'

  51085.      Instruct 'gdbserver' to display remote protocol debug output.  This

  51086.      option is intended for 'gdbserver' development and for bug reports

  51087.      to the developers.

  51088. 

  51089. '--debug-file=FILENAME'

  51090.      Instruct 'gdbserver' to send any debug output to the given

  51091.      FILENAME.  This option is intended for 'gdbserver' development and

  51092.      for bug reports to the developers.

  51093. 

  51094. '--debug-format=option1[,option2,...]'

  51095.      Instruct 'gdbserver' to include extra information in each line of

  51096.      debugging output.  *Note Other Command-Line Arguments for

  51097.      gdbserver::.

  51098. 

  51099. '--wrapper'

  51100.      Specify a wrapper to launch programs for debugging.  The option

  51101.      should be followed by the name of the wrapper, then any

  51102.      command-line arguments to pass to the wrapper, then '--' indicating

  51103.      the end of the wrapper arguments.

  51104. 

  51105. '--once'

  51106.      By default, 'gdbserver' keeps the listening TCP port open, so that

  51107.      additional connections are possible.  However, if you start

  51108.      'gdbserver' with the '--once' option, it will stop listening for

  51109.      any further connection attempts after connecting to the first GDB

  51110.      session.

  51111. 

  51112. 

  51113. File: gdb.info,  Node: gcore man,  Next: gdbinit man,  Prev: gdbserver man,  Up: Man Pages

  51114. 

  51115. gcore

  51116. =====

  51117. 

  51118. gcore [-a] [-o PREFIX] PID1 [PID2...PIDN]

  51119. 

  51120.    Generate core dumps of one or more running programs with process IDs

  51121. PID1, PID2, etc.  A core file produced by 'gcore' is equivalent to one

  51122. produced by the kernel when the process crashes (and when 'ulimit -c'

  51123. was used to set up an appropriate core dump limit).  However, unlike

  51124. after a crash, after 'gcore' finishes its job the program remains

  51125. running without any change.

  51126. 

  51127. '-a'

  51128.      Dump all memory mappings.  The actual effect of this option depends

  51129.      on the Operating System.  On GNU/Linux, it will disable

  51130.      'use-coredump-filter' (*note set use-coredump-filter::) and enable

  51131.      'dump-excluded-mappings' (*note set dump-excluded-mappings::).

  51132. 

  51133. '-o PREFIX'

  51134.      The optional argument PREFIX specifies the prefix to be used when

  51135.      composing the file names of the core dumps.  The file name is

  51136.      composed as 'PREFIX.PID', where PID is the process ID of the

  51137.      running program being analyzed by 'gcore'.  If not specified,

  51138.      PREFIX defaults to GCORE.

  51139. 

  51140. 

  51141. File: gdb.info,  Node: gdbinit man,  Next: gdb-add-index man,  Prev: gcore man,  Up: Man Pages

  51142. 

  51143. gdbinit

  51144. =======

  51145. 

  51146. /tmp/jenkins-GCC-10-pipeline-48_20201124_1606180639/install-native/x86_64-apple-darwin10/arm-none-eabi/lib/gdbinit

  51147. 

  51148. 

  51149. ~/.gdbinit

  51150. 

  51151. ./.gdbinit

  51152. 

  51153.    These files contain GDB commands to automatically execute during GDB

  51154. startup.  The lines of contents are canned sequences of commands,

  51155. described in *note Sequences::.

  51156. 

  51157.    Please read more in *note Startup::.

  51158. 

  51159. '/tmp/jenkins-GCC-10-pipeline-48_20201124_1606180639/install-native/x86_64-apple-darwin10/arm-none-eabi/lib/gdbinit'

  51160.      System-wide initialization file.  It is executed unless user

  51161.      specified GDB option '-nx' or '-n'.  See more in

  51162. '(not enabled with --with-system-gdbinit-dir during compilation)'

  51163.      System-wide initialization directory.  All files in this directory

  51164.      are executed on startup unless user specified GDB option '-nx' or

  51165.      '-n', as long as they have a recognized file extension.  See more

  51166.      in *note System-wide configuration::.

  51167. 

  51168. '~/.gdbinit'

  51169.      User initialization file.  It is executed unless user specified GDB

  51170.      options '-nx', '-n' or '-nh'.

  51171. 

  51172. './.gdbinit'

  51173.      Initialization file for current directory.  It may need to be

  51174.      enabled with GDB security command 'set auto-load local-gdbinit'.

  51175.      See more in *note Init File in the Current Directory::.

  51176. 

  51177. 

  51178. File: gdb.info,  Node: gdb-add-index man,  Prev: gdbinit man,  Up: Man Pages

  51179. 

  51180. gdb-add-index

  51181. =============

  51182. 

  51183. gdb-add-index FILENAME

  51184. 

  51185.    When GDB finds a symbol file, it scans the symbols in the file in

  51186. order to construct an internal symbol table.  This lets most GDB

  51187. operations work quickly-at the cost of a delay early on.  For large

  51188. programs, this delay can be quite lengthy, so GDB provides a way to

  51189. build an index, which speeds up startup.

  51190. 

  51191.    To determine whether a file contains such an index, use the command

  51192. 'readelf -S filename': the index is stored in a section named

  51193. '.gdb_index'.  The index file can only be produced on systems which use

  51194. ELF binaries and DWARF debug information (i.e., sections named

  51195. '.debug_*').

  51196. 

  51197.    'gdb-add-index' uses GDB and 'objdump' found in the 'PATH'

  51198. environment variable.  If you want to use different versions of these

  51199. programs, you can specify them through the 'GDB' and 'OBJDUMP'

  51200. environment variables.

  51201. 

  51202.    See more in *note Index Files::.

  51203. 

  51204. 

  51205. File: gdb.info,  Node: Copying,  Next: GNU Free Documentation License,  Prev: Man Pages,  Up: Top

  51206. 

  51207. Appendix L GNU GENERAL PUBLIC LICENSE

  51208. *************************************

  51209. 

  51210.                         Version 3, 29 June 2007

  51211. 

  51212.      Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>

  51213. 

  51214.      Everyone is permitted to copy and distribute verbatim copies of this

  51215.      license document, but changing it is not allowed.

  51216. 

  51217. Preamble

  51218. ========

  51219. 

  51220. The GNU General Public License is a free, copyleft license for software

  51221. and other kinds of works.

  51222. 

  51223.    The licenses for most software and other practical works are designed

  51224. to take away your freedom to share and change the works.  By contrast,

  51225. the GNU General Public License is intended to guarantee your freedom to

  51226. share and change all versions of a program--to make sure it remains free

  51227. software for all its users.  We, the Free Software Foundation, use the

  51228. GNU General Public License for most of our software; it applies also to

  51229. any other work released this way by its authors.  You can apply it to

  51230. your programs, too.

  51231. 

  51232.    When we speak of free software, we are referring to freedom, not

  51233. price.  Our General Public Licenses are designed to make sure that you

  51234. have the freedom to distribute copies of free software (and charge for

  51235. them if you wish), that you receive source code or can get it if you

  51236. want it, that you can change the software or use pieces of it in new

  51237. free programs, and that you know you can do these things.

  51238. 

  51239.    To protect your rights, we need to prevent others from denying you

  51240. these rights or asking you to surrender the rights.  Therefore, you have

  51241. certain responsibilities if you distribute copies of the software, or if

  51242. you modify it: responsibilities to respect the freedom of others.

  51243. 

  51244.    For example, if you distribute copies of such a program, whether

  51245. gratis or for a fee, you must pass on to the recipients the same

  51246. freedoms that you received.  You must make sure that they, too, receive

  51247. or can get the source code.  And you must show them these terms so they

  51248. know their rights.

  51249. 

  51250.    Developers that use the GNU GPL protect your rights with two steps:

  51251. (1) assert copyright on the software, and (2) offer you this License

  51252. giving you legal permission to copy, distribute and/or modify it.

  51253. 

  51254.    For the developers' and authors' protection, the GPL clearly explains

  51255. that there is no warranty for this free software.  For both users' and

  51256. authors' sake, the GPL requires that modified versions be marked as

  51257. changed, so that their problems will not be attributed erroneously to

  51258. authors of previous versions.

  51259. 

  51260.    Some devices are designed to deny users access to install or run

  51261. modified versions of the software inside them, although the manufacturer

  51262. can do so.  This is fundamentally incompatible with the aim of

  51263. protecting users' freedom to change the software.  The systematic

  51264. pattern of such abuse occurs in the area of products for individuals to

  51265. use, which is precisely where it is most unacceptable.  Therefore, we

  51266. have designed this version of the GPL to prohibit the practice for those

  51267. products.  If such problems arise substantially in other domains, we

  51268. stand ready to extend this provision to those domains in future versions

  51269. of the GPL, as needed to protect the freedom of users.

  51270. 

  51271.    Finally, every program is threatened constantly by software patents.

  51272. States should not allow patents to restrict development and use of

  51273. software on general-purpose computers, but in those that do, we wish to

  51274. avoid the special danger that patents applied to a free program could

  51275. make it effectively proprietary.  To prevent this, the GPL assures that

  51276. patents cannot be used to render the program non-free.

  51277. 

  51278.    The precise terms and conditions for copying, distribution and

  51279. modification follow.

  51280. 

  51281. TERMS AND CONDITIONS

  51282. ====================

  51283. 

  51284.   0. Definitions.

  51285. 

  51286.      "This License" refers to version 3 of the GNU General Public

  51287.      License.

  51288. 

  51289.      "Copyright" also means copyright-like laws that apply to other

  51290.      kinds of works, such as semiconductor masks.

  51291. 

  51292.      "The Program" refers to any copyrightable work licensed under this

  51293.      License.  Each licensee is addressed as "you".  "Licensees" and

  51294.      "recipients" may be individuals or organizations.

  51295. 

  51296.      To "modify" a work means to copy from or adapt all or part of the

  51297.      work in a fashion requiring copyright permission, other than the

  51298.      making of an exact copy.  The resulting work is called a "modified

  51299.      version" of the earlier work or a work "based on" the earlier work.

  51300. 

  51301.      A "covered work" means either the unmodified Program or a work

  51302.      based on the Program.

  51303. 

  51304.      To "propagate" a work means to do anything with it that, without

  51305.      permission, would make you directly or secondarily liable for

  51306.      infringement under applicable copyright law, except executing it on

  51307.      a computer or modifying a private copy.  Propagation includes

  51308.      copying, distribution (with or without modification), making

  51309.      available to the public, and in some countries other activities as

  51310.      well.

  51311. 

  51312.      To "convey" a work means any kind of propagation that enables other

  51313.      parties to make or receive copies.  Mere interaction with a user

  51314.      through a computer network, with no transfer of a copy, is not

  51315.      conveying.

  51316. 

  51317.      An interactive user interface displays "Appropriate Legal Notices"

  51318.      to the extent that it includes a convenient and prominently visible

  51319.      feature that (1) displays an appropriate copyright notice, and (2)

  51320.      tells the user that there is no warranty for the work (except to

  51321.      the extent that warranties are provided), that licensees may convey

  51322.      the work under this License, and how to view a copy of this

  51323.      License.  If the interface presents a list of user commands or

  51324.      options, such as a menu, a prominent item in the list meets this

  51325.      criterion.

  51326. 

  51327.   1. Source Code.

  51328. 

  51329.      The "source code" for a work means the preferred form of the work

  51330.      for making modifications to it.  "Object code" means any non-source

  51331.      form of a work.

  51332. 

  51333.      A "Standard Interface" means an interface that either is an

  51334.      official standard defined by a recognized standards body, or, in

  51335.      the case of interfaces specified for a particular programming

  51336.      language, one that is widely used among developers working in that

  51337.      language.

  51338. 

  51339.      The "System Libraries" of an executable work include anything,

  51340.      other than the work as a whole, that (a) is included in the normal

  51341.      form of packaging a Major Component, but which is not part of that

  51342.      Major Component, and (b) serves only to enable use of the work with

  51343.      that Major Component, or to implement a Standard Interface for

  51344.      which an implementation is available to the public in source code

  51345.      form.  A "Major Component", in this context, means a major

  51346.      essential component (kernel, window system, and so on) of the

  51347.      specific operating system (if any) on which the executable work

  51348.      runs, or a compiler used to produce the work, or an object code

  51349.      interpreter used to run it.

  51350. 

  51351.      The "Corresponding Source" for a work in object code form means all

  51352.      the source code needed to generate, install, and (for an executable

  51353.      work) run the object code and to modify the work, including scripts

  51354.      to control those activities.  However, it does not include the

  51355.      work's System Libraries, or general-purpose tools or generally

  51356.      available free programs which are used unmodified in performing

  51357.      those activities but which are not part of the work.  For example,

  51358.      Corresponding Source includes interface definition files associated

  51359.      with source files for the work, and the source code for shared

  51360.      libraries and dynamically linked subprograms that the work is

  51361.      specifically designed to require, such as by intimate data

  51362.      communication or control flow between those subprograms and other

  51363.      parts of the work.

  51364. 

  51365.      The Corresponding Source need not include anything that users can

  51366.      regenerate automatically from other parts of the Corresponding

  51367.      Source.

  51368. 

  51369.      The Corresponding Source for a work in source code form is that

  51370.      same work.

  51371. 

  51372.   2. Basic Permissions.

  51373. 

  51374.      All rights granted under this License are granted for the term of

  51375.      copyright on the Program, and are irrevocable provided the stated

  51376.      conditions are met.  This License explicitly affirms your unlimited

  51377.      permission to run the unmodified Program.  The output from running

  51378.      a covered work is covered by this License only if the output, given

  51379.      its content, constitutes a covered work.  This License acknowledges

  51380.      your rights of fair use or other equivalent, as provided by

  51381.      copyright law.

  51382. 

  51383.      You may make, run and propagate covered works that you do not

  51384.      convey, without conditions so long as your license otherwise

  51385.      remains in force.  You may convey covered works to others for the

  51386.      sole purpose of having them make modifications exclusively for you,

  51387.      or provide you with facilities for running those works, provided

  51388.      that you comply with the terms of this License in conveying all

  51389.      material for which you do not control copyright.  Those thus making

  51390.      or running the covered works for you must do so exclusively on your

  51391.      behalf, under your direction and control, on terms that prohibit

  51392.      them from making any copies of your copyrighted material outside

  51393.      their relationship with you.

  51394. 

  51395.      Conveying under any other circumstances is permitted solely under

  51396.      the conditions stated below.  Sublicensing is not allowed; section

  51397.      10 makes it unnecessary.

  51398. 

  51399.   3. Protecting Users' Legal Rights From Anti-Circumvention Law.

  51400. 

  51401.      No covered work shall be deemed part of an effective technological

  51402.      measure under any applicable law fulfilling obligations under

  51403.      article 11 of the WIPO copyright treaty adopted on 20 December

  51404.      1996, or similar laws prohibiting or restricting circumvention of

  51405.      such measures.

  51406. 

  51407.      When you convey a covered work, you waive any legal power to forbid

  51408.      circumvention of technological measures to the extent such

  51409.      circumvention is effected by exercising rights under this License

  51410.      with respect to the covered work, and you disclaim any intention to

  51411.      limit operation or modification of the work as a means of

  51412.      enforcing, against the work's users, your or third parties' legal

  51413.      rights to forbid circumvention of technological measures.

  51414. 

  51415.   4. Conveying Verbatim Copies.

  51416. 

  51417.      You may convey verbatim copies of the Program's source code as you

  51418.      receive it, in any medium, provided that you conspicuously and

  51419.      appropriately publish on each copy an appropriate copyright notice;

  51420.      keep intact all notices stating that this License and any

  51421.      non-permissive terms added in accord with section 7 apply to the

  51422.      code; keep intact all notices of the absence of any warranty; and

  51423.      give all recipients a copy of this License along with the Program.

  51424. 

  51425.      You may charge any price or no price for each copy that you convey,

  51426.      and you may offer support or warranty protection for a fee.

  51427. 

  51428.   5. Conveying Modified Source Versions.

  51429. 

  51430.      You may convey a work based on the Program, or the modifications to

  51431.      produce it from the Program, in the form of source code under the

  51432.      terms of section 4, provided that you also meet all of these

  51433.      conditions:

  51434. 

  51435.        a. The work must carry prominent notices stating that you

  51436.           modified it, and giving a relevant date.

  51437. 

  51438.        b. The work must carry prominent notices stating that it is

  51439.           released under this License and any conditions added under

  51440.           section 7.  This requirement modifies the requirement in

  51441.           section 4 to "keep intact all notices".

  51442. 

  51443.        c. You must license the entire work, as a whole, under this

  51444.           License to anyone who comes into possession of a copy.  This

  51445.           License will therefore apply, along with any applicable

  51446.           section 7 additional terms, to the whole of the work, and all

  51447.           its parts, regardless of how they are packaged.  This License

  51448.           gives no permission to license the work in any other way, but

  51449.           it does not invalidate such permission if you have separately

  51450.           received it.

  51451. 

  51452.        d. If the work has interactive user interfaces, each must display

  51453.           Appropriate Legal Notices; however, if the Program has

  51454.           interactive interfaces that do not display Appropriate Legal

  51455.           Notices, your work need not make them do so.

  51456. 

  51457.      A compilation of a covered work with other separate and independent

  51458.      works, which are not by their nature extensions of the covered

  51459.      work, and which are not combined with it such as to form a larger

  51460.      program, in or on a volume of a storage or distribution medium, is

  51461.      called an "aggregate" if the compilation and its resulting

  51462.      copyright are not used to limit the access or legal rights of the

  51463.      compilation's users beyond what the individual works permit.

  51464.      Inclusion of a covered work in an aggregate does not cause this

  51465.      License to apply to the other parts of the aggregate.

  51466. 

  51467.   6. Conveying Non-Source Forms.

  51468. 

  51469.      You may convey a covered work in object code form under the terms

  51470.      of sections 4 and 5, provided that you also convey the

  51471.      machine-readable Corresponding Source under the terms of this

  51472.      License, in one of these ways:

  51473. 

  51474.        a. Convey the object code in, or embodied in, a physical product

  51475.           (including a physical distribution medium), accompanied by the

  51476.           Corresponding Source fixed on a durable physical medium

  51477.           customarily used for software interchange.

  51478. 

  51479.        b. Convey the object code in, or embodied in, a physical product

  51480.           (including a physical distribution medium), accompanied by a

  51481.           written offer, valid for at least three years and valid for as

  51482.           long as you offer spare parts or customer support for that

  51483.           product model, to give anyone who possesses the object code

  51484.           either (1) a copy of the Corresponding Source for all the

  51485.           software in the product that is covered by this License, on a

  51486.           durable physical medium customarily used for software

  51487.           interchange, for a price no more than your reasonable cost of

  51488.           physically performing this conveying of source, or (2) access

  51489.           to copy the Corresponding Source from a network server at no

  51490.           charge.

  51491. 

  51492.        c. Convey individual copies of the object code with a copy of the

  51493.           written offer to provide the Corresponding Source.  This

  51494.           alternative is allowed only occasionally and noncommercially,

  51495.           and only if you received the object code with such an offer,

  51496.           in accord with subsection 6b.

  51497. 

  51498.        d. Convey the object code by offering access from a designated

  51499.           place (gratis or for a charge), and offer equivalent access to

  51500.           the Corresponding Source in the same way through the same

  51501.           place at no further charge.  You need not require recipients

  51502.           to copy the Corresponding Source along with the object code.

  51503.           If the place to copy the object code is a network server, the

  51504.           Corresponding Source may be on a different server (operated by

  51505.           you or a third party) that supports equivalent copying

  51506.           facilities, provided you maintain clear directions next to the

  51507.           object code saying where to find the Corresponding Source.

  51508.           Regardless of what server hosts the Corresponding Source, you

  51509.           remain obligated to ensure that it is available for as long as

  51510.           needed to satisfy these requirements.

  51511. 

  51512.        e. Convey the object code using peer-to-peer transmission,

  51513.           provided you inform other peers where the object code and

  51514.           Corresponding Source of the work are being offered to the

  51515.           general public at no charge under subsection 6d.

  51516. 

  51517.      A separable portion of the object code, whose source code is

  51518.      excluded from the Corresponding Source as a System Library, need

  51519.      not be included in conveying the object code work.

  51520. 

  51521.      A "User Product" is either (1) a "consumer product", which means

  51522.      any tangible personal property which is normally used for personal,

  51523.      family, or household purposes, or (2) anything designed or sold for

  51524.      incorporation into a dwelling.  In determining whether a product is

  51525.      a consumer product, doubtful cases shall be resolved in favor of

  51526.      coverage.  For a particular product received by a particular user,

  51527.      "normally used" refers to a typical or common use of that class of

  51528.      product, regardless of the status of the particular user or of the

  51529.      way in which the particular user actually uses, or expects or is

  51530.      expected to use, the product.  A product is a consumer product

  51531.      regardless of whether the product has substantial commercial,

  51532.      industrial or non-consumer uses, unless such uses represent the

  51533.      only significant mode of use of the product.

  51534. 

  51535.      "Installation Information" for a User Product means any methods,

  51536.      procedures, authorization keys, or other information required to

  51537.      install and execute modified versions of a covered work in that

  51538.      User Product from a modified version of its Corresponding Source.

  51539.      The information must suffice to ensure that the continued

  51540.      functioning of the modified object code is in no case prevented or

  51541.      interfered with solely because modification has been made.

  51542. 

  51543.      If you convey an object code work under this section in, or with,

  51544.      or specifically for use in, a User Product, and the conveying

  51545.      occurs as part of a transaction in which the right of possession

  51546.      and use of the User Product is transferred to the recipient in

  51547.      perpetuity or for a fixed term (regardless of how the transaction

  51548.      is characterized), the Corresponding Source conveyed under this

  51549.      section must be accompanied by the Installation Information.  But

  51550.      this requirement does not apply if neither you nor any third party

  51551.      retains the ability to install modified object code on the User

  51552.      Product (for example, the work has been installed in ROM).

  51553. 

  51554.      The requirement to provide Installation Information does not

  51555.      include a requirement to continue to provide support service,

  51556.      warranty, or updates for a work that has been modified or installed

  51557.      by the recipient, or for the User Product in which it has been

  51558.      modified or installed.  Access to a network may be denied when the

  51559.      modification itself materially and adversely affects the operation

  51560.      of the network or violates the rules and protocols for

  51561.      communication across the network.

  51562. 

  51563.      Corresponding Source conveyed, and Installation Information

  51564.      provided, in accord with this section must be in a format that is

  51565.      publicly documented (and with an implementation available to the

  51566.      public in source code form), and must require no special password

  51567.      or key for unpacking, reading or copying.

  51568. 

  51569.   7. Additional Terms.

  51570. 

  51571.      "Additional permissions" are terms that supplement the terms of

  51572.      this License by making exceptions from one or more of its

  51573.      conditions.  Additional permissions that are applicable to the

  51574.      entire Program shall be treated as though they were included in

  51575.      this License, to the extent that they are valid under applicable

  51576.      law.  If additional permissions apply only to part of the Program,

  51577.      that part may be used separately under those permissions, but the

  51578.      entire Program remains governed by this License without regard to

  51579.      the additional permissions.

  51580. 

  51581.      When you convey a copy of a covered work, you may at your option

  51582.      remove any additional permissions from that copy, or from any part

  51583.      of it.  (Additional permissions may be written to require their own

  51584.      removal in certain cases when you modify the work.)  You may place

  51585.      additional permissions on material, added by you to a covered work,

  51586.      for which you have or can give appropriate copyright permission.

  51587. 

  51588.      Notwithstanding any other provision of this License, for material

  51589.      you add to a covered work, you may (if authorized by the copyright

  51590.      holders of that material) supplement the terms of this License with

  51591.      terms:

  51592. 

  51593.        a. Disclaiming warranty or limiting liability differently from

  51594.           the terms of sections 15 and 16 of this License; or

  51595. 

  51596.        b. Requiring preservation of specified reasonable legal notices

  51597.           or author attributions in that material or in the Appropriate

  51598.           Legal Notices displayed by works containing it; or

  51599. 

  51600.        c. Prohibiting misrepresentation of the origin of that material,

  51601.           or requiring that modified versions of such material be marked

  51602.           in reasonable ways as different from the original version; or

  51603. 

  51604.        d. Limiting the use for publicity purposes of names of licensors

  51605.           or authors of the material; or

  51606. 

  51607.        e. Declining to grant rights under trademark law for use of some

  51608.           trade names, trademarks, or service marks; or

  51609. 

  51610.        f. Requiring indemnification of licensors and authors of that

  51611.           material by anyone who conveys the material (or modified

  51612.           versions of it) with contractual assumptions of liability to

  51613.           the recipient, for any liability that these contractual

  51614.           assumptions directly impose on those licensors and authors.

  51615. 

  51616.      All other non-permissive additional terms are considered "further

  51617.      restrictions" within the meaning of section 10.  If the Program as

  51618.      you received it, or any part of it, contains a notice stating that

  51619.      it is governed by this License along with a term that is a further

  51620.      restriction, you may remove that term.  If a license document

  51621.      contains a further restriction but permits relicensing or conveying

  51622.      under this License, you may add to a covered work material governed

  51623.      by the terms of that license document, provided that the further

  51624.      restriction does not survive such relicensing or conveying.

  51625. 

  51626.      If you add terms to a covered work in accord with this section, you

  51627.      must place, in the relevant source files, a statement of the

  51628.      additional terms that apply to those files, or a notice indicating

  51629.      where to find the applicable terms.

  51630. 

  51631.      Additional terms, permissive or non-permissive, may be stated in

  51632.      the form of a separately written license, or stated as exceptions;

  51633.      the above requirements apply either way.

  51634. 

  51635.   8. Termination.

  51636. 

  51637.      You may not propagate or modify a covered work except as expressly

  51638.      provided under this License.  Any attempt otherwise to propagate or

  51639.      modify it is void, and will automatically terminate your rights

  51640.      under this License (including any patent licenses granted under the

  51641.      third paragraph of section 11).

  51642. 

  51643.      However, if you cease all violation of this License, then your

  51644.      license from a particular copyright holder is reinstated (a)

  51645.      provisionally, unless and until the copyright holder explicitly and

  51646.      finally terminates your license, and (b) permanently, if the

  51647.      copyright holder fails to notify you of the violation by some

  51648.      reasonable means prior to 60 days after the cessation.

  51649. 

  51650.      Moreover, your license from a particular copyright holder is

  51651.      reinstated permanently if the copyright holder notifies you of the

  51652.      violation by some reasonable means, this is the first time you have

  51653.      received notice of violation of this License (for any work) from

  51654.      that copyright holder, and you cure the violation prior to 30 days

  51655.      after your receipt of the notice.

  51656. 

  51657.      Termination of your rights under this section does not terminate

  51658.      the licenses of parties who have received copies or rights from you

  51659.      under this License.  If your rights have been terminated and not

  51660.      permanently reinstated, you do not qualify to receive new licenses

  51661.      for the same material under section 10.

  51662. 

  51663.   9. Acceptance Not Required for Having Copies.

  51664. 

  51665.      You are not required to accept this License in order to receive or

  51666.      run a copy of the Program.  Ancillary propagation of a covered work

  51667.      occurring solely as a consequence of using peer-to-peer

  51668.      transmission to receive a copy likewise does not require

  51669.      acceptance.  However, nothing other than this License grants you

  51670.      permission to propagate or modify any covered work.  These actions

  51671.      infringe copyright if you do not accept this License.  Therefore,

  51672.      by modifying or propagating a covered work, you indicate your

  51673.      acceptance of this License to do so.

  51674. 

  51675.   10. Automatic Licensing of Downstream Recipients.

  51676. 

  51677.      Each time you convey a covered work, the recipient automatically

  51678.      receives a license from the original licensors, to run, modify and

  51679.      propagate that work, subject to this License.  You are not

  51680.      responsible for enforcing compliance by third parties with this

  51681.      License.

  51682. 

  51683.      An "entity transaction" is a transaction transferring control of an

  51684.      organization, or substantially all assets of one, or subdividing an

  51685.      organization, or merging organizations.  If propagation of a

  51686.      covered work results from an entity transaction, each party to that

  51687.      transaction who receives a copy of the work also receives whatever

  51688.      licenses to the work the party's predecessor in interest had or

  51689.      could give under the previous paragraph, plus a right to possession

  51690.      of the Corresponding Source of the work from the predecessor in

  51691.      interest, if the predecessor has it or can get it with reasonable

  51692.      efforts.

  51693. 

  51694.      You may not impose any further restrictions on the exercise of the

  51695.      rights granted or affirmed under this License.  For example, you

  51696.      may not impose a license fee, royalty, or other charge for exercise

  51697.      of rights granted under this License, and you may not initiate

  51698.      litigation (including a cross-claim or counterclaim in a lawsuit)

  51699.      alleging that any patent claim is infringed by making, using,

  51700.      selling, offering for sale, or importing the Program or any portion

  51701.      of it.

  51702. 

  51703.   11. Patents.

  51704. 

  51705.      A "contributor" is a copyright holder who authorizes use under this

  51706.      License of the Program or a work on which the Program is based.

  51707.      The work thus licensed is called the contributor's "contributor

  51708.      version".

  51709. 

  51710.      A contributor's "essential patent claims" are all patent claims

  51711.      owned or controlled by the contributor, whether already acquired or

  51712.      hereafter acquired, that would be infringed by some manner,

  51713.      permitted by this License, of making, using, or selling its

  51714.      contributor version, but do not include claims that would be

  51715.      infringed only as a consequence of further modification of the

  51716.      contributor version.  For purposes of this definition, "control"

  51717.      includes the right to grant patent sublicenses in a manner

  51718.      consistent with the requirements of this License.

  51719. 

  51720.      Each contributor grants you a non-exclusive, worldwide,

  51721.      royalty-free patent license under the contributor's essential

  51722.      patent claims, to make, use, sell, offer for sale, import and

  51723.      otherwise run, modify and propagate the contents of its contributor

  51724.      version.

  51725. 

  51726.      In the following three paragraphs, a "patent license" is any

  51727.      express agreement or commitment, however denominated, not to

  51728.      enforce a patent (such as an express permission to practice a

  51729.      patent or covenant not to sue for patent infringement).  To "grant"

  51730.      such a patent license to a party means to make such an agreement or

  51731.      commitment not to enforce a patent against the party.

  51732. 

  51733.      If you convey a covered work, knowingly relying on a patent

  51734.      license, and the Corresponding Source of the work is not available

  51735.      for anyone to copy, free of charge and under the terms of this

  51736.      License, through a publicly available network server or other

  51737.      readily accessible means, then you must either (1) cause the

  51738.      Corresponding Source to be so available, or (2) arrange to deprive

  51739.      yourself of the benefit of the patent license for this particular

  51740.      work, or (3) arrange, in a manner consistent with the requirements

  51741.      of this License, to extend the patent license to downstream

  51742.      recipients.  "Knowingly relying" means you have actual knowledge

  51743.      that, but for the patent license, your conveying the covered work

  51744.      in a country, or your recipient's use of the covered work in a

  51745.      country, would infringe one or more identifiable patents in that

  51746.      country that you have reason to believe are valid.

  51747. 

  51748.      If, pursuant to or in connection with a single transaction or

  51749.      arrangement, you convey, or propagate by procuring conveyance of, a

  51750.      covered work, and grant a patent license to some of the parties

  51751.      receiving the covered work authorizing them to use, propagate,

  51752.      modify or convey a specific copy of the covered work, then the

  51753.      patent license you grant is automatically extended to all

  51754.      recipients of the covered work and works based on it.

  51755. 

  51756.      A patent license is "discriminatory" if it does not include within

  51757.      the scope of its coverage, prohibits the exercise of, or is

  51758.      conditioned on the non-exercise of one or more of the rights that

  51759.      are specifically granted under this License.  You may not convey a

  51760.      covered work if you are a party to an arrangement with a third

  51761.      party that is in the business of distributing software, under which

  51762.      you make payment to the third party based on the extent of your

  51763.      activity of conveying the work, and under which the third party

  51764.      grants, to any of the parties who would receive the covered work

  51765.      from you, a discriminatory patent license (a) in connection with

  51766.      copies of the covered work conveyed by you (or copies made from

  51767.      those copies), or (b) primarily for and in connection with specific

  51768.      products or compilations that contain the covered work, unless you

  51769.      entered into that arrangement, or that patent license was granted,

  51770.      prior to 28 March 2007.

  51771. 

  51772.      Nothing in this License shall be construed as excluding or limiting

  51773.      any implied license or other defenses to infringement that may

  51774.      otherwise be available to you under applicable patent law.

  51775. 

  51776.   12. No Surrender of Others' Freedom.

  51777. 

  51778.      If conditions are imposed on you (whether by court order, agreement

  51779.      or otherwise) that contradict the conditions of this License, they

  51780.      do not excuse you from the conditions of this License.  If you

  51781.      cannot convey a covered work so as to satisfy simultaneously your

  51782.      obligations under this License and any other pertinent obligations,

  51783.      then as a consequence you may not convey it at all.  For example,

  51784.      if you agree to terms that obligate you to collect a royalty for

  51785.      further conveying from those to whom you convey the Program, the

  51786.      only way you could satisfy both those terms and this License would

  51787.      be to refrain entirely from conveying the Program.

  51788. 

  51789.   13. Use with the GNU Affero General Public License.

  51790. 

  51791.      Notwithstanding any other provision of this License, you have

  51792.      permission to link or combine any covered work with a work licensed

  51793.      under version 3 of the GNU Affero General Public License into a

  51794.      single combined work, and to convey the resulting work.  The terms

  51795.      of this License will continue to apply to the part which is the

  51796.      covered work, but the special requirements of the GNU Affero

  51797.      General Public License, section 13, concerning interaction through

  51798.      a network will apply to the combination as such.

  51799. 

  51800.   14. Revised Versions of this License.

  51801. 

  51802.      The Free Software Foundation may publish revised and/or new

  51803.      versions of the GNU General Public License from time to time.  Such

  51804.      new versions will be similar in spirit to the present version, but

  51805.      may differ in detail to address new problems or concerns.

  51806. 

  51807.      Each version is given a distinguishing version number.  If the

  51808.      Program specifies that a certain numbered version of the GNU

  51809.      General Public License "or any later version" applies to it, you

  51810.      have the option of following the terms and conditions either of

  51811.      that numbered version or of any later version published by the Free

  51812.      Software Foundation.  If the Program does not specify a version

  51813.      number of the GNU General Public License, you may choose any

  51814.      version ever published by the Free Software Foundation.

  51815. 

  51816.      If the Program specifies that a proxy can decide which future

  51817.      versions of the GNU General Public License can be used, that

  51818.      proxy's public statement of acceptance of a version permanently

  51819.      authorizes you to choose that version for the Program.

  51820. 

  51821.      Later license versions may give you additional or different

  51822.      permissions.  However, no additional obligations are imposed on any

  51823.      author or copyright holder as a result of your choosing to follow a

  51824.      later version.

  51825. 

  51826.   15. Disclaimer of Warranty.

  51827. 

  51828.      THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY

  51829.      APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE

  51830.      COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"

  51831.      WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,

  51832.      INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

  51833.      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE

  51834.      RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.

  51835.      SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL

  51836.      NECESSARY SERVICING, REPAIR OR CORRECTION.

  51837. 

  51838.   16. Limitation of Liability.

  51839. 

  51840.      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN

  51841.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES

  51842.      AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR

  51843.      DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR

  51844.      CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE

  51845.      THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA

  51846.      BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD

  51847.      PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER

  51848.      PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF

  51849.      THE POSSIBILITY OF SUCH DAMAGES.

  51850. 

  51851.   17. Interpretation of Sections 15 and 16.

  51852. 

  51853.      If the disclaimer of warranty and limitation of liability provided

  51854.      above cannot be given local legal effect according to their terms,

  51855.      reviewing courts shall apply local law that most closely

  51856.      approximates an absolute waiver of all civil liability in

  51857.      connection with the Program, unless a warranty or assumption of

  51858.      liability accompanies a copy of the Program in return for a fee.

  51859. 

  51860. END OF TERMS AND CONDITIONS

  51861. ===========================

  51862. 

  51863. How to Apply These Terms to Your New Programs

  51864. =============================================

  51865. 

  51866. If you develop a new program, and you want it to be of the greatest

  51867. possible use to the public, the best way to achieve this is to make it

  51868. free software which everyone can redistribute and change under these

  51869. terms.

  51870. 

  51871.    To do so, attach the following notices to the program.  It is safest

  51872. to attach them to the start of each source file to most effectively

  51873. state the exclusion of warranty; and each file should have at least the

  51874. "copyright" line and a pointer to where the full notice is found.

  51875. 

  51876.      ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.

  51877.      Copyright (C) YEAR NAME OF AUTHOR

  51878. 

  51879.      This program is free software: you can redistribute it and/or modify

  51880.      it under the terms of the GNU General Public License as published by

  51881.      the Free Software Foundation, either version 3 of the License, or (at

  51882.      your option) any later version.

  51883. 

  51884.      This program is distributed in the hope that it will be useful, but

  51885.      WITHOUT ANY WARRANTY; without even the implied warranty of

  51886.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

  51887.      General Public License for more details.

  51888. 

  51889.      You should have received a copy of the GNU General Public License

  51890.      along with this program.  If not, see <http://www.gnu.org/licenses/>.

  51891. 

  51892.    Also add information on how to contact you by electronic and paper

  51893. mail.

  51894. 

  51895.    If the program does terminal interaction, make it output a short

  51896. notice like this when it starts in an interactive mode:

  51897. 

  51898.      PROGRAM Copyright (C) YEAR NAME OF AUTHOR

  51899.      This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.

  51900.      This is free software, and you are welcome to redistribute it

  51901.      under certain conditions; type 'show c' for details.

  51902. 

  51903.    The hypothetical commands 'show w' and 'show c' should show the

  51904. appropriate parts of the General Public License.  Of course, your

  51905. program's commands might be different; for a GUI interface, you would

  51906. use an "about box".

  51907. 

  51908.    You should also get your employer (if you work as a programmer) or

  51909. school, if any, to sign a "copyright disclaimer" for the program, if

  51910. necessary.  For more information on this, and how to apply and follow

  51911. the GNU GPL, see <http://www.gnu.org/licenses/>.

  51912. 

  51913.    The GNU General Public License does not permit incorporating your

  51914. program into proprietary programs.  If your program is a subroutine

  51915. library, you may consider it more useful to permit linking proprietary

  51916. applications with the library.  If this is what you want to do, use the

  51917. GNU Lesser General Public License instead of this License.  But first,

  51918. please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.

  51919. 

  51920. 

  51921. File: gdb.info,  Node: GNU Free Documentation License,  Next: Concept Index,  Prev: Copying,  Up: Top

  51922. 

  51923. Appendix M GNU Free Documentation License

  51924. *****************************************

  51925. 

  51926.                      Version 1.3, 3 November 2008

  51927. 

  51928.      Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.

  51929.      <http://fsf.org/>

  51930. 

  51931.      Everyone is permitted to copy and distribute verbatim copies

  51932.      of this license document, but changing it is not allowed.

  51933. 

  51934.   0. PREAMBLE

  51935. 

  51936.      The purpose of this License is to make a manual, textbook, or other

  51937.      functional and useful document "free" in the sense of freedom: to

  51938.      assure everyone the effective freedom to copy and redistribute it,

  51939.      with or without modifying it, either commercially or

  51940.      noncommercially.  Secondarily, this License preserves for the

  51941.      author and publisher a way to get credit for their work, while not

  51942.      being considered responsible for modifications made by others.

  51943. 

  51944.      This License is a kind of "copyleft", which means that derivative

  51945.      works of the document must themselves be free in the same sense.

  51946.      It complements the GNU General Public License, which is a copyleft

  51947.      license designed for free software.

  51948. 

  51949.      We have designed this License in order to use it for manuals for

  51950.      free software, because free software needs free documentation: a

  51951.      free program should come with manuals providing the same freedoms

  51952.      that the software does.  But this License is not limited to

  51953.      software manuals; it can be used for any textual work, regardless

  51954.      of subject matter or whether it is published as a printed book.  We

  51955.      recommend this License principally for works whose purpose is

  51956.      instruction or reference.

  51957. 

  51958.   1. APPLICABILITY AND DEFINITIONS

  51959. 

  51960.      This License applies to any manual or other work, in any medium,

  51961.      that contains a notice placed by the copyright holder saying it can

  51962.      be distributed under the terms of this License.  Such a notice

  51963.      grants a world-wide, royalty-free license, unlimited in duration,

  51964.      to use that work under the conditions stated herein.  The

  51965.      "Document", below, refers to any such manual or work.  Any member

  51966.      of the public is a licensee, and is addressed as "you".  You accept

  51967.      the license if you copy, modify or distribute the work in a way

  51968.      requiring permission under copyright law.

  51969. 

  51970.      A "Modified Version" of the Document means any work containing the

  51971.      Document or a portion of it, either copied verbatim, or with

  51972.      modifications and/or translated into another language.

  51973. 

  51974.      A "Secondary Section" is a named appendix or a front-matter section

  51975.      of the Document that deals exclusively with the relationship of the

  51976.      publishers or authors of the Document to the Document's overall

  51977.      subject (or to related matters) and contains nothing that could

  51978.      fall directly within that overall subject.  (Thus, if the Document

  51979.      is in part a textbook of mathematics, a Secondary Section may not

  51980.      explain any mathematics.)  The relationship could be a matter of

  51981.      historical connection with the subject or with related matters, or

  51982.      of legal, commercial, philosophical, ethical or political position

  51983.      regarding them.

  51984. 

  51985.      The "Invariant Sections" are certain Secondary Sections whose

  51986.      titles are designated, as being those of Invariant Sections, in the

  51987.      notice that says that the Document is released under this License.

  51988.      If a section does not fit the above definition of Secondary then it

  51989.      is not allowed to be designated as Invariant.  The Document may

  51990.      contain zero Invariant Sections.  If the Document does not identify

  51991.      any Invariant Sections then there are none.

  51992. 

  51993.      The "Cover Texts" are certain short passages of text that are

  51994.      listed, as Front-Cover Texts or Back-Cover Texts, in the notice

  51995.      that says that the Document is released under this License.  A

  51996.      Front-Cover Text may be at most 5 words, and a Back-Cover Text may

  51997.      be at most 25 words.

  51998. 

  51999.      A "Transparent" copy of the Document means a machine-readable copy,

  52000.      represented in a format whose specification is available to the

  52001.      general public, that is suitable for revising the document

  52002.      straightforwardly with generic text editors or (for images composed

  52003.      of pixels) generic paint programs or (for drawings) some widely

  52004.      available drawing editor, and that is suitable for input to text

  52005.      formatters or for automatic translation to a variety of formats

  52006.      suitable for input to text formatters.  A copy made in an otherwise

  52007.      Transparent file format whose markup, or absence of markup, has

  52008.      been arranged to thwart or discourage subsequent modification by

  52009.      readers is not Transparent.  An image format is not Transparent if

  52010.      used for any substantial amount of text.  A copy that is not

  52011.      "Transparent" is called "Opaque".

  52012. 

  52013.      Examples of suitable formats for Transparent copies include plain

  52014.      ASCII without markup, Texinfo input format, LaTeX input format,

  52015.      SGML or XML using a publicly available DTD, and standard-conforming

  52016.      simple HTML, PostScript or PDF designed for human modification.

  52017.      Examples of transparent image formats include PNG, XCF and JPG.

  52018.      Opaque formats include proprietary formats that can be read and

  52019.      edited only by proprietary word processors, SGML or XML for which

  52020.      the DTD and/or processing tools are not generally available, and

  52021.      the machine-generated HTML, PostScript or PDF produced by some word

  52022.      processors for output purposes only.

  52023. 

  52024.      The "Title Page" means, for a printed book, the title page itself,

  52025.      plus such following pages as are needed to hold, legibly, the

  52026.      material this License requires to appear in the title page.  For

  52027.      works in formats which do not have any title page as such, "Title

  52028.      Page" means the text near the most prominent appearance of the

  52029.      work's title, preceding the beginning of the body of the text.

  52030. 

  52031.      The "publisher" means any person or entity that distributes copies

  52032.      of the Document to the public.

  52033. 

  52034.      A section "Entitled XYZ" means a named subunit of the Document

  52035.      whose title either is precisely XYZ or contains XYZ in parentheses

  52036.      following text that translates XYZ in another language.  (Here XYZ

  52037.      stands for a specific section name mentioned below, such as

  52038.      "Acknowledgements", "Dedications", "Endorsements", or "History".)

  52039.      To "Preserve the Title" of such a section when you modify the

  52040.      Document means that it remains a section "Entitled XYZ" according

  52041.      to this definition.

  52042. 

  52043.      The Document may include Warranty Disclaimers next to the notice

  52044.      which states that this License applies to the Document.  These

  52045.      Warranty Disclaimers are considered to be included by reference in

  52046.      this License, but only as regards disclaiming warranties: any other

  52047.      implication that these Warranty Disclaimers may have is void and

  52048.      has no effect on the meaning of this License.

  52049. 

  52050.   2. VERBATIM COPYING

  52051. 

  52052.      You may copy and distribute the Document in any medium, either

  52053.      commercially or noncommercially, provided that this License, the

  52054.      copyright notices, and the license notice saying this License

  52055.      applies to the Document are reproduced in all copies, and that you

  52056.      add no other conditions whatsoever to those of this License.  You

  52057.      may not use technical measures to obstruct or control the reading

  52058.      or further copying of the copies you make or distribute.  However,

  52059.      you may accept compensation in exchange for copies.  If you

  52060.      distribute a large enough number of copies you must also follow the

  52061.      conditions in section 3.

  52062. 

  52063.      You may also lend copies, under the same conditions stated above,

  52064.      and you may publicly display copies.

  52065. 

  52066.   3. COPYING IN QUANTITY

  52067. 

  52068.      If you publish printed copies (or copies in media that commonly

  52069.      have printed covers) of the Document, numbering more than 100, and

  52070.      the Document's license notice requires Cover Texts, you must

  52071.      enclose the copies in covers that carry, clearly and legibly, all

  52072.      these Cover Texts: Front-Cover Texts on the front cover, and

  52073.      Back-Cover Texts on the back cover.  Both covers must also clearly

  52074.      and legibly identify you as the publisher of these copies.  The

  52075.      front cover must present the full title with all words of the title

  52076.      equally prominent and visible.  You may add other material on the

  52077.      covers in addition.  Copying with changes limited to the covers, as

  52078.      long as they preserve the title of the Document and satisfy these

  52079.      conditions, can be treated as verbatim copying in other respects.

  52080. 

  52081.      If the required texts for either cover are too voluminous to fit

  52082.      legibly, you should put the first ones listed (as many as fit

  52083.      reasonably) on the actual cover, and continue the rest onto

  52084.      adjacent pages.

  52085. 

  52086.      If you publish or distribute Opaque copies of the Document

  52087.      numbering more than 100, you must either include a machine-readable

  52088.      Transparent copy along with each Opaque copy, or state in or with

  52089.      each Opaque copy a computer-network location from which the general

  52090.      network-using public has access to download using public-standard

  52091.      network protocols a complete Transparent copy of the Document, free

  52092.      of added material.  If you use the latter option, you must take

  52093.      reasonably prudent steps, when you begin distribution of Opaque

  52094.      copies in quantity, to ensure that this Transparent copy will

  52095.      remain thus accessible at the stated location until at least one

  52096.      year after the last time you distribute an Opaque copy (directly or

  52097.      through your agents or retailers) of that edition to the public.

  52098. 

  52099.      It is requested, but not required, that you contact the authors of

  52100.      the Document well before redistributing any large number of copies,

  52101.      to give them a chance to provide you with an updated version of the

  52102.      Document.

  52103. 

  52104.   4. MODIFICATIONS

  52105. 

  52106.      You may copy and distribute a Modified Version of the Document

  52107.      under the conditions of sections 2 and 3 above, provided that you

  52108.      release the Modified Version under precisely this License, with the

  52109.      Modified Version filling the role of the Document, thus licensing

  52110.      distribution and modification of the Modified Version to whoever

  52111.      possesses a copy of it.  In addition, you must do these things in

  52112.      the Modified Version:

  52113. 

  52114.        A. Use in the Title Page (and on the covers, if any) a title

  52115.           distinct from that of the Document, and from those of previous

  52116.           versions (which should, if there were any, be listed in the

  52117.           History section of the Document).  You may use the same title

  52118.           as a previous version if the original publisher of that

  52119.           version gives permission.

  52120. 

  52121.        B. List on the Title Page, as authors, one or more persons or

  52122.           entities responsible for authorship of the modifications in

  52123.           the Modified Version, together with at least five of the

  52124.           principal authors of the Document (all of its principal

  52125.           authors, if it has fewer than five), unless they release you

  52126.           from this requirement.

  52127. 

  52128.        C. State on the Title page the name of the publisher of the

  52129.           Modified Version, as the publisher.

  52130. 

  52131.        D. Preserve all the copyright notices of the Document.

  52132. 

  52133.        E. Add an appropriate copyright notice for your modifications

  52134.           adjacent to the other copyright notices.

  52135. 

  52136.        F. Include, immediately after the copyright notices, a license

  52137.           notice giving the public permission to use the Modified

  52138.           Version under the terms of this License, in the form shown in

  52139.           the Addendum below.

  52140. 

  52141.        G. Preserve in that license notice the full lists of Invariant

  52142.           Sections and required Cover Texts given in the Document's

  52143.           license notice.

  52144. 

  52145.        H. Include an unaltered copy of this License.

  52146. 

  52147.        I. Preserve the section Entitled "History", Preserve its Title,

  52148.           and add to it an item stating at least the title, year, new

  52149.           authors, and publisher of the Modified Version as given on the

  52150.           Title Page.  If there is no section Entitled "History" in the

  52151.           Document, create one stating the title, year, authors, and

  52152.           publisher of the Document as given on its Title Page, then add

  52153.           an item describing the Modified Version as stated in the

  52154.           previous sentence.

  52155. 

  52156.        J. Preserve the network location, if any, given in the Document

  52157.           for public access to a Transparent copy of the Document, and

  52158.           likewise the network locations given in the Document for

  52159.           previous versions it was based on.  These may be placed in the

  52160.           "History" section.  You may omit a network location for a work

  52161.           that was published at least four years before the Document

  52162.           itself, or if the original publisher of the version it refers

  52163.           to gives permission.

  52164. 

  52165.        K. For any section Entitled "Acknowledgements" or "Dedications",

  52166.           Preserve the Title of the section, and preserve in the section

  52167.           all the substance and tone of each of the contributor

  52168.           acknowledgements and/or dedications given therein.

  52169. 

  52170.        L. Preserve all the Invariant Sections of the Document, unaltered

  52171.           in their text and in their titles.  Section numbers or the

  52172.           equivalent are not considered part of the section titles.

  52173. 

  52174.        M. Delete any section Entitled "Endorsements".  Such a section

  52175.           may not be included in the Modified Version.

  52176. 

  52177.        N. Do not retitle any existing section to be Entitled

  52178.           "Endorsements" or to conflict in title with any Invariant

  52179.           Section.

  52180. 

  52181.        O. Preserve any Warranty Disclaimers.

  52182. 

  52183.      If the Modified Version includes new front-matter sections or

  52184.      appendices that qualify as Secondary Sections and contain no

  52185.      material copied from the Document, you may at your option designate

  52186.      some or all of these sections as invariant.  To do this, add their

  52187.      titles to the list of Invariant Sections in the Modified Version's

  52188.      license notice.  These titles must be distinct from any other

  52189.      section titles.

  52190. 

  52191.      You may add a section Entitled "Endorsements", provided it contains

  52192.      nothing but endorsements of your Modified Version by various

  52193.      parties--for example, statements of peer review or that the text

  52194.      has been approved by an organization as the authoritative

  52195.      definition of a standard.

  52196. 

  52197.      You may add a passage of up to five words as a Front-Cover Text,

  52198.      and a passage of up to 25 words as a Back-Cover Text, to the end of

  52199.      the list of Cover Texts in the Modified Version.  Only one passage

  52200.      of Front-Cover Text and one of Back-Cover Text may be added by (or

  52201.      through arrangements made by) any one entity.  If the Document

  52202.      already includes a cover text for the same cover, previously added

  52203.      by you or by arrangement made by the same entity you are acting on

  52204.      behalf of, you may not add another; but you may replace the old

  52205.      one, on explicit permission from the previous publisher that added

  52206.      the old one.

  52207. 

  52208.      The author(s) and publisher(s) of the Document do not by this

  52209.      License give permission to use their names for publicity for or to

  52210.      assert or imply endorsement of any Modified Version.

  52211. 

  52212.   5. COMBINING DOCUMENTS

  52213. 

  52214.      You may combine the Document with other documents released under

  52215.      this License, under the terms defined in section 4 above for

  52216.      modified versions, provided that you include in the combination all

  52217.      of the Invariant Sections of all of the original documents,

  52218.      unmodified, and list them all as Invariant Sections of your

  52219.      combined work in its license notice, and that you preserve all

  52220.      their Warranty Disclaimers.

  52221. 

  52222.      The combined work need only contain one copy of this License, and

  52223.      multiple identical Invariant Sections may be replaced with a single

  52224.      copy.  If there are multiple Invariant Sections with the same name

  52225.      but different contents, make the title of each such section unique

  52226.      by adding at the end of it, in parentheses, the name of the

  52227.      original author or publisher of that section if known, or else a

  52228.      unique number.  Make the same adjustment to the section titles in

  52229.      the list of Invariant Sections in the license notice of the

  52230.      combined work.

  52231. 

  52232.      In the combination, you must combine any sections Entitled

  52233.      "History" in the various original documents, forming one section

  52234.      Entitled "History"; likewise combine any sections Entitled

  52235.      "Acknowledgements", and any sections Entitled "Dedications".  You

  52236.      must delete all sections Entitled "Endorsements."

  52237. 

  52238.   6. COLLECTIONS OF DOCUMENTS

  52239. 

  52240.      You may make a collection consisting of the Document and other

  52241.      documents released under this License, and replace the individual

  52242.      copies of this License in the various documents with a single copy

  52243.      that is included in the collection, provided that you follow the

  52244.      rules of this License for verbatim copying of each of the documents

  52245.      in all other respects.

  52246. 

  52247.      You may extract a single document from such a collection, and

  52248.      distribute it individually under this License, provided you insert

  52249.      a copy of this License into the extracted document, and follow this

  52250.      License in all other respects regarding verbatim copying of that

  52251.      document.

  52252. 

  52253.   7. AGGREGATION WITH INDEPENDENT WORKS

  52254. 

  52255.      A compilation of the Document or its derivatives with other

  52256.      separate and independent documents or works, in or on a volume of a

  52257.      storage or distribution medium, is called an "aggregate" if the

  52258.      copyright resulting from the compilation is not used to limit the

  52259.      legal rights of the compilation's users beyond what the individual

  52260.      works permit.  When the Document is included in an aggregate, this

  52261.      License does not apply to the other works in the aggregate which

  52262.      are not themselves derivative works of the Document.

  52263. 

  52264.      If the Cover Text requirement of section 3 is applicable to these

  52265.      copies of the Document, then if the Document is less than one half

  52266.      of the entire aggregate, the Document's Cover Texts may be placed

  52267.      on covers that bracket the Document within the aggregate, or the

  52268.      electronic equivalent of covers if the Document is in electronic

  52269.      form.  Otherwise they must appear on printed covers that bracket

  52270.      the whole aggregate.

  52271. 

  52272.   8. TRANSLATION

  52273. 

  52274.      Translation is considered a kind of modification, so you may

  52275.      distribute translations of the Document under the terms of section

  52276.      4.  Replacing Invariant Sections with translations requires special

  52277.      permission from their copyright holders, but you may include

  52278.      translations of some or all Invariant Sections in addition to the

  52279.      original versions of these Invariant Sections.  You may include a

  52280.      translation of this License, and all the license notices in the

  52281.      Document, and any Warranty Disclaimers, provided that you also

  52282.      include the original English version of this License and the

  52283.      original versions of those notices and disclaimers.  In case of a

  52284.      disagreement between the translation and the original version of

  52285.      this License or a notice or disclaimer, the original version will

  52286.      prevail.

  52287. 

  52288.      If a section in the Document is Entitled "Acknowledgements",

  52289.      "Dedications", or "History", the requirement (section 4) to

  52290.      Preserve its Title (section 1) will typically require changing the

  52291.      actual title.

  52292. 

  52293.   9. TERMINATION

  52294. 

  52295.      You may not copy, modify, sublicense, or distribute the Document

  52296.      except as expressly provided under this License.  Any attempt

  52297.      otherwise to copy, modify, sublicense, or distribute it is void,

  52298.      and will automatically terminate your rights under this License.

  52299. 

  52300.      However, if you cease all violation of this License, then your

  52301.      license from a particular copyright holder is reinstated (a)

  52302.      provisionally, unless and until the copyright holder explicitly and

  52303.      finally terminates your license, and (b) permanently, if the

  52304.      copyright holder fails to notify you of the violation by some

  52305.      reasonable means prior to 60 days after the cessation.

  52306. 

  52307.      Moreover, your license from a particular copyright holder is

  52308.      reinstated permanently if the copyright holder notifies you of the

  52309.      violation by some reasonable means, this is the first time you have

  52310.      received notice of violation of this License (for any work) from

  52311.      that copyright holder, and you cure the violation prior to 30 days

  52312.      after your receipt of the notice.

  52313. 

  52314.      Termination of your rights under this section does not terminate

  52315.      the licenses of parties who have received copies or rights from you

  52316.      under this License.  If your rights have been terminated and not

  52317.      permanently reinstated, receipt of a copy of some or all of the

  52318.      same material does not give you any rights to use it.

  52319. 

  52320.   10. FUTURE REVISIONS OF THIS LICENSE

  52321. 

  52322.      The Free Software Foundation may publish new, revised versions of

  52323.      the GNU Free Documentation License from time to time.  Such new

  52324.      versions will be similar in spirit to the present version, but may

  52325.      differ in detail to address new problems or concerns.  See

  52326.      <http://www.gnu.org/copyleft/>.

  52327. 

  52328.      Each version of the License is given a distinguishing version

  52329.      number.  If the Document specifies that a particular numbered

  52330.      version of this License "or any later version" applies to it, you

  52331.      have the option of following the terms and conditions either of

  52332.      that specified version or of any later version that has been

  52333.      published (not as a draft) by the Free Software Foundation.  If the

  52334.      Document does not specify a version number of this License, you may

  52335.      choose any version ever published (not as a draft) by the Free

  52336.      Software Foundation.  If the Document specifies that a proxy can

  52337.      decide which future versions of this License can be used, that

  52338.      proxy's public statement of acceptance of a version permanently

  52339.      authorizes you to choose that version for the Document.

  52340. 

  52341.   11. RELICENSING

  52342. 

  52343.      "Massive Multiauthor Collaboration Site" (or "MMC Site") means any

  52344.      World Wide Web server that publishes copyrightable works and also

  52345.      provides prominent facilities for anybody to edit those works.  A

  52346.      public wiki that anybody can edit is an example of such a server.

  52347.      A "Massive Multiauthor Collaboration" (or "MMC") contained in the

  52348.      site means any set of copyrightable works thus published on the MMC

  52349.      site.

  52350. 

  52351.      "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0

  52352.      license published by Creative Commons Corporation, a not-for-profit

  52353.      corporation with a principal place of business in San Francisco,

  52354.      California, as well as future copyleft versions of that license

  52355.      published by that same organization.

  52356. 

  52357.      "Incorporate" means to publish or republish a Document, in whole or

  52358.      in part, as part of another Document.

  52359. 

  52360.      An MMC is "eligible for relicensing" if it is licensed under this

  52361.      License, and if all works that were first published under this

  52362.      License somewhere other than this MMC, and subsequently

  52363.      incorporated in whole or in part into the MMC, (1) had no cover

  52364.      texts or invariant sections, and (2) were thus incorporated prior

  52365.      to November 1, 2008.

  52366. 

  52367.      The operator of an MMC Site may republish an MMC contained in the

  52368.      site under CC-BY-SA on the same site at any time before August 1,

  52369.      2009, provided the MMC is eligible for relicensing.

  52370. 

  52371. ADDENDUM: How to use this License for your documents

  52372. ====================================================

  52373. 

  52374. To use this License in a document you have written, include a copy of

  52375. the License in the document and put the following copyright and license

  52376. notices just after the title page:

  52377. 

  52378.        Copyright (C)  YEAR  YOUR NAME.

  52379.        Permission is granted to copy, distribute and/or modify this document

  52380.        under the terms of the GNU Free Documentation License, Version 1.3

  52381.        or any later version published by the Free Software Foundation;

  52382.        with no Invariant Sections, no Front-Cover Texts, and no Back-Cover

  52383.        Texts.  A copy of the license is included in the section entitled ``GNU

  52384.        Free Documentation License''.

  52385. 

  52386.    If you have Invariant Sections, Front-Cover Texts and Back-Cover

  52387. Texts, replace the "with...Texts."  line with this:

  52388. 

  52389.          with the Invariant Sections being LIST THEIR TITLES, with

  52390.          the Front-Cover Texts being LIST, and with the Back-Cover Texts

  52391.          being LIST.

  52392. 

  52393.    If you have Invariant Sections without Cover Texts, or some other

  52394. combination of the three, merge those two alternatives to suit the

  52395. situation.

  52396. 

  52397.    If your document contains nontrivial examples of program code, we

  52398. recommend releasing these examples in parallel under your choice of free

  52399. software license, such as the GNU General Public License, to permit

  52400. their use in free software.

  52401. 

  52402. 

  52403. File: gdb.info,  Node: Concept Index,  Next: Command and Variable Index,  Prev: GNU Free Documentation License,  Up: Top

  52404. 

  52405. Concept Index

  52406. *************

  52407. 

  52408. �[index�]

  52409. * Menu:

  52410. 

  52411. * ! packet:                              Packets.            (line   49)

  52412. * "No symbol "foo" in current context":  Variables.          (line  122)

  52413. * # in Modula-2:                         GDB/M2.             (line   18)

  52414. * $:                                     Value History.      (line   13)

  52415. * $$:                                    Value History.      (line   13)

  52416. * $_ and info breakpoints:               Set Breaks.         (line  133)

  52417. * $_ and info line:                      Machine Code.       (line   34)

  52418. * $_, $__, and value history:            Memory.             (line  119)

  52419. * &, background execution of commands:   Background Execution.

  52420.                                                              (line   16)

  52421. * --annotate:                            Mode Options.       (line  132)

  52422. * --args:                                Mode Options.       (line  145)

  52423. * --attach, gdbserver option:            Server.             (line   86)

  52424. * --batch:                               Mode Options.       (line   55)

  52425. * --batch-silent:                        Mode Options.       (line   73)

  52426. * --baud:                                Mode Options.       (line  151)

  52427. * --cd:                                  Mode Options.       (line  112)

  52428. * --command:                             File Options.       (line   51)

  52429. * --configuration:                       Mode Options.       (line  195)

  52430. * --core:                                File Options.       (line   43)

  52431. * --data-directory:                      Mode Options.       (line  117)

  52432. * --debug, gdbserver option:             Server.             (line  146)

  52433. * --debug-file, gdbserver option:        Server.             (line  148)

  52434. * --debug-format, gdbserver option:      Server.             (line  153)

  52435. * --directory:                           File Options.       (line   77)

  52436. * --eval-command:                        File Options.       (line   57)

  52437. * --exec:                                File Options.       (line   35)

  52438. * --fullname:                            Mode Options.       (line  122)

  52439. * --init-command:                        File Options.       (line   67)

  52440. * --init-eval-command:                   File Options.       (line   72)

  52441. * --interpreter:                         Mode Options.       (line  170)

  52442. * --multi, gdbserver option:             Connecting.         (line   45)

  52443. * --nh:                                  Mode Options.       (line   45)

  52444. * --nowindows:                           Mode Options.       (line  102)

  52445. * --nx:                                  Mode Options.       (line   11)

  52446. * --once, gdbserver option:              Server.             (line  126)

  52447. * --pid:                                 File Options.       (line   47)

  52448. * --quiet:                               Mode Options.       (line   51)

  52449. * --readnever, command-line option:      File Options.       (line   87)

  52450. * --readnow:                             File Options.       (line   81)

  52451. * --remote-debug, gdbserver option:      Server.             (line  147)

  52452. * --return-child-result:                 Mode Options.       (line   85)

  52453. * --se:                                  File Options.       (line   39)

  52454. * --selftest:                            Server.             (line  187)

  52455. * --silent:                              Mode Options.       (line   51)

  52456. * --statistics:                          Mode Options.       (line  187)

  52457. * --symbols:                             File Options.       (line   31)

  52458. * --tty:                                 Mode Options.       (line  160)

  52459. * --tui:                                 Mode Options.       (line  163)

  52460. * --version:                             Mode Options.       (line  191)

  52461. * --windows:                             Mode Options.       (line  108)

  52462. * --with-gdb-datadir:                    Data Files.         (line   19)

  52463. * --with-relocated-sources:              Source Path.        (line  149)

  52464. * --with-sysroot:                        Files.              (line  453)

  52465. * --wrapper, gdbserver option:           Server.             (line  166)

  52466. * --write:                               Mode Options.       (line  182)

  52467. * -b:                                    Mode Options.       (line  151)

  52468. * -c:                                    File Options.       (line   43)

  52469. * -d:                                    File Options.       (line   77)

  52470. * -D:                                    Mode Options.       (line  117)

  52471. * -e:                                    File Options.       (line   35)

  52472. * -ex:                                   File Options.       (line   57)

  52473. * -f:                                    Mode Options.       (line  122)

  52474. * -iex:                                  File Options.       (line   72)

  52475. * -info-gdb-mi-command:                  GDB/MI Support Commands.

  52476.                                                              (line   14)

  52477. * -ix:                                   File Options.       (line   67)

  52478. * -l:                                    Mode Options.       (line  155)

  52479. * -n:                                    Mode Options.       (line   11)

  52480. * -nw:                                   Mode Options.       (line  102)

  52481. * -p:                                    File Options.       (line   47)

  52482. * -q:                                    Mode Options.       (line   51)

  52483. * -r:                                    File Options.       (line   81)

  52484. * -readnever, option for symbol-file command: Files.         (line  101)

  52485. * -s:                                    File Options.       (line   31)

  52486. * -t:                                    Mode Options.       (line  160)

  52487. * -w:                                    Mode Options.       (line  108)

  52488. * -x:                                    File Options.       (line   51)

  52489. * ., Modula-2 scope operator:            M2 Scope.           (line    6)

  52490. * .build-id directory:                   Separate Debug Files.

  52491.                                                              (line    6)

  52492. * .debug subdirectories:                 Separate Debug Files.

  52493.                                                              (line    6)

  52494. * .debug_gdb_scripts section:            dotdebug_gdb_scripts section.

  52495.                                                              (line    6)

  52496. * .gdbinit:                              Startup.            (line   69)

  52497. * .gdb_index section:                    Index Files.        (line    6)

  52498. * .gdb_index section format:             Index Section Format.

  52499.                                                              (line    6)

  52500. * .gnu_debugdata section:                MiniDebugInfo.      (line    6)

  52501. * .gnu_debuglink sections:               Separate Debug Files.

  52502.                                                              (line   79)

  52503. * .note.gnu.build-id sections:           Separate Debug Files.

  52504.                                                              (line   95)

  52505. * .o files, reading symbols from:        Files.              (line  146)

  52506. * /proc:                                 Process Information.

  52507.                                                              (line    6)

  52508. * <architecture>:                        Target Description Format.

  52509.                                                              (line   72)

  52510. * <compatible>:                          Target Description Format.

  52511.                                                              (line   95)

  52512. * <feature>:                             Target Description Format.

  52513.                                                              (line  119)

  52514. * <flags>:                               Target Description Format.

  52515.                                                              (line  163)

  52516. * <not saved> values:                    Registers.          (line  106)

  52517. * <osabi>:                               Target Description Format.

  52518.                                                              (line   82)

  52519. * <reg>:                                 Target Description Format.

  52520.                                                              (line  222)

  52521. * <struct>:                              Target Description Format.

  52522.                                                              (line  163)

  52523. * <union>:                               Target Description Format.

  52524.                                                              (line  153)

  52525. * <vector>:                              Target Description Format.

  52526.                                                              (line  146)

  52527. * ? packet:                              Packets.            (line   58)

  52528. * _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C.

  52529.                                                              (line   11)

  52530. * {TYPE}:                                Expressions.        (line   41)

  52531. * A packet:                              Packets.            (line   65)

  52532. * AArch64 Pointer Authentication.:       AArch64.            (line   34)

  52533. * AArch64 support:                       AArch64.            (line    6)

  52534. * AArch64 SVE.:                          AArch64.            (line   19)

  52535. * abbreviation:                          Command Syntax.     (line   13)

  52536. * acknowledgment, for GDB remote:        Packet Acknowledgment.

  52537.                                                              (line    6)

  52538. * active targets:                        Active Targets.     (line    6)

  52539. * Ada:                                   Ada.                (line    6)

  52540. * Ada exception catching:                Set Catchpoints.    (line   66)

  52541. * Ada exception handlers catching:       Set Catchpoints.    (line   92)

  52542. * Ada mode, general:                     Ada Mode Intro.     (line    6)

  52543. * Ada settings:                          Ada Settings.       (line    6)

  52544. * Ada task switching:                    Ada Tasks.          (line  115)

  52545. * Ada tasking and core file debugging:   Ada Tasks and Core Files.

  52546.                                                              (line    6)

  52547. * Ada, deviations from:                  Additions to Ada.   (line    6)

  52548. * Ada, omissions from:                   Omissions from Ada. (line    6)

  52549. * Ada, problems:                         Ada Glitches.       (line    6)

  52550. * Ada, tasking:                          Ada Tasks.          (line    6)

  52551. * add new commands for external monitor: Connecting.         (line  279)

  52552. * address locations:                     Address Locations.  (line    6)

  52553. * address of a symbol:                   Symbols.            (line   85)

  52554. * address size for remote targets:       Remote Configuration.

  52555.                                                              (line   12)

  52556. * addressable memory unit:               Memory.             (line  133)

  52557. * aggregates (Ada):                      Omissions from Ada. (line   44)

  52558. * AIX shared library debugging:          Debugging Output.   (line   30)

  52559. * AIX threads:                           Debugging Output.   (line   36)

  52560. * aliases for commands:                  Aliases.            (line    6)

  52561. * alignment of remote memory accesses:   Packets.            (line  247)

  52562. * all-stop mode:                         All-Stop Mode.      (line    6)

  52563. * Alpha stack:                           MIPS.               (line    6)

  52564. * ambiguous expressions:                 Ambiguous Expressions.

  52565.                                                              (line    6)

  52566. * annotations:                           Annotations Overview.

  52567.                                                              (line    6)

  52568. * annotations for errors, warnings and interrupts: Errors.   (line    6)

  52569. * annotations for invalidation messages: Invalidation.       (line    6)

  52570. * annotations for prompts:               Prompting.          (line    6)

  52571. * annotations for running programs:      Annotations for Running.

  52572.                                                              (line    6)

  52573. * annotations for source display:        Source Annotations. (line    6)

  52574. * append data to a file:                 Dump/Restore Files. (line    6)

  52575. * Application Data Integrity:            Sparc64.            (line    5)

  52576. * apply a command to all frames (ignoring errors and empty output): Frame Apply.

  52577.                                                              (line   96)

  52578. * apply a command to all frames of all threads (ignoring errors and empty output): Threads.

  52579.                                                              (line  229)

  52580. * apply command to all threads (ignoring errors and empty output): Threads.

  52581.                                                              (line  222)

  52582. * apply command to several frames:       Frame Apply.        (line    6)

  52583. * apply command to several threads:      Threads.            (line  187)

  52584. * ARC EM:                                ARC.                (line    6)

  52585. * ARC HS:                                ARC.                (line    6)

  52586. * ARC specific commands:                 ARC.                (line    6)

  52587. * ARC600:                                ARC.                (line    6)

  52588. * ARC700:                                ARC.                (line    6)

  52589. * architecture debugging info:           Debugging Output.   (line   23)

  52590. * argument count in user-defined commands: Define.           (line   25)

  52591. * arguments (to your program):           Arguments.          (line    6)

  52592. * arguments, to gdbserver:               Server.             (line   34)

  52593. * arguments, to user-defined commands:   Define.             (line    6)

  52594. * ARM 32-bit mode:                       ARM.                (line   16)

  52595. * ARM AArch64:                           Debugging Output.   (line   17)

  52596. * array aggregates (Ada):                Omissions from Ada. (line   44)

  52597. * arrays:                                Arrays.             (line    6)

  52598. * arrays in expressions:                 Expressions.        (line   13)

  52599. * artificial array:                      Arrays.             (line    6)

  52600. * assembly instructions:                 Machine Code.       (line   43)

  52601. * assignment:                            Assignment.         (line    6)

  52602. * async output in GDB/MI:                GDB/MI Output Syntax.

  52603.                                                              (line   98)

  52604. * async records in GDB/MI:               GDB/MI Async Records.

  52605.                                                              (line    6)

  52606. * asynchronous execution:                Background Execution.

  52607.                                                              (line    6)

  52608. * asynchronous execution, and process record and replay: Process Record and Replay.

  52609.                                                              (line  101)

  52610. * AT&T disassembly flavor:               Machine Code.       (line  237)

  52611. * attach:                                Attach.             (line    6)

  52612. * attach to a program, gdbserver:        Server.             (line   86)

  52613. * auto-loading:                          Auto-loading.       (line    6)

  52614. * auto-loading extensions:               Auto-loading extensions.

  52615.                                                              (line    6)

  52616. * auto-loading init file in the current directory: Init File in the Current Directory.

  52617.                                                              (line    6)

  52618. * auto-loading libthread_db.so.1:        libthread_db.so.1 file.

  52619.                                                              (line    6)

  52620. * auto-loading safe-path:                Auto-loading safe path.

  52621.                                                              (line    6)

  52622. * auto-loading verbose mode:             Auto-loading verbose mode.

  52623.                                                              (line    6)

  52624. * auto-retry, for remote TCP target:     Remote Configuration.

  52625.                                                              (line  131)

  52626. * automatic display:                     Auto Display.       (line    6)

  52627. * automatic hardware breakpoints:        Set Breaks.         (line  296)

  52628. * automatic overlay debugging:           Automatic Overlay Debugging.

  52629.                                                              (line    6)

  52630. * automatic symbol index cache:          Index Files.        (line   73)

  52631. * automatic thread selection:            All-Stop Mode.      (line   28)

  52632. * auxiliary vector:                      OS Information.     (line    9)

  52633. * AVR:                                   AVR.                (line    6)

  52634. * b packet:                              Packets.            (line   76)

  52635. * B packet:                              Packets.            (line   91)

  52636. * background execution:                  Background Execution.

  52637.                                                              (line    6)

  52638. * backtrace beyond main function:        Backtrace.          (line  155)

  52639. * backtrace limit:                       Backtrace.          (line  192)

  52640. * base name differences:                 Files.              (line  520)

  52641. * baud rate for remote targets:          Remote Configuration.

  52642.                                                              (line   21)

  52643. * bc packet:                             Packets.            (line   96)

  52644. * bcache statistics:                     Maintenance Commands.

  52645.                                                              (line  342)

  52646. * bits in remote address:                Remote Configuration.

  52647.                                                              (line   12)

  52648. * blocks in guile:                       Blocks In Guile.    (line    6)

  52649. * blocks in python:                      Blocks In Python.   (line    6)

  52650. * bookmark:                              Checkpoint/Restart. (line    6)

  52651. * boundary violations, Intel MPX:        Signals.            (line  197)

  52652. * branch trace configuration format:     Branch Trace Configuration Format.

  52653.                                                              (line    6)

  52654. * branch trace format:                   Branch Trace Format.

  52655.                                                              (line    6)

  52656. * branch trace store:                    Process Record and Replay.

  52657.                                                              (line   70)

  52658. * break in overloaded functions:         Debugging C Plus Plus.

  52659.                                                              (line    9)

  52660. * break on a system call.:               Set Catchpoints.    (line  120)

  52661. * break on fork/exec:                    Set Catchpoints.    (line  116)

  52662. * BREAK signal instead of Ctrl-C:        Remote Configuration.

  52663.                                                              (line   36)

  52664. * breakpoint address adjusted:           Breakpoint-related Warnings.

  52665.                                                              (line    6)

  52666. * breakpoint at static probe point:      Linespec Locations. (line   65)

  52667. * breakpoint commands:                   Break Commands.     (line    6)

  52668. * breakpoint commands for GDB/MI:        GDB/MI Breakpoint Commands.

  52669.                                                              (line    6)

  52670. * breakpoint commands, in remote protocol: General Query Packets.

  52671.                                                              (line  983)

  52672. * breakpoint conditions:                 Conditions.         (line    6)

  52673. * breakpoint kinds, ARM:                 ARM Breakpoint Kinds.

  52674.                                                              (line    6)

  52675. * breakpoint kinds, MIPS:                MIPS Breakpoint Kinds.

  52676.                                                              (line    6)

  52677. * breakpoint lists:                      Breakpoints.        (line   45)

  52678. * breakpoint numbers:                    Breakpoints.        (line   38)

  52679. * breakpoint on events:                  Breakpoints.        (line   30)

  52680. * breakpoint on memory address:          Breakpoints.        (line   17)

  52681. * breakpoint on variable modification:   Breakpoints.        (line   17)

  52682. * breakpoint ranges:                     Breakpoints.        (line   45)

  52683. * breakpoint subroutine, remote:         Stub Contents.      (line   31)

  52684. * breakpointing Ada elaboration code:    Stopping Before Main Program.

  52685.                                                              (line    6)

  52686. * breakpoints:                           Breakpoints.        (line    6)

  52687. * breakpoints and tasks, in Ada:         Ada Tasks.          (line  135)

  52688. * breakpoints and threads:               Thread-Specific Breakpoints.

  52689.                                                              (line   10)

  52690. * breakpoints at functions matching a regexp: Set Breaks.    (line   90)

  52691. * breakpoints in guile:                  Breakpoints In Guile.

  52692.                                                              (line    6)

  52693. * breakpoints in overlays:               Overlay Commands.   (line   91)

  52694. * breakpoints in python:                 Breakpoints In Python.

  52695.                                                              (line    6)

  52696. * breakpoints, multiple locations:       Set Breaks.         (line  200)

  52697. * bs packet:                             Packets.            (line  102)

  52698. * bug criteria:                          Bug Criteria.       (line    6)

  52699. * bug reports:                           Bug Reporting.      (line    6)

  52700. * bugs in GDB:                           GDB Bugs.           (line    6)

  52701. * build ID sections:                     Separate Debug Files.

  52702.                                                              (line   95)

  52703. * build ID, and separate debugging files: Separate Debug Files.

  52704.                                                              (line    6)

  52705. * building GDB, requirements for:        Requirements.       (line    6)

  52706. * built-in simulator target:             Target Commands.    (line   73)

  52707. * builtin Go functions:                  Go.                 (line   31)

  52708. * builtin Go types:                      Go.                 (line   28)

  52709. * C and C++:                             C.                  (line    6)

  52710. * C and C++ checks:                      C Checks.           (line    6)

  52711. * C and C++ constants:                   C Constants.        (line    6)

  52712. * C and C++ defaults:                    C Defaults.         (line    6)

  52713. * C and C++ operators:                   C Operators.        (line    6)

  52714. * c packet:                              Packets.            (line  109)

  52715. * C packet:                              Packets.            (line  118)

  52716. * C++:                                   C.                  (line   10)

  52717. * C++ compilers:                         C Plus Plus Expressions.

  52718.                                                              (line    8)

  52719. * C++ demangling:                        Debugging C Plus Plus.

  52720.                                                              (line   36)

  52721. * C++ exception handling:                Debugging C Plus Plus.

  52722.                                                              (line   20)

  52723. * C++ overload debugging info:           Debugging Output.   (line  147)

  52724. * C++ scope resolution:                  Variables.          (line   90)

  52725. * C++ symbol decoding style:             Print Settings.     (line  529)

  52726. * C++ symbol display:                    Debugging C Plus Plus.

  52727.                                                              (line   40)

  52728. * caching data of targets:               Caching Target Data.

  52729.                                                              (line    6)

  52730. * caching of bfd objects:                File Caching.       (line    6)

  52731. * caching of opened files:               File Caching.       (line    6)

  52732. * call dummy stack unwinding:            Calling.            (line   36)

  52733. * call dummy stack unwinding on unhandled exception.: Calling.

  52734.                                                              (line   47)

  52735. * call overloaded functions:             C Plus Plus Expressions.

  52736.                                                              (line   26)

  52737. * call stack:                            Stack.              (line    9)

  52738. * call stack traces:                     Backtrace.          (line    6)

  52739. * call-clobbered registers:              Registers.          (line  106)

  52740. * caller-saved registers:                Registers.          (line  106)

  52741. * calling functions:                     Calling.            (line    6)

  52742. * calling functions in the program, disabling: Calling.      (line   59)

  52743. * calling make:                          Shell Commands.     (line   22)

  52744. * case sensitivity in symbol names:      Symbols.            (line   27)

  52745. * case-insensitive symbol names:         Symbols.            (line   27)

  52746. * casts, in expressions:                 Expressions.        (line   26)

  52747. * casts, to view memory:                 Expressions.        (line   41)

  52748. * catch Ada exceptions:                  Set Catchpoints.    (line   66)

  52749. * catch Ada exceptions when handled:     Set Catchpoints.    (line   92)

  52750. * catch syscalls from inferior, remote request: General Query Packets.

  52751.                                                              (line  401)

  52752. * catchpoints:                           Breakpoints.        (line   30)

  52753. * catchpoints, setting:                  Set Catchpoints.    (line    6)

  52754. * change GDB's working directory:        Working Directory.  (line   32)

  52755. * change inferior's working directory:   Working Directory.  (line   13)

  52756. * character sets:                        Character Sets.     (line    6)

  52757. * charset:                               Character Sets.     (line    6)

  52758. * checkpoint:                            Checkpoint/Restart. (line    6)

  52759. * checkpoints and process id:            Checkpoint/Restart. (line   76)

  52760. * checks, range:                         Type Checking.      (line   44)

  52761. * checks, type:                          Checks.             (line   23)

  52762. * checksum, for GDB remote:              Overview.           (line   21)

  52763. * choosing target byte order:            Byte Order.         (line    6)

  52764. * circular trace buffer:                 Starting and Stopping Trace Experiments.

  52765.                                                              (line   80)

  52766. * clearing breakpoints, watchpoints, catchpoints: Delete Breaks.

  52767.                                                              (line    6)

  52768. * close, file-i/o system call:           close.              (line    6)

  52769. * closest symbol and offset for an address: Symbols.         (line   95)

  52770. * code address and its source line:      Machine Code.       (line   28)

  52771. * code compression, MIPS:                MIPS.               (line   49)

  52772. * COFF/PE exported symbols:              Debugging Output.   (line   50)

  52773. * collected data discarded:              Starting and Stopping Trace Experiments.

  52774.                                                              (line    6)

  52775. * colon, doubled as scope operator:      M2 Scope.           (line    6)

  52776. * colon-colon, context for variables/functions: Variables.   (line   44)

  52777. * colors:                                Output Styling.     (line    6)

  52778. * command editing:                       Readline Bare Essentials.

  52779.                                                              (line    6)

  52780. * command files:                         Command Files.      (line    6)

  52781. * command history:                       Command History.    (line    6)

  52782. * command hooks:                         Hooks.              (line    6)

  52783. * command interpreters:                  Interpreters.       (line    6)

  52784. * command line editing:                  Editing.            (line    6)

  52785. * command options:                       Command Options.    (line    6)

  52786. * command options, boolean:              Command Options.    (line   21)

  52787. * command options, raw input:            Command Options.    (line   13)

  52788. * command scripts, debugging:            Messages/Warnings.  (line   65)

  52789. * command tracing:                       Messages/Warnings.  (line   60)

  52790. * commands for C++:                      Debugging C Plus Plus.

  52791.                                                              (line    6)

  52792. * commands in guile:                     Commands In Guile.  (line    6)

  52793. * commands in python:                    Commands In Python. (line    6)

  52794. * commands to access guile:              Guile Commands.     (line    6)

  52795. * commands to access python:             Python Commands.    (line    6)

  52796. * comment:                               Command Syntax.     (line   37)

  52797. * COMMON blocks, Fortran:                Special Fortran Commands.

  52798.                                                              (line    9)

  52799. * common targets:                        Target Commands.    (line   46)

  52800. * compatibility, GDB/MI and CLI:         GDB/MI Compatibility with CLI.

  52801.                                                              (line    6)

  52802. * compilation directory:                 Source Path.        (line   40)

  52803. * compile C++ type conversion:           Compiling and Injecting Code.

  52804.                                                              (line   90)

  52805. * compile command debugging info:        Compiling and Injecting Code.

  52806.                                                              (line   82)

  52807. * compile command driver filename override: Compiling and Injecting Code.

  52808.                                                              (line  300)

  52809. * compile command options override:      Compiling and Injecting Code.

  52810.                                                              (line  125)

  52811. * compiling code:                        Compiling and Injecting Code.

  52812.                                                              (line    6)

  52813. * completion:                            Completion.         (line    6)

  52814. * completion of Guile commands:          Commands In Guile.  (line  100)

  52815. * completion of Python commands:         Commands In Python. (line   70)

  52816. * completion of quoted strings:          Completion.         (line   83)

  52817. * completion of structure field names:   Completion.         (line  135)

  52818. * completion of union field names:       Completion.         (line  135)

  52819. * compressed debug sections:             Requirements.       (line  110)

  52820. * conditional breakpoints:               Conditions.         (line    6)

  52821. * conditional tracepoints:               Tracepoint Conditions.

  52822.                                                              (line    6)

  52823. * configuring GDB:                       Running Configure.  (line    6)

  52824. * confirmation:                          Messages/Warnings.  (line   49)

  52825. * connection timeout, for remote TCP target: Remote Configuration.

  52826.                                                              (line  147)

  52827. * console i/o as part of file-i/o:       Console I/O.        (line    6)

  52828. * console interpreter:                   Interpreters.       (line   21)

  52829. * console output in GDB/MI:              GDB/MI Output Syntax.

  52830.                                                              (line  106)

  52831. * constants, in file-i/o protocol:       Constants.          (line    6)

  52832. * continuing:                            Continuing and Stepping.

  52833.                                                              (line    6)

  52834. * continuing threads:                    Thread Stops.       (line    6)

  52835. * control C, and remote debugging:       Bootstrapping.      (line   25)

  52836. * controlling terminal:                  Input/Output.       (line   23)

  52837. * convenience functions:                 Convenience Funs.   (line    6)

  52838. * convenience functions in python:       Functions In Python.

  52839.                                                              (line    6)

  52840. * convenience variables:                 Convenience Vars.   (line    6)

  52841. * convenience variables for tracepoints: Tracepoint Variables.

  52842.                                                              (line    6)

  52843. * convenience variables, and trace state variables: Trace State Variables.

  52844.                                                              (line   17)

  52845. * convenience variables, initializing:   Convenience Vars.   (line   42)

  52846. * core dump file:                        Files.              (line    6)

  52847. * core dump file target:                 Target Commands.    (line   54)

  52848. * crash of debugger:                     Bug Criteria.       (line    9)

  52849. * CRC algorithm definition:              Separate Debug Files.

  52850.                                                              (line  140)

  52851. * CRC of memory block, remote request:   General Query Packets.

  52852.                                                              (line   65)

  52853. * CRIS:                                  CRIS.               (line    6)

  52854. * CRIS mode:                             CRIS.               (line   26)

  52855. * CRIS version:                          CRIS.               (line   10)

  52856. * Ctrl-BREAK, MS-Windows:                Cygwin Native.      (line    9)

  52857. * ctrl-c message, in file-i/o protocol:  The Ctrl-C Message. (line    6)

  52858. * current Ada task ID:                   Ada Tasks.          (line  105)

  52859. * current directory:                     Source Path.        (line   40)

  52860. * current Go package:                    Go.                 (line   11)

  52861. * current thread:                        Threads.            (line   29)

  52862. * current thread, remote request:        General Query Packets.

  52863.                                                              (line   55)

  52864. * custom JIT debug info:                 Custom Debug Info.  (line    6)

  52865. * Cygwin DLL, debugging:                 Cygwin Native.      (line   60)

  52866. * Cygwin-specific commands:              Cygwin Native.      (line    6)

  52867. * D:                                     D.                  (line    6)

  52868. * d packet:                              Packets.            (line  127)

  52869. * D packet:                              Packets.            (line  134)

  52870. * Darwin:                                Darwin.             (line    6)

  52871. * data breakpoints:                      Breakpoints.        (line   17)

  52872. * data manipulation, in GDB/MI:          GDB/MI Data Manipulation.

  52873.                                                              (line    6)

  52874. * dcache line-size:                      Caching Target Data.

  52875.                                                              (line   60)

  52876. * dcache size:                           Caching Target Data.

  52877.                                                              (line   57)

  52878. * dead names, GNU Hurd:                  Hurd Native.        (line   84)

  52879. * debug expression parser:               Debugging Output.   (line  152)

  52880. * debug formats and C++:                 C Plus Plus Expressions.

  52881.                                                              (line    8)

  52882. * debug link sections:                   Separate Debug Files.

  52883.                                                              (line   79)

  52884. * debug remote protocol:                 Debugging Output.   (line  159)

  52885. * debugger crash:                        Bug Criteria.       (line    9)

  52886. * debugging agent:                       In-Process Agent.   (line    6)

  52887. * debugging C++ programs:                C Plus Plus Expressions.

  52888.                                                              (line    8)

  52889. * debugging information directory, global: Separate Debug Files.

  52890.                                                              (line    6)

  52891. * debugging information in separate files: Separate Debug Files.

  52892.                                                              (line    6)

  52893. * debugging libthread_db:                Threads.            (line  331)

  52894. * debugging multiple processes:          Forks.              (line   55)

  52895. * debugging optimized code:              Optimized Code.     (line    6)

  52896. * debugging stub, example:               Remote Stub.        (line    6)

  52897. * debugging target:                      Targets.            (line    6)

  52898. * debugging the Cygwin DLL:              Cygwin Native.      (line   60)

  52899. * decimal floating point format:         Decimal Floating Point.

  52900.                                                              (line    6)

  52901. * default behavior of commands, changing: Command Settings.  (line    6)

  52902. * default collection action:             Tracepoint Actions. (line  142)

  52903. * default data directory:                Data Files.         (line   19)

  52904. * default settings, changing:            Command Settings.   (line    6)

  52905. * default source path substitution:      Source Path.        (line  149)

  52906. * default system root:                   Files.              (line  453)

  52907. * define trace state variable, remote request: Tracepoint Packets.

  52908.                                                              (line  121)

  52909. * defining macros interactively:         Macros.             (line   59)

  52910. * definition of a macro, showing:        Macros.             (line   47)

  52911. * delete breakpoints:                    Delete Breaks.      (line   41)

  52912. * deleting breakpoints, watchpoints, catchpoints: Delete Breaks.

  52913.                                                              (line    6)

  52914. * deliver a signal to a program:         Signaling.          (line    6)

  52915. * demangle:                              Symbols.            (line  114)

  52916. * demangler crashes:                     Maintenance Commands.

  52917.                                                              (line  146)

  52918. * demangler crashes <1>:                 Maintenance Commands.

  52919.                                                              (line  173)

  52920. * demangler crashes <2>:                 Maintenance Commands.

  52921.                                                              (line  197)

  52922. * demangling C++ names:                  Print Settings.     (line  510)

  52923. * deprecated commands:                   Maintenance Commands.

  52924.                                                              (line  160)

  52925. * derived type of an object, printing:   Print Settings.     (line  541)

  52926. * descriptor tables display:             DJGPP Native.       (line   24)

  52927. * detach from task, GNU Hurd:            Hurd Native.        (line   59)

  52928. * detach from thread, GNU Hurd:          Hurd Native.        (line  109)

  52929. * direct memory access (DMA) on MS-DOS:  DJGPP Native.       (line   74)

  52930. * directories for source files:          Source Path.        (line    6)

  52931. * directory, compilation:                Source Path.        (line   40)

  52932. * directory, current:                    Source Path.        (line   40)

  52933. * disable address space randomization, remote request: General Query Packets.

  52934.                                                              (line   84)

  52935. * disabling calling functions in the program: Calling.       (line   59)

  52936. * disassembler options:                  Machine Code.       (line  222)

  52937. * disconnected tracing:                  Starting and Stopping Trace Experiments.

  52938.                                                              (line   45)

  52939. * displaced stepping debugging info:     Debugging Output.   (line   75)

  52940. * displaced stepping support:            Maintenance Commands.

  52941.                                                              (line  112)

  52942. * displaced stepping, and process record and replay: Process Record and Replay.

  52943.                                                              (line   96)

  52944. * display command history:               Command History.    (line  110)

  52945. * display derived types:                 Print Settings.     (line  541)

  52946. * display disabled out of scope:         Auto Display.       (line   86)

  52947. * display GDB copyright:                 Help.               (line  167)

  52948. * display of expressions:                Auto Display.       (line    6)

  52949. * display remote monitor communications: Target Commands.    (line  107)

  52950. * display remote packets:                Debugging Output.   (line  159)

  52951. * DJGPP debugging:                       DJGPP Native.       (line    6)

  52952. * DLLs with no debugging symbols:        Non-debug DLL Symbols.

  52953.                                                              (line    6)

  52954. * do not print frame arguments:          Print Settings.     (line  154)

  52955. * documentation:                         Formatting Documentation.

  52956.                                                              (line   22)

  52957. * don't repeat command:                  Define.             (line  111)

  52958. * don't repeat Guile command:            Commands In Guile.  (line   67)

  52959. * don't repeat Python command:           Commands In Python. (line   42)

  52960. * DOS file-name semantics of file names.: Files.             (line  476)

  52961. * DOS serial data link, remote debugging: DJGPP Native.      (line  118)

  52962. * DOS serial port status:                DJGPP Native.       (line  139)

  52963. * DPMI:                                  DJGPP Native.       (line    6)

  52964. * dprintf:                               Dynamic Printf.     (line    6)

  52965. * dump all data collected at tracepoint: tdump.              (line    6)

  52966. * dump core from inferior:               Core File Generation.

  52967.                                                              (line    6)

  52968. * dump data to a file:                   Dump/Restore Files. (line    6)

  52969. * dump/restore files:                    Dump/Restore Files. (line    6)

  52970. * DVC register:                          PowerPC Embedded.   (line    6)

  52971. * DWARF compilation units cache:         Maintenance Commands.

  52972.                                                              (line  408)

  52973. * DWARF DIEs:                            Debugging Output.   (line   56)

  52974. * DWARF frame unwinders:                 Maintenance Commands.

  52975.                                                              (line  422)

  52976. * DWARF Line Tables:                     Debugging Output.   (line   61)

  52977. * DWARF Reading:                         Debugging Output.   (line   68)

  52978. * DWARF-2 CFI and CRIS:                  CRIS.               (line   18)

  52979. * dynamic linking:                       Files.              (line  123)

  52980. * dynamic printf:                        Dynamic Printf.     (line    6)

  52981. * dynamic varobj:                        GDB/MI Variable Objects.

  52982.                                                              (line  166)

  52983. * editing:                               Editing.            (line   15)

  52984. * editing command lines:                 Readline Bare Essentials.

  52985.                                                              (line    6)

  52986. * editing source files:                  Edit.               (line    6)

  52987. * eight-bit characters in strings:       Print Settings.     (line  455)

  52988. * elaboration phase:                     Starting.           (line   92)

  52989. * ELinOS system-wide configuration script: System-wide Configuration Scripts.

  52990.                                                              (line   15)

  52991. * Emacs:                                 Emacs.              (line    6)

  52992. * empty response, for unsupported packets: Overview.         (line   97)

  52993. * enable/disable a breakpoint:           Disabling.          (line    6)

  52994. * enabling and disabling probes:         Static Probe Points.

  52995.                                                              (line   52)

  52996. * entering numbers:                      Numbers.            (line    6)

  52997. * environment (of your program):         Environment.        (line    6)

  52998. * errno values, in file-i/o protocol:    Errno Values.       (line    6)

  52999. * error on valid input:                  Bug Criteria.       (line   12)

  53000. * event debugging info:                  Debugging Output.   (line   81)

  53001. * event designators:                     Event Designators.  (line    6)

  53002. * event handling:                        Set Catchpoints.    (line    6)

  53003. * examine process image:                 Process Information.

  53004.                                                              (line    6)

  53005. * examining data:                        Data.               (line    6)

  53006. * examining memory:                      Memory.             (line    9)

  53007. * exception handlers:                    Set Catchpoints.    (line    6)

  53008. * exceptions, guile:                     Guile Exception Handling.

  53009.                                                              (line    6)

  53010. * exceptions, python:                    Exception Handling. (line    6)

  53011. * exec events, remote reply:             Stop Reply Packets. (line  141)

  53012. * executable file:                       Files.              (line   16)

  53013. * executable file target:                Target Commands.    (line   50)

  53014. * executable file, for remote target:    Remote Configuration.

  53015.                                                              (line  102)

  53016. * execute commands from a file:          Command Files.      (line   17)

  53017. * execute forward or backward in time:   Reverse Execution.  (line   92)

  53018. * execute remote command, remote request: General Query Packets.

  53019.                                                              (line  536)

  53020. * execution, foreground, background and asynchronous: Background Execution.

  53021.                                                              (line    6)

  53022. * exit status of shell commands:         Convenience Vars.   (line  188)

  53023. * exiting GDB:                           Quitting GDB.       (line    6)

  53024. * expand macro once:                     Macros.             (line   38)

  53025. * expanding preprocessor macros:         Macros.             (line   29)

  53026. * explicit locations:                    Explicit Locations. (line    6)

  53027. * explore type:                          Data.               (line  234)

  53028. * explore value:                         Data.               (line  227)

  53029. * exploring hierarchical data structures: Data.              (line  125)

  53030. * expression debugging info:             Debugging Output.   (line   86)

  53031. * expression parser, debugging info:     Debugging Output.   (line  152)

  53032. * expressions:                           Expressions.        (line    6)

  53033. * expressions in Ada:                    Ada.                (line   11)

  53034. * expressions in C or C++:               C.                  (line    6)

  53035. * expressions in C++:                    C Plus Plus Expressions.

  53036.                                                              (line    6)

  53037. * expressions in Modula-2:               Modula-2.           (line   12)

  53038. * extend GDB for remote targets:         Connecting.         (line  279)

  53039. * extending GDB:                         Extending GDB.      (line    6)

  53040. * extra signal information:              Signals.            (line  156)

  53041. * F packet:                              Packets.            (line  150)

  53042. * F reply packet:                        The F Reply Packet. (line    6)

  53043. * F request packet:                      The F Request Packet.

  53044.                                                              (line    6)

  53045. * fast tracepoints:                      Set Tracepoints.    (line   24)

  53046. * fast tracepoints, setting:             Create and Delete Tracepoints.

  53047.                                                              (line   50)

  53048. * fatal signal:                          Bug Criteria.       (line    9)

  53049. * fatal signals:                         Signals.            (line   15)

  53050. * features of the remote protocol:       General Query Packets.

  53051.                                                              (line  589)

  53052. * file name canonicalization:            Files.              (line  520)

  53053. * file transfer:                         File Transfer.      (line    6)

  53054. * file transfer, remote protocol:        Host I/O Packets.   (line    6)

  53055. * file-i/o examples:                     File-I/O Examples.  (line    6)

  53056. * file-i/o overview:                     File-I/O Overview.  (line    6)

  53057. * File-I/O remote protocol extension:    File-I/O Remote Protocol Extension.

  53058.                                                              (line    6)

  53059. * file-i/o reply packet:                 The F Reply Packet. (line    6)

  53060. * file-i/o request packet:               The F Request Packet.

  53061.                                                              (line    6)

  53062. * filename-display:                      Backtrace.          (line  202)

  53063. * find trace snapshot:                   tfind.              (line    6)

  53064. * flinching:                             Messages/Warnings.  (line   49)

  53065. * float promotion:                       ABI.                (line   34)

  53066. * floating point:                        Floating Point Hardware.

  53067.                                                              (line    6)

  53068. * floating point registers:              Registers.          (line   15)

  53069. * floating point, MIPS remote:           MIPS Embedded.      (line   13)

  53070. * focus of debugging:                    Threads.            (line   29)

  53071. * foo:                                   Symbol Errors.      (line   54)

  53072. * foreground execution:                  Background Execution.

  53073.                                                              (line    6)

  53074. * fork events, remote reply:             Stop Reply Packets. (line  104)

  53075. * fork, debugging programs which call:   Forks.              (line    6)

  53076. * format options:                        Print Settings.     (line    6)

  53077. * formatted output:                      Output Formats.     (line    6)

  53078. * Fortran:                               Summary.            (line   40)

  53079. * Fortran Defaults:                      Fortran Defaults.   (line    6)

  53080. * Fortran modules, information about:    Symbols.            (line  555)

  53081. * Fortran operators and expressions:     Fortran Operators.  (line    6)

  53082. * Fortran-specific support in GDB:       Fortran.            (line    6)

  53083. * FR-V shared-library debugging:         Debugging Output.   (line  193)

  53084. * frame debugging info:                  Debugging Output.   (line  101)

  53085. * frame decorator api:                   Frame Decorator API.

  53086.                                                              (line    6)

  53087. * frame filters api:                     Frame Filter API.   (line    6)

  53088. * frame information, printing:           Print Settings.     (line  314)

  53089. * frame level:                           Frames.             (line   28)

  53090. * frame number:                          Frames.             (line   28)

  53091. * frame pointer:                         Frames.             (line   21)

  53092. * frame pointer register:                Registers.          (line   31)

  53093. * frame, definition:                     Frames.             (line    6)

  53094. * frameless execution:                   Frames.             (line   34)

  53095. * frames in guile:                       Frames In Guile.    (line    6)

  53096. * frames in python:                      Frames In Python.   (line    6)

  53097. * free memory information (MS-DOS):      DJGPP Native.       (line   19)

  53098. * FreeBSD:                               FreeBSD.            (line    6)

  53099. * FreeBSD LWP debug messages:            Debugging Output.   (line   92)

  53100. * FreeBSD native target debug messages:  Debugging Output.   (line   97)

  53101. * fstat, file-i/o system call:           stat/fstat.         (line    6)

  53102. * Fujitsu:                               Remote Stub.        (line   68)

  53103. * full symbol tables, listing GDB's internal: Symbols.       (line  645)

  53104. * function call arguments, optimized out: Backtrace.         (line  133)

  53105. * function entry/exit, wrong values of variables: Variables. (line  106)

  53106. * functions and variables by Fortran module: Symbols.        (line  555)

  53107. * functions without line info, and stepping: Continuing and Stepping.

  53108.                                                              (line   92)

  53109. * g packet:                              Packets.            (line  155)

  53110. * G packet:                              Packets.            (line  183)

  53111. * g++, GNU C++ compiler:                 C.                  (line   10)

  53112. * garbled pointers:                      DJGPP Native.       (line   42)

  53113. * GCC and C++:                           C Plus Plus Expressions.

  53114.                                                              (line    8)

  53115. * GDB bugs, reporting:                   Bug Reporting.      (line    6)

  53116. * GDB internal error:                    Maintenance Commands.

  53117.                                                              (line  197)

  53118. * gdb module:                            Basic Python.       (line   28)

  53119. * gdb objects:                           GDB Scheme Data Types.

  53120.                                                              (line    6)

  53121. * GDB reference card:                    Formatting Documentation.

  53122.                                                              (line    6)

  53123. * GDB startup:                           Startup.            (line    6)

  53124. * GDB version number:                    Help.               (line  157)

  53125. * gdb.ini:                               Startup.            (line   69)

  53126. * gdb.printing:                          gdb.printing.       (line    6)

  53127. * gdb.prompt:                            gdb.prompt.         (line    6)

  53128. * gdb.types:                             gdb.types.          (line    6)

  53129. * gdb.Value:                             Values From Inferior.

  53130.                                                              (line    6)

  53131. * GDB/MI development:                    GDB/MI Development and Front Ends.

  53132.                                                              (line    6)

  53133. * GDB/MI General Design:                 GDB/MI General Design.

  53134.                                                              (line    6)

  53135. * GDB/MI, async records:                 GDB/MI Async Records.

  53136.                                                              (line    6)

  53137. * GDB/MI, breakpoint commands:           GDB/MI Breakpoint Commands.

  53138.                                                              (line    6)

  53139. * GDB/MI, compatibility with CLI:        GDB/MI Compatibility with CLI.

  53140.                                                              (line    6)

  53141. * GDB/MI, data manipulation:             GDB/MI Data Manipulation.

  53142.                                                              (line    6)

  53143. * GDB/MI, input syntax:                  GDB/MI Input Syntax.

  53144.                                                              (line    6)

  53145. * GDB/MI, its purpose:                   GDB/MI.             (line   36)

  53146. * GDB/MI, output syntax:                 GDB/MI Output Syntax.

  53147.                                                              (line    6)

  53148. * GDB/MI, result records:                GDB/MI Result Records.

  53149.                                                              (line    6)

  53150. * GDB/MI, simple examples:               GDB/MI Simple Examples.

  53151.                                                              (line    6)

  53152. * GDB/MI, stream records:                GDB/MI Stream Records.

  53153.                                                              (line    6)

  53154. * gdbarch debugging info:                Debugging Output.   (line   23)

  53155. * GDBHISTFILE, environment variable:     Command History.    (line   26)

  53156. * GDBHISTSIZE, environment variable:     Command History.    (line   56)

  53157. * gdbserver, command-line arguments:     Server.             (line   34)

  53158. * gdbserver, connecting:                 Connecting.         (line    6)

  53159. * gdbserver, search path for libthread_db: Server.           (line  254)

  53160. * gdbserver, send all debug output to a single file: Server. (line  148)

  53161. * gdbserver, target extended-remote mode: Connecting.        (line    6)

  53162. * gdbserver, target remote mode:         Connecting.         (line    6)

  53163. * gdbserver, types of connections:       Connecting.         (line    6)

  53164. * GDT:                                   DJGPP Native.       (line   24)

  53165. * get thread information block address:  General Query Packets.

  53166.                                                              (line  303)

  53167. * get thread-local storage address, remote request: General Query Packets.

  53168.                                                              (line  271)

  53169. * gettimeofday, file-i/o system call:    gettimeofday.       (line    6)

  53170. * getting structure elements using gdb.Field objects as subscripts: Values From Inferior.

  53171.                                                              (line   40)

  53172. * global debugging information directories: Separate Debug Files.

  53173.                                                              (line    6)

  53174. * global thread identifier (GDB):        Threads.            (line   88)

  53175. * global thread number:                  Threads.            (line   88)

  53176. * GNAT descriptive types:                Ada Glitches.       (line   57)

  53177. * GNAT encoding:                         Ada Glitches.       (line   57)

  53178. * GNU C++:                               C.                  (line   10)

  53179. * GNU Emacs:                             Emacs.              (line    6)

  53180. * GNU Hurd debugging:                    Hurd Native.        (line    6)

  53181. * GNU/Hurd debug messages:               Debugging Output.   (line  106)

  53182. * GNU/Linux LWP debug messages:          Debugging Output.   (line  121)

  53183. * GNU/Linux namespaces debug messages:   Debugging Output.   (line  125)

  53184. * Go (programming language):             Go.                 (line    6)

  53185. * guile api:                             Guile API.          (line    6)

  53186. * guile architectures:                   Architectures In Guile.

  53187.                                                              (line    6)

  53188. * guile auto-loading:                    Guile Auto-loading. (line    6)

  53189. * guile commands:                        Guile Commands.     (line    6)

  53190. * guile commands <1>:                    Commands In Guile.  (line    6)

  53191. * guile configuration:                   Guile Configuration.

  53192.                                                              (line    6)

  53193. * guile exceptions:                      Guile Exception Handling.

  53194.                                                              (line    6)

  53195. * guile gdb module:                      Basic Guile.        (line   37)

  53196. * guile iterators:                       Iterators In Guile. (line    6)

  53197. * guile modules:                         Guile Modules.      (line    6)

  53198. * guile pagination:                      Basic Guile.        (line    6)

  53199. * guile parameters:                      Parameters In Guile.

  53200.                                                              (line    6)

  53201. * guile pretty printing api:             Guile Pretty Printing API.

  53202.                                                              (line    6)

  53203. * guile scripting:                       Guile.              (line    6)

  53204. * guile scripts directory:               Guile Introduction. (line   15)

  53205. * guile stdout:                          Basic Guile.        (line    6)

  53206. * guile, working with types:             Types In Guile.     (line    6)

  53207. * guile, working with values from inferior: Values From Inferior In Guile.

  53208.                                                              (line    6)

  53209. * H packet:                              Packets.            (line  193)

  53210. * handling signals:                      Signals.            (line   27)

  53211. * hardware breakpoints:                  Set Breaks.         (line   61)

  53212. * hardware debug registers:              Maintenance Commands.

  53213.                                                              (line  468)

  53214. * hardware watchpoints:                  Set Watchpoints.    (line   31)

  53215. * hash mark while downloading:           Target Commands.    (line   98)

  53216. * heuristic-fence-post (Alpha, MIPS):    MIPS.               (line   14)

  53217. * history events:                        Event Designators.  (line    8)

  53218. * history expansion:                     History Interaction.

  53219.                                                              (line    6)

  53220. * history expansion, turn on/off:        Command History.    (line   85)

  53221. * history file:                          Command History.    (line   26)

  53222. * history number:                        Value History.      (line   13)

  53223. * history of values printed by GDB:      Value History.      (line    6)

  53224. * history size:                          Command History.    (line   56)

  53225. * history substitution:                  Command History.    (line   26)

  53226. * hooks, for commands:                   Hooks.              (line    6)

  53227. * hooks, post-command:                   Hooks.              (line   11)

  53228. * hooks, pre-command:                    Hooks.              (line    6)

  53229. * host character set:                    Character Sets.     (line    6)

  53230. * Host I/O, remote protocol:             Host I/O Packets.   (line    6)

  53231. * how many arguments (user-defined commands): Define.        (line   25)

  53232. * HPPA support:                          HPPA.               (line    6)

  53233. * i packet:                              Packets.            (line  207)

  53234. * I packet:                              Packets.            (line  212)

  53235. * i/o:                                   Input/Output.       (line    6)

  53236. * I/O registers (Atmel AVR):             AVR.                (line   10)

  53237. * i386:                                  Remote Stub.        (line   56)

  53238. * i386-stub.c:                           Remote Stub.        (line   56)

  53239. * IDT:                                   DJGPP Native.       (line   24)

  53240. * ignore count (of breakpoint):          Conditions.         (line   79)

  53241. * in-process agent protocol:             In-Process Agent Protocol.

  53242.                                                              (line    6)

  53243. * incomplete type:                       Symbols.            (line  346)

  53244. * indentation in structure display:      Print Settings.     (line  417)

  53245. * index files:                           Index Files.        (line    6)

  53246. * index section format:                  Index Section Format.

  53247.                                                              (line    6)

  53248. * inferior:                              Inferiors Connections and Programs.

  53249.                                                              (line   15)

  53250. * inferior debugging info:               Debugging Output.   (line  110)

  53251. * inferior events in Python:             Events In Python.   (line    6)

  53252. * inferior functions, calling:           Calling.            (line    6)

  53253. * inferior tty:                          Input/Output.       (line   44)

  53254. * inferiors in Python:                   Inferiors In Python.

  53255.                                                              (line    6)

  53256. * infinite recursion in user-defined commands: Define.       (line  128)

  53257. * info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands.

  53258.                                                              (line  335)

  53259. * info for known object files:           Maintenance Commands.

  53260.                                                              (line  320)

  53261. * info line, repeated calls:             Machine Code.       (line   40)

  53262. * info proc cmdline:                     Process Information.

  53263.                                                              (line   41)

  53264. * info proc cwd:                         Process Information.

  53265.                                                              (line   45)

  53266. * info proc exe:                         Process Information.

  53267.                                                              (line   49)

  53268. * info proc files:                       Process Information.

  53269.                                                              (line   53)

  53270. * information about static tracepoint markers: Listing Static Tracepoint Markers.

  53271.                                                              (line    6)

  53272. * information about tracepoints:         Listing Tracepoints.

  53273.                                                              (line    6)

  53274. * inheritance:                           Debugging C Plus Plus.

  53275.                                                              (line   26)

  53276. * init file:                             Startup.            (line   11)

  53277. * init file name:                        Startup.            (line   69)

  53278. * initial frame:                         Frames.             (line   12)

  53279. * initialization file, readline:         Readline Init File. (line    6)

  53280. * injecting code:                        Compiling and Injecting Code.

  53281.                                                              (line    6)

  53282. * inline functions, debugging:           Inline Functions.   (line    6)

  53283. * innermost frame:                       Frames.             (line   12)

  53284. * input syntax for GDB/MI:               GDB/MI Input Syntax.

  53285.                                                              (line    6)

  53286. * installation:                          Installing GDB.     (line    6)

  53287. * instructions, assembly:                Machine Code.       (line   43)

  53288. * integral datatypes, in file-i/o protocol: Integral Datatypes.

  53289.                                                              (line    6)

  53290. * Intel:                                 Remote Stub.        (line   56)

  53291. * Intel disassembly flavor:              Machine Code.       (line  237)

  53292. * Intel Memory Protection Extensions (MPX).: i386.           (line   21)

  53293. * Intel MPX boundary violations:         Signals.            (line  197)

  53294. * Intel Processor Trace:                 Process Record and Replay.

  53295.                                                              (line   75)

  53296. * interaction, readline:                 Readline Interaction.

  53297.                                                              (line    6)

  53298. * internal commands:                     Maintenance Commands.

  53299.                                                              (line    6)

  53300. * internal errors, control of GDB behavior: Maintenance Commands.

  53301.                                                              (line  197)

  53302. * internal GDB breakpoints:              Set Breaks.         (line  374)

  53303. * interrupt:                             Quitting GDB.       (line   13)

  53304. * interrupt debuggee on MS-Windows:      Cygwin Native.      (line    9)

  53305. * interrupt remote programs:             Remote Configuration.

  53306.                                                              (line   36)

  53307. * interrupt remote programs <1>:         Remote Configuration.

  53308.                                                              (line  108)

  53309. * interrupting remote programs:          Connecting.         (line  246)

  53310. * interrupting remote targets:           Bootstrapping.      (line   25)

  53311. * interrupts (remote protocol):          Interrupts.         (line    6)

  53312. * invalid input:                         Bug Criteria.       (line   16)

  53313. * invoke another interpreter:            Interpreters.       (line   39)

  53314. * ipa protocol commands:                 IPA Protocol Commands.

  53315.                                                              (line    6)

  53316. * ipa protocol objects:                  IPA Protocol Objects.

  53317.                                                              (line    6)

  53318. * isatty, file-i/o system call:          isatty.             (line    6)

  53319. * JIT compilation interface:             JIT Interface.      (line    6)

  53320. * JIT debug info reader:                 Custom Debug Info.  (line    6)

  53321. * just-in-time compilation:              JIT Interface.      (line    6)

  53322. * just-in-time compilation, debugging messages: Debugging Output.

  53323.                                                              (line  117)

  53324. * k packet:                              Packets.            (line  216)

  53325. * kernel crash dump:                     BSD libkvm Interface.

  53326.                                                              (line    6)

  53327. * kernel memory image:                   BSD libkvm Interface.

  53328.                                                              (line    6)

  53329. * kill ring:                             Readline Killing Commands.

  53330.                                                              (line   18)

  53331. * killing text:                          Readline Killing Commands.

  53332.                                                              (line    6)

  53333. * languages:                             Languages.          (line    6)

  53334. * last tracepoint number:                Create and Delete Tracepoints.

  53335.                                                              (line  122)

  53336. * latest breakpoint:                     Set Breaks.         (line    6)

  53337. * lazy strings in guile:                 Lazy Strings In Guile.

  53338.                                                              (line    6)

  53339. * lazy strings in python:                Lazy Strings In Python.

  53340.                                                              (line    6)

  53341. * LDT:                                   DJGPP Native.       (line   24)

  53342. * leaving GDB:                           Quitting GDB.       (line    6)

  53343. * libkvm:                                BSD libkvm Interface.

  53344.                                                              (line    6)

  53345. * library list format, remote protocol:  Library List Format.

  53346.                                                              (line    6)

  53347. * library list format, remote protocol <1>: Library List Format for SVR4 Targets.

  53348.                                                              (line    6)

  53349. * limit hardware breakpoints and watchpoints: Remote Configuration.

  53350.                                                              (line   79)

  53351. * limit hardware watchpoints length:     Remote Configuration.

  53352.                                                              (line   91)

  53353. * limit on number of printed array elements: Print Settings. (line  141)

  53354. * limits, in file-i/o protocol:          Limits.             (line    6)

  53355. * line tables in python:                 Line Tables In Python.

  53356.                                                              (line    6)

  53357. * line tables, listing GDB's internal:   Symbols.            (line  692)

  53358. * linespec locations:                    Linespec Locations. (line    6)

  53359. * Linux lightweight processes:           Debugging Output.   (line  121)

  53360. * list active threads, remote request:   General Query Packets.

  53361.                                                              (line  238)

  53362. * list of supported file-i/o calls:      List of Supported Calls.

  53363.                                                              (line    6)

  53364. * list output in GDB/MI:                 GDB/MI Output Syntax.

  53365.                                                              (line  117)

  53366. * list, how many lines to display:       List.               (line   30)

  53367. * listing GDB's internal line tables:    Symbols.            (line  692)

  53368. * listing GDB's internal symbol tables:  Symbols.            (line  645)

  53369. * listing machine instructions:          Machine Code.       (line   43)

  53370. * listing mapped overlays:               Overlay Commands.   (line   60)

  53371. * lists of breakpoints:                  Breakpoints.        (line   45)

  53372. * load address, overlay's:               How Overlays Work.  (line    6)

  53373. * load shared library:                   Files.              (line  327)

  53374. * load symbols from memory:              Files.              (line  193)

  53375. * local socket, target remote:           Connecting.         (line  147)

  53376. * local variables:                       Symbols.            (line  415)

  53377. * locate address:                        Output Formats.     (line   35)

  53378. * location:                              Specify Location.   (line    6)

  53379. * lock scheduler:                        All-Stop Mode.      (line   37)

  53380. * log output in GDB/MI:                  GDB/MI Output Syntax.

  53381.                                                              (line  113)

  53382. * logging file name:                     Logging Output.     (line   12)

  53383. * logging GDB output:                    Logging Output.     (line    6)

  53384. * lseek flags, in file-i/o protocol:     Lseek Flags.        (line    6)

  53385. * lseek, file-i/o system call:           lseek.              (line    6)

  53386. * m packet:                              Packets.            (line  239)

  53387. * M packet:                              Packets.            (line  259)

  53388. * m680x0:                                Remote Stub.        (line   59)

  53389. * m68k-stub.c:                           Remote Stub.        (line   59)

  53390. * Mach-O symbols processing:             Debugging Output.   (line  130)

  53391. * machine instructions:                  Machine Code.       (line   43)

  53392. * macro definition, showing:             Macros.             (line   47)

  53393. * macro expansion, showing the results of preprocessor: Macros.

  53394.                                                              (line   29)

  53395. * macros, example of debugging with:     Macros.             (line   83)

  53396. * macros, from debug info:               Macros.             (line   47)

  53397. * macros, user-defined:                  Macros.             (line   59)

  53398. * mailing lists:                         GDB/MI Development and Front Ends.

  53399.                                                              (line   77)

  53400. * maintenance commands:                  Maintenance Commands.

  53401.                                                              (line    6)

  53402. * Man pages:                             Man Pages.          (line    6)

  53403. * managing frame filters:                Frame Filter Management.

  53404.                                                              (line    6)

  53405. * manual overlay debugging:              Overlay Commands.   (line   23)

  53406. * map an overlay:                        Overlay Commands.   (line   30)

  53407. * mapinfo list, QNX Neutrino:            Process Information.

  53408.                                                              (line  131)

  53409. * mapped address:                        How Overlays Work.  (line    6)

  53410. * mapped overlays:                       How Overlays Work.  (line    6)

  53411. * markers, static tracepoints:           Set Tracepoints.    (line   28)

  53412. * maximum value for offset of closest symbol: Print Settings.

  53413.                                                              (line   70)

  53414. * member functions:                      C Plus Plus Expressions.

  53415.                                                              (line   16)

  53416. * memory address space mappings:         Process Information.

  53417.                                                              (line   80)

  53418. * memory address space mappings <1>:     Maintenance Commands.

  53419.                                                              (line  260)

  53420. * memory map format:                     Memory Map Format.  (line    6)

  53421. * memory region attributes:              Memory Region Attributes.

  53422.                                                              (line    6)

  53423. * memory tracing:                        Breakpoints.        (line   17)

  53424. * memory transfer, in file-i/o protocol: Memory Transfer.    (line    6)

  53425. * memory used by commands:               Maintenance Commands.

  53426.                                                              (line  569)

  53427. * memory used for symbol tables:         Files.              (line  315)

  53428. * memory, alignment and size of remote accesses: Packets.    (line  247)

  53429. * memory, viewing as typed object:       Expressions.        (line   41)

  53430. * mi interpreter:                        Interpreters.       (line   26)

  53431. * mi1 interpreter:                       Interpreters.       (line   37)

  53432. * mi2 interpreter:                       Interpreters.       (line   34)

  53433. * mi3 interpreter:                       Interpreters.       (line   31)

  53434. * minimal language:                      Unsupported Languages.

  53435.                                                              (line    6)

  53436. * minimal symbol dump:                   Symbols.            (line  619)

  53437. * Minimal symbols and DLLs:              Non-debug DLL Symbols.

  53438.                                                              (line    6)

  53439. * MIPS addresses, masking:               MIPS.               (line   80)

  53440. * MIPS remote floating point:            MIPS Embedded.      (line   13)

  53441. * MIPS stack:                            MIPS.               (line    6)

  53442. * miscellaneous settings:                Other Misc Settings.

  53443.                                                              (line    6)

  53444. * MMX registers (x86):                   Registers.          (line   76)

  53445. * mode_t values, in file-i/o protocol:   mode_t Values.      (line    6)

  53446. * Modula-2:                              Summary.            (line   29)

  53447. * Modula-2 built-ins:                    Built-In Func/Proc. (line    6)

  53448. * Modula-2 checks:                       M2 Checks.          (line    6)

  53449. * Modula-2 constants:                    Built-In Func/Proc. (line  114)

  53450. * Modula-2 defaults:                     M2 Defaults.        (line    6)

  53451. * Modula-2 operators:                    M2 Operators.       (line    6)

  53452. * Modula-2 types:                        M2 Types.           (line    6)

  53453. * Modula-2, deviations from:             Deviations.         (line    6)

  53454. * Modula-2, GDB support:                 Modula-2.           (line    6)

  53455. * module functions and variables:        Symbols.            (line  555)

  53456. * modules:                               Symbols.            (line  547)

  53457. * monitor commands, for gdbserver:       Server.             (line  218)

  53458. * Motorola 680x0:                        Remote Stub.        (line   59)

  53459. * MS Windows debugging:                  Cygwin Native.      (line    6)

  53460. * MS-DOS system info:                    DJGPP Native.       (line   19)

  53461. * MS-DOS-specific commands:              DJGPP Native.       (line    6)

  53462. * multiple locations, breakpoints:       Set Breaks.         (line  200)

  53463. * multiple processes:                    Forks.              (line    6)

  53464. * multiple targets:                      Active Targets.     (line    6)

  53465. * multiple threads:                      Threads.            (line    6)

  53466. * multiple threads, backtrace:           Backtrace.          (line   97)

  53467. * multiple-symbols menu:                 Ambiguous Expressions.

  53468.                                                              (line   51)

  53469. * multiprocess extensions, in remote protocol: General Query Packets.

  53470.                                                              (line  913)

  53471. * name a thread:                         Threads.            (line  247)

  53472. * names of symbols:                      Symbols.            (line   14)

  53473. * namespace in C++:                      C Plus Plus Expressions.

  53474.                                                              (line   20)

  53475. * native Cygwin debugging:               Cygwin Native.      (line    6)

  53476. * native DJGPP debugging:                DJGPP Native.       (line    6)

  53477. * native script auto-loading:            Auto-loading sequences.

  53478.                                                              (line    6)

  53479. * native target:                         Target Commands.    (line   85)

  53480. * negative breakpoint numbers:           Set Breaks.         (line  374)

  53481. * never read symbols:                    Files.              (line  101)

  53482. * New SYSTAG message:                    Threads.            (line   35)

  53483. * new user interface:                    Interpreters.       (line   68)

  53484. * Newlib OS ABI and its influence on the longjmp handling: ABI.

  53485.                                                              (line   11)

  53486. * Nios II architecture:                  Nios II.            (line    6)

  53487. * no debug info functions:               Calling.            (line   78)

  53488. * no debug info variables:               Variables.          (line  142)

  53489. * non-member C++ functions, set breakpoint in: Set Breaks.   (line  113)

  53490. * non-stop mode:                         Non-Stop Mode.      (line    6)

  53491. * non-stop mode, and process record and replay: Process Record and Replay.

  53492.                                                              (line  101)

  53493. * non-stop mode, and set displaced-stepping: Maintenance Commands.

  53494.                                                              (line  129)

  53495. * non-stop mode, remote request:         General Query Packets.

  53496.                                                              (line  379)

  53497. * noninvasive task options:              Hurd Native.        (line   72)

  53498. * notation, readline:                    Readline Bare Essentials.

  53499.                                                              (line    6)

  53500. * notational conventions, for GDB/MI:    GDB/MI.             (line   52)

  53501. * notification packets:                  Notification Packets.

  53502.                                                              (line    6)

  53503. * notify output in GDB/MI:               GDB/MI Output Syntax.

  53504.                                                              (line  102)

  53505. * NULL elements in arrays:               Print Settings.     (line  408)

  53506. * number of array elements to print:     Print Settings.     (line  141)

  53507. * number representation:                 Numbers.            (line    6)

  53508. * numbers for breakpoints:               Breakpoints.        (line   38)

  53509. * object files, relocatable, reading symbols from: Files.    (line  146)

  53510. * Objective-C:                           Objective-C.        (line    6)

  53511. * Objective-C, classes and selectors:    Symbols.            (line  570)

  53512. * Objective-C, print objects:            The Print Command with Objective-C.

  53513.                                                              (line    6)

  53514. * OBJFILE-gdb.gdb:                       objfile-gdbdotext file.

  53515.                                                              (line    6)

  53516. * OBJFILE-gdb.py:                        objfile-gdbdotext file.

  53517.                                                              (line    6)

  53518. * OBJFILE-gdb.scm:                       objfile-gdbdotext file.

  53519.                                                              (line    6)

  53520. * objfiles in guile:                     Objfiles In Guile.  (line    6)

  53521. * objfiles in python:                    Objfiles In Python. (line    6)

  53522. * observer debugging info:               Debugging Output.   (line  142)

  53523. * octal escapes in strings:              Print Settings.     (line  455)

  53524. * online documentation:                  Help.               (line    6)

  53525. * opaque data types:                     Symbols.            (line  582)

  53526. * open flags, in file-i/o protocol:      Open Flags.         (line    6)

  53527. * open, file-i/o system call:            open.               (line    6)

  53528. * OpenCL C:                              OpenCL C.           (line    6)

  53529. * OpenCL C Datatypes:                    OpenCL C Datatypes. (line    6)

  53530. * OpenCL C Expressions:                  OpenCL C Expressions.

  53531.                                                              (line    6)

  53532. * OpenCL C Operators:                    OpenCL C Operators. (line    6)

  53533. * OpenRISC 1000:                         OpenRISC 1000.      (line    6)

  53534. * operate-and-get-next:                  Editing.            (line   32)

  53535. * operating system information:          Operating System Information.

  53536.                                                              (line    6)

  53537. * operating system information, process list: Process list.  (line    6)

  53538. * optimized code, debugging:             Optimized Code.     (line    6)

  53539. * optimized code, wrong values of variables: Variables.      (line  106)

  53540. * optimized out value in guile:          Values From Inferior In Guile.

  53541.                                                              (line  102)

  53542. * optimized out value in Python:         Values From Inferior.

  53543.                                                              (line   70)

  53544. * optimized out, in backtrace:           Backtrace.          (line  133)

  53545. * optional debugging messages:           Debugging Output.   (line    6)

  53546. * optional warnings:                     Messages/Warnings.  (line    6)

  53547. * OS ABI:                                ABI.                (line   11)

  53548. * OS information:                        OS Information.     (line    6)

  53549. * out-of-line single-stepping:           Maintenance Commands.

  53550.                                                              (line  112)

  53551. * outermost frame:                       Frames.             (line   12)

  53552. * output formats:                        Output Formats.     (line    6)

  53553. * output syntax of GDB/MI:               GDB/MI Output Syntax.

  53554.                                                              (line    6)

  53555. * overlay area:                          How Overlays Work.  (line    6)

  53556. * overlay example program:               Overlay Sample Program.

  53557.                                                              (line    6)

  53558. * overlays:                              Overlays.           (line    6)

  53559. * overlays, setting breakpoints in:      Overlay Commands.   (line   91)

  53560. * overloaded functions, calling:         C Plus Plus Expressions.

  53561.                                                              (line   26)

  53562. * overloaded functions, overload resolution: Debugging C Plus Plus.

  53563.                                                              (line   59)

  53564. * overloading in C++:                    Debugging C Plus Plus.

  53565.                                                              (line   15)

  53566. * overloading, Ada:                      Overloading support for Ada.

  53567.                                                              (line    6)

  53568. * p packet:                              Packets.            (line  271)

  53569. * P packet:                              Packets.            (line  284)

  53570. * packet acknowledgment, for GDB remote: Packet Acknowledgment.

  53571.                                                              (line    6)

  53572. * packet size, remote protocol:          General Query Packets.

  53573.                                                              (line  819)

  53574. * packets, notification:                 Notification Packets.

  53575.                                                              (line    6)

  53576. * packets, reporting on stdout:          Debugging Output.   (line  159)

  53577. * packets, tracepoint:                   Tracepoint Packets. (line    6)

  53578. * page size:                             Screen Size.        (line    6)

  53579. * page tables display (MS-DOS):          DJGPP Native.       (line   55)

  53580. * pagination:                            Screen Size.        (line    6)

  53581. * parameters in guile:                   Parameters In Guile.

  53582.                                                              (line    6)

  53583. * parameters in python:                  Parameters In Python.

  53584.                                                              (line    6)

  53585. * partial symbol dump:                   Symbols.            (line  619)

  53586. * partial symbol tables, listing GDB's internal: Symbols.    (line  645)

  53587. * Pascal:                                Summary.            (line   35)

  53588. * Pascal objects, static members display: Print Settings.    (line  570)

  53589. * Pascal support in GDB, limitations:    Pascal.             (line    6)

  53590. * pass signals to inferior, remote request: General Query Packets.

  53591.                                                              (line  440)

  53592. * patching binaries:                     Patching.           (line    6)

  53593. * patching object files:                 Files.              (line   26)

  53594. * pause current task (GNU Hurd):         Hurd Native.        (line   48)

  53595. * pause current thread (GNU Hurd):       Hurd Native.        (line   90)

  53596. * pauses in output:                      Screen Size.        (line    6)

  53597. * pending breakpoints:                   Set Breaks.         (line  245)

  53598. * physical address from linear address:  DJGPP Native.       (line   80)

  53599. * physname:                              Debugging Output.   (line   41)

  53600. * pipe, target remote to:                Connecting.         (line  234)

  53601. * pipes:                                 Starting.           (line   64)

  53602. * pointer values, in file-i/o protocol:  Pointer Values.     (line    6)

  53603. * pointer, finding referent:             Print Settings.     (line   80)

  53604. * port rights, GNU Hurd:                 Hurd Native.        (line   84)

  53605. * port sets, GNU Hurd:                   Hurd Native.        (line   84)

  53606. * PowerPC architecture:                  PowerPC.            (line    6)

  53607. * prefix for data files:                 Data Files.         (line    6)

  53608. * prefix for executable and shared library file names: Files.

  53609.                                                              (line  386)

  53610. * premature return from system calls:    Interrupted System Calls.

  53611.                                                              (line    6)

  53612. * preprocessor macro expansion, showing the results of: Macros.

  53613.                                                              (line   29)

  53614. * pretty print arrays:                   Print Settings.     (line  115)

  53615. * pretty print C++ virtual function tables: Print Settings.  (line  581)

  53616. * pretty-printer commands:               Pretty-Printer Commands.

  53617.                                                              (line    6)

  53618. * print all frame argument values:       Print Settings.     (line  154)

  53619. * print an Objective-C object description: The Print Command with Objective-C.

  53620.                                                              (line   11)

  53621. * print array indexes:                   Print Settings.     (line  125)

  53622. * print frame argument values for scalars only: Print Settings.

  53623.                                                              (line  154)

  53624. * print list of auto-loaded canned sequences of commands scripts: Auto-loading sequences.

  53625.                                                              (line   21)

  53626. * print list of auto-loaded Guile scripts: Guile Auto-loading.

  53627.                                                              (line   23)

  53628. * print list of auto-loaded Python scripts: Python Auto-loading.

  53629.                                                              (line   23)

  53630. * print messages on inferior start and exit: Inferiors Connections and Programs.

  53631.                                                              (line  169)

  53632. * print messages on thread start and exit: Threads.          (line  272)

  53633. * print messages when symbols are loaded: Symbols.           (line  600)

  53634. * print settings:                        Print Settings.     (line    6)

  53635. * print structures in indented form:     Print Settings.     (line  417)

  53636. * print/don't print memory addresses:    Print Settings.     (line   13)

  53637. * printing byte arrays:                  Output Formats.     (line   60)

  53638. * printing data:                         Data.               (line    6)

  53639. * printing frame argument values:        Print Settings.     (line  154)

  53640. * printing frame information:            Print Settings.     (line  314)

  53641. * printing nested structures:            Print Settings.     (line  362)

  53642. * printing strings:                      Output Formats.     (line   60)

  53643. * probe static tracepoint marker:        Create and Delete Tracepoints.

  53644.                                                              (line   75)

  53645. * probing markers, static tracepoints:   Set Tracepoints.    (line   28)

  53646. * process detailed status information:   Process Information.

  53647.                                                              (line   89)

  53648. * process ID:                            Process Information.

  53649.                                                              (line   25)

  53650. * process info via /proc:                Process Information.

  53651.                                                              (line    6)

  53652. * process list, QNX Neutrino:            Process Information.

  53653.                                                              (line  127)

  53654. * process record and replay:             Process Record and Replay.

  53655.                                                              (line    6)

  53656. * process status register:               Registers.          (line   31)

  53657. * processes, multiple:                   Forks.              (line    6)

  53658. * procfs API calls:                      Process Information.

  53659.                                                              (line  106)

  53660. * profiling GDB:                         Maintenance Commands.

  53661.                                                              (line  452)

  53662. * program counter register:              Registers.          (line   31)

  53663. * program entry point:                   Backtrace.          (line  155)

  53664. * programming in guile:                  Guile API.          (line    6)

  53665. * programming in python:                 Python API.         (line    6)

  53666. * progspaces in guile:                   Progspaces In Guile.

  53667.                                                              (line    6)

  53668. * progspaces in python:                  Progspaces In Python.

  53669.                                                              (line    6)

  53670. * prompt:                                Prompt.             (line    6)

  53671. * protocol basics, file-i/o:             Protocol Basics.    (line    6)

  53672. * protocol, GDB remote serial:           Overview.           (line   14)

  53673. * protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes.

  53674.                                                              (line    6)

  53675. * python api:                            Python API.         (line    6)

  53676. * Python architectures:                  Architectures In Python.

  53677.                                                              (line    6)

  53678. * Python auto-loading:                   Python Auto-loading.

  53679.                                                              (line    6)

  53680. * python commands:                       Python Commands.    (line    6)

  53681. * python commands <1>:                   Commands In Python. (line    6)

  53682. * python convenience functions:          Functions In Python.

  53683.                                                              (line    6)

  53684. * python directory:                      Python.             (line   12)

  53685. * python exceptions:                     Exception Handling. (line    6)

  53686. * python finish breakpoints:             Finish Breakpoints in Python.

  53687.                                                              (line    6)

  53688. * python functions:                      Basic Python.       (line   28)

  53689. * python module:                         Basic Python.       (line   28)

  53690. * python modules:                        Python modules.     (line    6)

  53691. * python pagination:                     Basic Python.       (line    6)

  53692. * python parameters:                     Parameters In Python.

  53693.                                                              (line    6)

  53694. * python pretty printing api:            Pretty Printing API.

  53695.                                                              (line    6)

  53696. * python scripting:                      Python.             (line    6)

  53697. * python stdout:                         Basic Python.       (line    6)

  53698. * Python TUI Windows:                    TUI Windows In Python.

  53699.                                                              (line    6)

  53700. * Python, working with types:            Types In Python.    (line    6)

  53701. * python, working with values from inferior: Values From Inferior.

  53702.                                                              (line    6)

  53703. * q packet:                              Packets.            (line  296)

  53704. * Q packet:                              Packets.            (line  296)

  53705. * QAllow packet:                         General Query Packets.

  53706.                                                              (line   44)

  53707. * qAttached packet:                      General Query Packets.

  53708.                                                              (line 1381)

  53709. * qC packet:                             General Query Packets.

  53710.                                                              (line   55)

  53711. * QCatchSyscalls packet:                 General Query Packets.

  53712.                                                              (line  401)

  53713. * qCRC packet:                           General Query Packets.

  53714.                                                              (line   65)

  53715. * QDisableRandomization packet:          General Query Packets.

  53716.                                                              (line   84)

  53717. * QEnvironmentHexEncoded packet:         General Query Packets.

  53718.                                                              (line  144)

  53719. * QEnvironmentReset packet:              General Query Packets.

  53720.                                                              (line  197)

  53721. * QEnvironmentUnset packet:              General Query Packets.

  53722.                                                              (line  173)

  53723. * qfThreadInfo packet:                   General Query Packets.

  53724.                                                              (line  238)

  53725. * qGetTIBAddr packet:                    General Query Packets.

  53726.                                                              (line  303)

  53727. * qGetTLSAddr packet:                    General Query Packets.

  53728.                                                              (line  271)

  53729. * QNonStop packet:                       General Query Packets.

  53730.                                                              (line  379)

  53731. * qOffsets packet:                       General Query Packets.

  53732.                                                              (line  342)

  53733. * qP packet:                             General Query Packets.

  53734.                                                              (line  369)

  53735. * QPassSignals packet:                   General Query Packets.

  53736.                                                              (line  440)

  53737. * QProgramSignals packet:                General Query Packets.

  53738.                                                              (line  469)

  53739. * qRcmd packet:                          General Query Packets.

  53740.                                                              (line  536)

  53741. * qSearch memory packet:                 General Query Packets.

  53742.                                                              (line  558)

  53743. * QSetWorkingDir packet:                 General Query Packets.

  53744.                                                              (line  219)

  53745. * QStartNoAckMode packet:                General Query Packets.

  53746.                                                              (line  575)

  53747. * QStartupWithShell packet:              General Query Packets.

  53748.                                                              (line  114)

  53749. * qsThreadInfo packet:                   General Query Packets.

  53750.                                                              (line  238)

  53751. * qSupported packet:                     General Query Packets.

  53752.                                                              (line  589)

  53753. * qSymbol packet:                        General Query Packets.

  53754.                                                              (line 1033)

  53755. * qTBuffer packet:                       Tracepoint Packets. (line  393)

  53756. * QTBuffer size packet:                  Tracepoint Packets. (line  406)

  53757. * QTDisable packet:                      Tracepoint Packets. (line  209)

  53758. * QTDisconnected packet:                 Tracepoint Packets. (line  228)

  53759. * QTDP packet:                           Tracepoint Packets. (line   10)

  53760. * QTDPsrc packet:                        Tracepoint Packets. (line   90)

  53761. * QTDV packet:                           Tracepoint Packets. (line  121)

  53762. * QTEnable packet:                       Tracepoint Packets. (line  204)

  53763. * qTfP packet:                           Tracepoint Packets. (line  335)

  53764. * QTFrame packet:                        Tracepoint Packets. (line  133)

  53765. * qTfSTM packet:                         Tracepoint Packets. (line  352)

  53766. * qTfV packet:                           Tracepoint Packets. (line  343)

  53767. * QThreadEvents packet:                  General Query Packets.

  53768.                                                              (line  509)

  53769. * qThreadExtraInfo packet:               General Query Packets.

  53770.                                                              (line 1076)

  53771. * QTinit packet:                         Tracepoint Packets. (line  214)

  53772. * qTMinFTPILen packet:                   Tracepoint Packets. (line  171)

  53773. * QTNotes packet:                        Tracepoint Packets. (line  411)

  53774. * qTP packet:                            Tracepoint Packets. (line  307)

  53775. * QTro packet:                           Tracepoint Packets. (line  217)

  53776. * QTSave packet:                         Tracepoint Packets. (line  387)

  53777. * qTsP packet:                           Tracepoint Packets. (line  336)

  53778. * qTsSTM packet:                         Tracepoint Packets. (line  352)

  53779. * QTStart packet:                        Tracepoint Packets. (line  195)

  53780. * qTStatus packet:                       Tracepoint Packets. (line  234)

  53781. * qTSTMat packet:                        Tracepoint Packets. (line  381)

  53782. * QTStop packet:                         Tracepoint Packets. (line  201)

  53783. * qTsV packet:                           Tracepoint Packets. (line  344)

  53784. * qTV packet:                            Tracepoint Packets. (line  318)

  53785. * qualified thread ID:                   Threads.            (line   52)

  53786. * query attached, remote request:        General Query Packets.

  53787.                                                              (line 1381)

  53788. * quotes in commands:                    Completion.         (line   83)

  53789. * quoting Ada internal identifiers:      Additions to Ada.   (line   76)

  53790. * quoting names:                         Symbols.            (line   14)

  53791. * qXfer packet:                          General Query Packets.

  53792.                                                              (line 1113)

  53793. * r packet:                              Packets.            (line  300)

  53794. * R packet:                              Packets.            (line  305)

  53795. * range checking:                        Type Checking.      (line   45)

  53796. * range stepping:                        Continuing and Stepping.

  53797.                                                              (line  217)

  53798. * ranged breakpoint:                     PowerPC Embedded.   (line   33)

  53799. * ranges of breakpoints:                 Breakpoints.        (line   45)

  53800. * Ravenscar Profile:                     Ravenscar Profile.  (line    6)

  53801. * Ravenscar thread:                      Ravenscar Profile.  (line   26)

  53802. * raw printing:                          Output Formats.     (line   76)

  53803. * read special object, remote request:   General Query Packets.

  53804.                                                              (line 1113)

  53805. * read, file-i/o system call:            read.               (line    6)

  53806. * read-only sections:                    Files.              (line  265)

  53807. * reading symbols from relocatable object files: Files.      (line  146)

  53808. * reading symbols immediately:           Files.              (line   94)

  53809. * readline:                              Editing.            (line    6)

  53810. * Readline application name:             Editing.            (line   29)

  53811. * receive rights, GNU Hurd:              Hurd Native.        (line   84)

  53812. * recent tracepoint number:              Create and Delete Tracepoints.

  53813.                                                              (line  122)

  53814. * record aggregates (Ada):               Omissions from Ada. (line   44)

  53815. * record mode:                           Process Record and Replay.

  53816.                                                              (line   19)

  53817. * record serial communications on file:  Remote Configuration.

  53818.                                                              (line   64)

  53819. * recording a session script:            Bug Reporting.      (line   93)

  53820. * recording inferior's execution and replaying it: Process Record and Replay.

  53821.                                                              (line    6)

  53822. * recordings in python:                  Recordings In Python.

  53823.                                                              (line    6)

  53824. * redirection:                           Input/Output.       (line    6)

  53825. * reference card:                        Formatting Documentation.

  53826.                                                              (line    6)

  53827. * reference declarations:                C Plus Plus Expressions.

  53828.                                                              (line   50)

  53829. * register packet format, MIPS:          MIPS Register packet Format.

  53830.                                                              (line    6)

  53831. * registers:                             Registers.          (line    6)

  53832. * Registers In Python:                   Registers In Python.

  53833.                                                              (line    6)

  53834. * regular expression:                    Set Breaks.         (line   90)

  53835. * reloading the overlay table:           Overlay Commands.   (line   52)

  53836. * relocatable object files, reading symbols from: Files.     (line  146)

  53837. * remote async notification debugging info: Debugging Output.

  53838.                                                              (line  136)

  53839. * remote connection commands:            Connecting.         (line  127)

  53840. * remote connection without stubs:       Server.             (line    6)

  53841. * remote debugging:                      Remote Debugging.   (line    6)

  53842. * remote debugging, connecting:          Connecting.         (line    6)

  53843. * remote debugging, detach and program exit: Connecting.     (line   19)

  53844. * remote debugging, symbol files:        Connecting.         (line   97)

  53845. * remote debugging, types of connections: Connecting.        (line    6)

  53846. * remote memory comparison:              Memory.             (line  142)

  53847. * remote packets, enabling and disabling: Remote Configuration.

  53848.                                                              (line  159)

  53849. * remote programs, interrupting:         Connecting.         (line  246)

  53850. * remote protocol debugging:             Debugging Output.   (line  159)

  53851. * remote protocol, binary data:          Overview.           (line   63)

  53852. * remote protocol, field separator:      Overview.           (line   55)

  53853. * remote query requests:                 General Query Packets.

  53854.                                                              (line    6)

  53855. * remote serial debugging summary:       Debug Session.      (line    6)

  53856. * remote serial debugging, overview:     Remote Stub.        (line   14)

  53857. * remote serial protocol:                Overview.           (line   14)

  53858. * remote serial stub:                    Stub Contents.      (line    6)

  53859. * remote serial stub list:               Remote Stub.        (line   53)

  53860. * remote serial stub, initialization:    Stub Contents.      (line   10)

  53861. * remote serial stub, main routine:      Stub Contents.      (line   15)

  53862. * remote stub, example:                  Remote Stub.        (line    6)

  53863. * remote stub, support routines:         Bootstrapping.      (line    6)

  53864. * remote target:                         Target Commands.    (line   58)

  53865. * remote target, file transfer:          File Transfer.      (line    6)

  53866. * remote target, limit break- and watchpoints: Remote Configuration.

  53867.                                                              (line   79)

  53868. * remote target, limit watchpoints length: Remote Configuration.

  53869.                                                              (line   91)

  53870. * remote timeout:                        Remote Configuration.

  53871.                                                              (line   72)

  53872. * remove actions from a tracepoint:      Tracepoint Actions. (line   21)

  53873. * remove duplicate history:              Command History.    (line   69)

  53874. * rename, file-i/o system call:          rename.             (line    6)

  53875. * Renesas:                               Remote Stub.        (line   62)

  53876. * repeated array elements:               Print Settings.     (line  348)

  53877. * repeating command sequences:           Command Syntax.     (line   41)

  53878. * repeating commands:                    Command Syntax.     (line   21)

  53879. * replay log events, remote reply:       Stop Reply Packets. (line   70)

  53880. * replay mode:                           Process Record and Replay.

  53881.                                                              (line   10)

  53882. * reporting bugs in GDB:                 GDB Bugs.           (line    6)

  53883. * reprint the last value:                Data.               (line  112)

  53884. * reprint the last value <1>:            Compiling and Injecting Code.

  53885.                                                              (line   74)

  53886. * reset environment, remote request:     General Query Packets.

  53887.                                                              (line  197)

  53888. * resources used by commands:            Maintenance Commands.

  53889.                                                              (line  523)

  53890. * response time, MIPS debugging:         MIPS.               (line   10)

  53891. * restart:                               Checkpoint/Restart. (line    6)

  53892. * restore data from a file:              Dump/Restore Files. (line    6)

  53893. * restrictions on Go expressions:        Go.                 (line   35)

  53894. * result records in GDB/MI:              GDB/MI Result Records.

  53895.                                                              (line    6)

  53896. * resume threads of multiple processes simultaneously: All-Stop Mode.

  53897.                                                              (line   54)

  53898. * resuming execution:                    Continuing and Stepping.

  53899.                                                              (line    6)

  53900. * returning from a function:             Returning.          (line    6)

  53901. * reverse execution:                     Reverse Execution.  (line    6)

  53902. * rewind program state:                  Checkpoint/Restart. (line    6)

  53903. * run to first instruction:              Starting.           (line  114)

  53904. * run to main procedure:                 Starting.           (line   81)

  53905. * run until specified location:          Continuing and Stepping.

  53906.                                                              (line  124)

  53907. * running:                               Starting.           (line    6)

  53908. * running programs backward:             Reverse Execution.  (line    6)

  53909. * s packet:                              Packets.            (line  312)

  53910. * S packet:                              Packets.            (line  321)

  53911. * S12Z support:                          S12Z.               (line    6)

  53912. * save breakpoints to a file for future sessions: Save Breakpoints.

  53913.                                                              (line    9)

  53914. * save command history:                  Command History.    (line   44)

  53915. * save GDB output to a file:             Logging Output.     (line    6)

  53916. * save tracepoints for future sessions:  save tracepoints.   (line    6)

  53917. * scheduler locking mode:                All-Stop Mode.      (line   37)

  53918. * scope:                                 M2 Scope.           (line    6)

  53919. * screen size:                           Screen Size.        (line    6)

  53920. * scripting commands:                    Command Files.      (line    6)

  53921. * scripting with guile:                  Guile.              (line    6)

  53922. * scripting with python:                 Python.             (line    6)

  53923. * search for a thread:                   Threads.            (line  258)

  53924. * search path for libthread_db:          Threads.            (line  293)

  53925. * searching memory:                      Searching Memory.   (line    6)

  53926. * searching memory, in remote debugging: General Query Packets.

  53927.                                                              (line  558)

  53928. * searching source files:                Search.             (line    6)

  53929. * section offsets, remote request:       General Query Packets.

  53930.                                                              (line  342)

  53931. * segment descriptor tables:             DJGPP Native.       (line   24)

  53932. * select Ctrl-C, BREAK or BREAK-g:       Remote Configuration.

  53933.                                                              (line  108)

  53934. * select trace snapshot:                 tfind.              (line    6)

  53935. * selected frame:                        Stack.              (line   19)

  53936. * selecting guile pretty-printers:       Selecting Guile Pretty-Printers.

  53937.                                                              (line    6)

  53938. * selecting python pretty-printers:      Selecting Pretty-Printers.

  53939.                                                              (line    6)

  53940. * self tests:                            Maintenance Commands.

  53941.                                                              (line  374)

  53942. * self tests <1>:                        Maintenance Commands.

  53943.                                                              (line  380)

  53944. * semaphores on static probe points:     Static Probe Points.

  53945.                                                              (line   20)

  53946. * send command to remote monitor:        Connecting.         (line  279)

  53947. * send command to simulator:             Embedded Processors.

  53948.                                                              (line    9)

  53949. * send interrupt-sequence on start:      Remote Configuration.

  53950.                                                              (line  121)

  53951. * send rights, GNU Hurd:                 Hurd Native.        (line   84)

  53952. * send the output of a gdb command to a shell command: Shell Commands.

  53953.                                                              (line   26)

  53954. * sending files to remote systems:       File Transfer.      (line    6)

  53955. * separate debug sections:               MiniDebugInfo.      (line    6)

  53956. * separate debugging information files:  Separate Debug Files.

  53957.                                                              (line    6)

  53958. * sequence-id, for GDB remote:           Overview.           (line   30)

  53959. * serial connections, debugging:         Debugging Output.   (line  159)

  53960. * serial line, target remote:            Connecting.         (line  136)

  53961. * serial protocol, GDB remote:           Overview.           (line   14)

  53962. * server prefix:                         Server Prefix.      (line    6)

  53963. * server, command prefix:                Command History.    (line   20)

  53964. * set ABI for MIPS:                      MIPS.               (line   32)

  53965. * set breakpoints in many functions:     Set Breaks.         (line   90)

  53966. * set breakpoints on all functions:      Set Breaks.         (line  117)

  53967. * set environment variable, remote request: General Query Packets.

  53968.                                                              (line  144)

  53969. * set exec-file-mismatch:                Attach.             (line   34)

  53970. * set fast tracepoint:                   Create and Delete Tracepoints.

  53971.                                                              (line   50)

  53972. * set inferior controlling terminal:     Input/Output.       (line   44)

  53973. * set static tracepoint:                 Create and Delete Tracepoints.

  53974.                                                              (line   75)

  53975. * set tdesc filename:                    Retrieving Descriptions.

  53976.                                                              (line   18)

  53977. * set tracepoint:                        Create and Delete Tracepoints.

  53978.                                                              (line    6)

  53979. * set working directory, remote request: General Query Packets.

  53980.                                                              (line  219)

  53981. * setting variables:                     Assignment.         (line    6)

  53982. * setting watchpoints:                   Set Watchpoints.    (line    6)

  53983. * settings:                              Command Settings.   (line   39)

  53984. * SH:                                    Remote Stub.        (line   62)

  53985. * sh-stub.c:                             Remote Stub.        (line   62)

  53986. * shared libraries:                      Files.              (line  287)

  53987. * shared library events, remote reply:   Stop Reply Packets. (line   65)

  53988. * shell command, exit code:              Convenience Vars.   (line  188)

  53989. * shell command, exit signal:            Convenience Vars.   (line  188)

  53990. * shell escape:                          Shell Commands.     (line   10)

  53991. * show all convenience functions:        Convenience Funs.   (line  228)

  53992. * show all user variables and functions: Convenience Vars.   (line   37)

  53993. * show exec-file-mismatch:               Attach.             (line   44)

  53994. * show inferior's working directory:     Working Directory.  (line   27)

  53995. * show last commands:                    Command History.    (line  110)

  53996. * show tdesc filename:                   Retrieving Descriptions.

  53997.                                                              (line   25)

  53998. * signals:                               Signals.            (line    6)

  53999. * signals the inferior may see, remote request: General Query Packets.

  54000.                                                              (line  469)

  54001. * SIGQUIT signal, dump core of GDB:      Maintenance Commands.

  54002.                                                              (line  169)

  54003. * SingleKey keymap name:                 TUI Single Key Mode.

  54004.                                                              (line   53)

  54005. * size of remote memory accesses:        Packets.            (line  247)

  54006. * size of screen:                        Screen Size.        (line    6)

  54007. * skipping over files via glob-style patterns: Skipping Over Functions and Files.

  54008.                                                              (line   55)

  54009. * skipping over functions and files:     Skipping Over Functions and Files.

  54010.                                                              (line    6)

  54011. * skipping over functions via regular expressions: Skipping Over Functions and Files.

  54012.                                                              (line   68)

  54013. * snapshot of a process:                 Checkpoint/Restart. (line    6)

  54014. * software watchpoints:                  Set Watchpoints.    (line   31)

  54015. * source file and line of a symbol:      Print Settings.     (line   50)

  54016. * source line and its code address:      Machine Code.       (line    6)

  54017. * source location:                       Specify Location.   (line    6)

  54018. * source path:                           Source Path.        (line    6)

  54019. * Sparc:                                 Remote Stub.        (line   65)

  54020. * sparc-stub.c:                          Remote Stub.        (line   65)

  54021. * Sparc64 support:                       Sparc64.            (line    6)

  54022. * sparcl-stub.c:                         Remote Stub.        (line   68)

  54023. * SparcLite:                             Remote Stub.        (line   68)

  54024. * Special Fortran commands:              Special Fortran Commands.

  54025.                                                              (line    6)

  54026. * specifying location:                   Specify Location.   (line    6)

  54027. * SSE registers (x86):                   Registers.          (line   76)

  54028. * stack frame:                           Frames.             (line    6)

  54029. * stack on Alpha:                        MIPS.               (line    6)

  54030. * stack on MIPS:                         MIPS.               (line    6)

  54031. * stack pointer register:                Registers.          (line   31)

  54032. * stacking targets:                      Active Targets.     (line    6)

  54033. * standard registers:                    Registers.          (line   31)

  54034. * start a new independent interpreter:   Interpreters.       (line   52)

  54035. * start a new trace experiment:          Starting and Stopping Trace Experiments.

  54036.                                                              (line    6)

  54037. * starting:                              Starting.           (line    6)

  54038. * startup code, and backtrace:           Backtrace.          (line  155)

  54039. * startup with shell, remote request:    General Query Packets.

  54040.                                                              (line  114)

  54041. * stat, file-i/o system call:            stat/fstat.         (line    6)

  54042. * static members of C++ objects:         Print Settings.     (line  559)

  54043. * static members of Pascal objects:      Print Settings.     (line  570)

  54044. * static probe point, DTrace:            Static Probe Points.

  54045.                                                              (line    6)

  54046. * static probe point, SystemTap:         Static Probe Points.

  54047.                                                              (line    6)

  54048. * static tracepoints:                    Set Tracepoints.    (line   28)

  54049. * static tracepoints, in remote protocol: General Query Packets.

  54050.                                                              (line  961)

  54051. * static tracepoints, setting:           Create and Delete Tracepoints.

  54052.                                                              (line   75)

  54053. * status of trace data collection:       Starting and Stopping Trace Experiments.

  54054.                                                              (line   27)

  54055. * status output in GDB/MI:               GDB/MI Output Syntax.

  54056.                                                              (line   94)

  54057. * stepping:                              Continuing and Stepping.

  54058.                                                              (line    6)

  54059. * stepping and signal handlers:          Signals.            (line  106)

  54060. * stepping into functions with no line info: Continuing and Stepping.

  54061.                                                              (line   92)

  54062. * stop a running trace experiment:       Starting and Stopping Trace Experiments.

  54063.                                                              (line   16)

  54064. * stop on C++ exceptions:                Set Catchpoints.    (line   16)

  54065. * stop reply packets:                    Stop Reply Packets. (line    6)

  54066. * stopped threads:                       Thread Stops.       (line    6)

  54067. * stream records in GDB/MI:              GDB/MI Stream Records.

  54068.                                                              (line    6)

  54069. * string tracing, in remote protocol:    General Query Packets.

  54070.                                                              (line  978)

  54071. * struct gdb_reader_funcs:               Writing JIT Debug Info Readers.

  54072.                                                              (line   22)

  54073. * struct gdb_symbol_callbacks:           Writing JIT Debug Info Readers.

  54074.                                                              (line   43)

  54075. * struct gdb_unwind_callbacks:           Writing JIT Debug Info Readers.

  54076.                                                              (line   43)

  54077. * struct return convention:              i386.               (line    7)

  54078. * struct stat, in file-i/o protocol:     struct stat.        (line    6)

  54079. * struct timeval, in file-i/o protocol:  struct timeval.     (line    6)

  54080. * struct/union returned in registers:    i386.               (line    7)

  54081. * structure field name completion:       Completion.         (line  135)

  54082. * stub example, remote debugging:        Remote Stub.        (line    6)

  54083. * stupid questions:                      Messages/Warnings.  (line   49)

  54084. * styling:                               Output Styling.     (line    6)

  54085. * Super-H:                               Super-H.            (line    6)

  54086. * supported GDB/MI features, list:       GDB/MI Support Commands.

  54087.                                                              (line   57)

  54088. * supported packets, remote query:       General Query Packets.

  54089.                                                              (line  589)

  54090. * switching threads:                     Threads.            (line    6)

  54091. * switching threads automatically:       All-Stop Mode.      (line   28)

  54092. * symbol cache size:                     Symbols.            (line  698)

  54093. * symbol cache, flushing:                Symbols.            (line  714)

  54094. * symbol cache, printing its contents:   Symbols.            (line  706)

  54095. * symbol cache, printing usage statistics: Symbols.          (line  710)

  54096. * symbol decoding style, C++:            Print Settings.     (line  529)

  54097. * symbol dump:                           Symbols.            (line  619)

  54098. * symbol file functions:                 Debugging Output.   (line  205)

  54099. * symbol files, remote debugging:        Connecting.         (line   97)

  54100. * symbol from address:                   Symbols.            (line   95)

  54101. * symbol lookup:                         Debugging Output.   (line  198)

  54102. * symbol lookup, remote request:         General Query Packets.

  54103.                                                              (line 1033)

  54104. * symbol names:                          Symbols.            (line   14)

  54105. * symbol table:                          Files.              (line    6)

  54106. * symbol table creation:                 Debugging Output.   (line  210)

  54107. * symbol tables in guile:                Symbol Tables In Guile.

  54108.                                                              (line    6)

  54109. * symbol tables in python:               Symbol Tables In Python.

  54110.                                                              (line    6)

  54111. * symbol tables, listing GDB's internal: Symbols.            (line  645)

  54112. * symbol, source file and line:          Print Settings.     (line   50)

  54113. * symbols in guile:                      Symbols In Guile.   (line    6)

  54114. * symbols in python:                     Symbols In Python.  (line    6)

  54115. * symbols, never read:                   Files.              (line  101)

  54116. * symbols, reading from relocatable object files: Files.     (line  146)

  54117. * symbols, reading immediately:          Files.              (line   94)

  54118. * Synopsys ARC:                          ARC.                (line    6)

  54119. * syscall DSO:                           Files.              (line  193)

  54120. * system calls and thread breakpoints:   Interrupted System Calls.

  54121.                                                              (line    6)

  54122. * system root, alternate:                Files.              (line  386)

  54123. * system, file-i/o system call:          system.             (line    6)

  54124. * system-wide configuration scripts:     System-wide Configuration Scripts.

  54125.                                                              (line    6)

  54126. * system-wide init file:                 System-wide configuration.

  54127.                                                              (line    6)

  54128. * t packet:                              Packets.            (line  331)

  54129. * T packet:                              Packets.            (line  336)

  54130. * T packet reply:                        Stop Reply Packets. (line   26)

  54131. * tail call frames, debugging:           Tail Call Frames.   (line    6)

  54132. * target architecture:                   Targets.            (line   17)

  54133. * target byte order:                     Byte Order.         (line    6)

  54134. * target character set:                  Character Sets.     (line    6)

  54135. * target debugging info:                 Debugging Output.   (line  217)

  54136. * target descriptions:                   Target Descriptions.

  54137.                                                              (line    6)

  54138. * target descriptions, AArch64 features: AArch64 Features.   (line    6)

  54139. * target descriptions, ARC Features:     ARC Features.       (line    6)

  54140. * target descriptions, ARM features:     ARM Features.       (line    6)

  54141. * target descriptions, enum types:       Enum Target Types.  (line    6)

  54142. * target descriptions, i386 features:    i386 Features.      (line    6)

  54143. * target descriptions, inclusion:        Target Description Format.

  54144.                                                              (line   53)

  54145. * target descriptions, M68K features:    M68K Features.      (line    6)

  54146. * target descriptions, MicroBlaze features: MicroBlaze Features.

  54147.                                                              (line    6)

  54148. * target descriptions, MIPS features:    MIPS Features.      (line    6)

  54149. * target descriptions, NDS32 features:   NDS32 Features.     (line    6)

  54150. * target descriptions, Nios II features: Nios II Features.   (line    6)

  54151. * target descriptions, OpenRISC 1000 features: OpenRISC 1000 Features.

  54152.                                                              (line    6)

  54153. * target descriptions, PowerPC features: PowerPC Features.   (line    6)

  54154. * target descriptions, predefined types: Predefined Target Types.

  54155.                                                              (line    6)

  54156. * target descriptions, RISC-V Features:  RISC-V Features.    (line    6)

  54157. * target descriptions, RX Features:      RX Features.        (line    6)

  54158. * target descriptions, S/390 features:   S/390 and System z Features.

  54159.                                                              (line    6)

  54160. * target descriptions, sparc32 features: Sparc Features.     (line    6)

  54161. * target descriptions, sparc64 features: Sparc Features.     (line    6)

  54162. * target descriptions, standard features: Standard Target Features.

  54163.                                                              (line    6)

  54164. * target descriptions, System z features: S/390 and System z Features.

  54165.                                                              (line    6)

  54166. * target descriptions, TIC6x features:   TIC6x Features.     (line    6)

  54167. * target descriptions, TMS320C6x features: TIC6x Features.   (line    6)

  54168. * target descriptions, XML format:       Target Description Format.

  54169.                                                              (line    6)

  54170. * target memory comparison:              Memory.             (line  142)

  54171. * target output in GDB/MI:               GDB/MI Output Syntax.

  54172.                                                              (line  110)

  54173. * target stack description:              Maintenance Commands.

  54174.                                                              (line  355)

  54175. * target-assisted range stepping:        Continuing and Stepping.

  54176.                                                              (line  217)

  54177. * task attributes (GNU Hurd):            Hurd Native.        (line   48)

  54178. * task breakpoints, in Ada:              Ada Tasks.          (line  135)

  54179. * task exception port, GNU Hurd:         Hurd Native.        (line   67)

  54180. * task suspend count:                    Hurd Native.        (line   59)

  54181. * task switching with program using Ravenscar Profile: Ravenscar Profile.

  54182.                                                              (line   10)

  54183. * TCP port, target remote:               Connecting.         (line  173)

  54184. * temporarily change settings:           Command Settings.   (line   39)

  54185. * terminal:                              Input/Output.       (line    6)

  54186. * Text User Interface:                   TUI.                (line    6)

  54187. * thread attributes info, remote request: General Query Packets.

  54188.                                                              (line 1076)

  54189. * thread breakpoints:                    Thread-Specific Breakpoints.

  54190.                                                              (line   10)

  54191. * thread breakpoints and system calls:   Interrupted System Calls.

  54192.                                                              (line    6)

  54193. * thread create event, remote reply:     Stop Reply Packets. (line  152)

  54194. * thread create/exit events, remote request: General Query Packets.

  54195.                                                              (line  509)

  54196. * thread default settings, GNU Hurd:     Hurd Native.        (line  130)

  54197. * thread exit event, remote reply:       Stop Reply Packets. (line  181)

  54198. * thread ID lists:                       Threads.            (line   65)

  54199. * thread identifier (GDB):               Threads.            (line   47)

  54200. * thread identifier (system):            Threads.            (line   35)

  54201. * thread info (Solaris):                 Threads.            (line  167)

  54202. * thread information, remote request:    General Query Packets.

  54203.                                                              (line  369)

  54204. * thread list format:                    Thread List Format. (line    6)

  54205. * thread number, per inferior:           Threads.            (line   47)

  54206. * thread properties, GNU Hurd:           Hurd Native.        (line   90)

  54207. * thread suspend count, GNU Hurd:        Hurd Native.        (line  109)

  54208. * THREAD-ID, in remote protocol:         Packets.            (line   20)

  54209. * threads and watchpoints:               Set Watchpoints.    (line  179)

  54210. * threads in python:                     Threads In Python.  (line    6)

  54211. * threads of execution:                  Threads.            (line    6)

  54212. * threads, automatic switching:          All-Stop Mode.      (line   28)

  54213. * threads, continuing:                   Thread Stops.       (line    6)

  54214. * threads, stopped:                      Thread Stops.       (line    6)

  54215. * time of command execution:             Maintenance Commands.

  54216.                                                              (line  573)

  54217. * timeout for commands:                  Maintenance Commands.

  54218.                                                              (line  624)

  54219. * timeout for serial communications:     Remote Configuration.

  54220.                                                              (line   72)

  54221. * timeout, for remote target connection: Remote Configuration.

  54222.                                                              (line  147)

  54223. * timestamping debugging info:           Debugging Output.   (line  224)

  54224. * trace experiment, status of:           Starting and Stopping Trace Experiments.

  54225.                                                              (line   27)

  54226. * trace file format:                     Trace File Format.  (line    6)

  54227. * trace files:                           Trace Files.        (line    6)

  54228. * trace state variable value, remote request: Tracepoint Packets.

  54229.                                                              (line  318)

  54230. * trace state variables:                 Trace State Variables.

  54231.                                                              (line    6)

  54232. * traceback:                             Backtrace.          (line    6)

  54233. * traceframe info format:                Traceframe Info Format.

  54234.                                                              (line    6)

  54235. * tracepoint actions:                    Tracepoint Actions. (line    6)

  54236. * tracepoint conditions:                 Tracepoint Conditions.

  54237.                                                              (line    6)

  54238. * tracepoint data, display:              tdump.              (line    6)

  54239. * tracepoint deletion:                   Create and Delete Tracepoints.

  54240.                                                              (line  125)

  54241. * tracepoint number:                     Create and Delete Tracepoints.

  54242.                                                              (line  122)

  54243. * tracepoint packets:                    Tracepoint Packets. (line    6)

  54244. * tracepoint pass count:                 Tracepoint Passcounts.

  54245.                                                              (line    6)

  54246. * tracepoint restrictions:               Tracepoint Restrictions.

  54247.                                                              (line    6)

  54248. * tracepoint status, remote request:     Tracepoint Packets. (line  307)

  54249. * tracepoint variables:                  Tracepoint Variables.

  54250.                                                              (line    6)

  54251. * tracepoints:                           Tracepoints.        (line    6)

  54252. * tracepoints support in gdbserver:      Server.             (line  272)

  54253. * trailing underscore, in Fortran symbols: Fortran.          (line    9)

  54254. * translating between character sets:    Character Sets.     (line    6)

  54255. * TUI:                                   TUI.                (line    6)

  54256. * TUI commands:                          TUI Commands.       (line    6)

  54257. * TUI configuration variables:           TUI Configuration.  (line    6)

  54258. * TUI key bindings:                      TUI Keys.           (line    6)

  54259. * TUI single key mode:                   TUI Single Key Mode.

  54260.                                                              (line    6)

  54261. * type casting memory:                   Expressions.        (line   41)

  54262. * type chain of a data type:             Maintenance Commands.

  54263.                                                              (line  367)

  54264. * type checking:                         Checks.             (line   24)

  54265. * type conversions in C++:               C Plus Plus Expressions.

  54266.                                                              (line   26)

  54267. * type printer:                          Type Printing API.  (line    9)

  54268. * type printing API for Python:          Type Printing API.  (line    6)

  54269. * types in guile:                        Types In Guile.     (line    6)

  54270. * types in Python:                       Types In Python.    (line    6)

  54271. * UDP port, target remote:               Connecting.         (line  222)

  54272. * union field name completion:           Completion.         (line  135)

  54273. * unions in structures, printing:        Print Settings.     (line  469)

  54274. * Unix domain socket:                    Connecting.         (line  147)

  54275. * unknown address, locating:             Output Formats.     (line   35)

  54276. * unknown type:                          Symbols.            (line  363)

  54277. * unlink, file-i/o system call:          unlink.             (line    6)

  54278. * unlinked object files:                 Files.              (line   26)

  54279. * unload symbols from shared libraries:  Files.              (line  348)

  54280. * unmap an overlay:                      Overlay Commands.   (line   39)

  54281. * unmapped overlays:                     How Overlays Work.  (line    6)

  54282. * unset environment variable, remote request: General Query Packets.

  54283.                                                              (line  173)

  54284. * unset tdesc filename:                  Retrieving Descriptions.

  54285.                                                              (line   21)

  54286. * unsupported languages:                 Unsupported Languages.

  54287.                                                              (line    6)

  54288. * unwind stack in called functions:      Calling.            (line   36)

  54289. * unwind stack in called functions with unhandled exceptions: Calling.

  54290.                                                              (line   47)

  54291. * unwinding frames in Python:            Unwinding Frames in Python.

  54292.                                                              (line    6)

  54293. * use only software watchpoints:         Set Watchpoints.    (line  108)

  54294. * user registers:                        Maintenance Commands.

  54295.                                                              (line  326)

  54296. * user-defined command:                  Define.             (line    6)

  54297. * user-defined macros:                   Macros.             (line   59)

  54298. * user-defined variables:                Convenience Vars.   (line    6)

  54299. * value history:                         Value History.      (line    6)

  54300. * values from inferior, in guile:        Values From Inferior In Guile.

  54301.                                                              (line    6)

  54302. * values from inferior, with Python:     Values From Inferior.

  54303.                                                              (line    6)

  54304. * variable name conflict:                Variables.          (line   36)

  54305. * variable object debugging info:        Debugging Output.   (line  231)

  54306. * variable objects in GDB/MI:            GDB/MI Variable Objects.

  54307.                                                              (line    9)

  54308. * variable values, wrong:                Variables.          (line  106)

  54309. * variables, readline:                   Readline Init File Syntax.

  54310.                                                              (line   34)

  54311. * variables, setting:                    Assignment.         (line   16)

  54312. * vAttach packet:                        Packets.            (line  350)

  54313. * vCont packet:                          Packets.            (line  368)

  54314. * vCont? packet:                         Packets.            (line  435)

  54315. * vCtrlC packet:                         Packets.            (line  445)

  54316. * vector unit:                           Vector Unit.        (line    6)

  54317. * vector, auxiliary:                     OS Information.     (line    9)

  54318. * verbose operation:                     Messages/Warnings.  (line    6)

  54319. * verify remote memory image:            Memory.             (line  142)

  54320. * verify target memory image:            Memory.             (line  142)

  54321. * vFile packet:                          Packets.            (line  459)

  54322. * vFlashDone packet:                     Packets.            (line  498)

  54323. * vFlashErase packet:                    Packets.            (line  463)

  54324. * vFlashWrite packet:                    Packets.            (line  478)

  54325. * vfork events, remote reply:            Stop Reply Packets. (line  116)

  54326. * vforkdone events, remote reply:        Stop Reply Packets. (line  128)

  54327. * virtual functions (C++) display:       Print Settings.     (line  581)

  54328. * vKill packet:                          Packets.            (line  505)

  54329. * vMustReplyEmpty packet:                Packets.            (line  517)

  54330. * volatile registers:                    Registers.          (line  106)

  54331. * vRun packet:                           Packets.            (line  529)

  54332. * vStopped packet:                       Packets.            (line  544)

  54333. * VTBL display:                          Print Settings.     (line  581)

  54334. * watchdog timer:                        Maintenance Commands.

  54335.                                                              (line  624)

  54336. * watchpoints:                           Breakpoints.        (line   17)

  54337. * watchpoints and threads:               Set Watchpoints.    (line  179)

  54338. * where to look for shared libraries:    Files.              (line  381)

  54339. * wild pointer, interpreting:            Print Settings.     (line   80)

  54340. * Wind River Linux system-wide configuration script: System-wide Configuration Scripts.

  54341.                                                              (line   22)

  54342. * word completion:                       Completion.         (line    6)

  54343. * working directory:                     Source Path.        (line   40)

  54344. * working directory (of your program):   Working Directory.  (line    6)

  54345. * working language:                      Languages.          (line   13)

  54346. * write data into object, remote request: General Query Packets.

  54347.                                                              (line 1338)

  54348. * write, file-i/o system call:           write.              (line    6)

  54349. * writing a frame filter:                Writing a Frame Filter.

  54350.                                                              (line    6)

  54351. * writing a Guile pretty-printer:        Writing a Guile Pretty-Printer.

  54352.                                                              (line    6)

  54353. * writing a pretty-printer:              Writing a Pretty-Printer.

  54354.                                                              (line    6)

  54355. * writing convenience functions:         Functions In Python.

  54356.                                                              (line    6)

  54357. * writing into corefiles:                Patching.           (line    6)

  54358. * writing into executables:              Patching.           (line    6)

  54359. * writing into executables <1>:          Compiling and Injecting Code.

  54360.                                                              (line    6)

  54361. * writing JIT debug info readers:        Writing JIT Debug Info Readers.

  54362.                                                              (line    6)

  54363. * writing xmethods in Python:            Writing an Xmethod. (line    6)

  54364. * wrong values:                          Variables.          (line  106)

  54365. * x command, default address:            Machine Code.       (line   34)

  54366. * X packet:                              Packets.            (line  547)

  54367. * Xilinx MicroBlaze:                     MicroBlaze.         (line    6)

  54368. * XInclude:                              Target Description Format.

  54369.                                                              (line   53)

  54370. * XMD, Xilinx Microprocessor Debugger:   MicroBlaze.         (line    6)

  54371. * xmethod API:                           Xmethod API.        (line    6)

  54372. * xmethods in Python:                    Xmethods In Python. (line    6)

  54373. * XML parser debugging:                  Debugging Output.   (line  237)

  54374. * yanking text:                          Readline Killing Commands.

  54375.                                                              (line    6)

  54376. * z packet:                              Packets.            (line  560)

  54377. * Z packets:                             Packets.            (line  560)

  54378. * z0 packet:                             Packets.            (line  575)

  54379. * Z0 packet:                             Packets.            (line  575)

  54380. * z1 packet:                             Packets.            (line  630)

  54381. * Z1 packet:                             Packets.            (line  630)

  54382. * z2 packet:                             Packets.            (line  651)

  54383. * Z2 packet:                             Packets.            (line  651)

  54384. * z3 packet:                             Packets.            (line  664)

  54385. * Z3 packet:                             Packets.            (line  664)

  54386. * z4 packet:                             Packets.            (line  677)

  54387. * Z4 packet:                             Packets.            (line  677)

  54388. 

  54389. 

  54390. File: gdb.info,  Node: Command and Variable Index,  Prev: Concept Index,  Up: Top

  54391. 

  54392. Command, Variable, and Function Index

  54393. *************************************

  54394. 

  54395. �[index�]

  54396. * Menu:

  54397. 

  54398. * !:                                     Shell Commands.      (line  10)

  54399. * # (a comment):                         Command Syntax.      (line  37)

  54400. * $bpnum, convenience variable:          Set Breaks.          (line   6)

  54401. * $cdir, convenience variable:           Source Path.         (line  40)

  54402. * $cwd, convenience variable:            Source Path.         (line  40)

  54403. * $tpnum:                                Create and Delete Tracepoints.

  54404.                                                               (line 122)

  54405. * $tracepoint:                           Tracepoint Variables.

  54406.                                                               (line  10)

  54407. * $trace_file:                           Tracepoint Variables.

  54408.                                                               (line  16)

  54409. * $trace_frame:                          Tracepoint Variables.

  54410.                                                               (line   6)

  54411. * $trace_func:                           Tracepoint Variables.

  54412.                                                               (line  19)

  54413. * $trace_line:                           Tracepoint Variables.

  54414.                                                               (line  13)

  54415. * $_, convenience variable:              Convenience Vars.    (line  65)

  54416. * $_ada_exception, convenience variable: Set Catchpoints.     (line  82)

  54417. * $_any_caller_is, convenience function: Convenience Funs.    (line 182)

  54418. * $_any_caller_matches, convenience function: Convenience Funs.

  54419.                                                               (line 194)

  54420. * $_as_string, convenience function:     Convenience Funs.    (line 206)

  54421. * $_caller_is, convenience function:     Convenience Funs.    (line 152)

  54422. * $_caller_matches, convenience function: Convenience Funs.   (line 175)

  54423. * $_cimag, convenience function:         Convenience Funs.    (line 217)

  54424. * $_creal, convenience function:         Convenience Funs.    (line 217)

  54425. * $_exception, convenience variable:     Set Catchpoints.     (line  21)

  54426. * $_exitcode, convenience variable:      Convenience Vars.    (line  80)

  54427. * $_exitsignal, convenience variable:    Convenience Vars.    (line  85)

  54428. * $_gdb_maint_setting, convenience function: Convenience Funs.

  54429.                                                               (line 129)

  54430. * $_gdb_maint_setting_str, convenience function: Convenience Funs.

  54431.                                                               (line 125)

  54432. * $_gdb_major, convenience variable:     Convenience Vars.    (line 179)

  54433. * $_gdb_minor, convenience variable:     Convenience Vars.    (line 179)

  54434. * $_gdb_setting, convenience function:   Convenience Funs.    (line  76)

  54435. * $_gdb_setting_str, convenience function: Convenience Funs.  (line  63)

  54436. * $_gthread, convenience variable:       Threads.             (line  98)

  54437. * $_inferior, convenience variable:      Inferiors Connections and Programs.

  54438.                                                               (line  90)

  54439. * $_isvoid, convenience function:        Convenience Funs.    (line  15)

  54440. * $_memeq, convenience function:         Convenience Funs.    (line 136)

  54441. * $_probe_arg, convenience variable:     Static Probe Points. (line  77)

  54442. * $_regex, convenience function:         Convenience Funs.    (line 140)

  54443. * $_sdata, collect:                      Tracepoint Actions.  (line  86)

  54444. * $_sdata, inspect, convenience variable: Convenience Vars.   (line 147)

  54445. * $_shell_exitcode, convenience variable: Convenience Vars.   (line 188)

  54446. * $_shell_exitsignal, convenience variable: Convenience Vars. (line 188)

  54447. * $_siginfo, convenience variable:       Convenience Vars.    (line 153)

  54448. * $_streq, convenience function:         Convenience Funs.    (line 145)

  54449. * $_strlen, convenience function:        Convenience Funs.    (line 149)

  54450. * $_thread, convenience variable:        Threads.             (line  98)

  54451. * $_tlb, convenience variable:           Convenience Vars.    (line 159)

  54452. * $__, convenience variable:             Convenience Vars.    (line  74)

  54453. * (make-command:                         Commands In Guile.   (line  15)

  54454. * (make-parameter:                       Parameters In Guile. (line  22)

  54455. * -ada-task-info:                        GDB/MI Ada Tasking Commands.

  54456.                                                               (line   9)

  54457. * -add-inferior:                         GDB/MI Miscellaneous Commands.

  54458.                                                               (line 295)

  54459. * -break-after:                          GDB/MI Breakpoint Commands.

  54460.                                                               (line  11)

  54461. * -break-commands:                       GDB/MI Breakpoint Commands.

  54462.                                                               (line  56)

  54463. * -break-condition:                      GDB/MI Breakpoint Commands.

  54464.                                                               (line  90)

  54465. * -break-delete:                         GDB/MI Breakpoint Commands.

  54466.                                                               (line 127)

  54467. * -break-disable:                        GDB/MI Breakpoint Commands.

  54468.                                                               (line 161)

  54469. * -break-enable:                         GDB/MI Breakpoint Commands.

  54470.                                                               (line 197)

  54471. * -break-info:                           GDB/MI Breakpoint Commands.

  54472.                                                               (line 232)

  54473. * -break-insert:                         GDB/MI Breakpoint Commands.

  54474.                                                               (line 256)

  54475. * -break-list:                           GDB/MI Breakpoint Commands.

  54476.                                                               (line 427)

  54477. * -break-passcount:                      GDB/MI Breakpoint Commands.

  54478.                                                               (line 499)

  54479. * -break-watch:                          GDB/MI Breakpoint Commands.

  54480.                                                               (line 511)

  54481. * -catch-assert:                         Ada Exception GDB/MI Catchpoint Commands.

  54482.                                                               (line  12)

  54483. * -catch-catch:                          C++ Exception GDB/MI Catchpoint Commands.

  54484.                                                               (line  98)

  54485. * -catch-exception:                      Ada Exception GDB/MI Catchpoint Commands.

  54486.                                                               (line  46)

  54487. * -catch-handlers:                       Ada Exception GDB/MI Catchpoint Commands.

  54488.                                                               (line  91)

  54489. * -catch-load:                           Shared Library GDB/MI Catchpoint Commands.

  54490.                                                               (line   9)

  54491. * -catch-rethrow:                        C++ Exception GDB/MI Catchpoint Commands.

  54492.                                                               (line  56)

  54493. * -catch-throw:                          C++ Exception GDB/MI Catchpoint Commands.

  54494.                                                               (line  13)

  54495. * -catch-unload:                         Shared Library GDB/MI Catchpoint Commands.

  54496.                                                               (line  36)

  54497. * -complete:                             GDB/MI Miscellaneous Commands.

  54498.                                                               (line 436)

  54499. * -data-disassemble:                     GDB/MI Data Manipulation.

  54500.                                                               (line  15)

  54501. * -data-evaluate-expression:             GDB/MI Data Manipulation.

  54502.                                                               (line 192)

  54503. * -data-list-changed-registers:          GDB/MI Data Manipulation.

  54504.                                                               (line 230)

  54505. * -data-list-register-names:             GDB/MI Data Manipulation.

  54506.                                                               (line 266)

  54507. * -data-list-register-values:            GDB/MI Data Manipulation.

  54508.                                                               (line 306)

  54509. * -data-read-memory:                     GDB/MI Data Manipulation.

  54510.                                                               (line 393)

  54511. * -data-read-memory-bytes:               GDB/MI Data Manipulation.

  54512.                                                               (line 500)

  54513. * -data-write-memory-bytes:              GDB/MI Data Manipulation.

  54514.                                                               (line 575)

  54515. * -dprintf-insert:                       GDB/MI Breakpoint Commands.

  54516.                                                               (line 363)

  54517. * -enable-frame-filters:                 GDB/MI Stack Manipulation.

  54518.                                                               (line   9)

  54519. * -enable-pretty-printing:               GDB/MI Variable Objects.

  54520.                                                               (line 118)

  54521. * -enable-timings:                       GDB/MI Miscellaneous Commands.

  54522.                                                               (line 392)

  54523. * -environment-cd:                       GDB/MI Program Context.

  54524.                                                               (line  33)

  54525. * -environment-directory:                GDB/MI Program Context.

  54526.                                                               (line  56)

  54527. * -environment-path:                     GDB/MI Program Context.

  54528.                                                               (line 100)

  54529. * -environment-pwd:                      GDB/MI Program Context.

  54530.                                                               (line 141)

  54531. * -exec-arguments:                       GDB/MI Program Context.

  54532.                                                               (line   9)

  54533. * -exec-continue:                        GDB/MI Program Execution.

  54534.                                                               (line  13)

  54535. * -exec-finish:                          GDB/MI Program Execution.

  54536.                                                               (line  53)

  54537. * -exec-interrupt:                       GDB/MI Program Execution.

  54538.                                                               (line  97)

  54539. * -exec-jump:                            GDB/MI Program Execution.

  54540.                                                               (line 147)

  54541. * -exec-next:                            GDB/MI Program Execution.

  54542.                                                               (line 171)

  54543. * -exec-next-instruction:                GDB/MI Program Execution.

  54544.                                                               (line 202)

  54545. * -exec-return:                          GDB/MI Program Execution.

  54546.                                                               (line 238)

  54547. * -exec-run:                             GDB/MI Program Execution.

  54548.                                                               (line 283)

  54549. * -exec-step:                            GDB/MI Program Execution.

  54550.                                                               (line 353)

  54551. * -exec-step-instruction:                GDB/MI Program Execution.

  54552.                                                               (line 395)

  54553. * -exec-until:                           GDB/MI Program Execution.

  54554.                                                               (line 436)

  54555. * -file-exec-and-symbols:                GDB/MI File Commands.

  54556.                                                               (line  12)

  54557. * -file-exec-file:                       GDB/MI File Commands.

  54558.                                                               (line  40)

  54559. * -file-list-exec-source-file:           GDB/MI File Commands.

  54560.                                                               (line  67)

  54561. * -file-list-exec-source-files:          GDB/MI File Commands.

  54562.                                                               (line  93)

  54563. * -file-list-shared-libraries:           GDB/MI File Commands.

  54564.                                                               (line 123)

  54565. * -file-symbol-file:                     GDB/MI File Commands.

  54566.                                                               (line 157)

  54567. * -gdb-exit:                             GDB/MI Miscellaneous Commands.

  54568.                                                               (line   9)

  54569. * -gdb-set:                              GDB/MI Miscellaneous Commands.

  54570.                                                               (line  31)

  54571. * -gdb-show:                             GDB/MI Miscellaneous Commands.

  54572.                                                               (line  54)

  54573. * -gdb-version:                          GDB/MI Miscellaneous Commands.

  54574.                                                               (line  77)

  54575. * -inferior-tty-set:                     GDB/MI Miscellaneous Commands.

  54576.                                                               (line 343)

  54577. * -inferior-tty-show:                    GDB/MI Miscellaneous Commands.

  54578.                                                               (line 366)

  54579. * -info-ada-exceptions:                  GDB/MI Ada Exceptions Commands.

  54580.                                                               (line   9)

  54581. * -info-gdb-mi-command:                  GDB/MI Support Commands.

  54582.                                                               (line  14)

  54583. * -info-os:                              GDB/MI Miscellaneous Commands.

  54584.                                                               (line 221)

  54585. * -interpreter-exec:                     GDB/MI Miscellaneous Commands.

  54586.                                                               (line 317)

  54587. * -list-features:                        GDB/MI Support Commands.

  54588.                                                               (line  57)

  54589. * -list-target-features:                 GDB/MI Support Commands.

  54590.                                                               (line 115)

  54591. * -list-thread-groups:                   GDB/MI Miscellaneous Commands.

  54592.                                                               (line 111)

  54593. * -stack-info-depth:                     GDB/MI Stack Manipulation.

  54594.                                                               (line  51)

  54595. * -stack-info-frame:                     GDB/MI Stack Manipulation.

  54596.                                                               (line  24)

  54597. * -stack-list-arguments:                 GDB/MI Stack Manipulation.

  54598.                                                               (line  89)

  54599. * -stack-list-frames:                    GDB/MI Stack Manipulation.

  54600.                                                               (line 188)

  54601. * -stack-list-locals:                    GDB/MI Stack Manipulation.

  54602.                                                               (line 305)

  54603. * -stack-list-variables:                 GDB/MI Stack Manipulation.

  54604.                                                               (line 351)

  54605. * -stack-select-frame:                   GDB/MI Stack Manipulation.

  54606.                                                               (line 379)

  54607. * -symbol-info-functions:                GDB/MI Symbol Query. (line   9)

  54608. * -symbol-info-module-functions:         GDB/MI Symbol Query. (line 109)

  54609. * -symbol-info-module-variables:         GDB/MI Symbol Query. (line 170)

  54610. * -symbol-info-modules:                  GDB/MI Symbol Query. (line 241)

  54611. * -symbol-info-types:                    GDB/MI Symbol Query. (line 295)

  54612. * -symbol-info-variables:                GDB/MI Symbol Query. (line 352)

  54613. * -symbol-list-lines:                    GDB/MI Symbol Query. (line 457)

  54614. * -target-attach:                        GDB/MI Target Manipulation.

  54615.                                                               (line   9)

  54616. * -target-detach:                        GDB/MI Target Manipulation.

  54617.                                                               (line  36)

  54618. * -target-disconnect:                    GDB/MI Target Manipulation.

  54619.                                                               (line  61)

  54620. * -target-download:                      GDB/MI Target Manipulation.

  54621.                                                               (line  85)

  54622. * -target-file-delete:                   GDB/MI File Transfer Commands.

  54623.                                                               (line  57)

  54624. * -target-file-get:                      GDB/MI File Transfer Commands.

  54625.                                                               (line  33)

  54626. * -target-file-put:                      GDB/MI File Transfer Commands.

  54627.                                                               (line   9)

  54628. * -target-flash-erase:                   GDB/MI Target Manipulation.

  54629.                                                               (line 192)

  54630. * -target-select:                        GDB/MI Target Manipulation.

  54631.                                                               (line 212)

  54632. * -thread-info:                          GDB/MI Thread Commands.

  54633.                                                               (line   9)

  54634. * -thread-list-ids:                      GDB/MI Thread Commands.

  54635.                                                               (line  58)

  54636. * -thread-select:                        GDB/MI Thread Commands.

  54637.                                                               (line  86)

  54638. * -trace-define-variable:                GDB/MI Tracepoint Commands.

  54639.                                                               (line  80)

  54640. * -trace-find:                           GDB/MI Tracepoint Commands.

  54641.                                                               (line  12)

  54642. * -trace-frame-collected:                GDB/MI Tracepoint Commands.

  54643.                                                               (line  97)

  54644. * -trace-list-variables:                 GDB/MI Tracepoint Commands.

  54645.                                                               (line 204)

  54646. * -trace-save:                           GDB/MI Tracepoint Commands.

  54647.                                                               (line 246)

  54648. * -trace-start:                          GDB/MI Tracepoint Commands.

  54649.                                                               (line 267)

  54650. * -trace-status:                         GDB/MI Tracepoint Commands.

  54651.                                                               (line 283)

  54652. * -trace-stop:                           GDB/MI Tracepoint Commands.

  54653.                                                               (line 354)

  54654. * -var-assign:                           GDB/MI Variable Objects.

  54655.                                                               (line 497)

  54656. * -var-create:                           GDB/MI Variable Objects.

  54657.                                                               (line 136)

  54658. * -var-delete:                           GDB/MI Variable Objects.

  54659.                                                               (line 224)

  54660. * -var-evaluate-expression:              GDB/MI Variable Objects.

  54661.                                                               (line 476)

  54662. * -var-info-expression:                  GDB/MI Variable Objects.

  54663.                                                               (line 413)

  54664. * -var-info-num-children:                GDB/MI Variable Objects.

  54665.                                                               (line 278)

  54666. * -var-info-path-expression:             GDB/MI Variable Objects.

  54667.                                                               (line 438)

  54668. * -var-info-type:                        GDB/MI Variable Objects.

  54669.                                                               (line 400)

  54670. * -var-list-children:                    GDB/MI Variable Objects.

  54671.                                                               (line 294)

  54672. * -var-set-format:                       GDB/MI Variable Objects.

  54673.                                                               (line 237)

  54674. * -var-set-frozen:                       GDB/MI Variable Objects.

  54675.                                                               (line 641)

  54676. * -var-set-update-range:                 GDB/MI Variable Objects.

  54677.                                                               (line 667)

  54678. * -var-set-visualizer:                   GDB/MI Variable Objects.

  54679.                                                               (line 690)

  54680. * -var-show-attributes:                  GDB/MI Variable Objects.

  54681.                                                               (line 462)

  54682. * -var-show-format:                      GDB/MI Variable Objects.

  54683.                                                               (line 265)

  54684. * -var-update:                           GDB/MI Variable Objects.

  54685.                                                               (line 521)

  54686. * <gdb:arch>:                            Architectures In Guile.

  54687.                                                               (line   6)

  54688. * <gdb:block>:                           Blocks In Guile.     (line   6)

  54689. * <gdb:breakpoint>:                      Breakpoints In Guile.

  54690.                                                               (line   6)

  54691. * <gdb:iterator>:                        Iterators In Guile.  (line   6)

  54692. * <gdb:lazy-string>:                     Lazy Strings In Guile.

  54693.                                                               (line   6)

  54694. * <gdb:objfile>:                         Objfiles In Guile.   (line   6)

  54695. * <gdb:progspace>:                       Progspaces In Guile. (line   6)

  54696. * <gdb:sal>:                             Symbol Tables In Guile.

  54697.                                                               (line   6)

  54698. * <gdb:symbol>:                          Symbols In Guile.    (line   6)

  54699. * <gdb:symtab>:                          Symbol Tables In Guile.

  54700.                                                               (line   6)

  54701. * <gdb:type>:                            Types In Guile.      (line   6)

  54702. * <gdb:value>:                           Values From Inferior In Guile.

  54703.                                                               (line   6)

  54704. * @, referencing memory as an array:     Arrays.              (line   6)

  54705. * ^connected:                            GDB/MI Result Records.

  54706.                                                               (line  22)

  54707. * ^done:                                 GDB/MI Result Records.

  54708.                                                               (line   9)

  54709. * ^error:                                GDB/MI Result Records.

  54710.                                                               (line  25)

  54711. * ^exit:                                 GDB/MI Result Records.

  54712.                                                               (line  36)

  54713. * ^running:                              GDB/MI Result Records.

  54714.                                                               (line  14)

  54715. * __init__ on TypePrinter:               gdb.types.           (line  82)

  54716. * |:                                     Shell Commands.      (line  26)

  54717. * abort (C-g):                           Miscellaneous Commands.

  54718.                                                               (line  10)

  54719. * accept-line (Newline or Return):       Commands For History.

  54720.                                                               (line   6)

  54721. * actions:                               Tracepoint Actions.  (line   6)

  54722. * ada-task-info:                         GDB/MI Support Commands.

  54723.                                                               (line  94)

  54724. * add-auto-load-safe-path:               Auto-loading safe path.

  54725.                                                               (line  50)

  54726. * add-auto-load-scripts-directory:       objfile-gdbdotext file.

  54727.                                                               (line  68)

  54728. * add-inferior:                          Inferiors Connections and Programs.

  54729.                                                               (line 103)

  54730. * add-symbol-file:                       Files.               (line 123)

  54731. * add-symbol-file-from-memory:           Files.               (line 193)

  54732. * adi assign:                            Sparc64.             (line  45)

  54733. * adi examine:                           Sparc64.             (line  27)

  54734. * advance LOCATION:                      Continuing and Stepping.

  54735.                                                               (line 187)

  54736. * alias:                                 Aliases.             (line  21)

  54737. * append:                                Dump/Restore Files.  (line  34)

  54738. * append-pretty-printer!:                Guile Printing Module.

  54739.                                                               (line  18)

  54740. * apropos:                               Help.                (line  74)

  54741. * arch-bool-type:                        Architectures In Guile.

  54742.                                                               (line  84)

  54743. * arch-char-type:                        Architectures In Guile.

  54744.                                                               (line  36)

  54745. * arch-charset:                          Architectures In Guile.

  54746.                                                               (line  23)

  54747. * arch-disassemble:                      Disassembly In Guile.

  54748.                                                               (line  10)

  54749. * arch-double-type:                      Architectures In Guile.

  54750.                                                               (line  76)

  54751. * arch-float-type:                       Architectures In Guile.

  54752.                                                               (line  72)

  54753. * arch-int-type:                         Architectures In Guile.

  54754.                                                               (line  44)

  54755. * arch-int16-type:                       Architectures In Guile.

  54756.                                                               (line 104)

  54757. * arch-int32-type:                       Architectures In Guile.

  54758.                                                               (line 112)

  54759. * arch-int64-type:                       Architectures In Guile.

  54760.                                                               (line 120)

  54761. * arch-int8-type:                        Architectures In Guile.

  54762.                                                               (line  96)

  54763. * arch-long-type:                        Architectures In Guile.

  54764.                                                               (line  48)

  54765. * arch-longdouble-type:                  Architectures In Guile.

  54766.                                                               (line  80)

  54767. * arch-longlong-type:                    Architectures In Guile.

  54768.                                                               (line  88)

  54769. * arch-name:                             Architectures In Guile.

  54770.                                                               (line  20)

  54771. * arch-schar-type:                       Architectures In Guile.

  54772.                                                               (line  52)

  54773. * arch-short-type:                       Architectures In Guile.

  54774.                                                               (line  40)

  54775. * arch-uchar-type:                       Architectures In Guile.

  54776.                                                               (line  56)

  54777. * arch-uint-type:                        Architectures In Guile.

  54778.                                                               (line  64)

  54779. * arch-uint16-type:                      Architectures In Guile.

  54780.                                                               (line 108)

  54781. * arch-uint32-type:                      Architectures In Guile.

  54782.                                                               (line 116)

  54783. * arch-uint64-type:                      Architectures In Guile.

  54784.                                                               (line 124)

  54785. * arch-uint8-type:                       Architectures In Guile.

  54786.                                                               (line 100)

  54787. * arch-ulong-type:                       Architectures In Guile.

  54788.                                                               (line  68)

  54789. * arch-ulonglong-type:                   Architectures In Guile.

  54790.                                                               (line  92)

  54791. * arch-ushort-type:                      Architectures In Guile.

  54792.                                                               (line  60)

  54793. * arch-void-type:                        Architectures In Guile.

  54794.                                                               (line  32)

  54795. * arch-wide-charset:                     Architectures In Guile.

  54796.                                                               (line  26)

  54797. * arch?:                                 Architectures In Guile.

  54798.                                                               (line  13)

  54799. * Architecture.disassemble:              Architectures In Python.

  54800.                                                               (line  15)

  54801. * Architecture.name:                     Architectures In Python.

  54802.                                                               (line  12)

  54803. * Architecture.registers:                Architectures In Python.

  54804.                                                               (line  47)

  54805. * Architecture.register_groups:          Architectures In Python.

  54806.                                                               (line  53)

  54807. * attach:                                Attach.              (line   6)

  54808. * attach&:                               Background Execution.

  54809.                                                               (line  25)

  54810. * awatch:                                Set Watchpoints.     (line  83)

  54811. * b (break):                             Set Breaks.          (line   6)

  54812. * backtrace:                             Backtrace.           (line  11)

  54813. * backward-char (C-b):                   Commands For Moving. (line  15)

  54814. * backward-delete-char (Rubout):         Commands For Text.   (line  17)

  54815. * backward-kill-line (C-x Rubout):       Commands For Killing.

  54816.                                                               (line   9)

  54817. * backward-kill-word (M-<DEL>):          Commands For Killing.

  54818.                                                               (line  24)

  54819. * backward-word (M-b):                   Commands For Moving. (line  22)

  54820. * beginning-of-history (M-<):            Commands For History.

  54821.                                                               (line  19)

  54822. * beginning-of-line (C-a):               Commands For Moving. (line   6)

  54823. * bell-style:                            Readline Init File Syntax.

  54824.                                                               (line  35)

  54825. * bfd caching:                           File Caching.        (line  14)

  54826. * bfd caching <1>:                       File Caching.        (line  24)

  54827. * bfd caching <2>:                       File Caching.        (line  27)

  54828. * bind-tty-special-chars:                Readline Init File Syntax.

  54829.                                                               (line  42)

  54830. * blink-matching-paren:                  Readline Init File Syntax.

  54831.                                                               (line  47)

  54832. * block-end:                             Blocks In Guile.     (line  70)

  54833. * block-function:                        Blocks In Guile.     (line  73)

  54834. * block-global-block:                    Blocks In Guile.     (line  87)

  54835. * block-global?:                         Blocks In Guile.     (line  93)

  54836. * block-start:                           Blocks In Guile.     (line  67)

  54837. * block-static-block:                    Blocks In Guile.     (line  90)

  54838. * block-static?:                         Blocks In Guile.     (line  97)

  54839. * block-superblock:                      Blocks In Guile.     (line  83)

  54840. * block-symbols:                         Blocks In Guile.     (line 101)

  54841. * block-symbols-progress?:               Blocks In Guile.     (line 112)

  54842. * block-valid?:                          Blocks In Guile.     (line  59)

  54843. * Block.end:                             Blocks In Python.    (line  86)

  54844. * Block.function:                        Blocks In Python.    (line  90)

  54845. * Block.global_block:                    Blocks In Python.    (line 105)

  54846. * Block.is_global:                       Blocks In Python.    (line 113)

  54847. * Block.is_static:                       Blocks In Python.    (line 117)

  54848. * Block.is_valid:                        Blocks In Python.    (line  73)

  54849. * Block.start:                           Blocks In Python.    (line  83)

  54850. * Block.static_block:                    Blocks In Python.    (line 109)

  54851. * Block.superblock:                      Blocks In Python.    (line 100)

  54852. * block?:                                Blocks In Guile.     (line  55)

  54853. * BP_ACCESS_WATCHPOINT:                  Breakpoints In Python.

  54854.                                                               (line  74)

  54855. * BP_ACCESS_WATCHPOINT <1>:              Breakpoints In Guile.

  54856.                                                               (line  71)

  54857. * BP_BREAKPOINT:                         Breakpoints In Python.

  54858.                                                               (line  62)

  54859. * BP_BREAKPOINT <1>:                     Breakpoints In Guile.

  54860.                                                               (line  57)

  54861. * BP_HARDWARE_WATCHPOINT:                Breakpoints In Python.

  54862.                                                               (line  68)

  54863. * BP_HARDWARE_WATCHPOINT <1>:            Breakpoints In Guile.

  54864.                                                               (line  63)

  54865. * BP_READ_WATCHPOINT:                    Breakpoints In Python.

  54866.                                                               (line  71)

  54867. * BP_READ_WATCHPOINT <1>:                Breakpoints In Guile.

  54868.                                                               (line  67)

  54869. * BP_WATCHPOINT:                         Breakpoints In Python.

  54870.                                                               (line  65)

  54871. * BP_WATCHPOINT <1>:                     Breakpoints In Guile.

  54872.                                                               (line  60)

  54873. * bracketed-paste-begin ():              Commands For Text.   (line  36)

  54874. * break:                                 Set Breaks.          (line   6)

  54875. * break ... task TASKNO (Ada):           Ada Tasks.           (line 135)

  54876. * break ... thread THREAD-ID:            Thread-Specific Breakpoints.

  54877.                                                               (line  10)

  54878. * break, and Objective-C:                Method Names in Commands.

  54879.                                                               (line   9)

  54880. * break-range:                           PowerPC Embedded.    (line  41)

  54881. * breakpoint annotation:                 Annotations for Running.

  54882.                                                               (line  47)

  54883. * breakpoint-commands:                   Breakpoints In Guile.

  54884.                                                               (line 236)

  54885. * breakpoint-condition:                  Breakpoints In Guile.

  54886.                                                               (line 194)

  54887. * breakpoint-enabled?:                   Breakpoints In Guile.

  54888.                                                               (line 144)

  54889. * breakpoint-expression:                 Breakpoints In Guile.

  54890.                                                               (line 139)

  54891. * breakpoint-hit-count:                  Breakpoints In Guile.

  54892.                                                               (line 169)

  54893. * breakpoint-ignore-count:               Breakpoints In Guile.

  54894.                                                               (line 163)

  54895. * breakpoint-location:                   Breakpoints In Guile.

  54896.                                                               (line 134)

  54897. * breakpoint-notifications:              GDB/MI Support Commands.

  54898.                                                               (line  91)

  54899. * breakpoint-number:                     Breakpoints In Guile.

  54900.                                                               (line 122)

  54901. * breakpoint-silent?:                    Breakpoints In Guile.

  54902.                                                               (line 151)

  54903. * breakpoint-stop:                       Breakpoints In Guile.

  54904.                                                               (line 202)

  54905. * breakpoint-task:                       Breakpoints In Guile.

  54906.                                                               (line 185)

  54907. * breakpoint-thread:                     Breakpoints In Guile.

  54908.                                                               (line 176)

  54909. * breakpoint-type:                       Breakpoints In Guile.

  54910.                                                               (line 126)

  54911. * breakpoint-valid?:                     Breakpoints In Guile.

  54912.                                                               (line 112)

  54913. * breakpoint-visible?:                   Breakpoints In Guile.

  54914.                                                               (line 130)

  54915. * Breakpoint.commands:                   Breakpoints In Python.

  54916.                                                               (line 211)

  54917. * Breakpoint.condition:                  Breakpoints In Python.

  54918.                                                               (line 206)

  54919. * Breakpoint.delete:                     Breakpoints In Python.

  54920.                                                               (line 128)

  54921. * Breakpoint.enabled:                    Breakpoints In Python.

  54922.                                                               (line 133)

  54923. * Breakpoint.expression:                 Breakpoints In Python.

  54924.                                                               (line 200)

  54925. * Breakpoint.hit_count:                  Breakpoints In Python.

  54926.                                                               (line 189)

  54927. * Breakpoint.ignore_count:               Breakpoints In Python.

  54928.                                                               (line 161)

  54929. * Breakpoint.is_valid:                   Breakpoints In Python.

  54930.                                                               (line 120)

  54931. * Breakpoint.location:                   Breakpoints In Python.

  54932.                                                               (line 194)

  54933. * Breakpoint.number:                     Breakpoints In Python.

  54934.                                                               (line 165)

  54935. * Breakpoint.pending:                    Breakpoints In Python.

  54936.                                                               (line 146)

  54937. * Breakpoint.silent:                     Breakpoints In Python.

  54938.                                                               (line 138)

  54939. * Breakpoint.stop:                       Breakpoints In Python.

  54940.                                                               (line  89)

  54941. * Breakpoint.task:                       Breakpoints In Python.

  54942.                                                               (line 155)

  54943. * Breakpoint.temporary:                  Breakpoints In Python.

  54944.                                                               (line 180)

  54945. * Breakpoint.thread:                     Breakpoints In Python.

  54946.                                                               (line 150)

  54947. * Breakpoint.type:                       Breakpoints In Python.

  54948.                                                               (line 170)

  54949. * Breakpoint.visible:                    Breakpoints In Python.

  54950.                                                               (line 175)

  54951. * Breakpoint.__init__:                   Breakpoints In Python.

  54952.                                                               (line  16)

  54953. * Breakpoint.__init__ <1>:               Breakpoints In Python.

  54954.                                                               (line  49)

  54955. * breakpoint?:                           Breakpoints In Guile.

  54956.                                                               (line 108)

  54957. * BreakpointEvent.breakpoint:            Events In Python.    (line 105)

  54958. * BreakpointEvent.breakpoints:           Events In Python.    (line 101)

  54959. * breakpoints:                           Breakpoints In Guile.

  54960.                                                               (line 104)

  54961. * breakpoints-invalid annotation:        Invalidation.        (line  14)

  54962. * bt (backtrace):                        Backtrace.           (line  11)

  54963. * c (continue):                          Continuing and Stepping.

  54964.                                                               (line  16)

  54965. * c (SingleKey TUI key):                 TUI Single Key Mode. (line  10)

  54966. * C-L:                                   TUI Keys.            (line  79)

  54967. * C-x 1:                                 TUI Keys.            (line  22)

  54968. * C-x 2:                                 TUI Keys.            (line  32)

  54969. * C-x a:                                 TUI Keys.            (line  11)

  54970. * C-x A:                                 TUI Keys.            (line  12)

  54971. * C-x C-a:                               TUI Keys.            (line  10)

  54972. * C-x o:                                 TUI Keys.            (line  43)

  54973. * C-x s:                                 TUI Keys.            (line  53)

  54974. * call:                                  Calling.             (line  11)

  54975. * call-last-kbd-macro (C-x e):           Keyboard Macros.     (line  13)

  54976. * capitalize-word (M-c):                 Commands For Text.   (line  64)

  54977. * catch:                                 Set Catchpoints.     (line  10)

  54978. * catch assert:                          Set Catchpoints.     (line 112)

  54979. * catch catch:                           Set Catchpoints.     (line  16)

  54980. * catch exception:                       Set Catchpoints.     (line  66)

  54981. * catch exception unhandled:             Set Catchpoints.     (line  87)

  54982. * catch exec:                            Set Catchpoints.     (line 116)

  54983. * catch fork:                            Set Catchpoints.     (line 261)

  54984. * catch handlers:                        Set Catchpoints.     (line  92)

  54985. * catch load:                            Set Catchpoints.     (line 268)

  54986. * catch rethrow:                         Set Catchpoints.     (line  16)

  54987. * catch signal:                          Set Catchpoints.     (line 273)

  54988. * catch syscall:                         Set Catchpoints.     (line 120)

  54989. * catch throw:                           Set Catchpoints.     (line  16)

  54990. * catch unload:                          Set Catchpoints.     (line 268)

  54991. * catch vfork:                           Set Catchpoints.     (line 264)

  54992. * cd:                                    Working Directory.   (line  32)

  54993. * cdir:                                  Source Path.         (line  40)

  54994. * character-search (C-]):                Miscellaneous Commands.

  54995.                                                               (line  42)

  54996. * character-search-backward (M-C-]):     Miscellaneous Commands.

  54997.                                                               (line  47)

  54998. * checkpoint:                            Checkpoint/Restart.  (line  26)

  54999. * clear:                                 Delete Breaks.       (line  21)

  55000. * clear, and Objective-C:                Method Names in Commands.

  55001.                                                               (line   9)

  55002. * clear-screen (C-l):                    Commands For Moving. (line  40)

  55003. * ClearObjFilesEvent.progspace:          Events In Python.    (line 125)

  55004. * clone-inferior:                        Inferiors Connections and Programs.

  55005.                                                               (line 119)

  55006. * collect (tracepoints):                 Tracepoint Actions.  (line  49)

  55007. * colon-colon, in Modula-2:              M2 Scope.            (line   6)

  55008. * colored-completion-prefix:             Readline Init File Syntax.

  55009.                                                               (line  52)

  55010. * colored-stats:                         Readline Init File Syntax.

  55011.                                                               (line  59)

  55012. * Command.complete:                      Commands In Python.  (line  70)

  55013. * Command.dont_repeat:                   Commands In Python.  (line  42)

  55014. * Command.invoke:                        Commands In Python.  (line  48)

  55015. * Command.__init__:                      Commands In Python.  (line  10)

  55016. * command?:                              Commands In Guile.   (line  63)

  55017. * commands:                              Break Commands.      (line  11)

  55018. * commands annotation:                   Prompting.           (line  27)

  55019. * COMMAND_BREAKPOINTS:                   Commands In Python.  (line 142)

  55020. * COMMAND_BREAKPOINTS <1>:               Commands In Guile.   (line 177)

  55021. * COMMAND_DATA:                          Commands In Python.  (line 113)

  55022. * COMMAND_DATA <1>:                      Commands In Guile.   (line 148)

  55023. * COMMAND_FILES:                         Commands In Python.  (line 124)

  55024. * COMMAND_FILES <1>:                     Commands In Guile.   (line 159)

  55025. * COMMAND_MAINTENANCE:                   Commands In Python.  (line 171)

  55026. * COMMAND_MAINTENANCE <1>:               Commands In Guile.   (line 201)

  55027. * COMMAND_NONE:                          Commands In Python.  (line 103)

  55028. * COMMAND_NONE <1>:                      Commands In Guile.   (line 137)

  55029. * COMMAND_OBSCURE:                       Commands In Python.  (line 165)

  55030. * COMMAND_OBSCURE <1>:                   Commands In Guile.   (line 195)

  55031. * COMMAND_RUNNING:                       Commands In Python.  (line 107)

  55032. * COMMAND_RUNNING <1>:                   Commands In Guile.   (line 142)

  55033. * COMMAND_STACK:                         Commands In Python.  (line 118)

  55034. * COMMAND_STACK <1>:                     Commands In Guile.   (line 153)

  55035. * COMMAND_STATUS:                        Commands In Python.  (line 136)

  55036. * COMMAND_STATUS <1>:                    Commands In Guile.   (line 171)

  55037. * COMMAND_SUPPORT:                       Commands In Python.  (line 129)

  55038. * COMMAND_SUPPORT <1>:                   Commands In Guile.   (line 164)

  55039. * COMMAND_TRACEPOINTS:                   Commands In Python.  (line 148)

  55040. * COMMAND_TRACEPOINTS <1>:               Commands In Guile.   (line 183)

  55041. * COMMAND_TUI:                           Commands In Python.  (line 154)

  55042. * COMMAND_USER:                          Commands In Python.  (line 159)

  55043. * COMMAND_USER <1>:                      Commands In Guile.   (line 189)

  55044. * comment-begin:                         Readline Init File Syntax.

  55045.                                                               (line  65)

  55046. * compare-sections:                      Memory.              (line 149)

  55047. * compile code:                          Compiling and Injecting Code.

  55048.                                                               (line  11)

  55049. * compile file:                          Compiling and Injecting Code.

  55050.                                                               (line  56)

  55051. * complete:                              Help.                (line 106)

  55052. * complete (<TAB>):                      Commands For Completion.

  55053.                                                               (line   6)

  55054. * COMPLETE_COMMAND:                      Commands In Python.  (line 192)

  55055. * COMPLETE_COMMAND <1>:                  Commands In Guile.   (line 222)

  55056. * COMPLETE_EXPRESSION:                   Commands In Python.  (line 200)

  55057. * COMPLETE_EXPRESSION <1>:               Commands In Guile.   (line 230)

  55058. * COMPLETE_FILENAME:                     Commands In Python.  (line 185)

  55059. * COMPLETE_FILENAME <1>:                 Commands In Guile.   (line 215)

  55060. * COMPLETE_LOCATION:                     Commands In Python.  (line 188)

  55061. * COMPLETE_LOCATION <1>:                 Commands In Guile.   (line 218)

  55062. * COMPLETE_NONE:                         Commands In Python.  (line 182)

  55063. * COMPLETE_NONE <1>:                     Commands In Guile.   (line 212)

  55064. * COMPLETE_SYMBOL:                       Commands In Python.  (line 196)

  55065. * COMPLETE_SYMBOL <1>:                   Commands In Guile.   (line 226)

  55066. * completion-display-width:              Readline Init File Syntax.

  55067.                                                               (line  70)

  55068. * completion-ignore-case:                Readline Init File Syntax.

  55069.                                                               (line  77)

  55070. * completion-map-case:                   Readline Init File Syntax.

  55071.                                                               (line  82)

  55072. * completion-prefix-display-length:      Readline Init File Syntax.

  55073.                                                               (line  88)

  55074. * completion-query-items:                Readline Init File Syntax.

  55075.                                                               (line  95)

  55076. * condition:                             Conditions.          (line  58)

  55077. * continue:                              Continuing and Stepping.

  55078.                                                               (line  16)

  55079. * continue&:                             Background Execution.

  55080.                                                               (line  40)

  55081. * convert-meta:                          Readline Init File Syntax.

  55082.                                                               (line 105)

  55083. * copy-backward-word ():                 Commands For Killing.

  55084.                                                               (line  49)

  55085. * copy-forward-word ():                  Commands For Killing.

  55086.                                                               (line  54)

  55087. * copy-region-as-kill ():                Commands For Killing.

  55088.                                                               (line  45)

  55089. * core-file:                             Files.               (line 107)

  55090. * ctf:                                   Trace Files.         (line  28)

  55091. * Ctrl-o (operate-and-get-next):         Command Syntax.      (line  41)

  55092. * current-arch:                          Architectures In Guile.

  55093.                                                               (line  17)

  55094. * current-objfile:                       Objfiles In Guile.   (line  46)

  55095. * current-progspace:                     Progspaces In Guile. (line  26)

  55096. * cwd:                                   Source Path.         (line  40)

  55097. * d (delete):                            Delete Breaks.       (line  41)

  55098. * d (SingleKey TUI key):                 TUI Single Key Mode. (line  13)

  55099. * data-directory:                        Guile Configuration. (line   9)

  55100. * data-disassemble-a-option:             GDB/MI Support Commands.

  55101.                                                               (line 108)

  55102. * data-read-memory-bytes:                GDB/MI Support Commands.

  55103.                                                               (line  88)

  55104. * default-visualizer:                    Guile Pretty Printing API.

  55105.                                                               (line 129)

  55106. * define:                                Define.              (line  50)

  55107. * define-prefix:                         Define.              (line  75)

  55108. * delete:                                Delete Breaks.       (line  41)

  55109. * delete checkpoint CHECKPOINT-ID:       Checkpoint/Restart.  (line  53)

  55110. * delete display:                        Auto Display.        (line  45)

  55111. * delete mem:                            Memory Region Attributes.

  55112.                                                               (line  34)

  55113. * delete tracepoint:                     Create and Delete Tracepoints.

  55114.                                                               (line 125)

  55115. * delete tvariable:                      Trace State Variables.

  55116.                                                               (line  42)

  55117. * delete-breakpoint!:                    Breakpoints In Guile.

  55118.                                                               (line  95)

  55119. * delete-char (C-d):                     Commands For Text.   (line  12)

  55120. * delete-char-or-list ():                Commands For Completion.

  55121.                                                               (line  39)

  55122. * delete-horizontal-space ():            Commands For Killing.

  55123.                                                               (line  37)

  55124. * demangle:                              Symbols.             (line 114)

  55125. * detach:                                Attach.              (line  55)

  55126. * detach (remote):                       Connecting.          (line 263)

  55127. * detach inferiors INFNO...:             Inferiors Connections and Programs.

  55128.                                                               (line 148)

  55129. * digit-argument (M-0, M-1, ... M--):    Numeric Arguments.   (line   6)

  55130. * dir:                                   Source Path.         (line  99)

  55131. * directory:                             Source Path.         (line  99)

  55132. * dis (disable):                         Disabling.           (line  37)

  55133. * disable:                               Disabling.           (line  37)

  55134. * disable display:                       Auto Display.        (line  56)

  55135. * disable frame-filter:                  Frame Filter Management.

  55136.                                                               (line  16)

  55137. * disable mem:                           Memory Region Attributes.

  55138.                                                               (line  38)

  55139. * disable pretty-printer:                Pretty-Printer Commands.

  55140.                                                               (line  20)

  55141. * disable probes:                        Static Probe Points. (line  73)

  55142. * disable tracepoint:                    Enable and Disable Tracepoints.

  55143.                                                               (line   9)

  55144. * disable type-printer:                  Symbols.             (line 411)

  55145. * disable-completion:                    Readline Init File Syntax.

  55146.                                                               (line 113)

  55147. * disassemble:                           Machine Code.        (line  43)

  55148. * disconnect:                            Connecting.          (line 272)

  55149. * display:                               Auto Display.        (line  23)

  55150. * do (down):                             Selection.           (line  74)

  55151. * do-lowercase-version (M-A, M-B, M-X, ...): Miscellaneous Commands.

  55152.                                                               (line  14)

  55153. * document:                              Define.              (line  63)

  55154. * dont-repeat:                           Commands In Guile.   (line  67)

  55155. * dont-repeat <1>:                       Define.              (line 111)

  55156. * down:                                  Selection.           (line  74)

  55157. * Down:                                  TUI Keys.            (line  70)

  55158. * down-silently:                         Selection.           (line 106)

  55159. * downcase-word (M-l):                   Commands For Text.   (line  60)

  55160. * dprintf:                               Dynamic Printf.      (line  26)

  55161. * dprintf-style agent:                   Dynamic Printf.      (line  46)

  55162. * dprintf-style call:                    Dynamic Printf.      (line  42)

  55163. * dprintf-style gdb:                     Dynamic Printf.      (line  39)

  55164. * dump:                                  Dump/Restore Files.  (line  13)

  55165. * dump-functions ():                     Miscellaneous Commands.

  55166.                                                               (line  70)

  55167. * dump-macros ():                        Miscellaneous Commands.

  55168.                                                               (line  82)

  55169. * dump-variables ():                     Miscellaneous Commands.

  55170.                                                               (line  76)

  55171. * e (edit):                              Edit.                (line   6)

  55172. * echo:                                  Output.              (line  12)

  55173. * echo-control-characters:               Readline Init File Syntax.

  55174.                                                               (line 118)

  55175. * edit:                                  Edit.                (line   6)

  55176. * editing-mode:                          Readline Init File Syntax.

  55177.                                                               (line 123)

  55178. * else:                                  Command Files.       (line  74)

  55179. * emacs-editing-mode (C-e):              Miscellaneous Commands.

  55180.                                                               (line  88)

  55181. * emacs-mode-string:                     Readline Init File Syntax.

  55182.                                                               (line 129)

  55183. * enable:                                Disabling.           (line  44)

  55184. * enable display:                        Auto Display.        (line  65)

  55185. * enable frame-filter:                   Frame Filter Management.

  55186.                                                               (line  26)

  55187. * enable mem:                            Memory Region Attributes.

  55188.                                                               (line  42)

  55189. * enable pretty-printer:                 Pretty-Printer Commands.

  55190.                                                               (line  25)

  55191. * enable probes:                         Static Probe Points. (line  60)

  55192. * enable tracepoint:                     Enable and Disable Tracepoints.

  55193.                                                               (line  19)

  55194. * enable type-printer:                   Symbols.             (line 411)

  55195. * enable-bracketed-paste:                Readline Init File Syntax.

  55196.                                                               (line 139)

  55197. * enable-keypad:                         Readline Init File Syntax.

  55198.                                                               (line 147)

  55199. * enabled:                               Xmethod API.         (line  18)

  55200. * enabled of type_printer:               Type Printing API.   (line  13)

  55201. * end (breakpoint commands):             Break Commands.      (line  11)

  55202. * end (if/else/while commands):          Command Files.       (line 103)

  55203. * end (user-defined commands):           Define.              (line  63)

  55204. * end-kbd-macro (C-x )):                 Keyboard Macros.     (line   9)

  55205. * end-of-file (usually C-d):             Commands For Text.   (line   6)

  55206. * end-of-history (M->):                  Commands For History.

  55207.                                                               (line  22)

  55208. * end-of-iteration:                      Iterators In Guile.  (line  70)

  55209. * end-of-iteration?:                     Iterators In Guile.  (line  73)

  55210. * end-of-line (C-e):                     Commands For Moving. (line   9)

  55211. * error annotation:                      Errors.              (line  10)

  55212. * error-begin annotation:                Errors.              (line  22)

  55213. * error-port:                            I/O Ports in Guile.  (line  12)

  55214. * eval:                                  Output.              (line 117)

  55215. * EventRegistry.connect:                 Events In Python.    (line  19)

  55216. * EventRegistry.disconnect:              Events In Python.    (line  23)

  55217. * exception-args:                        Guile Exception Handling.

  55218.                                                               (line 103)

  55219. * exception-key:                         Guile Exception Handling.

  55220.                                                               (line 100)

  55221. * exception?:                            Guile Exception Handling.

  55222.                                                               (line  96)

  55223. * exceptionHandler:                      Bootstrapping.       (line  38)

  55224. * exchange-point-and-mark (C-x C-x):     Miscellaneous Commands.

  55225.                                                               (line  37)

  55226. * exec-file:                             Files.               (line  39)

  55227. * exec-file-mismatch:                    Attach.              (line  34)

  55228. * exec-run-start-option:                 GDB/MI Support Commands.

  55229.                                                               (line 105)

  55230. * execute:                               Basic Guile.         (line  68)

  55231. * exited annotation:                     Annotations for Running.

  55232.                                                               (line  18)

  55233. * ExitedEvent.exit_code:                 Events In Python.    (line  67)

  55234. * ExitedEvent.inferior:                  Events In Python.    (line  72)

  55235. * expand-tilde:                          Readline Init File Syntax.

  55236.                                                               (line 158)

  55237. * explore:                               Data.                (line 125)

  55238. * f (frame):                             Selection.           (line  11)

  55239. * f (SingleKey TUI key):                 TUI Single Key Mode. (line  16)

  55240. * faas:                                  Frame Apply.         (line  96)

  55241. * fg (resume foreground execution):      Continuing and Stepping.

  55242.                                                               (line  16)

  55243. * field-artificial?:                     Types In Guile.      (line 262)

  55244. * field-base-class?:                     Types In Guile.      (line 266)

  55245. * field-bitpos:                          Types In Guile.      (line 253)

  55246. * field-bitsize:                         Types In Guile.      (line 257)

  55247. * field-enumval:                         Types In Guile.      (line 250)

  55248. * field-name:                            Types In Guile.      (line 243)

  55249. * field-type:                            Types In Guile.      (line 246)

  55250. * field?:                                Types In Guile.      (line 239)

  55251. * file:                                  Files.               (line  16)

  55252. * fin (finish):                          Continuing and Stepping.

  55253.                                                               (line 109)

  55254. * find:                                  Searching Memory.    (line   9)

  55255. * find-pc-line:                          Symbol Tables In Guile.

  55256.                                                               (line  71)

  55257. * finish:                                Continuing and Stepping.

  55258.                                                               (line 109)

  55259. * finish&:                               Background Execution.

  55260.                                                               (line  43)

  55261. * FinishBreakpoint.out_of_scope:         Finish Breakpoints in Python.

  55262.                                                               (line  21)

  55263. * FinishBreakpoint.return_value:         Finish Breakpoints in Python.

  55264.                                                               (line  38)

  55265. * FinishBreakpoint.__init__:             Finish Breakpoints in Python.

  55266.                                                               (line  14)

  55267. * flash-erase:                           Target Commands.     (line 140)

  55268. * flushregs:                             Maintenance Commands.

  55269.                                                               (line 317)

  55270. * flush_i_cache:                         Bootstrapping.       (line  60)

  55271. * fo (forward-search):                   Search.              (line   9)

  55272. * focus:                                 TUI Commands.        (line 103)

  55273. * forward-backward-delete-char ():       Commands For Text.   (line  21)

  55274. * forward-char (C-f):                    Commands For Moving. (line  12)

  55275. * forward-search:                        Search.              (line   9)

  55276. * forward-search-history (C-s):          Commands For History.

  55277.                                                               (line  30)

  55278. * forward-word (M-f):                    Commands For Moving. (line  18)

  55279. * frame address:                         Selection.           (line  30)

  55280. * frame apply:                           Frame Apply.         (line   6)

  55281. * frame function:                        Selection.           (line  48)

  55282. * frame level:                           Selection.           (line  16)

  55283. * frame view:                            Selection.           (line  53)

  55284. * frame, selecting:                      Selection.           (line  11)

  55285. * frame-arch:                            Frames In Guile.     (line  35)

  55286. * frame-block:                           Frames In Guile.     (line 121)

  55287. * frame-function:                        Frames In Guile.     (line 125)

  55288. * frame-name:                            Frames In Guile.     (line  32)

  55289. * frame-newer:                           Frames In Guile.     (line 133)

  55290. * frame-older:                           Frames In Guile.     (line 130)

  55291. * frame-pc:                              Frames In Guile.     (line 118)

  55292. * frame-read-register:                   Frames In Guile.     (line 140)

  55293. * frame-read-var:                        Frames In Guile.     (line 144)

  55294. * frame-sal:                             Frames In Guile.     (line 136)

  55295. * frame-select:                          Frames In Guile.     (line 152)

  55296. * frame-type:                            Frames In Guile.     (line  39)

  55297. * frame-unwind-stop-reason:              Frames In Guile.     (line  67)

  55298. * frame-valid?:                          Frames In Guile.     (line  26)

  55299. * Frame.architecture:                    Frames In Python.    (line  53)

  55300. * Frame.block:                           Frames In Python.    (line 139)

  55301. * Frame.find_sal:                        Frames In Python.    (line 155)

  55302. * Frame.function:                        Frames In Python.    (line 145)

  55303. * Frame.is_valid:                        Frames In Python.    (line  43)

  55304. * Frame.name:                            Frames In Python.    (line  49)

  55305. * Frame.newer:                           Frames In Python.    (line 152)

  55306. * Frame.older:                           Frames In Python.    (line 149)

  55307. * Frame.pc:                              Frames In Python.    (line 136)

  55308. * Frame.read_register:                   Frames In Python.    (line 159)

  55309. * Frame.read_var:                        Frames In Python.    (line 179)

  55310. * Frame.select:                          Frames In Python.    (line 187)

  55311. * Frame.type:                            Frames In Python.    (line  57)

  55312. * Frame.unwind_stop_reason:              Frames In Python.    (line  84)

  55313. * frame?:                                Frames In Guile.     (line  22)

  55314. * FrameDecorator.address:                Frame Decorator API. (line  60)

  55315. * FrameDecorator.elided:                 Frame Decorator API. (line  29)

  55316. * FrameDecorator.filename:               Frame Decorator API. (line  70)

  55317. * FrameDecorator.frame_args:             Frame Decorator API. (line  91)

  55318. * FrameDecorator.frame_locals:           Frame Decorator API. (line 143)

  55319. * FrameDecorator.function:               Frame Decorator API. (line  49)

  55320. * FrameDecorator.inferior_frame:         Frame Decorator API. (line 176)

  55321. * FrameDecorator.line:                   Frame Decorator API. (line  81)

  55322. * FrameFilter.enabled:                   Frame Filter API.    (line 122)

  55323. * FrameFilter.filter:                    Frame Filter API.    (line  75)

  55324. * FrameFilter.name:                      Frame Filter API.    (line 115)

  55325. * FrameFilter.priority:                  Frame Filter API.    (line 131)

  55326. * frames-invalid annotation:             Invalidation.        (line   9)

  55327. * frozen-varobjs:                        GDB/MI Support Commands.

  55328.                                                               (line  75)

  55329. * ftrace:                                Create and Delete Tracepoints.

  55330.                                                               (line  50)

  55331. * Function:                              Functions In Python. (line   6)

  55332. * Function.invoke:                       Functions In Python. (line  19)

  55333. * Function.__init__:                     Functions In Python. (line  10)

  55334. * gcore:                                 Core File Generation.

  55335.                                                               (line  17)

  55336. * gdb-object-kind:                       GDB Scheme Data Types.

  55337.                                                               (line  10)

  55338. * gdb-version:                           Guile Configuration. (line  17)

  55339. * gdb.Block:                             Blocks In Python.    (line   6)

  55340. * gdb.block_for_pc:                      Blocks In Python.    (line  64)

  55341. * gdb.block_for_pc <1>:                  Blocks In Python.    (line  64)

  55342. * gdb.BP_ACCESS_WATCHPOINT:              Breakpoints In Python.

  55343.                                                               (line  74)

  55344. * gdb.BP_BREAKPOINT:                     Breakpoints In Python.

  55345.                                                               (line  62)

  55346. * gdb.BP_HARDWARE_WATCHPOINT:            Breakpoints In Python.

  55347.                                                               (line  68)

  55348. * gdb.BP_READ_WATCHPOINT:                Breakpoints In Python.

  55349.                                                               (line  71)

  55350. * gdb.BP_WATCHPOINT:                     Breakpoints In Python.

  55351.                                                               (line  65)

  55352. * gdb.Breakpoint:                        Breakpoints In Python.

  55353.                                                               (line   6)

  55354. * gdb.breakpoints:                       Basic Python.        (line  59)

  55355. * gdb.breakpoints <1>:                   Basic Python.        (line  59)

  55356. * gdb.COMMAND_BREAKPOINTS:               Commands In Python.  (line 142)

  55357. * gdb.COMMAND_DATA:                      Commands In Python.  (line 113)

  55358. * gdb.COMMAND_FILES:                     Commands In Python.  (line 124)

  55359. * gdb.COMMAND_MAINTENANCE:               Commands In Python.  (line 171)

  55360. * gdb.COMMAND_NONE:                      Commands In Python.  (line 103)

  55361. * gdb.COMMAND_OBSCURE:                   Commands In Python.  (line 165)

  55362. * gdb.COMMAND_RUNNING:                   Commands In Python.  (line 107)

  55363. * gdb.COMMAND_STACK:                     Commands In Python.  (line 118)

  55364. * gdb.COMMAND_STATUS:                    Commands In Python.  (line 136)

  55365. * gdb.COMMAND_SUPPORT:                   Commands In Python.  (line 129)

  55366. * gdb.COMMAND_TRACEPOINTS:               Commands In Python.  (line 148)

  55367. * gdb.COMMAND_TUI:                       Commands In Python.  (line 154)

  55368. * gdb.COMMAND_USER:                      Commands In Python.  (line 159)

  55369. * gdb.COMPLETE_COMMAND:                  Commands In Python.  (line 192)

  55370. * gdb.COMPLETE_EXPRESSION:               Commands In Python.  (line 200)

  55371. * gdb.COMPLETE_FILENAME:                 Commands In Python.  (line 185)

  55372. * gdb.COMPLETE_LOCATION:                 Commands In Python.  (line 188)

  55373. * gdb.COMPLETE_NONE:                     Commands In Python.  (line 182)

  55374. * gdb.COMPLETE_SYMBOL:                   Commands In Python.  (line 196)

  55375. * gdb.convenience_variable:              Basic Python.        (line 106)

  55376. * gdb.convenience_variable <1>:          Basic Python.        (line 106)

  55377. * gdb.current_objfile:                   Objfiles In Python.  (line  15)

  55378. * gdb.current_objfile <1>:               Objfiles In Python.  (line  15)

  55379. * gdb.current_progspace:                 Progspaces In Python.

  55380.                                                               (line  14)

  55381. * gdb.current_progspace <1>:             Progspaces In Python.

  55382.                                                               (line  14)

  55383. * gdb.current_recording:                 Recordings In Python.

  55384.                                                               (line  21)

  55385. * gdb.decode_line:                       Basic Python.        (line 229)

  55386. * gdb.decode_line <1>:                   Basic Python.        (line 229)

  55387. * gdb.default_visualizer:                Pretty Printing API. (line  96)

  55388. * gdb.default_visualizer <1>:            Pretty Printing API. (line  96)

  55389. * gdb.error:                             Exception Handling.  (line  22)

  55390. * gdb.execute:                           Basic Python.        (line  40)

  55391. * gdb.execute <1>:                       Basic Python.        (line  40)

  55392. * gdb.find_pc_line:                      Basic Python.        (line 132)

  55393. * gdb.find_pc_line <1>:                  Basic Python.        (line 132)

  55394. * gdb.FinishBreakpoint:                  Finish Breakpoints in Python.

  55395.                                                               (line   6)

  55396. * gdb.flush:                             Basic Python.        (line 193)

  55397. * gdb.flush <1>:                         Basic Python.        (line 193)

  55398. * gdb.FrameDecorator:                    Frame Decorator API. (line  25)

  55399. * gdb.frame_stop_reason_string:          Frames In Python.    (line  29)

  55400. * gdb.Function:                          Functions In Python. (line   6)

  55401. * gdb.GdbError:                          Exception Handling.  (line  48)

  55402. * gdb.history:                           Basic Python.        (line  93)

  55403. * gdb.history <1>:                       Basic Python.        (line  93)

  55404. * gdb.Inferior:                          Inferiors In Python. (line   6)

  55405. * gdb.InferiorCallPostEvent:             Events In Python.    (line 145)

  55406. * gdb.InferiorCallPreEvent:              Events In Python.    (line 135)

  55407. * gdb.inferiors:                         Inferiors In Python. (line  14)

  55408. * gdb.InferiorThread:                    Threads In Python.   (line   6)

  55409. * gdb.invalidate_cached_frames:          Frames In Python.    (line  34)

  55410. * gdb.invalidate_cached_frames <1>:      Frames In Python.    (line  34)

  55411. * gdb.LazyString:                        Lazy Strings In Python.

  55412.                                                               (line   6)

  55413. * gdb.LineTable:                         Line Tables In Python.

  55414.                                                               (line   6)

  55415. * gdb.lookup_global_symbol:              Symbols In Python.   (line  33)

  55416. * gdb.lookup_global_symbol <1>:          Symbols In Python.   (line  33)

  55417. * gdb.lookup_objfile:                    Objfiles In Python.  (line  28)

  55418. * gdb.lookup_objfile <1>:                Objfiles In Python.  (line  28)

  55419. * gdb.lookup_static_symbol:              Symbols In Python.   (line  45)

  55420. * gdb.lookup_static_symbol <1>:          Symbols In Python.   (line  45)

  55421. * gdb.lookup_static_symbols:             Symbols In Python.   (line  71)

  55422. * gdb.lookup_static_symbols <1>:         Symbols In Python.   (line  71)

  55423. * gdb.lookup_symbol:                     Symbols In Python.   (line  13)

  55424. * gdb.lookup_symbol <1>:                 Symbols In Python.   (line  13)

  55425. * gdb.lookup_type:                       Types In Python.     (line  11)

  55426. * gdb.lookup_type <1>:                   Types In Python.     (line  11)

  55427. * gdb.MemoryError:                       Exception Handling.  (line  30)

  55428. * gdb.newest_frame:                      Frames In Python.    (line  26)

  55429. * gdb.newest_frame <1>:                  Frames In Python.    (line  26)

  55430. * gdb.Objfile:                           Objfiles In Python.  (line   6)

  55431. * gdb.objfiles:                          Objfiles In Python.  (line  21)

  55432. * gdb.objfiles <1>:                      Objfiles In Python.  (line  21)

  55433. * gdb.Parameter:                         Parameters In Python.

  55434.                                                               (line   6)

  55435. * gdb.parameter:                         Basic Python.        (line  82)

  55436. * gdb.parameter <1>:                     Basic Python.        (line  82)

  55437. * gdb.PARAM_AUTO_BOOLEAN:                Parameters In Python.

  55438.                                                               (line 116)

  55439. * gdb.PARAM_BOOLEAN:                     Parameters In Python.

  55440.                                                               (line 112)

  55441. * gdb.PARAM_ENUM:                        Parameters In Python.

  55442.                                                               (line 160)

  55443. * gdb.PARAM_FILENAME:                    Parameters In Python.

  55444.                                                               (line 142)

  55445. * gdb.PARAM_INTEGER:                     Parameters In Python.

  55446.                                                               (line 125)

  55447. * gdb.PARAM_OPTIONAL_FILENAME:           Parameters In Python.

  55448.                                                               (line 139)

  55449. * gdb.PARAM_STRING:                      Parameters In Python.

  55450.                                                               (line 129)

  55451. * gdb.PARAM_STRING_NOESCAPE:             Parameters In Python.

  55452.                                                               (line 135)

  55453. * gdb.PARAM_UINTEGER:                    Parameters In Python.

  55454.                                                               (line 121)

  55455. * gdb.PARAM_ZINTEGER:                    Parameters In Python.

  55456.                                                               (line 146)

  55457. * gdb.PARAM_ZUINTEGER:                   Parameters In Python.

  55458.                                                               (line 150)

  55459. * gdb.PARAM_ZUINTEGER_UNLIMITED:         Parameters In Python.

  55460.                                                               (line 155)

  55461. * gdb.parse_and_eval:                    Basic Python.        (line 122)

  55462. * gdb.parse_and_eval <1>:                Basic Python.        (line 122)

  55463. * gdb.post_event:                        Basic Python.        (line 141)

  55464. * gdb.post_event <1>:                    Basic Python.        (line 141)

  55465. * gdb.pretty_printers:                   Selecting Pretty-Printers.

  55466.                                                               (line  12)

  55467. * gdb.pretty_printers <1>:               Selecting Pretty-Printers.

  55468.                                                               (line  12)

  55469. * gdb.Progspace:                         Progspaces In Python.

  55470.                                                               (line   6)

  55471. * gdb.progspaces:                        Progspaces In Python.

  55472.                                                               (line  20)

  55473. * gdb.progspaces <1>:                    Progspaces In Python.

  55474.                                                               (line  20)

  55475. * gdb.prompt_hook:                       Basic Python.        (line 241)

  55476. * gdb.PYTHONDIR:                         Basic Python.        (line  37)

  55477. * gdb.PYTHONDIR <1>:                     Basic Python.        (line  37)

  55478. * gdb.rbreak:                            Basic Python.        (line  66)

  55479. * gdb.register_window_type:              TUI Windows In Python.

  55480.                                                               (line   8)

  55481. * gdb.register_window_type <1>:          TUI Windows In Python.

  55482.                                                               (line   8)

  55483. * gdb.search_memory:                     Inferiors In Python. (line  71)

  55484. * gdb.selected_frame:                    Frames In Python.    (line  22)

  55485. * gdb.selected_frame <1>:                Frames In Python.    (line  22)

  55486. * gdb.selected_inferior:                 Inferiors In Python. (line  17)

  55487. * gdb.selected_thread:                   Threads In Python.   (line  13)

  55488. * gdb.selected_thread <1>:               Threads In Python.   (line  13)

  55489. * gdb.set_convenience_variable:          Basic Python.        (line 113)

  55490. * gdb.set_convenience_variable <1>:      Basic Python.        (line 113)

  55491. * gdb.solib_name:                        Basic Python.        (line 223)

  55492. * gdb.solib_name <1>:                    Basic Python.        (line 223)

  55493. * gdb.start_recording:                   Recordings In Python.

  55494.                                                               (line   9)

  55495. * gdb.STDERR:                            Basic Python.        (line 183)

  55496. * gdb.STDERR <1>:                        Basic Python.        (line 203)

  55497. * gdb.STDLOG:                            Basic Python.        (line 186)

  55498. * gdb.STDLOG <1>:                        Basic Python.        (line 206)

  55499. * gdb.STDOUT:                            Basic Python.        (line 180)

  55500. * gdb.STDOUT <1>:                        Basic Python.        (line 200)

  55501. * gdb.stop_recording:                    Recordings In Python.

  55502.                                                               (line  25)

  55503. * gdb.string_to_argv:                    Commands In Python.  (line  61)

  55504. * gdb.Symbol:                            Symbols In Python.   (line   6)

  55505. * gdb.SYMBOL_COMMON_BLOCK_DOMAIN:        Symbols In Python.   (line 178)

  55506. * gdb.SYMBOL_LABEL_DOMAIN:               Symbols In Python.   (line 172)

  55507. * gdb.SYMBOL_LOC_ARG:                    Symbols In Python.   (line 197)

  55508. * gdb.SYMBOL_LOC_BLOCK:                  Symbols In Python.   (line 218)

  55509. * gdb.SYMBOL_LOC_COMPUTED:               Symbols In Python.   (line 232)

  55510. * gdb.SYMBOL_LOC_COMPUTED <1>:           Symbols In Python.   (line 235)

  55511. * gdb.SYMBOL_LOC_CONST:                  Symbols In Python.   (line 188)

  55512. * gdb.SYMBOL_LOC_CONST_BYTES:            Symbols In Python.   (line 221)

  55513. * gdb.SYMBOL_LOC_LOCAL:                  Symbols In Python.   (line 211)

  55514. * gdb.SYMBOL_LOC_OPTIMIZED_OUT:          Symbols In Python.   (line 229)

  55515. * gdb.SYMBOL_LOC_REF_ARG:                Symbols In Python.   (line 201)

  55516. * gdb.SYMBOL_LOC_REGISTER:               Symbols In Python.   (line 194)

  55517. * gdb.SYMBOL_LOC_REGPARM_ADDR:           Symbols In Python.   (line 206)

  55518. * gdb.SYMBOL_LOC_STATIC:                 Symbols In Python.   (line 191)

  55519. * gdb.SYMBOL_LOC_TYPEDEF:                Symbols In Python.   (line 214)

  55520. * gdb.SYMBOL_LOC_UNDEF:                  Symbols In Python.   (line 184)

  55521. * gdb.SYMBOL_LOC_UNRESOLVED:             Symbols In Python.   (line 224)

  55522. * gdb.SYMBOL_MODULE_DOMAIN:              Symbols In Python.   (line 175)

  55523. * gdb.SYMBOL_STRUCT_DOMAIN:              Symbols In Python.   (line 169)

  55524. * gdb.SYMBOL_UNDEF_DOMAIN:               Symbols In Python.   (line 160)

  55525. * gdb.SYMBOL_VAR_DOMAIN:                 Symbols In Python.   (line 165)

  55526. * gdb.Symtab:                            Symbol Tables In Python.

  55527.                                                               (line   6)

  55528. * gdb.Symtab_and_line:                   Symbol Tables In Python.

  55529.                                                               (line   6)

  55530. * gdb.target_charset:                    Basic Python.        (line 212)

  55531. * gdb.target_charset <1>:                Basic Python.        (line 212)

  55532. * gdb.target_wide_charset:               Basic Python.        (line 217)

  55533. * gdb.target_wide_charset <1>:           Basic Python.        (line 217)

  55534. * gdb.Type:                              Types In Python.     (line   6)

  55535. * gdb.TYPE_CODE_ARRAY:                   Types In Python.     (line 228)

  55536. * gdb.TYPE_CODE_BITSTRING:               Types In Python.     (line 266)

  55537. * gdb.TYPE_CODE_BOOL:                    Types In Python.     (line 290)

  55538. * gdb.TYPE_CODE_CHAR:                    Types In Python.     (line 287)

  55539. * gdb.TYPE_CODE_COMPLEX:                 Types In Python.     (line 293)

  55540. * gdb.TYPE_CODE_DECFLOAT:                Types In Python.     (line 302)

  55541. * gdb.TYPE_CODE_ENUM:                    Types In Python.     (line 237)

  55542. * gdb.TYPE_CODE_ERROR:                   Types In Python.     (line 269)

  55543. * gdb.TYPE_CODE_FLAGS:                   Types In Python.     (line 240)

  55544. * gdb.TYPE_CODE_FLT:                     Types In Python.     (line 249)

  55545. * gdb.TYPE_CODE_FUNC:                    Types In Python.     (line 243)

  55546. * gdb.TYPE_CODE_INT:                     Types In Python.     (line 246)

  55547. * gdb.TYPE_CODE_INTERNAL_FUNCTION:       Types In Python.     (line 305)

  55548. * gdb.TYPE_CODE_MEMBERPTR:               Types In Python.     (line 278)

  55549. * gdb.TYPE_CODE_METHOD:                  Types In Python.     (line 272)

  55550. * gdb.TYPE_CODE_METHODPTR:               Types In Python.     (line 275)

  55551. * gdb.TYPE_CODE_NAMESPACE:               Types In Python.     (line 299)

  55552. * gdb.TYPE_CODE_PTR:                     Types In Python.     (line 225)

  55553. * gdb.TYPE_CODE_RANGE:                   Types In Python.     (line 258)

  55554. * gdb.TYPE_CODE_REF:                     Types In Python.     (line 281)

  55555. * gdb.TYPE_CODE_RVALUE_REF:              Types In Python.     (line 284)

  55556. * gdb.TYPE_CODE_SET:                     Types In Python.     (line 255)

  55557. * gdb.TYPE_CODE_STRING:                  Types In Python.     (line 261)

  55558. * gdb.TYPE_CODE_STRUCT:                  Types In Python.     (line 231)

  55559. * gdb.TYPE_CODE_TYPEDEF:                 Types In Python.     (line 296)

  55560. * gdb.TYPE_CODE_UNION:                   Types In Python.     (line 234)

  55561. * gdb.TYPE_CODE_VOID:                    Types In Python.     (line 252)

  55562. * gdb.unwinder.register_unwinder:        Unwinding Frames in Python.

  55563.                                                               (line 161)

  55564. * gdb.UnwindInfo.add_saved_register:     Unwinding Frames in Python.

  55565.                                                               (line 111)

  55566. * gdb.WP_ACCESS:                         Breakpoints In Python.

  55567.                                                               (line  86)

  55568. * gdb.WP_READ:                           Breakpoints In Python.

  55569.                                                               (line  80)

  55570. * gdb.WP_WRITE:                          Breakpoints In Python.

  55571.                                                               (line  83)

  55572. * gdb.write:                             Basic Python.        (line 175)

  55573. * gdb.write <1>:                         Basic Python.        (line 175)

  55574. * gdb:error:                             Guile Exception Handling.

  55575.                                                               (line  69)

  55576. * gdb:invalid-object:                    Guile Exception Handling.

  55577.                                                               (line  72)

  55578. * gdb:memory-error:                      Guile Exception Handling.

  55579.                                                               (line  80)

  55580. * gdb:pp-type-error:                     Guile Exception Handling.

  55581.                                                               (line  84)

  55582. * gdbserver:                             Server.              (line   6)

  55583. * gdb_init_reader:                       Writing JIT Debug Info Readers.

  55584.                                                               (line  20)

  55585. * generate-core-file:                    Core File Generation.

  55586.                                                               (line  17)

  55587. * get-basic-type:                        Guile Types Module.  (line  13)

  55588. * getDebugChar:                          Bootstrapping.       (line  14)

  55589. * gnu_debuglink_crc32:                   Separate Debug Files.

  55590.                                                               (line 163)

  55591. * gr:                                    Guile Commands.      (line   8)

  55592. * gu:                                    Guile Commands.      (line  15)

  55593. * guile:                                 Guile Commands.      (line  15)

  55594. * guile-data-directory:                  Guile Configuration. (line  13)

  55595. * guile-repl:                            Guile Commands.      (line   8)

  55596. * h (help):                              Help.                (line   9)

  55597. * handle:                                Signals.             (line  49)

  55598. * handle_exception:                      Stub Contents.       (line  15)

  55599. * hbreak:                                Set Breaks.          (line  61)

  55600. * help:                                  Help.                (line   6)

  55601. * help function:                         Convenience Funs.    (line 228)

  55602. * help target:                           Target Commands.     (line  19)

  55603. * help user-defined:                     Define.              (line 116)

  55604. * history-append!:                       Basic Guile.         (line 105)

  55605. * history-preserve-point:                Readline Init File Syntax.

  55606.                                                               (line 162)

  55607. * history-ref:                           Basic Guile.         (line  87)

  55608. * history-search-backward ():            Commands For History.

  55609.                                                               (line  52)

  55610. * history-search-forward ():             Commands For History.

  55611.                                                               (line  46)

  55612. * history-size:                          Readline Init File Syntax.

  55613.                                                               (line 168)

  55614. * history-substring-search-backward ():  Commands For History.

  55615.                                                               (line  64)

  55616. * history-substring-search-forward ():   Commands For History.

  55617.                                                               (line  58)

  55618. * hook:                                  Hooks.               (line   6)

  55619. * hookpost:                              Hooks.               (line  11)

  55620. * horizontal-scroll-mode:                Readline Init File Syntax.

  55621.                                                               (line 177)

  55622. * host-config:                           Guile Configuration. (line  20)

  55623. * i (info):                              Help.                (line 129)

  55624. * i (SingleKey TUI key):                 TUI Single Key Mode. (line  34)

  55625. * if:                                    Command Files.       (line  74)

  55626. * ignore:                                Conditions.          (line  90)

  55627. * inferior INFNO:                        Inferiors Connections and Programs.

  55628.                                                               (line  85)

  55629. * Inferior.architecture:                 Inferiors In Python. (line  50)

  55630. * Inferior.is_valid:                     Inferiors In Python. (line  38)

  55631. * Inferior.num:                          Inferiors In Python. (line  22)

  55632. * Inferior.pid:                          Inferiors In Python. (line  25)

  55633. * Inferior.progspace:                    Inferiors In Python. (line  33)

  55634. * Inferior.read_memory:                  Inferiors In Python. (line  57)

  55635. * Inferior.read_memory <1>:              Inferiors In Python. (line  57)

  55636. * Inferior.search_memory:                Inferiors In Python. (line  71)

  55637. * Inferior.threads:                      Inferiors In Python. (line  45)

  55638. * Inferior.thread_from_handle:           Inferiors In Python. (line  80)

  55639. * Inferior.thread_from_handle <1>:       Inferiors In Python. (line  80)

  55640. * Inferior.thread_from_thread_handle:    Inferiors In Python. (line  80)

  55641. * Inferior.was_attached:                 Inferiors In Python. (line  29)

  55642. * Inferior.write_memory:                 Inferiors In Python. (line  64)

  55643. * Inferior.write_memory <1>:             Inferiors In Python. (line  64)

  55644. * InferiorCallPostEvent.address:         Events In Python.    (line 152)

  55645. * InferiorCallPostEvent.ptid:            Events In Python.    (line 149)

  55646. * InferiorCallPreEvent.address:          Events In Python.    (line 142)

  55647. * InferiorCallPreEvent.ptid:             Events In Python.    (line 139)

  55648. * InferiorThread.global_num:             Threads In Python.   (line  35)

  55649. * InferiorThread.handle:                 Threads In Python.   (line  74)

  55650. * InferiorThread.inferior:               Threads In Python.   (line  48)

  55651. * InferiorThread.is_exited:              Threads In Python.   (line  71)

  55652. * InferiorThread.is_running:             Threads In Python.   (line  68)

  55653. * InferiorThread.is_stopped:             Threads In Python.   (line  65)

  55654. * InferiorThread.is_valid:               Threads In Python.   (line  54)

  55655. * InferiorThread.name:                   Threads In Python.   (line  22)

  55656. * InferiorThread.num:                    Threads In Python.   (line  32)

  55657. * InferiorThread.ptid:                   Threads In Python.   (line  40)

  55658. * InferiorThread.switch:                 Threads In Python.   (line  61)

  55659. * info:                                  Help.                (line 129)

  55660. * info address:                          Symbols.             (line  85)

  55661. * info all-registers:                    Registers.           (line  15)

  55662. * info args:                             Frame Info.          (line  43)

  55663. * info auto-load:                        Auto-loading.        (line  60)

  55664. * info auto-load gdb-scripts:            Auto-loading sequences.

  55665.                                                               (line  21)

  55666. * info auto-load guile-scripts:          Guile Auto-loading.  (line  23)

  55667. * info auto-load libthread-db:           libthread_db.so.1 file.

  55668.                                                               (line  29)

  55669. * info auto-load local-gdbinit:          Init File in the Current Directory.

  55670.                                                               (line  22)

  55671. * info auto-load python-scripts:         Python Auto-loading. (line  23)

  55672. * info auxv:                             OS Information.      (line  20)

  55673. * info breakpoints:                      Set Breaks.          (line 133)

  55674. * info checkpoints:                      Checkpoint/Restart.  (line  31)

  55675. * info classes:                          Symbols.             (line 570)

  55676. * info common:                           Special Fortran Commands.

  55677.                                                               (line   9)

  55678. * info connections [ ID... ]:            Inferiors Connections and Programs.

  55679.                                                               (line  58)

  55680. * info copying:                          Help.                (line 167)

  55681. * info dcache:                           Caching Target Data. (line  46)

  55682. * info display:                          Auto Display.        (line  78)

  55683. * info dll:                              Files.               (line 336)

  55684. * info dos:                              DJGPP Native.        (line  15)

  55685. * info exceptions:                       Ada Exceptions.      (line   8)

  55686. * info extensions:                       Show.                (line  34)

  55687. * info f (info frame):                   Frame Info.          (line  17)

  55688. * info files:                            Files.               (line 211)

  55689. * info float:                            Floating Point Hardware.

  55690.                                                               (line   9)

  55691. * info frame:                            Frame Info.          (line  17)

  55692. * info frame, show the source language:  Show.                (line  15)

  55693. * info frame-filter:                     Frame Filter Management.

  55694.                                                               (line  12)

  55695. * info functions:                        Symbols.             (line 467)

  55696. * info handle:                           Signals.             (line  33)

  55697. * info inferiors [ ID... ]:              Inferiors Connections and Programs.

  55698.                                                               (line  27)

  55699. * info io_registers, AVR:                AVR.                 (line  10)

  55700. * info line:                             Machine Code.        (line  14)

  55701. * info line, and Objective-C:            Method Names in Commands.

  55702.                                                               (line   9)

  55703. * info locals:                           Frame Info.          (line  67)

  55704. * info macro:                            Macros.              (line  47)

  55705. * info macros:                           Macros.              (line  54)

  55706. * info mem:                              Memory Region Attributes.

  55707.                                                               (line  45)

  55708. * info meminfo:                          Process Information. (line 131)

  55709. * info module:                           Symbols.             (line 555)

  55710. * info modules:                          Symbols.             (line 547)

  55711. * info os:                               OS Information.      (line  37)

  55712. * info os cpus:                          OS Information.      (line  43)

  55713. * info os files:                         OS Information.      (line  51)

  55714. * info os modules:                       OS Information.      (line  57)

  55715. * info os msg:                           OS Information.      (line  64)

  55716. * info os processes:                     OS Information.      (line  75)

  55717. * info os procgroups:                    OS Information.      (line  84)

  55718. * info os semaphores:                    OS Information.      (line  94)

  55719. * info os shm:                           OS Information.      (line 102)

  55720. * info os sockets:                       OS Information.      (line 112)

  55721. * info os threads:                       OS Information.      (line 119)

  55722. * info pidlist:                          Process Information. (line 127)

  55723. * info pretty-printer:                   Pretty-Printer Commands.

  55724.                                                               (line   6)

  55725. * info probes:                           Static Probe Points. (line  32)

  55726. * info proc:                             Process Information. (line  25)

  55727. * info program:                          Stopping.            (line  18)

  55728. * info record:                           Process Record and Replay.

  55729.                                                               (line 323)

  55730. * info registers:                        Registers.           (line  11)

  55731. * info scope:                            Symbols.             (line 415)

  55732. * info selectors:                        Symbols.             (line 576)

  55733. * info serial:                           DJGPP Native.        (line 139)

  55734. * info set:                              Help.                (line 150)

  55735. * info share:                            Files.               (line 330)

  55736. * info sharedlibrary:                    Files.               (line 330)

  55737. * info signals:                          Signals.             (line  33)

  55738. * info skip:                             Skipping Over Functions and Files.

  55739.                                                               (line 113)

  55740. * info source:                           Symbols.             (line 436)

  55741. * info source, show the source language: Show.                (line  21)

  55742. * info sources:                          Symbols.             (line 452)

  55743. * info stack:                            Backtrace.           (line  94)

  55744. * info static-tracepoint-markers:        Listing Static Tracepoint Markers.

  55745.                                                               (line   6)

  55746. * info symbol:                           Symbols.             (line  95)

  55747. * info target:                           Files.               (line 211)

  55748. * info task TASKNO:                      Ada Tasks.           (line  88)

  55749. * info tasks:                            Ada Tasks.           (line   9)

  55750. * info terminal:                         Input/Output.        (line  12)

  55751. * info threads:                          Threads.             (line 115)

  55752. * info tp [N...]:                        Listing Tracepoints. (line   6)

  55753. * info tracepoints [N...]:               Listing Tracepoints. (line   6)

  55754. * info tvariables:                       Trace State Variables.

  55755.                                                               (line  37)

  55756. * info type-printers:                    Symbols.             (line 403)

  55757. * info types:                            Symbols.             (line 378)

  55758. * info variables:                        Symbols.             (line 512)

  55759. * info vector:                           Vector Unit.         (line   9)

  55760. * info w32:                              Cygwin Native.       (line  19)

  55761. * info warranty:                         Help.                (line 171)

  55762. * info watchpoints [LIST...]:            Set Watchpoints.     (line  87)

  55763. * info win:                              TUI Commands.        (line  26)

  55764. * info-gdb-mi-command:                   GDB/MI Support Commands.

  55765.                                                               (line  99)

  55766. * init-if-undefined:                     Convenience Vars.    (line  42)

  55767. * input-meta:                            Readline Init File Syntax.

  55768.                                                               (line 184)

  55769. * input-port:                            I/O Ports in Guile.  (line   6)

  55770. * insert-comment (M-#):                  Miscellaneous Commands.

  55771.                                                               (line  61)

  55772. * insert-completions (M-*):              Commands For Completion.

  55773.                                                               (line  18)

  55774. * inspect:                               Data.                (line   6)

  55775. * instantiate on type_printer:           Type Printing API.   (line  22)

  55776. * Instruction.data:                      Recordings In Python.

  55777.                                                               (line  69)

  55778. * Instruction.decoded:                   Recordings In Python.

  55779.                                                               (line  73)

  55780. * Instruction.pc:                        Recordings In Python.

  55781.                                                               (line  66)

  55782. * Instruction.size:                      Recordings In Python.

  55783.                                                               (line  76)

  55784. * interpreter-exec:                      Interpreters.        (line  39)

  55785. * interrupt:                             Background Execution.

  55786.                                                               (line  59)

  55787. * isearch-terminators:                   Readline Init File Syntax.

  55788.                                                               (line 192)

  55789. * iterator->list:                        Iterators In Guile.  (line  83)

  55790. * iterator-filter:                       Iterators In Guile.  (line  94)

  55791. * iterator-for-each:                     Iterators In Guile.  (line  90)

  55792. * iterator-map:                          Iterators In Guile.  (line  86)

  55793. * iterator-next!:                        Iterators In Guile.  (line  63)

  55794. * iterator-object:                       Iterators In Guile.  (line  53)

  55795. * iterator-progress:                     Iterators In Guile.  (line  57)

  55796. * iterator-until:                        Iterators In Guile.  (line  98)

  55797. * iterator?:                             Iterators In Guile.  (line  49)

  55798. * j (jump):                              Jumping.             (line  10)

  55799. * jit-reader-load:                       Using JIT Debug Info Readers.

  55800.                                                               (line   6)

  55801. * jit-reader-unload:                     Using JIT Debug Info Readers.

  55802.                                                               (line   6)

  55803. * jump:                                  Jumping.             (line  10)

  55804. * jump, and Objective-C:                 Method Names in Commands.

  55805.                                                               (line   9)

  55806. * KeyboardInterrupt:                     Exception Handling.  (line  34)

  55807. * keymap:                                Readline Init File Syntax.

  55808.                                                               (line 199)

  55809. * kill:                                  Kill Process.        (line   6)

  55810. * kill inferiors INFNO...:               Inferiors Connections and Programs.

  55811.                                                               (line 154)

  55812. * kill-line (C-k):                       Commands For Killing.

  55813.                                                               (line   6)

  55814. * kill-region ():                        Commands For Killing.

  55815.                                                               (line  41)

  55816. * kill-whole-line ():                    Commands For Killing.

  55817.                                                               (line  15)

  55818. * kill-word (M-d):                       Commands For Killing.

  55819.                                                               (line  19)

  55820. * kvm:                                   BSD libkvm Interface.

  55821.                                                               (line  24)

  55822. * l (list):                              List.                (line   6)

  55823. * language-option:                       GDB/MI Support Commands.

  55824.                                                               (line  96)

  55825. * layout:                                TUI Commands.        (line  75)

  55826. * lazy-string->value:                    Lazy Strings In Guile.

  55827.                                                               (line  46)

  55828. * lazy-string-address:                   Lazy Strings In Guile.

  55829.                                                               (line  26)

  55830. * lazy-string-encoding:                  Lazy Strings In Guile.

  55831.                                                               (line  34)

  55832. * lazy-string-length:                    Lazy Strings In Guile.

  55833.                                                               (line  29)

  55834. * lazy-string-type:                      Lazy Strings In Guile.

  55835.                                                               (line  40)

  55836. * lazy-string?:                          Lazy Strings In Guile.

  55837.                                                               (line  22)

  55838. * LazyString.address:                    Lazy Strings In Python.

  55839.                                                               (line  26)

  55840. * LazyString.encoding:                   Lazy Strings In Python.

  55841.                                                               (line  36)

  55842. * LazyString.length:                     Lazy Strings In Python.

  55843.                                                               (line  30)

  55844. * LazyString.type:                       Lazy Strings In Python.

  55845.                                                               (line  43)

  55846. * LazyString.value:                      Lazy Strings In Python.

  55847.                                                               (line  20)

  55848. * Left:                                  TUI Keys.            (line  73)

  55849. * LineTable.has_line:                    Line Tables In Python.

  55850.                                                               (line  57)

  55851. * LineTable.line:                        Line Tables In Python.

  55852.                                                               (line  51)

  55853. * LineTable.source_lines:                Line Tables In Python.

  55854.                                                               (line  62)

  55855. * LineTableEntry.line:                   Line Tables In Python.

  55856.                                                               (line  16)

  55857. * LineTableEntry.pc:                     Line Tables In Python.

  55858.                                                               (line  21)

  55859. * list:                                  List.                (line   6)

  55860. * list, and Objective-C:                 Method Names in Commands.

  55861.                                                               (line   9)

  55862. * load FILENAME OFFSET:                  Target Commands.     (line 114)

  55863. * lookup-block:                          Blocks In Guile.     (line 117)

  55864. * lookup-global-symbol:                  Symbols In Guile.    (line  99)

  55865. * lookup-symbol:                         Symbols In Guile.    (line  79)

  55866. * lookup-type:                           Types In Guile.      (line  15)

  55867. * loop_break:                            Command Files.       (line  93)

  55868. * loop_continue:                         Command Files.       (line  97)

  55869. * macro define:                          Macros.              (line  59)

  55870. * macro exp1:                            Macros.              (line  36)

  55871. * macro expand:                          Macros.              (line  29)

  55872. * macro list:                            Macros.              (line  80)

  55873. * macro undef:                           Macros.              (line  74)

  55874. * maint ada set ignore-descriptive-types: Ada Glitches.       (line  73)

  55875. * maint ada show ignore-descriptive-types: Ada Glitches.      (line  77)

  55876. * maint agent:                           Maintenance Commands.

  55877.                                                               (line  11)

  55878. * maint agent-eval:                      Maintenance Commands.

  55879.                                                               (line  11)

  55880. * maint agent-printf:                    Maintenance Commands.

  55881.                                                               (line  26)

  55882. * maint btrace clear:                    Maintenance Commands.

  55883.                                                               (line  99)

  55884. * maint btrace clear-packet-history:     Maintenance Commands.

  55885.                                                               (line  94)

  55886. * maint btrace packet-history:           Maintenance Commands.

  55887.                                                               (line  65)

  55888. * maint check libthread-db:              Maintenance Commands.

  55889.                                                               (line 252)

  55890. * maint check xml-descriptions:          Maintenance Commands.

  55891.                                                               (line 248)

  55892. * maint check-psymtabs:                  Maintenance Commands.

  55893.                                                               (line 134)

  55894. * maint check-symtabs:                   Maintenance Commands.

  55895.                                                               (line 139)

  55896. * maint cplus first_component:           Maintenance Commands.

  55897.                                                               (line 154)

  55898. * maint cplus namespace:                 Maintenance Commands.

  55899.                                                               (line 157)

  55900. * maint demangler-warning:               Maintenance Commands.

  55901.                                                               (line 173)

  55902. * maint deprecate:                       Maintenance Commands.

  55903.                                                               (line 160)

  55904. * maint dump-me:                         Maintenance Commands.

  55905.                                                               (line 168)

  55906. * maint expand-symtabs:                  Maintenance Commands.

  55907.                                                               (line 142)

  55908. * maint flush-symbol-cache:              Symbols.             (line 714)

  55909. * maint info bdccsr, S12Z:               S12Z.                (line  10)

  55910. * maint info bfds:                       File Caching.        (line  10)

  55911. * maint info breakpoints:                Maintenance Commands.

  55912.                                                               (line  32)

  55913. * maint info btrace:                     Maintenance Commands.

  55914.                                                               (line  62)

  55915. * maint info line-table:                 Symbols.             (line 692)

  55916. * maint info program-spaces:             Inferiors Connections and Programs.

  55917.                                                               (line 191)

  55918. * maint info psymtabs:                   Symbols.             (line 645)

  55919. * maint info sections:                   Files.               (line 220)

  55920. * maint info selftests:                  Maintenance Commands.

  55921.                                                               (line 380)

  55922. * maint info sol-threads:                Threads.             (line 167)

  55923. * maint info symtabs:                    Symbols.             (line 645)

  55924. * maint internal-error:                  Maintenance Commands.

  55925.                                                               (line 173)

  55926. * maint internal-warning:                Maintenance Commands.

  55927.                                                               (line 173)

  55928. * maint packet:                          Maintenance Commands.

  55929.                                                               (line 220)

  55930. * maint print arc arc-instruction:       ARC.                 (line  17)

  55931. * maint print architecture:              Maintenance Commands.

  55932.                                                               (line 226)

  55933. * maint print c-tdesc [FILE]:            Maintenance Commands.

  55934.                                                               (line 230)

  55935. * maint print cooked-registers:          Maintenance Commands.

  55936.                                                               (line 282)

  55937. * maint print core-file-backed-mappings: Maintenance Commands.

  55938.                                                               (line 260)

  55939. * maint print dummy-frames:              Maintenance Commands.

  55940.                                                               (line 266)

  55941. * maint print msymbols:                  Symbols.             (line 619)

  55942. * maint print objfiles:                  Maintenance Commands.

  55943.                                                               (line 320)

  55944. * maint print psymbols:                  Symbols.             (line 619)

  55945. * maint print raw-registers:             Maintenance Commands.

  55946.                                                               (line 282)

  55947. * maint print reggroups:                 Maintenance Commands.

  55948.                                                               (line 301)

  55949. * maint print register-groups:           Maintenance Commands.

  55950.                                                               (line 282)

  55951. * maint print registers:                 Maintenance Commands.

  55952.                                                               (line 282)

  55953. * maint print remote-registers:          Maintenance Commands.

  55954.                                                               (line 282)

  55955. * maint print section-scripts:           Maintenance Commands.

  55956.                                                               (line 335)

  55957. * maint print statistics:                Maintenance Commands.

  55958.                                                               (line 342)

  55959. * maint print symbol-cache:              Symbols.             (line 706)

  55960. * maint print symbol-cache-statistics:   Symbols.             (line 710)

  55961. * maint print symbols:                   Symbols.             (line 619)

  55962. * maint print target-stack:              Maintenance Commands.

  55963.                                                               (line 355)

  55964. * maint print type:                      Maintenance Commands.

  55965.                                                               (line 367)

  55966. * maint print unwind, HPPA:              HPPA.                (line  17)

  55967. * maint print user-registers:            Maintenance Commands.

  55968.                                                               (line 326)

  55969. * maint print xml-tdesc:                 Maintenance Commands.

  55970.                                                               (line 240)

  55971. * maint selftest:                        Maintenance Commands.

  55972.                                                               (line 374)

  55973. * maint set bfd-sharing:                 File Caching.        (line  14)

  55974. * maint set btrace pt skip-pad:          Maintenance Commands.

  55975.                                                               (line 107)

  55976. * maint set catch-demangler-crashes:     Maintenance Commands.

  55977.                                                               (line 146)

  55978. * maint set check-libthread-db:          Maintenance Commands.

  55979.                                                               (line 560)

  55980. * maint set demangler-warning:           Maintenance Commands.

  55981.                                                               (line 197)

  55982. * maint set dwarf always-disassemble:    Maintenance Commands.

  55983.                                                               (line 383)

  55984. * maint set dwarf max-cache-age:         Maintenance Commands.

  55985.                                                               (line 404)

  55986. * maint set dwarf unwinders:             Maintenance Commands.

  55987.                                                               (line 418)

  55988. * maint set internal-error:              Maintenance Commands.

  55989.                                                               (line 197)

  55990. * maint set internal-warning:            Maintenance Commands.

  55991.                                                               (line 197)

  55992. * maint set per-command:                 Maintenance Commands.

  55993.                                                               (line 521)

  55994. * maint set profile:                     Maintenance Commands.

  55995.                                                               (line 452)

  55996. * maint set show-all-tib:                Maintenance Commands.

  55997.                                                               (line 476)

  55998. * maint set show-debug-regs:             Maintenance Commands.

  55999.                                                               (line 468)

  56000. * maint set symbol-cache-size:           Symbols.             (line 698)

  56001. * maint set target-async:                Maintenance Commands.

  56002.                                                               (line 482)

  56003. * maint set target-non-stop MODE [on|off|auto]: Maintenance Commands.

  56004.                                                               (line 490)

  56005. * maint set test-settings:               Maintenance Commands.

  56006.                                                               (line 609)

  56007. * maint set tui-resize-message:          Maintenance Commands.

  56008.                                                               (line 510)

  56009. * maint set worker-threads:              Maintenance Commands.

  56010.                                                               (line 441)

  56011. * maint show bfd-sharing:                File Caching.        (line  14)

  56012. * maint show btrace pt skip-pad:         Maintenance Commands.

  56013.                                                               (line 108)

  56014. * maint show catch-demangler-crashes:    Maintenance Commands.

  56015.                                                               (line 146)

  56016. * maint show check-libthread-db:         Maintenance Commands.

  56017.                                                               (line 560)

  56018. * maint show demangler-warning:          Maintenance Commands.

  56019.                                                               (line 197)

  56020. * maint show dwarf always-disassemble:   Maintenance Commands.

  56021.                                                               (line 383)

  56022. * maint show dwarf max-cache-age:        Maintenance Commands.

  56023.                                                               (line 404)

  56024. * maint show dwarf unwinders:            Maintenance Commands.

  56025.                                                               (line 418)

  56026. * maint show internal-error:             Maintenance Commands.

  56027.                                                               (line 197)

  56028. * maint show internal-warning:           Maintenance Commands.

  56029.                                                               (line 197)

  56030. * maint show per-command:                Maintenance Commands.

  56031.                                                               (line 521)

  56032. * maint show profile:                    Maintenance Commands.

  56033.                                                               (line 452)

  56034. * maint show show-all-tib:               Maintenance Commands.

  56035.                                                               (line 476)

  56036. * maint show show-debug-regs:            Maintenance Commands.

  56037.                                                               (line 468)

  56038. * maint show symbol-cache-size:          Symbols.             (line 703)

  56039. * maint show target-async:               Maintenance Commands.

  56040.                                                               (line 482)

  56041. * maint show target-non-stop:            Maintenance Commands.

  56042.                                                               (line 490)

  56043. * maint show test-options-completion-result: Maintenance Commands.

  56044.                                                               (line 604)

  56045. * maint show test-settings:              Maintenance Commands.

  56046.                                                               (line 609)

  56047. * maint show tui-resize-message:         Maintenance Commands.

  56048.                                                               (line 510)

  56049. * maint show worker-threads:             Maintenance Commands.

  56050.                                                               (line 441)

  56051. * maint space:                           Maintenance Commands.

  56052.                                                               (line 569)

  56053. * maint test-options:                    Maintenance Commands.

  56054.                                                               (line 590)

  56055. * maint time:                            Maintenance Commands.

  56056.                                                               (line 573)

  56057. * maint translate-address:               Maintenance Commands.

  56058.                                                               (line 577)

  56059. * maint undeprecate:                     Maintenance Commands.

  56060.                                                               (line 160)

  56061. * maint with:                            Maintenance Commands.

  56062.                                                               (line 615)

  56063. * make:                                  Shell Commands.      (line  22)

  56064. * make-block-symbols-iterator:           Blocks In Guile.     (line 105)

  56065. * make-breakpoint:                       Breakpoints In Guile.

  56066.                                                               (line  19)

  56067. * make-enum-hashtable:                   Guile Types Module.  (line  37)

  56068. * make-exception:                        Guile Exception Handling.

  56069.                                                               (line  91)

  56070. * make-field-iterator:                   Types In Guile.      (line 125)

  56071. * make-iterator:                         Iterators In Guile.  (line  11)

  56072. * make-lazy-value:                       Values From Inferior In Guile.

  56073.                                                               (line 327)

  56074. * make-list-iterator:                    Iterators In Guile.  (line  80)

  56075. * make-pretty-printer:                   Guile Pretty Printing API.

  56076.                                                               (line  15)

  56077. * make-pretty-printer-worker:            Guile Pretty Printing API.

  56078.                                                               (line  42)

  56079. * make-value:                            Values From Inferior In Guile.

  56080.                                                               (line  45)

  56081. * mark-modified-lines:                   Readline Init File Syntax.

  56082.                                                               (line 229)

  56083. * mark-symlinked-directories:            Readline Init File Syntax.

  56084.                                                               (line 234)

  56085. * match-hidden-files:                    Readline Init File Syntax.

  56086.                                                               (line 239)

  56087. * may-insert-breakpoints:                Observer Mode.       (line  50)

  56088. * may-insert-fast-tracepoints:           Observer Mode.       (line  69)

  56089. * may-insert-tracepoints:                Observer Mode.       (line  59)

  56090. * may-interrupt:                         Observer Mode.       (line  79)

  56091. * may-write-memory:                      Observer Mode.       (line  41)

  56092. * may-write-registers:                   Observer Mode.       (line  32)

  56093. * mem:                                   Memory Region Attributes.

  56094.                                                               (line  22)

  56095. * memory-port-range:                     Memory Ports in Guile.

  56096.                                                               (line  33)

  56097. * memory-port-read-buffer-size:          Memory Ports in Guile.

  56098.                                                               (line  37)

  56099. * memory-port-write-buffer-size:         Memory Ports in Guile.

  56100.                                                               (line  52)

  56101. * memory-port?:                          Memory Ports in Guile.

  56102.                                                               (line  29)

  56103. * MemoryChangedEvent.address:            Events In Python.    (line 162)

  56104. * MemoryChangedEvent.length:             Events In Python.    (line 165)

  56105. * memset:                                Bootstrapping.       (line  70)

  56106. * menu-complete ():                      Commands For Completion.

  56107.                                                               (line  22)

  56108. * menu-complete-backward ():             Commands For Completion.

  56109.                                                               (line  34)

  56110. * menu-complete-display-prefix:          Readline Init File Syntax.

  56111.                                                               (line 246)

  56112. * meta-flag:                             Readline Init File Syntax.

  56113.                                                               (line 184)

  56114. * methods:                               Xmethod API.         (line  22)

  56115. * monitor:                               Connecting.          (line 279)

  56116. * n (next):                              Continuing and Stepping.

  56117.                                                               (line  77)

  56118. * n (SingleKey TUI key):                 TUI Single Key Mode. (line  19)

  56119. * name:                                  Xmethod API.         (line  15)

  56120. * name of type_printer:                  Type Printing API.   (line  18)

  56121. * new-ui:                                Interpreters.        (line  68)

  56122. * newest-frame:                          Frames In Guile.     (line 160)

  56123. * NewInferiorEvent.inferior:             Events In Python.    (line 204)

  56124. * NewInferiorEvent.inferior <1>:         Events In Python.    (line 215)

  56125. * NewObjFileEvent.new_objfile:           Events In Python.    (line 115)

  56126. * NewThreadEvent.inferior_thread:        Events In Python.    (line 223)

  56127. * next:                                  Continuing and Stepping.

  56128.                                                               (line  77)

  56129. * next&:                                 Background Execution.

  56130.                                                               (line  34)

  56131. * next-history (C-n):                    Commands For History.

  56132.                                                               (line  16)

  56133. * next-screen-line ():                   Commands For Moving. (line  33)

  56134. * nexti:                                 Continuing and Stepping.

  56135.                                                               (line 209)

  56136. * nexti&:                                Background Execution.

  56137.                                                               (line  37)

  56138. * ni (nexti):                            Continuing and Stepping.

  56139.                                                               (line 209)

  56140. * non-incremental-forward-search-history (M-n): Commands For History.

  56141.                                                               (line  40)

  56142. * non-incremental-reverse-search-history (M-p): Commands For History.

  56143.                                                               (line  34)

  56144. * nosharedlibrary:                       Files.               (line 348)

  56145. * o (SingleKey TUI key):                 TUI Single Key Mode. (line  22)

  56146. * Objfile:                               Objfiles In Python.  (line   6)

  56147. * objfile-filename:                      Objfiles In Guile.   (line  28)

  56148. * objfile-pretty-printers:               Objfiles In Guile.   (line  36)

  56149. * objfile-progspace:                     Objfiles In Guile.   (line  32)

  56150. * objfile-valid?:                        Objfiles In Guile.   (line  21)

  56151. * Objfile.add_separate_debug_file:       Objfiles In Python.  (line 127)

  56152. * Objfile.build_id:                      Objfiles In Python.  (line  69)

  56153. * Objfile.filename:                      Objfiles In Python.  (line  49)

  56154. * Objfile.frame_filters:                 Objfiles In Python.  (line  95)

  56155. * Objfile.is_valid:                      Objfiles In Python.  (line 120)

  56156. * Objfile.lookup_global_symbol:          Objfiles In Python.  (line 136)

  56157. * Objfile.lookup_static_symbol:          Objfiles In Python.  (line 147)

  56158. * Objfile.owner:                         Objfiles In Python.  (line  62)

  56159. * Objfile.pretty_printers:               Objfiles In Python.  (line  83)

  56160. * Objfile.progspace:                     Objfiles In Python.  (line  79)

  56161. * Objfile.type_printers:                 Objfiles In Python.  (line  91)

  56162. * Objfile.username:                      Objfiles In Python.  (line  56)

  56163. * objfile?:                              Objfiles In Guile.   (line  17)

  56164. * objfiles:                              Objfiles In Guile.   (line  52)

  56165. * observer:                              Observer Mode.       (line  22)

  56166. * open-memory:                           Memory Ports in Guile.

  56167.                                                               (line  11)

  56168. * output:                                Output.              (line  35)

  56169. * output-meta:                           Readline Init File Syntax.

  56170.                                                               (line 251)

  56171. * output-port:                           I/O Ports in Guile.  (line   9)

  56172. * overlay:                               Overlay Commands.    (line  17)

  56173. * overload-choice annotation:            Prompting.           (line  32)

  56174. * overwrite-mode ():                     Commands For Text.   (line  68)

  56175. * page-completions:                      Readline Init File Syntax.

  56176.                                                               (line 257)

  56177. * Parameter:                             Parameters In Python.

  56178.                                                               (line   6)

  56179. * Parameter <1>:                         Parameters In Guile. (line   6)

  56180. * parameter-value:                       Parameters In Guile. (line 103)

  56181. * Parameter.get_set_string:              Parameters In Python.

  56182.                                                               (line  73)

  56183. * Parameter.get_show_string:             Parameters In Python.

  56184.                                                               (line 102)

  56185. * Parameter.set_doc:                     Parameters In Python.

  56186.                                                               (line  53)

  56187. * Parameter.show_doc:                    Parameters In Python.

  56188.                                                               (line  59)

  56189. * Parameter.value:                       Parameters In Python.

  56190.                                                               (line  65)

  56191. * Parameter.__init__:                    Parameters In Python.

  56192.                                                               (line  18)

  56193. * parameter?:                            Parameters In Guile. (line  99)

  56194. * PARAM_AUTO_BOOLEAN:                    Parameters In Python.

  56195.                                                               (line 116)

  56196. * PARAM_AUTO_BOOLEAN <1>:                Parameters In Guile. (line 120)

  56197. * PARAM_BOOLEAN:                         Parameters In Python.

  56198.                                                               (line 112)

  56199. * PARAM_BOOLEAN <1>:                     Parameters In Guile. (line 116)

  56200. * PARAM_ENUM:                            Parameters In Python.

  56201.                                                               (line 160)

  56202. * PARAM_ENUM <1>:                        Parameters In Guile. (line 156)

  56203. * PARAM_FILENAME:                        Parameters In Python.

  56204.                                                               (line 142)

  56205. * PARAM_FILENAME <1>:                    Parameters In Guile. (line 152)

  56206. * PARAM_INTEGER:                         Parameters In Python.

  56207.                                                               (line 125)

  56208. * PARAM_OPTIONAL_FILENAME:               Parameters In Python.

  56209.                                                               (line 139)

  56210. * PARAM_OPTIONAL_FILENAME <1>:           Parameters In Guile. (line 149)

  56211. * PARAM_STRING:                          Parameters In Python.

  56212.                                                               (line 129)

  56213. * PARAM_STRING <1>:                      Parameters In Guile. (line 139)

  56214. * PARAM_STRING_NOESCAPE:                 Parameters In Python.

  56215.                                                               (line 135)

  56216. * PARAM_STRING_NOESCAPE <1>:             Parameters In Guile. (line 145)

  56217. * PARAM_UINTEGER:                        Parameters In Python.

  56218.                                                               (line 121)

  56219. * PARAM_UINTEGER <1>:                    Parameters In Guile. (line 125)

  56220. * PARAM_ZINTEGER:                        Parameters In Python.

  56221.                                                               (line 146)

  56222. * PARAM_ZINTEGER <1>:                    Parameters In Guile. (line 129)

  56223. * PARAM_ZUINTEGER:                       Parameters In Python.

  56224.                                                               (line 150)

  56225. * PARAM_ZUINTEGER <1>:                   Parameters In Guile. (line 132)

  56226. * PARAM_ZUINTEGER_UNLIMITED:             Parameters In Python.

  56227.                                                               (line 155)

  56228. * PARAM_ZUINTEGER_UNLIMITED <1>:         Parameters In Guile. (line 135)

  56229. * parse-and-eval:                        Basic Guile.         (line 113)

  56230. * passcount:                             Tracepoint Passcounts.

  56231.                                                               (line   6)

  56232. * path:                                  Environment.         (line  14)

  56233. * pending-breakpoints:                   GDB/MI Support Commands.

  56234.                                                               (line  79)

  56235. * PendingFrame.architecture:             Unwinding Frames in Python.

  56236.                                                               (line  99)

  56237. * PendingFrame.create_unwind_info:       Unwinding Frames in Python.

  56238.                                                               (line  66)

  56239. * PendingFrame.read_register:            Unwinding Frames in Python.

  56240.                                                               (line  42)

  56241. * PgDn:                                  TUI Keys.            (line  64)

  56242. * PgUp:                                  TUI Keys.            (line  61)

  56243. * pi:                                    Python Commands.     (line   9)

  56244. * pipe:                                  Shell Commands.      (line  26)

  56245. * po (print-object):                     The Print Command with Objective-C.

  56246.                                                               (line   6)

  56247. * possible-completions (M-?):            Commands For Completion.

  56248.                                                               (line  11)

  56249. * post-commands annotation:              Prompting.           (line  27)

  56250. * post-overload-choice annotation:       Prompting.           (line  32)

  56251. * post-prompt annotation:                Prompting.           (line  24)

  56252. * post-prompt-for-continue annotation:   Prompting.           (line  40)

  56253. * post-query annotation:                 Prompting.           (line  36)

  56254. * pre-commands annotation:               Prompting.           (line  27)

  56255. * pre-overload-choice annotation:        Prompting.           (line  32)

  56256. * pre-prompt annotation:                 Prompting.           (line  24)

  56257. * pre-prompt-for-continue annotation:    Prompting.           (line  40)

  56258. * pre-query annotation:                  Prompting.           (line  36)

  56259. * prefix-meta (<ESC>):                   Miscellaneous Commands.

  56260.                                                               (line  19)

  56261. * prepend-pretty-printer!:               Guile Printing Module.

  56262.                                                               (line  13)

  56263. * pretty-printer-enabled?:               Guile Pretty Printing API.

  56264.                                                               (line  28)

  56265. * pretty-printer?:                       Guile Pretty Printing API.

  56266.                                                               (line  24)

  56267. * pretty-printers:                       Guile Pretty Printing API.

  56268.                                                               (line  35)

  56269. * pretty_printer.children:               Pretty Printing API. (line  10)

  56270. * pretty_printer.display_hint:           Pretty Printing API. (line  32)

  56271. * pretty_printer.to_string:              Pretty Printing API. (line  64)

  56272. * previous-history (C-p):                Commands For History.

  56273.                                                               (line  12)

  56274. * previous-screen-line ():               Commands For Moving. (line  26)

  56275. * print:                                 Data.                (line   6)

  56276. * print-last-kbd-macro ():               Keyboard Macros.     (line  17)

  56277. * print-object:                          The Print Command with Objective-C.

  56278.                                                               (line   6)

  56279. * printf:                                Output.              (line  46)

  56280. * proc-trace-entry:                      Process Information. (line 123)

  56281. * proc-trace-exit:                       Process Information. (line 123)

  56282. * proc-untrace-entry:                    Process Information. (line 123)

  56283. * proc-untrace-exit:                     Process Information. (line 123)

  56284. * Progspace:                             Progspaces In Python.

  56285.                                                               (line   6)

  56286. * progspace-filename:                    Progspaces In Guile. (line  34)

  56287. * progspace-objfiles:                    Progspaces In Guile. (line  44)

  56288. * progspace-pretty-printers:             Progspaces In Guile. (line  52)

  56289. * progspace-valid?:                      Progspaces In Guile. (line  21)

  56290. * Progspace.block_for_pc:                Progspaces In Python.

  56291.                                                               (line  47)

  56292. * Progspace.block_for_pc <1>:            Progspaces In Python.

  56293.                                                               (line  47)

  56294. * Progspace.filename:                    Progspaces In Python.

  56295.                                                               (line  26)

  56296. * Progspace.find_pc_line:                Progspaces In Python.

  56297.                                                               (line  52)

  56298. * Progspace.find_pc_line <1>:            Progspaces In Python.

  56299.                                                               (line  52)

  56300. * Progspace.frame_filters:               Progspaces In Python.

  56301.                                                               (line  41)

  56302. * Progspace.is_valid:                    Progspaces In Python.

  56303.                                                               (line  59)

  56304. * Progspace.is_valid <1>:                Progspaces In Python.

  56305.                                                               (line  59)

  56306. * Progspace.objfiles:                    Progspaces In Python.

  56307.                                                               (line  66)

  56308. * Progspace.objfiles <1>:                Progspaces In Python.

  56309.                                                               (line  66)

  56310. * Progspace.pretty_printers:             Progspaces In Python.

  56311.                                                               (line  29)

  56312. * Progspace.solib_name:                  Progspaces In Python.

  56313.                                                               (line  70)

  56314. * Progspace.solib_name <1>:              Progspaces In Python.

  56315.                                                               (line  70)

  56316. * Progspace.type_printers:               Progspaces In Python.

  56317.                                                               (line  37)

  56318. * progspace?:                            Progspaces In Guile. (line  17)

  56319. * progspaces:                            Progspaces In Guile. (line  31)

  56320. * prompt annotation:                     Prompting.           (line  24)

  56321. * prompt-for-continue annotation:        Prompting.           (line  40)

  56322. * ptype:                                 Symbols.             (line 298)

  56323. * putDebugChar:                          Bootstrapping.       (line  20)

  56324. * pwd:                                   Working Directory.   (line  40)

  56325. * py:                                    Python Commands.     (line  23)

  56326. * python:                                GDB/MI Support Commands.

  56327.                                                               (line  82)

  56328. * python <1>:                            Python Commands.     (line  23)

  56329. * python-interactive:                    Python Commands.     (line   9)

  56330. * q (quit):                              Quitting GDB.        (line   6)

  56331. * q (SingleKey TUI key):                 TUI Single Key Mode. (line  25)

  56332. * query annotation:                      Prompting.           (line  36)

  56333. * queue-signal:                          Signaling.           (line  36)

  56334. * quit annotation:                       Errors.              (line   6)

  56335. * quit [EXPRESSION]:                     Quitting GDB.        (line   6)

  56336. * quoted-insert (C-q or C-v):            Commands For Text.   (line  26)

  56337. * r (run):                               Starting.            (line   6)

  56338. * r (SingleKey TUI key):                 TUI Single Key Mode. (line  28)

  56339. * rbreak:                                Set Breaks.          (line  90)

  56340. * rc (reverse-continue):                 Reverse Execution.   (line  36)

  56341. * re-read-init-file (C-x C-r):           Miscellaneous Commands.

  56342.                                                               (line   6)

  56343. * readnow:                               Files.               (line  94)

  56344. * rec:                                   Process Record and Replay.

  56345.                                                               (line  43)

  56346. * rec btrace:                            Process Record and Replay.

  56347.                                                               (line  43)

  56348. * rec btrace bts:                        Process Record and Replay.

  56349.                                                               (line  43)

  56350. * rec btrace pt:                         Process Record and Replay.

  56351.                                                               (line  43)

  56352. * rec bts:                               Process Record and Replay.

  56353.                                                               (line  43)

  56354. * rec del:                               Process Record and Replay.

  56355.                                                               (line 357)

  56356. * rec full:                              Process Record and Replay.

  56357.                                                               (line  43)

  56358. * rec function-call-history:             Process Record and Replay.

  56359.                                                               (line 423)

  56360. * rec instruction-history:               Process Record and Replay.

  56361.                                                               (line 363)

  56362. * rec pt:                                Process Record and Replay.

  56363.                                                               (line  43)

  56364. * rec s:                                 Process Record and Replay.

  56365.                                                               (line 106)

  56366. * recognize on type_recognizer:          Type Printing API.   (line  42)

  56367. * record:                                Process Record and Replay.

  56368.                                                               (line  43)

  56369. * record btrace:                         Process Record and Replay.

  56370.                                                               (line  43)

  56371. * record btrace bts:                     Process Record and Replay.

  56372.                                                               (line  43)

  56373. * record btrace pt:                      Process Record and Replay.

  56374.                                                               (line  43)

  56375. * record bts:                            Process Record and Replay.

  56376.                                                               (line  43)

  56377. * record delete:                         Process Record and Replay.

  56378.                                                               (line 357)

  56379. * record full:                           Process Record and Replay.

  56380.                                                               (line  43)

  56381. * record function-call-history:          Process Record and Replay.

  56382.                                                               (line 423)

  56383. * record goto:                           Process Record and Replay.

  56384.                                                               (line 129)

  56385. * record instruction-history:            Process Record and Replay.

  56386.                                                               (line 363)

  56387. * record pt:                             Process Record and Replay.

  56388.                                                               (line  43)

  56389. * record restore:                        Process Record and Replay.

  56390.                                                               (line 150)

  56391. * record save:                           Process Record and Replay.

  56392.                                                               (line 143)

  56393. * record stop:                           Process Record and Replay.

  56394.                                                               (line 106)

  56395. * Record.begin:                          Recordings In Python.

  56396.                                                               (line  40)

  56397. * Record.end:                            Recordings In Python.

  56398.                                                               (line  44)

  56399. * Record.format:                         Recordings In Python.

  56400.                                                               (line  36)

  56401. * Record.function_call_history:          Recordings In Python.

  56402.                                                               (line  55)

  56403. * Record.goto:                           Recordings In Python.

  56404.                                                               (line  60)

  56405. * Record.instruction_history:            Recordings In Python.

  56406.                                                               (line  52)

  56407. * Record.method:                         Recordings In Python.

  56408.                                                               (line  32)

  56409. * Record.replay_position:                Recordings In Python.

  56410.                                                               (line  48)

  56411. * RecordFunctionSegment.instructions:    Recordings In Python.

  56412.                                                               (line 126)

  56413. * RecordFunctionSegment.level:           Recordings In Python.

  56414.                                                               (line 122)

  56415. * RecordFunctionSegment.next:            Recordings In Python.

  56416.                                                               (line 140)

  56417. * RecordFunctionSegment.number:          Recordings In Python.

  56418.                                                               (line 113)

  56419. * RecordFunctionSegment.prev:            Recordings In Python.

  56420.                                                               (line 136)

  56421. * RecordFunctionSegment.symbol:          Recordings In Python.

  56422.                                                               (line 118)

  56423. * RecordFunctionSegment.up:              Recordings In Python.

  56424.                                                               (line 130)

  56425. * RecordGap.error_code:                  Recordings In Python.

  56426.                                                               (line 104)

  56427. * RecordGap.error_string:                Recordings In Python.

  56428.                                                               (line 108)

  56429. * RecordGap.number:                      Recordings In Python.

  56430.                                                               (line  99)

  56431. * RecordInstruction.is_speculative:      Recordings In Python.

  56432.                                                               (line  91)

  56433. * RecordInstruction.number:              Recordings In Python.

  56434.                                                               (line  81)

  56435. * RecordInstruction.sal:                 Recordings In Python.

  56436.                                                               (line  86)

  56437. * redraw-current-line ():                Commands For Moving. (line  44)

  56438. * refresh:                               TUI Commands.        (line 125)

  56439. * register-breakpoint!:                  Breakpoints In Guile.

  56440.                                                               (line  87)

  56441. * register-command!:                     Commands In Guile.   (line  58)

  56442. * register-parameter!:                   Parameters In Guile. (line  94)

  56443. * RegisterChangedEvent.frame:            Events In Python.    (line 172)

  56444. * RegisterChangedEvent.regnum:           Events In Python.    (line 175)

  56445. * RegisterDescriptor.name:               Registers In Python. (line  19)

  56446. * RegisterDescriptorIterator.find:       Registers In Python. (line  25)

  56447. * RegisterGroup.name:                    Registers In Python. (line  48)

  56448. * register_xmethod_matcher:              Xmethod API.         (line  82)

  56449. * remote delete:                         File Transfer.       (line  23)

  56450. * remote get:                            File Transfer.       (line  19)

  56451. * remote put:                            File Transfer.       (line  15)

  56452. * remove-inferiors:                      Inferiors Connections and Programs.

  56453.                                                               (line 138)

  56454. * remove-symbol-file:                    Files.               (line 174)

  56455. * restart CHECKPOINT-ID:                 Checkpoint/Restart.  (line  41)

  56456. * restore:                               Dump/Restore Files.  (line  40)

  56457. * RET (repeat last command):             Command Syntax.      (line  21)

  56458. * return:                                Returning.           (line   6)

  56459. * reverse-continue:                      Reverse Execution.   (line  36)

  56460. * reverse-finish:                        Reverse Execution.   (line  83)

  56461. * reverse-next:                          Reverse Execution.   (line  66)

  56462. * reverse-nexti:                         Reverse Execution.   (line  75)

  56463. * reverse-search:                        Search.              (line  16)

  56464. * reverse-search-history (C-r):          Commands For History.

  56465.                                                               (line  26)

  56466. * reverse-step:                          Reverse Execution.   (line  43)

  56467. * reverse-stepi:                         Reverse Execution.   (line  58)

  56468. * revert-all-at-newline:                 Readline Init File Syntax.

  56469.                                                               (line 267)

  56470. * revert-line (M-r):                     Miscellaneous Commands.

  56471.                                                               (line  26)

  56472. * Right:                                 TUI Keys.            (line  76)

  56473. * rn (reverse-next):                     Reverse Execution.   (line  66)

  56474. * rni (reverse-nexti):                   Reverse Execution.   (line  75)

  56475. * rs (step):                             Reverse Execution.   (line  43)

  56476. * rsi (reverse-stepi):                   Reverse Execution.   (line  58)

  56477. * run:                                   Starting.            (line   6)

  56478. * run&:                                  Background Execution.

  56479.                                                               (line  21)

  56480. * rwatch:                                Set Watchpoints.     (line  79)

  56481. * s (SingleKey TUI key):                 TUI Single Key Mode. (line  31)

  56482. * s (step):                              Continuing and Stepping.

  56483.                                                               (line  45)

  56484. * sal-last:                              Symbol Tables In Guile.

  56485.                                                               (line  68)

  56486. * sal-line:                              Symbol Tables In Guile.

  56487.                                                               (line  62)

  56488. * sal-pc:                                Symbol Tables In Guile.

  56489.                                                               (line  65)

  56490. * sal-symtab:                            Symbol Tables In Guile.

  56491.                                                               (line  59)

  56492. * sal-valid?:                            Symbol Tables In Guile.

  56493.                                                               (line  53)

  56494. * sal?:                                  Symbol Tables In Guile.

  56495.                                                               (line  49)

  56496. * save breakpoints:                      Save Breakpoints.    (line   9)

  56497. * save gdb-index:                        Index Files.         (line  30)

  56498. * save tracepoints:                      save tracepoints.    (line   6)

  56499. * save-tracepoints:                      save tracepoints.    (line   6)

  56500. * search:                                Search.              (line   9)

  56501. * section:                               Files.               (line 203)

  56502. * select-frame:                          Selection.           (line  98)

  56503. * selected-frame:                        Frames In Guile.     (line 156)

  56504. * self:                                  Commands In Guile.   (line 100)

  56505. * self-insert (a, b, A, 1, !, ...):      Commands For Text.   (line  33)

  56506. * set:                                   Help.                (line 138)

  56507. * set ada print-signatures:              Overloading support for Ada.

  56508.                                                               (line  31)

  56509. * set ada trust-PAD-over-XVS:            Ada Glitches.        (line  42)

  56510. * set agent off:                         In-Process Agent.    (line  47)

  56511. * set agent on:                          In-Process Agent.    (line  38)

  56512. * set annotate:                          Annotations Overview.

  56513.                                                               (line  29)

  56514. * set architecture:                      Targets.             (line  21)

  56515. * set args:                              Arguments.           (line  21)

  56516. * set arm:                               ARM.                 (line   9)

  56517. * set auto-connect-native-target:        Starting.            (line 168)

  56518. * set auto-load gdb-scripts:             Auto-loading sequences.

  56519.                                                               (line  13)

  56520. * set auto-load guile-scripts:           Guile Auto-loading.  (line  17)

  56521. * set auto-load libthread-db:            libthread_db.so.1 file.

  56522.                                                               (line  21)

  56523. * set auto-load local-gdbinit:           Init File in the Current Directory.

  56524.                                                               (line  14)

  56525. * set auto-load off:                     Auto-loading.        (line  32)

  56526. * set auto-load python-scripts:          Python Auto-loading. (line  17)

  56527. * set auto-load safe-path:               Auto-loading safe path.

  56528.                                                               (line  32)

  56529. * set auto-load scripts-directory:       objfile-gdbdotext file.

  56530.                                                               (line  41)

  56531. * set auto-solib-add:                    Files.               (line 307)

  56532. * set backtrace:                         Backtrace.           (line 166)

  56533. * set basenames-may-differ:              Files.               (line 536)

  56534. * set breakpoint always-inserted:        Set Breaks.          (line 325)

  56535. * set breakpoint auto-hw:                Set Breaks.          (line 305)

  56536. * set breakpoint condition-evaluation:   Set Breaks.          (line 346)

  56537. * set breakpoint pending:                Set Breaks.          (line 275)

  56538. * set can-use-hw-watchpoints:            Set Watchpoints.     (line 116)

  56539. * set case-sensitive:                    Symbols.             (line  27)

  56540. * set charset:                           Character Sets.      (line  46)

  56541. * set check range:                       Range Checking.      (line  34)

  56542. * set check type:                        Type Checking.       (line  35)

  56543. * set circular-trace-buffer:             Starting and Stopping Trace Experiments.

  56544.                                                               (line  93)

  56545. * set code-cache:                        Caching Target Data. (line  36)

  56546. * set coerce-float-to-double:            ABI.                 (line  45)

  56547. * set com1base:                          DJGPP Native.        (line 122)

  56548. * set com1irq:                           DJGPP Native.        (line 122)

  56549. * set com2base:                          DJGPP Native.        (line 122)

  56550. * set com2irq:                           DJGPP Native.        (line 122)

  56551. * set com3base:                          DJGPP Native.        (line 122)

  56552. * set com3irq:                           DJGPP Native.        (line 122)

  56553. * set com4base:                          DJGPP Native.        (line 122)

  56554. * set com4irq:                           DJGPP Native.        (line 122)

  56555. * set complaints:                        Messages/Warnings.   (line  29)

  56556. * set confirm:                           Messages/Warnings.   (line  49)

  56557. * set cp-abi:                            ABI.                 (line  57)

  56558. * set cwd:                               Working Directory.   (line  13)

  56559. * set cygwin-exceptions:                 Cygwin Native.       (line  60)

  56560. * set data-directory:                    Data Files.          (line  12)

  56561. * set dcache line-size:                  Caching Target Data. (line  60)

  56562. * set dcache size:                       Caching Target Data. (line  57)

  56563. * set debug:                             Debugging Output.    (line  17)

  56564. * set debug aarch64:                     AArch64.             (line  10)

  56565. * set debug arc:                         ARC.                 (line   9)

  56566. * set debug auto-load:                   Auto-loading verbose mode.

  56567.                                                               (line  27)

  56568. * set debug bfd-cache LEVEL:             File Caching.        (line  24)

  56569. * set debug darwin:                      Darwin.              (line   9)

  56570. * set debug entry-values:                Tail Call Frames.    (line  47)

  56571. * set debug hppa:                        HPPA.                (line  10)

  56572. * set debug libthread-db:                Threads.             (line 331)

  56573. * set debug mach-o:                      Darwin.              (line  16)

  56574. * set debug mips:                        MIPS.                (line 100)

  56575. * set debug monitor:                     Target Commands.     (line 107)

  56576. * set debug nios2:                       Nios II.             (line  10)

  56577. * set debug skip:                        Skipping Over Functions and Files.

  56578.                                                               (line 149)

  56579. * set debug-file-directory:              Separate Debug Files.

  56580.                                                               (line  70)

  56581. * set debugevents:                       Cygwin Native.       (line  89)

  56582. * set debugexceptions:                   Cygwin Native.       (line 100)

  56583. * set debugexec:                         Cygwin Native.       (line  96)

  56584. * set debugmemory:                       Cygwin Native.       (line 104)

  56585. * set default-collect:                   Tracepoint Actions.  (line 142)

  56586. * set demangle-style:                    Print Settings.      (line 529)

  56587. * set detach-on-fork:                    Forks.               (line  58)

  56588. * set directories:                       Source Path.         (line 178)

  56589. * set disable-randomization:             Starting.            (line 212)

  56590. * set disassemble-next-line:             Machine Code.        (line 249)

  56591. * set disassembler-options:              Machine Code.        (line 222)

  56592. * set disassembly-flavor:                Machine Code.        (line 237)

  56593. * set disconnected-dprintf:              Dynamic Printf.      (line  83)

  56594. * set disconnected-tracing:              Starting and Stopping Trace Experiments.

  56595.                                                               (line  55)

  56596. * set displaced-stepping:                Maintenance Commands.

  56597.                                                               (line 112)

  56598. * set dump-excluded-mappings:            Core File Generation.

  56599.                                                               (line  60)

  56600. * set editing:                           Editing.             (line  15)

  56601. * set endian:                            Byte Order.          (line  13)

  56602. * set environment:                       Environment.         (line  39)

  56603. * set exceptions, Hurd command:          Hurd Native.         (line  39)

  56604. * set exec-direction:                    Reverse Execution.   (line  89)

  56605. * set exec-done-display:                 Debugging Output.    (line  11)

  56606. * set exec-wrapper:                      Starting.            (line 120)

  56607. * set extended-prompt:                   Prompt.              (line  25)

  56608. * set extension-language:                Show.                (line  30)

  56609. * set follow-exec-mode:                  Forks.               (line 106)

  56610. * set follow-fork-mode:                  Forks.               (line  39)

  56611. * set frame-filter priority:             Frame Filter Management.

  56612.                                                               (line  84)

  56613. * set gnutarget:                         Target Commands.     (line  28)

  56614. * set guile print-stack:                 Guile Exception Handling.

  56615.                                                               (line   6)

  56616. * set hash, for remote monitors:         Target Commands.     (line  98)

  56617. * set height:                            Screen Size.         (line  22)

  56618. * set history expansion:                 Command History.     (line  97)

  56619. * set history filename:                  Command History.     (line  26)

  56620. * set history remove-duplicates:         Command History.     (line  69)

  56621. * set history save:                      Command History.     (line  44)

  56622. * set history size:                      Command History.     (line  56)

  56623. * set host-charset:                      Character Sets.      (line  33)

  56624. * set index-cache:                       Index Files.         (line  79)

  56625. * set inferior-tty:                      Input/Output.        (line  49)

  56626. * set input-radix:                       Numbers.             (line  14)

  56627. * set interactive-mode:                  Other Misc Settings. (line   6)

  56628. * set language:                          Manually.            (line   9)

  56629. * set libthread-db-search-path:          Threads.             (line 293)

  56630. * set listsize:                          List.                (line  33)

  56631. * set logging:                           Logging Output.      (line   9)

  56632. * set mach-exceptions:                   Darwin.              (line  27)

  56633. * set max-completions:                   Completion.          (line  70)

  56634. * set max-user-call-depth:               Define.              (line 128)

  56635. * set max-value-size:                    Value Sizes.         (line  12)

  56636. * set may-call-functions:                Calling.             (line  59)

  56637. * set mem inaccessible-by-default:       Memory Region Attributes.

  56638.                                                               (line 123)

  56639. * set mips abi:                          MIPS.                (line  32)

  56640. * set mips compression:                  MIPS.                (line  49)

  56641. * set mips mask-address:                 MIPS.                (line  80)

  56642. * set mipsfpu:                           MIPS Embedded.       (line  13)

  56643. * set mpx bound:                         i386.                (line  60)

  56644. * set multiple-symbols:                  Ambiguous Expressions.

  56645.                                                               (line  50)

  56646. * set new-console:                       Cygwin Native.       (line  72)

  56647. * set new-group:                         Cygwin Native.       (line  81)

  56648. * set non-stop:                          Non-Stop Mode.       (line  35)

  56649. * set opaque-type-resolution:            Symbols.             (line 582)

  56650. * set osabi:                             ABI.                 (line  11)

  56651. * set output-radix:                      Numbers.             (line  30)

  56652. * set overload-resolution:               Debugging C Plus Plus.

  56653.                                                               (line  59)

  56654. * set pagination:                        Screen Size.         (line  41)

  56655. * set powerpc:                           PowerPC Embedded.    (line  51)

  56656. * set print:                             Print Settings.      (line  11)

  56657. * set print entry-values:                Print Settings.      (line 214)

  56658. * set print finish:                      Continuing and Stepping.

  56659.                                                               (line 117)

  56660. * set print frame-arguments:             Print Settings.      (line 154)

  56661. * set print frame-info:                  Print Settings.      (line 314)

  56662. * set print inferior-events:             Inferiors Connections and Programs.

  56663.                                                               (line 169)

  56664. * set print symbol-loading:              Symbols.             (line 600)

  56665. * set print thread-events:               Threads.             (line 272)

  56666. * set print type methods:                Symbols.             (line  44)

  56667. * set print type nested-type-limit:      Symbols.             (line  57)

  56668. * set print type typedefs:               Symbols.             (line  68)

  56669. * set processor:                         Targets.             (line  31)

  56670. * set procfs-file:                       Process Information. (line 112)

  56671. * set procfs-trace:                      Process Information. (line 106)

  56672. * set prompt:                            Prompt.              (line  16)

  56673. * set python print-stack:                Python Commands.     (line  44)

  56674. * set radix:                             Numbers.             (line  43)

  56675. * set range-stepping:                    Continuing and Stepping.

  56676.                                                               (line 228)

  56677. * set ravenscar task-switching off:      Ravenscar Profile.   (line  14)

  56678. * set ravenscar task-switching on:       Ravenscar Profile.   (line  10)

  56679. * set record:                            Process Record and Replay.

  56680.                                                               (line 413)

  56681. * set record btrace:                     Process Record and Replay.

  56682.                                                               (line 204)

  56683. * set record btrace bts:                 Process Record and Replay.

  56684.                                                               (line 277)

  56685. * set record btrace pt:                  Process Record and Replay.

  56686.                                                               (line 300)

  56687. * set record full:                       Process Record and Replay.

  56688.                                                               (line 154)

  56689. * set remote:                            Remote Configuration.

  56690.                                                               (line   6)

  56691. * set remote system-call-allowed:        system.              (line  37)

  56692. * set remote-mips64-transfers-32bit-regs: MIPS.               (line  90)

  56693. * set remotecache:                       Caching Target Data. (line  20)

  56694. * set remoteflow:                        Remote Configuration.

  56695.                                                               (line  48)

  56696. * set schedule-multiple:                 All-Stop Mode.       (line  67)

  56697. * set script-extension:                  Extending GDB.       (line  29)

  56698. * set sh calling-convention:             Super-H.             (line   9)

  56699. * set shell:                             Cygwin Native.       (line 108)

  56700. * set signal-thread:                     Hurd Native.         (line  21)

  56701. * set signals, Hurd command:             Hurd Native.         (line  11)

  56702. * set sigs, Hurd command:                Hurd Native.         (line  11)

  56703. * set sigthread:                         Hurd Native.         (line  21)

  56704. * set solib-absolute-prefix:             Files.               (line 386)

  56705. * set solib-search-path:                 Files.               (line 462)

  56706. * set stack-cache:                       Caching Target Data. (line  28)

  56707. * set startup-with-shell:                Starting.            (line 145)

  56708. * set step-mode:                         Continuing and Stepping.

  56709.                                                               (line  91)

  56710. * set stop-on-solib-events:              Files.               (line 363)

  56711. * set stopped, Hurd command:             Hurd Native.         (line  31)

  56712. * set struct-convention:                 i386.                (line   7)

  56713. * set style:                             Output Styling.      (line   6)

  56714. * set substitute-path:                   Source Path.         (line 185)

  56715. * set sysroot:                           Files.               (line 386)

  56716. * set target-charset:                    Character Sets.      (line  28)

  56717. * set target-file-system-kind (unix|dos-based|auto): Files.   (line 476)

  56718. * set target-wide-charset:               Character Sets.      (line  61)

  56719. * set task, Hurd commands:               Hurd Native.         (line  48)

  56720. * set tcp:                               Remote Configuration.

  56721.                                                               (line 130)

  56722. * set thread, Hurd command:              Hurd Native.         (line  90)

  56723. * set trace-buffer-size:                 Starting and Stopping Trace Experiments.

  56724.                                                               (line 107)

  56725. * set trace-commands:                    Messages/Warnings.   (line  65)

  56726. * set trace-notes:                       Starting and Stopping Trace Experiments.

  56727.                                                               (line 126)

  56728. * set trace-stop-notes:                  Starting and Stopping Trace Experiments.

  56729.                                                               (line 132)

  56730. * set trace-user:                        Starting and Stopping Trace Experiments.

  56731.                                                               (line 122)

  56732. * set trust-readonly-sections:           Files.               (line 265)

  56733. * set tui active-border-mode:            TUI Configuration.   (line  24)

  56734. * set tui border-kind:                   TUI Configuration.   (line   9)

  56735. * set tui border-mode:                   TUI Configuration.   (line  23)

  56736. * set tui compact-source:                TUI Configuration.   (line  54)

  56737. * set tui tab-width:                     TUI Configuration.   (line  49)

  56738. * set unwind-on-terminating-exception:   Calling.             (line  47)

  56739. * set unwindonsignal:                    Calling.             (line  36)

  56740. * set use-coredump-filter:               Core File Generation.

  56741.                                                               (line  33)

  56742. * set variable:                          Assignment.          (line  16)

  56743. * set varsize-limit:                     Ada Settings.        (line   6)

  56744. * set verbose:                           Messages/Warnings.   (line  15)

  56745. * set watchdog:                          Maintenance Commands.

  56746.                                                               (line 624)

  56747. * set width:                             Screen Size.         (line  22)

  56748. * set write:                             Patching.            (line  15)

  56749. * set-breakpoint-condition!:             Breakpoints In Guile.

  56750.                                                               (line 198)

  56751. * set-breakpoint-enabled!:               Breakpoints In Guile.

  56752.                                                               (line 147)

  56753. * set-breakpoint-hit-count!:             Breakpoints In Guile.

  56754.                                                               (line 172)

  56755. * set-breakpoint-ignore-count!:          Breakpoints In Guile.

  56756.                                                               (line 166)

  56757. * set-breakpoint-silent!:                Breakpoints In Guile.

  56758.                                                               (line 158)

  56759. * set-breakpoint-stop!:                  Breakpoints In Guile.

  56760.                                                               (line 206)

  56761. * set-breakpoint-task!:                  Breakpoints In Guile.

  56762.                                                               (line 190)

  56763. * set-breakpoint-thread!:                Breakpoints In Guile.

  56764.                                                               (line 180)

  56765. * set-iterator-progress!:                Iterators In Guile.  (line  60)

  56766. * set-mark (C-@):                        Miscellaneous Commands.

  56767.                                                               (line  33)

  56768. * set-memory-port-read-buffer-size!:     Memory Ports in Guile.

  56769.                                                               (line  44)

  56770. * set-memory-port-write-buffer-size!:    Memory Ports in Guile.

  56771.                                                               (line  59)

  56772. * set-objfile-pretty-printers!:          Objfiles In Guile.   (line  40)

  56773. * set-parameter-value!:                  Parameters In Guile. (line 107)

  56774. * set-pretty-printer-enabled!:           Guile Pretty Printing API.

  56775.                                                               (line  31)

  56776. * set-pretty-printers!:                  Guile Pretty Printing API.

  56777.                                                               (line  38)

  56778. * set-progspace-pretty-printers!:        Progspaces In Guile. (line  57)

  56779. * set_debug_traps:                       Stub Contents.       (line  10)

  56780. * share:                                 Files.               (line 339)

  56781. * sharedlibrary:                         Files.               (line 339)

  56782. * shell:                                 Shell Commands.      (line  10)

  56783. * show:                                  Help.                (line 143)

  56784. * show ada print-signatures:             Overloading support for Ada.

  56785.                                                               (line  36)

  56786. * show ada trust-PAD-over-XVS:           Ada Glitches.        (line  42)

  56787. * show agent:                            In-Process Agent.    (line  51)

  56788. * show annotate:                         Annotations Overview.

  56789.                                                               (line  34)

  56790. * show architecture:                     Targets.             (line  21)

  56791. * show args:                             Arguments.           (line  28)

  56792. * show arm:                              ARM.                 (line  13)

  56793. * show auto-load:                        Auto-loading.        (line  45)

  56794. * show auto-load gdb-scripts:            Auto-loading sequences.

  56795.                                                               (line  17)

  56796. * show auto-load guile-scripts:          Guile Auto-loading.  (line  20)

  56797. * show auto-load libthread-db:           libthread_db.so.1 file.

  56798.                                                               (line  25)

  56799. * show auto-load local-gdbinit:          Init File in the Current Directory.

  56800.                                                               (line  18)

  56801. * show auto-load python-scripts:         Python Auto-loading. (line  20)

  56802. * show auto-load safe-path:              Auto-loading safe path.

  56803.                                                               (line  46)

  56804. * show auto-load scripts-directory:      objfile-gdbdotext file.

  56805.                                                               (line  65)

  56806. * show auto-solib-add:                   Files.               (line 324)

  56807. * show backtrace:                        Backtrace.           (line 173)

  56808. * show basenames-may-differ:             Files.               (line 539)

  56809. * show breakpoint always-inserted:       Set Breaks.          (line 325)

  56810. * show breakpoint auto-hw:               Set Breaks.          (line 305)

  56811. * show breakpoint condition-evaluation:  Set Breaks.          (line 346)

  56812. * show breakpoint pending:               Set Breaks.          (line 275)

  56813. * show can-use-hw-watchpoints:           Set Watchpoints.     (line 119)

  56814. * show case-sensitive:                   Symbols.             (line  40)

  56815. * show charset:                          Character Sets.      (line  52)

  56816. * show check range:                      Range Checking.      (line  34)

  56817. * show check type:                       Type Checking.       (line  35)

  56818. * show circular-trace-buffer:            Starting and Stopping Trace Experiments.

  56819.                                                               (line 100)

  56820. * show code-cache:                       Caching Target Data. (line  42)

  56821. * show coerce-float-to-double:           ABI.                 (line  54)

  56822. * show com1base:                         DJGPP Native.        (line 134)

  56823. * show com1irq:                          DJGPP Native.        (line 134)

  56824. * show com2base:                         DJGPP Native.        (line 134)

  56825. * show com2irq:                          DJGPP Native.        (line 134)

  56826. * show com3base:                         DJGPP Native.        (line 134)

  56827. * show com3irq:                          DJGPP Native.        (line 134)

  56828. * show com4base:                         DJGPP Native.        (line 134)

  56829. * show com4irq:                          DJGPP Native.        (line 134)

  56830. * show commands:                         Command History.     (line 110)

  56831. * show complaints:                       Messages/Warnings.   (line  35)

  56832. * show configuration:                    Help.                (line 176)

  56833. * show confirm:                          Messages/Warnings.   (line  57)

  56834. * show convenience:                      Convenience Vars.    (line  37)

  56835. * show copying:                          Help.                (line 167)

  56836. * show cp-abi:                           ABI.                 (line  57)

  56837. * show cwd:                              Working Directory.   (line  27)

  56838. * show cygwin-exceptions:                Cygwin Native.       (line  68)

  56839. * show data-directory:                   Data Files.          (line  16)

  56840. * show dcache line-size:                 Caching Target Data. (line  68)

  56841. * show dcache size:                      Caching Target Data. (line  64)

  56842. * show debug:                            Debugging Output.    (line  20)

  56843. * show debug arc:                        ARC.                 (line  14)

  56844. * show debug auto-load:                  Auto-loading verbose mode.

  56845.                                                               (line  30)

  56846. * show debug bfd-cache:                  File Caching.        (line  27)

  56847. * show debug darwin:                     Darwin.              (line  13)

  56848. * show debug entry-values:               Tail Call Frames.    (line  55)

  56849. * show debug libthread-db:               Threads.             (line 331)

  56850. * show debug mach-o:                     Darwin.              (line  23)

  56851. * show debug mips:                       MIPS.                (line 104)

  56852. * show debug monitor:                    Target Commands.     (line 111)

  56853. * show debug nios2:                      Nios II.             (line  14)

  56854. * show debug skip:                       Skipping Over Functions and Files.

  56855.                                                               (line 153)

  56856. * show debug-file-directory:             Separate Debug Files.

  56857.                                                               (line  75)

  56858. * show default-collect:                  Tracepoint Actions.  (line 150)

  56859. * show detach-on-fork:                   Forks.               (line  73)

  56860. * show directories:                      Source Path.         (line 182)

  56861. * show disassemble-next-line:            Machine Code.        (line 249)

  56862. * show disassembler-options:             Machine Code.        (line 234)

  56863. * show disassembly-flavor:               Machine Code.        (line 246)

  56864. * show disconnected-dprintf:             Dynamic Printf.      (line  88)

  56865. * show disconnected-tracing:             Starting and Stopping Trace Experiments.

  56866.                                                               (line  62)

  56867. * show displaced-stepping:               Maintenance Commands.

  56868.                                                               (line 112)

  56869. * show editing:                          Editing.             (line  22)

  56870. * show environment:                      Environment.         (line  33)

  56871. * show exceptions, Hurd command:         Hurd Native.         (line  45)

  56872. * show exec-done-display:                Debugging Output.    (line  14)

  56873. * show extended-prompt:                  Prompt.              (line  39)

  56874. * show follow-fork-mode:                 Forks.               (line  52)

  56875. * show frame-filter priority:            Frame Filter Management.

  56876.                                                               (line  91)

  56877. * show gnutarget:                        Target Commands.     (line  40)

  56878. * show hash, for remote monitors:        Target Commands.     (line 104)

  56879. * show height:                           Screen Size.         (line  22)

  56880. * show history:                          Command History.     (line 102)

  56881. * show host-charset:                     Character Sets.      (line  55)

  56882. * show index-cache:                      Index Files.         (line  84)

  56883. * show inferior-tty:                     Input/Output.        (line  54)

  56884. * show input-radix:                      Numbers.             (line  35)

  56885. * show interactive-mode:                 Other Misc Settings. (line  20)

  56886. * show language:                         Show.                (line  10)

  56887. * show libthread-db-search-path:         Threads.             (line 328)

  56888. * show listsize:                         List.                (line  39)

  56889. * show logging:                          Logging Output.      (line  26)

  56890. * show mach-exceptions:                  Darwin.              (line  34)

  56891. * show max-completions:                  Completion.          (line  78)

  56892. * show max-user-call-depth:              Define.              (line 128)

  56893. * show max-value-size:                   Value Sizes.         (line  36)

  56894. * show may-call-functions:               Calling.             (line  73)

  56895. * show mem inaccessible-by-default:      Memory Region Attributes.

  56896.                                                               (line 129)

  56897. * show mips abi:                         MIPS.                (line  46)

  56898. * show mips compression:                 MIPS.                (line  72)

  56899. * show mips mask-address:                MIPS.                (line  86)

  56900. * show mipsfpu:                          MIPS Embedded.       (line  13)

  56901. * show mpx bound:                        i386.                (line  57)

  56902. * show multiple-symbols:                 Ambiguous Expressions.

  56903.                                                               (line  70)

  56904. * show new-console:                      Cygwin Native.       (line  77)

  56905. * show new-group:                        Cygwin Native.       (line  86)

  56906. * show non-stop:                         Non-Stop Mode.       (line  38)

  56907. * show opaque-type-resolution:           Symbols.             (line 597)

  56908. * show osabi:                            ABI.                 (line  11)

  56909. * show output-radix:                     Numbers.             (line  38)

  56910. * show overload-resolution:              Debugging C Plus Plus.

  56911.                                                               (line  76)

  56912. * show pagination:                       Screen Size.         (line  47)

  56913. * show paths:                            Environment.         (line  29)

  56914. * show print:                            Print Settings.      (line  39)

  56915. * show print finish:                     Continuing and Stepping.

  56916.                                                               (line 117)

  56917. * show print inferior-events:            Inferiors Connections and Programs.

  56918.                                                               (line 177)

  56919. * show print symbol-loading:             Symbols.             (line 615)

  56920. * show print thread-events:              Threads.             (line 282)

  56921. * show print type methods:               Symbols.             (line  53)

  56922. * show print type nested-type-limit:     Symbols.             (line  64)

  56923. * show print type typedefs:              Symbols.             (line  81)

  56924. * show processor:                        Targets.             (line  31)

  56925. * show procfs-file:                      Process Information. (line 117)

  56926. * show procfs-trace:                     Process Information. (line 109)

  56927. * show prompt:                           Prompt.              (line  19)

  56928. * show radix:                            Numbers.             (line  43)

  56929. * show range-stepping:                   Continuing and Stepping.

  56930.                                                               (line 228)

  56931. * show ravenscar task-switching:         Ravenscar Profile.   (line  22)

  56932. * show record:                           Process Record and Replay.

  56933.                                                               (line 419)

  56934. * show record btrace:                    Process Record and Replay.

  56935.                                                               (line 270)

  56936. * show record full:                      Process Record and Replay.

  56937.                                                               (line 172)

  56938. * show remote:                           Remote Configuration.

  56939.                                                               (line   6)

  56940. * show remote system-call-allowed:       system.              (line  41)

  56941. * show remote-mips64-transfers-32bit-regs: MIPS.              (line  96)

  56942. * show remotecache:                      Caching Target Data. (line  25)

  56943. * show remoteflow:                       Remote Configuration.

  56944.                                                               (line  52)

  56945. * show script-extension:                 Extending GDB.       (line  29)

  56946. * show sh calling-convention:            Super-H.             (line  22)

  56947. * show shell:                            Cygwin Native.       (line 112)

  56948. * show signal-thread:                    Hurd Native.         (line  27)

  56949. * show signals, Hurd command:            Hurd Native.         (line  17)

  56950. * show sigs, Hurd command:               Hurd Native.         (line  17)

  56951. * show sigthread:                        Hurd Native.         (line  27)

  56952. * show solib-search-path:                Files.               (line 473)

  56953. * show stack-cache:                      Caching Target Data. (line  33)

  56954. * show stop-on-solib-events:             Files.               (line 369)

  56955. * show stopped, Hurd command:            Hurd Native.         (line  36)

  56956. * show struct-convention:                i386.                (line  15)

  56957. * show style:                            Output Styling.      (line   6)

  56958. * show substitute-path:                  Source Path.         (line 222)

  56959. * show sysroot:                          Files.               (line 459)

  56960. * show target-charset:                   Character Sets.      (line  58)

  56961. * show target-file-system-kind:          Files.               (line 476)

  56962. * show target-wide-charset:              Character Sets.      (line  67)

  56963. * show task, Hurd commands:              Hurd Native.         (line  56)

  56964. * show tcp:                              Remote Configuration.

  56965.                                                               (line 130)

  56966. * show thread, Hurd command:             Hurd Native.         (line 100)

  56967. * show trace-buffer-size:                Starting and Stopping Trace Experiments.

  56968.                                                               (line 114)

  56969. * show trace-notes:                      Starting and Stopping Trace Experiments.

  56970.                                                               (line 129)

  56971. * show trace-stop-notes:                 Starting and Stopping Trace Experiments.

  56972.                                                               (line 137)

  56973. * show trace-user:                       Starting and Stopping Trace Experiments.

  56974.                                                               (line 124)

  56975. * show unwind-on-terminating-exception:  Calling.             (line  55)

  56976. * show unwindonsignal:                   Calling.             (line  43)

  56977. * show user:                             Define.              (line 121)

  56978. * show values:                           Value History.       (line  47)

  56979. * show varsize-limit:                    Ada Settings.        (line  26)

  56980. * show verbose:                          Messages/Warnings.   (line  21)

  56981. * show version:                          Help.                (line 157)

  56982. * show warranty:                         Help.                (line 171)

  56983. * show width:                            Screen Size.         (line  22)

  56984. * show write:                            Patching.            (line  26)

  56985. * show-all-if-ambiguous:                 Readline Init File Syntax.

  56986.                                                               (line 273)

  56987. * show-all-if-unmodified:                Readline Init File Syntax.

  56988.                                                               (line 279)

  56989. * show-mode-in-prompt:                   Readline Init File Syntax.

  56990.                                                               (line 288)

  56991. * si (stepi):                            Continuing and Stepping.

  56992.                                                               (line 196)

  56993. * signal:                                Signaling.           (line   6)

  56994. * signal annotation:                     Annotations for Running.

  56995.                                                               (line  42)

  56996. * signal-event:                          Cygwin Native.       (line  35)

  56997. * signal-name annotation:                Annotations for Running.

  56998.                                                               (line  22)

  56999. * signal-name-end annotation:            Annotations for Running.

  57000.                                                               (line  22)

  57001. * signal-string annotation:              Annotations for Running.

  57002.                                                               (line  22)

  57003. * signal-string-end annotation:          Annotations for Running.

  57004.                                                               (line  22)

  57005. * SignalEvent.stop_signal:               Events In Python.    (line  91)

  57006. * signalled annotation:                  Annotations for Running.

  57007.                                                               (line  22)

  57008. * silent:                                Break Commands.      (line  43)

  57009. * sim, a command:                        Embedded Processors. (line  13)

  57010. * skip:                                  Skipping Over Functions and Files.

  57011.                                                               (line  44)

  57012. * skip delete:                           Skipping Over Functions and Files.

  57013.                                                               (line 137)

  57014. * skip disable:                          Skipping Over Functions and Files.

  57015.                                                               (line 145)

  57016. * skip enable:                           Skipping Over Functions and Files.

  57017.                                                               (line 141)

  57018. * skip file:                             Skipping Over Functions and Files.

  57019.                                                               (line 100)

  57020. * skip function:                         Skipping Over Functions and Files.

  57021.                                                               (line  89)

  57022. * skip-completed-text:                   Readline Init File Syntax.

  57023.                                                               (line 294)

  57024. * skip-csi-sequence ():                  Miscellaneous Commands.

  57025.                                                               (line  52)

  57026. * source:                                Command Files.       (line  17)

  57027. * source annotation:                     Source Annotations.  (line   6)

  57028. * start:                                 Starting.            (line  80)

  57029. * start-kbd-macro (C-x ():               Keyboard Macros.     (line   6)

  57030. * starti:                                Starting.            (line 113)

  57031. * starting annotation:                   Annotations for Running.

  57032.                                                               (line   6)

  57033. * STDERR:                                Basic Python.        (line 183)

  57034. * STDERR <1>:                            Basic Python.        (line 203)

  57035. * stdio-port?:                           I/O Ports in Guile.  (line  15)

  57036. * STDLOG:                                Basic Python.        (line 186)

  57037. * STDLOG <1>:                            Basic Python.        (line 206)

  57038. * STDOUT:                                Basic Python.        (line 180)

  57039. * STDOUT <1>:                            Basic Python.        (line 200)

  57040. * step:                                  Continuing and Stepping.

  57041.                                                               (line  45)

  57042. * step&:                                 Background Execution.

  57043.                                                               (line  28)

  57044. * stepi:                                 Continuing and Stepping.

  57045.                                                               (line 196)

  57046. * stepi&:                                Background Execution.

  57047.                                                               (line  31)

  57048. * stop, a pseudo-command:                Hooks.               (line  21)

  57049. * stopping annotation:                   Annotations for Running.

  57050.                                                               (line   6)

  57051. * strace:                                Create and Delete Tracepoints.

  57052.                                                               (line  75)

  57053. * string->argv:                          Commands In Guile.   (line  73)

  57054. * symbol-addr-class:                     Symbols In Guile.    (line  48)

  57055. * symbol-argument?:                      Symbols In Guile.    (line  58)

  57056. * symbol-constant?:                      Symbols In Guile.    (line  62)

  57057. * symbol-file:                           Files.               (line  45)

  57058. * symbol-function?:                      Symbols In Guile.    (line  65)

  57059. * symbol-line:                           Symbols In Guile.    (line  32)

  57060. * symbol-linkage-name:                   Symbols In Guile.    (line  39)

  57061. * symbol-name:                           Symbols In Guile.    (line  36)

  57062. * symbol-needs-frame?:                   Symbols In Guile.    (line  53)

  57063. * symbol-print-name:                     Symbols In Guile.    (line  43)

  57064. * symbol-symtab:                         Symbols In Guile.    (line  28)

  57065. * symbol-type:                           Symbols In Guile.    (line  24)

  57066. * symbol-valid?:                         Symbols In Guile.    (line  17)

  57067. * symbol-value:                          Symbols In Guile.    (line  72)

  57068. * symbol-variable?:                      Symbols In Guile.    (line  69)

  57069. * Symbol.addr_class:                     Symbols In Python.   (line 119)

  57070. * Symbol.is_argument:                    Symbols In Python.   (line 129)

  57071. * Symbol.is_constant:                    Symbols In Python.   (line 132)

  57072. * Symbol.is_function:                    Symbols In Python.   (line 135)

  57073. * Symbol.is_valid:                       Symbols In Python.   (line 143)

  57074. * Symbol.is_variable:                    Symbols In Python.   (line 138)

  57075. * Symbol.line:                           Symbols In Python.   (line 102)

  57076. * Symbol.linkage_name:                   Symbols In Python.   (line 110)

  57077. * Symbol.name:                           Symbols In Python.   (line 106)

  57078. * Symbol.needs_frame:                    Symbols In Python.   (line 124)

  57079. * Symbol.print_name:                     Symbols In Python.   (line 114)

  57080. * Symbol.symtab:                         Symbols In Python.   (line  97)

  57081. * Symbol.type:                           Symbols In Python.   (line  92)

  57082. * Symbol.value:                          Symbols In Python.   (line 150)

  57083. * symbol?:                               Symbols In Guile.    (line  13)

  57084. * SYMBOL_COMMON_BLOCK_DOMAIN:            Symbols In Python.   (line 178)

  57085. * SYMBOL_FUNCTIONS_DOMAIN:               Symbols In Guile.    (line 133)

  57086. * SYMBOL_LABEL_DOMAIN:                   Symbols In Python.   (line 172)

  57087. * SYMBOL_LABEL_DOMAIN <1>:               Symbols In Guile.    (line 126)

  57088. * SYMBOL_LOC_ARG:                        Symbols In Python.   (line 197)

  57089. * SYMBOL_LOC_ARG <1>:                    Symbols In Guile.    (line 155)

  57090. * SYMBOL_LOC_BLOCK:                      Symbols In Python.   (line 218)

  57091. * SYMBOL_LOC_BLOCK <1>:                  Symbols In Guile.    (line 176)

  57092. * SYMBOL_LOC_COMPUTED:                   Symbols In Python.   (line 232)

  57093. * SYMBOL_LOC_COMPUTED <1>:               Symbols In Python.   (line 235)

  57094. * SYMBOL_LOC_COMPUTED <2>:               Symbols In Guile.    (line 190)

  57095. * SYMBOL_LOC_CONST:                      Symbols In Python.   (line 188)

  57096. * SYMBOL_LOC_CONST <1>:                  Symbols In Guile.    (line 146)

  57097. * SYMBOL_LOC_CONST_BYTES:                Symbols In Python.   (line 221)

  57098. * SYMBOL_LOC_CONST_BYTES <1>:            Symbols In Guile.    (line 179)

  57099. * SYMBOL_LOC_LOCAL:                      Symbols In Python.   (line 211)

  57100. * SYMBOL_LOC_LOCAL <1>:                  Symbols In Guile.    (line 169)

  57101. * SYMBOL_LOC_OPTIMIZED_OUT:              Symbols In Python.   (line 229)

  57102. * SYMBOL_LOC_OPTIMIZED_OUT <1>:          Symbols In Guile.    (line 187)

  57103. * SYMBOL_LOC_REF_ARG:                    Symbols In Python.   (line 201)

  57104. * SYMBOL_LOC_REF_ARG <1>:                Symbols In Guile.    (line 159)

  57105. * SYMBOL_LOC_REGISTER:                   Symbols In Python.   (line 194)

  57106. * SYMBOL_LOC_REGISTER <1>:               Symbols In Guile.    (line 152)

  57107. * SYMBOL_LOC_REGPARM_ADDR:               Symbols In Python.   (line 206)

  57108. * SYMBOL_LOC_REGPARM_ADDR <1>:           Symbols In Guile.    (line 164)

  57109. * SYMBOL_LOC_STATIC:                     Symbols In Python.   (line 191)

  57110. * SYMBOL_LOC_STATIC <1>:                 Symbols In Guile.    (line 149)

  57111. * SYMBOL_LOC_TYPEDEF:                    Symbols In Python.   (line 214)

  57112. * SYMBOL_LOC_TYPEDEF <1>:                Symbols In Guile.    (line 172)

  57113. * SYMBOL_LOC_UNDEF:                      Symbols In Python.   (line 184)

  57114. * SYMBOL_LOC_UNDEF <1>:                  Symbols In Guile.    (line 142)

  57115. * SYMBOL_LOC_UNRESOLVED:                 Symbols In Python.   (line 224)

  57116. * SYMBOL_LOC_UNRESOLVED <1>:             Symbols In Guile.    (line 182)

  57117. * SYMBOL_MODULE_DOMAIN:                  Symbols In Python.   (line 175)

  57118. * SYMBOL_STRUCT_DOMAIN:                  Symbols In Python.   (line 169)

  57119. * SYMBOL_STRUCT_DOMAIN <1>:              Symbols In Guile.    (line 123)

  57120. * SYMBOL_TYPES_DOMAIN:                   Symbols In Guile.    (line 136)

  57121. * SYMBOL_UNDEF_DOMAIN:                   Symbols In Python.   (line 160)

  57122. * SYMBOL_UNDEF_DOMAIN <1>:               Symbols In Guile.    (line 114)

  57123. * SYMBOL_VARIABLES_DOMAIN:               Symbols In Guile.    (line 129)

  57124. * SYMBOL_VAR_DOMAIN:                     Symbols In Python.   (line 165)

  57125. * SYMBOL_VAR_DOMAIN <1>:                 Symbols In Guile.    (line 119)

  57126. * symtab-filename:                       Symbol Tables In Guile.

  57127.                                                               (line  28)

  57128. * symtab-fullname:                       Symbol Tables In Guile.

  57129.                                                               (line  31)

  57130. * symtab-global-block:                   Symbol Tables In Guile.

  57131.                                                               (line  38)

  57132. * symtab-objfile:                        Symbol Tables In Guile.

  57133.                                                               (line  34)

  57134. * symtab-static-block:                   Symbol Tables In Guile.

  57135.                                                               (line  42)

  57136. * symtab-valid?:                         Symbol Tables In Guile.

  57137.                                                               (line  21)

  57138. * Symtab.filename:                       Symbol Tables In Python.

  57139.                                                               (line  43)

  57140. * Symtab.fullname:                       Symbol Tables In Python.

  57141.                                                               (line  66)

  57142. * Symtab.global_block:                   Symbol Tables In Python.

  57143.                                                               (line  69)

  57144. * Symtab.is_valid:                       Symbol Tables In Python.

  57145.                                                               (line  59)

  57146. * Symtab.linetable:                      Symbol Tables In Python.

  57147.                                                               (line  77)

  57148. * Symtab.objfile:                        Symbol Tables In Python.

  57149.                                                               (line  47)

  57150. * Symtab.producer:                       Symbol Tables In Python.

  57151.                                                               (line  51)

  57152. * Symtab.static_block:                   Symbol Tables In Python.

  57153.                                                               (line  73)

  57154. * symtab?:                               Symbol Tables In Guile.

  57155.                                                               (line  17)

  57156. * Symtab_and_line.is_valid:              Symbol Tables In Python.

  57157.                                                               (line  34)

  57158. * Symtab_and_line.last:                  Symbol Tables In Python.

  57159.                                                               (line  24)

  57160. * Symtab_and_line.line:                  Symbol Tables In Python.

  57161.                                                               (line  28)

  57162. * Symtab_and_line.pc:                    Symbol Tables In Python.

  57163.                                                               (line  20)

  57164. * Symtab_and_line.symtab:                Symbol Tables In Python.

  57165.                                                               (line  16)

  57166. * sysinfo:                               DJGPP Native.        (line  19)

  57167. * taas:                                  Threads.             (line 222)

  57168. * tab-insert (M-<TAB>):                  Commands For Text.   (line  30)

  57169. * tabset:                                TUI Configuration.   (line  49)

  57170. * target:                                Target Commands.     (line  49)

  57171. * target ctf:                            Trace Files.         (line  28)

  57172. * target record:                         Process Record and Replay.

  57173.                                                               (line  43)

  57174. * target record-btrace:                  Process Record and Replay.

  57175.                                                               (line  43)

  57176. * target record-full:                    Process Record and Replay.

  57177.                                                               (line  43)

  57178. * target sim:                            OpenRISC 1000.       (line  13)

  57179. * target tfile:                          Trace Files.         (line  28)

  57180. * target-config:                         Guile Configuration. (line  24)

  57181. * task (Ada):                            Ada Tasks.           (line 105)

  57182. * tbreak:                                Set Breaks.          (line  54)

  57183. * tcatch:                                Set Catchpoints.     (line 298)

  57184. * tdump:                                 tdump.               (line   6)

  57185. * teval (tracepoints):                   Tracepoint Actions.  (line 118)

  57186. * tfaas:                                 Threads.             (line 229)

  57187. * tfile:                                 Trace Files.         (line  28)

  57188. * tfind:                                 tfind.               (line   6)

  57189. * thbreak:                               Set Breaks.          (line  80)

  57190. * this, inside C++ member functions:     C Plus Plus Expressions.

  57191.                                                               (line  20)

  57192. * thread apply:                          Threads.             (line 187)

  57193. * thread find:                           Threads.             (line 258)

  57194. * thread name:                           Threads.             (line 247)

  57195. * thread THREAD-ID:                      Threads.             (line 169)

  57196. * thread-info:                           GDB/MI Support Commands.

  57197.                                                               (line  86)

  57198. * ThreadEvent.inferior_thread:           Events In Python.    (line  54)

  57199. * throw-user-error:                      Commands In Guile.   (line  81)

  57200. * tilde-expand (M-~):                    Miscellaneous Commands.

  57201.                                                               (line  30)

  57202. * trace:                                 Create and Delete Tracepoints.

  57203.                                                               (line   6)

  57204. * transpose-chars (C-t):                 Commands For Text.   (line  45)

  57205. * transpose-words (M-t):                 Commands For Text.   (line  51)

  57206. * tsave:                                 Trace Files.         (line  12)

  57207. * tstart [ NOTES ]:                      Starting and Stopping Trace Experiments.

  57208.                                                               (line   6)

  57209. * tstatus:                               Starting and Stopping Trace Experiments.

  57210.                                                               (line  27)

  57211. * tstop [ NOTES ]:                       Starting and Stopping Trace Experiments.

  57212.                                                               (line  16)

  57213. * tty:                                   Input/Output.        (line  23)

  57214. * tui disable:                           TUI Commands.        (line  23)

  57215. * tui enable:                            TUI Commands.        (line  18)

  57216. * tui new-layout:                        TUI Commands.        (line  29)

  57217. * tui reg:                               TUI Commands.        (line 128)

  57218. * TuiWindow.erase:                       TUI Windows In Python.

  57219.                                                               (line  44)

  57220. * TuiWindow.height:                      TUI Windows In Python.

  57221.                                                               (line  36)

  57222. * TuiWindow.is_valid:                    TUI Windows In Python.

  57223.                                                               (line  26)

  57224. * TuiWindow.title:                       TUI Windows In Python.

  57225.                                                               (line  39)

  57226. * TuiWindow.width:                       TUI Windows In Python.

  57227.                                                               (line  33)

  57228. * TuiWindow.write:                       TUI Windows In Python.

  57229.                                                               (line  47)

  57230. * tvariable:                             Trace State Variables.

  57231.                                                               (line  26)

  57232. * type-array:                            Types In Guile.      (line  52)

  57233. * type-code:                             Types In Guile.      (line  25)

  57234. * type-const:                            Types In Guile.      (line  99)

  57235. * type-field:                            Types In Guile.      (line 129)

  57236. * type-fields:                           Types In Guile.      (line 115)

  57237. * type-has-field-deep?:                  Guile Types Module.  (line  32)

  57238. * type-has-field?:                       Types In Guile.      (line 142)

  57239. * type-name:                             Types In Guile.      (line  34)

  57240. * type-num-fields:                       Types In Guile.      (line 112)

  57241. * type-pointer:                          Types In Guile.      (line  73)

  57242. * type-print-name:                       Types In Guile.      (line  38)

  57243. * type-range:                            Types In Guile.      (line  77)

  57244. * type-reference:                        Types In Guile.      (line  81)

  57245. * type-sizeof:                           Types In Guile.      (line  43)

  57246. * type-strip-typedefs:                   Types In Guile.      (line  48)

  57247. * type-tag:                              Types In Guile.      (line  29)

  57248. * type-target:                           Types In Guile.      (line  85)

  57249. * type-unqualified:                      Types In Guile.      (line 107)

  57250. * type-vector:                           Types In Guile.      (line  60)

  57251. * type-volatile:                         Types In Guile.      (line 103)

  57252. * Type.alignof:                          Types In Python.     (line  32)

  57253. * Type.array:                            Types In Python.     (line 138)

  57254. * Type.code:                             Types In Python.     (line  38)

  57255. * Type.const:                            Types In Python.     (line 159)

  57256. * Type.dynamic:                          Types In Python.     (line  42)

  57257. * Type.fields:                           Types In Python.     (line  85)

  57258. * Type.name:                             Types In Python.     (line  62)

  57259. * Type.objfile:                          Types In Python.     (line  79)

  57260. * Type.optimized_out:                    Types In Python.     (line 216)

  57261. * Type.pointer:                          Types In Python.     (line 182)

  57262. * Type.range:                            Types In Python.     (line 172)

  57263. * Type.reference:                        Types In Python.     (line 178)

  57264. * Type.sizeof:                           Types In Python.     (line  66)

  57265. * Type.strip_typedefs:                   Types In Python.     (line 186)

  57266. * Type.tag:                              Types In Python.     (line  73)

  57267. * Type.target:                           Types In Python.     (line 190)

  57268. * Type.template_argument:                Types In Python.     (line 204)

  57269. * Type.unqualified:                      Types In Python.     (line 167)

  57270. * Type.vector:                           Types In Python.     (line 146)

  57271. * Type.volatile:                         Types In Python.     (line 163)

  57272. * type?:                                 Types In Guile.      (line  11)

  57273. * TYPE_CODE_ARRAY:                       Types In Python.     (line 228)

  57274. * TYPE_CODE_ARRAY <1>:                   Types In Guile.      (line 153)

  57275. * TYPE_CODE_BITSTRING:                   Types In Python.     (line 266)

  57276. * TYPE_CODE_BITSTRING <1>:               Types In Guile.      (line 191)

  57277. * TYPE_CODE_BOOL:                        Types In Python.     (line 290)

  57278. * TYPE_CODE_BOOL <1>:                    Types In Guile.      (line 212)

  57279. * TYPE_CODE_CHAR:                        Types In Python.     (line 287)

  57280. * TYPE_CODE_CHAR <1>:                    Types In Guile.      (line 209)

  57281. * TYPE_CODE_COMPLEX:                     Types In Python.     (line 293)

  57282. * TYPE_CODE_COMPLEX <1>:                 Types In Guile.      (line 215)

  57283. * TYPE_CODE_DECFLOAT:                    Types In Python.     (line 302)

  57284. * TYPE_CODE_DECFLOAT <1>:                Types In Guile.      (line 224)

  57285. * TYPE_CODE_ENUM:                        Types In Python.     (line 237)

  57286. * TYPE_CODE_ENUM <1>:                    Types In Guile.      (line 162)

  57287. * TYPE_CODE_ERROR:                       Types In Python.     (line 269)

  57288. * TYPE_CODE_ERROR <1>:                   Types In Guile.      (line 194)

  57289. * TYPE_CODE_FLAGS:                       Types In Python.     (line 240)

  57290. * TYPE_CODE_FLAGS <1>:                   Types In Guile.      (line 165)

  57291. * TYPE_CODE_FLT:                         Types In Python.     (line 249)

  57292. * TYPE_CODE_FLT <1>:                     Types In Guile.      (line 174)

  57293. * TYPE_CODE_FUNC:                        Types In Python.     (line 243)

  57294. * TYPE_CODE_FUNC <1>:                    Types In Guile.      (line 168)

  57295. * TYPE_CODE_INT:                         Types In Python.     (line 246)

  57296. * TYPE_CODE_INT <1>:                     Types In Guile.      (line 171)

  57297. * TYPE_CODE_INTERNAL_FUNCTION:           Types In Python.     (line 305)

  57298. * TYPE_CODE_INTERNAL_FUNCTION <1>:       Types In Guile.      (line 227)

  57299. * TYPE_CODE_MEMBERPTR:                   Types In Python.     (line 278)

  57300. * TYPE_CODE_MEMBERPTR <1>:               Types In Guile.      (line 203)

  57301. * TYPE_CODE_METHOD:                      Types In Python.     (line 272)

  57302. * TYPE_CODE_METHOD <1>:                  Types In Guile.      (line 197)

  57303. * TYPE_CODE_METHODPTR:                   Types In Python.     (line 275)

  57304. * TYPE_CODE_METHODPTR <1>:               Types In Guile.      (line 200)

  57305. * TYPE_CODE_NAMESPACE:                   Types In Python.     (line 299)

  57306. * TYPE_CODE_NAMESPACE <1>:               Types In Guile.      (line 221)

  57307. * TYPE_CODE_PTR:                         Types In Python.     (line 225)

  57308. * TYPE_CODE_PTR <1>:                     Types In Guile.      (line 150)

  57309. * TYPE_CODE_RANGE:                       Types In Python.     (line 258)

  57310. * TYPE_CODE_RANGE <1>:                   Types In Guile.      (line 183)

  57311. * TYPE_CODE_REF:                         Types In Python.     (line 281)

  57312. * TYPE_CODE_REF <1>:                     Types In Guile.      (line 206)

  57313. * TYPE_CODE_RVALUE_REF:                  Types In Python.     (line 284)

  57314. * TYPE_CODE_SET:                         Types In Python.     (line 255)

  57315. * TYPE_CODE_SET <1>:                     Types In Guile.      (line 180)

  57316. * TYPE_CODE_STRING:                      Types In Python.     (line 261)

  57317. * TYPE_CODE_STRING <1>:                  Types In Guile.      (line 186)

  57318. * TYPE_CODE_STRUCT:                      Types In Python.     (line 231)

  57319. * TYPE_CODE_STRUCT <1>:                  Types In Guile.      (line 156)

  57320. * TYPE_CODE_TYPEDEF:                     Types In Python.     (line 296)

  57321. * TYPE_CODE_TYPEDEF <1>:                 Types In Guile.      (line 218)

  57322. * TYPE_CODE_UNION:                       Types In Python.     (line 234)

  57323. * TYPE_CODE_UNION <1>:                   Types In Guile.      (line 159)

  57324. * TYPE_CODE_VOID:                        Types In Python.     (line 252)

  57325. * TYPE_CODE_VOID <1>:                    Types In Guile.      (line 177)

  57326. * u (SingleKey TUI key):                 TUI Single Key Mode. (line  37)

  57327. * u (until):                             Continuing and Stepping.

  57328.                                                               (line 124)

  57329. * undefined-command-error-code:          GDB/MI Support Commands.

  57330.                                                               (line 101)

  57331. * undisplay:                             Auto Display.        (line  45)

  57332. * undo (C-_ or C-x C-u):                 Miscellaneous Commands.

  57333.                                                               (line  23)

  57334. * universal-argument ():                 Numeric Arguments.   (line  10)

  57335. * unix-filename-rubout ():               Commands For Killing.

  57336.                                                               (line  32)

  57337. * unix-line-discard (C-u):               Commands For Killing.

  57338.                                                               (line  12)

  57339. * unix-word-rubout (C-w):                Commands For Killing.

  57340.                                                               (line  28)

  57341. * unset environment:                     Environment.         (line  65)

  57342. * unset substitute-path:                 Source Path.         (line 214)

  57343. * until:                                 Continuing and Stepping.

  57344.                                                               (line 124)

  57345. * until&:                                Background Execution.

  57346.                                                               (line  46)

  57347. * unwind-stop-reason-string:             Frames In Guile.     (line 163)

  57348. * up:                                    Selection.           (line  69)

  57349. * Up:                                    TUI Keys.            (line  67)

  57350. * up-silently:                           Selection.           (line 106)

  57351. * upcase-word (M-u):                     Commands For Text.   (line  56)

  57352. * update:                                TUI Commands.        (line 154)

  57353. * v (SingleKey TUI key):                 TUI Single Key Mode. (line  40)

  57354. * value->bool:                           Values From Inferior In Guile.

  57355.                                                               (line 234)

  57356. * value->bytevector:                     Values From Inferior In Guile.

  57357.                                                               (line 246)

  57358. * value->integer:                        Values From Inferior In Guile.

  57359.                                                               (line 238)

  57360. * value->lazy-string:                    Values From Inferior In Guile.

  57361.                                                               (line 291)

  57362. * value->real:                           Values From Inferior In Guile.

  57363.                                                               (line 242)

  57364. * value->string:                         Values From Inferior In Guile.

  57365.                                                               (line 250)

  57366. * value-abs:                             Arithmetic In Guile. (line  35)

  57367. * value-add:                             Arithmetic In Guile. (line  15)

  57368. * value-address:                         Values From Inferior In Guile.

  57369.                                                               (line 106)

  57370. * value-call:                            Values From Inferior In Guile.

  57371.                                                               (line 228)

  57372. * value-cast:                            Values From Inferior In Guile.

  57373.                                                               (line 129)

  57374. * value-dereference:                     Values From Inferior In Guile.

  57375.                                                               (line 143)

  57376. * value-div:                             Arithmetic In Guile. (line  21)

  57377. * value-dynamic-cast:                    Values From Inferior In Guile.

  57378.                                                               (line 135)

  57379. * value-dynamic-type:                    Values From Inferior In Guile.

  57380.                                                               (line 114)

  57381. * value-fetch-lazy!:                     Values From Inferior In Guile.

  57382.                                                               (line 333)

  57383. * value-field:                           Values From Inferior In Guile.

  57384.                                                               (line 221)

  57385. * value-lazy?:                           Values From Inferior In Guile.

  57386.                                                               (line 316)

  57387. * value-logand:                          Arithmetic In Guile. (line  47)

  57388. * value-logior:                          Arithmetic In Guile. (line  49)

  57389. * value-lognot:                          Arithmetic In Guile. (line  45)

  57390. * value-logxor:                          Arithmetic In Guile. (line  51)

  57391. * value-lsh:                             Arithmetic In Guile. (line  37)

  57392. * value-max:                             Arithmetic In Guile. (line  43)

  57393. * value-min:                             Arithmetic In Guile. (line  41)

  57394. * value-mod:                             Arithmetic In Guile. (line  25)

  57395. * value-mul:                             Arithmetic In Guile. (line  19)

  57396. * value-neg:                             Arithmetic In Guile. (line  31)

  57397. * value-not:                             Arithmetic In Guile. (line  29)

  57398. * value-optimized-out?:                  Values From Inferior In Guile.

  57399.                                                               (line 102)

  57400. * value-pos:                             Arithmetic In Guile. (line  33)

  57401. * value-pow:                             Arithmetic In Guile. (line  27)

  57402. * value-print:                           Values From Inferior In Guile.

  57403.                                                               (line 342)

  57404. * value-referenced-value:                Values From Inferior In Guile.

  57405.                                                               (line 196)

  57406. * value-reinterpret-cast:                Values From Inferior In Guile.

  57407.                                                               (line 139)

  57408. * value-rem:                             Arithmetic In Guile. (line  23)

  57409. * value-rsh:                             Arithmetic In Guile. (line  39)

  57410. * value-sub:                             Arithmetic In Guile. (line  17)

  57411. * value-subscript:                       Values From Inferior In Guile.

  57412.                                                               (line 224)

  57413. * value-type:                            Values From Inferior In Guile.

  57414.                                                               (line 110)

  57415. * Value.address:                         Values From Inferior.

  57416.                                                               (line  65)

  57417. * Value.cast:                            Values From Inferior.

  57418.                                                               (line 148)

  57419. * Value.const_value:                     Values From Inferior.

  57420.                                                               (line 236)

  57421. * Value.dereference:                     Values From Inferior.

  57422.                                                               (line 154)

  57423. * Value.dynamic_cast:                    Values From Inferior.

  57424.                                                               (line 240)

  57425. * Value.dynamic_type:                    Values From Inferior.

  57426.                                                               (line  79)

  57427. * Value.fetch_lazy:                      Values From Inferior.

  57428.                                                               (line 386)

  57429. * Value.format_string:                   Values From Inferior.

  57430.                                                               (line 248)

  57431. * Value.is_lazy:                         Values From Inferior.

  57432.                                                               (line  94)

  57433. * Value.is_optimized_out:                Values From Inferior.

  57434.                                                               (line  70)

  57435. * Value.lazy_string:                     Values From Inferior.

  57436.                                                               (line 364)

  57437. * Value.referenced_value:                Values From Inferior.

  57438.                                                               (line 207)

  57439. * Value.reference_value:                 Values From Inferior.

  57440.                                                               (line 232)

  57441. * Value.reinterpret_cast:                Values From Inferior.

  57442.                                                               (line 244)

  57443. * Value.string:                          Values From Inferior.

  57444.                                                               (line 332)

  57445. * Value.type:                            Values From Inferior.

  57446.                                                               (line  75)

  57447. * Value.__init__:                        Values From Inferior.

  57448.                                                               (line 107)

  57449. * Value.__init__ <1>:                    Values From Inferior.

  57450.                                                               (line 141)

  57451. * value<=?:                              Arithmetic In Guile. (line  57)

  57452. * value<?:                               Arithmetic In Guile. (line  55)

  57453. * value=?:                               Arithmetic In Guile. (line  53)

  57454. * value>=?:                              Arithmetic In Guile. (line  61)

  57455. * value>?:                               Arithmetic In Guile. (line  59)

  57456. * value?:                                Values From Inferior In Guile.

  57457.                                                               (line  41)

  57458. * vi-cmd-mode-string:                    Readline Init File Syntax.

  57459.                                                               (line 307)

  57460. * vi-editing-mode (M-C-j):               Miscellaneous Commands.

  57461.                                                               (line  92)

  57462. * vi-ins-mode-string:                    Readline Init File Syntax.

  57463.                                                               (line 318)

  57464. * visible-stats:                         Readline Init File Syntax.

  57465.                                                               (line 329)

  57466. * w (SingleKey TUI key):                 TUI Single Key Mode. (line  43)

  57467. * w (with):                              Command Settings.    (line  39)

  57468. * watch:                                 Set Watchpoints.     (line  42)

  57469. * watchpoint annotation:                 Annotations for Running.

  57470.                                                               (line  50)

  57471. * whatis:                                Symbols.             (line 125)

  57472. * where:                                 Backtrace.           (line  94)

  57473. * while:                                 Command Files.       (line  85)

  57474. * while-stepping (tracepoints):          Tracepoint Actions.  (line 126)

  57475. * Window.close:                          TUI Windows In Python.

  57476.                                                               (line  62)

  57477. * Window.hscroll:                        TUI Windows In Python.

  57478.                                                               (line  81)

  57479. * Window.render:                         TUI Windows In Python.

  57480.                                                               (line  71)

  57481. * Window.vscroll:                        TUI Windows In Python.

  57482.                                                               (line  88)

  57483. * winheight:                             TUI Commands.        (line 158)

  57484. * with command:                          Command Settings.    (line  39)

  57485. * WP_ACCESS:                             Breakpoints In Python.

  57486.                                                               (line  86)

  57487. * WP_ACCESS <1>:                         Breakpoints In Guile.

  57488.                                                               (line  84)

  57489. * WP_READ:                               Breakpoints In Python.

  57490.                                                               (line  80)

  57491. * WP_READ <1>:                           Breakpoints In Guile.

  57492.                                                               (line  78)

  57493. * WP_WRITE:                              Breakpoints In Python.

  57494.                                                               (line  83)

  57495. * WP_WRITE <1>:                          Breakpoints In Guile.

  57496.                                                               (line  81)

  57497. * x (examine memory):                    Memory.              (line   9)

  57498. * x(examine), and info line:             Machine Code.        (line  34)

  57499. * XMethod.__init__:                      Xmethod API.         (line  38)

  57500. * XMethodMatcher.match:                  Xmethod API.         (line  47)

  57501. * XMethodMatcher.__init__:               Xmethod API.         (line  43)

  57502. * XMethodWorker.get_arg_types:           Xmethod API.         (line  60)

  57503. * XMethodWorker.get_result_type:         Xmethod API.         (line  67)

  57504. * XMethodWorker.__call__:                Xmethod API.         (line  73)

  57505. * yank (C-y):                            Commands For Killing.

  57506.                                                               (line  59)

  57507. * yank-last-arg (M-. or M-_):            Commands For History.

  57508.                                                               (line  79)

  57509. * yank-nth-arg (M-C-y):                  Commands For History.

  57510.                                                               (line  70)

  57511. * yank-pop (M-y):                        Commands For Killing.

  57512.                                                               (line  62)

  57513. 

  57514. 

  57515. 

  57516. Tag Table:

  57517. Node: Top1757

  57518. Node: Summary5244

  57519. Node: Free Software7105

  57520. Node: Free Documentation7845

  57521. Node: Contributors12779

  57522. Node: Sample Session21810

  57523. Node: Invocation28663

  57524. Node: Invoking GDB29206

  57525. Node: File Options31548

  57526. Ref: --readnever34619

  57527. Node: Mode Options35093

  57528. Ref: -nx35320

  57529. Ref: -nh37077

  57530. Node: Startup43401

  57531. Ref: Home Directory Init File44247

  57532. Ref: Option -init-eval-command44357

  57533. Ref: Init File in the Current Directory during Startup44697

  57534. Ref: Startup-Footnote-146893

  57535. Node: Quitting GDB47002

  57536. Node: Shell Commands47899

  57537. Ref: pipe48891

  57538. Node: Logging Output50405

  57539. Node: Commands51531

  57540. Node: Command Syntax52396

  57541. Node: Command Settings54568

  57542. Node: Completion57581

  57543. Ref: Completion-Footnote-164521

  57544. Node: Command Options64681

  57545. Node: Command aliases default args67057

  57546. Ref: Command aliases default args-Footnote-170510

  57547. Node: Help70664

  57548. Node: Running77738

  57549. Node: Compilation78991

  57550. Node: Starting81070

  57551. Ref: set exec-wrapper86860

  57552. Ref: set startup-with-shell87949

  57553. Ref: set auto-connect-native-target89010

  57554. Node: Arguments93481

  57555. Node: Environment94750

  57556. Ref: set environment96632

  57557. Ref: unset environment97814

  57558. Node: Working Directory98820

  57559. Ref: set cwd command99392

  57560. Ref: cd command100332

  57561. Node: Input/Output101026

  57562. Node: Attach103086

  57563. Ref: set exec-file-mismatch104303

  57564. Node: Kill Process106439

  57565. Node: Inferiors Connections and Programs107432

  57566. Node: Threads117254

  57567. Ref: thread numbers119377

  57568. Ref: thread ID lists120267

  57569. Ref: global thread numbers121307

  57570. Ref: thread apply all125163

  57571. Ref: set libthread-db-search-path130013

  57572. Node: Forks132067

  57573. Node: Checkpoint/Restart138633

  57574. Ref: Checkpoint/Restart-Footnote-1143161

  57575. Node: Stopping143196

  57576. Node: Breakpoints144459

  57577. Node: Set Breaks147716

  57578. Node: Set Watchpoints166675

  57579. Node: Set Catchpoints176057

  57580. Ref: catch syscall181555

  57581. Node: Delete Breaks189320

  57582. Node: Disabling191256

  57583. Node: Conditions194636

  57584. Node: Break Commands200283

  57585. Node: Dynamic Printf203503

  57586. Node: Save Breakpoints207807

  57587. Node: Static Probe Points208982

  57588. Ref: Static Probe Points-Footnote-1213160

  57589. Ref: Static Probe Points-Footnote-2213320

  57590. Node: Error in Breakpoints213460

  57591. Node: Breakpoint-related Warnings214196

  57592. Node: Continuing and Stepping216523

  57593. Ref: range stepping226303

  57594. Node: Skipping Over Functions and Files227383

  57595. Node: Signals233232

  57596. Ref: stepping and signal handlers237666

  57597. Ref: stepping into signal handlers238462

  57598. Ref: extra signal information239695

  57599. Node: Thread Stops242161

  57600. Node: All-Stop Mode243260

  57601. Node: Non-Stop Mode247227

  57602. Node: Background Execution250640

  57603. Node: Thread-Specific Breakpoints252856

  57604. Node: Interrupted System Calls254872

  57605. Node: Observer Mode256386

  57606. Node: Reverse Execution259822

  57607. Ref: Reverse Execution-Footnote-1264740

  57608. Ref: Reverse Execution-Footnote-2265367

  57609. Node: Process Record and Replay265417

  57610. Node: Stack286806

  57611. Node: Frames288423

  57612. Node: Backtrace290761

  57613. Ref: backtrace-command291098

  57614. Ref: set backtrace past-main297545

  57615. Ref: set backtrace past-entry297873

  57616. Ref: set backtrace limit298440

  57617. Ref: Backtrace-Footnote-1299064

  57618. Node: Selection299252

  57619. Node: Frame Info304035

  57620. Node: Frame Apply308457

  57621. Node: Frame Filter Management312887

  57622. Ref: disable frame-filter all313415

  57623. Node: Source317723

  57624. Node: List318789

  57625. Node: Specify Location321491

  57626. Node: Linespec Locations322112

  57627. Node: Explicit Locations325511

  57628. Node: Address Locations328723

  57629. Node: Edit330474

  57630. Ref: Edit-Footnote-1331950

  57631. Node: Search332185

  57632. Node: Source Path332993

  57633. Ref: set substitute-path341934

  57634. Node: Machine Code344154

  57635. Node: Data354498

  57636. Ref: print options355337

  57637. Node: Expressions365338

  57638. Node: Ambiguous Expressions367441

  57639. Node: Variables370671

  57640. Node: Arrays377269

  57641. Node: Output Formats379800

  57642. Ref: Output Formats-Footnote-1383173

  57643. Node: Memory383330

  57644. Ref: addressable memory unit389515

  57645. Node: Auto Display391009

  57646. Node: Print Settings395551

  57647. Ref: set print address395849

  57648. Ref: set print symbol399511

  57649. Ref: set print array399999

  57650. Ref: set print array-indexes400327

  57651. Ref: set print elements400813

  57652. Ref: set print frame-arguments401478

  57653. Ref: set print raw-frame-arguments403647

  57654. Ref: set print entry-values404063

  57655. Ref: set print frame-info408442

  57656. Ref: set print repeats410108

  57657. Ref: set print max-depth410750

  57658. Ref: set print null-stop412442

  57659. Ref: set print pretty412766

  57660. Ref: set print raw-values413353

  57661. Ref: set print union414370

  57662. Ref: set print object416676

  57663. Ref: set print static-members417470

  57664. Ref: set print vtbl418147

  57665. Node: Pretty Printing418531

  57666. Node: Pretty-Printer Introduction419045

  57667. Node: Pretty-Printer Example420800

  57668. Node: Pretty-Printer Commands421578

  57669. Node: Value History424509

  57670. Node: Convenience Vars426931

  57671. Node: Convenience Funs434602

  57672. Node: Registers443117

  57673. Ref: info_registers_reggroup443774

  57674. Ref: standard registers444325

  57675. Ref: Registers-Footnote-1449276

  57676. Node: Floating Point Hardware449671

  57677. Node: Vector Unit450203

  57678. Node: OS Information450590

  57679. Ref: linux info os infotypes452614

  57680. Node: Memory Region Attributes457205

  57681. Node: Dump/Restore Files461869

  57682. Node: Core File Generation464272

  57683. Ref: set use-coredump-filter465832

  57684. Ref: set dump-excluded-mappings467280

  57685. Node: Character Sets467562

  57686. Node: Caching Target Data473927

  57687. Ref: Caching Target Data-Footnote-1476667

  57688. Node: Searching Memory476905

  57689. Node: Value Sizes480048

  57690. Node: Optimized Code481700

  57691. Node: Inline Functions483377

  57692. Node: Tail Call Frames486004

  57693. Ref: set debug entry-values488141

  57694. Node: Macros492205

  57695. Ref: Macros-Footnote-1499781

  57696. Node: Tracepoints499934

  57697. Node: Set Tracepoints501996

  57698. Node: Create and Delete Tracepoints504934

  57699. Node: Enable and Disable Tracepoints511282

  57700. Node: Tracepoint Passcounts512522

  57701. Node: Tracepoint Conditions513933

  57702. Node: Trace State Variables515627

  57703. Node: Tracepoint Actions517822

  57704. Node: Listing Tracepoints524605

  57705. Node: Listing Static Tracepoint Markers526307

  57706. Node: Starting and Stopping Trace Experiments528155

  57707. Ref: disconnected tracing529900

  57708. Node: Tracepoint Restrictions534320

  57709. Node: Analyze Collected Data538089

  57710. Node: tfind539395

  57711. Node: tdump543877

  57712. Node: save tracepoints546392

  57713. Node: Tracepoint Variables546888

  57714. Node: Trace Files548016

  57715. Node: Overlays550392

  57716. Node: How Overlays Work551112

  57717. Ref: A code overlay553647

  57718. Node: Overlay Commands557080

  57719. Node: Automatic Overlay Debugging561262

  57720. Node: Overlay Sample Program563401

  57721. Node: Languages565138

  57722. Node: Setting566301

  57723. Node: Filenames568002

  57724. Node: Manually568813

  57725. Node: Automatically570022

  57726. Node: Show571083

  57727. Ref: show language571371

  57728. Node: Checks572405

  57729. Node: Type Checking573410

  57730. Node: Range Checking575239

  57731. Node: Supported Languages577640

  57732. Node: C578977

  57733. Node: C Operators579941

  57734. Node: C Constants584280

  57735. Node: C Plus Plus Expressions587159

  57736. Node: C Defaults590519

  57737. Node: C Checks591187

  57738. Node: Debugging C591747

  57739. Node: Debugging C Plus Plus592231

  57740. Node: Decimal Floating Point597118

  57741. Node: D598388

  57742. Node: Go598646

  57743. Node: Objective-C599740

  57744. Node: Method Names in Commands600203

  57745. Node: The Print Command with Objective-C601894

  57746. Node: OpenCL C602545

  57747. Node: OpenCL C Datatypes602820

  57748. Node: OpenCL C Expressions603195

  57749. Node: OpenCL C Operators603552

  57750. Node: Fortran603784

  57751. Node: Fortran Operators604505

  57752. Node: Fortran Defaults605550

  57753. Node: Special Fortran Commands605935

  57754. Node: Pascal606441

  57755. Node: Rust606952

  57756. Node: Modula-2610039

  57757. Node: M2 Operators611012

  57758. Node: Built-In Func/Proc614010

  57759. Node: M2 Constants616924

  57760. Node: M2 Types618525

  57761. Node: M2 Defaults621743

  57762. Node: Deviations622344

  57763. Node: M2 Checks623445

  57764. Node: M2 Scope624262

  57765. Node: GDB/M2625286

  57766. Node: Ada626199

  57767. Node: Ada Mode Intro627505

  57768. Node: Omissions from Ada629007

  57769. Node: Additions to Ada633362

  57770. Node: Overloading support for Ada637290

  57771. Node: Stopping Before Main Program638930

  57772. Node: Ada Exceptions639477

  57773. Node: Ada Tasks640676

  57774. Node: Ada Tasks and Core Files647167

  57775. Node: Ravenscar Profile648014

  57776. Node: Ada Settings650185

  57777. Node: Ada Glitches651607

  57778. Node: Unsupported Languages655615

  57779. Node: Symbols656305

  57780. Ref: quoting names656908

  57781. Node: Altering687823

  57782. Node: Assignment688861

  57783. Node: Jumping691967

  57784. Node: Signaling694041

  57785. Node: Returning696970

  57786. Node: Calling700321

  57787. Node: Patching705806

  57788. Node: Compiling and Injecting Code706920

  57789. Ref: set debug compile710547

  57790. Ref: set debug compile-cplus-types710797

  57791. Node: GDB Files720818

  57792. Node: Files721607

  57793. Ref: Shared Libraries735319

  57794. Ref: Files-Footnote-1747512

  57795. Node: File Caching747641

  57796. Node: Separate Debug Files748775

  57797. Ref: build ID750016

  57798. Ref: debug-file-directory752128

  57799. Node: MiniDebugInfo760743

  57800. Node: Index Files763194

  57801. Node: Symbol Errors767257

  57802. Node: Data Files770873

  57803. Node: Targets771829

  57804. Node: Active Targets773309

  57805. Node: Target Commands774383

  57806. Ref: load778772

  57807. Ref: flash-erase779965

  57808. Node: Byte Order780025

  57809. Node: Remote Debugging781464

  57810. Node: Connecting782726

  57811. Ref: --multi Option in Types of Remote Connnections784952

  57812. Ref: Attaching in Types of Remote Connections786367

  57813. Ref: Host and target files787247

  57814. Node: File Transfer795869

  57815. Node: Server796808

  57816. Ref: Running gdbserver798384

  57817. Ref: Attaching to a program800602

  57818. Ref: Other Command-Line Arguments for gdbserver803127

  57819. Ref: Monitor Commands for gdbserver806446

  57820. Ref: Server-Footnote-1811822

  57821. Node: Remote Configuration811942

  57822. Ref: set remotebreak813202

  57823. Ref: set remote hardware-watchpoint-limit814664

  57824. Ref: set remote hardware-breakpoint-limit814664

  57825. Ref: set remote hardware-watchpoint-length-limit815166

  57826. Ref: set remote exec-file815621

  57827. Node: Remote Stub827426

  57828. Node: Stub Contents830321

  57829. Node: Bootstrapping832428

  57830. Node: Debug Session836243

  57831. Node: Configurations838284

  57832. Node: Native839053

  57833. Node: BSD libkvm Interface839622

  57834. Node: Process Information840674

  57835. Node: DJGPP Native846298

  57836. Node: Cygwin Native852852

  57837. Node: Non-debug DLL Symbols857773

  57838. Node: Hurd Native862012

  57839. Node: Darwin867268

  57840. Node: FreeBSD868545

  57841. Node: Embedded OS869265

  57842. Node: Embedded Processors869676

  57843. Node: ARC870703

  57844. Node: ARM871250

  57845. Node: BPF873796

  57846. Node: M68K874276

  57847. Node: MicroBlaze874449

  57848. Node: MIPS Embedded875898

  57849. Node: OpenRISC 1000877195

  57850. Node: PowerPC Embedded878101

  57851. Node: AVR881330

  57852. Node: CRIS881702

  57853. Node: Super-H882680

  57854. Node: Architectures883739

  57855. Node: AArch64884135

  57856. Node: i386885708

  57857. Ref: i386-Footnote-1889918

  57858. Node: Alpha890004

  57859. Node: MIPS890137

  57860. Node: HPPA894031

  57861. Node: PowerPC894553

  57862. Node: Nios II895289

  57863. Node: Sparc64895694

  57864. Node: S12Z898062

  57865. Node: Controlling GDB898355

  57866. Node: Prompt899298

  57867. Node: Editing901016

  57868. Node: Command History902326

  57869. Node: Screen Size907520

  57870. Node: Output Styling909536

  57871. Node: Numbers913619

  57872. Node: ABI915601

  57873. Node: Auto-loading918774

  57874. Ref: set auto-load off920149

  57875. Ref: show auto-load920785

  57876. Ref: info auto-load921564

  57877. Node: Init File in the Current Directory924531

  57878. Ref: set auto-load local-gdbinit925106

  57879. Ref: show auto-load local-gdbinit925288

  57880. Ref: info auto-load local-gdbinit925452

  57881. Node: libthread_db.so.1 file925600

  57882. Ref: set auto-load libthread-db926539

  57883. Ref: show auto-load libthread-db926670

  57884. Ref: info auto-load libthread-db926807

  57885. Node: Auto-loading safe path926991

  57886. Ref: set auto-load safe-path928292

  57887. Ref: show auto-load safe-path929031

  57888. Ref: add-auto-load-safe-path929154

  57889. Node: Auto-loading verbose mode932056

  57890. Ref: set debug auto-load933219

  57891. Ref: show debug auto-load933320

  57892. Node: Messages/Warnings933442

  57893. Ref: confirmation requests934876

  57894. Node: Debugging Output936080

  57895. Node: Other Misc Settings946497

  57896. Node: Extending GDB947521

  57897. Node: Sequences949374

  57898. Node: Define950035

  57899. Node: Hooks955520

  57900. Node: Command Files957886

  57901. Node: Output962959

  57902. Ref: eval967761

  57903. Node: Auto-loading sequences967923

  57904. Ref: set auto-load gdb-scripts968418

  57905. Ref: show auto-load gdb-scripts968542

  57906. Ref: info auto-load gdb-scripts968672

  57907. Node: Python968903

  57908. Node: Python Commands970189

  57909. Node: Python API972303

  57910. Node: Basic Python975038

  57911. Ref: prompt_hook986075

  57912. Node: Exception Handling986673

  57913. Node: Values From Inferior989575

  57914. Node: Types In Python1006911

  57915. Node: Pretty Printing API1018141

  57916. Node: Selecting Pretty-Printers1022584

  57917. Node: Writing a Pretty-Printer1025311

  57918. Node: Type Printing API1030633

  57919. Node: Frame Filter API1033249

  57920. Node: Frame Decorator API1040561

  57921. Ref: frame_args1044302

  57922. Node: Writing a Frame Filter1047632

  57923. Node: Unwinding Frames in Python1059106

  57924. Node: Xmethods In Python1066901

  57925. Node: Xmethod API1069797

  57926. Node: Writing an Xmethod1073609

  57927. Node: Inferiors In Python1079444

  57928. Node: Events In Python1083215

  57929. Node: Threads In Python1092423

  57930. Node: Recordings In Python1095768

  57931. Node: Commands In Python1103102

  57932. Node: Parameters In Python1112693

  57933. Node: Functions In Python1119631

  57934. Node: Progspaces In Python1121848

  57935. Node: Objfiles In Python1126772

  57936. Node: Frames In Python1133429

  57937. Ref: gdbpy_frame_read_register1139646

  57938. Node: Blocks In Python1141331

  57939. Node: Symbols In Python1145998

  57940. Node: Symbol Tables In Python1155461

  57941. Node: Line Tables In Python1158682

  57942. Node: Breakpoints In Python1161519

  57943. Ref: python_breakpoint_thread1167842

  57944. Node: Finish Breakpoints in Python1170875

  57945. Node: Lazy Strings In Python1172981

  57946. Node: Architectures In Python1175209

  57947. Ref: gdbpy_architecture_registers1177426

  57948. Ref: gdbpy_architecture_reggroups1177747

  57949. Node: Registers In Python1177946

  57950. Node: TUI Windows In Python1180216

  57951. Node: Python Auto-loading1184443

  57952. Ref: set auto-load python-scripts1185072

  57953. Ref: show auto-load python-scripts1185172

  57954. Ref: info auto-load python-scripts1185278

  57955. Node: Python modules1186412

  57956. Node: gdb.printing1186798

  57957. Node: gdb.types1188225

  57958. Node: gdb.prompt1191237

  57959. Node: Guile1192833

  57960. Node: Guile Introduction1193492

  57961. Node: Guile Commands1194330

  57962. Node: Guile API1196184

  57963. Node: Basic Guile1198181

  57964. Node: Guile Configuration1203863

  57965. Node: GDB Scheme Data Types1204839

  57966. Node: Guile Exception Handling1206671

  57967. Node: Values From Inferior In Guile1210705

  57968. Node: Arithmetic In Guile1226241

  57969. Node: Types In Guile1227872

  57970. Ref: Fields of a type in Guile1235813

  57971. Node: Guile Pretty Printing API1237201

  57972. Node: Selecting Guile Pretty-Printers1242930

  57973. Node: Writing a Guile Pretty-Printer1245306

  57974. Node: Commands In Guile1250491

  57975. Node: Parameters In Guile1261271

  57976. Ref: Parameters In Guile-Footnote-11268152

  57977. Node: Progspaces In Guile1268268

  57978. Node: Objfiles In Guile1270880

  57979. Node: Frames In Guile1273161

  57980. Node: Blocks In Guile1279739

  57981. Node: Symbols In Guile1284547

  57982. Node: Symbol Tables In Guile1291882

  57983. Node: Breakpoints In Guile1294845

  57984. Node: Lazy Strings In Guile1305106

  57985. Node: Architectures In Guile1307397

  57986. Node: Disassembly In Guile1311704

  57987. Node: I/O Ports in Guile1314906

  57988. Node: Memory Ports in Guile1315462

  57989. Node: Iterators In Guile1319313

  57990. Node: Guile Auto-loading1323602

  57991. Ref: set auto-load guile-scripts1324225

  57992. Ref: show auto-load guile-scripts1324323

  57993. Ref: info auto-load guile-scripts1324427

  57994. Node: Guile Modules1325386

  57995. Node: Guile Printing Module1325708

  57996. Node: Guile Types Module1326527

  57997. Node: Auto-loading extensions1327820

  57998. Node: objfile-gdbdotext file1329018

  57999. Ref: set auto-load scripts-directory1330688

  58000. Ref: with-auto-load-dir1331064

  58001. Ref: show auto-load scripts-directory1331882

  58002. Ref: add-auto-load-scripts-directory1331962

  58003. Node: dotdebug_gdb_scripts section1332438

  58004. Node: Which flavor to choose?1336188

  58005. Node: Multiple Extension Languages1338009

  58006. Node: Aliases1339073

  58007. Node: Interpreters1342543

  58008. Node: TUI1345694

  58009. Node: TUI Overview1346692

  58010. Node: TUI Keys1349195

  58011. Node: TUI Single Key Mode1351918

  58012. Node: TUI Commands1353101

  58013. Node: TUI Configuration1358958

  58014. Node: Emacs1360980

  58015. Node: GDB/MI1366417

  58016. Node: GDB/MI General Design1369122

  58017. Node: Context management1371642

  58018. Node: Asynchronous and non-stop modes1375429

  58019. Node: Thread groups1378402

  58020. Node: GDB/MI Command Syntax1380692

  58021. Node: GDB/MI Input Syntax1380935

  58022. Node: GDB/MI Output Syntax1382485

  58023. Node: GDB/MI Compatibility with CLI1386070

  58024. Node: GDB/MI Development and Front Ends1386807

  58025. Node: GDB/MI Output Records1390322

  58026. Node: GDB/MI Result Records1390728

  58027. Node: GDB/MI Stream Records1392078

  58028. Node: GDB/MI Async Records1393343

  58029. Node: GDB/MI Breakpoint Information1403776

  58030. Node: GDB/MI Frame Information1409412

  58031. Node: GDB/MI Thread Information1410694

  58032. Node: GDB/MI Ada Exception Information1412164

  58033. Node: GDB/MI Simple Examples1412714

  58034. Node: GDB/MI Command Description Format1414950

  58035. Node: GDB/MI Breakpoint Commands1415830

  58036. Ref: -break-insert1422938

  58037. Node: GDB/MI Catchpoint Commands1436512

  58038. Node: Shared Library GDB/MI Catchpoint Commands1436925

  58039. Node: Ada Exception GDB/MI Catchpoint Commands1438583

  58040. Node: C++ Exception GDB/MI Catchpoint Commands1442133

  58041. Node: GDB/MI Program Context1446149

  58042. Node: GDB/MI Thread Commands1450417

  58043. Node: GDB/MI Ada Tasking Commands1453718

  58044. Node: GDB/MI Program Execution1455990

  58045. Node: GDB/MI Stack Manipulation1468257

  58046. Ref: -stack-list-arguments1470181

  58047. Ref: -stack-list-frames1474011

  58048. Ref: -stack-list-locals1478340

  58049. Ref: -stack-list-variables1479830

  58050. Node: GDB/MI Variable Objects1481364

  58051. Ref: -var-set-format1491330

  58052. Ref: -var-list-children1492711

  58053. Ref: -var-update1501519

  58054. Ref: -var-set-frozen1504517

  58055. Ref: -var-set-update-range1505314

  58056. Ref: -var-set-visualizer1505843

  58057. Node: GDB/MI Data Manipulation1507333

  58058. Node: GDB/MI Tracepoint Commands1527821

  58059. Node: GDB/MI Symbol Query1539612

  58060. Ref: -symbol-info-functions1539881

  58061. Ref: -symbol-info-module-functions1544394

  58062. Ref: -symbol-info-module-variables1547374

  58063. Ref: -symbol-info-modules1551091

  58064. Ref: -symbol-info-types1552995

  58065. Ref: -symbol-info-variables1554988

  58066. Node: GDB/MI File Commands1560012

  58067. Node: GDB/MI Target Manipulation1564446

  58068. Node: GDB/MI File Transfer Commands1571104

  58069. Node: GDB/MI Ada Exceptions Commands1572427

  58070. Node: GDB/MI Support Commands1573780

  58071. Node: GDB/MI Miscellaneous Commands1578499

  58072. Ref: -interpreter-exec1588863

  58073. Node: Annotations1592835

  58074. Node: Annotations Overview1593754

  58075. Node: Server Prefix1596217

  58076. Node: Prompting1596951

  58077. Node: Errors1598468

  58078. Node: Invalidation1599364

  58079. Node: Annotations for Running1599843

  58080. Node: Source Annotations1601377

  58081. Node: JIT Interface1602306

  58082. Node: Declarations1604106

  58083. Node: Registering Code1605493

  58084. Node: Unregistering Code1606465

  58085. Node: Custom Debug Info1607092

  58086. Node: Using JIT Debug Info Readers1608388

  58087. Node: Writing JIT Debug Info Readers1609400

  58088. Node: In-Process Agent1611595

  58089. Ref: Control Agent1613538

  58090. Node: In-Process Agent Protocol1614405

  58091. Node: IPA Protocol Objects1615196

  58092. Ref: agent expression object1616194

  58093. Ref: tracepoint action object1616399

  58094. Ref: tracepoint object1616479

  58095. Node: IPA Protocol Commands1619009

  58096. Node: GDB Bugs1620479

  58097. Node: Bug Criteria1621211

  58098. Node: Bug Reporting1622088

  58099. Node: Command Line Editing1629065

  58100. Node: Introduction and Notation1629717

  58101. Node: Readline Interaction1631338

  58102. Node: Readline Bare Essentials1632527

  58103. Node: Readline Movement Commands1634308

  58104. Node: Readline Killing Commands1635266

  58105. Node: Readline Arguments1637182

  58106. Node: Searching1638224

  58107. Node: Readline Init File1640374

  58108. Node: Readline Init File Syntax1641525

  58109. Node: Conditional Init Constructs1661681

  58110. Node: Sample Init File1665875

  58111. Node: Bindable Readline Commands1668990

  58112. Node: Commands For Moving1670042

  58113. Node: Commands For History1671606

  58114. Node: Commands For Text1675868

  58115. Node: Commands For Killing1679307

  58116. Node: Numeric Arguments1681471

  58117. Node: Commands For Completion1682608

  58118. Node: Keyboard Macros1684574

  58119. Node: Miscellaneous Commands1685259

  58120. Node: Readline vi Mode1689178

  58121. Node: Using History Interactively1690088

  58122. Node: History Interaction1690603

  58123. Node: Event Designators1692499

  58124. Node: Word Designators1693636

  58125. Node: Modifiers1695271

  58126. Node: In Memoriam1696492

  58127. Node: Formatting Documentation1697375

  58128. Ref: Formatting Documentation-Footnote-11700755

  58129. Node: Installing GDB1700853

  58130. Node: Requirements1701425

  58131. Ref: Expat1702126

  58132. Ref: MPFR1705419

  58133. Node: Running Configure1707040

  58134. Node: Separate Objdir1709922

  58135. Node: Config Names1712902

  58136. Node: Configure Options1714381

  58137. Node: System-wide configuration1724203

  58138. Node: System-wide Configuration Scripts1726740

  58139. Node: Maintenance Commands1727924

  58140. Ref: maint info breakpoints1729579

  58141. Ref: maint check libthread-db1738464

  58142. Node: Remote Protocol1755382

  58143. Node: Overview1756074

  58144. Ref: Binary Data1758619

  58145. Node: Packets1761275

  58146. Ref: thread-id syntax1762175

  58147. Ref: extended mode1763620

  58148. Ref: ? packet1763878

  58149. Ref: bc1765344

  58150. Ref: bs1765554

  58151. Ref: read registers packet1767171

  58152. Ref: cycle step packet1769026

  58153. Ref: write register packet1771737

  58154. Ref: step with signal packet1772716

  58155. Ref: vCont packet1774192

  58156. Ref: vCtrlC packet1777426

  58157. Ref: vKill packet1779844

  58158. Ref: X packet1781378

  58159. Ref: insert breakpoint or watchpoint packet1781747

  58160. Node: Stop Reply Packets1786073

  58161. Ref: swbreak stop reason1789324

  58162. Ref: thread create event1792921

  58163. Ref: thread exit event1794124

  58164. Node: General Query Packets1796333

  58165. Ref: qCRC packet1799163

  58166. Ref: QEnvironmentHexEncoded1802316

  58167. Ref: QEnvironmentUnset1803546

  58168. Ref: QEnvironmentReset1804490

  58169. Ref: QSetWorkingDir packet1805434

  58170. Ref: QNonStop1811885

  58171. Ref: QCatchSyscalls1812561

  58172. Ref: QPassSignals1814098

  58173. Ref: QProgramSignals1815305

  58174. Ref: QThreadEvents1816872

  58175. Ref: qSearch memory1818890

  58176. Ref: QStartNoAckMode1819398

  58177. Ref: qSupported1819930

  58178. Ref: multiprocess extensions1835450

  58179. Ref: install tracepoint in tracing1837480

  58180. Ref: qXfer read1842003

  58181. Ref: qXfer auxiliary vector read1843610

  58182. Ref: qXfer btrace read1843958

  58183. Ref: qXfer btrace-conf read1845023

  58184. Ref: qXfer executable filename read1845374

  58185. Ref: qXfer target description read1845989

  58186. Ref: qXfer library list read1846423

  58187. Ref: qXfer svr4 library list read1847079

  58188. Ref: qXfer memory map read1848932

  58189. Ref: qXfer sdata read1849319

  58190. Ref: qXfer siginfo read1849785

  58191. Ref: qXfer threads read1850181

  58192. Ref: qXfer traceframe info read1850584

  58193. Ref: qXfer unwind info block1851002

  58194. Ref: qXfer fdpic loadmap read1851236

  58195. Ref: qXfer osdata read1851652

  58196. Ref: qXfer write1851806

  58197. Ref: qXfer siginfo write1852898

  58198. Ref: General Query Packets-Footnote-11855626

  58199. Node: Architecture-Specific Protocol Details1855953

  58200. Node: ARM-Specific Protocol Details1856462

  58201. Node: ARM Breakpoint Kinds1856710

  58202. Node: MIPS-Specific Protocol Details1857041

  58203. Node: MIPS Register packet Format1857324

  58204. Node: MIPS Breakpoint Kinds1858251

  58205. Node: Tracepoint Packets1858669

  58206. Ref: QTEnable1867983

  58207. Ref: QTDisable1868179

  58208. Ref: qTfSTM1873716

  58209. Ref: qTsSTM1873716

  58210. Ref: qTSTMat1874793

  58211. Ref: QTBuffer-size1875944

  58212. Node: Host I/O Packets1877917

  58213. Node: Interrupts1883498

  58214. Ref: interrupting remote targets1883642

  58215. Node: Notification Packets1885810

  58216. Node: Remote Non-Stop1891235

  58217. Node: Packet Acknowledgment1894351

  58218. Node: Examples1896466

  58219. Node: File-I/O Remote Protocol Extension1897060

  58220. Node: File-I/O Overview1897522

  58221. Node: Protocol Basics1899721

  58222. Node: The F Request Packet1901950

  58223. Node: The F Reply Packet1902851

  58224. Node: The Ctrl-C Message1903769

  58225. Node: Console I/O1905395

  58226. Node: List of Supported Calls1906611

  58227. Node: open1906973

  58228. Node: close1909481

  58229. Node: read1909864

  58230. Node: write1910473

  58231. Node: lseek1911244

  58232. Node: rename1912128

  58233. Node: unlink1913535

  58234. Node: stat/fstat1914482

  58235. Node: gettimeofday1915375

  58236. Node: isatty1915811

  58237. Node: system1916407

  58238. Node: Protocol-specific Representation of Datatypes1917949

  58239. Node: Integral Datatypes1918326

  58240. Node: Pointer Values1919133

  58241. Node: Memory Transfer1919837

  58242. Node: struct stat1920457

  58243. Node: struct timeval1922659

  58244. Node: Constants1923176

  58245. Node: Open Flags1923625

  58246. Node: mode_t Values1923966

  58247. Node: Errno Values1924458

  58248. Node: Lseek Flags1925268

  58249. Node: Limits1925453

  58250. Node: File-I/O Examples1925813

  58251. Node: Library List Format1926901

  58252. Node: Library List Format for SVR4 Targets1929683

  58253. Node: Memory Map Format1932150

  58254. Node: Thread List Format1934674

  58255. Node: Traceframe Info Format1935678

  58256. Node: Branch Trace Format1937364

  58257. Node: Branch Trace Configuration Format1939064

  58258. Node: Agent Expressions1940238

  58259. Node: General Bytecode Design1943059

  58260. Node: Bytecode Descriptions1947853

  58261. Node: Using Agent Expressions1961320

  58262. Node: Varying Target Capabilities1963297

  58263. Node: Rationale1964458

  58264. Node: Target Descriptions1971847

  58265. Node: Retrieving Descriptions1973790

  58266. Node: Target Description Format1974875

  58267. Node: Predefined Target Types1984750

  58268. Node: Enum Target Types1986195

  58269. Node: Standard Target Features1987190

  58270. Node: AArch64 Features1989190

  58271. Node: ARC Features1989896

  58272. Ref: ARC Features-Footnote-11991715

  58273. Node: ARM Features1991748

  58274. Node: i386 Features1993262

  58275. Node: MicroBlaze Features1995477

  58276. Node: MIPS Features1996054

  58277. Node: M68K Features1997245

  58278. Node: NDS32 Features1998232

  58279. Node: Nios II Features1999256

  58280. Node: OpenRISC 1000 Features1999661

  58281. Node: PowerPC Features2000027

  58282. Node: RISC-V Features2003997

  58283. Node: RX Features2005687

  58284. Node: S/390 and System z Features2006049

  58285. Node: Sparc Features2008189

  58286. Node: TIC6x Features2009094

  58287. Node: Operating System Information2009643

  58288. Node: Process list2010479

  58289. Node: Trace File Format2011542

  58290. Node: Index Section Format2014756

  58291. Node: Man Pages2022682

  58292. Node: gdb man2023152

  58293. Node: gdbserver man2029126

  58294. Node: gcore man2036535

  58295. Node: gdbinit man2037657

  58296. Node: gdb-add-index man2039020

  58297. Ref: gdb-add-index2039129

  58298. Node: Copying2040003

  58299. Node: GNU Free Documentation License2077564

  58300. Node: Concept Index2102711

  58301. Node: Command and Variable Index2244493

  58302. 

  58303. End Tag Table