1 |
1181 |
sfurman |
This is gdb.info, produced by makeinfo version 4.1 from ./gdb.texinfo.
|
2 |
|
|
|
3 |
|
|
INFO-DIR-SECTION Programming & development tools.
|
4 |
|
|
START-INFO-DIR-ENTRY
|
5 |
|
|
* Gdb: (gdb). The GNU debugger.
|
6 |
|
|
END-INFO-DIR-ENTRY
|
7 |
|
|
|
8 |
|
|
This file documents the GNU debugger GDB.
|
9 |
|
|
|
10 |
|
|
This is the Ninth Edition, December 2001, of `Debugging with GDB:
|
11 |
|
|
the GNU Source-Level Debugger' for GDB Version 5.3.
|
12 |
|
|
|
13 |
|
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
14 |
|
|
1998,
|
15 |
|
|
1999, 2000, 2001, 2002 Free Software Foundation, Inc.
|
16 |
|
|
|
17 |
|
|
Permission is granted to copy, distribute and/or modify this document
|
18 |
|
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
19 |
|
|
any later version published by the Free Software Foundation; with the
|
20 |
|
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
21 |
|
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
22 |
|
|
with the Back-Cover Texts as in (a) below.
|
23 |
|
|
|
24 |
|
|
(a) The Free Software Foundation's Back-Cover Text is: "You have
|
25 |
|
|
freedom to copy and modify this GNU Manual, like GNU software. Copies
|
26 |
|
|
published by the Free Software Foundation raise funds for GNU
|
27 |
|
|
development."
|
28 |
|
|
|
29 |
|
|
|
30 |
|
|
File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
|
31 |
|
|
|
32 |
|
|
Debugging with GDB
|
33 |
|
|
******************
|
34 |
|
|
|
35 |
|
|
This file describes GDB, the GNU symbolic debugger.
|
36 |
|
|
|
37 |
|
|
This is the Ninth Edition, December 2001, for GDB Version 5.3.
|
38 |
|
|
|
39 |
|
|
Copyright (C) 1988-2002 Free Software Foundation, Inc.
|
40 |
|
|
|
41 |
|
|
* Menu:
|
42 |
|
|
|
43 |
|
|
* Summary:: Summary of GDB
|
44 |
|
|
* Sample Session:: A sample GDB session
|
45 |
|
|
|
46 |
|
|
* Invocation:: Getting in and out of GDB
|
47 |
|
|
* Commands:: GDB commands
|
48 |
|
|
* Running:: Running programs under GDB
|
49 |
|
|
* Stopping:: Stopping and continuing
|
50 |
|
|
* Stack:: Examining the stack
|
51 |
|
|
* Source:: Examining source files
|
52 |
|
|
* Data:: Examining data
|
53 |
|
|
* Macros:: Preprocessor Macros
|
54 |
|
|
* Tracepoints:: Debugging remote targets non-intrusively
|
55 |
|
|
* Overlays:: Debugging programs that use overlays
|
56 |
|
|
|
57 |
|
|
* Languages:: Using GDB with different languages
|
58 |
|
|
|
59 |
|
|
* Symbols:: Examining the symbol table
|
60 |
|
|
* Altering:: Altering execution
|
61 |
|
|
* GDB Files:: GDB files
|
62 |
|
|
* Targets:: Specifying a debugging target
|
63 |
|
|
* Remote Debugging:: Debugging remote programs
|
64 |
|
|
* Configurations:: Configuration-specific information
|
65 |
|
|
* Controlling GDB:: Controlling GDB
|
66 |
|
|
* Sequences:: Canned sequences of commands
|
67 |
|
|
* TUI:: GDB Text User Interface
|
68 |
|
|
* Emacs:: Using GDB under GNU Emacs
|
69 |
|
|
* Annotations:: GDB's annotation interface.
|
70 |
|
|
* GDB/MI:: GDB's Machine Interface.
|
71 |
|
|
|
72 |
|
|
* GDB Bugs:: Reporting bugs in GDB
|
73 |
|
|
* Formatting Documentation:: How to format and print GDB documentation
|
74 |
|
|
|
75 |
|
|
* Command Line Editing:: Command Line Editing
|
76 |
|
|
* Using History Interactively:: Using History Interactively
|
77 |
|
|
* Installing GDB:: Installing GDB
|
78 |
|
|
* Maintenance Commands:: Maintenance Commands
|
79 |
|
|
* Remote Protocol:: GDB Remote Serial Protocol
|
80 |
|
|
* Copying:: GNU General Public License says
|
81 |
|
|
how you can copy and share GDB
|
82 |
|
|
* GNU Free Documentation License:: The license for this documentation
|
83 |
|
|
* Index:: Index
|
84 |
|
|
|
85 |
|
|
|
86 |
|
|
File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top
|
87 |
|
|
|
88 |
|
|
Summary of GDB
|
89 |
|
|
**************
|
90 |
|
|
|
91 |
|
|
The purpose of a debugger such as GDB is to allow you to see what is
|
92 |
|
|
going on "inside" another program while it executes--or what another
|
93 |
|
|
program was doing at the moment it crashed.
|
94 |
|
|
|
95 |
|
|
GDB can do four main kinds of things (plus other things in support of
|
96 |
|
|
these) to help you catch bugs in the act:
|
97 |
|
|
|
98 |
|
|
* Start your program, specifying anything that might affect its
|
99 |
|
|
behavior.
|
100 |
|
|
|
101 |
|
|
* Make your program stop on specified conditions.
|
102 |
|
|
|
103 |
|
|
* Examine what has happened, when your program has stopped.
|
104 |
|
|
|
105 |
|
|
* Change things in your program, so you can experiment with
|
106 |
|
|
correcting the effects of one bug and go on to learn about another.
|
107 |
|
|
|
108 |
|
|
You can use GDB to debug programs written in C and C++. For more
|
109 |
|
|
information, see *Note Supported languages: Support. For more
|
110 |
|
|
information, see *Note C and C++: C.
|
111 |
|
|
|
112 |
|
|
Support for Modula-2 is partial. For information on Modula-2, see
|
113 |
|
|
*Note Modula-2: Modula-2.
|
114 |
|
|
|
115 |
|
|
Debugging Pascal programs which use sets, subranges, file variables,
|
116 |
|
|
or nested functions does not currently work. GDB does not support
|
117 |
|
|
entering expressions, printing values, or similar features using Pascal
|
118 |
|
|
syntax.
|
119 |
|
|
|
120 |
|
|
GDB can be used to debug programs written in Fortran, although it
|
121 |
|
|
may be necessary to refer to some variables with a trailing underscore.
|
122 |
|
|
|
123 |
|
|
* Menu:
|
124 |
|
|
|
125 |
|
|
* Free Software:: Freely redistributable software
|
126 |
|
|
* Contributors:: Contributors to GDB
|
127 |
|
|
|
128 |
|
|
|
129 |
|
|
File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary
|
130 |
|
|
|
131 |
|
|
Free software
|
132 |
|
|
=============
|
133 |
|
|
|
134 |
|
|
GDB is "free software", protected by the GNU General Public License
|
135 |
|
|
(GPL). The GPL gives you the freedom to copy or adapt a licensed
|
136 |
|
|
program--but every person getting a copy also gets with it the freedom
|
137 |
|
|
to modify that copy (which means that they must get access to the
|
138 |
|
|
source code), and the freedom to distribute further copies. Typical
|
139 |
|
|
software companies use copyrights to limit your freedoms; the Free
|
140 |
|
|
Software Foundation uses the GPL to preserve these freedoms.
|
141 |
|
|
|
142 |
|
|
Fundamentally, the General Public License is a license which says
|
143 |
|
|
that you have these freedoms and that you cannot take these freedoms
|
144 |
|
|
away from anyone else.
|
145 |
|
|
|
146 |
|
|
Free Software Needs Free Documentation
|
147 |
|
|
======================================
|
148 |
|
|
|
149 |
|
|
The biggest deficiency in the free software community today is not in
|
150 |
|
|
the software--it is the lack of good free documentation that we can
|
151 |
|
|
include with the free software. Many of our most important programs do
|
152 |
|
|
not come with free reference manuals and free introductory texts.
|
153 |
|
|
Documentation is an essential part of any software package; when an
|
154 |
|
|
important free software package does not come with a free manual and a
|
155 |
|
|
free tutorial, that is a major gap. We have many such gaps today.
|
156 |
|
|
|
157 |
|
|
Consider Perl, for instance. The tutorial manuals that people
|
158 |
|
|
normally use are non-free. How did this come about? Because the
|
159 |
|
|
authors of those manuals published them with restrictive terms--no
|
160 |
|
|
copying, no modification, source files not available--which exclude
|
161 |
|
|
them from the free software world.
|
162 |
|
|
|
163 |
|
|
That wasn't the first time this sort of thing happened, and it was
|
164 |
|
|
far from the last. Many times we have heard a GNU user eagerly
|
165 |
|
|
describe a manual that he is writing, his intended contribution to the
|
166 |
|
|
community, only to learn that he had ruined everything by signing a
|
167 |
|
|
publication contract to make it non-free.
|
168 |
|
|
|
169 |
|
|
Free documentation, like free software, is a matter of freedom, not
|
170 |
|
|
price. The problem with the non-free manual is not that publishers
|
171 |
|
|
charge a price for printed copies--that in itself is fine. (The Free
|
172 |
|
|
Software Foundation sells printed copies of manuals, too.) The problem
|
173 |
|
|
is the restrictions on the use of the manual. Free manuals are
|
174 |
|
|
available in source code form, and give you permission to copy and
|
175 |
|
|
modify. Non-free manuals do not allow this.
|
176 |
|
|
|
177 |
|
|
The criteria of freedom for a free manual are roughly the same as for
|
178 |
|
|
free software. Redistribution (including the normal kinds of
|
179 |
|
|
commercial redistribution) must be permitted, so that the manual can
|
180 |
|
|
accompany every copy of the program, both on-line and on paper.
|
181 |
|
|
|
182 |
|
|
Permission for modification of the technical content is crucial too.
|
183 |
|
|
When people modify the software, adding or changing features, if they
|
184 |
|
|
are conscientious they will change the manual too--so they can provide
|
185 |
|
|
accurate and clear documentation for the modified program. A manual
|
186 |
|
|
that leaves you no choice but to write a new manual to document a
|
187 |
|
|
changed version of the program is not really available to our community.
|
188 |
|
|
|
189 |
|
|
Some kinds of limits on the way modification is handled are
|
190 |
|
|
acceptable. For example, requirements to preserve the original
|
191 |
|
|
author's copyright notice, the distribution terms, or the list of
|
192 |
|
|
authors, are ok. It is also no problem to require modified versions to
|
193 |
|
|
include notice that they were modified. Even entire sections that may
|
194 |
|
|
not be deleted or changed are acceptable, as long as they deal with
|
195 |
|
|
nontechnical topics (like this one). These kinds of restrictions are
|
196 |
|
|
acceptable because they don't obstruct the community's normal use of
|
197 |
|
|
the manual.
|
198 |
|
|
|
199 |
|
|
However, it must be possible to modify all the _technical_ content
|
200 |
|
|
of the manual, and then distribute the result in all the usual media,
|
201 |
|
|
through all the usual channels. Otherwise, the restrictions obstruct
|
202 |
|
|
the use of the manual, it is not free, and we need another manual to
|
203 |
|
|
replace it.
|
204 |
|
|
|
205 |
|
|
Please spread the word about this issue. Our community continues to
|
206 |
|
|
lose manuals to proprietary publishing. If we spread the word that
|
207 |
|
|
free software needs free reference manuals and free tutorials, perhaps
|
208 |
|
|
the next person who wants to contribute by writing documentation will
|
209 |
|
|
realize, before it is too late, that only free manuals contribute to
|
210 |
|
|
the free software community.
|
211 |
|
|
|
212 |
|
|
If you are writing documentation, please insist on publishing it
|
213 |
|
|
under the GNU Free Documentation License or another free documentation
|
214 |
|
|
license. Remember that this decision requires your approval--you don't
|
215 |
|
|
have to let the publisher decide. Some commercial publishers will use
|
216 |
|
|
a free license if you insist, but they will not propose the option; it
|
217 |
|
|
is up to you to raise the issue and say firmly that this is what you
|
218 |
|
|
want. If the publisher you are dealing with refuses, please try other
|
219 |
|
|
publishers. If you're not sure whether a proposed license is free,
|
220 |
|
|
write to .
|
221 |
|
|
|
222 |
|
|
You can encourage commercial publishers to sell more free, copylefted
|
223 |
|
|
manuals and tutorials by buying them, and particularly by buying copies
|
224 |
|
|
from the publishers that paid for their writing or for major
|
225 |
|
|
improvements. Meanwhile, try to avoid buying non-free documentation at
|
226 |
|
|
all. Check the distribution terms of a manual before you buy it, and
|
227 |
|
|
insist that whoever seeks your business must respect your freedom.
|
228 |
|
|
Check the history of the book, and try to reward the publishers that
|
229 |
|
|
have paid or pay the authors to work on it.
|
230 |
|
|
|
231 |
|
|
The Free Software Foundation maintains a list of free documentation
|
232 |
|
|
published by other publishers, at
|
233 |
|
|
.
|
234 |
|
|
|
235 |
|
|
|
236 |
|
|
File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary
|
237 |
|
|
|
238 |
|
|
Contributors to GDB
|
239 |
|
|
===================
|
240 |
|
|
|
241 |
|
|
Richard Stallman was the original author of GDB, and of many other
|
242 |
|
|
GNU programs. Many others have contributed to its development. This
|
243 |
|
|
section attempts to credit major contributors. One of the virtues of
|
244 |
|
|
free software is that everyone is free to contribute to it; with
|
245 |
|
|
regret, we cannot actually acknowledge everyone here. The file
|
246 |
|
|
`ChangeLog' in the GDB distribution approximates a blow-by-blow account.
|
247 |
|
|
|
248 |
|
|
Changes much prior to version 2.0 are lost in the mists of time.
|
249 |
|
|
|
250 |
|
|
_Plea:_ Additions to this section are particularly welcome. If you
|
251 |
|
|
or your friends (or enemies, to be evenhanded) have been unfairly
|
252 |
|
|
omitted from this list, we would like to add your names!
|
253 |
|
|
|
254 |
|
|
So that they may not regard their many labors as thankless, we
|
255 |
|
|
particularly thank those who shepherded GDB through major releases:
|
256 |
|
|
Andrew Cagney (releases 5.3, 5.2, 5.1 and 5.0); Jim Blandy (release
|
257 |
|
|
4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); Fred
|
258 |
|
|
Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); Stu
|
259 |
|
|
Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); John
|
260 |
|
|
Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases
|
261 |
|
|
3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and 3.0).
|
262 |
|
|
|
263 |
|
|
Richard Stallman, assisted at various times by Peter TerMaat, Chris
|
264 |
|
|
Hanson, and Richard Mlynarik, handled releases through 2.8.
|
265 |
|
|
|
266 |
|
|
Michael Tiemann is the author of most of the GNU C++ support in GDB,
|
267 |
|
|
with significant additional contributions from Per Bothner and Daniel
|
268 |
|
|
Berlin. James Clark wrote the GNU C++ demangler. Early work on C++
|
269 |
|
|
was by Peter TerMaat (who also did much general update work leading to
|
270 |
|
|
release 3.0).
|
271 |
|
|
|
272 |
|
|
GDB uses the BFD subroutine library to examine multiple object-file
|
273 |
|
|
formats; BFD was a joint project of David V. Henkel-Wallace, Rich
|
274 |
|
|
Pixley, Steve Chamberlain, and John Gilmore.
|
275 |
|
|
|
276 |
|
|
David Johnson wrote the original COFF support; Pace Willison did the
|
277 |
|
|
original support for encapsulated COFF.
|
278 |
|
|
|
279 |
|
|
Brent Benson of Harris Computer Systems contributed DWARF2 support.
|
280 |
|
|
|
281 |
|
|
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
|
282 |
|
|
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
|
283 |
|
|
support. Jean-Daniel Fekete contributed Sun 386i support. Chris
|
284 |
|
|
Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
|
285 |
|
|
Hasei contributed Sony/News OS 3 support. David Johnson contributed
|
286 |
|
|
Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
|
287 |
|
|
Jeff Law contributed HP PA and SOM support. Keith Packard contributed
|
288 |
|
|
NS32K support. Doug Rabson contributed Acorn Risc Machine support.
|
289 |
|
|
Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
|
290 |
|
|
contributed Convex support (and Fortran debugging). Jonathan Stone
|
291 |
|
|
contributed Pyramid support. Michael Tiemann contributed SPARC support.
|
292 |
|
|
Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
|
293 |
|
|
Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
|
294 |
|
|
Symmetry support.
|
295 |
|
|
|
296 |
|
|
Andreas Schwab contributed M68K GNU/Linux support.
|
297 |
|
|
|
298 |
|
|
Rich Schaefer and Peter Schauer helped with support of SunOS shared
|
299 |
|
|
libraries.
|
300 |
|
|
|
301 |
|
|
Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
|
302 |
|
|
several machine instruction sets.
|
303 |
|
|
|
304 |
|
|
Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
|
305 |
|
|
develop remote debugging. Intel Corporation, Wind River Systems, AMD,
|
306 |
|
|
and ARM contributed remote debugging modules for the i960, VxWorks,
|
307 |
|
|
A29K UDI, and RDI targets, respectively.
|
308 |
|
|
|
309 |
|
|
Brian Fox is the author of the readline libraries providing
|
310 |
|
|
command-line editing and command history.
|
311 |
|
|
|
312 |
|
|
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
|
313 |
|
|
Modula-2 support, and contributed the Languages chapter of this manual.
|
314 |
|
|
|
315 |
|
|
Fred Fish wrote most of the support for Unix System Vr4. He also
|
316 |
|
|
enhanced the command-completion support to cover C++ overloaded symbols.
|
317 |
|
|
|
318 |
|
|
Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
|
319 |
|
|
Super-H processors.
|
320 |
|
|
|
321 |
|
|
NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
|
322 |
|
|
processors.
|
323 |
|
|
|
324 |
|
|
Mitsubishi sponsored the support for D10V, D30V, and M32R/D
|
325 |
|
|
processors.
|
326 |
|
|
|
327 |
|
|
Toshiba sponsored the support for the TX39 Mips processor.
|
328 |
|
|
|
329 |
|
|
Matsushita sponsored the support for the MN10200 and MN10300
|
330 |
|
|
processors.
|
331 |
|
|
|
332 |
|
|
Fujitsu sponsored the support for SPARClite and FR30 processors.
|
333 |
|
|
|
334 |
|
|
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
|
335 |
|
|
watchpoints.
|
336 |
|
|
|
337 |
|
|
Michael Snyder added support for tracepoints.
|
338 |
|
|
|
339 |
|
|
Stu Grossman wrote gdbserver.
|
340 |
|
|
|
341 |
|
|
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
|
342 |
|
|
innumerable bug fixes and cleanups throughout GDB.
|
343 |
|
|
|
344 |
|
|
The following people at the Hewlett-Packard Company contributed
|
345 |
|
|
support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
|
346 |
|
|
(narrow mode), HP's implementation of kernel threads, HP's aC++
|
347 |
|
|
compiler, and the terminal user interface: Ben Krepp, Richard Title,
|
348 |
|
|
John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
|
349 |
|
|
Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
|
350 |
|
|
information in this manual.
|
351 |
|
|
|
352 |
|
|
DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
|
353 |
|
|
Hoehne made significant contributions to the DJGPP port.
|
354 |
|
|
|
355 |
|
|
Cygnus Solutions has sponsored GDB maintenance and much of its
|
356 |
|
|
development since 1991. Cygnus engineers who have worked on GDB
|
357 |
|
|
fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
|
358 |
|
|
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
|
359 |
|
|
Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
|
360 |
|
|
Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
|
361 |
|
|
Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
|
362 |
|
|
addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
|
363 |
|
|
JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
|
364 |
|
|
Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
|
365 |
|
|
Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
|
366 |
|
|
Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
|
367 |
|
|
Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
|
368 |
|
|
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
|
369 |
|
|
Zuhn have made contributions both large and small.
|
370 |
|
|
|
371 |
|
|
Jim Blandy added support for preprocessor macros, while working for
|
372 |
|
|
Red Hat.
|
373 |
|
|
|
374 |
|
|
|
375 |
|
|
File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
|
376 |
|
|
|
377 |
|
|
A Sample GDB Session
|
378 |
|
|
********************
|
379 |
|
|
|
380 |
|
|
You can use this manual at your leisure to read all about GDB.
|
381 |
|
|
However, a handful of commands are enough to get started using the
|
382 |
|
|
debugger. This chapter illustrates those commands.
|
383 |
|
|
|
384 |
|
|
One of the preliminary versions of GNU `m4' (a generic macro
|
385 |
|
|
processor) exhibits the following bug: sometimes, when we change its
|
386 |
|
|
quote strings from the default, the commands used to capture one macro
|
387 |
|
|
definition within another stop working. In the following short `m4'
|
388 |
|
|
session, we define a macro `foo' which expands to `0000'; we then use
|
389 |
|
|
the `m4' built-in `defn' to define `bar' as the same thing. However,
|
390 |
|
|
when we change the open quote string to `' and the close quote
|
391 |
|
|
string to `', the same procedure fails to define a new synonym
|
392 |
|
|
`baz':
|
393 |
|
|
|
394 |
|
|
$ cd gnu/m4
|
395 |
|
|
$ ./m4
|
396 |
|
|
define(foo,0000)
|
397 |
|
|
|
398 |
|
|
foo
|
399 |
|
|
0000
|
400 |
|
|
define(bar,defn(`foo'))
|
401 |
|
|
|
402 |
|
|
bar
|
403 |
|
|
0000
|
404 |
|
|
changequote(,)
|
405 |
|
|
|
406 |
|
|
define(baz,defn(foo))
|
407 |
|
|
baz
|
408 |
|
|
C-d
|
409 |
|
|
m4: End of input: 0: fatal error: EOF in string
|
410 |
|
|
|
411 |
|
|
Let us use GDB to try to see what is going on.
|
412 |
|
|
|
413 |
|
|
$ gdb m4
|
414 |
|
|
GDB is free software and you are welcome to distribute copies
|
415 |
|
|
of it under certain conditions; type "show copying" to see
|
416 |
|
|
the conditions.
|
417 |
|
|
There is absolutely no warranty for GDB; type "show warranty"
|
418 |
|
|
for details.
|
419 |
|
|
|
420 |
|
|
GDB 5.3, Copyright 1999 Free Software Foundation, Inc...
|
421 |
|
|
(gdb)
|
422 |
|
|
|
423 |
|
|
GDB reads only enough symbol data to know where to find the rest when
|
424 |
|
|
needed; as a result, the first prompt comes up very quickly. We now
|
425 |
|
|
tell GDB to use a narrower display width than usual, so that examples
|
426 |
|
|
fit in this manual.
|
427 |
|
|
|
428 |
|
|
(gdb) set width 70
|
429 |
|
|
|
430 |
|
|
We need to see how the `m4' built-in `changequote' works. Having
|
431 |
|
|
looked at the source, we know the relevant subroutine is
|
432 |
|
|
`m4_changequote', so we set a breakpoint there with the GDB `break'
|
433 |
|
|
command.
|
434 |
|
|
|
435 |
|
|
(gdb) break m4_changequote
|
436 |
|
|
Breakpoint 1 at 0x62f4: file builtin.c, line 879.
|
437 |
|
|
|
438 |
|
|
Using the `run' command, we start `m4' running under GDB control; as
|
439 |
|
|
long as control does not reach the `m4_changequote' subroutine, the
|
440 |
|
|
program runs as usual:
|
441 |
|
|
|
442 |
|
|
(gdb) run
|
443 |
|
|
Starting program: /work/Editorial/gdb/gnu/m4/m4
|
444 |
|
|
define(foo,0000)
|
445 |
|
|
|
446 |
|
|
foo
|
447 |
|
|
0000
|
448 |
|
|
|
449 |
|
|
To trigger the breakpoint, we call `changequote'. GDB suspends
|
450 |
|
|
execution of `m4', displaying information about the context where it
|
451 |
|
|
stops.
|
452 |
|
|
|
453 |
|
|
changequote(,)
|
454 |
|
|
|
455 |
|
|
Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
|
456 |
|
|
at builtin.c:879
|
457 |
|
|
879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
|
458 |
|
|
|
459 |
|
|
Now we use the command `n' (`next') to advance execution to the next
|
460 |
|
|
line of the current function.
|
461 |
|
|
|
462 |
|
|
(gdb) n
|
463 |
|
|
882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
|
464 |
|
|
: nil,
|
465 |
|
|
|
466 |
|
|
`set_quotes' looks like a promising subroutine. We can go into it by
|
467 |
|
|
using the command `s' (`step') instead of `next'. `step' goes to the
|
468 |
|
|
next line to be executed in _any_ subroutine, so it steps into
|
469 |
|
|
`set_quotes'.
|
470 |
|
|
|
471 |
|
|
(gdb) s
|
472 |
|
|
set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
473 |
|
|
at input.c:530
|
474 |
|
|
530 if (lquote != def_lquote)
|
475 |
|
|
|
476 |
|
|
The display that shows the subroutine where `m4' is now suspended (and
|
477 |
|
|
its arguments) is called a stack frame display. It shows a summary of
|
478 |
|
|
the stack. We can use the `backtrace' command (which can also be
|
479 |
|
|
spelled `bt'), to see where we are in the stack as a whole: the
|
480 |
|
|
`backtrace' command displays a stack frame for each active subroutine.
|
481 |
|
|
|
482 |
|
|
(gdb) bt
|
483 |
|
|
#0 set_quotes (lq=0x34c78 "", rq=0x34c88 "")
|
484 |
|
|
at input.c:530
|
485 |
|
|
#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
|
486 |
|
|
at builtin.c:882
|
487 |
|
|
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
|
488 |
|
|
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
|
489 |
|
|
at macro.c:71
|
490 |
|
|
#4 0x79dc in expand_input () at macro.c:40
|
491 |
|
|
#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
|
492 |
|
|
|
493 |
|
|
We step through a few more lines to see what happens. The first two
|
494 |
|
|
times, we can use `s'; the next two times we use `n' to avoid falling
|
495 |
|
|
into the `xstrdup' subroutine.
|
496 |
|
|
|
497 |
|
|
(gdb) s
|
498 |
|
|
0x3b5c 532 if (rquote != def_rquote)
|
499 |
|
|
(gdb) s
|
500 |
|
|
0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
|
501 |
|
|
def_lquote : xstrdup(lq);
|
502 |
|
|
(gdb) n
|
503 |
|
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
504 |
|
|
: xstrdup(rq);
|
505 |
|
|
(gdb) n
|
506 |
|
|
538 len_lquote = strlen(rquote);
|
507 |
|
|
|
508 |
|
|
The last line displayed looks a little odd; we can examine the variables
|
509 |
|
|
`lquote' and `rquote' to see if they are in fact the new left and right
|
510 |
|
|
quotes we specified. We use the command `p' (`print') to see their
|
511 |
|
|
values.
|
512 |
|
|
|
513 |
|
|
(gdb) p lquote
|
514 |
|
|
$1 = 0x35d40 ""
|
515 |
|
|
(gdb) p rquote
|
516 |
|
|
$2 = 0x35d50 ""
|
517 |
|
|
|
518 |
|
|
`lquote' and `rquote' are indeed the new left and right quotes. To
|
519 |
|
|
look at some context, we can display ten lines of source surrounding
|
520 |
|
|
the current line with the `l' (`list') command.
|
521 |
|
|
|
522 |
|
|
(gdb) l
|
523 |
|
|
533 xfree(rquote);
|
524 |
|
|
534
|
525 |
|
|
535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
|
526 |
|
|
: xstrdup (lq);
|
527 |
|
|
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
|
528 |
|
|
: xstrdup (rq);
|
529 |
|
|
537
|
530 |
|
|
538 len_lquote = strlen(rquote);
|
531 |
|
|
539 len_rquote = strlen(lquote);
|
532 |
|
|
540 }
|
533 |
|
|
541
|
534 |
|
|
542 void
|
535 |
|
|
|
536 |
|
|
Let us step past the two lines that set `len_lquote' and `len_rquote',
|
537 |
|
|
and then examine the values of those variables.
|
538 |
|
|
|
539 |
|
|
(gdb) n
|
540 |
|
|
539 len_rquote = strlen(lquote);
|
541 |
|
|
(gdb) n
|
542 |
|
|
540 }
|
543 |
|
|
(gdb) p len_lquote
|
544 |
|
|
$3 = 9
|
545 |
|
|
(gdb) p len_rquote
|
546 |
|
|
$4 = 7
|
547 |
|
|
|
548 |
|
|
That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
|
549 |
|
|
meant to be the lengths of `lquote' and `rquote' respectively. We can
|
550 |
|
|
set them to better values using the `p' command, since it can print the
|
551 |
|
|
value of any expression--and that expression can include subroutine
|
552 |
|
|
calls and assignments.
|
553 |
|
|
|
554 |
|
|
(gdb) p len_lquote=strlen(lquote)
|
555 |
|
|
$5 = 7
|
556 |
|
|
(gdb) p len_rquote=strlen(rquote)
|
557 |
|
|
$6 = 9
|
558 |
|
|
|
559 |
|
|
Is that enough to fix the problem of using the new quotes with the `m4'
|
560 |
|
|
built-in `defn'? We can allow `m4' to continue executing with the `c'
|
561 |
|
|
(`continue') command, and then try the example that caused trouble
|
562 |
|
|
initially:
|
563 |
|
|
|
564 |
|
|
(gdb) c
|
565 |
|
|
Continuing.
|
566 |
|
|
|
567 |
|
|
define(baz,defn(foo))
|
568 |
|
|
|
569 |
|
|
baz
|
570 |
|
|
0000
|
571 |
|
|
|
572 |
|
|
Success! The new quotes now work just as well as the default ones. The
|
573 |
|
|
problem seems to have been just the two typos defining the wrong
|
574 |
|
|
lengths. We allow `m4' exit by giving it an EOF as input:
|
575 |
|
|
|
576 |
|
|
C-d
|
577 |
|
|
Program exited normally.
|
578 |
|
|
|
579 |
|
|
The message `Program exited normally.' is from GDB; it indicates `m4'
|
580 |
|
|
has finished executing. We can end our GDB session with the GDB `quit'
|
581 |
|
|
command.
|
582 |
|
|
|
583 |
|
|
(gdb) quit
|
584 |
|
|
|
585 |
|
|
|
586 |
|
|
File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
|
587 |
|
|
|
588 |
|
|
Getting In and Out of GDB
|
589 |
|
|
*************************
|
590 |
|
|
|
591 |
|
|
This chapter discusses how to start GDB, and how to get out of it.
|
592 |
|
|
The essentials are:
|
593 |
|
|
* type `gdb' to start GDB.
|
594 |
|
|
|
595 |
|
|
* type `quit' or `C-d' to exit.
|
596 |
|
|
|
597 |
|
|
* Menu:
|
598 |
|
|
|
599 |
|
|
* Invoking GDB:: How to start GDB
|
600 |
|
|
* Quitting GDB:: How to quit GDB
|
601 |
|
|
* Shell Commands:: How to use shell commands inside GDB
|
602 |
|
|
|
603 |
|
|
|
604 |
|
|
File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
|
605 |
|
|
|
606 |
|
|
Invoking GDB
|
607 |
|
|
============
|
608 |
|
|
|
609 |
|
|
Invoke GDB by running the program `gdb'. Once started, GDB reads
|
610 |
|
|
commands from the terminal until you tell it to exit.
|
611 |
|
|
|
612 |
|
|
You can also run `gdb' with a variety of arguments and options, to
|
613 |
|
|
specify more of your debugging environment at the outset.
|
614 |
|
|
|
615 |
|
|
The command-line options described here are designed to cover a
|
616 |
|
|
variety of situations; in some environments, some of these options may
|
617 |
|
|
effectively be unavailable.
|
618 |
|
|
|
619 |
|
|
The most usual way to start GDB is with one argument, specifying an
|
620 |
|
|
executable program:
|
621 |
|
|
|
622 |
|
|
gdb PROGRAM
|
623 |
|
|
|
624 |
|
|
You can also start with both an executable program and a core file
|
625 |
|
|
specified:
|
626 |
|
|
|
627 |
|
|
gdb PROGRAM CORE
|
628 |
|
|
|
629 |
|
|
You can, instead, specify a process ID as a second argument, if you
|
630 |
|
|
want to debug a running process:
|
631 |
|
|
|
632 |
|
|
gdb PROGRAM 1234
|
633 |
|
|
|
634 |
|
|
would attach GDB to process `1234' (unless you also have a file named
|
635 |
|
|
`1234'; GDB does check for a core file first).
|
636 |
|
|
|
637 |
|
|
Taking advantage of the second command-line argument requires a
|
638 |
|
|
fairly complete operating system; when you use GDB as a remote debugger
|
639 |
|
|
attached to a bare board, there may not be any notion of "process", and
|
640 |
|
|
there is often no way to get a core dump. GDB will warn you if it is
|
641 |
|
|
unable to attach or to read core dumps.
|
642 |
|
|
|
643 |
|
|
You can optionally have `gdb' pass any arguments after the
|
644 |
|
|
executable file to the inferior using `--args'. This option stops
|
645 |
|
|
option processing.
|
646 |
|
|
gdb --args gcc -O2 -c foo.c
|
647 |
|
|
This will cause `gdb' to debug `gcc', and to set `gcc''s
|
648 |
|
|
command-line arguments (*note Arguments::) to `-O2 -c foo.c'.
|
649 |
|
|
|
650 |
|
|
You can run `gdb' without printing the front material, which
|
651 |
|
|
describes GDB's non-warranty, by specifying `-silent':
|
652 |
|
|
|
653 |
|
|
gdb -silent
|
654 |
|
|
|
655 |
|
|
You can further control how GDB starts up by using command-line
|
656 |
|
|
options. GDB itself can remind you of the options available.
|
657 |
|
|
|
658 |
|
|
Type
|
659 |
|
|
|
660 |
|
|
gdb -help
|
661 |
|
|
|
662 |
|
|
to display all available options and briefly describe their use (`gdb
|
663 |
|
|
-h' is a shorter equivalent).
|
664 |
|
|
|
665 |
|
|
All options and command line arguments you give are processed in
|
666 |
|
|
sequential order. The order makes a difference when the `-x' option is
|
667 |
|
|
used.
|
668 |
|
|
|
669 |
|
|
* Menu:
|
670 |
|
|
|
671 |
|
|
* File Options:: Choosing files
|
672 |
|
|
* Mode Options:: Choosing modes
|
673 |
|
|
|
674 |
|
|
|
675 |
|
|
File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
|
676 |
|
|
|
677 |
|
|
Choosing files
|
678 |
|
|
--------------
|
679 |
|
|
|
680 |
|
|
When GDB starts, it reads any arguments other than options as
|
681 |
|
|
specifying an executable file and core file (or process ID). This is
|
682 |
|
|
the same as if the arguments were specified by the `-se' and `-c' (or
|
683 |
|
|
`-p' options respectively. (GDB reads the first argument that does not
|
684 |
|
|
have an associated option flag as equivalent to the `-se' option
|
685 |
|
|
followed by that argument; and the second argument that does not have
|
686 |
|
|
an associated option flag, if any, as equivalent to the `-c'/`-p'
|
687 |
|
|
option followed by that argument.) If the second argument begins with
|
688 |
|
|
a decimal digit, GDB will first attempt to attach to it as a process,
|
689 |
|
|
and if that fails, attempt to open it as a corefile. If you have a
|
690 |
|
|
corefile whose name begins with a digit, you can prevent GDB from
|
691 |
|
|
treating it as a pid by prefixing it with `./', eg. `./12345'.
|
692 |
|
|
|
693 |
|
|
If GDB has not been configured to included core file support, such
|
694 |
|
|
as for most embedded targets, then it will complain about a second
|
695 |
|
|
argument and ignore it.
|
696 |
|
|
|
697 |
|
|
Many options have both long and short forms; both are shown in the
|
698 |
|
|
following list. GDB also recognizes the long forms if you truncate
|
699 |
|
|
them, so long as enough of the option is present to be unambiguous.
|
700 |
|
|
(If you prefer, you can flag option arguments with `--' rather than
|
701 |
|
|
`-', though we illustrate the more usual convention.)
|
702 |
|
|
|
703 |
|
|
`-symbols FILE'
|
704 |
|
|
`-s FILE'
|
705 |
|
|
Read symbol table from file FILE.
|
706 |
|
|
|
707 |
|
|
`-exec FILE'
|
708 |
|
|
`-e FILE'
|
709 |
|
|
Use file FILE as the executable file to execute when appropriate,
|
710 |
|
|
and for examining pure data in conjunction with a core dump.
|
711 |
|
|
|
712 |
|
|
`-se FILE'
|
713 |
|
|
Read symbol table from file FILE and use it as the executable file.
|
714 |
|
|
|
715 |
|
|
`-core FILE'
|
716 |
|
|
`-c FILE'
|
717 |
|
|
Use file FILE as a core dump to examine.
|
718 |
|
|
|
719 |
|
|
`-c NUMBER'
|
720 |
|
|
|
721 |
|
|
`-pid NUMBER'
|
722 |
|
|
`-p NUMBER'
|
723 |
|
|
Connect to process ID NUMBER, as with the `attach' command. If
|
724 |
|
|
there is no such process, GDB will attempt to open a core file
|
725 |
|
|
named NUMBER.
|
726 |
|
|
|
727 |
|
|
`-command FILE'
|
728 |
|
|
`-x FILE'
|
729 |
|
|
Execute GDB commands from file FILE. *Note Command files: Command
|
730 |
|
|
Files.
|
731 |
|
|
|
732 |
|
|
`-directory DIRECTORY'
|
733 |
|
|
`-d DIRECTORY'
|
734 |
|
|
Add DIRECTORY to the path to search for source files.
|
735 |
|
|
|
736 |
|
|
`-m'
|
737 |
|
|
`-mapped'
|
738 |
|
|
_Warning: this option depends on operating system facilities that
|
739 |
|
|
are not supported on all systems._
|
740 |
|
|
If memory-mapped files are available on your system through the
|
741 |
|
|
`mmap' system call, you can use this option to have GDB write the
|
742 |
|
|
symbols from your program into a reusable file in the current
|
743 |
|
|
directory. If the program you are debugging is called
|
744 |
|
|
`/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future
|
745 |
|
|
GDB debugging sessions notice the presence of this file, and can
|
746 |
|
|
quickly map in symbol information from it, rather than reading the
|
747 |
|
|
symbol table from the executable program.
|
748 |
|
|
|
749 |
|
|
The `.syms' file is specific to the host machine where GDB is run.
|
750 |
|
|
It holds an exact image of the internal GDB symbol table. It
|
751 |
|
|
cannot be shared across multiple host platforms.
|
752 |
|
|
|
753 |
|
|
`-r'
|
754 |
|
|
`-readnow'
|
755 |
|
|
Read each symbol file's entire symbol table immediately, rather
|
756 |
|
|
than the default, which is to read it incrementally as it is
|
757 |
|
|
needed. This makes startup slower, but makes future operations
|
758 |
|
|
faster.
|
759 |
|
|
|
760 |
|
|
You typically combine the `-mapped' and `-readnow' options in order
|
761 |
|
|
to build a `.syms' file that contains complete symbol information.
|
762 |
|
|
(*Note Commands to specify files: Files, for information on `.syms'
|
763 |
|
|
files.) A simple GDB invocation to do nothing but build a `.syms' file
|
764 |
|
|
for future use is:
|
765 |
|
|
|
766 |
|
|
gdb -batch -nx -mapped -readnow programname
|
767 |
|
|
|
768 |
|
|
|
769 |
|
|
File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB
|
770 |
|
|
|
771 |
|
|
Choosing modes
|
772 |
|
|
--------------
|
773 |
|
|
|
774 |
|
|
You can run GDB in various alternative modes--for example, in batch
|
775 |
|
|
mode or quiet mode.
|
776 |
|
|
|
777 |
|
|
`-nx'
|
778 |
|
|
`-n'
|
779 |
|
|
Do not execute commands found in any initialization files.
|
780 |
|
|
Normally, GDB executes the commands in these files after all the
|
781 |
|
|
command options and arguments have been processed. *Note Command
|
782 |
|
|
files: Command Files.
|
783 |
|
|
|
784 |
|
|
`-quiet'
|
785 |
|
|
`-silent'
|
786 |
|
|
`-q'
|
787 |
|
|
"Quiet". Do not print the introductory and copyright messages.
|
788 |
|
|
These messages are also suppressed in batch mode.
|
789 |
|
|
|
790 |
|
|
`-batch'
|
791 |
|
|
Run in batch mode. Exit with status `0' after processing all the
|
792 |
|
|
command files specified with `-x' (and all commands from
|
793 |
|
|
initialization files, if not inhibited with `-n'). Exit with
|
794 |
|
|
nonzero status if an error occurs in executing the GDB commands in
|
795 |
|
|
the command files.
|
796 |
|
|
|
797 |
|
|
Batch mode may be useful for running GDB as a filter, for example
|
798 |
|
|
to download and run a program on another computer; in order to
|
799 |
|
|
make this more useful, the message
|
800 |
|
|
|
801 |
|
|
Program exited normally.
|
802 |
|
|
|
803 |
|
|
(which is ordinarily issued whenever a program running under GDB
|
804 |
|
|
control terminates) is not issued when running in batch mode.
|
805 |
|
|
|
806 |
|
|
`-nowindows'
|
807 |
|
|
`-nw'
|
808 |
|
|
"No windows". If GDB comes with a graphical user interface (GUI)
|
809 |
|
|
built in, then this option tells GDB to only use the command-line
|
810 |
|
|
interface. If no GUI is available, this option has no effect.
|
811 |
|
|
|
812 |
|
|
`-windows'
|
813 |
|
|
`-w'
|
814 |
|
|
If GDB includes a GUI, then this option requires it to be used if
|
815 |
|
|
possible.
|
816 |
|
|
|
817 |
|
|
`-cd DIRECTORY'
|
818 |
|
|
Run GDB using DIRECTORY as its working directory, instead of the
|
819 |
|
|
current directory.
|
820 |
|
|
|
821 |
|
|
`-fullname'
|
822 |
|
|
`-f'
|
823 |
|
|
GNU Emacs sets this option when it runs GDB as a subprocess. It
|
824 |
|
|
tells GDB to output the full file name and line number in a
|
825 |
|
|
standard, recognizable fashion each time a stack frame is
|
826 |
|
|
displayed (which includes each time your program stops). This
|
827 |
|
|
recognizable format looks like two `\032' characters, followed by
|
828 |
|
|
the file name, line number and character position separated by
|
829 |
|
|
colons, and a newline. The Emacs-to-GDB interface program uses
|
830 |
|
|
the two `\032' characters as a signal to display the source code
|
831 |
|
|
for the frame.
|
832 |
|
|
|
833 |
|
|
`-epoch'
|
834 |
|
|
The Epoch Emacs-GDB interface sets this option when it runs GDB as
|
835 |
|
|
a subprocess. It tells GDB to modify its print routines so as to
|
836 |
|
|
allow Epoch to display values of expressions in a separate window.
|
837 |
|
|
|
838 |
|
|
`-annotate LEVEL'
|
839 |
|
|
This option sets the "annotation level" inside GDB. Its effect is
|
840 |
|
|
identical to using `set annotate LEVEL' (*note Annotations::).
|
841 |
|
|
Annotation level controls how much information does GDB print
|
842 |
|
|
together with its prompt, values of expressions, source lines, and
|
843 |
|
|
other types of output. Level 0 is the normal, level 1 is for use
|
844 |
|
|
when GDB is run as a subprocess of GNU Emacs, level 2 is the
|
845 |
|
|
maximum annotation suitable for programs that control GDB.
|
846 |
|
|
|
847 |
|
|
`-async'
|
848 |
|
|
Use the asynchronous event loop for the command-line interface.
|
849 |
|
|
GDB processes all events, such as user keyboard input, via a
|
850 |
|
|
special event loop. This allows GDB to accept and process user
|
851 |
|
|
commands in parallel with the debugged process being run(1), so
|
852 |
|
|
you don't need to wait for control to return to GDB before you
|
853 |
|
|
type the next command. (_Note:_ as of version 5.1, the target
|
854 |
|
|
side of the asynchronous operation is not yet in place, so
|
855 |
|
|
`-async' does not work fully yet.)
|
856 |
|
|
|
857 |
|
|
When the standard input is connected to a terminal device, GDB
|
858 |
|
|
uses the asynchronous event loop by default, unless disabled by the
|
859 |
|
|
`-noasync' option.
|
860 |
|
|
|
861 |
|
|
`-noasync'
|
862 |
|
|
Disable the asynchronous event loop for the command-line interface.
|
863 |
|
|
|
864 |
|
|
`--args'
|
865 |
|
|
Change interpretation of command line so that arguments following
|
866 |
|
|
the executable file are passed as command line arguments to the
|
867 |
|
|
inferior. This option stops option processing.
|
868 |
|
|
|
869 |
|
|
`-baud BPS'
|
870 |
|
|
`-b BPS'
|
871 |
|
|
Set the line speed (baud rate or bits per second) of any serial
|
872 |
|
|
interface used by GDB for remote debugging.
|
873 |
|
|
|
874 |
|
|
`-tty DEVICE'
|
875 |
|
|
`-t DEVICE'
|
876 |
|
|
Run using DEVICE for your program's standard input and output.
|
877 |
|
|
|
878 |
|
|
`-tui'
|
879 |
|
|
Activate the Terminal User Interface when starting. The Terminal
|
880 |
|
|
User Interface manages several text windows on the terminal,
|
881 |
|
|
showing source, assembly, registers and GDB command outputs (*note
|
882 |
|
|
GDB Text User Interface: TUI.). Do not use this option if you run
|
883 |
|
|
GDB from Emacs (*note Using GDB under GNU Emacs: Emacs.).
|
884 |
|
|
|
885 |
|
|
`-interpreter INTERP'
|
886 |
|
|
Use the interpreter INTERP for interface with the controlling
|
887 |
|
|
program or device. This option is meant to be set by programs
|
888 |
|
|
which communicate with GDB using it as a back end.
|
889 |
|
|
|
890 |
|
|
`--interpreter=mi' (or `--interpreter=mi1') causes GDB to use the
|
891 |
|
|
"gdb/mi interface" (*note The GDB/MI Interface: GDB/MI.). The
|
892 |
|
|
older GDB/MI interface, included in GDB version 5.0 can be
|
893 |
|
|
selected with `--interpreter=mi0'.
|
894 |
|
|
|
895 |
|
|
`-write'
|
896 |
|
|
Open the executable and core files for both reading and writing.
|
897 |
|
|
This is equivalent to the `set write on' command inside GDB (*note
|
898 |
|
|
Patching::).
|
899 |
|
|
|
900 |
|
|
`-statistics'
|
901 |
|
|
This option causes GDB to print statistics about time and memory
|
902 |
|
|
usage after it completes each command and returns to the prompt.
|
903 |
|
|
|
904 |
|
|
`-version'
|
905 |
|
|
This option causes GDB to print its version number and no-warranty
|
906 |
|
|
blurb, and exit.
|
907 |
|
|
|
908 |
|
|
---------- Footnotes ----------
|
909 |
|
|
|
910 |
|
|
(1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this
|
911 |
|
|
mode of operation, but the event loop is suspended when the debuggee
|
912 |
|
|
runs.
|
913 |
|
|
|
914 |
|
|
|
915 |
|
|
File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
|
916 |
|
|
|
917 |
|
|
Quitting GDB
|
918 |
|
|
============
|
919 |
|
|
|
920 |
|
|
`quit [EXPRESSION]'
|
921 |
|
|
`q'
|
922 |
|
|
To exit GDB, use the `quit' command (abbreviated `q'), or type an
|
923 |
|
|
end-of-file character (usually `C-d'). If you do not supply
|
924 |
|
|
EXPRESSION, GDB will terminate normally; otherwise it will
|
925 |
|
|
terminate using the result of EXPRESSION as the error code.
|
926 |
|
|
|
927 |
|
|
An interrupt (often `C-c') does not exit from GDB, but rather
|
928 |
|
|
terminates the action of any GDB command that is in progress and
|
929 |
|
|
returns to GDB command level. It is safe to type the interrupt
|
930 |
|
|
character at any time because GDB does not allow it to take effect
|
931 |
|
|
until a time when it is safe.
|
932 |
|
|
|
933 |
|
|
If you have been using GDB to control an attached process or device,
|
934 |
|
|
you can release it with the `detach' command (*note Debugging an
|
935 |
|
|
already-running process: Attach.).
|
936 |
|
|
|
937 |
|
|
|
938 |
|
|
File: gdb.info, Node: Shell Commands, Prev: Quitting GDB, Up: Invocation
|
939 |
|
|
|
940 |
|
|
Shell commands
|
941 |
|
|
==============
|
942 |
|
|
|
943 |
|
|
If you need to execute occasional shell commands during your
|
944 |
|
|
debugging session, there is no need to leave or suspend GDB; you can
|
945 |
|
|
just use the `shell' command.
|
946 |
|
|
|
947 |
|
|
`shell COMMAND STRING'
|
948 |
|
|
Invoke a standard shell to execute COMMAND STRING. If it exists,
|
949 |
|
|
the environment variable `SHELL' determines which shell to run.
|
950 |
|
|
Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
|
951 |
|
|
`COMMAND.COM' on MS-DOS, etc.).
|
952 |
|
|
|
953 |
|
|
The utility `make' is often needed in development environments. You
|
954 |
|
|
do not have to use the `shell' command for this purpose in GDB:
|
955 |
|
|
|
956 |
|
|
`make MAKE-ARGS'
|
957 |
|
|
Execute the `make' program with the specified arguments. This is
|
958 |
|
|
equivalent to `shell make MAKE-ARGS'.
|
959 |
|
|
|
960 |
|
|
|
961 |
|
|
File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
|
962 |
|
|
|
963 |
|
|
GDB Commands
|
964 |
|
|
************
|
965 |
|
|
|
966 |
|
|
You can abbreviate a GDB command to the first few letters of the
|
967 |
|
|
command name, if that abbreviation is unambiguous; and you can repeat
|
968 |
|
|
certain GDB commands by typing just . You can also use the
|
969 |
|
|
key to get GDB to fill out the rest of a word in a command (or to show
|
970 |
|
|
you the alternatives available, if there is more than one possibility).
|
971 |
|
|
|
972 |
|
|
* Menu:
|
973 |
|
|
|
974 |
|
|
* Command Syntax:: How to give commands to GDB
|
975 |
|
|
* Completion:: Command completion
|
976 |
|
|
* Help:: How to ask GDB for help
|
977 |
|
|
|
978 |
|
|
|
979 |
|
|
File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
|
980 |
|
|
|
981 |
|
|
Command syntax
|
982 |
|
|
==============
|
983 |
|
|
|
984 |
|
|
A GDB command is a single line of input. There is no limit on how
|
985 |
|
|
long it can be. It starts with a command name, which is followed by
|
986 |
|
|
arguments whose meaning depends on the command name. For example, the
|
987 |
|
|
command `step' accepts an argument which is the number of times to
|
988 |
|
|
step, as in `step 5'. You can also use the `step' command with no
|
989 |
|
|
arguments. Some commands do not allow any arguments.
|
990 |
|
|
|
991 |
|
|
GDB command names may always be truncated if that abbreviation is
|
992 |
|
|
unambiguous. Other possible command abbreviations are listed in the
|
993 |
|
|
documentation for individual commands. In some cases, even ambiguous
|
994 |
|
|
abbreviations are allowed; for example, `s' is specially defined as
|
995 |
|
|
equivalent to `step' even though there are other commands whose names
|
996 |
|
|
start with `s'. You can test abbreviations by using them as arguments
|
997 |
|
|
to the `help' command.
|
998 |
|
|
|
999 |
|
|
A blank line as input to GDB (typing just ) means to repeat the
|
1000 |
|
|
previous command. Certain commands (for example, `run') will not
|
1001 |
|
|
repeat this way; these are commands whose unintentional repetition
|
1002 |
|
|
might cause trouble and which you are unlikely to want to repeat.
|
1003 |
|
|
|
1004 |
|
|
The `list' and `x' commands, when you repeat them with ,
|
1005 |
|
|
construct new arguments rather than repeating exactly as typed. This
|
1006 |
|
|
permits easy scanning of source or memory.
|
1007 |
|
|
|
1008 |
|
|
GDB can also use in another way: to partition lengthy output,
|
1009 |
|
|
in a way similar to the common utility `more' (*note Screen size:
|
1010 |
|
|
Screen Size.). Since it is easy to press one too many in this
|
1011 |
|
|
situation, GDB disables command repetition after any command that
|
1012 |
|
|
generates this sort of display.
|
1013 |
|
|
|
1014 |
|
|
Any text from a `#' to the end of the line is a comment; it does
|
1015 |
|
|
nothing. This is useful mainly in command files (*note Command files:
|
1016 |
|
|
Command Files.).
|
1017 |
|
|
|
1018 |
|
|
The `C-o' binding is useful for repeating a complex sequence of
|
1019 |
|
|
commands. This command accepts the current line, like `RET', and then
|
1020 |
|
|
fetches the next line relative to the current line from the history for
|
1021 |
|
|
editing.
|
1022 |
|
|
|
1023 |
|
|
|
1024 |
|
|
File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
|
1025 |
|
|
|
1026 |
|
|
Command completion
|
1027 |
|
|
==================
|
1028 |
|
|
|
1029 |
|
|
GDB can fill in the rest of a word in a command for you, if there is
|
1030 |
|
|
only one possibility; it can also show you what the valid possibilities
|
1031 |
|
|
are for the next word in a command, at any time. This works for GDB
|
1032 |
|
|
commands, GDB subcommands, and the names of symbols in your program.
|
1033 |
|
|
|
1034 |
|
|
Press the key whenever you want GDB to fill out the rest of a
|
1035 |
|
|
word. If there is only one possibility, GDB fills in the word, and
|
1036 |
|
|
waits for you to finish the command (or press to enter it). For
|
1037 |
|
|
example, if you type
|
1038 |
|
|
|
1039 |
|
|
(gdb) info bre
|
1040 |
|
|
|
1041 |
|
|
GDB fills in the rest of the word `breakpoints', since that is the only
|
1042 |
|
|
`info' subcommand beginning with `bre':
|
1043 |
|
|
|
1044 |
|
|
(gdb) info breakpoints
|
1045 |
|
|
|
1046 |
|
|
You can either press at this point, to run the `info breakpoints'
|
1047 |
|
|
command, or backspace and enter something else, if `breakpoints' does
|
1048 |
|
|
not look like the command you expected. (If you were sure you wanted
|
1049 |
|
|
`info breakpoints' in the first place, you might as well just type
|
1050 |
|
|
immediately after `info bre', to exploit command abbreviations
|
1051 |
|
|
rather than command completion).
|
1052 |
|
|
|
1053 |
|
|
If there is more than one possibility for the next word when you
|
1054 |
|
|
press , GDB sounds a bell. You can either supply more characters
|
1055 |
|
|
and try again, or just press a second time; GDB displays all the
|
1056 |
|
|
possible completions for that word. For example, you might want to set
|
1057 |
|
|
a breakpoint on a subroutine whose name begins with `make_', but when
|
1058 |
|
|
you type `b make_' GDB just sounds the bell. Typing again
|
1059 |
|
|
displays all the function names in your program that begin with those
|
1060 |
|
|
characters, for example:
|
1061 |
|
|
|
1062 |
|
|
(gdb) b make_
|
1063 |
|
|
GDB sounds bell; press again, to see:
|
1064 |
|
|
make_a_section_from_file make_environ
|
1065 |
|
|
make_abs_section make_function_type
|
1066 |
|
|
make_blockvector make_pointer_type
|
1067 |
|
|
make_cleanup make_reference_type
|
1068 |
|
|
make_command make_symbol_completion_list
|
1069 |
|
|
(gdb) b make_
|
1070 |
|
|
|
1071 |
|
|
After displaying the available possibilities, GDB copies your partial
|
1072 |
|
|
input (`b make_' in the example) so you can finish the command.
|
1073 |
|
|
|
1074 |
|
|
If you just want to see the list of alternatives in the first place,
|
1075 |
|
|
you can press `M-?' rather than pressing twice. `M-?' means
|
1076 |
|
|
` ?'. You can type this either by holding down a key designated
|
1077 |
|
|
as the shift on your keyboard (if there is one) while typing
|
1078 |
|
|
`?', or as followed by `?'.
|
1079 |
|
|
|
1080 |
|
|
Sometimes the string you need, while logically a "word", may contain
|
1081 |
|
|
parentheses or other characters that GDB normally excludes from its
|
1082 |
|
|
notion of a word. To permit word completion to work in this situation,
|
1083 |
|
|
you may enclose words in `'' (single quote marks) in GDB commands.
|
1084 |
|
|
|
1085 |
|
|
The most likely situation where you might need this is in typing the
|
1086 |
|
|
name of a C++ function. This is because C++ allows function
|
1087 |
|
|
overloading (multiple definitions of the same function, distinguished
|
1088 |
|
|
by argument type). For example, when you want to set a breakpoint you
|
1089 |
|
|
may need to distinguish whether you mean the version of `name' that
|
1090 |
|
|
takes an `int' parameter, `name(int)', or the version that takes a
|
1091 |
|
|
`float' parameter, `name(float)'. To use the word-completion
|
1092 |
|
|
facilities in this situation, type a single quote `'' at the beginning
|
1093 |
|
|
of the function name. This alerts GDB that it may need to consider
|
1094 |
|
|
more information than usual when you press or `M-?' to request
|
1095 |
|
|
word completion:
|
1096 |
|
|
|
1097 |
|
|
(gdb) b 'bubble( M-?
|
1098 |
|
|
bubble(double,double) bubble(int,int)
|
1099 |
|
|
(gdb) b 'bubble(
|
1100 |
|
|
|
1101 |
|
|
In some cases, GDB can tell that completing a name requires using
|
1102 |
|
|
quotes. When this happens, GDB inserts the quote for you (while
|
1103 |
|
|
completing as much as it can) if you do not type the quote in the first
|
1104 |
|
|
place:
|
1105 |
|
|
|
1106 |
|
|
(gdb) b bub
|
1107 |
|
|
GDB alters your input line to the following, and rings a bell:
|
1108 |
|
|
(gdb) b 'bubble(
|
1109 |
|
|
|
1110 |
|
|
In general, GDB can tell that a quote is needed (and inserts it) if you
|
1111 |
|
|
have not yet started typing the argument list when you ask for
|
1112 |
|
|
completion on an overloaded symbol.
|
1113 |
|
|
|
1114 |
|
|
For more information about overloaded functions, see *Note C++
|
1115 |
|
|
expressions: C plus plus expressions. You can use the command `set
|
1116 |
|
|
overload-resolution off' to disable overload resolution; see *Note GDB
|
1117 |
|
|
features for C++: Debugging C plus plus.
|
1118 |
|
|
|
1119 |
|
|
|
1120 |
|
|
File: gdb.info, Node: Help, Prev: Completion, Up: Commands
|
1121 |
|
|
|
1122 |
|
|
Getting help
|
1123 |
|
|
============
|
1124 |
|
|
|
1125 |
|
|
You can always ask GDB itself for information on its commands, using
|
1126 |
|
|
the command `help'.
|
1127 |
|
|
|
1128 |
|
|
`help'
|
1129 |
|
|
`h'
|
1130 |
|
|
You can use `help' (abbreviated `h') with no arguments to display
|
1131 |
|
|
a short list of named classes of commands:
|
1132 |
|
|
|
1133 |
|
|
(gdb) help
|
1134 |
|
|
List of classes of commands:
|
1135 |
|
|
|
1136 |
|
|
aliases -- Aliases of other commands
|
1137 |
|
|
breakpoints -- Making program stop at certain points
|
1138 |
|
|
data -- Examining data
|
1139 |
|
|
files -- Specifying and examining files
|
1140 |
|
|
internals -- Maintenance commands
|
1141 |
|
|
obscure -- Obscure features
|
1142 |
|
|
running -- Running the program
|
1143 |
|
|
stack -- Examining the stack
|
1144 |
|
|
status -- Status inquiries
|
1145 |
|
|
support -- Support facilities
|
1146 |
|
|
tracepoints -- Tracing of program execution without
|
1147 |
|
|
|
1148 |
|
|
stopping the program
|
1149 |
|
|
user-defined -- User-defined commands
|
1150 |
|
|
|
1151 |
|
|
Type "help" followed by a class name for a list of
|
1152 |
|
|
commands in that class.
|
1153 |
|
|
Type "help" followed by command name for full
|
1154 |
|
|
documentation.
|
1155 |
|
|
Command name abbreviations are allowed if unambiguous.
|
1156 |
|
|
(gdb)
|
1157 |
|
|
|
1158 |
|
|
`help CLASS'
|
1159 |
|
|
Using one of the general help classes as an argument, you can get a
|
1160 |
|
|
list of the individual commands in that class. For example, here
|
1161 |
|
|
is the help display for the class `status':
|
1162 |
|
|
|
1163 |
|
|
(gdb) help status
|
1164 |
|
|
Status inquiries.
|
1165 |
|
|
|
1166 |
|
|
List of commands:
|
1167 |
|
|
|
1168 |
|
|
info -- Generic command for showing things
|
1169 |
|
|
about the program being debugged
|
1170 |
|
|
show -- Generic command for showing things
|
1171 |
|
|
about the debugger
|
1172 |
|
|
|
1173 |
|
|
Type "help" followed by command name for full
|
1174 |
|
|
documentation.
|
1175 |
|
|
Command name abbreviations are allowed if unambiguous.
|
1176 |
|
|
(gdb)
|
1177 |
|
|
|
1178 |
|
|
`help COMMAND'
|
1179 |
|
|
With a command name as `help' argument, GDB displays a short
|
1180 |
|
|
paragraph on how to use that command.
|
1181 |
|
|
|
1182 |
|
|
`apropos ARGS'
|
1183 |
|
|
The `apropos ARGS' command searches through all of the GDB
|
1184 |
|
|
commands, and their documentation, for the regular expression
|
1185 |
|
|
specified in ARGS. It prints out all matches found. For example:
|
1186 |
|
|
|
1187 |
|
|
apropos reload
|
1188 |
|
|
|
1189 |
|
|
results in:
|
1190 |
|
|
|
1191 |
|
|
set symbol-reloading -- Set dynamic symbol table reloading
|
1192 |
|
|
multiple times in one run
|
1193 |
|
|
show symbol-reloading -- Show dynamic symbol table reloading
|
1194 |
|
|
multiple times in one run
|
1195 |
|
|
|
1196 |
|
|
`complete ARGS'
|
1197 |
|
|
The `complete ARGS' command lists all the possible completions for
|
1198 |
|
|
the beginning of a command. Use ARGS to specify the beginning of
|
1199 |
|
|
the command you want completed. For example:
|
1200 |
|
|
|
1201 |
|
|
complete i
|
1202 |
|
|
|
1203 |
|
|
results in:
|
1204 |
|
|
|
1205 |
|
|
if
|
1206 |
|
|
ignore
|
1207 |
|
|
info
|
1208 |
|
|
inspect
|
1209 |
|
|
|
1210 |
|
|
This is intended for use by GNU Emacs.
|
1211 |
|
|
|
1212 |
|
|
In addition to `help', you can use the GDB commands `info' and
|
1213 |
|
|
`show' to inquire about the state of your program, or the state of GDB
|
1214 |
|
|
itself. Each command supports many topics of inquiry; this manual
|
1215 |
|
|
introduces each of them in the appropriate context. The listings under
|
1216 |
|
|
`info' and under `show' in the Index point to all the sub-commands.
|
1217 |
|
|
*Note Index::.
|
1218 |
|
|
|
1219 |
|
|
`info'
|
1220 |
|
|
This command (abbreviated `i') is for describing the state of your
|
1221 |
|
|
program. For example, you can list the arguments given to your
|
1222 |
|
|
program with `info args', list the registers currently in use with
|
1223 |
|
|
`info registers', or list the breakpoints you have set with `info
|
1224 |
|
|
breakpoints'. You can get a complete list of the `info'
|
1225 |
|
|
sub-commands with `help info'.
|
1226 |
|
|
|
1227 |
|
|
`set'
|
1228 |
|
|
You can assign the result of an expression to an environment
|
1229 |
|
|
variable with `set'. For example, you can set the GDB prompt to a
|
1230 |
|
|
$-sign with `set prompt $'.
|
1231 |
|
|
|
1232 |
|
|
`show'
|
1233 |
|
|
In contrast to `info', `show' is for describing the state of GDB
|
1234 |
|
|
itself. You can change most of the things you can `show', by
|
1235 |
|
|
using the related command `set'; for example, you can control what
|
1236 |
|
|
number system is used for displays with `set radix', or simply
|
1237 |
|
|
inquire which is currently in use with `show radix'.
|
1238 |
|
|
|
1239 |
|
|
To display all the settable parameters and their current values,
|
1240 |
|
|
you can use `show' with no arguments; you may also use `info set'.
|
1241 |
|
|
Both commands produce the same display.
|
1242 |
|
|
|
1243 |
|
|
Here are three miscellaneous `show' subcommands, all of which are
|
1244 |
|
|
exceptional in lacking corresponding `set' commands:
|
1245 |
|
|
|
1246 |
|
|
`show version'
|
1247 |
|
|
Show what version of GDB is running. You should include this
|
1248 |
|
|
information in GDB bug-reports. If multiple versions of GDB are
|
1249 |
|
|
in use at your site, you may need to determine which version of
|
1250 |
|
|
GDB you are running; as GDB evolves, new commands are introduced,
|
1251 |
|
|
and old ones may wither away. Also, many system vendors ship
|
1252 |
|
|
variant versions of GDB, and there are variant versions of GDB in
|
1253 |
|
|
GNU/Linux distributions as well. The version number is the same
|
1254 |
|
|
as the one announced when you start GDB.
|
1255 |
|
|
|
1256 |
|
|
`show copying'
|
1257 |
|
|
Display information about permission for copying GDB.
|
1258 |
|
|
|
1259 |
|
|
`show warranty'
|
1260 |
|
|
Display the GNU "NO WARRANTY" statement, or a warranty, if your
|
1261 |
|
|
version of GDB comes with one.
|
1262 |
|
|
|
1263 |
|
|
|
1264 |
|
|
File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
|
1265 |
|
|
|
1266 |
|
|
Running Programs Under GDB
|
1267 |
|
|
**************************
|
1268 |
|
|
|
1269 |
|
|
When you run a program under GDB, you must first generate debugging
|
1270 |
|
|
information when you compile it.
|
1271 |
|
|
|
1272 |
|
|
You may start GDB with its arguments, if any, in an environment of
|
1273 |
|
|
your choice. If you are doing native debugging, you may redirect your
|
1274 |
|
|
program's input and output, debug an already running process, or kill a
|
1275 |
|
|
child process.
|
1276 |
|
|
|
1277 |
|
|
* Menu:
|
1278 |
|
|
|
1279 |
|
|
* Compilation:: Compiling for debugging
|
1280 |
|
|
* Starting:: Starting your program
|
1281 |
|
|
* Arguments:: Your program's arguments
|
1282 |
|
|
* Environment:: Your program's environment
|
1283 |
|
|
|
1284 |
|
|
* Working Directory:: Your program's working directory
|
1285 |
|
|
* Input/Output:: Your program's input and output
|
1286 |
|
|
* Attach:: Debugging an already-running process
|
1287 |
|
|
* Kill Process:: Killing the child process
|
1288 |
|
|
|
1289 |
|
|
* Threads:: Debugging programs with multiple threads
|
1290 |
|
|
* Processes:: Debugging programs with multiple processes
|
1291 |
|
|
|