Commit | Line | Data |
---|---|---|
e91b87a3 | 1 | \input texinfo |
5a131cc7 RP |
2 | @setfilename _GDBP__.info |
3 | @c | |
4 | @c NOTE: this manual is marked up for preprocessing with a collection | |
5 | @c of m4 macros called "pretex.m4". If you see <_if__> and <_fi__> | |
6 | @c scattered around the source, you have the full source before | |
7 | @c preprocessing; if you don't, you have the source configured for | |
8 | @c _HOST__ architectures (and you can of course get the full source, | |
9 | @c with all configurations, from wherever you got this). | |
10 | _if__(0) | |
11 | ||
12 | THIS IS THE FULL SOURCE. The full source needs to be run through m4 | |
13 | before either tex- or info- formatting: for example, | |
14 | m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo | |
15 | will produce (assuming your path finds either GNU or SysV m4; Berkeley | |
16 | won't do) a file suitable for formatting. See the text in "pretex.m4" | |
17 | for a fuller explanation (and the macro definitions). | |
18 | ||
19 | _fi__(0) | |
20 | @c | |
4187119d | 21 | @synindex ky cp |
369a6ade | 22 | @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN: |
23e2e5e1 RP |
23 | @c Tue Feb 26 01:47:07 1991 Cygnus John Gilmore (cygnus at yuba) |
24 | @c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint) | |
e91b87a3 | 25 | @ifinfo |
5a131cc7 | 26 | This file documents the GNU debugger _GDBN__. |
e91b87a3 | 27 | |
d62719de | 28 | Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc. |
e91b87a3 | 29 | |
30 | Permission is granted to make and distribute verbatim copies of | |
31 | this manual provided the copyright notice and this permission notice | |
32 | are preserved on all copies. | |
33 | ||
34 | @ignore | |
35 | Permission is granted to process this file through Tex and print the | |
36 | results, provided the printed document carries copying permission | |
37 | notice identical to this one except for the removal of this paragraph | |
38 | (this paragraph not being relevant to the printed manual). | |
39 | ||
40 | @end ignore | |
41 | Permission is granted to copy and distribute modified versions of this | |
42 | manual under the conditions for verbatim copying, provided also that the | |
4187119d | 43 | section entitled ``GNU General Public License'' is included exactly as |
44 | in the original, and provided that the entire resulting derived work is | |
45 | distributed under the terms of a permission notice identical to this | |
46 | one. | |
e91b87a3 | 47 | |
48 | Permission is granted to copy and distribute translations of this manual | |
49 | into another language, under the above conditions for modified versions, | |
4187119d | 50 | except that the section entitled ``GNU General Public License'' may be |
51 | included in a translation approved by the author instead of in the | |
52 | original English. | |
e91b87a3 | 53 | @end ifinfo |
cb9d2049 | 54 | @smallbook |
e91b87a3 | 55 | @setchapternewpage odd |
5a131cc7 RP |
56 | _if__(_GENERIC__) |
57 | @settitle Using _GDBN__ (v4.0) | |
58 | _fi__(_GENERIC__) | |
59 | _if__(!_GENERIC__) | |
60 | @settitle Using _GDBN__ v4.0 (_HOST__) | |
61 | _fi__(!_GENERIC__) | |
616875fd | 62 | @iftex |
cb9d2049 | 63 | @c @finalout |
616875fd | 64 | @end iftex |
e91b87a3 | 65 | @titlepage |
5a131cc7 | 66 | @title{Using _GDBN__} |
26376b06 | 67 | @subtitle{A Guide to the GNU Source-Level Debugger} |
5a131cc7 RP |
68 | _if__(!_GENERIC__) |
69 | @subtitle{On _HOST__ Systems} | |
70 | _fi__(!_GENERIC__) | |
e91b87a3 | 71 | @sp 1 |
369a6ade | 72 | @c Maybe crank this up to "Fourth Edition" when released at FSF |
5a131cc7 RP |
73 | @c @subtitle Third Edition---_GDBN__ version 4.0 |
74 | @subtitle _GDBN__ version 4.0 | |
369a6ade | 75 | @subtitle January 1991 |
26376b06 | 76 | @author{Richard M. Stallman} |
5a131cc7 | 77 | @author{Roland H. Pesch (Cygnus Support)} |
e91b87a3 | 78 | @page |
26376b06 RP |
79 | |
80 | @tex | |
81 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
82 | \xdef\manvers{\$Revision$} % For use in headers, footers too | |
83 | {\parskip=0pt | |
84 | \hfill Cygnus Support\par | |
1695733e | 85 | \hfill {\it Using _GDBN__}, \manvers\par |
26376b06 RP |
86 | \hfill \TeX{}info \texinfoversion\par |
87 | } | |
88 | @end tex | |
89 | ||
e91b87a3 | 90 | @vskip 0pt plus 1filll |
d62719de | 91 | Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc. |
e91b87a3 | 92 | |
93 | Permission is granted to make and distribute verbatim copies of | |
94 | this manual provided the copyright notice and this permission notice | |
95 | are preserved on all copies. | |
96 | ||
97 | Permission is granted to copy and distribute modified versions of this | |
98 | manual under the conditions for verbatim copying, provided also that the | |
4187119d | 99 | section entitled ``GNU General Public License'' is included exactly as |
100 | in the original, and provided that the entire resulting derived work is | |
101 | distributed under the terms of a permission notice identical to this | |
102 | one. | |
e91b87a3 | 103 | |
104 | Permission is granted to copy and distribute translations of this manual | |
105 | into another language, under the above conditions for modified versions, | |
4187119d | 106 | except that the section entitled ``GNU General Public License'' may be |
107 | included in a translation approved by the author instead of in the | |
108 | original English. | |
e91b87a3 | 109 | @end titlepage |
110 | @page | |
111 | ||
54e4a398 | 112 | @node Top, New Features, (dir), (dir) |
5a131cc7 | 113 | @unnumbered Summary of _GDBN__ |
e91b87a3 | 114 | |
5a131cc7 | 115 | The purpose of a debugger such as _GDBN__ is to allow you to see what is |
9da601bf | 116 | going on ``inside'' another program while it executes---or what another |
5a131cc7 | 117 | program was doing at the moment it crashed. |
e91b87a3 | 118 | |
5a131cc7 | 119 | _GDBN__ can do four main kinds of things (plus other things in support of |
9da601bf | 120 | these) to help you catch bugs in the act: |
e91b87a3 | 121 | |
122 | @enumerate | |
123 | @item | |
9da601bf | 124 | Start your program, specifying anything that might affect its behavior. |
e91b87a3 | 125 | |
126 | @item | |
9da601bf | 127 | Make your program stop on specified conditions. |
e91b87a3 | 128 | |
129 | @item | |
9da601bf | 130 | Examine what has happened, when your program has stopped. |
e91b87a3 | 131 | |
132 | @item | |
9da601bf RP |
133 | Change things in your program, so you can experiment with correcting the |
134 | effects of one bug and go on to learn about another. | |
e91b87a3 | 135 | @end enumerate |
136 | ||
5a131cc7 | 137 | _GDBN__ can be used to debug programs written in C and C++. Pascal support |
e91b87a3 | 138 | is being implemented, and Fortran support will be added when a GNU |
5a131cc7 | 139 | Fortran compiler is ready. |
e91b87a3 | 140 | |
cb9d2049 | 141 | @node Free Software,,, |
369a6ade | 142 | @unnumberedsec Free Software |
5a131cc7 | 143 | _GDBN__ is Free Software, protected by the GNU General Public License (GPL). |
369a6ade RP |
144 | The GPL gives you the freedom to copy or adapt a licensed |
145 | program---but every person getting a copy also gets with it the | |
146 | freedom to modify that copy (which means that they must get access to | |
147 | the source code), and the freedom to distribute further copies. | |
148 | Typical software companies use copyrights to limit your freedoms; the | |
149 | Free Software Foundation uses the GPL to preserve these freedoms. | |
150 | ||
151 | Fundamentally, the General Public License is a license which says that | |
152 | you have these freedoms and that you can't take these freedoms away | |
153 | from anyone else. | |
154 | ||
155 | For full details, @pxref{License}. | |
156 | ||
369a6ade | 157 | @node New Features, Invocation, Top, Top |
5a131cc7 | 158 | @unnumbered New Features in _GDBN__ version 4.0 |
9da601bf RP |
159 | |
160 | @itemize @bullet | |
161 | @item | |
162 | TARGETS: Using the new command @samp{target}, you can select at runtime | |
163 | whether you are debugging local files, local processes, standalone | |
164 | systems over the serial port, realtime systems over a TCP/IP | |
5a131cc7 | 165 | connection, etc. _GDBN__ now uses a function vector to mediate access to |
9da601bf RP |
166 | all the different possible targets, making it much easier to add |
167 | support for new remote protocols. | |
168 | ||
169 | @item | |
5a131cc7 | 170 | WATCHPOINTS: _GDBN__ now sports watchpoints as well as breakpoints. You can |
9da601bf RP |
171 | use a watchpoint to stop execution whenever the value of an expression |
172 | changes, without having to predict a particular place in the inferior | |
173 | process where this may happen. | |
174 | ||
175 | @item | |
5a131cc7 | 176 | OBJECT CODE FORMATS: _GDBN__ uses a new scheme called Binary File |
9da601bf RP |
177 | Descriptors (BFD) to permit it to switch dynamically, without |
178 | reconfiguration or recompilation, between different object-file | |
179 | formats. Formats currently supported are COFF, a.out, and the new | |
180 | Intel 960 b.out; files may be read as .o's, archive libraries, or core | |
181 | dumps. BFD is available as a subroutine library so that other | |
182 | programs may take advantage of it, and the other GNU binary utilities | |
183 | are being converted to use it. | |
184 | ||
185 | @item | |
186 | CONFIGURATION: You must still choose a particular machine architecture | |
5a131cc7 | 187 | and operating system for _GDBN__'s host and target systems when _GDBN__ is built. |
9da601bf RP |
188 | The script @samp{config.gdb} now handles specification of separate host |
189 | and target configurations. | |
190 | ||
191 | @item | |
5a131cc7 | 192 | INTERACTION: _GDBN__ now uses the GNU @code{readline} interface to read its |
9da601bf | 193 | input; this provides inline editing of commands, using the familiar |
5a131cc7 RP |
194 | Emacs or @code{vi} keymaps, and command-history support. The user interface |
195 | to _GDBN__'s control variables has been simplified and consolidated in two | |
a58d77ad JG |
196 | commands, @samp{set} and @samp{show}. Output lines are now broken at |
197 | readable places, rather than overflowing onto the next line. | |
9da601bf RP |
198 | |
199 | @item | |
5a131cc7 | 200 | SOURCE LANGUAGE: _GDBN__ now understands C++ source as well as C. Multiple |
9da601bf | 201 | inheritance is supported when used with G++ 2.0. There is also limited |
5a131cc7 | 202 | support for C++ exception handling: _GDBN__ can break when an exception is |
d2e08421 | 203 | raised, before the stack is peeled back to the exception handler's |
a58d77ad JG |
204 | context. You can suppress output of machine-level addresses, |
205 | displaying only source language information. | |
9da601bf RP |
206 | |
207 | @item | |
5a131cc7 | 208 | PORTS: _GDBN__ has been ported to the following new architectures: |
9da601bf RP |
209 | AT&T 3b1, Acorn RISC machine, HP300 running HPUX, big- and little- |
210 | endian MIPS machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS | |
211 | 4. In addition, the following are supported as targets only: AMD | |
212 | 29k, Intel 960, and Wind River's VxWorks. | |
213 | ||
214 | @item | |
5a131cc7 | 215 | SHARED LIBRARIES: _GDBN__ 4.0 supports SunOS shared libraries. |
9da601bf RP |
216 | |
217 | @item | |
218 | WORK IN PROGRESS: kernel debugging for BSD and Mach systems; Tahoe and | |
219 | HPPA architecture support. | |
220 | ||
221 | @end itemize | |
222 | ||
369a6ade | 223 | @node Invocation, User Interface, New Features, Top |
5a131cc7 | 224 | @chapter Starting _GDBN__ |
9da601bf | 225 | |
5a131cc7 | 226 | _GDBN__ is invoked with the shell command @samp{_GDBP__}. Once started, it reads |
54e4a398 | 227 | commands from the terminal until you tell it to exit. |
9da601bf | 228 | |
5a131cc7 | 229 | The most usual way to start _GDBN__ is with one argument or two, specifying |
369a6ade RP |
230 | an executable program as the argument: |
231 | @example | |
5a131cc7 | 232 | _GDBP__ program |
369a6ade RP |
233 | @end example |
234 | @noindent | |
235 | or you can start with both an executable program and a core file specified: | |
236 | @example | |
5a131cc7 | 237 | _GDBP__ program core |
369a6ade RP |
238 | @end example |
239 | ||
5a131cc7 | 240 | You can get more detailed control over how _GDBN__ starts up using some of |
cb9d2049 | 241 | the command-line options. |
369a6ade RP |
242 | |
243 | All the options and command line arguments given are processed | |
244 | in sequential order. The order makes a difference when the | |
245 | @samp{-x} option is used. | |
246 | ||
369a6ade | 247 | @node File Options, Mode Options, Invocation, Invocation |
5a131cc7 | 248 | @section Options and Arguments to Choose Files |
369a6ade | 249 | |
cb9d2049 RP |
250 | As shown above, any arguments other than options specify an executable |
251 | file and core file; that is, the first argument encountered with no | |
252 | associated option flag is equivalent to a @samp{-se} option, and the | |
253 | second, if any, is equivalent to a @samp{-c} option. | |
369a6ade RP |
254 | |
255 | @table @code | |
256 | @item -s @var{file} | |
257 | Read symbol table from file @var{file}. | |
258 | ||
259 | @item -e @var{file} | |
260 | Use file @var{file} as the executable file to execute when | |
261 | appropriate, and for examining pure data in conjunction with a core | |
262 | dump. | |
263 | ||
264 | @item -se @var{file} | |
265 | Read symbol table from file @var{file} and use it as the executable | |
266 | file. | |
267 | ||
268 | @item -c @var{file} | |
269 | Use file @var{file} as a core dump to examine. | |
270 | ||
271 | @item -x @var{file} | |
5a131cc7 | 272 | Execute _GDBN__ commands from file @var{file}. @xref{Command Files}. |
369a6ade RP |
273 | |
274 | @item -d @var{directory} | |
275 | Add @var{directory} to the path to search for source files. | |
276 | @end table | |
277 | ||
278 | @node Mode Options, Remote i960-Nindy, File Options, Invocation | |
5a131cc7 | 279 | @section Options to Choose Modes |
369a6ade RP |
280 | |
281 | @table @code | |
282 | @item -nx | |
5a131cc7 | 283 | Do not execute commands from the init files @file{._GDBP__init}. |
369a6ade RP |
284 | Normally, the commands in these files are executed after all the |
285 | command options and arguments have been processed. @xref{Command | |
286 | Files}. | |
287 | ||
288 | @item -q | |
289 | ``Quiet''. Do not print the introductory and copyright messages. These | |
290 | messages are also suppressed in batch mode, or if an executable file name is | |
5a131cc7 | 291 | specified on the _GDBN__ command line. |
369a6ade RP |
292 | |
293 | @item -batch | |
9d7c0513 | 294 | Run in batch mode. Exit with code @code{0} after processing all the command |
5a131cc7 RP |
295 | files specified with @samp{-x} (and @file{._GDBP__init}, if not inhibited). |
296 | Exit with nonzero status if an error occurs in executing the _GDBN__ | |
369a6ade RP |
297 | commands in the command files. |
298 | ||
5a131cc7 | 299 | Batch mode may be useful for running _GDBN__ as a filter, for example to |
369a6ade | 300 | download and run a program on another computer; in order to make this |
9d7c0513 RP |
301 | more useful, the message |
302 | @example | |
303 | Program exited normally. | |
304 | @end example | |
305 | @noindent | |
5a131cc7 | 306 | (which is ordinarily issued whenever a program running under _GDBN__ control |
9d7c0513 | 307 | terminates) is not issued when running in batch mode. |
369a6ade RP |
308 | |
309 | @item -fullname | |
5a131cc7 | 310 | This option is used when Emacs runs _GDBN__ as a subprocess. It tells _GDBN__ |
369a6ade RP |
311 | to output the full file name and line number in a standard, |
312 | recognizable fashion each time a stack frame is displayed (which | |
313 | includes each time the program stops). This recognizable format looks | |
314 | like two @samp{\032} characters, followed by the file name, line number | |
315 | and character position separated by colons, and a newline. The | |
5a131cc7 | 316 | Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as |
369a6ade RP |
317 | a signal to display the source code for the frame. |
318 | ||
319 | @item -b @var{bps} | |
320 | Set the line speed (baud rate or bps) of any serial interface used by | |
5a131cc7 | 321 | _GDBN__ for remote debugging. |
369a6ade RP |
322 | @end table |
323 | ||
5a131cc7 | 324 | _if__(_I960__) |
cb9d2049 | 325 | @node i960-Nindy Remote,,, |
5a131cc7 | 326 | @section _GDBN__ with a Remote Intel 960 (Nindy) |
369a6ade | 327 | |
9d7c0513 | 328 | ``Nindy'' is the name of a Rom Monitor program for Intel 960 target |
5a131cc7 RP |
329 | systems. When _GDBN__ is configured to control a remote Intel 960 using |
330 | Nindy, you can tell _GDBN__ how to connect to the 960 in several ways: | |
369a6ade RP |
331 | |
332 | @itemize @bullet | |
333 | @item | |
334 | Through command line options specifying device, baud rate, and protocol; | |
335 | ||
336 | @item | |
337 | By responding to a prompt on startup; | |
338 | ||
339 | @item | |
5a131cc7 | 340 | By using the @samp{target} command at any point during your _GDBN__ session. |
369a6ade RP |
341 | @end itemize |
342 | ||
5a131cc7 RP |
343 | @node Nindy Startup,,, |
344 | @subsection Startup with Nindy | |
345 | ||
369a6ade | 346 | The command-line options for Nindy are detailed below. If you simply |
5a131cc7 RP |
347 | start @code{_GDBP__} without using options to specify a serial port, you are |
348 | prompted for it, @emph{before} you reach the ordinary _GDBN__ prompt: | |
369a6ade RP |
349 | @example |
350 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: | |
351 | @end example | |
352 | @noindent | |
353 | You can, if you choose, simply start up with no Nindy connection by | |
354 | responding to the prompt with an empty line. If you do this, and later | |
355 | wish to attach to Nindy, use @samp{target} (@pxref{Target Commands}). | |
356 | ||
5a131cc7 RP |
357 | @node Nindy Options,,, |
358 | @subsection Options for Nindy | |
359 | ||
360 | These are the startup options for beginning your _GDBN__ session with a | |
369a6ade RP |
361 | Nindy-960 board attached: |
362 | ||
363 | @table @code | |
364 | @item -r @var{port} | |
365 | Specify the serial port name of a serial interface to be used to connect | |
5a131cc7 | 366 | to the target system. This option is only available when _GDBN__ is |
9d7c0513 RP |
367 | configured for the Intel 960 target architecture. You may specify |
368 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a | |
369a6ade RP |
369 | device name in @samp{/dev} (e.g. @samp{-r ttya}), or simply the unique |
370 | suffix for a specific @code{tty} (e.g. @samp{-r a}). | |
371 | ||
372 | @item -O | |
5a131cc7 | 373 | (An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use |
9d7c0513 | 374 | the ``old'' Nindy monitor protocol to connect to the target system. |
5a131cc7 | 375 | This option is only available when _GDBN__ is configured for the Intel 960 |
9d7c0513 | 376 | target architecture. |
369a6ade RP |
377 | |
378 | @quotation | |
379 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to | |
380 | connect to a target system using the current protocol, the connection | |
5a131cc7 | 381 | will fail appearing to be a speed mismatch, and _GDBN__ will repeatedly |
369a6ade RP |
382 | attempt to reconnect at several different line speeds. You can abort |
383 | this process with an interrupt. | |
384 | @end quotation | |
385 | ||
386 | @item -brk | |
5a131cc7 | 387 | Specify that _GDBN__ should first send a @samp{BREAK} signal to the target |
369a6ade | 388 | system, in an attempt to reset it, before connecting to a Nindy target. |
5a131cc7 | 389 | This option is only available when _GDBN__ is configured for the Intel 960 |
369a6ade RP |
390 | target architecture. |
391 | ||
9d7c0513 RP |
392 | @quotation |
393 | @emph{Warning:} Many target systems do not have the hardware that this | |
394 | requires; it only works with a few boards. | |
395 | @end quotation | |
396 | ||
369a6ade RP |
397 | @end table |
398 | ||
9d7c0513 RP |
399 | The standard @samp{-b} option controls the line speed used on the serial |
400 | port. | |
5a131cc7 | 401 | _fi__(_I960__) |
9d7c0513 | 402 | |
5a131cc7 RP |
403 | _if__(_AMD29K__) |
404 | @node EB29K Remote,,, | |
405 | @section Starting _GDBN__ with a Remote EB29K | |
cb9d2049 RP |
406 | |
407 | @cindex EB29K board | |
408 | @cindex running 29K programs | |
409 | @cindex 29K | |
410 | ||
5a131cc7 | 411 | To use _GDBN__ from a Unix system to run programs on AMD's EB29K |
cb9d2049 RP |
412 | board in a PC, you must first connect a serial cable between the PC |
413 | and a serial port on the Unix system. In the following, we assume | |
414 | you've hooked the cable between the PC's @samp{COM1} port and | |
415 | @samp{/dev/ttya} on the Unix system. | |
416 | ||
5a131cc7 RP |
417 | @node Comms (EB29K),,, |
418 | @subsection Communications Setup | |
cb9d2049 RP |
419 | The next step is to set up the PC's port, by doing something like the |
420 | following in DOS on the PC: | |
421 | @example | |
1695733e | 422 | C:\> MODE com1:9600,n,8,1,none |
cb9d2049 RP |
423 | @end example |
424 | @noindent | |
425 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 | |
426 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; | |
427 | you must match the communications parameters when establishing the Unix | |
428 | end of the connection as well. | |
429 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may | |
430 | @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91 | |
431 | ||
432 | To give control of the PC to the Unix side of the serial line, type | |
433 | the following at the DOS console: | |
434 | @example | |
1695733e | 435 | C:\> CTTY com1 |
cb9d2049 RP |
436 | @end example |
437 | @noindent | |
438 | (Later, if you wish to return control to the DOS console, you can use | |
439 | the command @samp{CTTY con}---but you must send it over the device that | |
440 | had control, in our example over the @samp{com1} serial line). | |
441 | ||
cb9d2049 RP |
442 | From the Unix host, use a communications program such as @code{tip} or |
443 | @code{cu} to communicate with the PC; for example, | |
444 | @example | |
445 | cu -s 9600 -l /dev/ttya | |
446 | @end example | |
447 | @noindent | |
448 | The @code{cu} options shown specify, respectively, the linespeed and the | |
1695733e RP |
449 | serial port to use. If you use @code{tip} instead, your command line |
450 | may look something like the following instead: | |
451 | @example | |
452 | tip -9600 /dev/ttya | |
453 | @end example | |
454 | @noindent | |
455 | Your system may define a different name where our example uses | |
456 | @samp{/dev/ttya} (the argument to @code{tip}). The communications | |
457 | parameters, including what port to use, are associated with the | |
458 | @code{tip} argument in the ``remote'' descriptions file---normally the | |
459 | system table @file{/etc/remote}. | |
cb9d2049 RP |
460 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of |
461 | @c the DOS side's comms setup? cu can support -o (odd | |
462 | @c parity), -e (even parity)---apparently no settings for no parity or | |
463 | @c for character size. Taken from stty maybe...? John points out tip | |
464 | @c can set these as internal variables, eg ~s parity=none; man stty | |
465 | @c suggests that it *might* work to stty these options with stdin or | |
1695733e | 466 | @c stdout redirected... ---pesch@cygnus.com, 25feb91 |
cb9d2049 | 467 | |
cb9d2049 RP |
468 | @kindex EBMON |
469 | Using the @samp{tip} or @samp{cu} connection, change the DOS working | |
470 | directory to the directory containing a copy of your 29K program, then | |
471 | start the PC program @samp{EBMON} (an EB29K control program supplied | |
1695733e RP |
472 | with your board by AMD). You should see an initial display from |
473 | @code{EBMON} similar to the one in our example, ending with the | |
474 | @code{EBMON} prompt @samp{#}--- | |
cb9d2049 | 475 | @example |
1695733e RP |
476 | C:\> g: |
477 | ||
478 | G:\> CD \usr\joe\work29k | |
479 | ||
480 | G:\USR\JOE\WORK29K> EBMON | |
481 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 | |
482 | Copyright 1990 Advanced Micro Devices, Inc. | |
483 | Written by Gibbons and Associates, Inc. | |
484 | ||
485 | Enter '?' or 'H' for help | |
486 | ||
487 | PC Coprocessor Type = EB29K | |
488 | I/O Base = 0x208 | |
489 | Memory Base = 0xd0000 | |
490 | ||
491 | Data Memory Size = 2048KB | |
492 | Available I-RAM Range = 0x8000 to 0x1fffff | |
493 | Available D-RAM Range = 0x80002000 to 0x801fffff | |
494 | ||
495 | PageSize = 0x400 | |
496 | Register Stack Size = 0x800 | |
497 | Memory Stack Size = 0x1800 | |
498 | ||
499 | CPU PRL = 0x3 | |
500 | Am29027 Available = No | |
501 | Byte Write Available = Yes | |
502 | ||
503 | # ~. | |
5a131cc7 | 504 | @end example |
cb9d2049 | 505 | |
5a131cc7 | 506 | Then exit the @code{cu} or @code{tip} program (done in the example by |
1695733e RP |
507 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep |
508 | running, ready for _GDBN__ to take over. | |
cb9d2049 | 509 | |
cb9d2049 RP |
510 | For this example, we've assumed what is probably the most convenient |
511 | way to make sure the same 29K program is on both the PC and the Unix | |
1695733e | 512 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the |
cb9d2049 RP |
513 | PC as a file system on the Unix host. If you don't have PC/NFS or |
514 | something similar connecting the two systems, you must arrange some | |
515 | other way---perhaps floppy-disk transfer---of getting the 29K program | |
5a131cc7 | 516 | from the Unix system to the PC; _GDBN__ will @emph{not} download it over the |
cb9d2049 RP |
517 | serial line. |
518 | ||
5a131cc7 | 519 | @node _GDBP__-EB29K |
cb9d2049 RP |
520 | @subsection EB29K cross-debugging |
521 | Finally, @code{cd} to the directory containing an image of your 29K | |
5a131cc7 | 522 | program on the Unix system, and start _GDBN__---specifying as argument the |
cb9d2049 RP |
523 | name of your 29K program: |
524 | @example | |
525 | cd /usr/joe/work29k | |
5a131cc7 | 526 | _GDBP__ myfoo |
cb9d2049 RP |
527 | @end example |
528 | Now you can use the @code{target} command: | |
529 | @example | |
530 | target amd-eb /dev/ttya 9600 MYFOO | |
531 | @end example | |
532 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to | |
533 | @c emphasize that this is the name as seen by DOS (since I think DOS is | |
534 | @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91 | |
535 | ||
536 | @noindent | |
537 | In this example, we've assumed your program is in a file called | |
538 | @samp{myfoo}. Note that the filename given as the last argument to | |
539 | @samp{target amd-eb} should be the name of the program as it appears to DOS. | |
540 | In our example it is simply @samp{MYFOO}, but in general it can include | |
541 | a DOS path, and depending on your transfer mechanism may not resemble | |
542 | the name on the Unix side. | |
543 | ||
544 | At this point, you can set any breakpoints you wish; when you're ready | |
5a131cc7 | 545 | to see your program run on the 29K board, use the _GDBN__ command |
cb9d2049 RP |
546 | @example |
547 | run | |
548 | @end example | |
549 | ||
5a131cc7 | 550 | To stop debugging the remote program, use the _GDBN__ @samp{detach} |
cb9d2049 RP |
551 | command. |
552 | ||
553 | To return control of the PC to its console, use @code{tip} or @code{cu} | |
5a131cc7 | 554 | once again, after your _GDBN__ session has concluded, to attach to |
cb9d2049 RP |
555 | @code{EBMON}. You can then type the command @samp{q} to shut down |
556 | @code{EBMON}, returning control to the DOS command-line interpreter. | |
557 | Type @samp{CTTY con} to return command input to the main DOS console, | |
558 | and type @samp{~.} to leave @code{tip} or @code{cu}. | |
559 | ||
560 | @node Remote Log, , Remote Commands, Remote | |
561 | @subsection Remote Log | |
562 | @kindex eb.log | |
563 | @cindex log file for EB29K | |
5a131cc7 | 564 | The @samp{target amd-eb} command creates a file @file{eb.log} in the |
cb9d2049 RP |
565 | current working directory, to help debug problems with the connection. |
566 | @file{eb.log} records all the output from @code{EBMON}, including echoes | |
567 | of the commands sent to it. Running @samp{tail -f} on this file in | |
568 | another window often helps to debug trouble with @code{EBMON}, or | |
569 | unexpected events on the PC side of the connection. | |
5a131cc7 | 570 | _fi__(_AMD29K__) |
369a6ade RP |
571 | |
572 | @node User Interface, Files, Invocation, Top | |
5a131cc7 | 573 | @chapter _GDBN__ Commands and Displays |
369a6ade | 574 | |
5a131cc7 | 575 | A _GDBN__ command is a single line of input. There is no limit on how long |
54e4a398 RP |
576 | it can be. It starts with a command name, which is followed by arguments |
577 | whose meaning depends on the command name. For example, the command | |
578 | @samp{step} accepts an argument which is the number of times to step, | |
579 | as in @samp{step 5}. You can also use the @samp{step} command with | |
580 | no arguments. Some command names do not allow any arguments. | |
4187119d | 581 | |
54e4a398 | 582 | @cindex abbreviation |
5a131cc7 | 583 | _GDBN__ command names may always be truncated if that abbreviation is |
54e4a398 RP |
584 | unambiguous. Other possible command abbreviations are listed in the |
585 | documentation of the individual commands. Sometimes even ambiguous | |
586 | abbreviations are allowed; for example, @samp{s} is specially defined as | |
587 | equivalent to @samp{step} even though there are other commands whose | |
588 | names start with @samp{s}. | |
4187119d | 589 | |
54e4a398 | 590 | @cindex repeating commands |
5a131cc7 | 591 | A blank line as input to _GDBN__ means to repeat the previous command. |
54e4a398 RP |
592 | Certain commands will not repeat this way; these are commands for which |
593 | unintentional repetition might cause trouble and which you are unlikely | |
594 | to want to repeat. Certain others (@samp{list} and @samp{x}) act | |
595 | differently when repeated because that is more useful. | |
4187119d | 596 | |
54e4a398 RP |
597 | @kindex # |
598 | @cindex comment | |
599 | A line of input starting with @samp{#} is a comment; it does nothing. | |
600 | This is useful mainly in command files (@xref{Command Files}). | |
4187119d | 601 | |
54e4a398 RP |
602 | @cindex online documentation |
603 | @kindex help | |
604 | @table @code | |
605 | @item help | |
606 | @itemx help @var{category} | |
607 | @itemx help @var{command} | |
5a131cc7 | 608 | You can always ask _GDBN__ itself for information on its commands, using the |
54e4a398 RP |
609 | command @samp{help}. With a command name as argument, it will display a |
610 | paragraph on how to use the command. Used with no arguments, | |
611 | @samp{help} displays a short list of named categories of commands; you | |
612 | can then use @samp{help @var{category}} to list the individual commands | |
613 | in a category. | |
4187119d | 614 | |
54e4a398 RP |
615 | @kindex info version |
616 | @item info version | |
5a131cc7 RP |
617 | As _GDBN__ evolves, new commands are introduced, and old ones may wither |
618 | away. If multiple versions of _GDBN__ are in use at your site, it may | |
619 | occasionally be useful to make sure what version of _GDBN__ you're running. | |
620 | _GDBN__ announces its version whenever it starts up; but you can make it | |
54e4a398 RP |
621 | repeat this information with the @samp{info version} command. |
622 | @end table | |
4187119d | 623 | |
54e4a398 | 624 | @cindex prompt |
5a131cc7 RP |
625 | _GDBN__ indicates its readiness to read a command by printing a string |
626 | called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You can | |
54e4a398 | 627 | change the prompt string with the @samp{set prompt} command. For |
5a131cc7 RP |
628 | instance, when debugging _GDBN__ with _GDBN__, it is useful to change the prompt |
629 | in one of the _GDBN__s so that you tell which one you are talking to. | |
4187119d | 630 | |
54e4a398 RP |
631 | @table @code |
632 | @item set prompt @var{newprompt} | |
633 | @kindex set prompt | |
5a131cc7 | 634 | Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth. |
54e4a398 RP |
635 | @kindex show prompt |
636 | @item show prompt | |
637 | Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} | |
638 | @end table | |
4187119d | 639 | |
5a131cc7 | 640 | @cindex exiting _GDBN__ |
54e4a398 | 641 | @kindex quit |
5a131cc7 | 642 | To exit _GDBN__, use the @samp{quit} command (abbreviated @samp{q}), or type |
54e4a398 | 643 | an end-of-file character (usually @ctrl{d}). An interrupt (often |
5a131cc7 RP |
644 | @ctrl{c}) will not exit from _GDBN__, but rather will terminate the action |
645 | of any _GDBN__ command that is in progress and return to _GDBN__ command level. | |
646 | It is safe to type the interrupt character at any time because _GDBN__ does | |
54e4a398 | 647 | not allow it to take effect until a time when it is safe. |
4187119d | 648 | |
54e4a398 RP |
649 | @cindex readline |
650 | @cindex command line editing | |
651 | @cindex history substitution | |
5a131cc7 | 652 | _GDBN__ reads its input commands via the @code{readline} interface. This |
54e4a398 RP |
653 | GNU library provides consistent behavior for programs which provide a |
654 | command line interface to the user. Advantages are @samp{emacs}-style | |
655 | or @samp{vi}-style inline editing of commands, @samp{csh}-like history | |
656 | substitution, and a storage and recall of command history across | |
657 | debugging sessions. | |
4187119d | 658 | |
5a131cc7 | 659 | You may control the behavior of command line editing in _GDBN__ with the |
54e4a398 RP |
660 | command @samp{set}. You may check the status of any of these settings |
661 | with the command @samp{show}. | |
e91b87a3 | 662 | |
54e4a398 RP |
663 | @table @code |
664 | @kindex set editing | |
665 | @cindex editing | |
666 | @item set editing | |
667 | @itemx set editing on | |
668 | Enable command line editing (enabled by default). | |
e91b87a3 | 669 | |
54e4a398 RP |
670 | @item set editing off |
671 | Disable command line editing. | |
4187119d | 672 | |
54e4a398 RP |
673 | @kindex show editing |
674 | @item show editing | |
675 | Show whether command line editing is enabled. | |
e91b87a3 | 676 | |
54e4a398 RP |
677 | @cindex history file |
678 | @kindex set history file | |
679 | @item set history file @var{filename} | |
5a131cc7 RP |
680 | Set the name of the _GDBN__ command history file to @samp{filename}. This is |
681 | the file from which _GDBN__ will read an initial command history | |
54e4a398 RP |
682 | list or to which it will write this list when it exits. This list is |
683 | accessed through history expansion or through the history | |
684 | command editing characters listed below. This file defaults to the | |
685 | value of the environmental variable @code{GDBHISTFILE}, or to | |
686 | @code{./.gdb_history} if this variable is not set. | |
e91b87a3 | 687 | |
54e4a398 RP |
688 | @cindex history write |
689 | @kindex set history write | |
690 | @item set history write | |
691 | @itemx set history write on | |
5a131cc7 | 692 | Make _GDBN__ record command history in a file, whose name may be specified with the |
54e4a398 | 693 | @samp{set history file} command. By default, this option is disabled. |
e91b87a3 | 694 | |
54e4a398 | 695 | @item set history write off |
5a131cc7 | 696 | Make _GDBN__ stop recording command history in a file. |
e91b87a3 | 697 | |
54e4a398 RP |
698 | @cindex history size |
699 | @kindex set history size | |
700 | @item set history size @var{size} | |
5a131cc7 | 701 | Set the number of commands which _GDBN__ will keep in its history list. |
54e4a398 RP |
702 | This defaults to the value of the environmental variable |
703 | @code{HISTSIZE}, or to 256 if this variable is not set. | |
704 | @end table | |
e91b87a3 | 705 | |
54e4a398 RP |
706 | @cindex history expansion |
707 | History expansion assigns special meaning to the character @samp{!} | |
708 | (@pxref{Event Designators}). Since @samp{!} is also the logical not | |
709 | operator in C, history expansion is off by default. If you decide to | |
710 | enable history expansion with the @samp{set history expansion on} | |
711 | command, you may sometimes need to follow @samp{!} (when it is used as | |
712 | logical not, in an expression) with a space or a tab to prevent it from | |
713 | being expanded. The @code{readline} history facilities will not attempt | |
714 | substitution on the strings @samp{!=} and @samp{!(}, even when history | |
715 | expansion is enabled. | |
e91b87a3 | 716 | |
54e4a398 | 717 | The commands to control history expansion are: |
96a816c5 JG |
718 | |
719 | @table @code | |
720 | ||
721 | @kindex set history expansion | |
722 | @item set history expansion on | |
723 | @itemx set history expansion | |
9c91ee3e | 724 | Enable history expansion. History expansion is off by default. |
96a816c5 JG |
725 | |
726 | @item set history expansion off | |
9c91ee3e | 727 | Disable history expansion. |
96a816c5 | 728 | |
9da601bf RP |
729 | The @code{readline} code comes with more complete documentation of |
730 | editing and history expansion features. Users unfamiliar with @samp{emacs} | |
731 | or @samp{vi} may wish to read it. @xref{Command Line Editing}. | |
732 | ||
733 | @kindex show history | |
734 | @item show history | |
735 | @itemx show history file | |
736 | @itemx show history write | |
737 | @itemx show history size | |
738 | @itemx show history expansion | |
5a131cc7 | 739 | These commands display the state of the _GDBN__ history parameters. |
9da601bf RP |
740 | @samp{show history} by itself displays all four states. |
741 | ||
23e2e5e1 RP |
742 | @kindex show |
743 | @kindex info set | |
744 | @item show | |
745 | @itemx info set | |
5a131cc7 | 746 | This chapter introduces a number of internal _GDBN__ variables that you |
23e2e5e1 RP |
747 | can control with the @samp{set} command, and display with the |
748 | @samp{show} command. A number of others are introduced throughout the | |
749 | manual. To display all the settable parameters and their current | |
750 | values, you can use @samp{show} with no arguments; you may also use | |
751 | @samp{info set}. Both commands produce the same display. | |
752 | ||
96a816c5 JG |
753 | @end table |
754 | ||
9da601bf RP |
755 | @table @code |
756 | @kindex info editing | |
757 | @item info editing | |
758 | Display the last ten commands in the command history. | |
9c91ee3e | 759 | |
9da601bf RP |
760 | @item info editing @var{n} |
761 | Print ten commands centered on command number @var{n}. | |
9c91ee3e | 762 | |
9da601bf RP |
763 | @item info editing + |
764 | Print ten commands just after the commands last printed. | |
765 | ||
766 | @end table | |
96a816c5 | 767 | |
5a131cc7 | 768 | Occasionally it is useful to execute a shell command from within _GDBN__. |
96a816c5 JG |
769 | This can be done with the @samp{shell} command. |
770 | ||
771 | @table @code | |
9c91ee3e | 772 | @item shell @var{command string} |
96a816c5 JG |
773 | @kindex shell |
774 | @cindex shell escape | |
5a131cc7 RP |
775 | Directs _GDBN__ to invoke an inferior shell to execute @var{command string}. |
776 | The environment variable @code{SHELL} is used if it exists, otherwise _GDBN__ | |
96a816c5 | 777 | uses @samp{/bin/sh}. |
d2e08421 | 778 | @end table |
96a816c5 | 779 | |
d2e08421 | 780 | The utility @samp{make} is often needed in development environments. |
5a131cc7 | 781 | You don't have to use the @samp{shell} command for this purpose in _GDBN__: |
d62719de | 782 | |
d2e08421 RP |
783 | @table @code |
784 | @item make @dots{} | |
9c91ee3e RP |
785 | @kindex make |
786 | @cindex calling make | |
5a131cc7 | 787 | Causes _GDBN__ to execute an inferior @code{make} program with the specified |
d2e08421 | 788 | arguments. This is equivalent to @samp{shell make @dots{}}. |
9c91ee3e RP |
789 | @end table |
790 | ||
4187119d | 791 | @cindex screen size |
792 | @cindex pauses in output | |
5a131cc7 RP |
793 | Certain commands to _GDBN__ may produce large amounts of information output |
794 | to the screen. To help you read all of it, _GDBN__ pauses and asks you for | |
4187119d | 795 | input at the end of each page of output. Type @key{RET} when you want |
5a131cc7 | 796 | to continue the output. Normally _GDBN__ knows the size of the screen from |
9c91ee3e RP |
797 | the termcap data base together with the value of the @code{TERM} |
798 | environment variable and the @code{stty rows} and @code{stty cols} | |
799 | settings. If this is not correct, you can override it with | |
96a816c5 | 800 | the @samp{set screen-height} and @samp{set screen-width} commands: |
4187119d | 801 | |
5a131cc7 | 802 | _GDBN__ also uses the screen width setting to determine when to wrap lines |
a58d77ad JG |
803 | of output. Depending what is being printed, it tries to break the |
804 | line at a readable place, rather than simply letting it overflow onto | |
805 | the following line. | |
806 | ||
4187119d | 807 | @table @code |
96a816c5 | 808 | @item set screen-height @var{lpp} |
9da601bf RP |
809 | @itemx show screen-height |
810 | @itemx set screen-width @var{cpl} | |
811 | @itemx show screen-width | |
96a816c5 JG |
812 | @kindex set screen-height |
813 | @kindex set screen-width | |
9da601bf RP |
814 | @kindex show screen-width |
815 | @kindex show screen-height | |
816 | These @samp{set} commands specify a screen height of @var{lpp} lines and | |
817 | a screen width of @var{cpl} characters. The associated @samp{show} | |
818 | commands display the current settings. | |
4187119d | 819 | |
5a131cc7 | 820 | If you specify a height of zero lines, _GDBN__ will not pause during output |
4187119d | 821 | no matter how long the output is. This is useful if output is to a file |
822 | or to an editor buffer. | |
823 | @end table | |
824 | ||
9da601bf RP |
825 | @cindex number representation |
826 | @cindex entering numbers | |
5a131cc7 | 827 | You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by |
9da601bf RP |
828 | the usual conventions: octal numbers begin with @samp{0}, decimal |
829 | numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}. | |
830 | Numbers that begin with none of these are, by default, entered in base | |
831 | 10; likewise, the default display for numbers---when no particular | |
832 | format is specified---is base 10. You can change the default base for | |
833 | both input and output with the @samp{set radix} command. | |
834 | ||
835 | @table @code | |
836 | @kindex set radix | |
837 | @item set radix @var{base} | |
838 | Set the default base for numeric input and display. Supported choices | |
839 | for @var{base} are decimal 8, 10, 16. @var{base} must itself be | |
840 | specified either unambiguously or using the current default radix; for | |
841 | example, any of | |
842 | ||
843 | @example | |
844 | set radix 012 | |
845 | set radix 10. | |
846 | set radix 0xa | |
847 | @end example | |
848 | ||
849 | @noindent | |
850 | will set the base to decimal. On the other hand, @samp{set radix 10} | |
851 | will leave the radix unchanged no matter what it was. | |
852 | ||
853 | @kindex show radix | |
854 | @item show radix | |
855 | Display the current default base for numeric input and display. | |
856 | ||
857 | @end table | |
858 | ||
5a131cc7 | 859 | By default, _GDBN__ is silent about its inner workings. If you are running |
9c91ee3e | 860 | on a slow machine, you may want to use the @samp{set verbose} command. |
5a131cc7 | 861 | It will make _GDBN__ tell you when it does a lengthy internal operation, so |
9c91ee3e | 862 | you won't think it has crashed. |
4187119d | 863 | |
864 | Currently, the messages controlled by @samp{set verbose} are those which | |
865 | announce that the symbol table for a source file is being read | |
469ddd56 | 866 | (@pxref{Files}, in the description of the command |
4187119d | 867 | @samp{symbol-file}). |
868 | @c The following is the right way to do it, but emacs 18.55 doesn't support | |
869 | @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo | |
870 | @c is released. | |
871 | @ignore | |
469ddd56 | 872 | see @samp{symbol-file} in @ref{Files}). |
4187119d | 873 | @end ignore |
874 | ||
9c91ee3e RP |
875 | @table @code |
876 | @kindex set verbose | |
877 | @item set verbose on | |
5a131cc7 | 878 | Enables _GDBN__'s output of certain informational messages. |
9c91ee3e RP |
879 | |
880 | @item set verbose off | |
5a131cc7 | 881 | Disables _GDBN__'s output of certain informational messages. |
9c91ee3e | 882 | |
9da601bf RP |
883 | @kindex show verbose |
884 | @item show verbose | |
885 | Displays whether @samp{set verbose} is on or off. | |
9c91ee3e RP |
886 | @end table |
887 | ||
5a131cc7 | 888 | By default, if _GDBN__ encounters bugs in the symbol table of an object file, |
d62719de JG |
889 | it prints a single message about each type of problem it finds, then |
890 | shuts up. You can suppress these messages, or allow more than one such | |
891 | message to be printed if you want to see how frequent the problems are. | |
469ddd56 | 892 | @xref{Files}. |
d62719de JG |
893 | |
894 | @table @code | |
895 | @kindex set complaints | |
23e2e5e1 | 896 | @item set complaints @var{limit} |
5a131cc7 | 897 | Permits _GDBN__ to output @var{limit} complaints about each type of unusual |
23e2e5e1 | 898 | symbols before becoming silent about the problem. Set @var{limit} to |
d62719de JG |
899 | zero to suppress all complaints; set it to a large number to prevent |
900 | complaints from being suppressed. | |
901 | ||
902 | @kindex show complaints | |
903 | @item show complaints | |
5a131cc7 | 904 | Displays how many symbol complaints _GDBN__ is permitted to produce. |
d62719de JG |
905 | @end table |
906 | ||
5a131cc7 | 907 | By default, _GDBN__ is cautious, and asks what sometimes seem to be a lot of |
d2e08421 RP |
908 | stupid questions. For example, if you try to run a program which is |
909 | already running: | |
9c91ee3e RP |
910 | @example |
911 | ||
5a131cc7 | 912 | (_GDBP__) run |
9c91ee3e RP |
913 | The program being debugged has been started already. |
914 | Start it from the beginning? (y or n) | |
915 | @end example | |
916 | ||
917 | If you're willing to unflinchingly face the consequences of your own | |
918 | commands, you can disable this ``feature'': | |
919 | ||
920 | @table @code | |
d2e08421 | 921 | @kindex set caution |
9c91ee3e | 922 | @cindex flinching |
4afc6002 | 923 | @cindex stupid questions |
d2e08421 RP |
924 | @item set caution off |
925 | Disables cautious questions. | |
9c91ee3e | 926 | |
d2e08421 RP |
927 | @item set caution on |
928 | Enables cautious questions (the default). | |
9da601bf | 929 | |
d2e08421 RP |
930 | @item show caution |
931 | @kindex show caution | |
932 | Displays state of cautious questions. | |
4afc6002 | 933 | @end table |
9c91ee3e | 934 | |
4187119d | 935 | @node Files, Compilation, User Interface, Top |
5a131cc7 | 936 | @chapter Specifying _GDBN__'s Files |
e91b87a3 | 937 | |
938 | @cindex core dump file | |
939 | @cindex executable file | |
940 | @cindex symbol table | |
5a131cc7 | 941 | _GDBN__ needs to know the file name of the program to be debugged, both in |
4187119d | 942 | order to read its symbol table and in order to start the program. To |
5a131cc7 | 943 | debug a core dump of a previous run, _GDBN__ must be told the file name of |
4187119d | 944 | the core dump. |
e91b87a3 | 945 | |
e91b87a3 | 946 | The usual way to specify the executable and core dump file names is with |
5a131cc7 | 947 | the command arguments given when you start _GDBN__, as discussed in |
369a6ade | 948 | @pxref{Invocation}. |
e91b87a3 | 949 | |
369a6ade | 950 | But occasionally it is necessary to change to a different file during a |
5a131cc7 RP |
951 | _GDBN__ session. Or you may run _GDBN__ and forget to specify the files you |
952 | want to use. In these situations the _GDBN__ commands to specify new files | |
369a6ade | 953 | are useful. |
e91b87a3 | 954 | |
955 | @table @code | |
9c91ee3e RP |
956 | @item file @var{filename} |
957 | @kindex file | |
d2e08421 | 958 | Use @var{filename} as the program to be debugged. It is read for its |
9c91ee3e RP |
959 | symbols, for getting the contents of pure memory, and it is the program |
960 | executed when you use the @samp{run} command. If you do not specify a | |
5a131cc7 | 961 | directory and the file is not found in _GDBN__'s working directory, _GDBN__ will |
9c91ee3e RP |
962 | use the environment variable @code{PATH} as a list of directories to |
963 | search, just as the shell does when looking for a program to run. | |
964 | ||
965 | @samp{file} with no argument makes both executable file and symbol | |
966 | table become unspecified. | |
967 | ||
e91b87a3 | 968 | @item exec-file @var{filename} |
969 | @kindex exec-file | |
9c91ee3e | 970 | Specify that the program to be run (but not the symbol table) is found |
5a131cc7 | 971 | in @var{filename}. _GDBN__ will search the environment variable @code{PATH} |
9c91ee3e | 972 | if necessary to locate the program. |
e91b87a3 | 973 | |
974 | @item symbol-file @var{filename} | |
975 | @kindex symbol-file | |
9c91ee3e RP |
976 | Read symbol table information from file @var{filename}. @code{PATH} is |
977 | searched when necessary. Use the @samp{file} command to get both symbol | |
978 | table and program to run from the same file. | |
e91b87a3 | 979 | |
5a131cc7 | 980 | @samp{symbol-file} with no argument clears out _GDBN__'s information on your |
d2e08421 | 981 | program's symbol table. |
e91b87a3 | 982 | |
5a131cc7 | 983 | The @samp{symbol-file} command causes _GDBN__ to forget the contents of its |
9da601bf | 984 | convenience variables, the value history, and all breakpoints and |
d62719de JG |
985 | auto-display expressions. This is because they may contain pointers to |
986 | the internal data recording symbols and data types, which are part of | |
5a131cc7 | 987 | the old symbol table data being discarded inside _GDBN__. |
9da601bf | 988 | |
d62719de JG |
989 | On some kinds of object files, the @samp{symbol-file} command does not |
990 | actually read the symbol table in full right away. Instead, it scans | |
991 | the symbol table quickly to find which source files and which symbols | |
992 | are present. The details are read later, one source file at a time, | |
993 | when they are needed. | |
4187119d | 994 | |
5a131cc7 | 995 | The purpose of this two-stage reading strategy is to make _GDBN__ start up |
9c91ee3e RP |
996 | faster. For the most part, it is invisible except for occasional pauses |
997 | while the symbol table details for a particular source file are being | |
998 | read. (The @samp{set verbose} command can turn these pauses into | |
999 | messages if desired. @xref{User Interface}). | |
4187119d | 1000 | |
1001 | When the symbol table is stored in COFF format, @samp{symbol-file} does | |
9da601bf RP |
1002 | read the symbol table data in full right away. We haven't implemented |
1003 | the two-stage strategy for COFF yet. | |
4187119d | 1004 | |
5a131cc7 | 1005 | When _GDBN__ is configured for a particular environment, it will understand |
9d7c0513 | 1006 | debugging information in whatever format is the standard generated for |
5a131cc7 | 1007 | that environment; you may use either the GNU compiler _GCC__, or other |
9d7c0513 | 1008 | compilers that adhere to the local conventions. Best results are |
5a131cc7 | 1009 | usually obtained from _GCC__; for example, using _GCC__ you can generate |
9d7c0513 RP |
1010 | debugging information for optimized code. |
1011 | ||
5a131cc7 | 1012 | While the symbol file is being read, _GDBN__ will occasionally encounter |
d62719de JG |
1013 | problems, such as symbol types it does not recognize, or known bugs in |
1014 | compiler output. By default, it prints one message about each such | |
1015 | type of problem, no matter how many times the problem occurs. You can | |
1016 | ask it to print more messages, to see how many times the problems occur, | |
1017 | or can shut the messages off entirely, with the @samp{set | |
1018 | complaints} command (@xref{User Interface}). | |
1019 | ||
1020 | The messages currently printed, and their meanings, are: | |
1021 | ||
1022 | @table @code | |
1023 | @item inner block not inside outer block in @var{symbol} | |
1024 | ||
1025 | The symbol information shows where symbol scopes begin and end | |
1026 | (such as at the start of a function or a block of statements). This | |
1027 | error indicates that an inner scope block is not fully contained | |
5a131cc7 | 1028 | in its outer scope blocks. _GDBN__ circumvents the problem by treating |
d62719de JG |
1029 | the inner block as if it had the same scope as the outer block. |
1030 | @var{symbol} may be ``(don't know)'' if the outer block is not | |
1031 | a function. | |
1032 | ||
1033 | @item block at @var{address} out of order | |
1034 | ||
1035 | The symbol information for symbol scope blocks should occur in | |
1036 | order of increasing addresses. This error indicates that it does not | |
5a131cc7 | 1037 | do so. _GDBN__ does not circumvent this problem, and will have trouble |
d62719de JG |
1038 | locating symbols in the source file whose symbols being read. (You |
1039 | can often determine what source file is affected by turning on | |
1040 | @samp{info verbose}. @xref{User Interface}.) | |
1041 | ||
1042 | @item bad block start address patched | |
1043 | ||
1044 | The symbol information for a symbol scope block has a start address | |
1045 | smaller than the address of the preceding source line. This is known | |
5a131cc7 | 1046 | to occur in the SunOS 4.1.1 (and earlier) C compiler. _GDBN__ circumvents |
d62719de JG |
1047 | the problem by treating the symbol scope block as starting on the |
1048 | previous source line. | |
1049 | ||
1050 | @comment @item{encountered DBX-style class variable debugging information. | |
1051 | @comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g". | |
5a131cc7 | 1052 | @comment Therefore _GDBN__ will not know about your class variables} |
d62719de JG |
1053 | @comment |
1054 | @comment This error indicates that the symbol information produced for a C++ | |
1055 | @comment program includes zero-size fields, which indicated static fields in | |
1056 | @comment a previous release of the G++ compiler. This message is probably | |
1057 | @comment obsolete. | |
1058 | @comment | |
1059 | @item bad string table offset in symbol @var{n} | |
1060 | ||
1061 | Symbol number @var{n} contains a pointer into the string table which is | |
5a131cc7 | 1062 | larger than the size of the string table. _GDBN__ circumvents the problem |
d62719de | 1063 | by considering the symbol to have the name @code{foo}, which may cause |
54e4a398 | 1064 | other problems if many symbols end up with this name. @cindex{foo} |
d62719de JG |
1065 | |
1066 | @item unknown symbol type @code{0xNN} | |
1067 | ||
5a131cc7 | 1068 | The symbol information contains new data types that _GDBN__ does not yet |
d62719de | 1069 | know how to read. @code{0xNN} is the symbol type of the misunderstood |
5a131cc7 | 1070 | information, in hexadecimal. _GDBN__ circumvents the error by ignoring |
d62719de JG |
1071 | this symbol information. This will usually allow the program to be |
1072 | debugged, though certain symbols will not be accessible. If you | |
5a131cc7 | 1073 | encounter such a problem and feel like debugging it, you can debug _GDBP__ |
d62719de JG |
1074 | with itself, breakpoint on "complain", then go "up" to |
1075 | read_dbx_symtab() and examine *bufp to see the symbol. | |
1076 | ||
23e2e5e1 RP |
1077 | @c @item stub type has NULL name |
1078 | @c | |
1079 | @c FIXME, Mike Tiemann needs to write about what this means. | |
d62719de JG |
1080 | |
1081 | @item const/volatile indicator missing, got 'X' | |
1082 | ||
1083 | The symbol information for a C++ type is missing some information that | |
1084 | the compiler should have output for it. | |
1085 | ||
1086 | @item C++ type mismatch between compiler and debugger | |
1087 | ||
1088 | The debugger could not parse a type specification output by the compiler | |
1089 | for some C++ object. | |
1090 | ||
1091 | @end table | |
1092 | ||
9da601bf | 1093 | @item core-file @var{filename} |
9da601bf | 1094 | @itemx core @var{filename} |
d2e08421 | 1095 | @kindex core |
9da601bf | 1096 | @kindex core-file |
9d7c0513 RP |
1097 | Specify the whereabouts of a core dump file to be used as the ``contents |
1098 | of memory''. Traditionally, core files contain only some parts of the | |
5a131cc7 | 1099 | address space of the process that generated them; _GDBN__ can access the |
9d7c0513 | 1100 | executable file itself for other parts. |
e91b87a3 | 1101 | |
1102 | @samp{core-file} with no argument specifies that no core file is | |
1103 | to be used. | |
1104 | ||
4187119d | 1105 | Note that the core file is ignored when your program is actually running |
5a131cc7 | 1106 | under _GDBN__. So, if you have been running the program and you wish to |
4187119d | 1107 | debug a core file instead, you must kill the subprocess in which the |
1108 | program is running. To do this, use the @samp{kill} command | |
1109 | (@pxref{Kill Process}). | |
1110 | ||
c81e78d1 | 1111 | @item load @var{filename} |
9c91ee3e | 1112 | @kindex load |
23e2e5e1 RP |
1113 | This command will dynamically link @var{filename} on the current target, |
1114 | performing any necessary downloads, then add @var{filename}'s symbol | |
1115 | table in the same way as the @samp{add-syms} command. | |
1116 | ||
1117 | @item add-syms @var{filename} @var{address} | |
1118 | @kindex add-syms | |
4187119d | 1119 | @cindex dynamic linking |
23e2e5e1 | 1120 | The @samp{add-syms} command reads additional symbol table information |
9da601bf | 1121 | from the file @var{filename}. You would use this command when that file |
23e2e5e1 RP |
1122 | has been dynamically loaded (by some other means) into the program that |
1123 | is running. @var{address} should be the memory address at which the | |
5a131cc7 | 1124 | file has been loaded; _GDBN__ cannot figure this out for itself. |
9c91ee3e | 1125 | |
4187119d | 1126 | The symbol table of the file @var{filename} is added to the symbol table |
1127 | originally read with the @samp{symbol-file} command. You can use the | |
23e2e5e1 | 1128 | @samp{add-syms} command any number of times; the new symbol data thus |
4187119d | 1129 | read keeps adding to the old. The @samp{symbol-file} command forgets |
5a131cc7 | 1130 | all the symbol data _GDBN__ has read. |
e91b87a3 | 1131 | |
1132 | @item info files | |
23e2e5e1 | 1133 | @itemx info target |
e91b87a3 | 1134 | @kindex info files |
23e2e5e1 RP |
1135 | @kindex info target |
1136 | @samp{info files} and @samp{info target} are synonymous; both print the | |
1137 | current targets (@pxref{Targets}), including the names of the | |
5a131cc7 | 1138 | executable and core dump files currently in use by _GDBN__, and the files |
23e2e5e1 RP |
1139 | from which symbols were loaded. |
1140 | ||
1141 | Beware: the similar command @samp{info targets} lists all possible | |
1142 | targets rather than current ones. | |
9c91ee3e RP |
1143 | |
1144 | @end table | |
e91b87a3 | 1145 | |
1146 | While all three file-specifying commands allow both absolute and relative | |
5a131cc7 | 1147 | file names as arguments, _GDBN__ always converts the file name to an absolute |
e91b87a3 | 1148 | one and remembers it that way. |
1149 | ||
9da601bf | 1150 | @kindex sharedlibrary |
96a816c5 JG |
1151 | @kindex share |
1152 | @cindex shared libraries | |
1153 | ||
5a131cc7 | 1154 | _GDBN__ supports the SunOS shared library format. Symbols from a shared |
96a816c5 JG |
1155 | library cannot be referenced before the shared library has been linked |
1156 | with the program. (That is to say, after one types @samp{run} and | |
9c91ee3e RP |
1157 | the function @code{main()} has been entered; or when examining core |
1158 | files.) Once the shared library has been linked in, you can use the | |
1159 | following commands: | |
96a816c5 | 1160 | |
9c91ee3e RP |
1161 | @table @code |
1162 | @item sharedlibrary @var{regex} | |
1163 | @itemx share @var{regex} | |
96a816c5 | 1164 | Load shared object library symbols for files matching a UNIX regular |
9d7c0513 | 1165 | expression. |
96a816c5 | 1166 | |
9c91ee3e RP |
1167 | @item share |
1168 | @itemx sharedlibrary | |
96a816c5 JG |
1169 | Load symbols for all shared libraries. |
1170 | ||
9c91ee3e RP |
1171 | @item info share |
1172 | @itemx info sharedlibrary | |
96a816c5 | 1173 | @kindex info sharedlibrary |
9c91ee3e | 1174 | @kindex info share |
96a816c5 | 1175 | Print the names of the shared libraries which are currently loaded. |
6ad6aa52 | 1176 | @end table |
96a816c5 JG |
1177 | |
1178 | ||
9c91ee3e | 1179 | @node Compilation, Targets, Files, Top |
cb9d2049 | 1180 | @chapter Compiling for Debugging |
e91b87a3 | 1181 | |
1182 | In order to debug a program effectively, you need to ask for debugging | |
9da601bf RP |
1183 | information when you compile it. This debugging information is stored |
1184 | in the object file; it describes the data type of each variable or | |
1185 | function and the correspondence between source line numbers and | |
1186 | addresses in the executable code. | |
e91b87a3 | 1187 | |
1188 | To request debugging information, specify the @samp{-g} option when you run | |
1189 | the compiler. | |
1190 | ||
1191 | The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options | |
1192 | together. This means that you cannot ask for optimization if you ask for | |
1193 | debugger information. | |
1194 | ||
1195 | The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it | |
1196 | possible to debug optimized code. We recommend that you @emph{always} use | |
1197 | @samp{-g} whenever you compile a program. You may think the program is | |
1198 | correct, but there's no sense in pushing your luck. | |
1199 | ||
9c91ee3e RP |
1200 | Some things do not work as well with @samp{-g -O} as with just |
1201 | @samp{-g}, particularly on machines with instruction scheduling. If in | |
1202 | doubt, recompile with @samp{-g} alone, and if this fixes the problem, | |
5a131cc7 | 1203 | please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}). |
9c91ee3e | 1204 | |
5a131cc7 RP |
1205 | Older versions of the GNU C compiler, _GCC__, permitted a variant option |
1206 | @samp{-gg} for debugging information. _GDBN__ no longer supports this format; | |
9c91ee3e | 1207 | if your GNU C compiler has this option, do not use it. |
e91b87a3 | 1208 | |
1c997a4a | 1209 | @ignore |
5a131cc7 | 1210 | @comment As far as I know, there are no cases in which _GDBN__ will |
1c997a4a | 1211 | @comment produce strange output in this case. (but no promises). |
4187119d | 1212 | If your program includes archives made with the @code{ar} program, and |
1213 | if the object files used as input to @code{ar} were compiled without the | |
5a131cc7 | 1214 | @samp{-g} option and have names longer than 15 characters, _GDBN__ will get |
4187119d | 1215 | confused reading the program's symbol table. No error message will be |
5a131cc7 | 1216 | given, but _GDBN__ may behave strangely. The reason for this problem is a |
4187119d | 1217 | deficiency in the Unix archive file format, which cannot represent file |
1218 | names longer than 15 characters. | |
e91b87a3 | 1219 | |
4187119d | 1220 | To avoid this problem, compile the archive members with the @samp{-g} |
1221 | option or use shorter file names. Alternatively, use a version of GNU | |
1222 | @code{ar} dated more recently than August 1989. | |
1c997a4a | 1223 | @end ignore |
e91b87a3 | 1224 | |
54e4a398 | 1225 | @node Targets, Running, Compilation, Top |
9c91ee3e RP |
1226 | @chapter Specifying a Debugging Target |
1227 | @cindex debugging target | |
1228 | @kindex target | |
23e2e5e1 RP |
1229 | A @dfn{target} is an interface between the debugger and a particular |
1230 | kind of file or process. | |
1231 | ||
5a131cc7 | 1232 | Often, you will be able to run _GDBN__ in the same host environment as the |
cb9d2049 | 1233 | program you are debugging; in that case, the debugging target can just be |
9c91ee3e | 1234 | specified as a side effect of the @samp{file} or @samp{core} commands. |
5a131cc7 | 1235 | When you need more flexibility---for example, running _GDBN__ on a |
9c91ee3e RP |
1236 | physically separate host, controlling standalone systems over a |
1237 | serial port, or realtime systems over a TCP/IP connection---you can use | |
1238 | the @samp{target} command. | |
1239 | ||
369a6ade RP |
1240 | @menu |
1241 | * Active Targets:: Active Targets | |
1242 | * Target Commands:: Commands for Managing Targets | |
1243 | @end menu | |
1244 | ||
1245 | @node Active Targets, Target Commands, Targets, Targets | |
23e2e5e1 RP |
1246 | @section Active Targets |
1247 | @cindex stacking targets | |
1248 | @cindex active targets | |
1249 | @cindex multiple targets | |
1250 | ||
1251 | Targets are managed in three @dfn{strata} that correspond to different | |
1252 | classes of target: processes, core files, and executable files. This | |
1253 | allows you to (for example) start a process and inspect its activity | |
1254 | without abandoning your work on a core file. | |
1255 | ||
1256 | More than one target can potentially respond to a request. In | |
5a131cc7 | 1257 | particular, when you access memory _GDBN__ will walk down the three strata of |
23e2e5e1 RP |
1258 | targets until it finds a target that can handle that particular address. |
1259 | ||
1260 | Strata are always examined in a fixed order: first a process if there is | |
1261 | one, then a core file if there is one, and finally an executable file if | |
1262 | there is one of those. | |
1263 | ||
1264 | When you specify a new target in a given stratum, it replaces any target | |
1265 | previously in that stratum. | |
1266 | ||
1267 | To get rid of a target without replacing it, use the @samp{detach} | |
9d7c0513 RP |
1268 | command. The related command @samp{attach} provides you with a way of |
1269 | choosing a particular running process as a new target. @xref{Attach}. | |
23e2e5e1 | 1270 | |
369a6ade | 1271 | @node Target Commands, , Active Targets, Targets |
23e2e5e1 RP |
1272 | @section Commands for Managing Targets |
1273 | ||
9c91ee3e RP |
1274 | @table @code |
1275 | @item target @var{type} @var{parameters} | |
5a131cc7 | 1276 | Connects the _GDBN__ host environment to a target machine or process. A |
9c91ee3e RP |
1277 | target is typically a protocol for talking to debugging facilities. You |
1278 | use the argument @var{type} to specify the type or protocol of the | |
9d7c0513 RP |
1279 | target machine; for example, @samp{target vxworks} for a TCP/IP link to |
1280 | a VxWorks system. | |
9c91ee3e RP |
1281 | |
1282 | Further @var{parameters} are interpreted by the target protocol, but | |
1283 | typically include things like device names or host names to connect | |
1284 | with, process numbers, and baud rates. Executing | |
1285 | @example | |
1286 | target @var{type} | |
1287 | @end example | |
1288 | ||
23e2e5e1 RP |
1289 | @noindent |
1290 | (without any parameters) will issue a message about what | |
9c91ee3e RP |
1291 | parameters are required for that target type. |
1292 | ||
9c91ee3e | 1293 | @item info targets |
23e2e5e1 RP |
1294 | @kindex info targets |
1295 | Displays the names of all targets available. Beware: the similar | |
1296 | command @samp{info target} displays targets currently in use rather than | |
1297 | all available ones. @samp{info files} gives the same information as | |
469ddd56 | 1298 | @samp{info target} (@pxref{Files}). |
9c91ee3e RP |
1299 | @end table |
1300 | ||
5a131cc7 | 1301 | Here are some common targets (available, or not, depending on _GDBN__ |
9d7c0513 RP |
1302 | configuration): |
1303 | ||
1304 | @table @code | |
9d7c0513 RP |
1305 | @item target exec @var{prog} |
1306 | @kindex target exec | |
1307 | An executable file. @samp{target exec @var{prog}} is the same as | |
1308 | @samp{exec-file @var{prog}}. | |
1309 | ||
1310 | @item target core @var{filename} | |
1311 | @kindex target core | |
1312 | A core dump file. @samp{target core @var{filename}} is the same as | |
1313 | @samp{core-file @var{filename}}. | |
1314 | ||
cb9d2049 RP |
1315 | @item target remote @var{dev} |
1316 | @kindex target remote | |
5a131cc7 | 1317 | Remote serial target in _GDBP__-specific protocol. The argument @var{dev} |
cb9d2049 RP |
1318 | specifies what serial device to use for the connection (e.g. |
1319 | @code{/dev/ttya}). | |
1320 | ||
5a131cc7 | 1321 | _if__(_AMD29K__) |
cb9d2049 RP |
1322 | @item target amd-eb @var{dev} @var{speed} @var{PROG} |
1323 | @kindex target amd-eb | |
1324 | @cindex AMD EB29K | |
1325 | Remote PC-resident AMD EB29K board, attached over serial lines. | |
1326 | @var{dev} is the serial device, as for @samp{target remote}; | |
1327 | @samp{speed} allows you to specify the linespeed; and @var{PROG} is the | |
1328 | name of the program to be debugged, as it appears to DOS on the PC. | |
1329 | @xref{AMD29K Remote}. | |
1330 | ||
5a131cc7 RP |
1331 | _fi__(_AMD29K__) |
1332 | _if__(_I960__) | |
9d7c0513 RP |
1333 | @item target nindy @var{devicename} |
1334 | @kindex target nindy | |
1335 | An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is | |
1336 | the name of the serial device to use for the connection, e.g. | |
1337 | @samp{/dev/ttya}. | |
1338 | ||
5a131cc7 RP |
1339 | _fi__(_I960__) |
1340 | _if__(_VXWORKS__) | |
9d7c0513 RP |
1341 | @item target vxworks @var{machinename} |
1342 | @kindex target vxworks | |
1343 | A VxWorks system, attached via TCP/IP. The argument @var{machinename} | |
1344 | is the target system's machine name or IP address. | |
1345 | ||
5a131cc7 | 1346 | _fi__(_VXWORKS__) |
9d7c0513 RP |
1347 | @end table |
1348 | ||
5a131cc7 RP |
1349 | _if__(_GENERIC__) |
1350 | Different targets are available on different configurations of _GDBN__; your | |
9d7c0513 | 1351 | configuration may have more or fewer targets. |
5a131cc7 | 1352 | _fi__(_GENERIC__) |
9d7c0513 | 1353 | |
9c91ee3e | 1354 | @node Running, Stopping, Targets, Top |
5a131cc7 | 1355 | @chapter Running Programs Under _GDBN__ |
e91b87a3 | 1356 | |
1357 | @cindex running | |
1358 | @kindex run | |
5a131cc7 | 1359 | To start your program under _GDBN__, use the @samp{run} command. Except on |
9c91ee3e | 1360 | VxWorks, the program must already have been specified using the |
5a131cc7 | 1361 | @samp{file} or @samp{exec-file} command, or with an argument to _GDBN__ |
9d7c0513 RP |
1362 | (@pxref{Files}). |
1363 | ||
1364 | On targets that support processes, @samp{run} creates an inferior | |
1365 | process and makes that process run your program. On other targets, | |
1366 | @samp{run} jumps to the location it has recorded for the start of the | |
1367 | program. | |
e91b87a3 | 1368 | |
4187119d | 1369 | The execution of a program is affected by certain information it |
5a131cc7 | 1370 | receives from its superior. _GDBN__ provides ways to specify this |
4187119d | 1371 | information, which you must do @i{before} starting the program. (You |
1372 | can change it after starting the program, but such changes do not affect | |
1373 | the program unless you start it over again.) This information may be | |
1374 | divided into three categories: | |
e91b87a3 | 1375 | |
1376 | @table @asis | |
1377 | @item The @i{arguments.} | |
1378 | You specify the arguments to give the program as the arguments of the | |
9d7c0513 RP |
1379 | @samp{run} command. If a shell is available on your target, the shell |
1380 | is used to pass the arguments, so that you may use normal conventions | |
1381 | (for example regular expression expansion or variable substitution) in | |
1382 | describing the arguments. In Unix systems, you can control which shell | |
1383 | is used with the @code{SHELL} environment variable. | |
e91b87a3 | 1384 | |
1385 | @item The @i{environment.} | |
5a131cc7 RP |
1386 | The program normally inherits its environment from _GDBN__, but you can |
1387 | use the _GDBN__ commands @samp{set environment} and | |
e91b87a3 | 1388 | @samp{unset environment} to change parts of the environment that will |
1389 | be given to the program.@refill | |
1390 | ||
1391 | @item The @i{working directory.} | |
5a131cc7 RP |
1392 | The program inherits its working directory from _GDBN__. You can set _GDBN__'s |
1393 | working directory with the @samp{cd} command in _GDBN__. | |
e91b87a3 | 1394 | @end table |
1395 | ||
9c91ee3e RP |
1396 | When you issue the @samp{run} command, your program begins to execute |
1397 | immediately. @xref{Stopping}, for discussion of how to arrange for your | |
1398 | program to stop. | |
e91b87a3 | 1399 | |
1400 | Note that once your program has been started by the @samp{run} command, | |
1401 | you may evaluate expressions that involve calls to functions in the | |
9c91ee3e RP |
1402 | inferior, using the @samp{print} or @samp{call} commands. @xref{Data}. |
1403 | ||
9d7c0513 | 1404 | If the modification time of your symbol file has changed since the last |
5a131cc7 | 1405 | time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and re-read |
9d7c0513 | 1406 | it. In this process, it tries to retain your current breakpoints. |
e91b87a3 | 1407 | |
1408 | @menu | |
54e4a398 RP |
1409 | * Arguments:: Specifying the arguments for your program. |
1410 | * Environment:: Specifying the environment for your program. | |
1411 | * Working Directory:: Specifying the working directory for giving | |
e91b87a3 | 1412 | to your program when it is run. |
54e4a398 | 1413 | * Input/Output:: Specifying the program's standard input and output. |
5a131cc7 | 1414 | * Attach:: Debugging a process started outside _GDBN__. |
54e4a398 | 1415 | * Kill Process:: Getting rid of the child process running your program. |
e91b87a3 | 1416 | @end menu |
1417 | ||
1418 | @node Arguments, Environment, Running, Running | |
1419 | @section Your Program's Arguments | |
1420 | ||
1421 | @cindex arguments (to your program) | |
4187119d | 1422 | The arguments to your program are specified by the arguments of the |
e91b87a3 | 1423 | @samp{run} command. They are passed to a shell, which expands wildcard |
1424 | characters and performs redirection of I/O, and thence to the program. | |
1425 | ||
1426 | @samp{run} with no arguments uses the same arguments used by the previous | |
1427 | @samp{run}. | |
1428 | ||
1429 | @kindex set args | |
9da601bf RP |
1430 | @table @code |
1431 | @item set args | |
e91b87a3 | 1432 | The command @samp{set args} can be used to specify the arguments to be used |
1433 | the next time the program is run. If @samp{set args} has no arguments, it | |
1434 | means to use no arguments the next time the program is run. If you have | |
1435 | run your program with arguments and want to run it again with no arguments, | |
1436 | this is the only way to do so. | |
1437 | ||
9da601bf RP |
1438 | @item show args |
1439 | @kindex show args | |
1440 | Show the arguments to give your program when it is started. | |
1441 | @end table | |
1442 | ||
e91b87a3 | 1443 | @node Environment, Working Directory, Arguments, Running |
1444 | @section Your Program's Environment | |
1445 | ||
1446 | @cindex environment (of your program) | |
1447 | The @dfn{environment} consists of a set of @dfn{environment variables} and | |
1448 | their values. Environment variables conventionally record such things as | |
1449 | your user name, your home directory, your terminal type, and your search | |
1450 | path for programs to run. Usually you set up environment variables with | |
1451 | the shell and they are inherited by all the other programs you run. When | |
1452 | debugging, it can be useful to try running the program with different | |
1453 | environments without having to start the debugger over again. | |
1454 | ||
1455 | @table @code | |
d2e08421 RP |
1456 | @item show environment @var{varname} |
1457 | @kindex show environment | |
e91b87a3 | 1458 | Print the value of environment variable @var{varname} to be given to |
d2e08421 | 1459 | your program when it is started. |
e91b87a3 | 1460 | |
d2e08421 | 1461 | @item show environment |
e91b87a3 | 1462 | Print the names and values of all environment variables to be given to |
d2e08421 | 1463 | your program when it is started. |
e91b87a3 | 1464 | |
1465 | @item set environment @var{varname} @var{value} | |
4187119d | 1466 | @itemx set environment @var{varname} = @var{value} |
e91b87a3 | 1467 | @kindex set environment |
1468 | Sets environment variable @var{varname} to @var{value}, for your program | |
5a131cc7 | 1469 | only, not for _GDBN__ itself. @var{value} may be any string; the values of |
e91b87a3 | 1470 | environment variables are just strings, and any interpretation is |
1471 | supplied by your program itself. The @var{value} parameter is optional; | |
d2e08421 | 1472 | if it is eliminated, the variable is set to a null value. |
e91b87a3 | 1473 | |
4187119d | 1474 | For example, this command: |
1475 | ||
1476 | @example | |
1477 | set env USER = foo | |
1478 | @end example | |
1479 | ||
1480 | @noindent | |
1481 | tells the program, when subsequently run, to assume it is being run | |
1482 | on behalf of the user named @samp{foo}. | |
1483 | ||
e91b87a3 | 1484 | @item delete environment @var{varname} |
4187119d | 1485 | @itemx unset environment @var{varname} |
e91b87a3 | 1486 | @kindex delete environment |
e91b87a3 | 1487 | @kindex unset environment |
4187119d | 1488 | Remove variable @var{varname} from the environment to be passed to your |
9da601bf RP |
1489 | program. This is different from @samp{set env @var{varname}@ =}; |
1490 | @samp{delete environment} removes the variable from the environment, | |
1491 | rather than assigning it an empty value. This command can be | |
1492 | abbreviated @samp{d e}. | |
e91b87a3 | 1493 | @end table |
1494 | ||
1495 | @node Working Directory, Input/Output, Environment, Running | |
1496 | @section Your Program's Working Directory | |
1497 | ||
1498 | @cindex working directory (of your program) | |
4187119d | 1499 | Each time you start your program with @samp{run}, it inherits its |
5a131cc7 | 1500 | working directory from the current working directory of _GDBN__. _GDBN__'s |
4187119d | 1501 | working directory is initially whatever it inherited from its parent |
1502 | process (typically the shell), but you can specify a new working | |
5a131cc7 | 1503 | directory in _GDBN__ with the @samp{cd} command. |
e91b87a3 | 1504 | |
5a131cc7 RP |
1505 | The _GDBN__ working directory also serves as a default for the commands |
1506 | that specify files for _GDBN__ to operate on. @xref{Files}. | |
e91b87a3 | 1507 | |
1508 | @table @code | |
1509 | @item cd @var{directory} | |
1510 | @kindex cd | |
5a131cc7 | 1511 | Set _GDBN__'s working directory to @var{directory}. |
e91b87a3 | 1512 | |
1513 | @item pwd | |
1514 | @kindex pwd | |
5a131cc7 | 1515 | Print _GDBN__'s working directory. |
e91b87a3 | 1516 | @end table |
1517 | ||
1518 | @node Input/Output, Attach, Working Directory, Running | |
1519 | @section Your Program's Input and Output | |
1520 | ||
1521 | @cindex redirection | |
d2e08421 RP |
1522 | @cindex i/o |
1523 | @cindex terminal | |
e91b87a3 | 1524 | @cindex controlling terminal |
5a131cc7 RP |
1525 | By default, the program you run under _GDBN__ does input and output to the same |
1526 | terminal that _GDBN__ uses. | |
e91b87a3 | 1527 | |
1528 | You can redirect the program's input and/or output using @samp{sh}-style | |
1529 | redirection commands in the @samp{run} command. For example, | |
1530 | ||
1531 | @example | |
1532 | run > outfile | |
1533 | @end example | |
1534 | ||
1535 | @noindent | |
1536 | starts the program, diverting its output to the file @file{outfile}. | |
1537 | ||
1538 | @kindex tty | |
4187119d | 1539 | Another way to specify where the program should do input and output is |
1540 | with the @samp{tty} command. This command accepts a file name as | |
1541 | argument, and causes this file to be the default for future @samp{run} | |
1542 | commands. It also resets the controlling terminal for the child | |
1543 | process, for future @samp{run} commands. For example, | |
e91b87a3 | 1544 | |
1545 | @example | |
1546 | tty /dev/ttyb | |
1547 | @end example | |
1548 | ||
1549 | @noindent | |
4187119d | 1550 | directs that processes started with subsequent @samp{run} commands |
1551 | default to do input and output on the terminal @file{/dev/ttyb} and have | |
1552 | that as their controlling terminal. | |
1553 | ||
1554 | An explicit redirection in @samp{run} overrides the @samp{tty} command's | |
1555 | effect on input/output redirection, but not its effect on the | |
1556 | controlling terminal. | |
e91b87a3 | 1557 | |
1558 | When you use the @samp{tty} command or redirect input in the @samp{run} | |
4187119d | 1559 | command, only the @emph{input for your program} is affected. The input |
5a131cc7 | 1560 | for _GDBN__ still comes from your terminal. |
e91b87a3 | 1561 | |
4187119d | 1562 | @node Attach, Kill Process, Input/Output, Running |
e91b87a3 | 1563 | @section Debugging an Already-Running Process |
e91b87a3 | 1564 | @kindex attach |
1565 | @cindex attach | |
1566 | ||
9c91ee3e RP |
1567 | @table @code |
1568 | @item attach @var{process--id} | |
9d7c0513 | 1569 | This command attaches to a running process, if your currently selected |
c81e78d1 RP |
1570 | target supports processes. (@samp{info files} will show your active |
1571 | targets). The command takes as argument a process ID. | |
9c91ee3e RP |
1572 | |
1573 | You specify a process ID to debug an already-running process that was | |
5a131cc7 | 1574 | started outside of _GDBN__. (The usual way to find out the process-id of |
9d7c0513 | 1575 | a Unix process is with the @code{ps} utility, or with the @code{jobs -l} |
9c91ee3e RP |
1576 | shell command.) In this case, you must have permission to send the |
1577 | process a signal, and it must have the same effective user ID as the | |
1578 | debugger. | |
1579 | @end table | |
e91b87a3 | 1580 | |
9c91ee3e RP |
1581 | When using @samp{attach}, you should first use the @samp{file} command |
1582 | to specify the program running in the process and load its symbol table. | |
e91b87a3 | 1583 | |
5a131cc7 RP |
1584 | The first thing _GDBN__ does after arranging to debug the process is to stop |
1585 | it. You can examine and modify an attached process with all the _GDBN__ | |
e91b87a3 | 1586 | commands that ordinarily available when you start processes with |
1587 | @samp{run}. You can insert breakpoints; you can step and continue; you | |
1588 | can modify storage. If you would rather the process continue running, | |
5a131cc7 | 1589 | you may use the @samp{continue} command after attaching _GDBN__ to the |
4187119d | 1590 | process. |
e91b87a3 | 1591 | |
c81e78d1 | 1592 | @kindex detach |
4187119d | 1593 | When you have finished debugging the attached process, you can use the |
5a131cc7 | 1594 | @samp{detach} command to release it from _GDBN__'s control. Detaching |
e91b87a3 | 1595 | the process continues its execution. After the @samp{detach} command, |
5a131cc7 | 1596 | that process and _GDBN__ become completely independent once more, and you |
e91b87a3 | 1597 | are ready to @samp{attach} another process or start one with @samp{run}. |
1598 | ||
5a131cc7 | 1599 | If you exit _GDBN__ or use the @samp{run} command while you have an attached |
9c91ee3e RP |
1600 | process, you kill that process. By default, you will be asked for |
1601 | confirmation if you try to do either of these things; you can control | |
d2e08421 | 1602 | whether or not this happens by using the @samp{set caution} command |
9c91ee3e | 1603 | (@pxref{User Interface}). |
e91b87a3 | 1604 | |
54e4a398 | 1605 | @node Kill Process, , Attach, Running |
4187119d | 1606 | @section Killing the Child Process |
1607 | ||
1608 | @table @code | |
1609 | @item kill | |
1610 | @kindex kill | |
5a131cc7 | 1611 | Kill the child process in which your program is running under _GDBN__. |
9c91ee3e | 1612 | @end table |
4187119d | 1613 | |
5a131cc7 | 1614 | This command is useful if you wish to debug a core dump instead. _GDBN__ |
9da601bf | 1615 | ignores any core dump file if it is actually running the program. |
4187119d | 1616 | |
9c91ee3e | 1617 | On some operating systems, you can't execute your program in another |
5a131cc7 | 1618 | process while breakpoints are active inside _GDBN__. The @samp{kill} |
9da601bf RP |
1619 | command is also useful in this situation, if you wish to run the program |
1620 | outside the debugger. | |
4187119d | 1621 | |
1622 | The @samp{kill} command is also useful if you wish to recompile and | |
1623 | relink the program, since on many systems it is impossible to modify an | |
9c91ee3e | 1624 | executable file which is running in a process. In this case, when you |
5a131cc7 | 1625 | next type @samp{run}, _GDBN__ will notice that the file has changed, and |
9c91ee3e RP |
1626 | will re-read the symbol table (while trying to preserve your current |
1627 | breakpoint settings). | |
4187119d | 1628 | |
e91b87a3 | 1629 | @node Stopping, Stack, Running, Top |
1630 | @chapter Stopping and Continuing | |
1631 | ||
4187119d | 1632 | When you run a program normally, it runs until it terminates. The |
1633 | principal purpose of using a debugger is so that you can stop it before | |
1634 | that point; or so that if the program runs into trouble you can | |
1635 | investigate and find out why. | |
e91b87a3 | 1636 | |
1637 | @menu | |
54e4a398 | 1638 | * Signals:: Fatal signals in your program just stop it; |
5a131cc7 | 1639 | then you can use _GDBN__ to see what is going on. |
54e4a398 | 1640 | * Breakpoints:: Breakpoints let you stop your program when it |
e91b87a3 | 1641 | reaches a specified point in the code. |
96a816c5 | 1642 | an expression changes. |
54e4a398 RP |
1643 | * Continuing:: Resuming execution until the next signal or breakpoint. |
1644 | * Stepping:: Stepping runs the program a short distance and | |
e91b87a3 | 1645 | then stops it wherever it has come to. |
1646 | @end menu | |
1647 | ||
1648 | @node Signals, Breakpoints, Stopping, Stopping | |
1649 | @section Signals | |
4187119d | 1650 | @cindex signals |
e91b87a3 | 1651 | |
1652 | A signal is an asynchronous event that can happen in a program. The | |
1653 | operating system defines the possible kinds of signals, and gives each kind | |
1654 | a name and a number. For example, @code{SIGINT} is the signal a program | |
1655 | gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program | |
1656 | gets from referencing a place in memory far away from all the areas in use; | |
1657 | @code{SIGALRM} occurs when the alarm clock timer goes off (which happens | |
1658 | only if the program has requested an alarm). | |
1659 | ||
4187119d | 1660 | @cindex fatal signals |
e91b87a3 | 1661 | Some signals, including @code{SIGALRM}, are a normal part of the |
1662 | functioning of the program. Others, such as @code{SIGSEGV}, indicate | |
1663 | errors; these signals are @dfn{fatal} (kill the program immediately) if the | |
1664 | program has not specified in advance some other way to handle the signal. | |
1665 | @code{SIGINT} does not indicate an error in the program, but it is normally | |
1666 | fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program. | |
1667 | ||
5a131cc7 RP |
1668 | _GDBN__ has the ability to detect any occurrence of a signal in the program |
1669 | running under _GDBN__'s control. You can tell _GDBN__ in advance what to do for | |
e91b87a3 | 1670 | each kind of signal. |
1671 | ||
4187119d | 1672 | @cindex handling signals |
5a131cc7 | 1673 | Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM} |
e91b87a3 | 1674 | (so as not to interfere with their role in the functioning of the program) |
1675 | but to stop the program immediately whenever an error signal happens. | |
831c8511 | 1676 | You can change these settings with the @samp{handle} command. |
e91b87a3 | 1677 | |
1678 | @table @code | |
1679 | @item info signal | |
1680 | @kindex info signal | |
5a131cc7 | 1681 | Print a table of all the kinds of signals and how _GDBN__ has been told to |
e91b87a3 | 1682 | handle each one. You can use this to see the signal numbers of all |
1683 | the defined types of signals. | |
1684 | ||
831c8511 | 1685 | @item handle @var{signal} @var{keywords}@dots{} |
e91b87a3 | 1686 | @kindex handle |
5a131cc7 | 1687 | Change the way _GDBN__ handles signal @var{signal}. @var{signal} can be the |
831c8511 JG |
1688 | number of a signal or its name (with or without the @samp{SIG} at the |
1689 | beginning). The @var{keywords} say what change to make. | |
e91b87a3 | 1690 | @end table |
1691 | ||
9da601bf RP |
1692 | The keywords allowed by the @samp{handle} command can be abbreviated. |
1693 | Their full names are | |
e91b87a3 | 1694 | |
1695 | @table @code | |
9da601bf | 1696 | @item nostop |
5a131cc7 | 1697 | _GDBN__ should not stop the program when this signal happens. It may |
9da601bf RP |
1698 | still print a message telling you that the signal has come in. |
1699 | ||
e91b87a3 | 1700 | @item stop |
5a131cc7 | 1701 | _GDBN__ should stop the program when this signal happens. This implies |
e91b87a3 | 1702 | the @samp{print} keyword as well. |
1703 | ||
1704 | @item print | |
5a131cc7 | 1705 | _GDBN__ should print a message when this signal happens. |
e91b87a3 | 1706 | |
e91b87a3 | 1707 | @item noprint |
5a131cc7 | 1708 | _GDBN__ should not mention the occurrence of the signal at all. This |
e91b87a3 | 1709 | implies the @samp{nostop} keyword as well. |
1710 | ||
1711 | @item pass | |
5a131cc7 | 1712 | _GDBN__ should allow the program to see this signal; the program will be |
e91b87a3 | 1713 | able to handle the signal, or may be terminated if the signal is fatal |
1714 | and not handled. | |
1715 | ||
1716 | @item nopass | |
5a131cc7 | 1717 | _GDBN__ should not allow the program to see this signal. |
e91b87a3 | 1718 | @end table |
1719 | ||
1720 | When a signal has been set to stop the program, the program cannot see the | |
1721 | signal until you continue. It will see the signal then, if @samp{pass} is | |
1722 | in effect for the signal in question @i{at that time}. In other words, | |
5a131cc7 | 1723 | after _GDBN__ reports a signal, you can use the @samp{handle} command with |
e91b87a3 | 1724 | @samp{pass} or @samp{nopass} to control whether that signal will be seen by |
1725 | the program when you later continue it. | |
1726 | ||
1727 | You can also use the @samp{signal} command to prevent the program from | |
1728 | seeing a signal, or cause it to see a signal it normally would not see, | |
1729 | or to give it any signal at any time. @xref{Signaling}. | |
1730 | ||
54e4a398 | 1731 | @node Breakpoints, Continuing, Signals, Stopping |
e91b87a3 | 1732 | @section Breakpoints |
1733 | ||
1734 | @cindex breakpoints | |
1735 | A @dfn{breakpoint} makes your program stop whenever a certain point in the | |
5a131cc7 | 1736 | program is reached. You set breakpoints explicitly with _GDBN__ commands, |
e91b87a3 | 1737 | specifying the place where the program should stop by line number, function |
1738 | name or exact address in the program. You can add various other conditions | |
1739 | to control whether the program will stop. | |
1740 | ||
1741 | Each breakpoint is assigned a number when it is created; these numbers are | |
1742 | successive integers starting with 1. In many of the commands for controlling | |
1743 | various features of breakpoints you use the breakpoint number to say which | |
1744 | breakpoint you want to change. Each breakpoint may be @dfn{enabled} or | |
1745 | @dfn{disabled}; if disabled, it has no effect on the program until you | |
1746 | enable it again. | |
1747 | ||
9c91ee3e | 1748 | @table @code |
e91b87a3 | 1749 | @kindex info break |
1750 | @kindex $_ | |
9c91ee3e | 1751 | @item info break |
e91b87a3 | 1752 | The command @samp{info break} prints a list of all breakpoints set and not |
4187119d | 1753 | deleted, showing their numbers, where in the program they are, and any |
e91b87a3 | 1754 | special features in use for them. Disabled breakpoints are included in the |
1755 | list, but marked as disabled. @samp{info break} with a breakpoint number | |
4187119d | 1756 | as argument lists only that breakpoint. The convenience variable @code{$_} |
e91b87a3 | 1757 | and the default examining-address for the @samp{x} command are set to the |
1758 | address of the last breakpoint listed (@pxref{Memory}). | |
1759 | ||
96a816c5 JG |
1760 | @kindex info watch |
1761 | @item info watch | |
1762 | This command prints a list of watchpoints. | |
9c91ee3e RP |
1763 | |
1764 | @cindex watchpoints | |
1765 | A @dfn{watchpoint} is a special breakpoint that stops your program when | |
1766 | the value of an expression changes. You can use a watchpoint to stop | |
1767 | execution whenever the value of an expression changes, without having to | |
1768 | predict a particular place in the inferior process where this may | |
1769 | happen. Aside from the different syntax in setting a watchpoint, it is | |
1770 | managed exactly like any other breakpoint and is enabled, disabled, and | |
9da601bf | 1771 | deleted using exactly the same commands. |
9c91ee3e | 1772 | |
9da601bf RP |
1773 | Watchpoints currently execute two orders of magnitude more slowly than |
1774 | other breakpoints, but this can well be worth it to catch errors where | |
1775 | you have no clue what part of your program is the culprit. Some | |
1776 | processors provide special hardware to implement this feature; future | |
5a131cc7 | 1777 | releases of _GDBN__ will use such hardware if it is available. |
9c91ee3e | 1778 | |
6ad6aa52 | 1779 | @end table |
96a816c5 | 1780 | |
e91b87a3 | 1781 | @menu |
54e4a398 | 1782 | * Set Breaks:: How to establish breakpoints. |
5a131cc7 | 1783 | * Exception Handling:: How _GDBN__ supports exception handling for C++. |
54e4a398 RP |
1784 | * Delete Breaks:: How to remove breakpoints no longer needed. |
1785 | * Disabling:: How to disable breakpoints (turn them off temporarily). | |
1786 | * Conditions:: Making extra conditions on whether to stop. | |
1787 | * Break Commands:: Commands to be executed at a breakpoint. | |
1788 | * Error in Breakpoints:: | |
e91b87a3 | 1789 | @end menu |
1790 | ||
d2e08421 | 1791 | @node Set Breaks, Exception Handling, Breakpoints, Breakpoints |
e91b87a3 | 1792 | @subsection Setting Breakpoints |
1793 | ||
1794 | @kindex break | |
96a816c5 | 1795 | @kindex watch |
e91b87a3 | 1796 | Breakpoints are set with the @samp{break} command (abbreviated @samp{b}). |
96a816c5 JG |
1797 | Watchpoints are set with the @samp{watch} command. |
1798 | ||
e91b87a3 | 1799 | You have several ways to say where the breakpoint should go. |
1800 | ||
1801 | @table @code | |
1802 | @item break @var{function} | |
1803 | Set a breakpoint at entry to function @var{function}. | |
1804 | ||
4187119d | 1805 | @item break @var{+offset} |
1806 | @itemx break @var{-offset} | |
1807 | Set a breakpoint some number of lines forward or back from the position | |
1808 | at which execution stopped in the currently selected frame. | |
1809 | ||
e91b87a3 | 1810 | @item break @var{linenum} |
1811 | Set a breakpoint at line @var{linenum} in the current source file. | |
1812 | That file is the last file whose source text was printed. This | |
1813 | breakpoint will stop the program just before it executes any of the | |
1814 | code on that line. | |
1815 | ||
1816 | @item break @var{filename}:@var{linenum} | |
1817 | Set a breakpoint at line @var{linenum} in source file @var{filename}. | |
1818 | ||
1819 | @item break @var{filename}:@var{function} | |
1820 | Set a breakpoint at entry to function @var{function} found in file | |
4187119d | 1821 | @var{filename}. Specifying a file name as well as a function name is |
e91b87a3 | 1822 | superfluous except when multiple files contain similarly named |
1823 | functions. | |
1824 | ||
1825 | @item break *@var{address} | |
1826 | Set a breakpoint at address @var{address}. You can use this to set | |
1827 | breakpoints in parts of the program which do not have debugging | |
1828 | information or source files. | |
1829 | ||
1830 | @item break | |
1831 | Set a breakpoint at the next instruction to be executed in the selected | |
1832 | stack frame (@pxref{Stack}). In any selected frame but the innermost, | |
1833 | this will cause the program to stop as soon as control returns to that | |
1834 | frame. This is equivalent to a @samp{finish} command in the frame | |
5a131cc7 | 1835 | inside the selected frame. If this is done in the innermost frame, _GDBN__ |
e91b87a3 | 1836 | will stop the next time it reaches the current location; this may be |
4187119d | 1837 | useful inside of loops. |
1838 | ||
5a131cc7 | 1839 | _GDBN__ normally ignores breakpoints when it resumes execution, until at |
4187119d | 1840 | least one instruction has been executed. If it did not do this, you |
1841 | would be unable to proceed past a breakpoint without first disabling the | |
1842 | breakpoint. This rule applies whether or not the breakpoint already | |
1843 | existed when the program stopped. | |
e91b87a3 | 1844 | |
1845 | @item break @dots{} if @var{cond} | |
1846 | Set a breakpoint with condition @var{cond}; evaluate the expression | |
1847 | @var{cond} each time the breakpoint is reached, and stop only if the | |
1848 | value is nonzero. @samp{@dots{}} stands for one of the possible | |
1849 | arguments described above (or no argument) specifying where to break. | |
1850 | @xref{Conditions}, for more information on breakpoint conditions. | |
1851 | ||
1852 | @item tbreak @var{args} | |
1853 | @kindex tbreak | |
1854 | Set a breakpoint enabled only for one stop. @var{args} are the | |
1855 | same as in the @samp{break} command, and the breakpoint is set in the same | |
4187119d | 1856 | way, but the breakpoint is automatically disabled the first time it |
1857 | is hit. @xref{Disabling}. | |
96a816c5 | 1858 | |
6ad6aa52 RP |
1859 | @item rbreak @var{regex} |
1860 | @kindex rbreak | |
1861 | Set a breakpoint on all functions matching @var{regex}. This is | |
1862 | useful for setting breakpoints on overloaded functions that are not | |
1863 | members of any special classes. This command sets an unconditional | |
1864 | breakpoint on all matches, printing a list of all breakpoints it set. | |
1865 | Once these breakpoints are set, they are treated just like the | |
1866 | breakpoints set with the @samp{break} command. They can be deleted, | |
1867 | disabled, made conditional, etc., in the standard ways. | |
1868 | ||
96a816c5 | 1869 | @kindex watch |
9c91ee3e | 1870 | @item watch @var{expr} |
96a816c5 | 1871 | Set a watchpoint for an expression. |
e91b87a3 | 1872 | @end table |
1873 | ||
5a131cc7 | 1874 | _GDBN__ allows you to set any number of breakpoints at the same place in the |
e91b87a3 | 1875 | program. There is nothing silly or meaningless about this. When the |
1876 | breakpoints are conditional, this is even useful (@pxref{Conditions}). | |
1877 | ||
d2e08421 | 1878 | @node Exception Handling, Delete Breaks, Set Breaks, Breakpoints |
cb9d2049 | 1879 | @subsection Breakpoints and Exceptions |
d2e08421 RP |
1880 | @cindex exception handlers |
1881 | ||
5a131cc7 | 1882 | Some languages, such as GNU C++, implement exception handling. _GDBN__ |
d2e08421 RP |
1883 | can be used to examine what caused the program to raise an exception |
1884 | and to list the exceptions the program is prepared to handle at a | |
1885 | given point in time. | |
1886 | ||
1887 | @cindex raise exceptions | |
1888 | GNU C++ raises an exception by calling a library function named | |
1889 | @code{__raise_exception} which has the following ANSI C interface: | |
1890 | ||
1891 | @example | |
1892 | /* ADDR is where the exception identifier is stored. | |
1893 | ID is the exception identifier. */ | |
1894 | void __raise_exception (void **addr, void *id); | |
1895 | @end example | |
1896 | ||
1897 | @noindent | |
1898 | You can make the debugger catch all exceptions @emph{before} any stack | |
1899 | unwinding takes place: set a breakpoint on @code{__raise_exception} | |
1900 | (@pxref{Breakpoints}). If you set a breakpoint in an exception handler | |
1901 | instead, it may not be easy to find out where the exception was raised. | |
1902 | ||
1903 | By using a conditional breakpoint (@xref{Conditions}), you can cause | |
1904 | the debugger to stop only when a specific exception is raised. | |
1905 | Multiple conditional breakpoints can be used to stop the program when | |
1906 | any of a number of exceptions are raised. | |
1907 | ||
1908 | @table @code | |
1909 | @item catch @var{exceptions} | |
1910 | @kindex catch | |
1911 | ||
1912 | Breakpoints can be set at active exception handlers by using the | |
1913 | @samp{catch} command. @var{exceptions} is a list of names of exceptions | |
1914 | to catch. | |
1915 | @end table | |
1916 | ||
1917 | You can use @samp{info catch} to list active exception handlers; | |
1918 | @pxref{Frame Info}. | |
1919 | ||
5a131cc7 | 1920 | There are currently some limitations to exception handling in _GDBN__. |
d2e08421 RP |
1921 | These will be corrected in a future release. |
1922 | ||
1923 | @itemize @bullet | |
1924 | @item | |
5a131cc7 | 1925 | If you call a function interactively, _GDBN__ will normally return |
d2e08421 RP |
1926 | control to you when the function has finished executing. If the call |
1927 | raises an exception, however, the call may bypass the mechanism that | |
1928 | returns control to the user and cause the program to simply continue | |
5a131cc7 | 1929 | running until it hits a breakpoint, catches a signal that _GDBN__ is |
d2e08421 RP |
1930 | listening for, or exits. |
1931 | @item | |
1932 | You cannot raise an exception interactively. | |
1933 | @item | |
1934 | You cannot interactively install an exception handler. | |
1935 | @end itemize | |
1936 | ||
54e4a398 | 1937 | @node Delete Breaks, Disabling, Exception Handling, Breakpoints |
4187119d | 1938 | @subsection Deleting Breakpoints |
e91b87a3 | 1939 | |
cb9d2049 RP |
1940 | @cindex clearing breakpoints, watchpoints |
1941 | @cindex deleting breakpoints, watchpoints | |
e91b87a3 | 1942 | It is often necessary to eliminate a breakpoint once it has done its job |
1943 | and you no longer want the program to stop there. This is called | |
4187119d | 1944 | @dfn{deleting} the breakpoint. A breakpoint that has been deleted no |
1945 | longer exists in any sense; it is forgotten. | |
e91b87a3 | 1946 | |
4187119d | 1947 | With the @samp{clear} command you can delete breakpoints according to where |
1948 | they are in the program. With the @samp{delete} command you can delete | |
e91b87a3 | 1949 | individual breakpoints by specifying their breakpoint numbers. |
1950 | ||
5a131cc7 | 1951 | It is not necessary to delete a breakpoint to proceed past it. _GDBN__ |
9da601bf | 1952 | automatically ignores breakpoints on the first instruction to be executed |
4187119d | 1953 | when you continue execution without changing the execution address. |
e91b87a3 | 1954 | |
1955 | @table @code | |
1956 | @item clear | |
1957 | @kindex clear | |
4187119d | 1958 | Delete any breakpoints at the next instruction to be executed in the |
e91b87a3 | 1959 | selected stack frame (@pxref{Selection}). When the innermost frame |
4187119d | 1960 | is selected, this is a good way to delete a breakpoint that the program |
e91b87a3 | 1961 | just stopped at. |
1962 | ||
1963 | @item clear @var{function} | |
1964 | @itemx clear @var{filename}:@var{function} | |
4187119d | 1965 | Delete any breakpoints set at entry to the function @var{function}. |
e91b87a3 | 1966 | |
1967 | @item clear @var{linenum} | |
4187119d | 1968 | @itemx clear @var{filename}:@var{linenum} |
1969 | Delete any breakpoints set at or within the code of the specified line. | |
e91b87a3 | 1970 | |
9da601bf | 1971 | @item delete breakpoints @var{bnums}@dots{} |
9da601bf | 1972 | @itemx delete @var{bnums}@dots{} |
26376b06 RP |
1973 | @itemx delete |
1974 | @kindex delete breakpoints | |
e91b87a3 | 1975 | @kindex delete |
26376b06 RP |
1976 | Delete the breakpoints of the numbers specified as arguments. If no |
1977 | argument is specified, delete all breakpoints. | |
e91b87a3 | 1978 | @end table |
1979 | ||
4187119d | 1980 | @node Disabling, Conditions, Delete Breaks, Breakpoints |
e91b87a3 | 1981 | @subsection Disabling Breakpoints |
1982 | ||
1983 | @cindex disabled breakpoints | |
1984 | @cindex enabled breakpoints | |
4187119d | 1985 | Rather than deleting a breakpoint, you might prefer to @dfn{disable} it. |
1986 | This makes the breakpoint inoperative as if it had been deleted, but | |
e91b87a3 | 1987 | remembers the information on the breakpoint so that you can @dfn{enable} |
1988 | it again later. | |
1989 | ||
1990 | You disable and enable breakpoints with the @samp{enable} and | |
26376b06 RP |
1991 | @samp{disable} commands, optionally specifying one or more breakpoint |
1992 | numbers as arguments. Use @samp{info break} to print a list of | |
1993 | breakpoints if you don't know which breakpoint numbers to use. | |
e91b87a3 | 1994 | |
1995 | A breakpoint can have any of four different states of enablement: | |
1996 | ||
1997 | @itemize @bullet | |
1998 | @item | |
1999 | Enabled. The breakpoint will stop the program. A breakpoint made | |
2000 | with the @samp{break} command starts out in this state. | |
2001 | @item | |
2002 | Disabled. The breakpoint has no effect on the program. | |
2003 | @item | |
2004 | Enabled once. The breakpoint will stop the program, but | |
2005 | when it does so it will become disabled. A breakpoint made | |
2006 | with the @samp{tbreak} command starts out in this state. | |
2007 | @item | |
2008 | Enabled for deletion. The breakpoint will stop the program, but | |
2009 | immediately after it does so it will be deleted permanently. | |
2010 | @end itemize | |
2011 | ||
9c91ee3e | 2012 | You can use the following commands to enable or disable a breakpoint: |
e91b87a3 | 2013 | |
2014 | @table @code | |
2015 | @item disable breakpoints @var{bnums}@dots{} | |
4187119d | 2016 | @itemx disable @var{bnums}@dots{} |
26376b06 | 2017 | @itemx disable |
e91b87a3 | 2018 | @kindex disable breakpoints |
e91b87a3 | 2019 | @kindex disable |
26376b06 RP |
2020 | Disable the specified breakpoints---or all breakpoints, if none are |
2021 | listed. A disabled breakpoint has no effect but is not forgotten. All | |
2022 | options such as ignore-counts, conditions and commands are remembered in | |
2023 | case the breakpoint is enabled again later. | |
e91b87a3 | 2024 | |
2025 | @item enable breakpoints @var{bnums}@dots{} | |
4187119d | 2026 | @itemx enable @var{bnums}@dots{} |
26376b06 | 2027 | @itemx enable |
e91b87a3 | 2028 | @kindex enable breakpoints |
e91b87a3 | 2029 | @kindex enable |
26376b06 RP |
2030 | Enable the specified breakpoints (or all defined breakpoints). They |
2031 | become effective once again in stopping the program, until you specify | |
2032 | otherwise. | |
e91b87a3 | 2033 | |
2034 | @item enable breakpoints once @var{bnums}@dots{} | |
4187119d | 2035 | @itemx enable once @var{bnums}@dots{} |
e91b87a3 | 2036 | Enable the specified breakpoints temporarily. Each will be disabled |
2037 | again the next time it stops the program (unless you have used one of | |
2038 | these commands to specify a different state before that time comes). | |
2039 | ||
2040 | @item enable breakpoints delete @var{bnums}@dots{} | |
4187119d | 2041 | @itemx enable delete @var{bnums}@dots{} |
e91b87a3 | 2042 | Enable the specified breakpoints to work once and then die. Each of |
2043 | the breakpoints will be deleted the next time it stops the program | |
2044 | (unless you have used one of these commands to specify a different | |
2045 | state before that time comes). | |
2046 | @end table | |
2047 | ||
d2e08421 | 2048 | Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks}), |
9c91ee3e RP |
2049 | breakpoints that you set are enabled or disabled only when you use one |
2050 | of the commands above. (The command @samp{until} can set and delete a | |
2051 | breakpoint on its own, but it will not change the state of your | |
2052 | breakpoints). | |
e91b87a3 | 2053 | |
2054 | @node Conditions, Break Commands, Disabling, Breakpoints | |
2055 | @subsection Break Conditions | |
4187119d | 2056 | @cindex conditional breakpoints |
2057 | @cindex breakpoint conditions | |
e91b87a3 | 2058 | |
e91b87a3 | 2059 | The simplest sort of breakpoint breaks every time the program reaches a |
4187119d | 2060 | specified place. You can also specify a @dfn{condition} for a |
2061 | breakpoint. A condition is just a boolean expression in your | |
2062 | programming language. (@xref{Expressions}). A breakpoint with a | |
2063 | condition evaluates the expression each time the program reaches it, and | |
2064 | the program stops only if the condition is true. | |
e91b87a3 | 2065 | |
2066 | Break conditions may have side effects, and may even call functions in your | |
2067 | program. These may sound like strange things to do, but their effects are | |
2068 | completely predictable unless there is another enabled breakpoint at the | |
5a131cc7 | 2069 | same address. (In that case, _GDBN__ might see the other breakpoint first and |
e91b87a3 | 2070 | stop the program without checking the condition of this one.) Note that |
2071 | breakpoint commands are usually more convenient and flexible for the | |
2072 | purpose of performing side effects when a breakpoint is reached | |
2073 | (@pxref{Break Commands}). | |
2074 | ||
2075 | Break conditions can be specified when a breakpoint is set, by using | |
2076 | @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}. | |
2077 | They can also be changed at any time with the @samp{condition} command: | |
2078 | ||
2079 | @table @code | |
2080 | @item condition @var{bnum} @var{expression} | |
2081 | @kindex condition | |
2082 | Specify @var{expression} as the break condition for breakpoint number | |
2083 | @var{bnum}. From now on, this breakpoint will stop the program only if | |
2084 | the value of @var{expression} is true (nonzero, in C). @var{expression} | |
2085 | is not evaluated at the time the @samp{condition} command is given. | |
9da601bf RP |
2086 | When you call @samp{condition}, the expression you specify is checked |
2087 | immediately for syntactic correctness, and to determine whether symbols | |
2088 | in it have referents in the context of your breakpoint. | |
e91b87a3 | 2089 | @xref{Expressions}. |
2090 | ||
2091 | @item condition @var{bnum} | |
2092 | Remove the condition from breakpoint number @var{bnum}. It becomes | |
2093 | an ordinary unconditional breakpoint. | |
2094 | @end table | |
2095 | ||
2096 | @cindex ignore count (of breakpoint) | |
4187119d | 2097 | A special case of a breakpoint condition is to stop only when the |
2098 | breakpoint has been reached a certain number of times. This is so | |
2099 | useful that there is a special way to do it, using the @dfn{ignore | |
2100 | count} of the breakpoint. Every breakpoint has an ignore count, which | |
2101 | is an integer. Most of the time, the ignore count is zero, and | |
2102 | therefore has no effect. But if the program reaches a breakpoint whose | |
2103 | ignore count is positive, then instead of stopping, it just decrements | |
2104 | the ignore count by one and continues. As a result, if the ignore count | |
2105 | value is @var{n}, the breakpoint will not stop the next @var{n} times it | |
2106 | is reached. | |
e91b87a3 | 2107 | |
2108 | @table @code | |
2109 | @item ignore @var{bnum} @var{count} | |
2110 | @kindex ignore | |
2111 | Set the ignore count of breakpoint number @var{bnum} to @var{count}. | |
9c91ee3e | 2112 | The next @var{count} times the breakpoint is reached, your program's |
5a131cc7 | 2113 | execution will not stop; other than to decrement the ignore count, _GDBN__ |
9c91ee3e | 2114 | takes no action. |
e91b87a3 | 2115 | |
2116 | To make the breakpoint stop the next time it is reached, specify | |
2117 | a count of zero. | |
2118 | ||
9da601bf RP |
2119 | @item continue @var{count} |
2120 | @itemx cont @var{count} | |
9d7c0513 RP |
2121 | @itemx c @var{count} |
2122 | @itemx fg @var{count} | |
9da601bf RP |
2123 | @kindex cont @var{count} |
2124 | @kindex continue @var{count} | |
e91b87a3 | 2125 | Continue execution of the program, setting the ignore count of the |
2126 | breakpoint that the program stopped at to @var{count} minus one. | |
4187119d | 2127 | Thus, the program will not stop at this breakpoint until the |
2128 | @var{count}'th time it is reached. | |
e91b87a3 | 2129 | |
2130 | This command is allowed only when the program stopped due to a | |
2131 | breakpoint. At other times, the argument to @samp{cont} is ignored. | |
9d7c0513 RP |
2132 | |
2133 | The synonym @samp{fg} is provided purely for convenience, and has | |
2134 | exactly the same behavior as other forms of the command. | |
e91b87a3 | 2135 | @end table |
2136 | ||
2137 | If a breakpoint has a positive ignore count and a condition, the condition | |
2138 | is not checked. Once the ignore count reaches zero, the condition will | |
9da601bf | 2139 | be checked. |
e91b87a3 | 2140 | |
4187119d | 2141 | Note that you could achieve the effect of the ignore count with a |
2142 | condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience | |
2143 | variable that is decremented each time. @xref{Convenience Vars}. | |
e91b87a3 | 2144 | |
2145 | @node Break Commands, Error in Breakpoints, Conditions, Breakpoints | |
2146 | @subsection Commands Executed on Breaking | |
2147 | ||
2148 | @cindex breakpoint commands | |
2149 | You can give any breakpoint a series of commands to execute when the | |
2150 | program stops due to that breakpoint. For example, you might want to | |
2151 | print the values of certain expressions, or enable other breakpoints. | |
2152 | ||
2153 | @table @code | |
2154 | @item commands @var{bnum} | |
9da601bf RP |
2155 | @kindex commands |
2156 | Specify a list of commands for breakpoint number @var{bnum}. The commands | |
e91b87a3 | 2157 | themselves appear on the following lines. Type a line containing just |
2158 | @samp{end} to terminate the commands. | |
2159 | ||
2160 | To remove all commands from a breakpoint, use the command | |
2161 | @samp{commands} and follow it immediately by @samp{end}; that is, give | |
2162 | no commands. | |
2163 | ||
9da601bf RP |
2164 | With no arguments, @samp{commands} refers to the last breakpoint set |
2165 | (not to the breakpoint most recently encountered). | |
e91b87a3 | 2166 | @end table |
2167 | ||
9da601bf RP |
2168 | You can use breakpoint commands to start the program up again. Simply |
2169 | use the @samp{cont} command, or @samp{step}, or any other command to | |
2170 | resume execution. However, if you do this, any further commands in the | |
2171 | same breakpoint's command list are ignored. When the program stops | |
5a131cc7 | 2172 | again, _GDBN__ will act according to the cause of that stop. |
e91b87a3 | 2173 | |
2174 | @kindex silent | |
2175 | If the first command specified is @samp{silent}, the usual message about | |
2176 | stopping at a breakpoint is not printed. This may be desirable for | |
2177 | breakpoints that are to print a specific message and then continue. | |
2178 | If the remaining commands too print nothing, you will see no sign that | |
2179 | the breakpoint was reached at all. @samp{silent} is not really a command; | |
2180 | it is meaningful only at the beginning of the commands for a breakpoint. | |
2181 | ||
2182 | The commands @samp{echo} and @samp{output} that allow you to print precisely | |
2183 | controlled output are often useful in silent breakpoints. @xref{Output}. | |
2184 | ||
2185 | For example, here is how you could use breakpoint commands to print the | |
4187119d | 2186 | value of @code{x} at entry to @code{foo} whenever it is positive. |
e91b87a3 | 2187 | |
2188 | @example | |
2189 | break foo if x>0 | |
4187119d | 2190 | commands |
e91b87a3 | 2191 | silent |
2192 | echo x is\040 | |
2193 | output x | |
2194 | echo \n | |
2195 | cont | |
2196 | end | |
2197 | @end example | |
2198 | ||
2199 | One application for breakpoint commands is to correct one bug so you can | |
2200 | test another. Put a breakpoint just after the erroneous line of code, give | |
2201 | it a condition to detect the case in which something erroneous has been | |
2202 | done, and give it commands to assign correct values to any variables that | |
2203 | need them. End with the @samp{cont} command so that the program does not | |
2204 | stop, and start with the @samp{silent} command so that no output is | |
2205 | produced. Here is an example: | |
2206 | ||
2207 | @example | |
2208 | break 403 | |
4187119d | 2209 | commands |
e91b87a3 | 2210 | silent |
2211 | set x = y + 4 | |
2212 | cont | |
2213 | end | |
2214 | @end example | |
2215 | ||
2216 | One deficiency in the operation of automatically continuing breakpoints | |
2217 | under Unix appears when your program uses raw mode for the terminal. | |
5a131cc7 | 2218 | _GDBN__ switches back to its own terminal modes (not raw) before executing |
e91b87a3 | 2219 | commands, and then must switch back to raw mode when your program is |
9da601bf | 2220 | continued. This causes any pending terminal input to be lost. |
e91b87a3 | 2221 | In the GNU system, this will be fixed by changing the behavior of |
2222 | terminal modes. | |
2223 | ||
2224 | Under Unix, when you have this problem, you might be able to get around | |
2225 | it by putting your actions into the breakpoint condition instead of | |
2226 | commands. For example | |
2227 | ||
2228 | @example | |
2229 | condition 5 (x = y + 4), 0 | |
2230 | @end example | |
2231 | ||
2232 | @noindent | |
4187119d | 2233 | specifies a condition expression (@xref{Expressions}) that will change |
2234 | @code{x} as needed, then always have the value 0 so the program will not | |
2235 | stop. Loss of input is avoided here because break conditions are | |
2236 | evaluated without changing the terminal modes. When you want to have | |
2237 | nontrivial conditions for performing the side effects, the operators | |
2238 | @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. | |
e91b87a3 | 2239 | |
54e4a398 | 2240 | @node Error in Breakpoints, , Break Commands, Breakpoints |
cb9d2049 | 2241 | @subsection ``Cannot Insert Breakpoints'' |
e91b87a3 | 2242 | |
cb9d2049 RP |
2243 | @c FIXME: "cannot insert breakpoints" error, v unclear. |
2244 | @c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91 | |
4187119d | 2245 | Under some operating systems, breakpoints cannot be used in a program if |
9da601bf | 2246 | any other process is running that program. In this situation, |
5a131cc7 | 2247 | attempting to run or continue a program with a breakpoint will cause _GDBN__ |
9da601bf | 2248 | to stop the other process. |
e91b87a3 | 2249 | |
2250 | When this happens, you have three ways to proceed: | |
2251 | ||
2252 | @enumerate | |
2253 | @item | |
2254 | Remove or disable the breakpoints, then continue. | |
2255 | ||
2256 | @item | |
5a131cc7 RP |
2257 | Suspend _GDBN__, and copy the file containing the program to a new name. |
2258 | Resume _GDBN__ and use the @samp{exec-file} command to specify that _GDBN__ | |
e91b87a3 | 2259 | should run the program under that name. Then start the program again. |
2260 | ||
2261 | @item | |
4187119d | 2262 | Relink the program so that the text segment is nonsharable, using the |
2263 | linker option @samp{-N}. The operating system limitation may not apply | |
2264 | to nonsharable executables. | |
e91b87a3 | 2265 | @end enumerate |
2266 | ||
2267 | @node Continuing, Stepping, Breakpoints, Stopping | |
2268 | @section Continuing | |
2269 | ||
2270 | After your program stops, most likely you will want it to run some more if | |
2271 | the bug you are looking for has not happened yet. | |
2272 | ||
2273 | @table @code | |
9da601bf | 2274 | @item continue |
e91b87a3 | 2275 | @item cont |
2276 | @kindex cont | |
9da601bf | 2277 | @kindex continue |
e91b87a3 | 2278 | Continue running the program at the place where it stopped. |
2279 | @end table | |
2280 | ||
2281 | If the program stopped at a breakpoint, the place to continue running | |
2282 | is the address of the breakpoint. You might expect that continuing would | |
2283 | just stop at the same breakpoint immediately. In fact, @samp{cont} | |
2284 | takes special care to prevent that from happening. You do not need | |
4187119d | 2285 | to delete the breakpoint to proceed through it after stopping at it. |
e91b87a3 | 2286 | |
2287 | You can, however, specify an ignore-count for the breakpoint that the | |
2288 | program stopped at, by means of an argument to the @samp{cont} command. | |
2289 | @xref{Conditions}. | |
2290 | ||
2291 | If the program stopped because of a signal other than @code{SIGINT} or | |
2292 | @code{SIGTRAP}, continuing will cause the program to see that signal. | |
2293 | You may not want this to happen. For example, if the program stopped | |
2294 | due to some sort of memory reference error, you might store correct | |
2295 | values into the erroneous variables and continue, hoping to see more | |
2296 | execution; but the program would probably terminate immediately as | |
2297 | a result of the fatal signal once it sees the signal. To prevent this, | |
2298 | you can continue with @samp{signal 0}. @xref{Signaling}. You can | |
d2e08421 RP |
2299 | also act in advance to control what signals your program will see, using |
2300 | the @samp{handle} command (@pxref{Signals}). | |
e91b87a3 | 2301 | |
54e4a398 | 2302 | @node Stepping, , Continuing, Stopping |
e91b87a3 | 2303 | @section Stepping |
2304 | ||
2305 | @cindex stepping | |
2306 | @dfn{Stepping} means setting your program in motion for a limited time, so | |
2307 | that control will return automatically to the debugger after one line of | |
2308 | code or one machine instruction. Breakpoints are active during stepping | |
2309 | and the program will stop for them even if it has not gone as far as the | |
2310 | stepping command specifies. | |
2311 | ||
2312 | @table @code | |
2313 | @item step | |
2314 | @kindex step | |
4187119d | 2315 | Continue running the program until control reaches a different line, |
2316 | then stop it and return control to the debugger. This command is | |
2317 | abbreviated @samp{s}. | |
e91b87a3 | 2318 | |
4187119d | 2319 | This command may be given when control is within a function for which |
e91b87a3 | 2320 | there is no debugging information. In that case, execution will proceed |
4187119d | 2321 | until control reaches a different function, or is about to return from |
2322 | this function. An argument repeats this action. | |
2323 | ||
2324 | @item step @var{count} | |
2325 | Continue running as in @samp{step}, but do so @var{count} times. If a | |
2326 | breakpoint is reached or a signal not related to stepping occurs before | |
2327 | @var{count} steps, stepping stops right away. | |
e91b87a3 | 2328 | |
2329 | @item next | |
2330 | @kindex next | |
2331 | Similar to @samp{step}, but any function calls appearing within the line of | |
2332 | code are executed without stopping. Execution stops when control reaches a | |
2333 | different line of code at the stack level which was executing when the | |
2334 | @samp{next} command was given. This command is abbreviated @samp{n}. | |
2335 | ||
2336 | An argument is a repeat count, as in @samp{step}. | |
2337 | ||
4187119d | 2338 | @samp{next} within a function without debugging information acts as does |
e91b87a3 | 2339 | @samp{step}, but any function calls appearing within the code of the |
4187119d | 2340 | function are executed without stopping. |
e91b87a3 | 2341 | |
2342 | @item finish | |
2343 | @kindex finish | |
4187119d | 2344 | Continue running until just after the selected stack frame returns (or |
2345 | until there is some other reason to stop, such as a fatal signal or a | |
2346 | breakpoint). Print value returned by the selected stack frame (if any). | |
e91b87a3 | 2347 | |
2348 | Contrast this with the @samp{return} command (@pxref{Returning}). | |
2349 | ||
2350 | @item until | |
2351 | @kindex until | |
4187119d | 2352 | This command is used to avoid single stepping through a loop more than |
2353 | once. It is like the @samp{next} command, except that when @samp{until} | |
2354 | encounters a jump, it automatically continues execution until the | |
2355 | program counter is greater than the address of the jump. | |
2356 | ||
2357 | This means that when you reach the end of a loop after single stepping | |
2358 | though it, @samp{until} will cause the program to continue execution | |
2359 | until the loop is exited. In contrast, a @samp{next} command at the end | |
2360 | of a loop will simply step back to the beginning of the loop, which | |
2361 | would force you to step through the next iteration. | |
2362 | ||
2363 | @samp{until} always stops the program if it attempts to exit the current | |
2364 | stack frame. | |
2365 | ||
2366 | @samp{until} may produce somewhat counterintuitive results if the order | |
2367 | of the source lines does not match the actual order of execution. For | |
2368 | example, in a typical C @code{for}-loop, the third expression in the | |
2369 | @code{for}-statement (the loop-step expression) is executed after the | |
2370 | statements in the body of the loop, but is written before them. | |
2371 | Therefore, the @samp{until} command would appear to step back to the | |
2372 | beginning of the loop when it advances to this expression. However, it | |
2373 | has not really done so, not in terms of the actual machine code. | |
2374 | ||
2375 | Note that @samp{until} with no argument works by means of single | |
2376 | instruction stepping, and hence is slower than @samp{until} with an | |
2377 | argument. | |
e91b87a3 | 2378 | |
2379 | @item until @var{location} | |
4187119d | 2380 | Continue running the program until either the specified location is |
9c91ee3e RP |
2381 | reached, or the current (innermost) stack frame returns. @var{location} |
2382 | is any of the forms of argument acceptable to @samp{break} (@pxref{Set | |
2383 | Breaks}). This form of the command uses breakpoints, and hence is | |
2384 | quicker than @samp{until} without an argument. | |
e91b87a3 | 2385 | |
2386 | @item stepi | |
2387 | @itemx si | |
2388 | @kindex stepi | |
2389 | @kindex si | |
4187119d | 2390 | Execute one machine instruction, then stop and return to the debugger. |
e91b87a3 | 2391 | |
2392 | It is often useful to do @samp{display/i $pc} when stepping by machine | |
2393 | instructions. This will cause the next instruction to be executed to | |
2394 | be displayed automatically at each stop. @xref{Auto Display}. | |
2395 | ||
2396 | An argument is a repeat count, as in @samp{step}. | |
2397 | ||
2398 | @item nexti | |
2399 | @itemx ni | |
2400 | @kindex nexti | |
2401 | @kindex ni | |
4187119d | 2402 | Execute one machine instruction, but if it is a subroutine call, |
e91b87a3 | 2403 | proceed until the subroutine returns. |
2404 | ||
2405 | An argument is a repeat count, as in @samp{next}. | |
2406 | @end table | |
2407 | ||
2408 | A typical technique for using stepping is to put a breakpoint | |
2409 | (@pxref{Breakpoints}) at the beginning of the function or the section of | |
2410 | the program in which a problem is believed to lie, and then step through | |
2411 | the suspect area, examining the variables that are interesting, until the | |
2412 | problem happens. | |
2413 | ||
2414 | The @samp{cont} command can be used after stepping to resume execution | |
2415 | until the next breakpoint or signal. | |
2416 | ||
2417 | @node Stack, Source, Stopping, Top | |
2418 | @chapter Examining the Stack | |
2419 | ||
2420 | When your program has stopped, the first thing you need to know is where it | |
2421 | stopped and how it got there. | |
2422 | ||
2423 | @cindex call stack | |
2424 | Each time your program performs a function call, the information about | |
2425 | where in the program the call was made from is saved in a block of data | |
2426 | called a @dfn{stack frame}. The frame also contains the arguments of the | |
2427 | call and the local variables of the function that was called. All the | |
2428 | stack frames are allocated in a region of memory called the @dfn{call | |
2429 | stack}. | |
2430 | ||
5a131cc7 | 2431 | When your program stops, the _GDBN__ commands for examining the stack allow you |
e91b87a3 | 2432 | to see all of this information. |
2433 | ||
5a131cc7 | 2434 | One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands |
e91b87a3 | 2435 | refer implicitly to the selected frame. In particular, whenever you ask |
5a131cc7 RP |
2436 | _GDBN__ for the value of a variable in the program, the value is found in the |
2437 | selected frame. There are special _GDBN__ commands to select whichever frame | |
e91b87a3 | 2438 | you are interested in. |
2439 | ||
5a131cc7 | 2440 | When the program stops, _GDBN__ automatically selects the currently executing |
e91b87a3 | 2441 | frame and describes it briefly as the @samp{frame} command does |
2442 | (@pxref{Frame Info, Info}). | |
2443 | ||
2444 | @menu | |
54e4a398 RP |
2445 | * Frames:: Explanation of stack frames and terminology. |
2446 | * Backtrace:: Summarizing many frames at once. | |
2447 | * Selection:: How to select a stack frame. | |
2448 | * Frame Info:: Information on a Frame | |
e91b87a3 | 2449 | @end menu |
2450 | ||
2451 | @node Frames, Backtrace, Stack, Stack | |
2452 | @section Stack Frames | |
2453 | ||
2454 | @cindex frame | |
4187119d | 2455 | @cindex stack frame |
2456 | The call stack is divided up into contiguous pieces called @dfn{stack | |
2457 | frames}, or @dfn{frames} for short; each frame is the data associated | |
2458 | with one call to one function. The frame contains the arguments given | |
2459 | to the function, the function's local variables, and the address at | |
2460 | which the function is executing. | |
e91b87a3 | 2461 | |
2462 | @cindex initial frame | |
2463 | @cindex outermost frame | |
2464 | @cindex innermost frame | |
2465 | When your program is started, the stack has only one frame, that of the | |
2466 | function @code{main}. This is called the @dfn{initial} frame or the | |
2467 | @dfn{outermost} frame. Each time a function is called, a new frame is | |
2468 | made. Each time a function returns, the frame for that function invocation | |
2469 | is eliminated. If a function is recursive, there can be many frames for | |
2470 | the same function. The frame for the function in which execution is | |
2471 | actually occurring is called the @dfn{innermost} frame. This is the most | |
2472 | recently created of all the stack frames that still exist. | |
2473 | ||
2474 | @cindex frame pointer | |
2475 | Inside your program, stack frames are identified by their addresses. A | |
2476 | stack frame consists of many bytes, each of which has its own address; each | |
2477 | kind of computer has a convention for choosing one of those bytes whose | |
2478 | address serves as the address of the frame. Usually this address is kept | |
2479 | in a register called the @dfn{frame pointer register} while execution is | |
2480 | going on in that frame. | |
2481 | ||
2482 | @cindex frame number | |
5a131cc7 | 2483 | _GDBN__ assigns numbers to all existing stack frames, starting with zero for |
e91b87a3 | 2484 | the innermost frame, one for the frame that called it, and so on upward. |
2485 | These numbers do not really exist in your program; they are to give you a | |
5a131cc7 | 2486 | way of talking about stack frames in _GDBN__ commands. |
e91b87a3 | 2487 | |
2488 | @cindex selected frame | |
5a131cc7 | 2489 | Many _GDBN__ commands refer implicitly to one stack frame, called the |
d2e08421 | 2490 | @dfn{selected} stack frame. You can select any frame using one set of |
5a131cc7 RP |
2491 | _GDBN__ commands, and then other commands will operate on that frame. When |
2492 | your program stops, _GDBN__ automatically selects the innermost frame. | |
e91b87a3 | 2493 | |
4187119d | 2494 | @cindex frameless execution |
d2e08421 | 2495 | Some compilers allow functions to be compiled to run without a frame |
5a131cc7 | 2496 | reserved for them on the stack. (For example, the _GCC__ option |
d2e08421 RP |
2497 | @samp{-fomit-frame-pointer} will generate functions without a frame.) |
2498 | This is occasionally done with heavily used library functions to save | |
5a131cc7 | 2499 | the frame setup time. _GDBN__ has limited facilities for dealing with these |
d2e08421 | 2500 | function invocations; if the innermost function invocation has no stack |
5a131cc7 | 2501 | frame, _GDBN__ will give it a virtual stack frame of 0 and correctly allow |
d2e08421 RP |
2502 | tracing of the function call chain. Results are undefined if a function |
2503 | invocation besides the innermost one is frameless. | |
4187119d | 2504 | |
e91b87a3 | 2505 | @node Backtrace, Selection, Frames, Stack |
2506 | @section Backtraces | |
2507 | ||
2508 | A backtrace is a summary of how the program got where it is. It shows one | |
2509 | line per frame, for many frames, starting with the currently executing | |
2510 | frame (frame zero), followed by its caller (frame one), and on up the | |
2511 | stack. | |
2512 | ||
2513 | @table @code | |
2514 | @item backtrace | |
2515 | @itemx bt | |
4187119d | 2516 | @kindex backtrace |
2517 | @kindex bt | |
e91b87a3 | 2518 | Print a backtrace of the entire stack: one line per frame for all |
2519 | frames in the stack. | |
2520 | ||
2521 | You can stop the backtrace at any time by typing the system interrupt | |
2522 | character, normally @kbd{Control-C}. | |
2523 | ||
2524 | @item backtrace @var{n} | |
2525 | @itemx bt @var{n} | |
4187119d | 2526 | Similar, but print only the innermost @var{n} frames. |
e91b87a3 | 2527 | |
2528 | @item backtrace @var{-n} | |
2529 | @itemx bt @var{-n} | |
4187119d | 2530 | Similar, but print only the outermost @var{n} frames. |
e91b87a3 | 2531 | @end table |
2532 | ||
4187119d | 2533 | @kindex where |
2534 | @kindex info stack | |
2535 | The names @samp{where} and @samp{info stack} are additional aliases | |
2536 | for @samp{backtrace}. | |
2537 | ||
d2e08421 RP |
2538 | Every line in the backtrace shows the frame number and the function |
2539 | name. The program counter value is also shown---unless you use | |
2540 | @samp{set addressprint off}. | |
4187119d | 2541 | |
2542 | If the function is in a source file whose symbol table data has been | |
2543 | fully read, the backtrace shows the source file name and line number, as | |
d2e08421 RP |
2544 | well as the arguments to the function. When the line number is shown, |
2545 | the program counter value is omitted if it is at the beginning of the | |
2546 | code for that line number. | |
4187119d | 2547 | |
4187119d | 2548 | Here is an example of a backtrace. It was made with the command |
2549 | @samp{bt 3}, so it shows the innermost three frames. | |
2550 | ||
2551 | @example | |
9c91ee3e RP |
2552 | #0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \ |
2553 | (/gp/rms/cc/rtlanal.c line 337) | |
4187119d | 2554 | #1 0x246b0 in expand_call (...) (...) |
2555 | #2 0x21cfc in expand_expr (...) (...) | |
2556 | (More stack frames follow...) | |
2557 | @end example | |
2558 | ||
2559 | @noindent | |
2560 | The functions @code{expand_call} and @code{expand_expr} are in a file | |
2561 | whose symbol details have not been fully read. Full detail is available | |
2562 | for the function @code{rtx_equal_p}, which is in the file | |
2563 | @file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown | |
2564 | with their typed values. | |
e91b87a3 | 2565 | |
2566 | @node Selection, Frame Info, Backtrace, Stack | |
2567 | @section Selecting a Frame | |
2568 | ||
2569 | Most commands for examining the stack and other data in the program work on | |
2570 | whichever stack frame is selected at the moment. Here are the commands for | |
2571 | selecting a stack frame; all of them finish by printing a brief description | |
2572 | of the stack frame just selected. | |
2573 | ||
2574 | @table @code | |
2575 | @item frame @var{n} | |
2576 | @kindex frame | |
2577 | Select frame number @var{n}. Recall that frame zero is the innermost | |
2578 | (currently executing) frame, frame one is the frame that called the | |
2579 | innermost one, and so on. The highest-numbered frame is @code{main}'s | |
2580 | frame. | |
2581 | ||
2582 | @item frame @var{addr} | |
2583 | Select the frame at address @var{addr}. This is useful mainly if the | |
2584 | chaining of stack frames has been damaged by a bug, making it | |
5a131cc7 | 2585 | impossible for _GDBN__ to assign numbers properly to all frames. In |
e91b87a3 | 2586 | addition, this can be useful when the program has multiple stacks and |
2587 | switches between them. | |
2588 | ||
2589 | @item up @var{n} | |
2590 | @kindex up | |
2591 | Select the frame @var{n} frames up from the frame previously selected. | |
2592 | For positive numbers @var{n}, this advances toward the outermost | |
2593 | frame, to higher frame numbers, to frames that have existed longer. | |
2594 | @var{n} defaults to one. | |
2595 | ||
2596 | @item down @var{n} | |
2597 | @kindex down | |
2598 | Select the frame @var{n} frames down from the frame previously | |
2599 | selected. For positive numbers @var{n}, this advances toward the | |
2600 | innermost frame, to lower frame numbers, to frames that were created | |
2601 | more recently. @var{n} defaults to one. | |
2602 | @end table | |
2603 | ||
2604 | All of these commands end by printing some information on the frame that | |
2605 | has been selected: the frame number, the function name, the arguments, the | |
2606 | source file and line number of execution in that frame, and the text of | |
2607 | that source line. For example: | |
2608 | ||
2609 | @example | |
23e2e5e1 | 2610 | #3 main (argc=3, argv=??, env=??) at main.c:67 |
e91b87a3 | 2611 | 67 read_input_file (argv[i]); |
2612 | @end example | |
2613 | ||
2614 | After such a printout, the @samp{list} command with no arguments will print | |
2615 | ten lines centered on the point of execution in the frame. @xref{List}. | |
2616 | ||
23e2e5e1 RP |
2617 | @table @code |
2618 | @item up-silently @var{n} | |
2619 | @itemx down-silently @var{n} | |
2620 | @kindex down-silently | |
2621 | @kindex up-silently | |
9d7c0513 | 2622 | These two commands are variants of @samp{up} and @samp{down}, |
23e2e5e1 RP |
2623 | respectively; they differ in that they do their work silently, without |
2624 | causing display of the new frame. They are intended primarily for use | |
5a131cc7 | 2625 | in _GDBN__ command scripts, where the output might be unnecessary and |
23e2e5e1 RP |
2626 | distracting. |
2627 | ||
369a6ade RP |
2628 | @end table |
2629 | ||
54e4a398 | 2630 | @node Frame Info, , Selection, Stack |
e91b87a3 | 2631 | @section Information on a Frame |
2632 | ||
2633 | There are several other commands to print information about the selected | |
2634 | stack frame. | |
2635 | ||
2636 | @table @code | |
2637 | @item frame | |
9da601bf RP |
2638 | When used without any argument, this command does not change which frame |
2639 | is selected, but still prints a brief description of the currently | |
2640 | selected stack frame. It can be abbreviated @samp{f}. With an | |
2641 | argument, this command is used to select a stack frame; with no | |
2642 | argument, it does not change which frame is selected, but still prints | |
2643 | the same kind of information. | |
e91b87a3 | 2644 | |
2645 | @item info frame | |
2646 | @kindex info frame | |
2647 | This command prints a verbose description of the selected stack frame, | |
2648 | including the address of the frame, the addresses of the next frame in | |
2649 | (called by this frame) and the next frame out (caller of this frame), | |
2650 | the address of the frame's arguments, the program counter saved in it | |
2651 | (the address of execution in the caller frame), and which registers | |
2652 | were saved in the frame. The verbose description is useful when | |
2653 | something has gone wrong that has made the stack format fail to fit | |
2654 | the usual conventions. | |
2655 | ||
2656 | @item info frame @var{addr} | |
2657 | Print a verbose description of the frame at address @var{addr}, | |
2658 | without selecting that frame. The selected frame remains unchanged by | |
2659 | this command. | |
2660 | ||
2661 | @item info args | |
2662 | @kindex info args | |
2663 | Print the arguments of the selected frame, each on a separate line. | |
2664 | ||
2665 | @item info locals | |
2666 | @kindex info locals | |
2667 | Print the local variables of the selected frame, each on a separate | |
2668 | line. These are all variables declared static or automatic within all | |
2669 | program blocks that execution in this frame is currently inside of. | |
e91b87a3 | 2670 | |
6ad6aa52 RP |
2671 | @item info catch |
2672 | @kindex info catch | |
9da601bf | 2673 | @cindex catch exceptions |
d2e08421 | 2674 | @cindex exception handlers |
6ad6aa52 | 2675 | Print a list of all the exception handlers that are active in the |
9da601bf RP |
2676 | current stack frame given the current value of @code{pc}. To see other |
2677 | exception handlers, visit the associated frame (using the @samp{up}, | |
d2e08421 RP |
2678 | @samp{down}, or @samp{frame} commands); then type @samp{info catch}. |
2679 | @xref{Exception Handling}. | |
9da601bf | 2680 | @end table |
6ad6aa52 | 2681 | |
e91b87a3 | 2682 | @node Source, Data, Stack, Top |
2683 | @chapter Examining Source Files | |
2684 | ||
5a131cc7 RP |
2685 | _GDBN__ knows which source files your program was compiled from, and |
2686 | can print parts of their text. When your program stops, _GDBN__ | |
e91b87a3 | 2687 | spontaneously prints the line it stopped in. Likewise, when you |
5a131cc7 | 2688 | select a stack frame (@pxref{Selection}), _GDBN__ prints the line |
e91b87a3 | 2689 | which execution in that frame has stopped in. You can also |
2690 | print parts of source files by explicit command. | |
2691 | ||
2692 | @menu | |
54e4a398 RP |
2693 | * List:: Using the @samp{list} command to print source files. |
2694 | * Search:: Commands for searching source files. | |
2695 | * Source Path:: Specifying the directories to search for source files. | |
e91b87a3 | 2696 | @end menu |
2697 | ||
2698 | @node List, Search, Source, Source | |
2699 | @section Printing Source Lines | |
2700 | ||
2701 | @kindex list | |
9da601bf | 2702 | @kindex l |
e91b87a3 | 2703 | To print lines from a source file, use the @samp{list} command |
2704 | (abbreviated @samp{l}). There are several ways to specify what part | |
2705 | of the file you want to print. | |
2706 | ||
2707 | Here are the forms of the @samp{list} command most commonly used: | |
2708 | ||
2709 | @table @code | |
2710 | @item list @var{linenum} | |
2711 | Print ten lines centered around line number @var{linenum} in the | |
2712 | current source file. | |
2713 | ||
2714 | @item list @var{function} | |
2715 | Print ten lines centered around the beginning of function | |
2716 | @var{function}. | |
2717 | ||
2718 | @item list | |
2719 | Print ten more lines. If the last lines printed were printed with a | |
2720 | @samp{list} command, this prints ten lines following the last lines | |
2721 | printed; however, if the last line printed was a solitary line printed | |
2722 | as part of displaying a stack frame (@pxref{Stack}), this prints ten | |
2723 | lines centered around that line. | |
2724 | ||
4187119d | 2725 | @item list - |
e91b87a3 | 2726 | Print ten lines just before the lines last printed. |
2727 | @end table | |
2728 | ||
2729 | Repeating a @samp{list} command with @key{RET} discards the argument, | |
2730 | so it is equivalent to typing just @samp{list}. This is more useful | |
2731 | than listing the same lines again. An exception is made for an | |
2732 | argument of @samp{-}; that argument is preserved in repetition so that | |
2733 | each repetition moves up in the file. | |
2734 | ||
4187119d | 2735 | @cindex linespec |
e91b87a3 | 2736 | In general, the @samp{list} command expects you to supply zero, one or two |
2737 | @dfn{linespecs}. Linespecs specify source lines; there are several ways | |
2738 | of writing them but the effect is always to specify some source line. | |
2739 | Here is a complete description of the possible arguments for @samp{list}: | |
2740 | ||
2741 | @table @code | |
2742 | @item list @var{linespec} | |
2743 | Print ten lines centered around the line specified by @var{linespec}. | |
2744 | ||
2745 | @item list @var{first},@var{last} | |
2746 | Print lines from @var{first} to @var{last}. Both arguments are | |
2747 | linespecs. | |
2748 | ||
2749 | @item list ,@var{last} | |
2750 | Print ten lines ending with @var{last}. | |
2751 | ||
2752 | @item list @var{first}, | |
2753 | Print ten lines starting with @var{first}. | |
2754 | ||
2755 | @item list + | |
2756 | Print ten lines just after the lines last printed. | |
2757 | ||
4187119d | 2758 | @item list - |
e91b87a3 | 2759 | Print ten lines just before the lines last printed. |
2760 | ||
2761 | @item list | |
2762 | As described in the preceding table. | |
2763 | @end table | |
2764 | ||
2765 | Here are the ways of specifying a single source line---all the | |
2766 | kinds of linespec. | |
2767 | ||
4187119d | 2768 | @table @code |
e91b87a3 | 2769 | @item @var{linenum} |
2770 | Specifies line @var{linenum} of the current source file. | |
2771 | When a @samp{list} command has two linespecs, this refers to | |
2772 | the same source file as the first linespec. | |
2773 | ||
2774 | @item +@var{offset} | |
2775 | Specifies the line @var{offset} lines after the last line printed. | |
2776 | When used as the second linespec in a @samp{list} command that has | |
2777 | two, this specifies the line @var{offset} lines down from the | |
2778 | first linespec. | |
2779 | ||
4187119d | 2780 | @item -@var{offset} |
e91b87a3 | 2781 | Specifies the line @var{offset} lines before the last line printed. |
2782 | ||
2783 | @item @var{filename}:@var{linenum} | |
2784 | Specifies line @var{linenum} in the source file @var{filename}. | |
2785 | ||
2786 | @item @var{function} | |
2787 | Specifies the line of the open-brace that begins the body of the | |
2788 | function @var{function}. | |
2789 | ||
2790 | @item @var{filename}:@var{function} | |
2791 | Specifies the line of the open-brace that begins the body of the | |
2792 | function @var{function} in the file @var{filename}. The file name is | |
2793 | needed with a function name only for disambiguation of identically | |
2794 | named functions in different source files. | |
2795 | ||
2796 | @item *@var{address} | |
2797 | Specifies the line containing the program address @var{address}. | |
2798 | @var{address} may be any expression. | |
2799 | @end table | |
2800 | ||
2801 | One other command is used to map source lines to program addresses. | |
2802 | ||
2803 | @table @code | |
2804 | @item info line @var{linenum} | |
2805 | @kindex info line | |
2806 | Print the starting and ending addresses of the compiled code for | |
2807 | source line @var{linenum}. | |
2808 | ||
2809 | @kindex $_ | |
2810 | The default examine address for the @samp{x} command is changed to the | |
2811 | starting address of the line, so that @samp{x/i} is sufficient to | |
2812 | begin examining the machine code (@pxref{Memory}). Also, this address | |
4187119d | 2813 | is saved as the value of the convenience variable @code{$_} |
e91b87a3 | 2814 | (@pxref{Convenience Vars}). |
2815 | @end table | |
2816 | ||
2817 | @node Search, Source Path, List, Source | |
2818 | @section Searching Source Files | |
2819 | @cindex searching | |
9da601bf | 2820 | @kindex search |
e91b87a3 | 2821 | @kindex forward-search |
2822 | @kindex reverse-search | |
2823 | ||
2824 | There are two commands for searching through the current source file for a | |
2825 | regular expression. | |
2826 | ||
2827 | The command @samp{forward-search @var{regexp}} checks each line, starting | |
2828 | with the one following the last line listed, for a match for @var{regexp}. | |
2829 | It lists the line that is found. You can abbreviate the command name | |
9da601bf | 2830 | as @samp{fo}. The synonym @samp{search @var{regexp}} is also supported. |
e91b87a3 | 2831 | |
2832 | The command @samp{reverse-search @var{regexp}} checks each line, starting | |
2833 | with the one before the last line listed and going backward, for a match | |
2834 | for @var{regexp}. It lists the line that is found. You can abbreviate | |
2835 | this command with as little as @samp{rev}. | |
2836 | ||
54e4a398 | 2837 | @node Source Path, , Search, Source |
e91b87a3 | 2838 | @section Specifying Source Directories |
2839 | ||
2840 | @cindex source path | |
2841 | @cindex directories for source files | |
6ad6aa52 RP |
2842 | Executable programs sometimes do not record the directories of the source |
2843 | files from which they were compiled, just the names. Even when they do, | |
2844 | the directories could be moved between the compilation and your debugging | |
5a131cc7 RP |
2845 | session. _GDBN__ remembers a list of directories to search for source files; |
2846 | this is called the @dfn{source path}. Each time _GDBN__ wants a source file, | |
6ad6aa52 | 2847 | it tries all the directories in the list, in the order they are present |
9da601bf RP |
2848 | in the list, until it finds a file with the desired name. Note that |
2849 | the executable search path is @emph{not} used for this purpose. Neither is | |
6ad6aa52 | 2850 | the current working directory, unless it happens to be in the source |
9da601bf | 2851 | path. |
0bed9994 JG |
2852 | |
2853 | If it can't find a source file in the source path, and the object program | |
5a131cc7 | 2854 | records what directory it was compiled in, _GDBN__ tries that directory too. |
0bed9994 | 2855 | If the source path is empty, and there is no record of the compilation |
5a131cc7 | 2856 | directory, _GDBN__ will, as a last resort, look in the current directory. |
0bed9994 | 2857 | |
5a131cc7 | 2858 | Whenever you reset or rearrange the source path, _GDBN__ will clear out |
0bed9994 JG |
2859 | any information it has cached about where source files are found, where |
2860 | each line is in the file, etc. | |
e91b87a3 | 2861 | |
2862 | @kindex directory | |
5a131cc7 | 2863 | When you start _GDBN__, its source path is empty. |
0bed9994 | 2864 | To add other directories, use the @samp{directory} command. |
e91b87a3 | 2865 | |
2866 | @table @code | |
4187119d | 2867 | @item directory @var{dirnames...} |
0bed9994 | 2868 | Add directory @var{dirname} to the front of the source path. Several |
4187119d | 2869 | directory names may be given to this command, separated by whitespace or |
0bed9994 JG |
2870 | @samp{:}. If a name is already in the source path, it is moved to the |
2871 | front of the path, so it will be searched sooner. | |
e91b87a3 | 2872 | |
2873 | @item directory | |
0bed9994 | 2874 | Reset the source path to empty again. This requires confirmation. |
e91b87a3 | 2875 | |
2876 | @item info directories | |
2877 | @kindex info directories | |
2878 | Print the source path: show which directories it contains. | |
2879 | @end table | |
2880 | ||
9c91ee3e | 2881 | Because the @samp{directory} command, when used with arguments, adds to |
5a131cc7 | 2882 | the front of the source path, it can affect files that _GDBN__ has already |
9c91ee3e RP |
2883 | found. If the source path contains directories that you do not want, |
2884 | and these directories contain misleading files with names matching your | |
2885 | source files, the way to correct the situation is as follows: | |
e91b87a3 | 2886 | |
2887 | @enumerate | |
2888 | @item | |
0bed9994 | 2889 | Use @samp{directory} with no argument to reset the source path to empty. |
e91b87a3 | 2890 | |
2891 | @item | |
2892 | Use @samp{directory} with suitable arguments to add any other | |
0bed9994 JG |
2893 | directories you want in the source path. You can add all the directories |
2894 | in one command. | |
e91b87a3 | 2895 | @end enumerate |
2896 | ||
2897 | @node Data, Symbols, Source, Top | |
2898 | @chapter Examining Data | |
2899 | ||
2900 | @cindex printing data | |
2901 | @cindex examining data | |
2902 | @kindex print | |
9da601bf | 2903 | @kindex inspect |
4187119d | 2904 | The usual way to examine data in your program is with the @samp{print} |
9da601bf RP |
2905 | command (abbreviated @samp{p}), or its synonym @samp{inspect}. It |
2906 | evaluates and prints the value of any valid expression of the language | |
2907 | the program is written in (for now, C or C++). You type | |
e91b87a3 | 2908 | |
2909 | @example | |
2910 | print @var{exp} | |
2911 | @end example | |
2912 | ||
2913 | @noindent | |
9c91ee3e RP |
2914 | where @var{exp} is any valid expression (in the source language), and |
2915 | the value of @var{exp} is printed in a format appropriate to its data | |
2916 | type. | |
e91b87a3 | 2917 | |
2918 | A more low-level way of examining data is with the @samp{x} command. | |
2919 | It examines data in memory at a specified address and prints it in a | |
2920 | specified format. | |
2921 | ||
e91b87a3 | 2922 | @menu |
54e4a398 RP |
2923 | * Expressions:: Expressions that can be computed and printed. |
2924 | * Variables:: Using your program's variables in expressions. | |
2925 | * Arrays:: Examining part of memory as an array. | |
2926 | * Format options:: Controlling how structures and arrays are printed. | |
2927 | * Output formats:: Specifying formats for printing values. | |
2928 | * Auto Display:: Printing certain expressions whenever program stops. | |
2929 | * Value History:: Referring to values previously printed. | |
2930 | * Convenience Vars:: Giving names to values for future reference. | |
2931 | * Registers:: Referring to and storing in machine registers. | |
e91b87a3 | 2932 | @end menu |
2933 | ||
2934 | @node Expressions, Variables, Data, Data | |
2935 | @section Expressions | |
2936 | ||
2937 | @cindex expressions | |
5a131cc7 | 2938 | Many different _GDBN__ commands accept an expression and compute its value. |
e91b87a3 | 2939 | Any kind of constant, variable or operator defined by the programming |
5a131cc7 | 2940 | language you are using is legal in an expression in _GDBN__. This includes |
d2e08421 RP |
2941 | conditional expressions, function calls, casts and string constants. It |
2942 | unfortunately does not include symbols defined by preprocessor | |
2943 | @code{#define} commands, or C++ expressions involving @samp{::}, the | |
2944 | name resolution operator. | |
e91b87a3 | 2945 | |
2946 | Casts are supported in all languages, not just in C, because it is so | |
2947 | useful to cast a number into a pointer so as to examine a structure | |
2948 | at that address in memory. | |
2949 | ||
5a131cc7 | 2950 | _GDBN__ supports three kinds of operator in addition to those of programming |
e91b87a3 | 2951 | languages: |
2952 | ||
2953 | @table @code | |
2954 | @item @@ | |
2955 | @samp{@@} is a binary operator for treating parts of memory as arrays. | |
2956 | @xref{Arrays}, for more information. | |
2957 | ||
2958 | @item :: | |
2959 | @samp{::} allows you to specify a variable in terms of the file or | |
2960 | function it is defined in. @xref{Variables}. | |
2961 | ||
2962 | @item @{@var{type}@} @var{addr} | |
2963 | Refers to an object of type @var{type} stored at address @var{addr} in | |
2964 | memory. @var{addr} may be any expression whose value is an integer or | |
2965 | pointer (but parentheses are required around nonunary operators, just as in | |
2966 | a cast). This construct is allowed regardless of what kind of data is | |
2967 | officially supposed to reside at @var{addr}.@refill | |
2968 | @end table | |
2969 | ||
2970 | @node Variables, Arrays, Expressions, Data | |
2971 | @section Program Variables | |
2972 | ||
2973 | The most common kind of expression to use is the name of a variable | |
2974 | in your program. | |
2975 | ||
2976 | Variables in expressions are understood in the selected stack frame | |
2977 | (@pxref{Selection}); they must either be global (or static) or be visible | |
2978 | according to the scope rules of the programming language from the point of | |
2979 | execution in that frame. This means that in the function | |
2980 | ||
2981 | @example | |
2982 | foo (a) | |
2983 | int a; | |
2984 | @{ | |
2985 | bar (a); | |
2986 | @{ | |
2987 | int b = test (); | |
2988 | bar (b); | |
2989 | @} | |
2990 | @} | |
2991 | @end example | |
2992 | ||
2993 | @noindent | |
2994 | the variable @code{a} is usable whenever the program is executing | |
2995 | within the function @code{foo}, but the variable @code{b} is visible | |
2996 | only while the program is executing inside the block in which @code{b} | |
2997 | is declared. | |
2998 | ||
2999 | As a special exception, you can refer to a variable or function whose | |
3000 | scope is a single source file even if the current execution point is not | |
3001 | in this file. But it is possible to have more than one such variable | |
3002 | or function with the same name (if they are in different source files). | |
3003 | In such a case, it is not defined which one you will get. If you wish, | |
3004 | you can specify any one of them using the colon-colon construct: | |
3005 | ||
d2e08421 RP |
3006 | @cindex colon-colon |
3007 | @cindex scope | |
3008 | @kindex :: | |
e91b87a3 | 3009 | @example |
3010 | @var{block}::@var{variable} | |
3011 | @end example | |
3012 | ||
3013 | @noindent | |
3014 | Here @var{block} is the name of the source file whose variable you want. | |
3015 | ||
d2e08421 RP |
3016 | @cindex name resolution (C++) |
3017 | Unfortunately, this use of @samp{::} conflicts with the very similar use | |
5a131cc7 RP |
3018 | of the same notation in C++; accordingly, _GDBN__ does not support use of |
3019 | the C++ name resolution operator in _GDBN__ expressions. | |
d2e08421 | 3020 | |
4187119d | 3021 | @node Arrays, Format options, Variables, Data |
e91b87a3 | 3022 | @section Artificial Arrays |
3023 | ||
3024 | @cindex artificial array | |
26376b06 | 3025 | @kindex @@ |
e91b87a3 | 3026 | It is often useful to print out several successive objects of the |
3027 | same type in memory; a section of an array, or an array of | |
3028 | dynamically determined size for which only a pointer exists in the | |
3029 | program. | |
3030 | ||
3031 | This can be done by constructing an @dfn{artificial array} with the | |
3032 | binary operator @samp{@@}. The left operand of @samp{@@} should be | |
3033 | the first element of the desired array, as an individual object. | |
3034 | The right operand should be the length of the array. The result is | |
3035 | an array value whose elements are all of the type of the left argument. | |
3036 | The first element is actually the left argument; the second element | |
3037 | comes from bytes of memory immediately following those that hold the | |
3038 | first element, and so on. Here is an example. If a program says | |
3039 | ||
3040 | @example | |
3041 | int *array = (int *) malloc (len * sizeof (int)); | |
3042 | @end example | |
3043 | ||
3044 | @noindent | |
3045 | you can print the contents of @code{array} with | |
3046 | ||
3047 | @example | |
3048 | p *array@@len | |
3049 | @end example | |
3050 | ||
3051 | The left operand of @samp{@@} must reside in memory. Array values made | |
3052 | with @samp{@@} in this way behave just like other arrays in terms of | |
3053 | subscripting, and are coerced to pointers when used in expressions. | |
3054 | (It would probably appear in an expression via the value history, | |
3055 | after you had printed it out.) | |
3056 | ||
4187119d | 3057 | @node Format options, Output formats, Arrays, Data |
3058 | @section Format options | |
3059 | ||
3060 | @cindex format options | |
5a131cc7 | 3061 | _GDBN__ provides a few ways to control how arrays, structures, and symbols are |
4187119d | 3062 | printed. |
3063 | ||
3064 | @table @code | |
4187119d | 3065 | @item set array-max @var{number-of-elements} |
3066 | @kindex set array-max | |
5a131cc7 | 3067 | If _GDBN__ is printing a large array, it will stop printing after it has |
4187119d | 3068 | printed the number of elements set by the @samp{set array-max} command. |
3069 | This limit also applies to the display of strings. | |
3070 | ||
9da601bf RP |
3071 | @item show array-max |
3072 | @kindex show array-max | |
5a131cc7 | 3073 | Display the number of elements of a large array that _GDBN__ will print |
9da601bf RP |
3074 | before losing patience. |
3075 | ||
96a816c5 JG |
3076 | @item set arrayprint |
3077 | @itemx set arrayprint on | |
3078 | @kindex set arrayprint | |
5a131cc7 | 3079 | _GDBN__ will pretty print arrays. This format is more convenient to read, |
96a816c5 JG |
3080 | but uses more space. The default is off. |
3081 | ||
3082 | @item set arrayprint off. | |
3083 | Return to compressed format for arrays. | |
3084 | ||
9da601bf RP |
3085 | @item show arrayprint |
3086 | @kindex show arrayprint | |
3087 | Show whether compressed or pretty format is selected for displaying | |
3088 | arrays. | |
3089 | ||
a58d77ad JG |
3090 | @item set demangle |
3091 | @itemx set demangle on | |
3092 | @kindex set demangle | |
3093 | Print C++ names in their source form rather than in the mangled form | |
3094 | in which they are passed to the assembler and linker for type-safe linkage. | |
3095 | The default is on. | |
3096 | ||
3097 | @item show demangle | |
3098 | @kindex show demangle | |
3099 | Show whether C++ names will be printed in mangled or demangled form. | |
3100 | ||
3101 | @item set asm-demangle | |
3102 | @itemx set asm-demangle on | |
3103 | @kindex set asm-demangle | |
3104 | Print C++ names in their source form rather than their mangled form, even | |
3105 | in assembler code printouts such as instruction disassemblies. | |
3106 | The default is off. | |
3107 | ||
c81e78d1 RP |
3108 | @item show asm-demangle |
3109 | @kindex show asm-demangle | |
a58d77ad JG |
3110 | Show whether C++ names in assembly listings will be printed in mangled |
3111 | or demangled form. | |
3112 | ||
96a816c5 JG |
3113 | @item set vtblprint |
3114 | @itemx set vtblprint on | |
9c91ee3e | 3115 | @kindex set vtblprint |
96a816c5 JG |
3116 | Pretty print C++ virtual function tables. The default is off. |
3117 | ||
3118 | @item set vtblprint off | |
d2e08421 | 3119 | Do not pretty print C++ virtual function tables. |
96a816c5 | 3120 | |
9da601bf RP |
3121 | @item show vtblprint |
3122 | @kindex show vtblprint | |
3123 | Show whether C++ virtual function tables are pretty printed, or not. | |
3124 | ||
96a816c5 | 3125 | @item set addressprint |
880d228b | 3126 | @item set addressprint on |
96a816c5 | 3127 | @kindex set addressprint |
5a131cc7 | 3128 | _GDBN__ will print memory addresses in stack traces, structure values, pointer |
a58d77ad | 3129 | values, breakpoints, etc. The default is on. |
96a816c5 JG |
3130 | |
3131 | @item set addressprint off | |
3132 | Do not print addresses. | |
3133 | ||
9da601bf RP |
3134 | @item show addressprint |
3135 | @kindex show addressprint | |
3136 | Show whether or not addresses are to be printed. | |
96a816c5 | 3137 | |
4187119d | 3138 | @item set prettyprint on |
3139 | @kindex set prettyprint | |
5a131cc7 | 3140 | Cause _GDBN__ to print structures in an indented format with one member per |
4187119d | 3141 | line, like this: |
3142 | ||
3143 | @example | |
3144 | $1 = @{ | |
3145 | next = 0x0, | |
3146 | flags = @{ | |
3147 | sweet = 1, | |
3148 | sour = 1 | |
3149 | @}, | |
3150 | meat = 0x54 "Pork" | |
3151 | @} | |
3152 | @end example | |
3153 | ||
3154 | @item set prettyprint off | |
5a131cc7 | 3155 | Cause _GDBN__ to print structures in a compact format, like this: |
4187119d | 3156 | |
54e4a398 | 3157 | @smallexample |
4afc6002 RP |
3158 | $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \ |
3159 | = 0x54 "Pork"@} | |
54e4a398 | 3160 | @end smallexample |
4187119d | 3161 | |
4afc6002 | 3162 | @noindent |
4187119d | 3163 | This is the default format. |
3164 | ||
9da601bf RP |
3165 | @item show prettyprint |
3166 | @kindex show prettyprint | |
5a131cc7 | 3167 | Show which format _GDBN__ will use to print structures. |
9da601bf | 3168 | |
4187119d | 3169 | @item set unionprint on |
3170 | @kindex set unionprint | |
5a131cc7 | 3171 | Tell _GDBN__ to print unions which are contained in structures. This is the |
4187119d | 3172 | default setting. |
9da601bf | 3173 | |
4187119d | 3174 | @item set unionprint off |
5a131cc7 | 3175 | Tell _GDBN__ not to print unions which are contained in structures. |
4187119d | 3176 | |
9da601bf RP |
3177 | @item show unionprint |
3178 | @kindex show unionprint | |
5a131cc7 | 3179 | Ask _GDBN__ whether or not it will print unions which are contained in |
9da601bf RP |
3180 | structures. |
3181 | ||
4187119d | 3182 | For example, given the declarations |
3183 | ||
54e4a398 | 3184 | @smallexample |
4187119d | 3185 | typedef enum @{Tree, Bug@} Species; |
3186 | typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; | |
9c91ee3e | 3187 | typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms; |
4187119d | 3188 | |
3189 | struct thing @{ | |
3190 | Species it; | |
3191 | union @{ | |
3192 | Tree_forms tree; | |
3193 | Bug_forms bug; | |
3194 | @} form; | |
3195 | @}; | |
3196 | ||
3197 | struct thing foo = @{Tree, @{Acorn@}@}; | |
54e4a398 | 3198 | @end smallexample |
4187119d | 3199 | |
3200 | @noindent | |
3201 | with @samp{set unionprint on} in effect @samp{p foo} would print | |
3202 | ||
54e4a398 | 3203 | @smallexample |
4187119d | 3204 | $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} |
54e4a398 | 3205 | @end smallexample |
4187119d | 3206 | |
3207 | @noindent | |
3208 | and with @samp{set unionprint off} in effect it would print | |
3209 | ||
3210 | @example | |
3211 | $1 = @{it = Tree, form = @{...@}@} | |
3212 | @end example | |
3213 | @end table | |
3214 | ||
54e4a398 | 3215 | @node Output formats, Auto Display, Format options, Data |
4187119d | 3216 | @section Output formats |
e91b87a3 | 3217 | |
3218 | @cindex formatted output | |
3219 | @cindex output formats | |
5a131cc7 | 3220 | _GDBN__ normally prints all values according to their data types. Sometimes |
e91b87a3 | 3221 | this is not what you want. For example, you might want to print a number |
3222 | in hex, or a pointer in decimal. Or you might want to view data in memory | |
3223 | at a certain address as a character string or an instruction. These things | |
3224 | can be done with @dfn{output formats}. | |
3225 | ||
3226 | The simplest use of output formats is to say how to print a value | |
3227 | already computed. This is done by starting the arguments of the | |
3228 | @samp{print} command with a slash and a format letter. The format | |
3229 | letters supported are: | |
3230 | ||
3231 | @table @samp | |
3232 | @item x | |
3233 | Regard the bits of the value as an integer, and print the integer in | |
3234 | hexadecimal. | |
3235 | ||
3236 | @item d | |
3237 | Print as integer in signed decimal. | |
3238 | ||
3239 | @item u | |
3240 | Print as integer in unsigned decimal. | |
3241 | ||
3242 | @item o | |
3243 | Print as integer in octal. | |
3244 | ||
3245 | @item a | |
9c91ee3e | 3246 | Print as an address, both absolute in hex and as an offset from the |
9da601bf RP |
3247 | nearest preceding symbol. This format can be used to discover where (in |
3248 | what function) an unknown address is located: | |
3249 | @example | |
5a131cc7 | 3250 | (_GDBP__) p/a 0x54320 |
9da601bf RP |
3251 | $3 = 0x54320 <_initialize_vx+396> |
3252 | @end example | |
3253 | ||
e91b87a3 | 3254 | |
3255 | @item c | |
3256 | Regard as an integer and print it as a character constant. | |
3257 | ||
3258 | @item f | |
3259 | Regard the bits of the value as a floating point number and print | |
3260 | using typical floating point syntax. | |
3261 | @end table | |
3262 | ||
3263 | For example, to print the program counter in hex (@pxref{Registers}), type | |
3264 | ||
3265 | @example | |
3266 | p/x $pc | |
3267 | @end example | |
3268 | ||
3269 | @noindent | |
3270 | Note that no space is required before the slash; this is because command | |
5a131cc7 | 3271 | names in _GDBN__ cannot contain a slash. |
e91b87a3 | 3272 | |
3273 | To reprint the last value in the value history with a different format, | |
3274 | you can use the @samp{print} command with just a format and no | |
3275 | expression. For example, @samp{p/x} reprints the last value in hex. | |
3276 | ||
54e4a398 RP |
3277 | @menu |
3278 | * Memory:: Examining Memory | |
3279 | @end menu | |
3280 | ||
3281 | @node Memory, , Output formats, Output formats | |
e91b87a3 | 3282 | @subsection Examining Memory |
3283 | ||
3284 | @cindex examining memory | |
9da601bf RP |
3285 | @table @code |
3286 | @kindex disassemble | |
3287 | @item disassemble | |
3288 | This specialized command is provided to dump a range of memory as | |
3289 | machine instructions. The default memory range is the function | |
3290 | surrounding the program counter of the selected frame. A single | |
3291 | argument to this command is a program counter value; the function | |
3292 | surrounding this value will be dumped. Two arguments (separated by one | |
880d228b | 3293 | or more spaces) specify a range of addresses (first inclusive, second |
9da601bf RP |
3294 | exclusive) to be dumped. |
3295 | ||
e91b87a3 | 3296 | @kindex x |
9da601bf | 3297 | @item x |
4187119d | 3298 | The command @samp{x} (for `examine') can be used to examine memory |
3299 | without reference to the program's data types. The format in which you | |
3300 | wish to examine memory is instead explicitly specified. The allowable | |
3301 | formats are a superset of the formats described in the previous section. | |
9da601bf | 3302 | @end table |
e91b87a3 | 3303 | |
3304 | @samp{x} is followed by a slash and an output format specification, | |
3305 | followed by an expression for an address. The expression need not have | |
3306 | a pointer value (though it may); it is used as an integer, as the | |
4187119d | 3307 | address of a byte of memory. @xref{Expressions} for more information on |
3308 | expressions. For example, @samp{x/4xw $sp} prints the four words of | |
3309 | memory above the stack pointer in hexadecimal. | |
e91b87a3 | 3310 | |
3311 | The output format in this case specifies both how big a unit of memory | |
3312 | to examine and how to print the contents of that unit. It is done | |
3313 | with one or two of the following letters: | |
3314 | ||
3315 | These letters specify just the size of unit to examine: | |
3316 | ||
3317 | @table @samp | |
3318 | @item b | |
3319 | Examine individual bytes. | |
3320 | ||
3321 | @item h | |
3322 | Examine halfwords (two bytes each). | |
3323 | ||
3324 | @item w | |
3325 | Examine words (four bytes each). | |
3326 | ||
3327 | @cindex word | |
3328 | Many assemblers and cpu designers still use `word' for a 16-bit quantity, | |
3329 | as a holdover from specific predecessor machines of the 1970's that really | |
3330 | did use two-byte words. But more generally the term `word' has always | |
3331 | referred to the size of quantity that a machine normally operates on and | |
5a131cc7 | 3332 | stores in its registers. This is 32 bits for all the machines that _GDBN__ |
e91b87a3 | 3333 | runs on. |
3334 | ||
3335 | @item g | |
3336 | Examine giant words (8 bytes). | |
3337 | @end table | |
3338 | ||
3339 | These letters specify just the way to print the contents: | |
3340 | ||
3341 | @table @samp | |
3342 | @item x | |
3343 | Print as integers in unsigned hexadecimal. | |
3344 | ||
3345 | @item d | |
3346 | Print as integers in signed decimal. | |
3347 | ||
3348 | @item u | |
3349 | Print as integers in unsigned decimal. | |
3350 | ||
3351 | @item o | |
3352 | Print as integers in unsigned octal. | |
3353 | ||
3354 | @item a | |
3355 | Print as an address, both absolute in hex and then relative | |
3356 | to a symbol defined as an address below it. | |
3357 | ||
3358 | @item c | |
3359 | Print as character constants. | |
3360 | ||
3361 | @item f | |
3362 | Print as floating point. This works only with sizes @samp{w} and | |
3363 | @samp{g}. | |
3364 | ||
3365 | @item s | |
3366 | Print a null-terminated string of characters. The specified unit size | |
3367 | is ignored; instead, the unit is however many bytes it takes to reach | |
3368 | a null character (including the null character). | |
3369 | ||
3370 | @item i | |
3371 | Print a machine instruction in assembler syntax (or nearly). The | |
3372 | specified unit size is ignored; the number of bytes in an instruction | |
3373 | varies depending on the type of machine, the opcode and the addressing | |
9da601bf RP |
3374 | modes used. The command @samp{disassemble} gives an alternative way of |
3375 | inspecting machine instructions. | |
e91b87a3 | 3376 | @end table |
3377 | ||
3378 | If either the manner of printing or the size of unit fails to be specified, | |
3379 | the default is to use the same one that was used last. If you don't want | |
3380 | to use any letters after the slash, you can omit the slash as well. | |
3381 | ||
d2e08421 RP |
3382 | You can also omit the address to examine. Then the address used is just |
3383 | after the last unit examined. This is why string and instruction | |
3384 | formats actually compute a unit-size based on the data: so that the next | |
3385 | string or instruction examined will start in the right place. | |
3386 | ||
3387 | When the @samp{print} command shows a value that resides in memory, | |
3388 | @samp{print} also sets the default address for the @samp{x} command. | |
3389 | @samp{info line} also sets the default for @samp{x}, to the address of | |
3390 | the start of the machine code for the specified line and @samp{info | |
3391 | breakpoints} sets it to the address of the last breakpoint listed. | |
3392 | ||
3393 | When you use @key{RET} to repeat an @samp{x} command, the address | |
3394 | specified previously (if any) is ignored, so that the repeated command | |
3395 | examines the successive locations in memory rather than the same ones. | |
e91b87a3 | 3396 | |
3397 | You can examine several consecutive units of memory with one command by | |
3398 | writing a repeat-count after the slash (before the format letters, if any). | |
3399 | The repeat count must be a decimal integer. It has the same effect as | |
3400 | repeating the @samp{x} command that many times except that the output may | |
4187119d | 3401 | be more compact with several units per line. For example, |
e91b87a3 | 3402 | |
3403 | @example | |
3404 | x/10i $pc | |
3405 | @end example | |
3406 | ||
3407 | @noindent | |
4187119d | 3408 | prints ten instructions starting with the one to be executed next in the |
9da601bf | 3409 | selected frame. After doing this, you could print another seven following |
e91b87a3 | 3410 | instructions with |
3411 | ||
3412 | @example | |
9da601bf | 3413 | x/7 |
e91b87a3 | 3414 | @end example |
3415 | ||
3416 | @noindent | |
3417 | in which the format and address are allowed to default. | |
3418 | ||
3419 | @kindex $_ | |
3420 | @kindex $__ | |
3421 | The addresses and contents printed by the @samp{x} command are not put in | |
3422 | the value history because there is often too much of them and they would | |
5a131cc7 | 3423 | get in the way. Instead, _GDBN__ makes these values available for subsequent |
4187119d | 3424 | use in expressions as values of the convenience variables @code{$_} and |
3425 | @code{$__}. | |
e91b87a3 | 3426 | |
3427 | After an @samp{x} command, the last address examined is available for use | |
4187119d | 3428 | in expressions in the convenience variable @code{$_}. The contents of that |
3429 | address, as examined, are available in the convenience variable @code{$__}. | |
e91b87a3 | 3430 | |
3431 | If the @samp{x} command has a repeat count, the address and contents saved | |
3432 | are from the last memory unit printed; this is not the same as the last | |
3433 | address printed if several units were printed on the last line of output. | |
3434 | ||
54e4a398 | 3435 | @node Auto Display, Value History, Output formats, Data |
e91b87a3 | 3436 | @section Automatic Display |
4187119d | 3437 | @cindex automatic display |
3438 | @cindex display of expressions | |
e91b87a3 | 3439 | |
3440 | If you find that you want to print the value of an expression frequently | |
3441 | (to see how it changes), you might want to add it to the @dfn{automatic | |
5a131cc7 | 3442 | display list} so that _GDBN__ will print its value each time the program stops. |
e91b87a3 | 3443 | Each expression added to the list is given a number to identify it; |
3444 | to remove an expression from the list, you specify that number. | |
3445 | The automatic display looks like this: | |
3446 | ||
3447 | @example | |
3448 | 2: foo = 38 | |
3449 | 3: bar[5] = (struct hack *) 0x3804 | |
3450 | @end example | |
3451 | ||
3452 | @noindent | |
3453 | showing item numbers, expressions and their current values. | |
3454 | ||
4187119d | 3455 | If the expression refers to local variables, then it does not make sense |
3456 | outside the lexical context for which it was set up. Such an expression | |
9c91ee3e RP |
3457 | is disabled when execution enters a context where one of its variables |
3458 | is not defined. For example, if you give the command | |
3459 | @samp{display name} while inside a function with an argument | |
3460 | @code{name}, then this argument will be displayed while the program | |
3461 | continues to stop inside that function. When it stops elsewhere---where | |
3462 | there is no variable @samp{name}---display is disabled. The next time | |
3463 | your program stops where @samp{name} is meaningful, you can enable the | |
3464 | display expression once again. | |
4187119d | 3465 | |
e91b87a3 | 3466 | @table @code |
3467 | @item display @var{exp} | |
3468 | @kindex display | |
3469 | Add the expression @var{exp} to the list of expressions to display | |
3470 | each time the program stops. @xref{Expressions}. | |
3471 | ||
3472 | @item display/@var{fmt} @var{exp} | |
3473 | For @var{fmt} specifying only a display format and not a size or | |
3474 | count, add the expression @var{exp} to the auto-display list but | |
3475 | arranges to display it each time in the specified format @var{fmt}. | |
3476 | ||
3477 | @item display/@var{fmt} @var{addr} | |
3478 | For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a | |
3479 | number of units, add the expression @var{addr} as a memory address to | |
3480 | be examined each time the program stops. Examining means in effect | |
3481 | doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}. | |
3482 | ||
3483 | @item undisplay @var{dnums}@dots{} | |
4187119d | 3484 | @itemx delete display @var{dnums}@dots{} |
e91b87a3 | 3485 | @kindex delete display |
4187119d | 3486 | @kindex undisplay |
e91b87a3 | 3487 | Remove item numbers @var{dnums} from the list of expressions to display. |
3488 | ||
3489 | @item disable display @var{dnums}@dots{} | |
3490 | @kindex disable display | |
4187119d | 3491 | Disable the display of item numbers @var{dnums}. A disabled display |
3492 | item is not printed automatically, but is not forgotten. It may be | |
9d7c0513 | 3493 | enabled again later. |
e91b87a3 | 3494 | |
3495 | @item enable display @var{dnums}@dots{} | |
3496 | @kindex enable display | |
3497 | Enable display of item numbers @var{dnums}. It becomes effective once | |
3498 | again in auto display of its expression, until you specify otherwise. | |
3499 | ||
3500 | @item display | |
3501 | Display the current values of the expressions on the list, just as is | |
3502 | done when the program stops. | |
3503 | ||
3504 | @item info display | |
3505 | @kindex info display | |
4187119d | 3506 | Print the list of expressions previously set up to display |
3507 | automatically, each one with its item number, but without showing the | |
3508 | values. This includes disabled expressions, which are marked as such. | |
3509 | It also includes expressions which would not be displayed right now | |
3510 | because they refer to automatic variables not currently available. | |
e91b87a3 | 3511 | @end table |
3512 | ||
3513 | @node Value History, Convenience Vars, Auto Display, Data | |
3514 | @section Value History | |
3515 | ||
3516 | @cindex value history | |
5a131cc7 | 3517 | Values printed by the @samp{print} command are saved in _GDBN__'s @dfn{value |
23e2e5e1 RP |
3518 | history} so that you can refer to them in other expressions. Values are |
3519 | kept until the symbol table is re-read or discarded (for example with | |
3520 | the @samp{file} or @samp{symbol-file} commands). When the symbol table | |
3521 | changes, the value history is discarded, since the values may contain | |
3522 | pointers back to the types defined in the symbol table. | |
e91b87a3 | 3523 | |
4187119d | 3524 | @cindex @code{$} |
3525 | @cindex @code{$$} | |
3526 | @cindex history number | |
e91b87a3 | 3527 | The values printed are given @dfn{history numbers} for you to refer to them |
3528 | by. These are successive integers starting with 1. @samp{print} shows you | |
4187119d | 3529 | the history number assigned to a value by printing @samp{$@var{num} = } |
3530 | before the value; here @var{num} is the history number. | |
e91b87a3 | 3531 | |
3532 | To refer to any previous value, use @samp{$} followed by the value's | |
9da601bf RP |
3533 | history number. The output printed by @samp{print} is designed to |
3534 | remind you of this. Just @code{$} refers to the most recent value in | |
3535 | the history, and @code{$$} refers to the value before that. | |
3536 | @code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} | |
3537 | is the value just prior to @code{$$}, @code{$$1} is equivalent to | |
3538 | @code{$$}, and @code{$$0} is equivalent to @code{$}. | |
e91b87a3 | 3539 | |
3540 | For example, suppose you have just printed a pointer to a structure and | |
3541 | want to see the contents of the structure. It suffices to type | |
3542 | ||
3543 | @example | |
3544 | p *$ | |
3545 | @end example | |
3546 | ||
3547 | If you have a chain of structures where the component @samp{next} points | |
4187119d | 3548 | to the next one, you can print the contents of the next one with this: |
e91b87a3 | 3549 | |
3550 | @example | |
3551 | p *$.next | |
3552 | @end example | |
3553 | ||
4187119d | 3554 | @noindent |
e91b87a3 | 3555 | It might be useful to repeat this command many times by typing @key{RET}. |
3556 | ||
3557 | Note that the history records values, not expressions. If the value of | |
4187119d | 3558 | @code{x} is 4 and you type this command: |
e91b87a3 | 3559 | |
3560 | @example | |
3561 | print x | |
3562 | set x=5 | |
3563 | @end example | |
3564 | ||
3565 | @noindent | |
3566 | then the value recorded in the value history by the @samp{print} command | |
4187119d | 3567 | remains 4 even though the value of @code{x} has changed. |
e91b87a3 | 3568 | |
3569 | @table @code | |
4187119d | 3570 | @kindex info values |
d2e08421 | 3571 | @item info values |
9da601bf RP |
3572 | @itemx info history |
3573 | @kindex info history | |
3574 | These two commands are synonymous. Either form will print the last ten | |
3575 | values in the value history, with their item numbers. This is like | |
3576 | @samp{p@ $$9} repeated ten times, except that @samp{info values} does | |
3577 | not change the history. | |
e91b87a3 | 3578 | |
4187119d | 3579 | @item info values @var{n} |
e91b87a3 | 3580 | Print ten history values centered on history item number @var{n}. |
4187119d | 3581 | |
3582 | @item info values + | |
3583 | Print ten history values just after the values last printed. | |
e91b87a3 | 3584 | @end table |
3585 | ||
3586 | @node Convenience Vars, Registers, Value History, Data | |
3587 | @section Convenience Variables | |
3588 | ||
3589 | @cindex convenience variables | |
5a131cc7 | 3590 | _GDBN__ provides @dfn{convenience variables} that you can use within _GDBN__ to |
e91b87a3 | 3591 | hold on to a value and refer to it later. These variables exist entirely |
5a131cc7 | 3592 | within _GDBN__; they are not part of your program, and setting a convenience |
e91b87a3 | 3593 | variable has no effect on further execution of your program. That's why |
3594 | you can use them freely. | |
3595 | ||
3596 | Convenience variables have names starting with @samp{$}. Any name starting | |
3597 | with @samp{$} can be used for a convenience variable, unless it is one of | |
3598 | the predefined set of register names (@pxref{Registers}). | |
3599 | ||
3600 | You can save a value in a convenience variable with an assignment | |
3601 | expression, just as you would set a variable in your program. Example: | |
3602 | ||
3603 | @example | |
3604 | set $foo = *object_ptr | |
3605 | @end example | |
3606 | ||
3607 | @noindent | |
4187119d | 3608 | would save in @code{$foo} the value contained in the object pointed to by |
e91b87a3 | 3609 | @code{object_ptr}. |
3610 | ||
3611 | Using a convenience variable for the first time creates it; but its value | |
3612 | is @code{void} until you assign a new value. You can alter the value with | |
3613 | another assignment at any time. | |
3614 | ||
3615 | Convenience variables have no fixed types. You can assign a convenience | |
d2e08421 RP |
3616 | variable any type of value, including structures and arrays, even if |
3617 | that variable already has a value of a different type. The convenience | |
3618 | variable as an expression has whatever type its current value has. | |
e91b87a3 | 3619 | |
3620 | @table @code | |
3621 | @item info convenience | |
3622 | @kindex info convenience | |
3623 | Print a list of convenience variables used so far, and their values. | |
3624 | Abbreviated @samp{i con}. | |
3625 | @end table | |
3626 | ||
3627 | One of the ways to use a convenience variable is as a counter to be | |
3628 | incremented or a pointer to be advanced. For example: | |
3629 | ||
3630 | @example | |
3631 | set $i = 0 | |
3632 | print bar[$i++]->contents | |
3633 | @i{@dots{}repeat that command by typing @key{RET}.} | |
3634 | @end example | |
3635 | ||
5a131cc7 | 3636 | Some convenience variables are created automatically by _GDBN__ and given |
e91b87a3 | 3637 | values likely to be useful. |
3638 | ||
4187119d | 3639 | @table @code |
e91b87a3 | 3640 | @item $_ |
4187119d | 3641 | The variable @code{$_} is automatically set by the @samp{x} command to |
e91b87a3 | 3642 | the last address examined (@pxref{Memory}). Other commands which |
4187119d | 3643 | provide a default address for @samp{x} to examine also set @code{$_} |
e91b87a3 | 3644 | to that address; these commands include @samp{info line} and @samp{info |
3645 | breakpoint}. | |
3646 | ||
3647 | @item $__ | |
4187119d | 3648 | The variable @code{$__} is automatically set by the @samp{x} command |
e91b87a3 | 3649 | to the value found in the last address examined. |
3650 | @end table | |
3651 | ||
54e4a398 | 3652 | @node Registers, , Convenience Vars, Data |
e91b87a3 | 3653 | @section Registers |
3654 | ||
3655 | @cindex registers | |
3656 | Machine register contents can be referred to in expressions as variables | |
3657 | with names starting with @samp{$}. The names of registers are different | |
3658 | for each machine; use @samp{info registers} to see the names used on your | |
d2e08421 | 3659 | machine. The names @code{$pc} and @code{$sp} are used on most machines for |
4187119d | 3660 | the program counter register and the stack pointer. Often @code{$fp} is |
3661 | used for a register that contains a pointer to the current stack frame, | |
3662 | and @code{$ps} is used for a register that contains the processor | |
3663 | status. These standard register names may be available on your machine | |
3664 | even though the @code{info registers} command displays them with a | |
3665 | different name. For example, on the SPARC, @code{info registers} | |
3666 | displays the processor status register as @code{$psr} but you can also | |
3667 | refer to it as @code{$ps}. | |
e91b87a3 | 3668 | |
5a131cc7 | 3669 | _GDBN__ always considers the contents of an ordinary register as an integer |
e91b87a3 | 3670 | when the register is examined in this way. Some machines have special |
3671 | registers which can hold nothing but floating point; these registers are | |
3672 | considered floating point. There is no way to refer to the contents of an | |
3673 | ordinary register as floating point value (although you can @emph{print} | |
3674 | it as a floating point value with @samp{print/f $@var{regname}}). | |
3675 | ||
3676 | Some registers have distinct ``raw'' and ``virtual'' data formats. This | |
9da601bf RP |
3677 | means that the data format in which the register contents are saved by |
3678 | the operating system is not the same one that your program normally | |
3679 | sees. For example, the registers of the 68881 floating point | |
3680 | coprocessor are always saved in ``extended'' (raw) format, but all C | |
3681 | programs expect to work with ``double'' (virtual) format. In such | |
5a131cc7 | 3682 | cases, _GDBN__ normally works with the virtual format only (the format that |
9da601bf RP |
3683 | makes sense for your program), but the @samp{info registers} command |
3684 | prints the data in both formats. | |
e91b87a3 | 3685 | |
3686 | Register values are relative to the selected stack frame | |
3687 | (@pxref{Selection}). This means that you get the value that the register | |
3688 | would contain if all stack frames farther in were exited and their saved | |
3689 | registers restored. In order to see the real contents of all registers, | |
3690 | you must select the innermost frame (with @samp{frame 0}). | |
3691 | ||
3692 | Some registers are never saved (typically those numbered zero or one) | |
d2e08421 RP |
3693 | because they are used for returning function values. In some operating |
3694 | systems (those using the ``caller saves'' convention), there are other | |
3695 | registers intended for free alteration by a called routine. For these | |
3696 | registers, relativization makes no difference. | |
e91b87a3 | 3697 | |
3698 | @table @code | |
3699 | @item info registers | |
3700 | @kindex info registers | |
3701 | Print the names and relativized values of all registers. | |
3702 | ||
3703 | @item info registers @var{regname} | |
3704 | Print the relativized value of register @var{regname}. @var{regname} | |
3705 | may be any register name valid on the machine you are using, with | |
3706 | or without the initial @samp{$}. | |
3707 | @end table | |
3708 | ||
3709 | @subsection Examples | |
3710 | ||
3711 | You could print the program counter in hex with | |
3712 | ||
3713 | @example | |
3714 | p/x $pc | |
3715 | @end example | |
3716 | ||
3717 | @noindent | |
3718 | or print the instruction to be executed next with | |
3719 | ||
3720 | @example | |
3721 | x/i $pc | |
3722 | @end example | |
3723 | ||
3724 | @noindent | |
3725 | or add four to the stack pointer with | |
3726 | ||
3727 | @example | |
3728 | set $sp += 4 | |
3729 | @end example | |
3730 | ||
3731 | @noindent | |
3732 | The last is a way of removing one word from the stack, on machines where | |
3733 | stacks grow downward in memory (most machines, nowadays). This assumes | |
4187119d | 3734 | that the innermost stack frame is selected. Setting @code{$sp} is |
d2e08421 RP |
3735 | not allowed when other stack frames are selected. (To pop entire frames |
3736 | off the stack, regardless of machine architecture, use @samp{return}; | |
3737 | @pxref{Returning}.) | |
e91b87a3 | 3738 | |
3739 | @node Symbols, Altering, Data, Top | |
3740 | @chapter Examining the Symbol Table | |
3741 | ||
9c91ee3e RP |
3742 | The commands described in this section allow you to inquire about the |
3743 | symbols (names of variables, functions and types) defined in your | |
5a131cc7 | 3744 | program. This information is found by _GDBN__ in the symbol table loaded by |
9c91ee3e RP |
3745 | the @samp{symbol-file} command; it is inherent in the text of your |
3746 | program and does not change as the program executes. | |
e91b87a3 | 3747 | |
3748 | @table @code | |
e91b87a3 | 3749 | @item info address @var{symbol} |
3750 | @kindex info address | |
4187119d | 3751 | Describe where the data for @var{symbol} is stored. For a register |
3752 | variable, this says which register it is kept in. For a non-register | |
3753 | local variable, this prints the stack-frame offset at which the variable | |
3754 | is always stored. | |
3755 | ||
3756 | Note the contrast with @samp{print &@var{symbol}}, which does not work | |
3757 | at all for a register variables, and for a stack local variable prints | |
3758 | the exact address of the current instantiation of the variable. | |
e91b87a3 | 3759 | |
831c8511 JG |
3760 | @item whatis @var{exp} |
3761 | @kindex whatis | |
3762 | Print the data type of expression @var{exp}. @var{exp} is not | |
3763 | actually evaluated, and any side-effecting operations (such as | |
3764 | assignments or function calls) inside it do not take place. | |
3765 | @xref{Expressions}. | |
3766 | ||
3767 | @item whatis | |
3768 | Print the data type of @code{$}, the last value in the value history. | |
3769 | ||
e91b87a3 | 3770 | @item ptype @var{typename} |
3771 | @kindex ptype | |
3772 | Print a description of data type @var{typename}. @var{typename} may be | |
3773 | the name of a type, or for C code it may have the form | |
3774 | @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or | |
3775 | @samp{enum @var{enum-tag}}.@refill | |
3776 | ||
831c8511 JG |
3777 | @item ptype @var{exp} |
3778 | Print a description of the type of expression @var{exp}. This is like | |
3779 | @samp{whatis} except it prints a detailed description, instead of just | |
3780 | the name of the type. For example, if the type of a variable is | |
3781 | @samp{struct complex @{double real; double imag;@}}, @samp{whatis} will | |
3782 | print @samp{struct complex} and @samp{ptype} will print @samp{struct | |
3783 | complex @{double real; double imag;@}} | |
3784 | ||
e91b87a3 | 3785 | @item info sources |
3786 | @kindex info sources | |
3787 | Print the names of all source files in the program for which there | |
3788 | is debugging information. | |
3789 | ||
3790 | @item info functions | |
3791 | @kindex info functions | |
3792 | Print the names and data types of all defined functions. | |
3793 | ||
3794 | @item info functions @var{regexp} | |
3795 | Print the names and data types of all defined functions | |
3796 | whose names contain a match for regular expression @var{regexp}. | |
3797 | Thus, @samp{info fun step} finds all functions whose names | |
3798 | include @samp{step}; @samp{info fun ^step} finds those whose names | |
3799 | start with @samp{step}. | |
3800 | ||
3801 | @item info variables | |
3802 | @kindex info variables | |
3803 | Print the names and data types of all variables that are declared | |
4187119d | 3804 | outside of functions (i.e., except for local variables). |
e91b87a3 | 3805 | |
3806 | @item info variables @var{regexp} | |
4187119d | 3807 | Print the names and data types of all variables (except for local |
3808 | variables) whose names contain a match for regular expression | |
e91b87a3 | 3809 | @var{regexp}. |
3810 | ||
e91b87a3 | 3811 | |
7a67dd45 | 3812 | @ignore |
3813 | This was never implemented. | |
e91b87a3 | 3814 | @item info methods |
4187119d | 3815 | @itemx info methods @var{regexp} |
e91b87a3 | 3816 | @kindex info methods |
3817 | The @samp{info-methods} command permits the user to examine all defined | |
4187119d | 3818 | methods within C++ program, or (with the @var{regexp} argument) a |
3819 | specific set of methods found in the various C++ classes. Many | |
3820 | C++ classes provide a large number of methods. Thus, the output | |
3821 | from the @samp{ptype} command can be overwhelming and hard to use. The | |
3822 | @samp{info-methods} command filters the methods, printing only those | |
3823 | which match the regular-expression @var{regexp}. | |
7a67dd45 | 3824 | @end ignore |
e91b87a3 | 3825 | |
3826 | @item printsyms @var{filename} | |
3827 | @kindex printsyms | |
3828 | Write a complete dump of the debugger's symbol data into the | |
3829 | file @var{filename}. | |
3830 | @end table | |
3831 | ||
3832 | @node Altering, Sequences, Symbols, Top | |
3833 | @chapter Altering Execution | |
3834 | ||
9c91ee3e | 3835 | Once you think you have found an error in the program, you might want to |
4187119d | 3836 | find out for certain whether correcting the apparent error would lead to |
3837 | correct results in the rest of the run. You can find the answer by | |
5a131cc7 | 3838 | experiment, using the _GDBN__ features for altering execution of the |
4187119d | 3839 | program. |
3840 | ||
3841 | For example, you can store new values into variables or memory | |
3842 | locations, give the program a signal, restart it at a different address, | |
3843 | or even return prematurely from a function to its caller. | |
e91b87a3 | 3844 | |
3845 | @menu | |
54e4a398 RP |
3846 | * Assignment:: Altering variable values or memory contents. |
3847 | * Jumping:: Altering control flow. | |
3848 | * Signaling:: Making signals happen in the program. | |
3849 | * Returning:: Making a function return prematurely. | |
3850 | * Calling:: Calling functions from your program | |
e91b87a3 | 3851 | @end menu |
3852 | ||
3853 | @node Assignment, Jumping, Altering, Altering | |
3854 | @section Assignment to Variables | |
3855 | ||
3856 | @cindex assignment | |
3857 | @cindex setting variables | |
3858 | To alter the value of a variable, evaluate an assignment expression. | |
3859 | @xref{Expressions}. For example, | |
3860 | ||
3861 | @example | |
3862 | print x=4 | |
3863 | @end example | |
3864 | ||
3865 | @noindent | |
3866 | would store the value 4 into the variable @code{x}, and then print | |
3867 | the value of the assignment expression (which is 4). | |
3868 | ||
4187119d | 3869 | All the assignment operators of C are supported, including the |
880d228b | 3870 | increment operators @samp{++} and @samp{--}, and combining |
4187119d | 3871 | assignments such as @samp{+=} and @samp{<<=}. |
3872 | ||
e91b87a3 | 3873 | @kindex set |
3874 | @kindex set variable | |
d2e08421 | 3875 | @cindex variables, setting |
e91b87a3 | 3876 | If you are not interested in seeing the value of the assignment, use the |
3877 | @samp{set} command instead of the @samp{print} command. @samp{set} is | |
3878 | really the same as @samp{print} except that the expression's value is not | |
3879 | printed and is not put in the value history (@pxref{Value History}). The | |
3880 | expression is evaluated only for side effects. | |
3881 | ||
3882 | Note that if the beginning of the argument string of the @samp{set} command | |
3883 | appears identical to a @samp{set} subcommand, it may be necessary to use | |
3884 | the @samp{set variable} command. This command is identical to @samp{set} | |
3885 | except for its lack of subcommands. | |
3886 | ||
5a131cc7 | 3887 | _GDBN__ allows more implicit conversions in assignments than C does; you can |
e91b87a3 | 3888 | freely store an integer value into a pointer variable or vice versa, and |
3889 | any structure can be converted to any other structure that is the same | |
3890 | length or shorter. | |
9c91ee3e RP |
3891 | @comment FIXME: how do structs align/pad in these conversions? |
3892 | @comment /pesch@cygnus.com 18dec1990 | |
e91b87a3 | 3893 | |
4187119d | 3894 | To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} |
e91b87a3 | 3895 | construct to generate a value of specified type at a specified address |
4187119d | 3896 | (@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer |
3897 | to memory location 0x83040 as an integer (which implies a certain size | |
3898 | and representation in memory), and | |
e91b87a3 | 3899 | |
3900 | @example | |
3901 | set @{int@}0x83040 = 4 | |
3902 | @end example | |
3903 | ||
4187119d | 3904 | would store the value 4 into that memory location. |
3905 | ||
e91b87a3 | 3906 | @node Jumping, Signaling, Assignment, Altering |
3907 | @section Continuing at a Different Address | |
3908 | ||
4187119d | 3909 | Ordinarily, when you continue the program, you do so at the place where |
3910 | it stopped, with the @samp{cont} command. You can instead continue at | |
3911 | an address of your own choosing, with the following commands: | |
3912 | ||
e91b87a3 | 3913 | @table @code |
3914 | @item jump @var{linenum} | |
3915 | @kindex jump | |
3916 | Resume execution at line number @var{linenum}. Execution may stop | |
3917 | immediately if there is a breakpoint there. | |
3918 | ||
3919 | The @samp{jump} command does not change the current stack frame, or | |
3920 | the stack pointer, or the contents of any memory location or any | |
3921 | register other than the program counter. If line @var{linenum} is in | |
3922 | a different function from the one currently executing, the results may | |
4187119d | 3923 | be bizarre if the two functions expect different patterns of arguments or |
e91b87a3 | 3924 | of local variables. For this reason, the @samp{jump} command requests |
3925 | confirmation if the specified line is not in the function currently | |
4187119d | 3926 | executing. However, even bizarre results are predictable based on |
3927 | careful study of the machine-language code of the program. | |
e91b87a3 | 3928 | |
3929 | @item jump *@var{address} | |
3930 | Resume execution at the instruction at address @var{address}. | |
3931 | @end table | |
3932 | ||
4187119d | 3933 | You can get much the same effect as the @code{jump} command by storing a |
3934 | new value into the register @code{$pc}. The difference is that this | |
3935 | does not start the program running; it only changes the address where it | |
3936 | @emph{will} run when it is continued. For example, | |
e91b87a3 | 3937 | |
3938 | @example | |
3939 | set $pc = 0x485 | |
3940 | @end example | |
3941 | ||
3942 | @noindent | |
4187119d | 3943 | causes the next @samp{cont} command or stepping command to execute at |
3944 | address 0x485, rather than at the address where the program stopped. | |
3945 | @xref{Stepping}. | |
3946 | ||
9da601bf RP |
3947 | The most common occasion to use the @samp{jump} command is to back up, |
3948 | perhaps with more breakpoints set, over a portion of a program that has | |
3949 | already executed. | |
e91b87a3 | 3950 | |
3951 | @node Signaling, Returning, Jumping, Altering | |
3952 | @section Giving the Program a Signal | |
3953 | ||
3954 | @table @code | |
3955 | @item signal @var{signalnum} | |
3956 | @kindex signal | |
4187119d | 3957 | Resume execution where the program stopped, but give it immediately the |
3958 | signal number @var{signalnum}. | |
3959 | ||
3960 | Alternatively, if @var{signalnum} is zero, continue execution without | |
3961 | giving a signal. This is useful when the program stopped on account of | |
3962 | a signal and would ordinary see the signal when resumed with the | |
3963 | @samp{cont} command; @samp{signal 0} causes it to resume without a | |
3964 | signal. | |
e91b87a3 | 3965 | @end table |
3966 | ||
9da601bf | 3967 | @node Returning, Calling, Signaling, Altering |
e91b87a3 | 3968 | @section Returning from a Function |
3969 | ||
d2e08421 RP |
3970 | @table @code |
3971 | @item return | |
e91b87a3 | 3972 | @cindex returning from a function |
3973 | @kindex return | |
4187119d | 3974 | You can cancel execution of a function call with the @samp{return} |
d2e08421 RP |
3975 | command. |
3976 | @end table | |
3977 | ||
3978 | This command has the effect of discarding the selected stack | |
4187119d | 3979 | frame (and all frames within it), so that control moves to the caller of |
3980 | that function. You can think of this as making the discarded frame | |
3981 | return prematurely. | |
e91b87a3 | 3982 | |
3983 | First select the stack frame that you wish to return from | |
4187119d | 3984 | (@pxref{Selection}). Then type the @samp{return} command. If you wish |
3985 | to specify the value to be returned, give that as an argument. | |
e91b87a3 | 3986 | |
3987 | This pops the selected stack frame (and any other frames inside of it), | |
3988 | leaving its caller as the innermost remaining frame. That frame becomes | |
3989 | selected. The specified value is stored in the registers used for | |
3990 | returning values of functions. | |
3991 | ||
4187119d | 3992 | The @samp{return} command does not resume execution; it leaves the |
3993 | program stopped in the state that would exist if the function had just | |
3994 | returned. Contrast this with the @samp{finish} command | |
3995 | (@pxref{Stepping}), which resumes execution until the selected stack | |
3996 | frame returns @emph{naturally}. | |
e91b87a3 | 3997 | |
54e4a398 | 3998 | @node Calling, , Returning, Altering |
9da601bf | 3999 | @comment node-name, next, previous, up |
d2e08421 | 4000 | @section Calling your Program's Functions |
9da601bf RP |
4001 | |
4002 | @cindex calling functions | |
4003 | @kindex call | |
4004 | @table @code | |
d2e08421 RP |
4005 | @item call @var{expr} |
4006 | Evaluate the expression @var{expr} without displaying @code{void} | |
4007 | returned values. | |
9da601bf | 4008 | @end table |
d2e08421 RP |
4009 | |
4010 | You can use this variant of the @samp{print} command if you want to | |
4011 | execute some piece of your program, but without cluttering the output | |
4012 | with @code{void} returned values. The result is printed and saved in | |
4013 | the value history, if it is not void. | |
9da601bf | 4014 | |
369a6ade | 4015 | @node Sequences, Emacs, Altering, Top |
e91b87a3 | 4016 | @chapter Canned Sequences of Commands |
4017 | ||
5a131cc7 | 4018 | Aside from breakpoint commands (@pxref{Break Commands}),_GDBN__ provides two |
d2e08421 RP |
4019 | ways to store sequences of commands for execution as a unit: |
4020 | user-defined commands and command files. | |
e91b87a3 | 4021 | |
4022 | @menu | |
54e4a398 RP |
4023 | * Define:: User-defined commands. |
4024 | * Command Files:: Command files. | |
4025 | * Output:: Controlled output commands useful in | |
e91b87a3 | 4026 | user-defined commands and command files. |
4027 | @end menu | |
4028 | ||
4029 | @node Define, Command Files, Sequences, Sequences | |
4030 | @section User-Defined Commands | |
4031 | ||
4187119d | 4032 | @cindex user-defined command |
5a131cc7 | 4033 | A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you |
e91b87a3 | 4034 | assign a new name as a command. This is done with the @samp{define} |
4035 | command. | |
4036 | ||
4037 | @table @code | |
4038 | @item define @var{commandname} | |
4039 | @kindex define | |
4040 | Define a command named @var{commandname}. If there is already a command | |
4041 | by that name, you are asked to confirm that you want to redefine it. | |
4042 | ||
5a131cc7 | 4043 | The definition of the command is made up of other _GDBN__ command lines, |
e91b87a3 | 4044 | which are given following the @samp{define} command. The end of these |
4045 | commands is marked by a line containing @samp{end}. | |
4046 | ||
4047 | @item document @var{commandname} | |
4048 | @kindex document | |
4049 | Give documentation to the user-defined command @var{commandname}. The | |
4050 | command @var{commandname} must already be defined. This command reads | |
4051 | lines of documentation just as @samp{define} reads the lines of the | |
4187119d | 4052 | command definition, ending with @samp{end}. After the @samp{document} |
4053 | command is finished, @samp{help} on command @var{commandname} will print | |
4054 | the documentation you have specified. | |
e91b87a3 | 4055 | |
4056 | You may use the @samp{document} command again to change the | |
4057 | documentation of a command. Redefining the command with @samp{define} | |
4058 | does not change the documentation. | |
4059 | @end table | |
4060 | ||
4061 | User-defined commands do not take arguments. When they are executed, the | |
4062 | commands of the definition are not printed. An error in any command | |
4063 | stops execution of the user-defined command. | |
4064 | ||
4065 | Commands that would ask for confirmation if used interactively proceed | |
5a131cc7 | 4066 | without asking when used inside a user-defined command. Many _GDBN__ commands |
e91b87a3 | 4067 | that normally print messages to say what they are doing omit the messages |
4068 | when used in user-defined command. | |
4069 | ||
4070 | @node Command Files, Output, Define, Sequences | |
4071 | @section Command Files | |
4072 | ||
4073 | @cindex command files | |
5a131cc7 | 4074 | A command file for _GDBN__ is a file of lines that are _GDBN__ commands. Comments |
e91b87a3 | 4075 | (lines starting with @samp{#}) may also be included. An empty line in a |
4076 | command file does nothing; it does not mean to repeat the last command, as | |
4077 | it would from the terminal. | |
4078 | ||
4079 | @cindex init file | |
5a131cc7 RP |
4080 | @cindex @file{._GDBP__init} |
4081 | When you start _GDBN__, it first executes commands from its @dfn{init files}. | |
4082 | These are files named @file{._GDBP__init}. _GDBN__ reads the init file (if any) | |
4afc6002 RP |
4083 | in your home directory and then the init file (if any) in the current |
4084 | working directory. (The init files are not executed if the @samp{-nx} | |
4085 | option is given.) You can also request the execution of a command file | |
4086 | with the @samp{source} command: | |
e91b87a3 | 4087 | |
4088 | @table @code | |
4089 | @item source @var{filename} | |
4090 | @kindex source | |
4091 | Execute the command file @var{filename}. | |
4092 | @end table | |
4093 | ||
4094 | The lines in a command file are executed sequentially. They are not | |
4095 | printed as they are executed. An error in any command terminates execution | |
4096 | of the command file. | |
4097 | ||
4098 | Commands that would ask for confirmation if used interactively proceed | |
5a131cc7 | 4099 | without asking when used in a command file. Many _GDBN__ commands that |
e91b87a3 | 4100 | normally print messages to say what they are doing omit the messages |
4101 | when used in a command file. | |
4102 | ||
54e4a398 | 4103 | @node Output, , Command Files, Sequences |
e91b87a3 | 4104 | @section Commands for Controlled Output |
4105 | ||
4106 | During the execution of a command file or a user-defined command, the only | |
4107 | output that appears is what is explicitly printed by the commands of the | |
4108 | definition. This section describes three commands useful for generating | |
4109 | exactly the output you want. | |
4110 | ||
4111 | @table @code | |
4112 | @item echo @var{text} | |
4113 | @kindex echo | |
4187119d | 4114 | @comment I don't consider backslash-space a standard C escape sequence |
4115 | @comment because it's not in ANSI. | |
4116 | Print @var{text}. Nonprinting characters can be included in @var{text} | |
4117 | using C escape sequences, such as @samp{\n} to print a newline. @b{No | |
4118 | newline will be printed unless you specify one.} In addition to the | |
4119 | standard C escape sequences a backslash followed by a space stands for a | |
4120 | space. This is useful for outputting a string with spaces at the | |
9c91ee3e RP |
4121 | beginning or the end, since leading and trailing spaces are otherwise |
4122 | trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the | |
4123 | command @samp{echo \@ and foo = \@ }. | |
4124 | @comment FIXME: verify hard copy actually issues enspaces for '@ '! Will this | |
4125 | @comment confuse texinfo? | |
4187119d | 4126 | |
4127 | A backslash at the end of @var{text} can be used, as in C, to continue | |
4128 | the command onto subsequent lines. For example, | |
e91b87a3 | 4129 | |
4187119d | 4130 | @example |
4131 | echo This is some text\n\ | |
4132 | which is continued\n\ | |
4133 | onto several lines.\n | |
4134 | @end example | |
4135 | ||
4136 | produces the same output as | |
e91b87a3 | 4137 | |
4138 | @example | |
4187119d | 4139 | echo This is some text\n |
4140 | echo which is continued\n | |
4141 | echo onto several lines.\n | |
e91b87a3 | 4142 | @end example |
4143 | ||
4144 | @item output @var{expression} | |
4145 | @kindex output | |
4146 | Print the value of @var{expression} and nothing but that value: no | |
4147 | newlines, no @samp{$@var{nn} = }. The value is not entered in the | |
4187119d | 4148 | value history either. @xref{Expressions} for more information on |
4149 | expressions. | |
e91b87a3 | 4150 | |
4151 | @item output/@var{fmt} @var{expression} | |
4152 | Print the value of @var{expression} in format @var{fmt}. | |
4187119d | 4153 | @xref{Output formats}, for more information. |
e91b87a3 | 4154 | |
4155 | @item printf @var{string}, @var{expressions}@dots{} | |
4156 | @kindex printf | |
4157 | Print the values of the @var{expressions} under the control of | |
4158 | @var{string}. The @var{expressions} are separated by commas and may | |
4159 | be either numbers or pointers. Their values are printed as specified | |
4160 | by @var{string}, exactly as if the program were to execute | |
4161 | ||
4162 | @example | |
4163 | printf (@var{string}, @var{expressions}@dots{}); | |
4164 | @end example | |
4165 | ||
4166 | For example, you can print two values in hex like this: | |
4167 | ||
4168 | @example | |
4169 | printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo | |
4170 | @end example | |
4171 | ||
9da601bf RP |
4172 | The only backslash-escape sequences that you can use in the format |
4173 | string are the simple ones that consist of backslash followed by a | |
4174 | letter. | |
e91b87a3 | 4175 | @end table |
4176 | ||
369a6ade | 4177 | @node Emacs, Remote, Sequences, Top |
5a131cc7 | 4178 | @chapter Using _GDBN__ under GNU Emacs |
e91b87a3 | 4179 | |
45007746 | 4180 | @cindex emacs |
e91b87a3 | 4181 | A special interface allows you to use GNU Emacs to view (and |
4182 | edit) the source files for the program you are debugging with | |
5a131cc7 | 4183 | _GDBN__. |
e91b87a3 | 4184 | |
4187119d | 4185 | To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the |
4186 | executable file you want to debug as an argument. This command starts | |
5a131cc7 | 4187 | _GDBN__ as a subprocess of Emacs, with input and output through a newly |
4187119d | 4188 | created Emacs buffer. |
e91b87a3 | 4189 | |
5a131cc7 | 4190 | Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two |
4187119d | 4191 | things: |
e91b87a3 | 4192 | |
4193 | @itemize @bullet | |
4194 | @item | |
4195 | All ``terminal'' input and output goes through the Emacs buffer. This | |
5a131cc7 | 4196 | applies both to _GDBN__ commands and their output, and to the input and |
e91b87a3 | 4197 | output done by the program you are debugging. |
4198 | ||
4199 | This is useful because it means that you can copy the text of previous | |
4200 | commands and input them again; you can even use parts of the output | |
4201 | in this way. | |
4202 | ||
880d228b | 4203 | All the facilities of Emacs' Shell mode are available for this purpose. |
e91b87a3 | 4204 | |
4205 | @item | |
5a131cc7 | 4206 | _GDBN__ displays source code through Emacs. Each time _GDBN__ displays a |
e91b87a3 | 4207 | stack frame, Emacs automatically finds the source file for that frame |
4208 | and puts an arrow (@samp{=>}) at the left margin of the current line. | |
9c91ee3e | 4209 | Emacs uses a separate buffer for source display, and splits the window |
5a131cc7 | 4210 | to show both your _GDBN__ session and the source. |
e91b87a3 | 4211 | |
5a131cc7 | 4212 | Explicit _GDBN__ @samp{list} or search commands still produce output as |
e91b87a3 | 4213 | usual, but you probably will have no reason to use them. |
4214 | @end itemize | |
4215 | ||
369a6ade RP |
4216 | @quotation |
4217 | @emph{Warning:} If the directory where your program resides is not your | |
4218 | current directory, it can be easy to confuse Emacs about the location of | |
4219 | the source files, in which case the auxiliary display buffer will not | |
5a131cc7 RP |
4220 | appear to show your source. _GDBN__ can find programs by searching your |
4221 | environment's @samp{PATH} variable, so the _GDBN__ I/O session will proceed | |
4222 | normally; but Emacs doesn't get enough information back from _GDBN__ to | |
369a6ade | 4223 | locate the source files in this situation. To avoid this problem, |
5a131cc7 | 4224 | either start _GDBN__ mode from the directory where your program resides, or |
369a6ade RP |
4225 | specify a full path name when prompted for the @kbd{M-x gdb} argument. |
4226 | ||
5a131cc7 | 4227 | A similar confusion can result if you use the _GDBN__ @samp{file} command to |
369a6ade | 4228 | switch to debugging a program in some other location, from an existing |
5a131cc7 | 4229 | _GDBN__ I/O buffer in Emacs. |
369a6ade RP |
4230 | @end quotation |
4231 | ||
4232 | By default, @kbd{M-x gdb} calls the program called ``@code{gdb}''. If | |
5a131cc7 | 4233 | you need to call _GDBN__ by a different name (for example, if you keep |
369a6ade RP |
4234 | several configurations around, with different names) you can set the |
4235 | Emacs variable @code{gdb-command-name}; for example, | |
4236 | @example | |
4237 | (setq gdb-command-name "mygdb") | |
4238 | @end example | |
4239 | @noindent | |
4240 | (preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or | |
4241 | in your @samp{.emacs} file) will make Emacs call the program named | |
4242 | ``@code{mygdb}'' instead. | |
4243 | ||
5a131cc7 | 4244 | In the _GDBN__ I/O buffer, you can use these special Emacs commands in |
369a6ade | 4245 | addition to the standard Shell mode commands: |
e91b87a3 | 4246 | |
4247 | @table @kbd | |
26376b06 | 4248 | @item C-h m |
5a131cc7 | 4249 | Describe the features of Emacs' _GDBN__ Mode. |
26376b06 | 4250 | |
e91b87a3 | 4251 | @item M-s |
5a131cc7 | 4252 | Execute to another source line, like the _GDBN__ @samp{step} command; also |
369a6ade | 4253 | update the display window to show the current file and location. |
e91b87a3 | 4254 | |
4255 | @item M-n | |
4256 | Execute to next source line in this function, skipping all function | |
5a131cc7 | 4257 | calls, like the _GDBN__ @samp{next} command. Then update the display window |
369a6ade | 4258 | to show the current file and location. |
e91b87a3 | 4259 | |
4260 | @item M-i | |
5a131cc7 | 4261 | Execute one instruction, like the _GDBN__ @samp{stepi} command; update |
369a6ade RP |
4262 | display window accordingly. |
4263 | ||
4264 | @item M-x gdb-nexti | |
5a131cc7 | 4265 | Execute to next instruction, using the _GDBN__ @samp{nexti} command; update |
369a6ade | 4266 | display window accordingly. |
e91b87a3 | 4267 | |
e91b87a3 | 4268 | @item C-c C-f |
5a131cc7 | 4269 | Execute until exit from the selected stack frame, like the _GDBN__ |
e91b87a3 | 4270 | @samp{finish} command. |
4187119d | 4271 | |
7a67dd45 | 4272 | @item M-c |
4273 | @comment C-c C-p in emacs 19 | |
5a131cc7 | 4274 | Continue execution of the program, like the _GDBN__ @samp{cont} command. |
7a67dd45 | 4275 | |
4276 | @item M-u | |
4277 | @comment C-c C-u in emacs 19 | |
4278 | Go up the number of frames indicated by the numeric argument | |
4279 | (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}), | |
5a131cc7 | 4280 | like the _GDBN__ @samp{up} command.@refill |
7a67dd45 | 4281 | |
4282 | @item M-d | |
4283 | @comment C-c C-d in emacs 19 | |
4284 | Go down the number of frames indicated by the numeric argument, like the | |
5a131cc7 | 4285 | _GDBN__ @samp{down} command. |
369a6ade RP |
4286 | |
4287 | @item C-x & | |
4288 | Read the number where the cursor is positioned, and insert it at the end | |
5a131cc7 | 4289 | of the _GDBN__ I/O buffer. For example, if you wish to disassemble code |
369a6ade RP |
4290 | around an address that was displayed earlier, type @kbd{disassemble}; |
4291 | then move the cursor to the address display, and pick up the | |
4292 | argument for @samp{disassemble} by typing @kbd{C-x &}. | |
4293 | ||
4294 | You can customize this further on the fly by defining elements of the list | |
4295 | @samp{gdb-print-command}; once it is defined, you can format or | |
4296 | otherwise process numbers picked up by @kbd{C-x &} before they are | |
4297 | inserted. A numeric argument to @kbd{C-x &} will both flag that you | |
4298 | wish special formatting, and act as an index to pick an element of the | |
4299 | list. If the list element is a string, the number to be inserted is | |
4300 | formatted using the Emacs function @samp{format}; otherwise the number | |
4301 | is passed as an argument to the corresponding list element. | |
4302 | ||
4303 | @item M-x gdb-display-frame | |
4304 | Explicitly request display of the source code surrounding the current | |
5a131cc7 | 4305 | frame location, in another window. _GDBN__ does this display automatically; |
369a6ade RP |
4306 | but if, for example, you accidentally kill the buffer where it is |
4307 | displayed, this command is a way of getting it back. | |
e91b87a3 | 4308 | @end table |
4309 | ||
4310 | In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) | |
5a131cc7 | 4311 | tells _GDBN__ to set a breakpoint on the source line point is on. |
e91b87a3 | 4312 | |
4313 | The source files displayed in Emacs are in ordinary Emacs buffers | |
4314 | which are visiting the source files in the usual way. You can edit | |
5a131cc7 | 4315 | the files with these buffers if you wish; but keep in mind that _GDBN__ |
e91b87a3 | 4316 | communicates with Emacs in terms of line numbers. If you add or |
5a131cc7 | 4317 | delete lines from the text, the line numbers that _GDBN__ knows will cease |
e91b87a3 | 4318 | to correspond properly to the code. |
4319 | ||
4afc6002 RP |
4320 | @comment The following dropped because Epoch is nonstandard. Reactivate |
4321 | @comment if/when v19 does something similar. ---pesch@cygnus.com 19dec1990 | |
4322 | @ignore | |
96a816c5 JG |
4323 | @kindex emacs epoch environment |
4324 | @kindex epoch | |
4325 | @kindex inspect | |
4326 | ||
4327 | Version 18 of Emacs has a built-in window system called the @samp{epoch} | |
4328 | environment. Users of this environment can use a new command, | |
4329 | @samp{inspect} which performs identically to @samp{print} except that | |
4330 | each value is printed in its own window. | |
4afc6002 | 4331 | @end ignore |
96a816c5 | 4332 | |
5a131cc7 | 4333 | @node Remote, _GDBN__ Bugs, Emacs, Top |
9da601bf | 4334 | @chapter Remote Debugging |
d2e08421 | 4335 | @cindex remote debugging |
e91b87a3 | 4336 | |
1c997a4a | 4337 | If you are trying to debug a program running on a machine that can't run |
5a131cc7 | 4338 | _GDBN__ in the usual way, it is often useful to use remote debugging. For |
1c997a4a | 4339 | example, you might be debugging an operating system kernel, or debugging |
4340 | a small system which does not have a general purpose operating system | |
5a131cc7 | 4341 | powerful enough to run a full-featured debugger. Currently _GDBN__ supports |
d2e08421 RP |
4342 | remote debugging over a serial connection, and (using Sun RPC) over a |
4343 | TCP/IP connection. | |
e91b87a3 | 4344 | |
4345 | The program to be debugged on the remote machine needs to contain a | |
5a131cc7 RP |
4346 | debugging device driver which talks to _GDBN__ over the serial line. The |
4347 | same version of _GDBN__ that is used ordinarily can be used for this. | |
4348 | Several sample remote debugging drivers are distributed with _GDBN__; see | |
4349 | the @file{README} file in the _GDBN__ distribution for more information. | |
e91b87a3 | 4350 | |
4351 | @menu | |
54e4a398 | 4352 | * Remote Commands:: Commands used to start and finish remote debugging. |
e91b87a3 | 4353 | @end menu |
4354 | ||
5a131cc7 | 4355 | For details of the communication protocol, see the comments in the _GDBN__ |
e91b87a3 | 4356 | source file @file{remote.c}. |
4357 | ||
54e4a398 | 4358 | @node Remote Commands, , Remote, Remote |
e91b87a3 | 4359 | @section Commands for Remote Debugging |
4360 | ||
5a131cc7 RP |
4361 | To start remote debugging, first run _GDBN__ and specify as an executable file |
4362 | the program that is running in the remote machine. This tells _GDBN__ how | |
e91b87a3 | 4363 | to find the program's symbols and the contents of its pure text. Then |
9da601bf RP |
4364 | establish communication using the @samp{target remote} command with a device |
4365 | name as an argument. For example: | |
e91b87a3 | 4366 | |
4367 | @example | |
9d7c0513 | 4368 | target remote /dev/ttyb |
e91b87a3 | 4369 | @end example |
4370 | ||
54e4a398 | 4371 | @noindent |
9d7c0513 | 4372 | if the serial line is connected to the device named @file{/dev/ttyb}. This |
54e4a398 RP |
4373 | will stop the remote machine if it is not already stopped. |
4374 | ||
4375 | Now you can use all the usual commands to examine and change data and to | |
4376 | step and continue the remote program. | |
4377 | ||
4378 | To resume the remote program and stop debugging it, use the @samp{detach} | |
4379 | command. | |
4380 | ||
9d7c0513 | 4381 | Other remote targets be available in your |
5a131cc7 | 4382 | configuration of _GDBN__; use @samp{info targets} to list them. |
9d7c0513 | 4383 | |
54e4a398 RP |
4384 | @table @code |
4385 | @item reset | |
4386 | @kindex reset | |
4387 | For a target attached through a serial line, this command sends a | |
4388 | ``break'' to the remote target system; this is only useful if the target | |
4389 | has been equipped with a circuit to perform a hard reset (or some other | |
4390 | interesting action) when a break is detected. | |
4391 | @end table | |
4392 | ||
5a131cc7 | 4393 | @node _GDBN__ Bugs, Installing _GDBN__, Remote, Top |
54e4a398 | 4394 | @comment node-name, next, previous, up |
5a131cc7 RP |
4395 | @chapter Reporting Bugs in _GDBN__ |
4396 | @cindex Bugs in _GDBN__ | |
4397 | @cindex Reporting Bugs in _GDBN__ | |
54e4a398 | 4398 | |
5a131cc7 | 4399 | Your bug reports play an essential role in making _GDBN__ reliable. |
54e4a398 RP |
4400 | |
4401 | Reporting a bug may help you by bringing a solution to your problem, or it | |
4402 | may not. But in any case the important function of a bug report is to help | |
5a131cc7 RP |
4403 | the entire community by making the next version of _GDBN__ work better. Bug |
4404 | reports are your contribution to the maintenance of _GDBN__. | |
54e4a398 RP |
4405 | |
4406 | In order for a bug report to serve its purpose, you must include the | |
4407 | information that makes for fixing the bug. | |
4408 | ||
4409 | @menu | |
4410 | * Bug Criteria:: Have You Found a Bug? | |
4411 | * Bug Reporting:: How to Report Bugs | |
4412 | @end menu | |
4413 | ||
5a131cc7 | 4414 | @node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs |
54e4a398 RP |
4415 | @section Have You Found a Bug? |
4416 | @cindex Bug Criteria | |
4417 | ||
4418 | If you are not sure whether you have found a bug, here are some guidelines: | |
4419 | ||
4420 | @itemize @bullet | |
4421 | @item | |
4422 | @cindex Fatal Signal | |
4423 | @cindex Core Dump | |
4424 | If the debugger gets a fatal signal, for any input whatever, that is a | |
5a131cc7 | 4425 | _GDBN__ bug. Reliable debuggers never crash. |
54e4a398 RP |
4426 | |
4427 | @item | |
4428 | @cindex error on Valid Input | |
5a131cc7 | 4429 | If _GDBN__ produces an error message for valid input, that is a bug. |
54e4a398 RP |
4430 | |
4431 | @item | |
4432 | @cindex Invalid Input | |
5a131cc7 | 4433 | If _GDBN__ does not produce an error message for invalid input, |
54e4a398 RP |
4434 | that is a bug. However, you should note that your idea of |
4435 | ``invalid input'' might be our idea of ``an extension'' or ``support | |
4436 | for traditional practice''. | |
4437 | ||
4438 | @item | |
4439 | If you are an experienced user of debugging tools, your suggestions | |
5a131cc7 | 4440 | for improvement of _GDBN__ are welcome in any case. |
54e4a398 RP |
4441 | @end itemize |
4442 | ||
5a131cc7 | 4443 | @node Bug Reporting, , Bug Criteria, _GDBN__ Bugs |
54e4a398 RP |
4444 | @section How to Report Bugs |
4445 | @cindex Bug Reports | |
4446 | @cindex Compiler Bugs, Reporting | |
4447 | ||
4448 | @comment The following is meant to be neutral and helpful, not just a plug for | |
4449 | @comment Cygnus; feedback on the issue (to "pesch@cygnus.com" or | |
4450 | @comment "info@cygnus.com"---the latter will reach all of Cygnus) | |
4451 | @comment is welcome. | |
4452 | A number of companies and individuals offer support for GNU products. | |
5a131cc7 | 4453 | If you obtained _GDBN__ from a support organization, we recommend you |
54e4a398 RP |
4454 | contact that organization first. |
4455 | ||
4456 | Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V | |
4457 | (Paris, France); Dynamix Corporation (King of Prussia PA, USA); The Nice | |
4458 | Computer Company (Perth, Australia); Optimal Solutions (Seattle WA, | |
4459 | USA); and The Pharos Group (Las Cruces NM, USA). | |
4460 | ||
4461 | Full contact information is in the file @samp{etc/SERVICE} in the GNU | |
4462 | Emacs distribution. Numerous individual consultants are also listed | |
4463 | there. | |
4464 | @comment END NEUTRAL+HELPFUL section | |
4465 | ||
5a131cc7 | 4466 | In any event, we also recommend that you send bug reports for _GDBN__ to one |
54e4a398 RP |
4467 | of these addresses: |
4468 | ||
4469 | @example | |
4470 | bug-gdb@@prep.ai.mit.edu | |
4471 | @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb | |
4472 | @end example | |
4473 | ||
4474 | @strong{Do not send bug reports to @samp{info-gdb}, or to | |
5a131cc7 | 4475 | @samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to |
54e4a398 RP |
4476 | receive bug reports. Those that do, have asked to be on @samp{bug-gdb}. |
4477 | ||
4478 | The mailing list @samp{bug-gdb} has a newsgroup which serves as a | |
4479 | repeater. The mailing list and the newsgroup carry exactly the same | |
4480 | messages. Often people think of posting bug reports to the newsgroup | |
4481 | instead of mailing them. This appears to work, but it has one problem | |
4482 | which can be crucial: a newsgroup posting does not contain a mail path | |
4483 | back to the sender. Thus, if we need to ask for more information, we | |
4484 | may be unable to reach you. For this reason, it is better to send bug | |
4485 | reports to the mailing list. | |
4486 | ||
4487 | As a last resort, send bug reports on paper to: | |
4488 | ||
4489 | @example | |
4490 | GNU Debugger Bugs | |
9d7c0513 | 4491 | 545 Tech Square |
54e4a398 RP |
4492 | Cambridge, MA 02139 |
4493 | @end example | |
4494 | ||
4495 | The fundamental principle of reporting bugs usefully is this: | |
4496 | @strong{report all the facts}. If you are not sure whether to state a | |
4497 | fact or leave it out, state it! | |
4498 | ||
4499 | Often people omit facts because they think they know what causes the | |
4500 | problem and they conclude that some details don't matter. Thus, you might | |
4501 | assume that the name of the variable you use in an example does not matter. | |
4502 | Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a | |
4503 | stray memory reference which happens to fetch from the location where that | |
4504 | name is stored in memory; perhaps, if the name were different, the contents | |
4505 | of that location would fool the debugger into doing the right thing despite | |
4506 | the bug. Play it safe and give a specific, complete example. That is the | |
4507 | easiest thing for you to do, and the most helpful. | |
4508 | ||
4509 | Keep in mind that the purpose of a bug report is to enable us to fix | |
4510 | the bug if it is not known. It isn't very important what happens if | |
4511 | the bug is already known. Therefore, always write your bug reports on | |
4512 | the assumption that the bug is not known. | |
4513 | ||
4514 | Sometimes people give a few sketchy facts and ask, ``Does this ring a | |
4515 | bell?'' Those bug reports are useless, and we urge everyone to | |
4516 | @emph{refuse to respond to them} except to chide the sender to report | |
4517 | bugs properly. | |
4518 | ||
4519 | To enable us to fix the bug, you should include all these things: | |
4520 | ||
4521 | @itemize @bullet | |
4522 | @item | |
5a131cc7 | 4523 | The version of _GDBN__. _GDBN__ announces it on startup; you can also print it |
54e4a398 RP |
4524 | at any time using @samp{info version}. |
4525 | ||
4526 | Without this, we won't know whether there is any point in looking for | |
5a131cc7 | 4527 | the bug in the current version of _GDBN__. |
54e4a398 RP |
4528 | |
4529 | @item | |
4530 | A complete input script, and all necessary source files, that will | |
4531 | reproduce the bug. | |
4532 | ||
4533 | @item | |
5a131cc7 RP |
4534 | What compiler (and its version) was used to compile _GDBN__---e.g. |
4535 | ``_GCC__-1.37.1''. | |
54e4a398 RP |
4536 | |
4537 | @item | |
5a131cc7 | 4538 | What compiler (and its version) was used to compile _GDBN__. |
54e4a398 RP |
4539 | |
4540 | @item | |
4541 | The command arguments you gave the compiler to compile that example and | |
4542 | observe the bug. For example, did you use @samp{-O}? To guarantee | |
4543 | you won't omit something important, list them all. | |
4544 | ||
4545 | If we were to try to guess the arguments, we would probably guess wrong | |
4546 | and then we would not encounter the bug. | |
4547 | ||
4548 | @item | |
4549 | The type of machine you are using, and the operating system name and | |
4550 | version number. | |
4551 | ||
4552 | @item | |
4553 | A description of what behavior you observe that you believe is | |
4554 | incorrect. For example, ``It gets a fatal signal.'' | |
4555 | ||
5a131cc7 | 4556 | Of course, if the bug is that _GDBN__ gets a fatal signal, then we |
54e4a398 RP |
4557 | will certainly notice it. But if the bug is incorrect output, we might |
4558 | not notice unless it is glaringly wrong. | |
4559 | ||
4560 | Even if the problem you experience is a fatal signal, you should still | |
4561 | say so explicitly. Suppose something strange is going on, such as, | |
5a131cc7 | 4562 | your copy of _GDBN__ is out of synch, or you have encountered a |
54e4a398 RP |
4563 | bug in the C library on your system. (This has happened!) Your copy |
4564 | might crash and ours would not. If you @i{told} us to expect a crash, | |
4565 | then when ours fails to crash, we would know that the bug was not | |
4566 | happening for us. If you had not told us to expect a crash, then we | |
4567 | would not be able to draw any conclusion from our observations. | |
4568 | ||
4569 | @item | |
5a131cc7 RP |
4570 | If you wish to suggest changes to the _GDBN__ source, send us context |
4571 | diffs. If you even discuss something in the _GDBN__ source, refer to | |
54e4a398 RP |
4572 | it by context, not by line number. |
4573 | ||
4574 | The line numbers in our development sources don't match those in your | |
4575 | sources. Your line numbers would convey no useful information to us. | |
4576 | ||
4577 | @end itemize | |
4578 | ||
4579 | Here are some things that are not necessary: | |
4580 | ||
4581 | @itemize @bullet | |
4582 | @item | |
4583 | A description of the envelope of the bug. | |
4584 | ||
4585 | Often people who encounter a bug spend a lot of time investigating | |
4586 | which changes to the input file will make the bug go away and which | |
4587 | changes will not affect it. | |
4588 | ||
4589 | This is often time consuming and not very useful, because the way we | |
4590 | will find the bug is by running a single example under the debugger | |
4591 | with breakpoints, not by pure deduction from a series of examples. | |
4592 | We recommend that you save your time for something else. | |
4593 | ||
4594 | Of course, if you can find a simpler example to report @emph{instead} | |
4595 | of the original one, that is a convenience for us. Errors in the | |
4596 | output will be easier to spot, running under the debugger will take | |
4597 | less time, etc. | |
4598 | ||
4599 | However, simplification is not vital; if you don't want to do this, | |
4600 | report the bug anyway and send us the entire test case you used. | |
4601 | ||
4602 | @item | |
4603 | A patch for the bug. | |
4604 | ||
4605 | A patch for the bug does help us if it is a good one. But don't omit | |
4606 | the necessary information, such as the test case, on the assumption that | |
4607 | a patch is all we need. We might see problems with your patch and decide | |
4608 | to fix the problem another way, or we might not understand it at all. | |
4609 | ||
5a131cc7 | 4610 | Sometimes with a program as complicated as _GDBN__ it is very hard to |
54e4a398 RP |
4611 | construct an example that will make the program follow a certain path |
4612 | through the code. If you don't send us the example, we won't be able | |
4613 | to construct one, so we won't be able to verify that the bug is fixed. | |
4614 | ||
4615 | And if we can't understand what bug you are trying to fix, or why your | |
4616 | patch should be an improvement, we won't install it. A test case will | |
4617 | help us to understand. | |
e91b87a3 | 4618 | |
54e4a398 RP |
4619 | @item |
4620 | A guess about what the bug is or what it depends on. | |
e91b87a3 | 4621 | |
54e4a398 RP |
4622 | Such guesses are usually wrong. Even we can't guess right about such |
4623 | things without first using the debugger to find the facts. | |
4624 | @end itemize | |
e91b87a3 | 4625 | |
54e4a398 RP |
4626 | @iftex |
4627 | @include readline/inc-readline.texinfo | |
4628 | @include readline/inc-history.texinfo | |
4629 | @end iftex | |
9da601bf | 4630 | |
5a131cc7 RP |
4631 | @node Installing _GDBN__, License, _GDBN__ Bugs, Top |
4632 | @appendix Installing _GDBN__ | |
4633 | @cindex configuring _GDBN__ | |
54e4a398 | 4634 | @cindex installation |
9c91ee3e | 4635 | |
5a131cc7 | 4636 | The script @samp{config.gdb} automates the process of preparing _GDBN__ for |
54e4a398 RP |
4637 | installation; you can then use @samp{make} to actually build it. For |
4638 | example, | |
9c91ee3e | 4639 | |
54e4a398 RP |
4640 | @example |
4641 | config.gdb sun3os4 | |
4642 | make | |
4643 | @end example | |
9c91ee3e | 4644 | |
54e4a398 | 4645 | @noindent |
5a131cc7 | 4646 | is all that's required to install _GDBN__ on a Sun 3 running SunOS 4. |
9c91ee3e | 4647 | |
54e4a398 RP |
4648 | @table @code |
4649 | @kindex config.gdb | |
4650 | @item config.gdb @var{machine} | |
23e2e5e1 | 4651 | @itemx config.gdb -srcdir=@var{dir} @var{machine} |
5a131cc7 RP |
4652 | This is the most usual way of configuring _GDBN__; to debug programs running |
4653 | on the same machine as _GDBN__ itself. If you wish to build the _GDBN__ binaries | |
54e4a398 | 4654 | in a completely different directory from the sources, specify a path to |
23e2e5e1 | 4655 | the source directory using the @samp{-srcdir} option. |
9c91ee3e | 4656 | |
23e2e5e1 | 4657 | @item config.gdb -host |
54e4a398 | 4658 | @cindex host environments |
5a131cc7 | 4659 | Display a list of supported host environments for _GDBN__. |
9c91ee3e | 4660 | |
54e4a398 | 4661 | @item config.gdb @var{host} @var{target} |
23e2e5e1 | 4662 | @itemx config.gdb -srcdir=@var{dir} @var{host} @var{target} |
54e4a398 | 4663 | @cindex cross-debugging |
5a131cc7 | 4664 | _GDBN__ can also be used as a cross-debugger, running on a machine of one |
54e4a398 RP |
4665 | type while debugging a program running on a machine of another type. |
4666 | You configure it this way by specifying first the @var{host}, then the | |
4667 | @var{target} environment on the @code{config.gdb} argument list; the | |
5a131cc7 | 4668 | @var{host} is where _GDBN__ runs, and the @var{target} is where your program |
23e2e5e1 | 4669 | runs. @xref{Remote}. Again, you can use @samp{-srcdir} to specify a |
5a131cc7 | 4670 | path to the _GDBN__ source. |
9c91ee3e | 4671 | |
23e2e5e1 | 4672 | @item config.gdb -target |
54e4a398 | 4673 | @cindex target environments |
5a131cc7 | 4674 | Display a list of supported target environments for _GDBN__. |
54e4a398 | 4675 | @end table |
9c91ee3e | 4676 | |
5a131cc7 | 4677 | @node License,,, |
54e4a398 RP |
4678 | @unnumbered GNU GENERAL PUBLIC LICENSE |
4679 | @center Version 1, February 1989 | |
9c91ee3e | 4680 | |
54e4a398 RP |
4681 | @display |
4682 | Copyright @copyright{} 1989 Free Software Foundation, Inc. | |
4683 | 675 Mass Ave, Cambridge, MA 02139, USA | |
9c91ee3e | 4684 | |
54e4a398 RP |
4685 | Everyone is permitted to copy and distribute verbatim copies |
4686 | of this license document, but changing it is not allowed. | |
4687 | @end display | |
9c91ee3e | 4688 | |
54e4a398 | 4689 | @unnumberedsec Preamble |
9c91ee3e | 4690 | |
54e4a398 RP |
4691 | The license agreements of most software companies try to keep users |
4692 | at the mercy of those companies. By contrast, our General Public | |
4693 | License is intended to guarantee your freedom to share and change free | |
4694 | software---to make sure the software is free for all its users. The | |
4695 | General Public License applies to the Free Software Foundation's | |
4696 | software and to any other program whose authors commit to using it. | |
4697 | You can use it for your programs, too. | |
d2e08421 | 4698 | |
54e4a398 RP |
4699 | When we speak of free software, we are referring to freedom, not |
4700 | price. Specifically, the General Public License is designed to make | |
4701 | sure that you have the freedom to give away or sell copies of free | |
4702 | software, that you receive source code or can get it if you want it, | |
4703 | that you can change the software or use pieces of it in new free | |
4704 | programs; and that you know you can do these things. | |
d2e08421 | 4705 | |
54e4a398 RP |
4706 | To protect your rights, we need to make restrictions that forbid |
4707 | anyone to deny you these rights or to ask you to surrender the rights. | |
4708 | These restrictions translate to certain responsibilities for you if you | |
4709 | distribute copies of the software, or if you modify it. | |
d2e08421 | 4710 | |
54e4a398 RP |
4711 | For example, if you distribute copies of a such a program, whether |
4712 | gratis or for a fee, you must give the recipients all the rights that | |
4713 | you have. You must make sure that they, too, receive or can get the | |
4714 | source code. And you must tell them their rights. | |
9c91ee3e | 4715 | |
54e4a398 RP |
4716 | We protect your rights with two steps: (1) copyright the software, and |
4717 | (2) offer you this license which gives you legal permission to copy, | |
4718 | distribute and/or modify the software. | |
9c91ee3e | 4719 | |
54e4a398 RP |
4720 | Also, for each author's protection and ours, we want to make certain |
4721 | that everyone understands that there is no warranty for this free | |
4722 | software. If the software is modified by someone else and passed on, we | |
4723 | want its recipients to know that what they have is not the original, so | |
4724 | that any problems introduced by others will not reflect on the original | |
4725 | authors' reputations. | |
9c91ee3e | 4726 | |
54e4a398 RP |
4727 | The precise terms and conditions for copying, distribution and |
4728 | modification follow. | |
9c91ee3e | 4729 | |
54e4a398 RP |
4730 | @iftex |
4731 | @unnumberedsec TERMS AND CONDITIONS | |
4732 | @end iftex | |
4733 | @ifinfo | |
4734 | @center TERMS AND CONDITIONS | |
4735 | @end ifinfo | |
9c91ee3e | 4736 | |
54e4a398 RP |
4737 | @enumerate |
4738 | @item | |
4739 | This License Agreement applies to any program or other work which | |
4740 | contains a notice placed by the copyright holder saying it may be | |
4741 | distributed under the terms of this General Public License. The | |
4742 | ``Program'', below, refers to any such program or work, and a ``work based | |
4743 | on the Program'' means either the Program or any work containing the | |
4744 | Program or a portion of it, either verbatim or with modifications. Each | |
4745 | licensee is addressed as ``you''. | |
9c91ee3e | 4746 | |
54e4a398 RP |
4747 | @item |
4748 | You may copy and distribute verbatim copies of the Program's source | |
4749 | code as you receive it, in any medium, provided that you conspicuously and | |
4750 | appropriately publish on each copy an appropriate copyright notice and | |
4751 | disclaimer of warranty; keep intact all the notices that refer to this | |
4752 | General Public License and to the absence of any warranty; and give any | |
4753 | other recipients of the Program a copy of this General Public License | |
4754 | along with the Program. You may charge a fee for the physical act of | |
4755 | transferring a copy. | |
9c91ee3e | 4756 | |
54e4a398 RP |
4757 | @item |
4758 | You may modify your copy or copies of the Program or any portion of | |
4759 | it, and copy and distribute such modifications under the terms of Paragraph | |
4760 | 1 above, provided that you also do the following: | |
9c91ee3e | 4761 | |
54e4a398 RP |
4762 | @itemize @bullet |
4763 | @item | |
4764 | cause the modified files to carry prominent notices stating that | |
4765 | you changed the files and the date of any change; and | |
9c91ee3e | 4766 | |
54e4a398 RP |
4767 | @item |
4768 | cause the whole of any work that you distribute or publish, that | |
4769 | in whole or in part contains the Program or any part thereof, either | |
4770 | with or without modifications, to be licensed at no charge to all | |
4771 | third parties under the terms of this General Public License (except | |
4772 | that you may choose to grant warranty protection to some or all | |
4773 | third parties, at your option). | |
9c91ee3e | 4774 | |
54e4a398 RP |
4775 | @item |
4776 | If the modified program normally reads commands interactively when | |
4777 | run, you must cause it, when started running for such interactive use | |
4778 | in the simplest and most usual way, to print or display an | |
4779 | announcement including an appropriate copyright notice and a notice | |
4780 | that there is no warranty (or else, saying that you provide a | |
4781 | warranty) and that users may redistribute the program under these | |
4782 | conditions, and telling the user how to view a copy of this General | |
4783 | Public License. | |
9c91ee3e | 4784 | |
9c91ee3e | 4785 | @item |
54e4a398 RP |
4786 | You may charge a fee for the physical act of transferring a |
4787 | copy, and you may at your option offer warranty protection in | |
4788 | exchange for a fee. | |
4789 | @end itemize | |
9c91ee3e | 4790 | |
54e4a398 RP |
4791 | Mere aggregation of another independent work with the Program (or its |
4792 | derivative) on a volume of a storage or distribution medium does not bring | |
4793 | the other work under the scope of these terms. | |
9c91ee3e RP |
4794 | |
4795 | @item | |
54e4a398 RP |
4796 | You may copy and distribute the Program (or a portion or derivative of |
4797 | it, under Paragraph 2) in object code or executable form under the terms of | |
4798 | Paragraphs 1 and 2 above provided that you also do one of the following: | |
9c91ee3e | 4799 | |
54e4a398 | 4800 | @itemize @bullet |
26376b06 | 4801 | @item |
54e4a398 RP |
4802 | accompany it with the complete corresponding machine-readable |
4803 | source code, which must be distributed under the terms of | |
4804 | Paragraphs 1 and 2 above; or, | |
9c91ee3e RP |
4805 | |
4806 | @item | |
54e4a398 RP |
4807 | accompany it with a written offer, valid for at least three |
4808 | years, to give any third party free (except for a nominal charge | |
4809 | for the cost of distribution) a complete machine-readable copy of the | |
4810 | corresponding source code, to be distributed under the terms of | |
4811 | Paragraphs 1 and 2 above; or, | |
d2e08421 RP |
4812 | |
4813 | @item | |
54e4a398 RP |
4814 | accompany it with the information you received as to where the |
4815 | corresponding source code may be obtained. (This alternative is | |
4816 | allowed only for noncommercial distribution and only if you | |
4817 | received the program in object code or executable form alone.) | |
4818 | @end itemize | |
9c91ee3e | 4819 | |
54e4a398 RP |
4820 | Source code for a work means the preferred form of the work for making |
4821 | modifications to it. For an executable file, complete source code means | |
4822 | all the source code for all modules it contains; but, as a special | |
4823 | exception, it need not include source code for modules which are standard | |
4824 | libraries that accompany the operating system on which the executable | |
4825 | file runs, or for standard header files or definitions files that | |
4826 | accompany that operating system. | |
9c91ee3e RP |
4827 | |
4828 | @item | |
54e4a398 RP |
4829 | You may not copy, modify, sublicense, distribute or transfer the |
4830 | Program except as expressly provided under this General Public License. | |
4831 | Any attempt otherwise to copy, modify, sublicense, distribute or transfer | |
4832 | the Program is void, and will automatically terminate your rights to use | |
4833 | the Program under this License. However, parties who have received | |
4834 | copies, or rights to use copies, from you under this General Public | |
4835 | License will not have their licenses terminated so long as such parties | |
4836 | remain in full compliance. | |
9c91ee3e RP |
4837 | |
4838 | @item | |
54e4a398 RP |
4839 | By copying, distributing or modifying the Program (or any work based |
4840 | on the Program) you indicate your acceptance of this license to do so, | |
4841 | and all its terms and conditions. | |
9c91ee3e RP |
4842 | |
4843 | @item | |
54e4a398 RP |
4844 | Each time you redistribute the Program (or any work based on the |
4845 | Program), the recipient automatically receives a license from the original | |
4846 | licensor to copy, distribute or modify the Program subject to these | |
4847 | terms and conditions. You may not impose any further restrictions on the | |
4848 | recipients' exercise of the rights granted herein. | |
9c91ee3e | 4849 | |
54e4a398 RP |
4850 | @item |
4851 | The Free Software Foundation may publish revised and/or new versions | |
4852 | of the General Public License from time to time. Such new versions will | |
4853 | be similar in spirit to the present version, but may differ in detail to | |
4854 | address new problems or concerns. | |
9c91ee3e | 4855 | |
54e4a398 RP |
4856 | Each version is given a distinguishing version number. If the Program |
4857 | specifies a version number of the license which applies to it and ``any | |
4858 | later version'', you have the option of following the terms and conditions | |
4859 | either of that version or of any later version published by the Free | |
4860 | Software Foundation. If the Program does not specify a version number of | |
4861 | the license, you may choose any version ever published by the Free Software | |
4862 | Foundation. | |
9c91ee3e | 4863 | |
9c91ee3e | 4864 | @item |
54e4a398 RP |
4865 | If you wish to incorporate parts of the Program into other free |
4866 | programs whose distribution conditions are different, write to the author | |
4867 | to ask for permission. For software which is copyrighted by the Free | |
4868 | Software Foundation, write to the Free Software Foundation; we sometimes | |
4869 | make exceptions for this. Our decision will be guided by the two goals | |
4870 | of preserving the free status of all derivatives of our free software and | |
4871 | of promoting the sharing and reuse of software generally. | |
9c91ee3e | 4872 | |
54e4a398 RP |
4873 | @iftex |
4874 | @heading NO WARRANTY | |
4875 | @end iftex | |
4876 | @ifinfo | |
4877 | @center NO WARRANTY | |
4878 | @end ifinfo | |
9c91ee3e | 4879 | |
54e4a398 RP |
4880 | @item |
4881 | BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | |
4882 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN | |
4883 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | |
4884 | PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED | |
4885 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
4886 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS | |
4887 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE | |
4888 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, | |
4889 | REPAIR OR CORRECTION. | |
9c91ee3e | 4890 | |
54e4a398 RP |
4891 | @item |
4892 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL | |
4893 | ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | |
4894 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | |
4895 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES | |
4896 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT | |
4897 | LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES | |
4898 | SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE | |
4899 | WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN | |
4900 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | |
4901 | @end enumerate | |
9c91ee3e | 4902 | |
54e4a398 RP |
4903 | @iftex |
4904 | @heading END OF TERMS AND CONDITIONS | |
4905 | @end iftex | |
4906 | @ifinfo | |
4907 | @center END OF TERMS AND CONDITIONS | |
4908 | @end ifinfo | |
9c91ee3e | 4909 | |
54e4a398 | 4910 | @page |
cb9d2049 | 4911 | @unnumberedsec Applying These Terms to Your New Programs |
9c91ee3e | 4912 | |
54e4a398 RP |
4913 | If you develop a new program, and you want it to be of the greatest |
4914 | possible use to humanity, the best way to achieve this is to make it | |
4915 | free software which everyone can redistribute and change under these | |
4916 | terms. | |
9c91ee3e | 4917 | |
54e4a398 RP |
4918 | To do so, attach the following notices to the program. It is safest to |
4919 | attach them to the start of each source file to most effectively convey | |
4920 | the exclusion of warranty; and each file should have at least the | |
4921 | ``copyright'' line and a pointer to where the full notice is found. | |
9c91ee3e | 4922 | |
54e4a398 RP |
4923 | @smallexample |
4924 | @var{one line to give the program's name and a brief idea of what it does.} | |
4925 | Copyright (C) 19@var{yy} @var{name of author} | |
9c91ee3e | 4926 | |
54e4a398 RP |
4927 | This program is free software; you can redistribute it and/or modify |
4928 | it under the terms of the GNU General Public License as published by | |
4929 | the Free Software Foundation; either version 1, or (at your option) | |
4930 | any later version. | |
9c91ee3e | 4931 | |
54e4a398 RP |
4932 | This program is distributed in the hope that it will be useful, |
4933 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
4934 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
4935 | GNU General Public License for more details. | |
9c91ee3e | 4936 | |
54e4a398 RP |
4937 | You should have received a copy of the GNU General Public License |
4938 | along with this program; if not, write to the Free Software | |
4939 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
4940 | @end smallexample | |
4187119d | 4941 | |
54e4a398 | 4942 | Also add information on how to contact you by electronic and paper mail. |
d2e08421 | 4943 | |
54e4a398 RP |
4944 | If the program is interactive, make it output a short notice like this |
4945 | when it starts in an interactive mode: | |
d2e08421 | 4946 | |
54e4a398 RP |
4947 | @smallexample |
4948 | Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} | |
4949 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. | |
4950 | This is free software, and you are welcome to redistribute it | |
4951 | under certain conditions; type `show c' for details. | |
4952 | @end smallexample | |
d2e08421 | 4953 | |
54e4a398 RP |
4954 | The hypothetical commands `show w' and `show c' should show the |
4955 | appropriate parts of the General Public License. Of course, the | |
4956 | commands you use may be called something other than `show w' and `show | |
4957 | c'; they could even be mouse-clicks or menu items---whatever suits your | |
4958 | program. | |
d2e08421 | 4959 | |
54e4a398 RP |
4960 | You should also get your employer (if you work as a programmer) or your |
4961 | school, if any, to sign a ``copyright disclaimer'' for the program, if | |
4962 | necessary. Here is a sample; alter the names: | |
d2e08421 | 4963 | |
54e4a398 RP |
4964 | @smallexample |
4965 | Yoyodyne, Inc., hereby disclaims all copyright interest in the | |
4966 | program `Gnomovision' (a program to direct compilers to make passes | |
4967 | at assemblers) written by James Hacker. | |
d2e08421 | 4968 | |
54e4a398 RP |
4969 | @var{signature of Ty Coon}, 1 April 1989 |
4970 | Ty Coon, President of Vice | |
4971 | @end smallexample | |
d2e08421 | 4972 | |
54e4a398 | 4973 | That's all there is to it! |
d2e08421 | 4974 | |
54e4a398 | 4975 | @node Commands, Concepts, License, Top |
e91b87a3 | 4976 | @unnumbered Command Index |
4977 | ||
4978 | @printindex ky | |
4979 | ||
54e4a398 | 4980 | @node Concepts, , Commands, Top |
d2e08421 | 4981 | @unnumbered Index |
e91b87a3 | 4982 | |
4983 | @printindex cp | |
4984 | ||
4985 | @contents | |
4986 | @bye |