Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
2 | _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc. | |
3 | _dnl__ This file is part of the source for the GDB manual. | |
8734fc33 | 4 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
5 | @c |
6 | @syncodeindex ky cp | |
7 | @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN: | |
8 | @c Sun May 19 05:36:59 1991 John Gilmore (gnu at cygint.cygnus.com) | |
9 | @c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint) | |
10 | @ifinfo | |
11 | This file documents the GNU debugger _GDBN__. | |
12 | ||
13 | Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc. | |
14 | ||
15 | Permission is granted to make and distribute verbatim copies of | |
16 | this manual provided the copyright notice and this permission notice | |
17 | are preserved on all copies. | |
18 | ||
19 | @ignore | |
20 | Permission is granted to process this file through TeX and print the | |
21 | results, provided the printed document carries copying permission | |
22 | notice identical to this one except for the removal of this paragraph | |
23 | (this paragraph not being relevant to the printed manual). | |
24 | ||
25 | @end ignore | |
26 | Permission is granted to copy and distribute modified versions of this | |
27 | manual under the conditions for verbatim copying, provided also that the | |
28 | section entitled ``GNU General Public License'' is included exactly as | |
29 | in the original, and provided that the entire resulting derived work is | |
30 | distributed under the terms of a permission notice identical to this | |
31 | one. | |
32 | ||
33 | Permission is granted to copy and distribute translations of this manual | |
34 | into another language, under the above conditions for modified versions, | |
35 | except that the section entitled ``GNU General Public License'' may be | |
36 | included in a translation approved by the Free Software Foundation | |
37 | instead of in the original English. | |
38 | @end ifinfo | |
39 | @smallbook | |
40 | @setchapternewpage odd | |
41 | _if__(_GENERIC__) | |
42 | @settitle Using _GDBN__ (v4.0) | |
43 | _fi__(_GENERIC__) | |
44 | _if__(!_GENERIC__) | |
45 | @settitle Using _GDBN__ v4.0 (_HOST__) | |
46 | _fi__(!_GENERIC__) | |
47 | @iftex | |
8734fc33 | 48 | @finalout |
9bcc06ef RP |
49 | @end iftex |
50 | @titlepage | |
51 | @title{Using _GDBN__} | |
52 | @subtitle{A Guide to the GNU Source-Level Debugger} | |
53 | _if__(!_GENERIC__) | |
54 | @subtitle{On _HOST__ Systems} | |
55 | _fi__(!_GENERIC__) | |
56 | @sp 1 | |
57 | @c Maybe crank this up to "Fourth Edition" when released at FSF | |
58 | @c @subtitle Third Edition---_GDBN__ version 4.0 | |
59 | @subtitle _GDBN__ version 4.0 | |
60 | @subtitle May 1991 | |
61 | @author{Richard M. Stallman@qquad @hfill Free Software Foundation} | |
62 | @author{Roland H. Pesch@qquad @hfill Cygnus Support} | |
63 | @page | |
8734fc33 RP |
64 | @tex |
65 | {\parskip=0pt | |
66 | \hfill rms\@ai.mit.edu, pesch\@cygnus.com\par | |
67 | \hfill {\it Using _GDBN__}, \manvers\par | |
68 | \hfill \TeX{}info \texinfoversion\par | |
69 | } | |
70 | @end tex | |
9bcc06ef | 71 | |
9bcc06ef RP |
72 | @vskip 0pt plus 1filll |
73 | Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc. | |
74 | ||
75 | Permission is granted to make and distribute verbatim copies of | |
76 | this manual provided the copyright notice and this permission notice | |
77 | are preserved on all copies. | |
78 | ||
79 | Permission is granted to copy and distribute modified versions of this | |
80 | manual under the conditions for verbatim copying, provided also that the | |
81 | section entitled ``GNU General Public License'' is included exactly as | |
82 | in the original, and provided that the entire resulting derived work is | |
83 | distributed under the terms of a permission notice identical to this | |
84 | one. | |
85 | ||
86 | Permission is granted to copy and distribute translations of this manual | |
87 | into another language, under the above conditions for modified versions, | |
88 | except that the section entitled ``GNU General Public License'' may be | |
89 | included in a translation approved by the Free Software Foundation | |
90 | instead of in the original English. | |
91 | @end titlepage | |
92 | @page | |
93 | ||
94 | @node Top, Summary, (dir), (dir) | |
95 | @ifinfo | |
96 | This file describes version 4.0 of GDB, the GNU symbolic debugger. | |
97 | @end ifinfo | |
98 | ||
99 | @menu | |
100 | * Summary:: Summary of _GDBN__ | |
101 | * New Features:: New Features in _GDBN__ version 4.0 | |
102 | * Sample Session:: A Sample _GDBN__ Session | |
103 | * Invocation:: Getting In and Out of _GDBN__ | |
104 | * Commands:: | |
105 | * Running:: Running Programs Under _GDBN__ | |
106 | * Stopping:: Stopping and Continuing | |
107 | * Stack:: Examining the Stack | |
108 | * Source:: Examining Source Files | |
109 | * Data:: Examining Data | |
110 | * Symbols:: Examining the Symbol Table | |
111 | * Altering:: Altering Execution | |
112 | * _GDBN__ Files:: | |
113 | * Targets:: Specifying a Debugging Target | |
114 | * Controlling _GDBN__:: Controlling _GDBN__ | |
115 | * Sequences:: Canned Sequences of Commands | |
116 | * Emacs:: Using _GDBN__ under GNU Emacs | |
8734fc33 | 117 | * _GDBN__ Bugs:: Reporting Bugs in _GDBN__ |
9bcc06ef RP |
118 | * Renamed Commands:: |
119 | * Installing _GDBN__:: Installing _GDBN__ | |
120 | * Copying:: GNU GENERAL PUBLIC LICENSE | |
121 | * Index:: Index | |
8734fc33 RP |
122 | --- The Detailed Node Listing --- |
123 | ||
124 | Summary of _GDBN__ | |
125 | ||
126 | * Free Software:: Free Software | |
127 | * Contributors:: Contributors to _GDBN__ | |
128 | ||
129 | Getting In and Out of _GDBN__ | |
130 | ||
131 | * Starting _GDBN__:: Starting _GDBN__ | |
132 | * Leaving _GDBN__:: Leaving _GDBN__ | |
133 | * Shell Commands:: Shell Commands | |
134 | ||
135 | Starting _GDBN__ | |
136 | ||
137 | * File Options:: Choosing Files | |
138 | * Mode Options:: Choosing Modes | |
139 | ||
140 | _GDBN__ Commands | |
141 | ||
142 | * Command Syntax:: Command Syntax | |
143 | * Help:: Getting Help | |
144 | ||
145 | Running Programs Under _GDBN__ | |
146 | ||
147 | * Compilation:: Compiling for Debugging | |
148 | * Starting:: Starting your Program | |
149 | * Arguments:: Your Program's Arguments | |
150 | * Environment:: Your Program's Environment | |
151 | * Working Directory:: Your Program's Working Directory | |
152 | * Input/Output:: Your Program's Input and Output | |
153 | * Attach:: Debugging an Already-Running Process | |
154 | * Kill Process:: Killing the Child Process | |
155 | ||
156 | Stopping and Continuing | |
157 | ||
158 | * Breakpoints:: Breakpoints, Watchpoints, and Exceptions | |
159 | * Stepping:: Stepping | |
160 | * Continuing:: Continuing | |
161 | * Signals:: Signals | |
162 | ||
163 | Breakpoints, Watchpoints, and Exceptions | |
164 | ||
165 | * Set Breaks:: Setting Breakpoints | |
166 | * Set Watchpoints:: Setting Watchpoints | |
167 | * Exception Handling:: Breakpoints and Exceptions | |
168 | * Delete Breaks:: Deleting Breakpoints | |
169 | * Disabling:: Disabling Breakpoints | |
170 | * Conditions:: Break Conditions | |
171 | * Break Commands:: Breakpoint Command Lists | |
172 | * Breakpoint Menus:: Breakpoint Menus | |
173 | * Error in Breakpoints:: | |
174 | ||
175 | Examining the Stack | |
176 | ||
177 | * Frames:: Stack Frames | |
178 | * Backtrace:: Backtraces | |
179 | * Selection:: Selecting a Frame | |
180 | * Frame Info:: Information on a Frame | |
181 | ||
182 | Examining Source Files | |
183 | ||
184 | * List:: Printing Source Lines | |
185 | * Search:: Searching Source Files | |
186 | * Source Path:: Specifying Source Directories | |
187 | * Machine Code:: Source and Machine Code | |
188 | ||
189 | Examining Data | |
190 | ||
191 | * Expressions:: Expressions | |
192 | * Variables:: Program Variables | |
193 | * Arrays:: Artificial Arrays | |
194 | * Output formats:: Output formats | |
195 | * Memory:: Examining Memory | |
196 | * Auto Display:: Automatic Display | |
197 | * Print Settings:: Print Settings | |
198 | * Value History:: Value History | |
199 | * Convenience Vars:: Convenience Variables | |
200 | * Registers:: Registers | |
201 | * Floating Point Hardware:: Floating Point Hardware | |
202 | ||
203 | Altering Execution | |
204 | ||
205 | * Assignment:: Assignment to Variables | |
206 | * Jumping:: Continuing at a Different Address | |
207 | * Signaling:: Giving the Program a Signal | |
208 | * Returning:: Returning from a Function | |
209 | * Calling:: Calling your Program's Functions | |
210 | ||
211 | _GDBN__'s Files | |
212 | ||
213 | * Files:: Commands to Specify Files | |
214 | * Symbol Errors:: Errors Reading Symbol Files | |
215 | ||
216 | Specifying a Debugging Target | |
217 | ||
218 | * Active Targets:: Active Targets | |
219 | * Target Commands:: Commands for Managing Targets | |
220 | * Remote:: Remote Debugging | |
221 | ||
222 | Remote Debugging | |
223 | ||
224 | * i960-Nindy Remote:: | |
225 | * EB29K Remote:: | |
226 | * VxWorks Remote:: | |
227 | ||
228 | _GDBN__ with a Remote i960 (Nindy) | |
229 | ||
230 | * Nindy Startup:: Startup with Nindy | |
231 | * Nindy Options:: Options for Nindy | |
232 | * Nindy reset:: Nindy Reset Command | |
233 | ||
234 | _GDBN__ with a Remote EB29K | |
235 | ||
236 | * Comms (EB29K):: Communications Setup | |
237 | * gdb-EB29K:: EB29K cross-debugging | |
238 | * Remote Log:: Remote Log | |
239 | ||
240 | _GDBN__ and VxWorks | |
241 | ||
242 | * VxWorks connection:: Connecting to VxWorks | |
243 | * VxWorks download:: VxWorks Download | |
244 | * VxWorks attach:: Running Tasks | |
245 | ||
246 | Controlling _GDBN__ | |
247 | ||
248 | * Prompt:: Prompt | |
249 | * Editing:: Command Editing | |
250 | * History:: Command History | |
251 | * Screen Size:: Screen Size | |
252 | * Numbers:: Numbers | |
253 | * Messages/Warnings:: Optional Warnings and Messages | |
254 | ||
255 | Canned Sequences of Commands | |
256 | ||
257 | * Define:: User-Defined Commands | |
258 | * Command Files:: Command Files | |
259 | * Output:: Commands for Controlled Output | |
260 | ||
261 | Reporting Bugs in _GDBN__ | |
262 | ||
263 | * Bug Criteria:: Have You Found a Bug? | |
264 | * Bug Reporting:: How to Report Bugs | |
9bcc06ef RP |
265 | @end menu |
266 | ||
267 | @node Summary, New Features, Top, Top | |
268 | @unnumbered Summary of _GDBN__ | |
269 | ||
270 | The purpose of a debugger such as _GDBN__ is to allow you to see what is | |
271 | going on ``inside'' another program while it executes---or what another | |
272 | program was doing at the moment it crashed. | |
273 | ||
274 | _GDBN__ can do four main kinds of things (plus other things in support of | |
275 | these) to help you catch bugs in the act: | |
276 | ||
277 | @itemize @bullet | |
278 | @item | |
279 | Start your program, specifying anything that might affect its behavior. | |
280 | ||
281 | @item | |
282 | Make your program stop on specified conditions. | |
283 | ||
284 | @item | |
285 | Examine what has happened, when your program has stopped. | |
286 | ||
287 | @item | |
288 | Change things in your program, so you can experiment with correcting the | |
289 | effects of one bug and go on to learn about another. | |
290 | @end itemize | |
291 | ||
292 | _GDBN__ can be used to debug programs written in C and C++. Pascal support | |
293 | is being implemented, and Fortran support will be added when a GNU | |
294 | Fortran compiler is ready. | |
295 | ||
296 | @menu | |
297 | * Free Software:: Free Software | |
298 | * Contributors:: Contributors to GDB | |
299 | @end menu | |
300 | ||
301 | @node Free Software, Contributors, Summary, Summary | |
302 | @unnumberedsec Free Software | |
303 | _GDBN__ is @dfn{free software}, protected by the GNU General Public License (GPL). | |
304 | The GPL gives you the freedom to copy or adapt a licensed | |
305 | program---but every person getting a copy also gets with it the | |
306 | freedom to modify that copy (which means that they must get access to | |
307 | the source code), and the freedom to distribute further copies. | |
308 | Typical software companies use copyrights to limit your freedoms; the | |
309 | Free Software Foundation uses the GPL to preserve these freedoms. | |
310 | ||
311 | Fundamentally, the General Public License is a license which says that | |
312 | you have these freedoms and that you can't take these freedoms away | |
313 | from anyone else. | |
314 | ||
315 | @c FIXME: (passim) go through all xrefs, expanding to use text headings | |
316 | For full details, @pxref{Copying}. | |
317 | @node Contributors, , Free Software, Summary | |
318 | @unnumberedsec Contributors to GDB | |
319 | ||
320 | Richard Stallman was the original author of GDB, as with many GNU | |
321 | programs. Many others have contributed to its development. This | |
322 | section attempts to credit major contributors. One of the virtues of | |
323 | free software is that everyone is free to contribute to it; with | |
324 | regret, we cannot actually acknowledge everyone here. The file | |
325 | @file{ChangeLog} in the GDB distribution approximates a blow-by-blow | |
326 | account. | |
327 | ||
328 | Changes much prior to version 2.0 are lost in the mists of time. | |
329 | ||
330 | @quotation | |
331 | @emph{Plea:} Additions to this section are particularly welcome. If you | |
332 | or your friends (or enemies; let's be evenhanded) have been unfairly | |
333 | omitted from this list, we would like to add your names! | |
334 | @end quotation | |
335 | ||
336 | So that they may not regard their long labor as thankless, we | |
337 | particularly thank those who shepherded GDB through major releases: | |
338 | John Gilmore (release 4.0); Jim Kingdon (releases 3.9, 3.5, 3.4, 3.3); | |
339 | and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of GDB | |
340 | for some period, each contributed significantly to the structure, | |
341 | stability, and capabilities of the entire debugger. | |
342 | ||
343 | Richard Stallman, assisted at various times by Pete TerMaat, Chris | |
344 | Hanson, and Richard Mlynarik, handled releases through 2.8. | |
345 | ||
346 | Michael Tiemann is the author of most of the GNU C++ support in GDB, | |
347 | with significant additional contributions from Per Bothner. James | |
348 | Clark wrote the GNU C++ demangler. Early work on C++ was by Peter | |
349 | TerMaat (who also did much general update work leading to release 3.0). | |
350 | ||
351 | GDB 4.0 uses the BFD subroutine library to examine multiple | |
352 | object-file formats; BFD was a joint project of V. Gumby | |
353 | Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. | |
354 | ||
355 | David Johnson wrote the original COFF support; Pace Willison did | |
356 | the original support for encapsulated COFF. | |
357 | ||
358 | Adam de Boor and Bradley Davis contributed the ISI Optimum V support. | |
359 | Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS | |
360 | support. Jean-Daniel Fekete contributed Sun 386i support. Chris | |
361 | Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki | |
362 | Hasei contributed Sony/News OS 3 support. David Johnson contributed | |
363 | Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. | |
364 | Keith Packard contributed NS32K support. Doug Rabson contributed | |
365 | Acorn Risc Machine support. Chris Smith contributed Convex support | |
366 | (and Fortran debugging). Jonathan Stone contributed Pyramid support. | |
367 | Michael Tiemann contributed SPARC support. Tim Tucker contributed | |
368 | support for the Gould NP1 and Gould Powernode. Pace Willison | |
369 | contributed Intel 386 support. Jay Vosburgh contributed Symmetry | |
370 | support. | |
371 | ||
372 | Rich Schaefer helped with support of SunOS shared libraries. | |
373 | ||
374 | Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about | |
375 | several machine instruction sets. | |
376 | ||
377 | Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped | |
378 | develop remote debugging. Intel Corporation and Wind River Systems | |
379 | contributed remote debugging modules for their products. | |
380 | ||
381 | Brian Fox is the author of the readline libraries providing | |
382 | command-line editing and command history. | |
383 | ||
384 | @node New Features, Sample Session, Summary, Top | |
385 | @unnumbered New Features since _GDBN__ version 3.5 | |
386 | ||
387 | @table @emph | |
388 | @item Targets | |
389 | Using the new command @code{target}, you can select at runtime whether | |
390 | you are debugging local files, local processes, standalone systems over | |
391 | a serial port, realtime systems over a TCP/IP connection, etc. | |
392 | Internally, _GDBN__ now uses a function vector to mediate access to | |
393 | different targets; if you need to add your own support for a remote | |
394 | protocol, this makes it much easier. | |
395 | ||
396 | @item Watchpoints | |
397 | _GDBN__ now sports watchpoints as well as breakpoints. You can use a | |
398 | watchpoint to stop execution whenever the value of an expression | |
399 | changes, without having to predict a particular place in your program | |
400 | where this may happen. | |
401 | ||
402 | @item Object Code Formats | |
403 | _GDBN__ uses a new scheme called Binary File Descriptors (BFD) to permit | |
404 | it to switch dynamically, without reconfiguration or recompilation, | |
405 | between different object-file formats. Formats currently supported are | |
406 | COFF, a.out, and the Intel 960 b.out; files may be read as .o's, archive | |
407 | libraries, or core dumps. BFD is available as a subroutine library so | |
408 | that other programs may take advantage of it, and the other GNU binary | |
409 | utilities are being converted to use it. | |
410 | ||
411 | @item Configuration | |
412 | Compile-time configuration (to select a particular architecture and | |
413 | operating system) is much easier. The script @code{config.gdb} now | |
414 | handles specification of separate host and target configurations. | |
415 | ||
416 | @item Interaction | |
417 | The user interface to _GDBN__'s control variables has been simplified | |
418 | and consolidated in two commands, @code{set} and @code{show}. Output | |
419 | lines are now broken at readable places, rather than overflowing onto | |
420 | the next line. You can suppress output of machine-level addresses, | |
421 | displaying only source language information. | |
422 | ||
423 | ||
424 | @item Source Language | |
425 | _GDBN__ now has limited support for C++ exception handling: _GDBN__ can | |
426 | break when an exception is raised, before the stack is peeled back to | |
427 | the exception handler's context. | |
428 | ||
429 | @item Command Rationalization | |
430 | Many _GDBN__ commands have been renamed to make them easier to remember | |
431 | and use. In particular, the subcommands of @code{info} and | |
432 | @code{show}/@code{set} are grouped to make the former refer to the state | |
433 | of your program, and the latter refer to the state of _GDBN__ itself. | |
434 | @xref{Renamed Commands}, for details on what commands were renamed. | |
435 | ||
436 | @item Ports | |
437 | _GDBN__ has been ported to the following new architectures: AT&T 3b1, | |
438 | Acorn RISC machine, HP300 running HPUX, big- and little-endian MIPS | |
439 | machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4. In | |
440 | addition, the following are supported as targets only: AMD 29k, Intel | |
441 | 960, and Wind River's VxWorks. | |
442 | ||
443 | @item Shared Libraries | |
444 | _GDBN__ 4.0 supports SunOS shared libraries. | |
445 | ||
446 | @item Work in Progress | |
447 | Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture | |
448 | support. | |
449 | ||
450 | @end table | |
451 |