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