Commit | Line | Data |
---|---|---|
3bfd3547 C |
1 | \input texinfo |
2 | @setfilename gdb.info | |
3 | @settitle GDB, The GNU Debugger | |
4 | @synindex ky cp | |
5 | @ifinfo | |
6 | This file documents the GNU debugger GDB. | |
7 | ||
8 | Copyright (C) 1988, 1989 Free Software Foundation, Inc. | |
9 | ||
10 | Permission is granted to make and distribute verbatim copies of | |
11 | this manual provided the copyright notice and this permission notice | |
12 | are preserved on all copies. | |
13 | ||
14 | @ignore | |
15 | Permission is granted to process this file through Tex and print the | |
16 | results, provided the printed document carries copying permission | |
17 | notice identical to this one except for the removal of this paragraph | |
18 | (this paragraph not being relevant to the printed manual). | |
19 | ||
20 | @end ignore | |
21 | Permission is granted to copy and distribute modified versions of this | |
22 | manual under the conditions for verbatim copying, provided also that the | |
23 | section entitled ``GNU General Public License'' is included exactly as | |
24 | in the original, and provided that the entire resulting derived work is | |
25 | distributed under the terms of a permission notice identical to this | |
26 | one. | |
27 | ||
28 | Permission is granted to copy and distribute translations of this manual | |
29 | into another language, under the above conditions for modified versions, | |
30 | except that the section entitled ``GNU General Public License'' may be | |
31 | included in a translation approved by the author instead of in the | |
32 | original English. | |
33 | @end ifinfo | |
34 | ||
35 | @setchapternewpage odd | |
36 | @settitle GDB Manual | |
37 | @titlepage | |
38 | @sp 6 | |
39 | @center @titlefont{GDB Manual} | |
40 | @sp 1 | |
41 | @center The GNU Source-Level Debugger | |
42 | @sp 4 | |
43 | @center Third Edition, GDB version 3.4 | |
44 | @sp 1 | |
45 | @center October 1989 | |
46 | @sp 5 | |
47 | @center Richard M. Stallman | |
48 | @page | |
49 | @vskip 0pt plus 1filll | |
50 | Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc. | |
51 | ||
52 | Permission is granted to make and distribute verbatim copies of | |
53 | this manual provided the copyright notice and this permission notice | |
54 | are preserved on all copies. | |
55 | ||
56 | Permission is granted to copy and distribute modified versions of this | |
57 | manual under the conditions for verbatim copying, provided also that the | |
58 | section entitled ``GNU General Public License'' is included exactly as | |
59 | in the original, and provided that the entire resulting derived work is | |
60 | distributed under the terms of a permission notice identical to this | |
61 | one. | |
62 | ||
63 | Permission is granted to copy and distribute translations of this manual | |
64 | into another language, under the above conditions for modified versions, | |
65 | except that the section entitled ``GNU General Public License'' may be | |
66 | included in a translation approved by the author instead of in the | |
67 | original English. | |
68 | @end titlepage | |
69 | @page | |
70 | ||
71 | @node Top, Top, Top, (DIR) | |
72 | @unnumbered Summary of GDB | |
73 | ||
74 | The purpose of a debugger such as GDB is to allow you to execute another | |
75 | program while examining what is going on inside it. We call the other | |
76 | program ``your program'' or ``the program being debugged''. | |
77 | ||
78 | GDB can do four kinds of things (plus other things in support of these): | |
79 | ||
80 | @enumerate | |
81 | @item | |
82 | Start the program, specifying anything that might affect its behavior. | |
83 | ||
84 | @item | |
85 | Make the program stop on specified conditions. | |
86 | ||
87 | @item | |
88 | Examine what has happened, when the program has stopped, so that you | |
89 | can see bugs happen. | |
90 | ||
91 | @item | |
92 | Change things in the program, so you can correct the effects of one bug | |
93 | and go on to learn about another without having to recompile first. | |
94 | @end enumerate | |
95 | ||
96 | GDB can be used to debug programs written in C and C++. Pascal support | |
97 | is being implemented, and Fortran support will be added when a GNU | |
98 | Fortran compiler is written. | |
99 | ||
100 | @menu | |
101 | * License:: The GNU General Public License gives you permission | |
102 | to redistribute GDB on certain terms; and also | |
103 | explains that there is no warranty. | |
104 | * User Interface:: GDB command syntax and input and output conventions. | |
105 | * Files:: Specifying files for GDB to operate on. | |
106 | * Options:: GDB arguments and options. | |
107 | * Compilation::Compiling your program so you can debug it. | |
108 | * Running:: Running your program under GDB. | |
109 | * Stopping:: Making your program stop. Why it may stop. What to do then. | |
110 | * Stack:: Examining your program's stack. | |
111 | * Source:: Examining your program's source files. | |
112 | * Data:: Examining data in your program. | |
113 | * Symbols:: Examining the debugger's symbol table. | |
114 | * Altering:: Altering things in your program. | |
115 | * Sequences:: Canned command sequences for repeated use. | |
116 | * Emacs:: Using GDB through GNU Emacs. | |
117 | * Remote:: Remote kernel debugging across a serial line. | |
118 | * Commands:: Index of GDB commands. | |
119 | * Concepts:: Index of GDB concepts. | |
120 | @end menu | |
121 | ||
122 | @node License, User Interface, Top, Top | |
123 | @unnumbered GNU GENERAL PUBLIC LICENSE | |
124 | @center Version 1, February 1989 | |
125 | ||
126 | @display | |
127 | Copyright @copyright{} 1989 Free Software Foundation, Inc. | |
128 | 675 Mass Ave, Cambridge, MA 02139, USA | |
129 | ||
130 | Everyone is permitted to copy and distribute verbatim copies | |
131 | of this license document, but changing it is not allowed. | |
132 | @end display | |
133 | ||
134 | @unnumberedsec Preamble | |
135 | ||
136 | The license agreements of most software companies try to keep users | |
137 | at the mercy of those companies. By contrast, our General Public | |
138 | License is intended to guarantee your freedom to share and change free | |
139 | software---to make sure the software is free for all its users. The | |
140 | General Public License applies to the Free Software Foundation's | |
141 | software and to any other program whose authors commit to using it. | |
142 | You can use it for your programs, too. | |
143 | ||
144 | When we speak of free software, we are referring to freedom, not | |
145 | price. Specifically, the General Public License is designed to make | |
146 | sure that you have the freedom to give away or sell copies of free | |
147 | software, that you receive source code or can get it if you want it, | |
148 | that you can change the software or use pieces of it in new free | |
149 | programs; and that you know you can do these things. | |
150 | ||
151 | To protect your rights, we need to make restrictions that forbid | |
152 | anyone to deny you these rights or to ask you to surrender the rights. | |
153 | These restrictions translate to certain responsibilities for you if you | |
154 | distribute copies of the software, or if you modify it. | |
155 | ||
156 | For example, if you distribute copies of a such a program, whether | |
157 | gratis or for a fee, you must give the recipients all the rights that | |
158 | you have. You must make sure that they, too, receive or can get the | |
159 | source code. And you must tell them their rights. | |
160 | ||
161 | We protect your rights with two steps: (1) copyright the software, and | |
162 | (2) offer you this license which gives you legal permission to copy, | |
163 | distribute and/or modify the software. | |
164 | ||
165 | Also, for each author's protection and ours, we want to make certain | |
166 | that everyone understands that there is no warranty for this free | |
167 | software. If the software is modified by someone else and passed on, we | |
168 | want its recipients to know that what they have is not the original, so | |
169 | that any problems introduced by others will not reflect on the original | |
170 | authors' reputations. | |
171 | ||
172 | The precise terms and conditions for copying, distribution and | |
173 | modification follow. | |
174 | ||
175 | @iftex | |
176 | @unnumberedsec TERMS AND CONDITIONS | |
177 | @end iftex | |
178 | @ifinfo | |
179 | @center TERMS AND CONDITIONS | |
180 | @end ifinfo | |
181 | ||
182 | @enumerate | |
183 | @item | |
184 | This License Agreement applies to any program or other work which | |
185 | contains a notice placed by the copyright holder saying it may be | |
186 | distributed under the terms of this General Public License. The | |
187 | ``Program'', below, refers to any such program or work, and a ``work based | |
188 | on the Program'' means either the Program or any work containing the | |
189 | Program or a portion of it, either verbatim or with modifications. Each | |
190 | licensee is addressed as ``you''. | |
191 | ||
192 | @item | |
193 | You may copy and distribute verbatim copies of the Program's source | |
194 | code as you receive it, in any medium, provided that you conspicuously and | |
195 | appropriately publish on each copy an appropriate copyright notice and | |
196 | disclaimer of warranty; keep intact all the notices that refer to this | |
197 | General Public License and to the absence of any warranty; and give any | |
198 | other recipients of the Program a copy of this General Public License | |
199 | along with the Program. You may charge a fee for the physical act of | |
200 | transferring a copy. | |
201 | ||
202 | @item | |
203 | You may modify your copy or copies of the Program or any portion of | |
204 | it, and copy and distribute such modifications under the terms of Paragraph | |
205 | 1 above, provided that you also do the following: | |
206 | ||
207 | @itemize @bullet | |
208 | @item | |
209 | cause the modified files to carry prominent notices stating that | |
210 | you changed the files and the date of any change; and | |
211 | ||
212 | @item | |
213 | cause the whole of any work that you distribute or publish, that | |
214 | in whole or in part contains the Program or any part thereof, either | |
215 | with or without modifications, to be licensed at no charge to all | |
216 | third parties under the terms of this General Public License (except | |
217 | that you may choose to grant warranty protection to some or all | |
218 | third parties, at your option). | |
219 | ||
220 | @item | |
221 | If the modified program normally reads commands interactively when | |
222 | run, you must cause it, when started running for such interactive use | |
223 | in the simplest and most usual way, to print or display an | |
224 | announcement including an appropriate copyright notice and a notice | |
225 | that there is no warranty (or else, saying that you provide a | |
226 | warranty) and that users may redistribute the program under these | |
227 | conditions, and telling the user how to view a copy of this General | |
228 | Public License. | |
229 | ||
230 | @item | |
231 | You may charge a fee for the physical act of transferring a | |
232 | copy, and you may at your option offer warranty protection in | |
233 | exchange for a fee. | |
234 | @end itemize | |
235 | ||
236 | Mere aggregation of another independent work with the Program (or its | |
237 | derivative) on a volume of a storage or distribution medium does not bring | |
238 | the other work under the scope of these terms. | |
239 | ||
240 | @item | |
241 | You may copy and distribute the Program (or a portion or derivative of | |
242 | it, under Paragraph 2) in object code or executable form under the terms of | |
243 | Paragraphs 1 and 2 above provided that you also do one of the following: | |
244 | ||
245 | @itemize @bullet | |
246 | @item | |
247 | accompany it with the complete corresponding machine-readable | |
248 | source code, which must be distributed under the terms of | |
249 | Paragraphs 1 and 2 above; or, | |
250 | ||
251 | @item | |
252 | accompany it with a written offer, valid for at least three | |
253 | years, to give any third party free (except for a nominal charge | |
254 | for the cost of distribution) a complete machine-readable copy of the | |
255 | corresponding source code, to be distributed under the terms of | |
256 | Paragraphs 1 and 2 above; or, | |
257 | ||
258 | @item | |
259 | accompany it with the information you received as to where the | |
260 | corresponding source code may be obtained. (This alternative is | |
261 | allowed only for noncommercial distribution and only if you | |
262 | received the program in object code or executable form alone.) | |
263 | @end itemize | |
264 | ||
265 | Source code for a work means the preferred form of the work for making | |
266 | modifications to it. For an executable file, complete source code means | |
267 | all the source code for all modules it contains; but, as a special | |
268 | exception, it need not include source code for modules which are standard | |
269 | libraries that accompany the operating system on which the executable | |
270 | file runs, or for standard header files or definitions files that | |
271 | accompany that operating system. | |
272 | ||
273 | @item | |
274 | You may not copy, modify, sublicense, distribute or transfer the | |
275 | Program except as expressly provided under this General Public License. | |
276 | Any attempt otherwise to copy, modify, sublicense, distribute or transfer | |
277 | the Program is void, and will automatically terminate your rights to use | |
278 | the Program under this License. However, parties who have received | |
279 | copies, or rights to use copies, from you under this General Public | |
280 | License will not have their licenses terminated so long as such parties | |
281 | remain in full compliance. | |
282 | ||
283 | @item | |
284 | By copying, distributing or modifying the Program (or any work based | |
285 | on the Program) you indicate your acceptance of this license to do so, | |
286 | and all its terms and conditions. | |
287 | ||
288 | @item | |
289 | Each time you redistribute the Program (or any work based on the | |
290 | Program), the recipient automatically receives a license from the original | |
291 | licensor to copy, distribute or modify the Program subject to these | |
292 | terms and conditions. You may not impose any further restrictions on the | |
293 | recipients' exercise of the rights granted herein. | |
294 | ||
295 | @item | |
296 | The Free Software Foundation may publish revised and/or new versions | |
297 | of the General Public License from time to time. Such new versions will | |
298 | be similar in spirit to the present version, but may differ in detail to | |
299 | address new problems or concerns. | |
300 | ||
301 | Each version is given a distinguishing version number. If the Program | |
302 | specifies a version number of the license which applies to it and ``any | |
303 | later version'', you have the option of following the terms and conditions | |
304 | either of that version or of any later version published by the Free | |
305 | Software Foundation. If the Program does not specify a version number of | |
306 | the license, you may choose any version ever published by the Free Software | |
307 | Foundation. | |
308 | ||
309 | @item | |
310 | If you wish to incorporate parts of the Program into other free | |
311 | programs whose distribution conditions are different, write to the author | |
312 | to ask for permission. For software which is copyrighted by the Free | |
313 | Software Foundation, write to the Free Software Foundation; we sometimes | |
314 | make exceptions for this. Our decision will be guided by the two goals | |
315 | of preserving the free status of all derivatives of our free software and | |
316 | of promoting the sharing and reuse of software generally. | |
317 | ||
318 | @iftex | |
319 | @heading NO WARRANTY | |
320 | @end iftex | |
321 | @ifinfo | |
322 | @center NO WARRANTY | |
323 | @end ifinfo | |
324 | ||
325 | @item | |
326 | BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | |
327 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN | |
328 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | |
329 | PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED | |
330 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
331 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS | |
332 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE | |
333 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, | |
334 | REPAIR OR CORRECTION. | |
335 | ||
336 | @item | |
337 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL | |
338 | ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | |
339 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | |
340 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES | |
341 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT | |
342 | LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES | |
343 | SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE | |
344 | WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN | |
345 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | |
346 | @end enumerate | |
347 | ||
348 | @iftex | |
349 | @heading END OF TERMS AND CONDITIONS | |
350 | @end iftex | |
351 | @ifinfo | |
352 | @center END OF TERMS AND CONDITIONS | |
353 | @end ifinfo | |
354 | ||
355 | @page | |
356 | @unnumberedsec Appendix: How to Apply These Terms to Your New Programs | |
357 | ||
358 | If you develop a new program, and you want it to be of the greatest | |
359 | possible use to humanity, the best way to achieve this is to make it | |
360 | free software which everyone can redistribute and change under these | |
361 | terms. | |
362 | ||
363 | To do so, attach the following notices to the program. It is safest to | |
364 | attach them to the start of each source file to most effectively convey | |
365 | the exclusion of warranty; and each file should have at least the | |
366 | ``copyright'' line and a pointer to where the full notice is found. | |
367 | ||
368 | @smallexample | |
369 | @var{one line to give the program's name and a brief idea of what it does.} | |
370 | Copyright (C) 19@var{yy} @var{name of author} | |
371 | ||
372 | This program is free software; you can redistribute it and/or modify | |
373 | it under the terms of the GNU General Public License as published by | |
374 | the Free Software Foundation; either version 1, or (at your option) | |
375 | any later version. | |
376 | ||
377 | This program is distributed in the hope that it will be useful, | |
378 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
379 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
380 | GNU General Public License for more details. | |
381 | ||
382 | You should have received a copy of the GNU General Public License | |
383 | along with this program; if not, write to the Free Software | |
384 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
385 | @end smallexample | |
386 | ||
387 | Also add information on how to contact you by electronic and paper mail. | |
388 | ||
389 | If the program is interactive, make it output a short notice like this | |
390 | when it starts in an interactive mode: | |
391 | ||
392 | @smallexample | |
393 | Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} | |
394 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. | |
395 | This is free software, and you are welcome to redistribute it | |
396 | under certain conditions; type `show c' for details. | |
397 | @end smallexample | |
398 | ||
399 | The hypothetical commands `show w' and `show c' should show the | |
400 | appropriate parts of the General Public License. Of course, the | |
401 | commands you use may be called something other than `show w' and `show | |
402 | c'; they could even be mouse-clicks or menu items---whatever suits your | |
403 | program. | |
404 | ||
405 | You should also get your employer (if you work as a programmer) or your | |
406 | school, if any, to sign a ``copyright disclaimer'' for the program, if | |
407 | necessary. Here a sample; alter the names: | |
408 | ||
409 | @example | |
410 | Yoyodyne, Inc., hereby disclaims all copyright interest in the | |
411 | program `Gnomovision' (a program to direct compilers to make passes | |
412 | at assemblers) written by James Hacker. | |
413 | ||
414 | @var{signature of Ty Coon}, 1 April 1989 | |
415 | Ty Coon, President of Vice | |
416 | @end example | |
417 | ||
418 | That's all there is to it! | |
419 | ||
420 | @node User Interface, Files, License, Top | |
421 | @chapter GDB Input and Output Conventions | |
422 | ||
423 | GDB is invoked with the shell command @samp{gdb}. Once started, it reads | |
424 | commands from the terminal until you tell it to exit. | |
425 | ||
426 | A GDB command is a single line of input. There is no limit on how long | |
427 | it can be. It starts with a command name, which is followed by arguments | |
428 | whose meaning depends on the command name. For example, the command | |
429 | @samp{step} accepts an argument which is the number of times to step, | |
430 | as in @samp{step 5}. You can also use the @samp{step} command with | |
431 | no arguments. Some command names do not allow any arguments. | |
432 | ||
433 | @cindex abbreviation | |
434 | GDB command names may always be abbreviated if the abbreviation is | |
435 | unambiguous. Sometimes even ambiguous abbreviations are allowed; for | |
436 | example, @samp{s} is specially defined as equivalent to @samp{step} | |
437 | even though there are other commands whose names start with @samp{s}. | |
438 | Possible command abbreviations are often stated in the documentation | |
439 | of the individual commands. | |
440 | ||
441 | @cindex repeating commands | |
442 | A blank line as input to GDB means to repeat the previous command verbatim. | |
443 | Certain commands do not allow themselves to be repeated this way; these are | |
444 | commands for which unintentional repetition might cause trouble and which | |
445 | you are unlikely to want to repeat. Certain others (@samp{list} and | |
446 | @samp{x}) act differently when repeated because that is more useful. | |
447 | ||
448 | A line of input starting with @samp{#} is a comment; it does nothing. | |
449 | This is useful mainly in command files (@xref{Command Files}). | |
450 | ||
451 | @cindex prompt | |
452 | GDB indicates its readiness to read a command by printing a string | |
453 | called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can | |
454 | change the prompt string with the @samp{set prompt} command. For | |
455 | instance, when debugging GDB with GDB, it is useful to change the prompt | |
456 | in one of the GDBs so that you tell which one you are talking to. | |
457 | ||
458 | @table @code | |
459 | @item set prompt @var{newprompt} | |
460 | @kindex set prompt | |
461 | Directs GDB to use @var{newprompt} as its prompt string henceforth. | |
462 | @end table | |
463 | ||
464 | @cindex exiting GDB | |
465 | @kindex quit | |
466 | To exit GDB, use the @samp{quit} command (abbreviated @samp{q}). | |
467 | @kbd{Ctrl-c} will not exit from GDB, but rather will terminate the action | |
468 | of any GDB command that is in progress and return to GDB command level. | |
469 | It is safe to type @kbd{Ctrl-c} at any time because GDB does not allow | |
470 | it to take effect until a time when it is safe. | |
471 | ||
472 | @cindex screen size | |
473 | @cindex pauses in output | |
474 | Certain commands to GDB may produce large amounts of information output | |
475 | to the screen. To help you read all of it, GDB pauses and asks you for | |
476 | input at the end of each page of output. Type @key{RET} when you want | |
477 | to continue the output. Normally GDB knows the size of the screen from | |
478 | on the termcap data base together with the value of the @code{TERM} | |
479 | environment variable; if this is not correct, you can override it with | |
480 | the @samp{set screensize} command: | |
481 | ||
482 | @table @code | |
483 | @item set screensize @var{lpp} | |
484 | @itemx set screensize @var{lpp} @var{cpl} | |
485 | @kindex set screensize | |
486 | Specify a screen height of @var{lpp} lines and (optionally) a width of | |
487 | @var{cpl} characters. If you omit @var{cpl}, the width does not change. | |
488 | ||
489 | If you specify a height of zero lines, GDB will not pause during output | |
490 | no matter how long the output is. This is useful if output is to a file | |
491 | or to an editor buffer. | |
492 | @end table | |
493 | ||
494 | Also, GDB may at times produce more information about its own workings | |
495 | than is of interest to the user. Some of these informational messages | |
496 | can be turned on and off with the @samp{set verbose} command: | |
497 | ||
498 | @table @code | |
499 | @kindex set verbose | |
500 | @item set verbose off | |
501 | Disables GDB's output of certain informational messages. | |
502 | ||
503 | @item set verbose on | |
504 | Re-enables GDB's output of certain informational messages. | |
505 | @end table | |
506 | ||
507 | Currently, the messages controlled by @samp{set verbose} are those which | |
508 | announce that the symbol table for a source file is being read | |
509 | (@pxref{File Commands}, in the description of the command | |
510 | @samp{symbol-file}). | |
511 | @c The following is the right way to do it, but emacs 18.55 doesn't support | |
512 | @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo | |
513 | @c is released. | |
514 | @ignore | |
515 | see @samp{symbol-file} in @ref{File Commands}). | |
516 | @end ignore | |
517 | ||
518 | @node Files, Compilation, User Interface, Top | |
519 | @chapter Specifying GDB's Files | |
520 | ||
521 | @cindex core dump file | |
522 | @cindex executable file | |
523 | @cindex symbol table | |
524 | GDB needs to know the file name of the program to be debugged, both in | |
525 | order to read its symbol table and in order to start the program. To | |
526 | debug a core dump of a previous run, GDB must be told the file name of | |
527 | the core dump. | |
528 | ||
529 | @menu | |
530 | * Arguments: File Arguments. Specifying files with arguments | |
531 | (when you start GDB). | |
532 | * Commands: File Commands. Specifying files with GDB commands. | |
533 | @end menu | |
534 | ||
535 | @node File Arguments, File Commands, Files, Files | |
536 | @section Specifying Files with Arguments | |
537 | ||
538 | The usual way to specify the executable and core dump file names is with | |
539 | two command arguments given when you start GDB. The first argument is used | |
540 | as the file for execution and symbols, and the second argument (if any) is | |
541 | used as the core dump file name. Thus, | |
542 | ||
543 | @example | |
544 | gdb progm core | |
545 | @end example | |
546 | ||
547 | @noindent | |
548 | specifies @file{progm} as the executable program and @file{core} as a core | |
549 | dump file to examine. (You do not need to have a core dump file if what | |
550 | you plan to do is debug the program interactively.) | |
551 | ||
552 | @xref{Options}, for full information on options and arguments for | |
553 | invoking GDB. | |
554 | ||
555 | @node File Commands,, File Arguments, Files | |
556 | @section Specifying Files with Commands | |
557 | ||
558 | Usually you specify the files for GDB to work with by giving arguments when | |
559 | you invoke GDB. But occasionally it is necessary to change to a different | |
560 | file during a GDB session. Or you may run GDB and forget to specify the | |
561 | files you want to use. In these situations the GDB commands to specify new | |
562 | files are useful. | |
563 | ||
564 | @table @code | |
565 | @item exec-file @var{filename} | |
566 | @kindex exec-file | |
567 | Specify that the program to be run is found in @var{filename}. If you | |
568 | do not specify a directory and the file is not found in GDB's working | |
569 | directory, GDB will use the environment variable @code{PATH} as a list | |
570 | of directories to search, just as the shell does when looking for a | |
571 | program to run. | |
572 | ||
573 | @item symbol-file @var{filename} | |
574 | @kindex symbol-file | |
575 | Read symbol table information from file @var{filename}. @code{PATH} | |
576 | is searched when necessary. Most of the time you will use both the | |
577 | @samp{exec-file} and @samp{symbol-file} commands on the same file. | |
578 | ||
579 | @samp{symbol-file} with no argument clears out GDB's symbol table. | |
580 | ||
581 | The @samp{symbol-file} command does not actually read the symbol table in | |
582 | full right away. Instead, it scans the symbol table quickly to find | |
583 | which source files and which symbols are present. The details are read | |
584 | later, one source file at a time, when they are needed. | |
585 | ||
586 | The purpose of this two-stage reading strategy is to make GDB start up | |
587 | faster. For the most part, it is invisible except for occasional | |
588 | messages telling you that the symbol table details for a particular | |
589 | source file are being read. (The @samp{set verbose} command controls | |
590 | whether these messages are printed; @pxref{User Interface}). | |
591 | ||
592 | However, you will sometimes see in backtraces lines for functions in | |
593 | source files whose data has not been read in; these lines omit some of | |
594 | the information, such as argument values, which cannot be printed | |
595 | without full details of the symbol table. | |
596 | ||
597 | When the symbol table is stored in COFF format, @samp{symbol-file} does | |
598 | read the symbol table data in full right away. We haven't bothered to | |
599 | implement the two-stage strategy for COFF. | |
600 | ||
601 | @item core-file @var{filename} | |
602 | @kindex core-file | |
603 | Specify the whereabouts of a core dump file to be used as the | |
604 | ``contents of memory''. Note that the core dump contains only the | |
605 | writable parts of memory; the read-only parts must come from the | |
606 | executable file. | |
607 | ||
608 | @samp{core-file} with no argument specifies that no core file is | |
609 | to be used. | |
610 | ||
611 | Note that the core file is ignored when your program is actually running | |
612 | under GDB. So, if you have been running the program and you wish to | |
613 | debug a core file instead, you must kill the subprocess in which the | |
614 | program is running. To do this, use the @samp{kill} command | |
615 | (@pxref{Kill Process}). | |
616 | ||
617 | @item add-file @var{filename} @var{address} | |
618 | @kindex add-file | |
619 | @cindex dynamic linking | |
620 | The @samp{add-file} command reads additional symbol table information | |
621 | from the file @var{filename}. You would use this when that file has | |
622 | been dynamically loaded into the program that is running. @var{address} | |
623 | should be the memory address at which the file has been loaded; GDB cannot | |
624 | figure this out for itself. | |
625 | ||
626 | The symbol table of the file @var{filename} is added to the symbol table | |
627 | originally read with the @samp{symbol-file} command. You can use the | |
628 | @samp{add-file} command any number of times; the new symbol data thus | |
629 | read keeps adding to the old. The @samp{symbol-file} command forgets | |
630 | all the symbol data GDB has read; that is the only time symbol data is | |
631 | forgotten in GDB. | |
632 | ||
633 | @item info files | |
634 | @kindex info files | |
635 | Print the names of the executable and core dump files currently in | |
636 | use by GDB, and the file from which symbols were loaded. | |
637 | @end table | |
638 | ||
639 | While all three file-specifying commands allow both absolute and relative | |
640 | file names as arguments, GDB always converts the file name to an absolute | |
641 | one and remembers it that way. | |
642 | ||
643 | The @samp{symbol-file} command causes GDB to forget the contents of its | |
644 | convenience variables, the value history, and all breakpoints and | |
645 | auto-display expressions. This is because they may contain pointers to the | |
646 | internal data recording symbols and data types, which are part of the old | |
647 | symbol table data being discarded inside GDB. | |
648 | ||
649 | @node Compilation, Running, Files, Top | |
650 | @chapter Compiling Your Program for Debugging | |
651 | ||
652 | In order to debug a program effectively, you need to ask for debugging | |
653 | information when you compile it. This information in the object file | |
654 | describes the data type of each variable or function and the correspondence | |
655 | between source line numbers and addresses in the executable code. | |
656 | ||
657 | To request debugging information, specify the @samp{-g} option when you run | |
658 | the compiler. | |
659 | ||
660 | The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options | |
661 | together. This means that you cannot ask for optimization if you ask for | |
662 | debugger information. | |
663 | ||
664 | The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it | |
665 | possible to debug optimized code. We recommend that you @emph{always} use | |
666 | @samp{-g} whenever you compile a program. You may think the program is | |
667 | correct, but there's no sense in pushing your luck. | |
668 | ||
669 | GDB no longer supports the debugging information produced by giving the | |
670 | GNU C compiler the @samp{-gg} option, so do not use this option. | |
671 | ||
672 | @ignore | |
673 | @comment As far as I know, there are no cases in which GDB will | |
674 | @comment produce strange output in this case. (but no promises). | |
675 | If your program includes archives made with the @code{ar} program, and | |
676 | if the object files used as input to @code{ar} were compiled without the | |
677 | @samp{-g} option and have names longer than 15 characters, GDB will get | |
678 | confused reading the program's symbol table. No error message will be | |
679 | given, but GDB may behave strangely. The reason for this problem is a | |
680 | deficiency in the Unix archive file format, which cannot represent file | |
681 | names longer than 15 characters. | |
682 | ||
683 | To avoid this problem, compile the archive members with the @samp{-g} | |
684 | option or use shorter file names. Alternatively, use a version of GNU | |
685 | @code{ar} dated more recently than August 1989. | |
686 | @end ignore | |
687 | ||
688 | @node Running, Stopping, Compilation, Top | |
689 | @chapter Running Your Program Under GDB | |
690 | ||
691 | @cindex running | |
692 | @kindex run | |
693 | To start your program under GDB, use the @samp{run} command. The program | |
694 | must already have been specified using the @samp{exec-file} command or with | |
695 | an argument to GDB (@pxref{Files}); what @samp{run} does is create an | |
696 | inferior process, load the program into it, and set it in motion. | |
697 | ||
698 | The execution of a program is affected by certain information it | |
699 | receives from its superior. GDB provides ways to specify this | |
700 | information, which you must do @i{before} starting the program. (You | |
701 | can change it after starting the program, but such changes do not affect | |
702 | the program unless you start it over again.) This information may be | |
703 | divided into three categories: | |
704 | ||
705 | @table @asis | |
706 | @item The @i{arguments.} | |
707 | You specify the arguments to give the program as the arguments of the | |
708 | @samp{run} command. | |
709 | ||
710 | @item The @i{environment.} | |
711 | The program normally inherits its environment from GDB, but you can | |
712 | use the GDB commands @samp{set environment} and | |
713 | @samp{unset environment} to change parts of the environment that will | |
714 | be given to the program.@refill | |
715 | ||
716 | @item The @i{working directory.} | |
717 | The program inherits its working directory from GDB. You can set GDB's | |
718 | working directory with the @samp{cd} command in GDB. | |
719 | @end table | |
720 | ||
721 | After the @samp{run} command, the debugger does nothing but wait for your | |
722 | program to stop. @xref{Stopping}. | |
723 | ||
724 | Note that once your program has been started by the @samp{run} command, | |
725 | you may evaluate expressions that involve calls to functions in the | |
726 | inferior. @xref{Expressions}. If you wish to evaluate a function | |
727 | simply for its side affects, you may use the @samp{set} command. | |
728 | @xref{Assignment}. | |
729 | ||
730 | @menu | |
731 | * Arguments:: Specifying the arguments for your program. | |
732 | * Environment:: Specifying the environment for your program. | |
733 | * Working Directory:: Specifying the working directory for giving | |
734 | to your program when it is run. | |
735 | * Input/Output:: Specifying the program's standard input and output. | |
736 | * Attach:: Debugging a process started outside GDB. | |
737 | * Kill Process:: Getting rid of the child process running your program. | |
738 | @end menu | |
739 | ||
740 | @node Arguments, Environment, Running, Running | |
741 | @section Your Program's Arguments | |
742 | ||
743 | @cindex arguments (to your program) | |
744 | The arguments to your program are specified by the arguments of the | |
745 | @samp{run} command. They are passed to a shell, which expands wildcard | |
746 | characters and performs redirection of I/O, and thence to the program. | |
747 | ||
748 | @samp{run} with no arguments uses the same arguments used by the previous | |
749 | @samp{run}. | |
750 | ||
751 | @kindex set args | |
752 | The command @samp{set args} can be used to specify the arguments to be used | |
753 | the next time the program is run. If @samp{set args} has no arguments, it | |
754 | means to use no arguments the next time the program is run. If you have | |
755 | run your program with arguments and want to run it again with no arguments, | |
756 | this is the only way to do so. | |
757 | ||
758 | @node Environment, Working Directory, Arguments, Running | |
759 | @section Your Program's Environment | |
760 | ||
761 | @cindex environment (of your program) | |
762 | The @dfn{environment} consists of a set of @dfn{environment variables} and | |
763 | their values. Environment variables conventionally record such things as | |
764 | your user name, your home directory, your terminal type, and your search | |
765 | path for programs to run. Usually you set up environment variables with | |
766 | the shell and they are inherited by all the other programs you run. When | |
767 | debugging, it can be useful to try running the program with different | |
768 | environments without having to start the debugger over again. | |
769 | ||
770 | @table @code | |
771 | @item info environment @var{varname} | |
772 | @kindex info environment | |
773 | Print the value of environment variable @var{varname} to be given to | |
774 | your program when it is started. This command can be abbreviated | |
775 | @samp{i env @var{varname}}. | |
776 | ||
777 | @item info environment | |
778 | Print the names and values of all environment variables to be given to | |
779 | your program when it is started. This command can be abbreviated | |
780 | @samp{i env}. | |
781 | ||
782 | @item set environment @var{varname} @var{value} | |
783 | @itemx set environment @var{varname} = @var{value} | |
784 | @kindex set environment | |
785 | Sets environment variable @var{varname} to @var{value}, for your program | |
786 | only, not for GDB itself. @var{value} may be any string; the values of | |
787 | environment variables are just strings, and any interpretation is | |
788 | supplied by your program itself. The @var{value} parameter is optional; | |
789 | if it is eliminated, the variable is set to a null value. This command | |
790 | can be abbreviated as short as @samp{set e}. | |
791 | ||
792 | For example, this command: | |
793 | ||
794 | @example | |
795 | set env USER = foo | |
796 | @end example | |
797 | ||
798 | @noindent | |
799 | tells the program, when subsequently run, to assume it is being run | |
800 | on behalf of the user named @samp{foo}. | |
801 | ||
802 | @item delete environment @var{varname} | |
803 | @itemx unset environment @var{varname} | |
804 | @kindex delete environment | |
805 | @kindex unset environment | |
806 | Remove variable @var{varname} from the environment to be passed to your | |
807 | program. This is different from @samp{set env @var{varname}@ =} because | |
808 | @samp{delete environment} leaves the variable with no value, which is | |
809 | distinguishable from an empty value. This command can be abbreviated | |
810 | @samp{d e}. | |
811 | @end table | |
812 | ||
813 | @node Working Directory, Input/Output, Environment, Running | |
814 | @section Your Program's Working Directory | |
815 | ||
816 | @cindex working directory (of your program) | |
817 | Each time you start your program with @samp{run}, it inherits its | |
818 | working directory from the current working directory of GDB. GDB's | |
819 | working directory is initially whatever it inherited from its parent | |
820 | process (typically the shell), but you can specify a new working | |
821 | directory in GDB with the @samp{cd} command. | |
822 | ||
823 | The GDB working directory also serves as a default for the commands | |
824 | that specify files for GDB to operate on. @xref{Files}. | |
825 | ||
826 | @table @code | |
827 | @item cd @var{directory} | |
828 | @kindex cd | |
829 | Set GDB's working directory to @var{directory}. | |
830 | ||
831 | @item pwd | |
832 | @kindex pwd | |
833 | Print GDB's working directory. | |
834 | @end table | |
835 | ||
836 | @node Input/Output, Attach, Working Directory, Running | |
837 | @section Your Program's Input and Output | |
838 | ||
839 | @cindex redirection | |
840 | @cindex controlling terminal | |
841 | By default, the program you run under GDB does input and output to the same | |
842 | terminal that GDB uses. | |
843 | ||
844 | You can redirect the program's input and/or output using @samp{sh}-style | |
845 | redirection commands in the @samp{run} command. For example, | |
846 | ||
847 | @example | |
848 | run > outfile | |
849 | @end example | |
850 | ||
851 | @noindent | |
852 | starts the program, diverting its output to the file @file{outfile}. | |
853 | ||
854 | @kindex tty | |
855 | Another way to specify where the program should do input and output is | |
856 | with the @samp{tty} command. This command accepts a file name as | |
857 | argument, and causes this file to be the default for future @samp{run} | |
858 | commands. It also resets the controlling terminal for the child | |
859 | process, for future @samp{run} commands. For example, | |
860 | ||
861 | @example | |
862 | tty /dev/ttyb | |
863 | @end example | |
864 | ||
865 | @noindent | |
866 | directs that processes started with subsequent @samp{run} commands | |
867 | default to do input and output on the terminal @file{/dev/ttyb} and have | |
868 | that as their controlling terminal. | |
869 | ||
870 | An explicit redirection in @samp{run} overrides the @samp{tty} command's | |
871 | effect on input/output redirection, but not its effect on the | |
872 | controlling terminal. | |
873 | ||
874 | When you use the @samp{tty} command or redirect input in the @samp{run} | |
875 | command, only the @emph{input for your program} is affected. The input | |
876 | for GDB still comes from your terminal. | |
877 | ||
878 | @node Attach, Kill Process, Input/Output, Running | |
879 | @section Debugging an Already-Running Process | |
880 | @kindex detach | |
881 | @kindex attach | |
882 | @cindex attach | |
883 | ||
884 | Some operating systems allow GDB to debug an already-running process | |
885 | that was started outside of GDB. To do this, you use the @samp{attach} | |
886 | command instead of the @samp{run} command. | |
887 | ||
888 | The @samp{attach} command requires one argument, which is the process-id | |
889 | of the process you want to debug. (The usual way to find out the | |
890 | process-id of the process is with the @code{ps} utility.) | |
891 | ||
892 | The first thing GDB does after arranging to debug the process is to stop | |
893 | it. You can examine and modify an attached process with all the GDB | |
894 | commands that ordinarily available when you start processes with | |
895 | @samp{run}. You can insert breakpoints; you can step and continue; you | |
896 | can modify storage. If you would rather the process continue running, | |
897 | you may use the @samp{continue} command after attaching GDB to the | |
898 | process. | |
899 | ||
900 | When you have finished debugging the attached process, you can use the | |
901 | @samp{detach} command to release it from GDB's control. Detaching | |
902 | the process continues its execution. After the @samp{detach} command, | |
903 | that process and GDB become completely independent once more, and you | |
904 | are ready to @samp{attach} another process or start one with @samp{run}. | |
905 | ||
906 | If you exit GDB or use the @samp{run} command while you have an attached | |
907 | process, you kill that process. You will be asked for confirmation if you | |
908 | try to do either of these things. | |
909 | ||
910 | The @samp{attach} command is also used to debug a remote machine via a | |
911 | serial connection. @xref{Attach}, for more info. | |
912 | ||
913 | @node Kill Process,, Attach, Running | |
914 | @section Killing the Child Process | |
915 | ||
916 | @table @code | |
917 | @item kill | |
918 | @kindex kill | |
919 | Kill the child process in which the program being debugged is running | |
920 | under GDB. | |
921 | ||
922 | This command is useful if you wish to debug a core dump instead. GDB | |
923 | ignores any core dump file if it is actually running the program, so the | |
924 | @samp{kill} command is the only sure way to make sure the core dump file | |
925 | is used once again. | |
926 | ||
927 | It is also useful if you wish to run the program outside the debugger | |
928 | for once and then go back to debugging it. | |
929 | ||
930 | The @samp{kill} command is also useful if you wish to recompile and | |
931 | relink the program, since on many systems it is impossible to modify an | |
932 | executable file which is running in a process. But, in this case, it is | |
933 | just as good to exit GDB, since you will need to read a new symbol table | |
934 | after the program is recompiled if you wish to debug the new version, | |
935 | and restarting GDB is the easiest way to do that. | |
936 | @end table | |
937 | ||
938 | @node Stopping, Stack, Running, Top | |
939 | @chapter Stopping and Continuing | |
940 | ||
941 | When you run a program normally, it runs until it terminates. The | |
942 | principal purpose of using a debugger is so that you can stop it before | |
943 | that point; or so that if the program runs into trouble you can | |
944 | investigate and find out why. | |
945 | ||
946 | @menu | |
947 | * Signals:: Fatal signals in your program just stop it; | |
948 | then you can use GDB to see what is going on. | |
949 | * Breakpoints:: Breakpoints let you stop your program when it | |
950 | reaches a specified point in the code. | |
951 | * Continuing:: Resuming execution until the next signal or breakpoint. | |
952 | * Stepping:: Stepping runs the program a short distance and | |
953 | then stops it wherever it has come to. | |
954 | @end menu | |
955 | ||
956 | @node Signals, Breakpoints, Stopping, Stopping | |
957 | @section Signals | |
958 | @cindex signals | |
959 | ||
960 | A signal is an asynchronous event that can happen in a program. The | |
961 | operating system defines the possible kinds of signals, and gives each kind | |
962 | a name and a number. For example, @code{SIGINT} is the signal a program | |
963 | gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program | |
964 | gets from referencing a place in memory far away from all the areas in use; | |
965 | @code{SIGALRM} occurs when the alarm clock timer goes off (which happens | |
966 | only if the program has requested an alarm). | |
967 | ||
968 | @cindex fatal signals | |
969 | Some signals, including @code{SIGALRM}, are a normal part of the | |
970 | functioning of the program. Others, such as @code{SIGSEGV}, indicate | |
971 | errors; these signals are @dfn{fatal} (kill the program immediately) if the | |
972 | program has not specified in advance some other way to handle the signal. | |
973 | @code{SIGINT} does not indicate an error in the program, but it is normally | |
974 | fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program. | |
975 | ||
976 | GDB has the ability to detect any occurrence of a signal in the program | |
977 | running under GDB's control. You can tell GDB in advance what to do for | |
978 | each kind of signal. | |
979 | ||
980 | @cindex handling signals | |
981 | Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM} | |
982 | (so as not to interfere with their role in the functioning of the program) | |
983 | but to stop the program immediately whenever an error signal happens. | |
984 | You can change these settings with the @samp{handle} command. You must | |
985 | specify which signal you are talking about with its number. | |
986 | ||
987 | @table @code | |
988 | @item info signal | |
989 | @kindex info signal | |
990 | Print a table of all the kinds of signals and how GDB has been told to | |
991 | handle each one. You can use this to see the signal numbers of all | |
992 | the defined types of signals. | |
993 | ||
994 | @item handle @var{signalnum} @var{keywords}@dots{} | |
995 | @kindex handle | |
996 | Change the way GDB handles signal @var{signalnum}. The @var{keywords} | |
997 | say what change to make. | |
998 | @end table | |
999 | ||
1000 | To use the @samp{handle} command you must know the code number of the | |
1001 | signal you are concerned with. To find the code number, type @samp{info | |
1002 | signal} which prints a table of signal names and numbers. | |
1003 | ||
1004 | The keywords allowed by the handle command can be abbreviated. Their full | |
1005 | names are | |
1006 | ||
1007 | @table @code | |
1008 | @item stop | |
1009 | GDB should stop the program when this signal happens. This implies | |
1010 | the @samp{print} keyword as well. | |
1011 | ||
1012 | @item print | |
1013 | GDB should print a message when this signal happens. | |
1014 | ||
1015 | @item nostop | |
1016 | GDB should not stop the program when this signal happens. It may | |
1017 | still print a message telling you that the signal has come in. | |
1018 | ||
1019 | @item noprint | |
1020 | GDB should not mention the occurrence of the signal at all. This | |
1021 | implies the @samp{nostop} keyword as well. | |
1022 | ||
1023 | @item pass | |
1024 | GDB should allow the program to see this signal; the program will be | |
1025 | able to handle the signal, or may be terminated if the signal is fatal | |
1026 | and not handled. | |
1027 | ||
1028 | @item nopass | |
1029 | GDB should not allow the program to see this signal. | |
1030 | @end table | |
1031 | ||
1032 | When a signal has been set to stop the program, the program cannot see the | |
1033 | signal until you continue. It will see the signal then, if @samp{pass} is | |
1034 | in effect for the signal in question @i{at that time}. In other words, | |
1035 | after GDB reports a signal, you can use the @samp{handle} command with | |
1036 | @samp{pass} or @samp{nopass} to control whether that signal will be seen by | |
1037 | the program when you later continue it. | |
1038 | ||
1039 | You can also use the @samp{signal} command to prevent the program from | |
1040 | seeing a signal, or cause it to see a signal it normally would not see, | |
1041 | or to give it any signal at any time. @xref{Signaling}. | |
1042 | ||
1043 | @node Breakpoints, Continuing, Signals, Stopping | |
1044 | @section Breakpoints | |
1045 | ||
1046 | @cindex breakpoints | |
1047 | A @dfn{breakpoint} makes your program stop whenever a certain point in the | |
1048 | program is reached. You set breakpoints explicitly with GDB commands, | |
1049 | specifying the place where the program should stop by line number, function | |
1050 | name or exact address in the program. You can add various other conditions | |
1051 | to control whether the program will stop. | |
1052 | ||
1053 | Each breakpoint is assigned a number when it is created; these numbers are | |
1054 | successive integers starting with 1. In many of the commands for controlling | |
1055 | various features of breakpoints you use the breakpoint number to say which | |
1056 | breakpoint you want to change. Each breakpoint may be @dfn{enabled} or | |
1057 | @dfn{disabled}; if disabled, it has no effect on the program until you | |
1058 | enable it again. | |
1059 | ||
1060 | @kindex info break | |
1061 | @kindex $_ | |
1062 | The command @samp{info break} prints a list of all breakpoints set and not | |
1063 | deleted, showing their numbers, where in the program they are, and any | |
1064 | special features in use for them. Disabled breakpoints are included in the | |
1065 | list, but marked as disabled. @samp{info break} with a breakpoint number | |
1066 | as argument lists only that breakpoint. The convenience variable @code{$_} | |
1067 | and the default examining-address for the @samp{x} command are set to the | |
1068 | address of the last breakpoint listed (@pxref{Memory}). | |
1069 | ||
1070 | @menu | |
1071 | * Set Breaks:: How to establish breakpoints. | |
1072 | * Delete Breaks:: How to remove breakpoints no longer needed. | |
1073 | * Disabling:: How to disable breakpoints (turn them off temporarily). | |
1074 | * Conditions:: Making extra conditions on whether to stop. | |
1075 | * Break Commands:: Commands to be executed at a breakpoint. | |
1076 | * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do. | |
1077 | @end menu | |
1078 | ||
1079 | @node Set Breaks, Delete Breaks, Breakpoints, Breakpoints | |
1080 | @subsection Setting Breakpoints | |
1081 | ||
1082 | @kindex break | |
1083 | Breakpoints are set with the @samp{break} command (abbreviated @samp{b}). | |
1084 | You have several ways to say where the breakpoint should go. | |
1085 | ||
1086 | @table @code | |
1087 | @item break @var{function} | |
1088 | Set a breakpoint at entry to function @var{function}. | |
1089 | ||
1090 | @item break @var{+offset} | |
1091 | @itemx break @var{-offset} | |
1092 | Set a breakpoint some number of lines forward or back from the position | |
1093 | at which execution stopped in the currently selected frame. | |
1094 | ||
1095 | @item break @var{linenum} | |
1096 | Set a breakpoint at line @var{linenum} in the current source file. | |
1097 | That file is the last file whose source text was printed. This | |
1098 | breakpoint will stop the program just before it executes any of the | |
1099 | code on that line. | |
1100 | ||
1101 | @item break @var{filename}:@var{linenum} | |
1102 | Set a breakpoint at line @var{linenum} in source file @var{filename}. | |
1103 | ||
1104 | @item break @var{filename}:@var{function} | |
1105 | Set a breakpoint at entry to function @var{function} found in file | |
1106 | @var{filename}. Specifying a file name as well as a function name is | |
1107 | superfluous except when multiple files contain similarly named | |
1108 | functions. | |
1109 | ||
1110 | @item break *@var{address} | |
1111 | Set a breakpoint at address @var{address}. You can use this to set | |
1112 | breakpoints in parts of the program which do not have debugging | |
1113 | information or source files. | |
1114 | ||
1115 | @item break | |
1116 | Set a breakpoint at the next instruction to be executed in the selected | |
1117 | stack frame (@pxref{Stack}). In any selected frame but the innermost, | |
1118 | this will cause the program to stop as soon as control returns to that | |
1119 | frame. This is equivalent to a @samp{finish} command in the frame | |
1120 | inside the selected frame. If this is done in the innermost frame, GDB | |
1121 | will stop the next time it reaches the current location; this may be | |
1122 | useful inside of loops. | |
1123 | ||
1124 | GDB normally ignores breakpoints when it resumes execution, until at | |
1125 | least one instruction has been executed. If it did not do this, you | |
1126 | would be unable to proceed past a breakpoint without first disabling the | |
1127 | breakpoint. This rule applies whether or not the breakpoint already | |
1128 | existed when the program stopped. | |
1129 | ||
1130 | @item break @dots{} if @var{cond} | |
1131 | Set a breakpoint with condition @var{cond}; evaluate the expression | |
1132 | @var{cond} each time the breakpoint is reached, and stop only if the | |
1133 | value is nonzero. @samp{@dots{}} stands for one of the possible | |
1134 | arguments described above (or no argument) specifying where to break. | |
1135 | @xref{Conditions}, for more information on breakpoint conditions. | |
1136 | ||
1137 | @item tbreak @var{args} | |
1138 | @kindex tbreak | |
1139 | Set a breakpoint enabled only for one stop. @var{args} are the | |
1140 | same as in the @samp{break} command, and the breakpoint is set in the same | |
1141 | way, but the breakpoint is automatically disabled the first time it | |
1142 | is hit. @xref{Disabling}. | |
1143 | @end table | |
1144 | ||
1145 | GDB allows you to set any number of breakpoints at the same place in the | |
1146 | program. There is nothing silly or meaningless about this. When the | |
1147 | breakpoints are conditional, this is even useful (@pxref{Conditions}). | |
1148 | ||
1149 | @node Delete Breaks, Disabling, Set Breaks, Breakpoints | |
1150 | @subsection Deleting Breakpoints | |
1151 | ||
1152 | @cindex clearing breakpoint | |
1153 | @cindex deleting breakpoints | |
1154 | It is often necessary to eliminate a breakpoint once it has done its job | |
1155 | and you no longer want the program to stop there. This is called | |
1156 | @dfn{deleting} the breakpoint. A breakpoint that has been deleted no | |
1157 | longer exists in any sense; it is forgotten. | |
1158 | ||
1159 | With the @samp{clear} command you can delete breakpoints according to where | |
1160 | they are in the program. With the @samp{delete} command you can delete | |
1161 | individual breakpoints by specifying their breakpoint numbers. | |
1162 | ||
1163 | @b{It is not necessary to delete a breakpoint to proceed past it.} GDB | |
1164 | automatically ignores breakpoints in the first instruction to be executed | |
1165 | when you continue execution without changing the execution address. | |
1166 | ||
1167 | @table @code | |
1168 | @item clear | |
1169 | @kindex clear | |
1170 | Delete any breakpoints at the next instruction to be executed in the | |
1171 | selected stack frame (@pxref{Selection}). When the innermost frame | |
1172 | is selected, this is a good way to delete a breakpoint that the program | |
1173 | just stopped at. | |
1174 | ||
1175 | @item clear @var{function} | |
1176 | @itemx clear @var{filename}:@var{function} | |
1177 | Delete any breakpoints set at entry to the function @var{function}. | |
1178 | ||
1179 | @item clear @var{linenum} | |
1180 | @itemx clear @var{filename}:@var{linenum} | |
1181 | Delete any breakpoints set at or within the code of the specified line. | |
1182 | ||
1183 | @item delete @var{bnums}@dots{} | |
1184 | @kindex delete | |
1185 | Delete the breakpoints of the numbers specified as arguments. | |
1186 | @end table | |
1187 | ||
1188 | @node Disabling, Conditions, Delete Breaks, Breakpoints | |
1189 | @subsection Disabling Breakpoints | |
1190 | ||
1191 | @cindex disabled breakpoints | |
1192 | @cindex enabled breakpoints | |
1193 | Rather than deleting a breakpoint, you might prefer to @dfn{disable} it. | |
1194 | This makes the breakpoint inoperative as if it had been deleted, but | |
1195 | remembers the information on the breakpoint so that you can @dfn{enable} | |
1196 | it again later. | |
1197 | ||
1198 | You disable and enable breakpoints with the @samp{enable} and | |
1199 | @samp{disable} commands, specifying one or more breakpoint numbers as | |
1200 | arguments. Use @samp{info break} to print a list of breakpoints if you | |
1201 | don't know which breakpoint numbers to use. | |
1202 | ||
1203 | A breakpoint can have any of four different states of enablement: | |
1204 | ||
1205 | @itemize @bullet | |
1206 | @item | |
1207 | Enabled. The breakpoint will stop the program. A breakpoint made | |
1208 | with the @samp{break} command starts out in this state. | |
1209 | @item | |
1210 | Disabled. The breakpoint has no effect on the program. | |
1211 | @item | |
1212 | Enabled once. The breakpoint will stop the program, but | |
1213 | when it does so it will become disabled. A breakpoint made | |
1214 | with the @samp{tbreak} command starts out in this state. | |
1215 | @item | |
1216 | Enabled for deletion. The breakpoint will stop the program, but | |
1217 | immediately after it does so it will be deleted permanently. | |
1218 | @end itemize | |
1219 | ||
1220 | You change the state of enablement of a breakpoint with the following | |
1221 | commands: | |
1222 | ||
1223 | @table @code | |
1224 | @item disable breakpoints @var{bnums}@dots{} | |
1225 | @itemx disable @var{bnums}@dots{} | |
1226 | @kindex disable breakpoints | |
1227 | @kindex disable | |
1228 | Disable the specified breakpoints. A disabled breakpoint has no | |
1229 | effect but is not forgotten. All options such as ignore-counts, | |
1230 | conditions and commands are remembered in case the breakpoint is | |
1231 | enabled again later. | |
1232 | ||
1233 | @item enable breakpoints @var{bnums}@dots{} | |
1234 | @itemx enable @var{bnums}@dots{} | |
1235 | @kindex enable breakpoints | |
1236 | @kindex enable | |
1237 | Enable the specified breakpoints. They become effective once again in | |
1238 | stopping the program, until you specify otherwise. | |
1239 | ||
1240 | @item enable breakpoints once @var{bnums}@dots{} | |
1241 | @itemx enable once @var{bnums}@dots{} | |
1242 | Enable the specified breakpoints temporarily. Each will be disabled | |
1243 | again the next time it stops the program (unless you have used one of | |
1244 | these commands to specify a different state before that time comes). | |
1245 | ||
1246 | @item enable breakpoints delete @var{bnums}@dots{} | |
1247 | @itemx enable delete @var{bnums}@dots{} | |
1248 | Enable the specified breakpoints to work once and then die. Each of | |
1249 | the breakpoints will be deleted the next time it stops the program | |
1250 | (unless you have used one of these commands to specify a different | |
1251 | state before that time comes). | |
1252 | @end table | |
1253 | ||
1254 | Aside from the automatic disablement or deletion of a breakpoint when it | |
1255 | stops the program, which happens only in certain states, the state of | |
1256 | enablement of a breakpoint changes only when one of the commands above | |
1257 | is used. | |
1258 | ||
1259 | @node Conditions, Break Commands, Disabling, Breakpoints | |
1260 | @subsection Break Conditions | |
1261 | @cindex conditional breakpoints | |
1262 | @cindex breakpoint conditions | |
1263 | ||
1264 | The simplest sort of breakpoint breaks every time the program reaches a | |
1265 | specified place. You can also specify a @dfn{condition} for a | |
1266 | breakpoint. A condition is just a boolean expression in your | |
1267 | programming language. (@xref{Expressions}). A breakpoint with a | |
1268 | condition evaluates the expression each time the program reaches it, and | |
1269 | the program stops only if the condition is true. | |
1270 | ||
1271 | Break conditions may have side effects, and may even call functions in your | |
1272 | program. These may sound like strange things to do, but their effects are | |
1273 | completely predictable unless there is another enabled breakpoint at the | |
1274 | same address. (In that case, GDB might see the other breakpoint first and | |
1275 | stop the program without checking the condition of this one.) Note that | |
1276 | breakpoint commands are usually more convenient and flexible for the | |
1277 | purpose of performing side effects when a breakpoint is reached | |
1278 | (@pxref{Break Commands}). | |
1279 | ||
1280 | Break conditions can be specified when a breakpoint is set, by using | |
1281 | @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}. | |
1282 | They can also be changed at any time with the @samp{condition} command: | |
1283 | ||
1284 | @table @code | |
1285 | @item condition @var{bnum} @var{expression} | |
1286 | @kindex condition | |
1287 | Specify @var{expression} as the break condition for breakpoint number | |
1288 | @var{bnum}. From now on, this breakpoint will stop the program only if | |
1289 | the value of @var{expression} is true (nonzero, in C). @var{expression} | |
1290 | is not evaluated at the time the @samp{condition} command is given. | |
1291 | @xref{Expressions}. | |
1292 | ||
1293 | @item condition @var{bnum} | |
1294 | Remove the condition from breakpoint number @var{bnum}. It becomes | |
1295 | an ordinary unconditional breakpoint. | |
1296 | @end table | |
1297 | ||
1298 | @cindex ignore count (of breakpoint) | |
1299 | A special case of a breakpoint condition is to stop only when the | |
1300 | breakpoint has been reached a certain number of times. This is so | |
1301 | useful that there is a special way to do it, using the @dfn{ignore | |
1302 | count} of the breakpoint. Every breakpoint has an ignore count, which | |
1303 | is an integer. Most of the time, the ignore count is zero, and | |
1304 | therefore has no effect. But if the program reaches a breakpoint whose | |
1305 | ignore count is positive, then instead of stopping, it just decrements | |
1306 | the ignore count by one and continues. As a result, if the ignore count | |
1307 | value is @var{n}, the breakpoint will not stop the next @var{n} times it | |
1308 | is reached. | |
1309 | ||
1310 | @table @code | |
1311 | @item ignore @var{bnum} @var{count} | |
1312 | @kindex ignore | |
1313 | Set the ignore count of breakpoint number @var{bnum} to @var{count}. | |
1314 | The next @var{count} times the breakpoint is reached, it will not stop. | |
1315 | ||
1316 | To make the breakpoint stop the next time it is reached, specify | |
1317 | a count of zero. | |
1318 | ||
1319 | @item cont @var{count} | |
1320 | Continue execution of the program, setting the ignore count of the | |
1321 | breakpoint that the program stopped at to @var{count} minus one. | |
1322 | Thus, the program will not stop at this breakpoint until the | |
1323 | @var{count}'th time it is reached. | |
1324 | ||
1325 | This command is allowed only when the program stopped due to a | |
1326 | breakpoint. At other times, the argument to @samp{cont} is ignored. | |
1327 | @end table | |
1328 | ||
1329 | If a breakpoint has a positive ignore count and a condition, the condition | |
1330 | is not checked. Once the ignore count reaches zero, the condition will | |
1331 | start to be checked. | |
1332 | ||
1333 | Note that you could achieve the effect of the ignore count with a | |
1334 | condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience | |
1335 | variable that is decremented each time. @xref{Convenience Vars}. | |
1336 | ||
1337 | @node Break Commands, Error in Breakpoints, Conditions, Breakpoints | |
1338 | @subsection Commands Executed on Breaking | |
1339 | ||
1340 | @cindex breakpoint commands | |
1341 | You can give any breakpoint a series of commands to execute when the | |
1342 | program stops due to that breakpoint. For example, you might want to | |
1343 | print the values of certain expressions, or enable other breakpoints. | |
1344 | ||
1345 | @table @code | |
1346 | @item commands @var{bnum} | |
1347 | Specify commands for breakpoint number @var{bnum}. The commands | |
1348 | themselves appear on the following lines. Type a line containing just | |
1349 | @samp{end} to terminate the commands. | |
1350 | ||
1351 | To remove all commands from a breakpoint, use the command | |
1352 | @samp{commands} and follow it immediately by @samp{end}; that is, give | |
1353 | no commands. | |
1354 | ||
1355 | With no arguments, @samp{commands} refers to the last breakpoint set. | |
1356 | @end table | |
1357 | ||
1358 | It is possible for breakpoint commands to start the program up again. | |
1359 | Simply use the @samp{cont} command, or @samp{step}, or any other command | |
1360 | to resume execution. However, any remaining breakpoint commands are | |
1361 | ignored. When the program stops again, GDB will act according to the | |
1362 | cause of that stop. | |
1363 | ||
1364 | @kindex silent | |
1365 | If the first command specified is @samp{silent}, the usual message about | |
1366 | stopping at a breakpoint is not printed. This may be desirable for | |
1367 | breakpoints that are to print a specific message and then continue. | |
1368 | If the remaining commands too print nothing, you will see no sign that | |
1369 | the breakpoint was reached at all. @samp{silent} is not really a command; | |
1370 | it is meaningful only at the beginning of the commands for a breakpoint. | |
1371 | ||
1372 | The commands @samp{echo} and @samp{output} that allow you to print precisely | |
1373 | controlled output are often useful in silent breakpoints. @xref{Output}. | |
1374 | ||
1375 | For example, here is how you could use breakpoint commands to print the | |
1376 | value of @code{x} at entry to @code{foo} whenever it is positive. | |
1377 | ||
1378 | @example | |
1379 | break foo if x>0 | |
1380 | commands | |
1381 | silent | |
1382 | echo x is\040 | |
1383 | output x | |
1384 | echo \n | |
1385 | cont | |
1386 | end | |
1387 | @end example | |
1388 | ||
1389 | One application for breakpoint commands is to correct one bug so you can | |
1390 | test another. Put a breakpoint just after the erroneous line of code, give | |
1391 | it a condition to detect the case in which something erroneous has been | |
1392 | done, and give it commands to assign correct values to any variables that | |
1393 | need them. End with the @samp{cont} command so that the program does not | |
1394 | stop, and start with the @samp{silent} command so that no output is | |
1395 | produced. Here is an example: | |
1396 | ||
1397 | @example | |
1398 | break 403 | |
1399 | commands | |
1400 | silent | |
1401 | set x = y + 4 | |
1402 | cont | |
1403 | end | |
1404 | @end example | |
1405 | ||
1406 | One deficiency in the operation of automatically continuing breakpoints | |
1407 | under Unix appears when your program uses raw mode for the terminal. | |
1408 | GDB switches back to its own terminal modes (not raw) before executing | |
1409 | commands, and then must switch back to raw mode when your program is | |
1410 | continued. This causes any pending terminal input to be lost. | |
1411 | ||
1412 | In the GNU system, this will be fixed by changing the behavior of | |
1413 | terminal modes. | |
1414 | ||
1415 | Under Unix, when you have this problem, you might be able to get around | |
1416 | it by putting your actions into the breakpoint condition instead of | |
1417 | commands. For example | |
1418 | ||
1419 | @example | |
1420 | condition 5 (x = y + 4), 0 | |
1421 | @end example | |
1422 | ||
1423 | @noindent | |
1424 | specifies a condition expression (@xref{Expressions}) that will change | |
1425 | @code{x} as needed, then always have the value 0 so the program will not | |
1426 | stop. Loss of input is avoided here because break conditions are | |
1427 | evaluated without changing the terminal modes. When you want to have | |
1428 | nontrivial conditions for performing the side effects, the operators | |
1429 | @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. | |
1430 | ||
1431 | @node Error in Breakpoints,, Break Commands, Breakpoints | |
1432 | @subsection ``Cannot Insert Breakpoints'' Error | |
1433 | ||
1434 | Under some operating systems, breakpoints cannot be used in a program if | |
1435 | any other process is running that program. Attempting to run or | |
1436 | continue the program with a breakpoint in this case will cause GDB to | |
1437 | stop it. | |
1438 | ||
1439 | When this happens, you have three ways to proceed: | |
1440 | ||
1441 | @enumerate | |
1442 | @item | |
1443 | Remove or disable the breakpoints, then continue. | |
1444 | ||
1445 | @item | |
1446 | Suspend GDB, and copy the file containing the program to a new name. | |
1447 | Resume GDB and use the @samp{exec-file} command to specify that GDB | |
1448 | should run the program under that name. Then start the program again. | |
1449 | ||
1450 | @item | |
1451 | Relink the program so that the text segment is nonsharable, using the | |
1452 | linker option @samp{-N}. The operating system limitation may not apply | |
1453 | to nonsharable executables. | |
1454 | @end enumerate | |
1455 | ||
1456 | @node Continuing, Stepping, Breakpoints, Stopping | |
1457 | @section Continuing | |
1458 | ||
1459 | After your program stops, most likely you will want it to run some more if | |
1460 | the bug you are looking for has not happened yet. | |
1461 | ||
1462 | @table @code | |
1463 | @item cont | |
1464 | @kindex cont | |
1465 | Continue running the program at the place where it stopped. | |
1466 | @end table | |
1467 | ||
1468 | If the program stopped at a breakpoint, the place to continue running | |
1469 | is the address of the breakpoint. You might expect that continuing would | |
1470 | just stop at the same breakpoint immediately. In fact, @samp{cont} | |
1471 | takes special care to prevent that from happening. You do not need | |
1472 | to delete the breakpoint to proceed through it after stopping at it. | |
1473 | ||
1474 | You can, however, specify an ignore-count for the breakpoint that the | |
1475 | program stopped at, by means of an argument to the @samp{cont} command. | |
1476 | @xref{Conditions}. | |
1477 | ||
1478 | If the program stopped because of a signal other than @code{SIGINT} or | |
1479 | @code{SIGTRAP}, continuing will cause the program to see that signal. | |
1480 | You may not want this to happen. For example, if the program stopped | |
1481 | due to some sort of memory reference error, you might store correct | |
1482 | values into the erroneous variables and continue, hoping to see more | |
1483 | execution; but the program would probably terminate immediately as | |
1484 | a result of the fatal signal once it sees the signal. To prevent this, | |
1485 | you can continue with @samp{signal 0}. @xref{Signaling}. You can | |
1486 | also act in advance to prevent the program from seeing certain kinds | |
1487 | of signals, using the @samp{handle} command (@pxref{Signals}). | |
1488 | ||
1489 | @node Stepping,, Continuing, Stopping | |
1490 | @section Stepping | |
1491 | ||
1492 | @cindex stepping | |
1493 | @dfn{Stepping} means setting your program in motion for a limited time, so | |
1494 | that control will return automatically to the debugger after one line of | |
1495 | code or one machine instruction. Breakpoints are active during stepping | |
1496 | and the program will stop for them even if it has not gone as far as the | |
1497 | stepping command specifies. | |
1498 | ||
1499 | @table @code | |
1500 | @item step | |
1501 | @kindex step | |
1502 | Continue running the program until control reaches a different line, | |
1503 | then stop it and return control to the debugger. This command is | |
1504 | abbreviated @samp{s}. | |
1505 | ||
1506 | This command may be given when control is within a function for which | |
1507 | there is no debugging information. In that case, execution will proceed | |
1508 | until control reaches a different function, or is about to return from | |
1509 | this function. An argument repeats this action. | |
1510 | ||
1511 | @item step @var{count} | |
1512 | Continue running as in @samp{step}, but do so @var{count} times. If a | |
1513 | breakpoint is reached or a signal not related to stepping occurs before | |
1514 | @var{count} steps, stepping stops right away. | |
1515 | ||
1516 | @item next | |
1517 | @kindex next | |
1518 | Similar to @samp{step}, but any function calls appearing within the line of | |
1519 | code are executed without stopping. Execution stops when control reaches a | |
1520 | different line of code at the stack level which was executing when the | |
1521 | @samp{next} command was given. This command is abbreviated @samp{n}. | |
1522 | ||
1523 | An argument is a repeat count, as in @samp{step}. | |
1524 | ||
1525 | @samp{next} within a function without debugging information acts as does | |
1526 | @samp{step}, but any function calls appearing within the code of the | |
1527 | function are executed without stopping. | |
1528 | ||
1529 | @item finish | |
1530 | @kindex finish | |
1531 | Continue running until just after the selected stack frame returns (or | |
1532 | until there is some other reason to stop, such as a fatal signal or a | |
1533 | breakpoint). Print value returned by the selected stack frame (if any). | |
1534 | ||
1535 | Contrast this with the @samp{return} command (@pxref{Returning}). | |
1536 | ||
1537 | @item until | |
1538 | @kindex until | |
1539 | This command is used to avoid single stepping through a loop more than | |
1540 | once. It is like the @samp{next} command, except that when @samp{until} | |
1541 | encounters a jump, it automatically continues execution until the | |
1542 | program counter is greater than the address of the jump. | |
1543 | ||
1544 | This means that when you reach the end of a loop after single stepping | |
1545 | though it, @samp{until} will cause the program to continue execution | |
1546 | until the loop is exited. In contrast, a @samp{next} command at the end | |
1547 | of a loop will simply step back to the beginning of the loop, which | |
1548 | would force you to step through the next iteration. | |
1549 | ||
1550 | @samp{until} always stops the program if it attempts to exit the current | |
1551 | stack frame. | |
1552 | ||
1553 | @samp{until} may produce somewhat counterintuitive results if the order | |
1554 | of the source lines does not match the actual order of execution. For | |
1555 | example, in a typical C @code{for}-loop, the third expression in the | |
1556 | @code{for}-statement (the loop-step expression) is executed after the | |
1557 | statements in the body of the loop, but is written before them. | |
1558 | Therefore, the @samp{until} command would appear to step back to the | |
1559 | beginning of the loop when it advances to this expression. However, it | |
1560 | has not really done so, not in terms of the actual machine code. | |
1561 | ||
1562 | Note that @samp{until} with no argument works by means of single | |
1563 | instruction stepping, and hence is slower than @samp{until} with an | |
1564 | argument. | |
1565 | ||
1566 | @item until @var{location} | |
1567 | Continue running the program until either the specified location is | |
1568 | reached, or the current (innermost) stack frame returns. This form of | |
1569 | the command uses breakpoints, and hence is quicker than @samp{until} | |
1570 | without an argument. | |
1571 | ||
1572 | @item stepi | |
1573 | @itemx si | |
1574 | @kindex stepi | |
1575 | @kindex si | |
1576 | Execute one machine instruction, then stop and return to the debugger. | |
1577 | ||
1578 | It is often useful to do @samp{display/i $pc} when stepping by machine | |
1579 | instructions. This will cause the next instruction to be executed to | |
1580 | be displayed automatically at each stop. @xref{Auto Display}. | |
1581 | ||
1582 | An argument is a repeat count, as in @samp{step}. | |
1583 | ||
1584 | @item nexti | |
1585 | @itemx ni | |
1586 | @kindex nexti | |
1587 | @kindex ni | |
1588 | Execute one machine instruction, but if it is a subroutine call, | |
1589 | proceed until the subroutine returns. | |
1590 | ||
1591 | An argument is a repeat count, as in @samp{next}. | |
1592 | @end table | |
1593 | ||
1594 | A typical technique for using stepping is to put a breakpoint | |
1595 | (@pxref{Breakpoints}) at the beginning of the function or the section of | |
1596 | the program in which a problem is believed to lie, and then step through | |
1597 | the suspect area, examining the variables that are interesting, until the | |
1598 | problem happens. | |
1599 | ||
1600 | The @samp{cont} command can be used after stepping to resume execution | |
1601 | until the next breakpoint or signal. | |
1602 | ||
1603 | @node Stack, Source, Stopping, Top | |
1604 | @chapter Examining the Stack | |
1605 | ||
1606 | When your program has stopped, the first thing you need to know is where it | |
1607 | stopped and how it got there. | |
1608 | ||
1609 | @cindex call stack | |
1610 | Each time your program performs a function call, the information about | |
1611 | where in the program the call was made from is saved in a block of data | |
1612 | called a @dfn{stack frame}. The frame also contains the arguments of the | |
1613 | call and the local variables of the function that was called. All the | |
1614 | stack frames are allocated in a region of memory called the @dfn{call | |
1615 | stack}. | |
1616 | ||
1617 | When your program stops, the GDB commands for examining the stack allow you | |
1618 | to see all of this information. | |
1619 | ||
1620 | One of the stack frames is @dfn{selected} by GDB and many GDB commands | |
1621 | refer implicitly to the selected frame. In particular, whenever you ask | |
1622 | GDB for the value of a variable in the program, the value is found in the | |
1623 | selected frame. There are special GDB commands to select whichever frame | |
1624 | you are interested in. | |
1625 | ||
1626 | When the program stops, GDB automatically selects the currently executing | |
1627 | frame and describes it briefly as the @samp{frame} command does | |
1628 | (@pxref{Frame Info, Info}). | |
1629 | ||
1630 | @menu | |
1631 | * Frames:: Explanation of stack frames and terminology. | |
1632 | * Backtrace:: Summarizing many frames at once. | |
1633 | * Selection:: How to select a stack frame. | |
1634 | * Info: Frame Info, Commands to print information on stack frames. | |
1635 | @end menu | |
1636 | ||
1637 | @node Frames, Backtrace, Stack, Stack | |
1638 | @section Stack Frames | |
1639 | ||
1640 | @cindex frame | |
1641 | @cindex stack frame | |
1642 | The call stack is divided up into contiguous pieces called @dfn{stack | |
1643 | frames}, or @dfn{frames} for short; each frame is the data associated | |
1644 | with one call to one function. The frame contains the arguments given | |
1645 | to the function, the function's local variables, and the address at | |
1646 | which the function is executing. | |
1647 | ||
1648 | @cindex initial frame | |
1649 | @cindex outermost frame | |
1650 | @cindex innermost frame | |
1651 | When your program is started, the stack has only one frame, that of the | |
1652 | function @code{main}. This is called the @dfn{initial} frame or the | |
1653 | @dfn{outermost} frame. Each time a function is called, a new frame is | |
1654 | made. Each time a function returns, the frame for that function invocation | |
1655 | is eliminated. If a function is recursive, there can be many frames for | |
1656 | the same function. The frame for the function in which execution is | |
1657 | actually occurring is called the @dfn{innermost} frame. This is the most | |
1658 | recently created of all the stack frames that still exist. | |
1659 | ||
1660 | @cindex frame pointer | |
1661 | Inside your program, stack frames are identified by their addresses. A | |
1662 | stack frame consists of many bytes, each of which has its own address; each | |
1663 | kind of computer has a convention for choosing one of those bytes whose | |
1664 | address serves as the address of the frame. Usually this address is kept | |
1665 | in a register called the @dfn{frame pointer register} while execution is | |
1666 | going on in that frame. | |
1667 | ||
1668 | @cindex frame number | |
1669 | GDB assigns numbers to all existing stack frames, starting with zero for | |
1670 | the innermost frame, one for the frame that called it, and so on upward. | |
1671 | These numbers do not really exist in your program; they are to give you a | |
1672 | way of talking about stack frames in GDB commands. | |
1673 | ||
1674 | @cindex selected frame | |
1675 | Many GDB commands refer implicitly to one stack frame. GDB records a stack | |
1676 | frame that is called the @dfn{selected} stack frame; you can select any | |
1677 | frame using one set of GDB commands, and then other commands will operate | |
1678 | on that frame. When your program stops, GDB automatically selects the | |
1679 | innermost frame. | |
1680 | ||
1681 | @cindex frameless execution | |
1682 | Some functions can be compiled to run without a frame reserved for them | |
1683 | on the stack. This is occasionally done with heavily used library | |
1684 | functions to save the frame setup time. GDB has limited facilities for | |
1685 | dealing with these function invocations; if the innermost function | |
1686 | invocation has no stack frame, GDB will give it a virtual stack frame of | |
1687 | 0 and correctly allow tracing of the function call chain. Results are | |
1688 | undefined if a function invocation besides the innermost one is | |
1689 | frameless. | |
1690 | ||
1691 | @node Backtrace, Selection, Frames, Stack | |
1692 | @section Backtraces | |
1693 | ||
1694 | A backtrace is a summary of how the program got where it is. It shows one | |
1695 | line per frame, for many frames, starting with the currently executing | |
1696 | frame (frame zero), followed by its caller (frame one), and on up the | |
1697 | stack. | |
1698 | ||
1699 | @table @code | |
1700 | @item backtrace | |
1701 | @itemx bt | |
1702 | @kindex backtrace | |
1703 | @kindex bt | |
1704 | Print a backtrace of the entire stack: one line per frame for all | |
1705 | frames in the stack. | |
1706 | ||
1707 | You can stop the backtrace at any time by typing the system interrupt | |
1708 | character, normally @kbd{Control-C}. | |
1709 | ||
1710 | @item backtrace @var{n} | |
1711 | @itemx bt @var{n} | |
1712 | Similar, but print only the innermost @var{n} frames. | |
1713 | ||
1714 | @item backtrace @var{-n} | |
1715 | @itemx bt @var{-n} | |
1716 | Similar, but print only the outermost @var{n} frames. | |
1717 | @end table | |
1718 | ||
1719 | @kindex where | |
1720 | @kindex info stack | |
1721 | The names @samp{where} and @samp{info stack} are additional aliases | |
1722 | for @samp{backtrace}. | |
1723 | ||
1724 | Every line in the backtrace shows the frame number, the function name | |
1725 | and the program counter value. | |
1726 | ||
1727 | If the function is in a source file whose symbol table data has been | |
1728 | fully read, the backtrace shows the source file name and line number, as | |
1729 | well as the arguments to the function. (The program counter value is | |
1730 | omitted if it is at the beginning of the code for that line number.) | |
1731 | ||
1732 | If the source file's symbol data has not been fully read, just scanned, | |
1733 | this extra information is replaced with an ellipsis. You can force the | |
1734 | symbol data for that frame's source file to be read by selecting the | |
1735 | frame. (@xref{Selection}). | |
1736 | ||
1737 | Here is an example of a backtrace. It was made with the command | |
1738 | @samp{bt 3}, so it shows the innermost three frames. | |
1739 | ||
1740 | @example | |
1741 | #0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) (/gp/rms/cc/rtlanal.c line 337) | |
1742 | #1 0x246b0 in expand_call (...) (...) | |
1743 | #2 0x21cfc in expand_expr (...) (...) | |
1744 | (More stack frames follow...) | |
1745 | @end example | |
1746 | ||
1747 | @noindent | |
1748 | The functions @code{expand_call} and @code{expand_expr} are in a file | |
1749 | whose symbol details have not been fully read. Full detail is available | |
1750 | for the function @code{rtx_equal_p}, which is in the file | |
1751 | @file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown | |
1752 | with their typed values. | |
1753 | ||
1754 | @node Selection, Frame Info, Backtrace, Stack | |
1755 | @section Selecting a Frame | |
1756 | ||
1757 | Most commands for examining the stack and other data in the program work on | |
1758 | whichever stack frame is selected at the moment. Here are the commands for | |
1759 | selecting a stack frame; all of them finish by printing a brief description | |
1760 | of the stack frame just selected. | |
1761 | ||
1762 | @table @code | |
1763 | @item frame @var{n} | |
1764 | @kindex frame | |
1765 | Select frame number @var{n}. Recall that frame zero is the innermost | |
1766 | (currently executing) frame, frame one is the frame that called the | |
1767 | innermost one, and so on. The highest-numbered frame is @code{main}'s | |
1768 | frame. | |
1769 | ||
1770 | @item frame @var{addr} | |
1771 | Select the frame at address @var{addr}. This is useful mainly if the | |
1772 | chaining of stack frames has been damaged by a bug, making it | |
1773 | impossible for GDB to assign numbers properly to all frames. In | |
1774 | addition, this can be useful when the program has multiple stacks and | |
1775 | switches between them. | |
1776 | ||
1777 | @item up @var{n} | |
1778 | @kindex up | |
1779 | Select the frame @var{n} frames up from the frame previously selected. | |
1780 | For positive numbers @var{n}, this advances toward the outermost | |
1781 | frame, to higher frame numbers, to frames that have existed longer. | |
1782 | @var{n} defaults to one. | |
1783 | ||
1784 | @item down @var{n} | |
1785 | @kindex down | |
1786 | Select the frame @var{n} frames down from the frame previously | |
1787 | selected. For positive numbers @var{n}, this advances toward the | |
1788 | innermost frame, to lower frame numbers, to frames that were created | |
1789 | more recently. @var{n} defaults to one. | |
1790 | @end table | |
1791 | ||
1792 | All of these commands end by printing some information on the frame that | |
1793 | has been selected: the frame number, the function name, the arguments, the | |
1794 | source file and line number of execution in that frame, and the text of | |
1795 | that source line. For example: | |
1796 | ||
1797 | @example | |
1798 | #3 main (argc=3, argv=??, env=??) at main.c, line 67 | |
1799 | 67 read_input_file (argv[i]); | |
1800 | @end example | |
1801 | ||
1802 | After such a printout, the @samp{list} command with no arguments will print | |
1803 | ten lines centered on the point of execution in the frame. @xref{List}. | |
1804 | ||
1805 | @node Frame Info,, Selection, Stack | |
1806 | @section Information on a Frame | |
1807 | ||
1808 | There are several other commands to print information about the selected | |
1809 | stack frame. | |
1810 | ||
1811 | @table @code | |
1812 | @item frame | |
1813 | This command prints a brief description of the selected stack frame. | |
1814 | It can be abbreviated @samp{f}. With an argument, this command is | |
1815 | used to select a stack frame; with no argument, it does not change | |
1816 | which frame is selected, but still prints the same information. | |
1817 | ||
1818 | @item info frame | |
1819 | @kindex info frame | |
1820 | This command prints a verbose description of the selected stack frame, | |
1821 | including the address of the frame, the addresses of the next frame in | |
1822 | (called by this frame) and the next frame out (caller of this frame), | |
1823 | the address of the frame's arguments, the program counter saved in it | |
1824 | (the address of execution in the caller frame), and which registers | |
1825 | were saved in the frame. The verbose description is useful when | |
1826 | something has gone wrong that has made the stack format fail to fit | |
1827 | the usual conventions. | |
1828 | ||
1829 | @item info frame @var{addr} | |
1830 | Print a verbose description of the frame at address @var{addr}, | |
1831 | without selecting that frame. The selected frame remains unchanged by | |
1832 | this command. | |
1833 | ||
1834 | @item info args | |
1835 | @kindex info args | |
1836 | Print the arguments of the selected frame, each on a separate line. | |
1837 | ||
1838 | @item info locals | |
1839 | @kindex info locals | |
1840 | Print the local variables of the selected frame, each on a separate | |
1841 | line. These are all variables declared static or automatic within all | |
1842 | program blocks that execution in this frame is currently inside of. | |
1843 | @end table | |
1844 | ||
1845 | @node Source, Data, Stack, Top | |
1846 | @chapter Examining Source Files | |
1847 | ||
1848 | GDB knows which source files your program was compiled from, and | |
1849 | can print parts of their text. When your program stops, GDB | |
1850 | spontaneously prints the line it stopped in. Likewise, when you | |
1851 | select a stack frame (@pxref{Selection}), GDB prints the line | |
1852 | which execution in that frame has stopped in. You can also | |
1853 | print parts of source files by explicit command. | |
1854 | ||
1855 | @menu | |
1856 | * List:: Using the @samp{list} command to print source files. | |
1857 | * Search:: Commands for searching source files. | |
1858 | * Source Path:: Specifying the directories to search for source files. | |
1859 | @end menu | |
1860 | ||
1861 | @node List, Search, Source, Source | |
1862 | @section Printing Source Lines | |
1863 | ||
1864 | @kindex list | |
1865 | To print lines from a source file, use the @samp{list} command | |
1866 | (abbreviated @samp{l}). There are several ways to specify what part | |
1867 | of the file you want to print. | |
1868 | ||
1869 | Here are the forms of the @samp{list} command most commonly used: | |
1870 | ||
1871 | @table @code | |
1872 | @item list @var{linenum} | |
1873 | Print ten lines centered around line number @var{linenum} in the | |
1874 | current source file. | |
1875 | ||
1876 | @item list @var{function} | |
1877 | Print ten lines centered around the beginning of function | |
1878 | @var{function}. | |
1879 | ||
1880 | @item list | |
1881 | Print ten more lines. If the last lines printed were printed with a | |
1882 | @samp{list} command, this prints ten lines following the last lines | |
1883 | printed; however, if the last line printed was a solitary line printed | |
1884 | as part of displaying a stack frame (@pxref{Stack}), this prints ten | |
1885 | lines centered around that line. | |
1886 | ||
1887 | @item list - | |
1888 | Print ten lines just before the lines last printed. | |
1889 | @end table | |
1890 | ||
1891 | Repeating a @samp{list} command with @key{RET} discards the argument, | |
1892 | so it is equivalent to typing just @samp{list}. This is more useful | |
1893 | than listing the same lines again. An exception is made for an | |
1894 | argument of @samp{-}; that argument is preserved in repetition so that | |
1895 | each repetition moves up in the file. | |
1896 | ||
1897 | @cindex linespec | |
1898 | In general, the @samp{list} command expects you to supply zero, one or two | |
1899 | @dfn{linespecs}. Linespecs specify source lines; there are several ways | |
1900 | of writing them but the effect is always to specify some source line. | |
1901 | Here is a complete description of the possible arguments for @samp{list}: | |
1902 | ||
1903 | @table @code | |
1904 | @item list @var{linespec} | |
1905 | Print ten lines centered around the line specified by @var{linespec}. | |
1906 | ||
1907 | @item list @var{first},@var{last} | |
1908 | Print lines from @var{first} to @var{last}. Both arguments are | |
1909 | linespecs. | |
1910 | ||
1911 | @item list ,@var{last} | |
1912 | Print ten lines ending with @var{last}. | |
1913 | ||
1914 | @item list @var{first}, | |
1915 | Print ten lines starting with @var{first}. | |
1916 | ||
1917 | @item list + | |
1918 | Print ten lines just after the lines last printed. | |
1919 | ||
1920 | @item list - | |
1921 | Print ten lines just before the lines last printed. | |
1922 | ||
1923 | @item list | |
1924 | As described in the preceding table. | |
1925 | @end table | |
1926 | ||
1927 | Here are the ways of specifying a single source line---all the | |
1928 | kinds of linespec. | |
1929 | ||
1930 | @table @code | |
1931 | @item @var{linenum} | |
1932 | Specifies line @var{linenum} of the current source file. | |
1933 | When a @samp{list} command has two linespecs, this refers to | |
1934 | the same source file as the first linespec. | |
1935 | ||
1936 | @item +@var{offset} | |
1937 | Specifies the line @var{offset} lines after the last line printed. | |
1938 | When used as the second linespec in a @samp{list} command that has | |
1939 | two, this specifies the line @var{offset} lines down from the | |
1940 | first linespec. | |
1941 | ||
1942 | @item -@var{offset} | |
1943 | Specifies the line @var{offset} lines before the last line printed. | |
1944 | ||
1945 | @item @var{filename}:@var{linenum} | |
1946 | Specifies line @var{linenum} in the source file @var{filename}. | |
1947 | ||
1948 | @item @var{function} | |
1949 | Specifies the line of the open-brace that begins the body of the | |
1950 | function @var{function}. | |
1951 | ||
1952 | @item @var{filename}:@var{function} | |
1953 | Specifies the line of the open-brace that begins the body of the | |
1954 | function @var{function} in the file @var{filename}. The file name is | |
1955 | needed with a function name only for disambiguation of identically | |
1956 | named functions in different source files. | |
1957 | ||
1958 | @item *@var{address} | |
1959 | Specifies the line containing the program address @var{address}. | |
1960 | @var{address} may be any expression. | |
1961 | @end table | |
1962 | ||
1963 | One other command is used to map source lines to program addresses. | |
1964 | ||
1965 | @table @code | |
1966 | @item info line @var{linenum} | |
1967 | @kindex info line | |
1968 | Print the starting and ending addresses of the compiled code for | |
1969 | source line @var{linenum}. | |
1970 | ||
1971 | @kindex $_ | |
1972 | The default examine address for the @samp{x} command is changed to the | |
1973 | starting address of the line, so that @samp{x/i} is sufficient to | |
1974 | begin examining the machine code (@pxref{Memory}). Also, this address | |
1975 | is saved as the value of the convenience variable @code{$_} | |
1976 | (@pxref{Convenience Vars}). | |
1977 | @end table | |
1978 | ||
1979 | @node Search, Source Path, List, Source | |
1980 | @section Searching Source Files | |
1981 | @cindex searching | |
1982 | @kindex forward-search | |
1983 | @kindex reverse-search | |
1984 | ||
1985 | There are two commands for searching through the current source file for a | |
1986 | regular expression. | |
1987 | ||
1988 | The command @samp{forward-search @var{regexp}} checks each line, starting | |
1989 | with the one following the last line listed, for a match for @var{regexp}. | |
1990 | It lists the line that is found. You can abbreviate the command name | |
1991 | as @samp{fo}. | |
1992 | ||
1993 | The command @samp{reverse-search @var{regexp}} checks each line, starting | |
1994 | with the one before the last line listed and going backward, for a match | |
1995 | for @var{regexp}. It lists the line that is found. You can abbreviate | |
1996 | this command with as little as @samp{rev}. | |
1997 | ||
1998 | @node Source Path,, Search, Source | |
1999 | @section Specifying Source Directories | |
2000 | ||
2001 | @cindex source path | |
2002 | @cindex directories for source files | |
2003 | Executable programs do not record the directories of the source files | |
2004 | from which they were compiled, just the names. GDB remembers a list of | |
2005 | directories to search for source files; this is called the @dfn{source | |
2006 | path}. Each time GDB wants a source file, it tries all the directories | |
2007 | in the list, in the order they are present in the list, until it finds a | |
2008 | file with the desired name. @b{Note that the executable search path is | |
2009 | @i{not} used for this purpose. Neither is the current working | |
2010 | directory, unless it happens to be in the source path.} | |
2011 | ||
2012 | @kindex directory | |
2013 | When you start GDB, its source path contains just the current working | |
2014 | directory. To add other directories, use the @samp{directory} command. | |
2015 | ||
2016 | @table @code | |
2017 | @item directory @var{dirnames...} | |
2018 | Add directory @var{dirname} to the end of the source path. Several | |
2019 | directory names may be given to this command, separated by whitespace or | |
2020 | @samp{:}. | |
2021 | ||
2022 | @item directory | |
2023 | Reset the source path to just the current working directory of GDB. | |
2024 | This requires confirmation. | |
2025 | ||
2026 | Since this command deletes directories from the search path, it may | |
2027 | change the directory in which a previously read source file will be | |
2028 | discovered. To make this work correctly, this command also clears out | |
2029 | the tables GDB maintains about the source files it has already found. | |
2030 | ||
2031 | @item info directories | |
2032 | @kindex info directories | |
2033 | Print the source path: show which directories it contains. | |
2034 | @end table | |
2035 | ||
2036 | Because the @samp{directory} command adds to the end of the source path, | |
2037 | it does not affect any file that GDB has already found. If the source | |
2038 | path contains directories that you do not want, and these directories | |
2039 | contain misleading files with names matching your source files, the | |
2040 | way to correct the situation is as follows: | |
2041 | ||
2042 | @enumerate | |
2043 | @item | |
2044 | Choose the directory you want at the beginning of the source path. | |
2045 | Use the @samp{cd} command to make that the current working directory. | |
2046 | ||
2047 | @item | |
2048 | Use @samp{directory} with no argument to reset the source path to just | |
2049 | that directory. | |
2050 | ||
2051 | @item | |
2052 | Use @samp{directory} with suitable arguments to add any other | |
2053 | directories you want in the source path. | |
2054 | @end enumerate | |
2055 | ||
2056 | @node Data, Symbols, Source, Top | |
2057 | @chapter Examining Data | |
2058 | ||
2059 | @cindex printing data | |
2060 | @cindex examining data | |
2061 | @kindex print | |
2062 | The usual way to examine data in your program is with the @samp{print} | |
2063 | command (abbreviated @samp{p}). It evaluates and prints the value of any | |
2064 | valid expression of the language the program is written in (for now, C). | |
2065 | You type | |
2066 | ||
2067 | @example | |
2068 | print @var{exp} | |
2069 | @end example | |
2070 | ||
2071 | @noindent | |
2072 | where @var{exp} is any valid expression, and the value of @var{exp} | |
2073 | is printed in a format appropriate to its data type. | |
2074 | ||
2075 | A more low-level way of examining data is with the @samp{x} command. | |
2076 | It examines data in memory at a specified address and prints it in a | |
2077 | specified format. | |
2078 | ||
2079 | @menu | |
2080 | * Expressions:: Expressions that can be computed and printed. | |
2081 | * Variables:: Using your program's variables in expressions. | |
2082 | * Assignment:: Setting your program's variables. | |
2083 | * Arrays:: Examining part of memory as an array. | |
2084 | * Format Options:: Controlling how structures and arrays are printed. | |
2085 | * Output formats:: Specifying formats for printing values. | |
2086 | * Memory:: Examining memory explicitly. | |
2087 | * Auto Display:: Printing certain expressions whenever program stops. | |
2088 | * Value History:: Referring to values previously printed. | |
2089 | * Convenience Vars:: Giving names to values for future reference. | |
2090 | * Registers:: Referring to and storing in machine registers. | |
2091 | @end menu | |
2092 | ||
2093 | @node Expressions, Variables, Data, Data | |
2094 | @section Expressions | |
2095 | ||
2096 | @cindex expressions | |
2097 | Many different GDB commands accept an expression and compute its value. | |
2098 | Any kind of constant, variable or operator defined by the programming | |
2099 | language you are using is legal in an expression in GDB. This includes | |
2100 | conditional expressions, function calls, casts and string constants. | |
2101 | It unfortunately does not include symbols defined by preprocessor | |
2102 | @code{#define} commands. | |
2103 | ||
2104 | Casts are supported in all languages, not just in C, because it is so | |
2105 | useful to cast a number into a pointer so as to examine a structure | |
2106 | at that address in memory. | |
2107 | ||
2108 | GDB supports three kinds of operator in addition to those of programming | |
2109 | languages: | |
2110 | ||
2111 | @table @code | |
2112 | @item @@ | |
2113 | @samp{@@} is a binary operator for treating parts of memory as arrays. | |
2114 | @xref{Arrays}, for more information. | |
2115 | ||
2116 | @item :: | |
2117 | @samp{::} allows you to specify a variable in terms of the file or | |
2118 | function it is defined in. @xref{Variables}. | |
2119 | ||
2120 | @item @{@var{type}@} @var{addr} | |
2121 | Refers to an object of type @var{type} stored at address @var{addr} in | |
2122 | memory. @var{addr} may be any expression whose value is an integer or | |
2123 | pointer (but parentheses are required around nonunary operators, just as in | |
2124 | a cast). This construct is allowed regardless of what kind of data is | |
2125 | officially supposed to reside at @var{addr}.@refill | |
2126 | @end table | |
2127 | ||
2128 | @node Variables, Arrays, Expressions, Data | |
2129 | @section Program Variables | |
2130 | ||
2131 | The most common kind of expression to use is the name of a variable | |
2132 | in your program. | |
2133 | ||
2134 | Variables in expressions are understood in the selected stack frame | |
2135 | (@pxref{Selection}); they must either be global (or static) or be visible | |
2136 | according to the scope rules of the programming language from the point of | |
2137 | execution in that frame. This means that in the function | |
2138 | ||
2139 | @example | |
2140 | foo (a) | |
2141 | int a; | |
2142 | @{ | |
2143 | bar (a); | |
2144 | @{ | |
2145 | int b = test (); | |
2146 | bar (b); | |
2147 | @} | |
2148 | @} | |
2149 | @end example | |
2150 | ||
2151 | @noindent | |
2152 | the variable @code{a} is usable whenever the program is executing | |
2153 | within the function @code{foo}, but the variable @code{b} is visible | |
2154 | only while the program is executing inside the block in which @code{b} | |
2155 | is declared. | |
2156 | ||
2157 | As a special exception, you can refer to a variable or function whose | |
2158 | scope is a single source file even if the current execution point is not | |
2159 | in this file. But it is possible to have more than one such variable | |
2160 | or function with the same name (if they are in different source files). | |
2161 | In such a case, it is not defined which one you will get. If you wish, | |
2162 | you can specify any one of them using the colon-colon construct: | |
2163 | ||
2164 | @example | |
2165 | @var{block}::@var{variable} | |
2166 | @end example | |
2167 | ||
2168 | @noindent | |
2169 | Here @var{block} is the name of the source file whose variable you want. | |
2170 | ||
2171 | @node Arrays, Format options, Variables, Data | |
2172 | @section Artificial Arrays | |
2173 | ||
2174 | @cindex artificial array | |
2175 | It is often useful to print out several successive objects of the | |
2176 | same type in memory; a section of an array, or an array of | |
2177 | dynamically determined size for which only a pointer exists in the | |
2178 | program. | |
2179 | ||
2180 | This can be done by constructing an @dfn{artificial array} with the | |
2181 | binary operator @samp{@@}. The left operand of @samp{@@} should be | |
2182 | the first element of the desired array, as an individual object. | |
2183 | The right operand should be the length of the array. The result is | |
2184 | an array value whose elements are all of the type of the left argument. | |
2185 | The first element is actually the left argument; the second element | |
2186 | comes from bytes of memory immediately following those that hold the | |
2187 | first element, and so on. Here is an example. If a program says | |
2188 | ||
2189 | @example | |
2190 | int *array = (int *) malloc (len * sizeof (int)); | |
2191 | @end example | |
2192 | ||
2193 | @noindent | |
2194 | you can print the contents of @code{array} with | |
2195 | ||
2196 | @example | |
2197 | p *array@@len | |
2198 | @end example | |
2199 | ||
2200 | The left operand of @samp{@@} must reside in memory. Array values made | |
2201 | with @samp{@@} in this way behave just like other arrays in terms of | |
2202 | subscripting, and are coerced to pointers when used in expressions. | |
2203 | (It would probably appear in an expression via the value history, | |
2204 | after you had printed it out.) | |
2205 | ||
2206 | @node Format options, Output formats, Arrays, Data | |
2207 | @section Format options | |
2208 | ||
2209 | @cindex format options | |
2210 | GDB provides a few ways to control how arrays and structures are | |
2211 | printed. | |
2212 | ||
2213 | @table @code | |
2214 | @item info format | |
2215 | @kindex info format | |
2216 | Display the current settings for the format options. | |
2217 | ||
2218 | @item set array-max @var{number-of-elements} | |
2219 | @kindex set array-max | |
2220 | If GDB is printing a large array, it will stop printing after it has | |
2221 | printed the number of elements set by the @samp{set array-max} command. | |
2222 | This limit also applies to the display of strings. | |
2223 | ||
2224 | @item set prettyprint on | |
2225 | @kindex set prettyprint | |
2226 | Cause GDB to print structures in an indented format with one member per | |
2227 | line, like this: | |
2228 | ||
2229 | @example | |
2230 | $1 = @{ | |
2231 | next = 0x0, | |
2232 | flags = @{ | |
2233 | sweet = 1, | |
2234 | sour = 1 | |
2235 | @}, | |
2236 | meat = 0x54 "Pork" | |
2237 | @} | |
2238 | @end example | |
2239 | ||
2240 | @item set prettyprint off | |
2241 | Cause GDB to print structures in a compact format, like this: | |
2242 | ||
2243 | @example | |
2244 | $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat = 0x54 "Pork"@} | |
2245 | @end example | |
2246 | ||
2247 | This is the default format. | |
2248 | ||
2249 | @item set unionprint on | |
2250 | @kindex set unionprint | |
2251 | Tell GDB to print unions which are contained in structures. This is the | |
2252 | default setting. | |
2253 | @item set unionprint off | |
2254 | Tell GDB not to print unions which are contained in structures. | |
2255 | ||
2256 | For example, given the declarations | |
2257 | ||
2258 | @example | |
2259 | typedef enum @{Tree, Bug@} Species; | |
2260 | typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; | |
2261 | typedef enum @{Caterpiller, Cocoon, Butterfly@} Bug_forms; | |
2262 | ||
2263 | struct thing @{ | |
2264 | Species it; | |
2265 | union @{ | |
2266 | Tree_forms tree; | |
2267 | Bug_forms bug; | |
2268 | @} form; | |
2269 | @}; | |
2270 | ||
2271 | struct thing foo = @{Tree, @{Acorn@}@}; | |
2272 | @end example | |
2273 | ||
2274 | @noindent | |
2275 | with @samp{set unionprint on} in effect @samp{p foo} would print | |
2276 | ||
2277 | @example | |
2278 | $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} | |
2279 | @end example | |
2280 | ||
2281 | @noindent | |
2282 | and with @samp{set unionprint off} in effect it would print | |
2283 | ||
2284 | @example | |
2285 | $1 = @{it = Tree, form = @{...@}@} | |
2286 | @end example | |
2287 | @end table | |
2288 | ||
2289 | @node Output formats, Memory, Format options, Data | |
2290 | @section Output formats | |
2291 | ||
2292 | @cindex formatted output | |
2293 | @cindex output formats | |
2294 | GDB normally prints all values according to their data types. Sometimes | |
2295 | this is not what you want. For example, you might want to print a number | |
2296 | in hex, or a pointer in decimal. Or you might want to view data in memory | |
2297 | at a certain address as a character string or an instruction. These things | |
2298 | can be done with @dfn{output formats}. | |
2299 | ||
2300 | The simplest use of output formats is to say how to print a value | |
2301 | already computed. This is done by starting the arguments of the | |
2302 | @samp{print} command with a slash and a format letter. The format | |
2303 | letters supported are: | |
2304 | ||
2305 | @table @samp | |
2306 | @item x | |
2307 | Regard the bits of the value as an integer, and print the integer in | |
2308 | hexadecimal. | |
2309 | ||
2310 | @item d | |
2311 | Print as integer in signed decimal. | |
2312 | ||
2313 | @item u | |
2314 | Print as integer in unsigned decimal. | |
2315 | ||
2316 | @item o | |
2317 | Print as integer in octal. | |
2318 | ||
2319 | @item a | |
2320 | Print as an address, both absolute in hex and then relative | |
2321 | to a symbol defined as an address below it. | |
2322 | ||
2323 | @item c | |
2324 | Regard as an integer and print it as a character constant. | |
2325 | ||
2326 | @item f | |
2327 | Regard the bits of the value as a floating point number and print | |
2328 | using typical floating point syntax. | |
2329 | @end table | |
2330 | ||
2331 | For example, to print the program counter in hex (@pxref{Registers}), type | |
2332 | ||
2333 | @example | |
2334 | p/x $pc | |
2335 | @end example | |
2336 | ||
2337 | @noindent | |
2338 | Note that no space is required before the slash; this is because command | |
2339 | names in GDB cannot contain a slash. | |
2340 | ||
2341 | To reprint the last value in the value history with a different format, | |
2342 | you can use the @samp{print} command with just a format and no | |
2343 | expression. For example, @samp{p/x} reprints the last value in hex. | |
2344 | ||
2345 | @node Memory, Auto Display, Output formats, Data | |
2346 | @subsection Examining Memory | |
2347 | ||
2348 | @cindex examining memory | |
2349 | @kindex x | |
2350 | The command @samp{x} (for `examine') can be used to examine memory | |
2351 | without reference to the program's data types. The format in which you | |
2352 | wish to examine memory is instead explicitly specified. The allowable | |
2353 | formats are a superset of the formats described in the previous section. | |
2354 | ||
2355 | @samp{x} is followed by a slash and an output format specification, | |
2356 | followed by an expression for an address. The expression need not have | |
2357 | a pointer value (though it may); it is used as an integer, as the | |
2358 | address of a byte of memory. @xref{Expressions} for more information on | |
2359 | expressions. For example, @samp{x/4xw $sp} prints the four words of | |
2360 | memory above the stack pointer in hexadecimal. | |
2361 | ||
2362 | The output format in this case specifies both how big a unit of memory | |
2363 | to examine and how to print the contents of that unit. It is done | |
2364 | with one or two of the following letters: | |
2365 | ||
2366 | These letters specify just the size of unit to examine: | |
2367 | ||
2368 | @table @samp | |
2369 | @item b | |
2370 | Examine individual bytes. | |
2371 | ||
2372 | @item h | |
2373 | Examine halfwords (two bytes each). | |
2374 | ||
2375 | @item w | |
2376 | Examine words (four bytes each). | |
2377 | ||
2378 | @cindex word | |
2379 | Many assemblers and cpu designers still use `word' for a 16-bit quantity, | |
2380 | as a holdover from specific predecessor machines of the 1970's that really | |
2381 | did use two-byte words. But more generally the term `word' has always | |
2382 | referred to the size of quantity that a machine normally operates on and | |
2383 | stores in its registers. This is 32 bits for all the machines that GDB | |
2384 | runs on. | |
2385 | ||
2386 | @item g | |
2387 | Examine giant words (8 bytes). | |
2388 | @end table | |
2389 | ||
2390 | These letters specify just the way to print the contents: | |
2391 | ||
2392 | @table @samp | |
2393 | @item x | |
2394 | Print as integers in unsigned hexadecimal. | |
2395 | ||
2396 | @item d | |
2397 | Print as integers in signed decimal. | |
2398 | ||
2399 | @item u | |
2400 | Print as integers in unsigned decimal. | |
2401 | ||
2402 | @item o | |
2403 | Print as integers in unsigned octal. | |
2404 | ||
2405 | @item a | |
2406 | Print as an address, both absolute in hex and then relative | |
2407 | to a symbol defined as an address below it. | |
2408 | ||
2409 | @item c | |
2410 | Print as character constants. | |
2411 | ||
2412 | @item f | |
2413 | Print as floating point. This works only with sizes @samp{w} and | |
2414 | @samp{g}. | |
2415 | ||
2416 | @item s | |
2417 | Print a null-terminated string of characters. The specified unit size | |
2418 | is ignored; instead, the unit is however many bytes it takes to reach | |
2419 | a null character (including the null character). | |
2420 | ||
2421 | @item i | |
2422 | Print a machine instruction in assembler syntax (or nearly). The | |
2423 | specified unit size is ignored; the number of bytes in an instruction | |
2424 | varies depending on the type of machine, the opcode and the addressing | |
2425 | modes used. | |
2426 | @end table | |
2427 | ||
2428 | If either the manner of printing or the size of unit fails to be specified, | |
2429 | the default is to use the same one that was used last. If you don't want | |
2430 | to use any letters after the slash, you can omit the slash as well. | |
2431 | ||
2432 | You can also omit the address to examine. Then the address used is | |
2433 | just after the last unit examined. This is why string and instruction | |
2434 | formats actually compute a unit-size based on the data: so that the | |
2435 | next string or instruction examined will start in the right place. | |
2436 | The @samp{print} command sometimes sets the default address for | |
2437 | the @samp{x} command; when the value printed resides in memory, the | |
2438 | default is set to examine the same location. @samp{info line} also | |
2439 | sets the default for @samp{x}, to the address of the start of the | |
2440 | machine code for the specified line and @samp{info breakpoints} sets | |
2441 | it to the address of the last breakpoint listed. | |
2442 | ||
2443 | When you use @key{RET} to repeat an @samp{x} command, it does not repeat | |
2444 | exactly the same: the address specified previously (if any) is ignored, so | |
2445 | that the repeated command examines the successive locations in memory | |
2446 | rather than the same ones. | |
2447 | ||
2448 | You can examine several consecutive units of memory with one command by | |
2449 | writing a repeat-count after the slash (before the format letters, if any). | |
2450 | The repeat count must be a decimal integer. It has the same effect as | |
2451 | repeating the @samp{x} command that many times except that the output may | |
2452 | be more compact with several units per line. For example, | |
2453 | ||
2454 | @example | |
2455 | x/10i $pc | |
2456 | @end example | |
2457 | ||
2458 | @noindent | |
2459 | prints ten instructions starting with the one to be executed next in the | |
2460 | selected frame. After doing this, you could print another ten following | |
2461 | instructions with | |
2462 | ||
2463 | @example | |
2464 | x/10 | |
2465 | @end example | |
2466 | ||
2467 | @noindent | |
2468 | in which the format and address are allowed to default. | |
2469 | ||
2470 | @kindex $_ | |
2471 | @kindex $__ | |
2472 | The addresses and contents printed by the @samp{x} command are not put in | |
2473 | the value history because there is often too much of them and they would | |
2474 | get in the way. Instead, GDB makes these values available for subsequent | |
2475 | use in expressions as values of the convenience variables @code{$_} and | |
2476 | @code{$__}. | |
2477 | ||
2478 | After an @samp{x} command, the last address examined is available for use | |
2479 | in expressions in the convenience variable @code{$_}. The contents of that | |
2480 | address, as examined, are available in the convenience variable @code{$__}. | |
2481 | ||
2482 | If the @samp{x} command has a repeat count, the address and contents saved | |
2483 | are from the last memory unit printed; this is not the same as the last | |
2484 | address printed if several units were printed on the last line of output. | |
2485 | ||
2486 | @kindex disassemble | |
2487 | The specialized command @samp{disassemble} is also provided to dump a | |
2488 | range of memory as machine instructions. The default memory range is | |
2489 | the function surrounding the program counter of the selected frame. A | |
2490 | single argument to this command is a program counter value; the function | |
2491 | surrounding this value will be dumped. Two arguments specify a range of | |
2492 | addresss (first inclusive, second exclusive) to be dumped. | |
2493 | ||
2494 | @node Auto Display, Value History, Memory, Data | |
2495 | @section Automatic Display | |
2496 | @cindex automatic display | |
2497 | @cindex display of expressions | |
2498 | ||
2499 | If you find that you want to print the value of an expression frequently | |
2500 | (to see how it changes), you might want to add it to the @dfn{automatic | |
2501 | display list} so that GDB will print its value each time the program stops. | |
2502 | Each expression added to the list is given a number to identify it; | |
2503 | to remove an expression from the list, you specify that number. | |
2504 | The automatic display looks like this: | |
2505 | ||
2506 | @example | |
2507 | 2: foo = 38 | |
2508 | 3: bar[5] = (struct hack *) 0x3804 | |
2509 | @end example | |
2510 | ||
2511 | @noindent | |
2512 | showing item numbers, expressions and their current values. | |
2513 | ||
2514 | If the expression refers to local variables, then it does not make sense | |
2515 | outside the lexical context for which it was set up. Such an expression | |
2516 | is printed only when execution is inside that lexical context. For | |
2517 | example, if you give the command @samp{display name} while inside a | |
2518 | function with an argument @code{name}, then this argument will be | |
2519 | displayed whenever the program stops inside that function, but not when | |
2520 | it stops elsewhere (since this argument doesn't exist elsewhere). | |
2521 | ||
2522 | @table @code | |
2523 | @item display @var{exp} | |
2524 | @kindex display | |
2525 | Add the expression @var{exp} to the list of expressions to display | |
2526 | each time the program stops. @xref{Expressions}. | |
2527 | ||
2528 | @item display/@var{fmt} @var{exp} | |
2529 | For @var{fmt} specifying only a display format and not a size or | |
2530 | count, add the expression @var{exp} to the auto-display list but | |
2531 | arranges to display it each time in the specified format @var{fmt}. | |
2532 | ||
2533 | @item display/@var{fmt} @var{addr} | |
2534 | For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a | |
2535 | number of units, add the expression @var{addr} as a memory address to | |
2536 | be examined each time the program stops. Examining means in effect | |
2537 | doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}. | |
2538 | ||
2539 | @item undisplay @var{dnums}@dots{} | |
2540 | @itemx delete display @var{dnums}@dots{} | |
2541 | @kindex delete display | |
2542 | @kindex undisplay | |
2543 | Remove item numbers @var{dnums} from the list of expressions to display. | |
2544 | ||
2545 | @item disable display @var{dnums}@dots{} | |
2546 | @kindex disable display | |
2547 | Disable the display of item numbers @var{dnums}. A disabled display | |
2548 | item is not printed automatically, but is not forgotten. It may be | |
2549 | reenabled later. | |
2550 | ||
2551 | @item enable display @var{dnums}@dots{} | |
2552 | @kindex enable display | |
2553 | Enable display of item numbers @var{dnums}. It becomes effective once | |
2554 | again in auto display of its expression, until you specify otherwise. | |
2555 | ||
2556 | @item display | |
2557 | Display the current values of the expressions on the list, just as is | |
2558 | done when the program stops. | |
2559 | ||
2560 | @item info display | |
2561 | @kindex info display | |
2562 | Print the list of expressions previously set up to display | |
2563 | automatically, each one with its item number, but without showing the | |
2564 | values. This includes disabled expressions, which are marked as such. | |
2565 | It also includes expressions which would not be displayed right now | |
2566 | because they refer to automatic variables not currently available. | |
2567 | @end table | |
2568 | ||
2569 | @node Value History, Convenience Vars, Auto Display, Data | |
2570 | @section Value History | |
2571 | ||
2572 | @cindex value history | |
2573 | Every value printed by the @samp{print} command is saved for the entire | |
2574 | session in GDB's @dfn{value history} so that you can refer to it in | |
2575 | other expressions. | |
2576 | ||
2577 | @cindex @code{$} | |
2578 | @cindex @code{$$} | |
2579 | @cindex history number | |
2580 | The values printed are given @dfn{history numbers} for you to refer to them | |
2581 | by. These are successive integers starting with 1. @samp{print} shows you | |
2582 | the history number assigned to a value by printing @samp{$@var{num} = } | |
2583 | before the value; here @var{num} is the history number. | |
2584 | ||
2585 | To refer to any previous value, use @samp{$} followed by the value's | |
2586 | history number. The output printed by @samp{print} is designed to remind | |
2587 | you of this. Just @code{$} refers to the most recent value in the history, | |
2588 | and @code{$$} refers to the value before that. | |
2589 | ||
2590 | For example, suppose you have just printed a pointer to a structure and | |
2591 | want to see the contents of the structure. It suffices to type | |
2592 | ||
2593 | @example | |
2594 | p *$ | |
2595 | @end example | |
2596 | ||
2597 | If you have a chain of structures where the component @samp{next} points | |
2598 | to the next one, you can print the contents of the next one with this: | |
2599 | ||
2600 | @example | |
2601 | p *$.next | |
2602 | @end example | |
2603 | ||
2604 | @noindent | |
2605 | It might be useful to repeat this command many times by typing @key{RET}. | |
2606 | ||
2607 | Note that the history records values, not expressions. If the value of | |
2608 | @code{x} is 4 and you type this command: | |
2609 | ||
2610 | @example | |
2611 | print x | |
2612 | set x=5 | |
2613 | @end example | |
2614 | ||
2615 | @noindent | |
2616 | then the value recorded in the value history by the @samp{print} command | |
2617 | remains 4 even though the value of @code{x} has changed. | |
2618 | ||
2619 | @table @code | |
2620 | @item info values | |
2621 | @kindex info values | |
2622 | Print the last ten values in the value history, with their item | |
2623 | numbers. This is like @samp{p $$9} repeated ten times, except that | |
2624 | @samp{info values} does not change the history. | |
2625 | ||
2626 | @item info values @var{n} | |
2627 | Print ten history values centered on history item number @var{n}. | |
2628 | ||
2629 | @item info values + | |
2630 | Print ten history values just after the values last printed. | |
2631 | @end table | |
2632 | ||
2633 | @node Convenience Vars, Registers, Value History, Data | |
2634 | @section Convenience Variables | |
2635 | ||
2636 | @cindex convenience variables | |
2637 | GDB provides @dfn{convenience variables} that you can use within GDB to | |
2638 | hold on to a value and refer to it later. These variables exist entirely | |
2639 | within GDB; they are not part of your program, and setting a convenience | |
2640 | variable has no effect on further execution of your program. That's why | |
2641 | you can use them freely. | |
2642 | ||
2643 | Convenience variables have names starting with @samp{$}. Any name starting | |
2644 | with @samp{$} can be used for a convenience variable, unless it is one of | |
2645 | the predefined set of register names (@pxref{Registers}). | |
2646 | ||
2647 | You can save a value in a convenience variable with an assignment | |
2648 | expression, just as you would set a variable in your program. Example: | |
2649 | ||
2650 | @example | |
2651 | set $foo = *object_ptr | |
2652 | @end example | |
2653 | ||
2654 | @noindent | |
2655 | would save in @code{$foo} the value contained in the object pointed to by | |
2656 | @code{object_ptr}. | |
2657 | ||
2658 | Using a convenience variable for the first time creates it; but its value | |
2659 | is @code{void} until you assign a new value. You can alter the value with | |
2660 | another assignment at any time. | |
2661 | ||
2662 | Convenience variables have no fixed types. You can assign a convenience | |
2663 | variable any type of value, even if it already has a value of a different | |
2664 | type. The convenience variable as an expression has whatever type its | |
2665 | current value has. | |
2666 | ||
2667 | @table @code | |
2668 | @item info convenience | |
2669 | @kindex info convenience | |
2670 | Print a list of convenience variables used so far, and their values. | |
2671 | Abbreviated @samp{i con}. | |
2672 | @end table | |
2673 | ||
2674 | One of the ways to use a convenience variable is as a counter to be | |
2675 | incremented or a pointer to be advanced. For example: | |
2676 | ||
2677 | @example | |
2678 | set $i = 0 | |
2679 | print bar[$i++]->contents | |
2680 | @i{@dots{}repeat that command by typing @key{RET}.} | |
2681 | @end example | |
2682 | ||
2683 | Some convenience variables are created automatically by GDB and given | |
2684 | values likely to be useful. | |
2685 | ||
2686 | @table @code | |
2687 | @item $_ | |
2688 | The variable @code{$_} is automatically set by the @samp{x} command to | |
2689 | the last address examined (@pxref{Memory}). Other commands which | |
2690 | provide a default address for @samp{x} to examine also set @code{$_} | |
2691 | to that address; these commands include @samp{info line} and @samp{info | |
2692 | breakpoint}. | |
2693 | ||
2694 | @item $__ | |
2695 | The variable @code{$__} is automatically set by the @samp{x} command | |
2696 | to the value found in the last address examined. | |
2697 | @end table | |
2698 | ||
2699 | @node Registers,, Convenience Vars, Data | |
2700 | @section Registers | |
2701 | ||
2702 | @cindex registers | |
2703 | Machine register contents can be referred to in expressions as variables | |
2704 | with names starting with @samp{$}. The names of registers are different | |
2705 | for each machine; use @samp{info registers} to see the names used on your | |
2706 | machine. The names @code{$pc} and @code{$sp} are used on all machines for | |
2707 | the program counter register and the stack pointer. Often @code{$fp} is | |
2708 | used for a register that contains a pointer to the current stack frame, | |
2709 | and @code{$ps} is used for a register that contains the processor | |
2710 | status. These standard register names may be available on your machine | |
2711 | even though the @code{info registers} command displays them with a | |
2712 | different name. For example, on the SPARC, @code{info registers} | |
2713 | displays the processor status register as @code{$psr} but you can also | |
2714 | refer to it as @code{$ps}. | |
2715 | ||
2716 | GDB always considers the contents of an ordinary register as an integer | |
2717 | when the register is examined in this way. Some machines have special | |
2718 | registers which can hold nothing but floating point; these registers are | |
2719 | considered floating point. There is no way to refer to the contents of an | |
2720 | ordinary register as floating point value (although you can @emph{print} | |
2721 | it as a floating point value with @samp{print/f $@var{regname}}). | |
2722 | ||
2723 | Some registers have distinct ``raw'' and ``virtual'' data formats. This | |
2724 | means that the data format in which the register contents are saved by the | |
2725 | operating system is not the same one that your program normally sees. For | |
2726 | example, the registers of the 68881 floating point coprocessor are always | |
2727 | saved in ``extended'' format, but all C programs expect to work with | |
2728 | ``double'' format. In such cases, GDB normally works with the virtual | |
2729 | format only (the format that makes sense for your program), but the | |
2730 | @samp{info registers} command prints the data in both formats. | |
2731 | ||
2732 | Register values are relative to the selected stack frame | |
2733 | (@pxref{Selection}). This means that you get the value that the register | |
2734 | would contain if all stack frames farther in were exited and their saved | |
2735 | registers restored. In order to see the real contents of all registers, | |
2736 | you must select the innermost frame (with @samp{frame 0}). | |
2737 | ||
2738 | Some registers are never saved (typically those numbered zero or one) | |
2739 | because they are used for returning function values; for these registers, | |
2740 | relativization makes no difference. | |
2741 | ||
2742 | @table @code | |
2743 | @item info registers | |
2744 | @kindex info registers | |
2745 | Print the names and relativized values of all registers. | |
2746 | ||
2747 | @item info registers @var{regname} | |
2748 | Print the relativized value of register @var{regname}. @var{regname} | |
2749 | may be any register name valid on the machine you are using, with | |
2750 | or without the initial @samp{$}. | |
2751 | @end table | |
2752 | ||
2753 | @subsection Examples | |
2754 | ||
2755 | You could print the program counter in hex with | |
2756 | ||
2757 | @example | |
2758 | p/x $pc | |
2759 | @end example | |
2760 | ||
2761 | @noindent | |
2762 | or print the instruction to be executed next with | |
2763 | ||
2764 | @example | |
2765 | x/i $pc | |
2766 | @end example | |
2767 | ||
2768 | @noindent | |
2769 | or add four to the stack pointer with | |
2770 | ||
2771 | @example | |
2772 | set $sp += 4 | |
2773 | @end example | |
2774 | ||
2775 | @noindent | |
2776 | The last is a way of removing one word from the stack, on machines where | |
2777 | stacks grow downward in memory (most machines, nowadays). This assumes | |
2778 | that the innermost stack frame is selected. Setting @code{$sp} is | |
2779 | not allowed when other stack frames are selected. | |
2780 | ||
2781 | @node Symbols, Altering, Data, Top | |
2782 | @chapter Examining the Symbol Table | |
2783 | ||
2784 | The commands described in this section allow you to make inquiries for | |
2785 | information about the symbols (names of variables, functions and types) | |
2786 | defined in your program. This information is found by GDB in the symbol | |
2787 | table loaded by the @samp{symbol-file} command; it is inherent in the text | |
2788 | of your program and does not change as the program executes. | |
2789 | ||
2790 | @table @code | |
2791 | @item whatis @var{exp} | |
2792 | @kindex whatis | |
2793 | Print the data type of expression @var{exp}. @var{exp} is not | |
2794 | actually evaluated, and any side-effecting operations (such as | |
2795 | assignments or function calls) inside it do not take place. | |
2796 | @xref{Expressions}. | |
2797 | ||
2798 | @item whatis | |
2799 | Print the data type of @code{$}, the last value in the value history. | |
2800 | ||
2801 | @item info address @var{symbol} | |
2802 | @kindex info address | |
2803 | Describe where the data for @var{symbol} is stored. For a register | |
2804 | variable, this says which register it is kept in. For a non-register | |
2805 | local variable, this prints the stack-frame offset at which the variable | |
2806 | is always stored. | |
2807 | ||
2808 | Note the contrast with @samp{print &@var{symbol}}, which does not work | |
2809 | at all for a register variables, and for a stack local variable prints | |
2810 | the exact address of the current instantiation of the variable. | |
2811 | ||
2812 | @item ptype @var{typename} | |
2813 | @kindex ptype | |
2814 | Print a description of data type @var{typename}. @var{typename} may be | |
2815 | the name of a type, or for C code it may have the form | |
2816 | @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or | |
2817 | @samp{enum @var{enum-tag}}.@refill | |
2818 | ||
2819 | @item info sources | |
2820 | @kindex info sources | |
2821 | Print the names of all source files in the program for which there | |
2822 | is debugging information. | |
2823 | ||
2824 | @item info functions | |
2825 | @kindex info functions | |
2826 | Print the names and data types of all defined functions. | |
2827 | ||
2828 | @item info functions @var{regexp} | |
2829 | Print the names and data types of all defined functions | |
2830 | whose names contain a match for regular expression @var{regexp}. | |
2831 | Thus, @samp{info fun step} finds all functions whose names | |
2832 | include @samp{step}; @samp{info fun ^step} finds those whose names | |
2833 | start with @samp{step}. | |
2834 | ||
2835 | @item info variables | |
2836 | @kindex info variables | |
2837 | Print the names and data types of all variables that are declared | |
2838 | outside of functions (i.e., except for local variables). | |
2839 | ||
2840 | @item info variables @var{regexp} | |
2841 | Print the names and data types of all variables (except for local | |
2842 | variables) whose names contain a match for regular expression | |
2843 | @var{regexp}. | |
2844 | ||
2845 | @item info types | |
2846 | @kindex info types | |
2847 | Print all data types that are defined in the program. | |
2848 | ||
2849 | @item info types @var{regexp} | |
2850 | Print all data types that are defined in the program whose names | |
2851 | contain a match for regular expression @var{regexp}. | |
2852 | ||
2853 | @ignore | |
2854 | This was never implemented. | |
2855 | @item info methods | |
2856 | @itemx info methods @var{regexp} | |
2857 | @kindex info methods | |
2858 | The @samp{info-methods} command permits the user to examine all defined | |
2859 | methods within C++ program, or (with the @var{regexp} argument) a | |
2860 | specific set of methods found in the various C++ classes. Many | |
2861 | C++ classes provide a large number of methods. Thus, the output | |
2862 | from the @samp{ptype} command can be overwhelming and hard to use. The | |
2863 | @samp{info-methods} command filters the methods, printing only those | |
2864 | which match the regular-expression @var{regexp}. | |
2865 | @end ignore | |
2866 | ||
2867 | @item printsyms @var{filename} | |
2868 | @kindex printsyms | |
2869 | Write a complete dump of the debugger's symbol data into the | |
2870 | file @var{filename}. | |
2871 | @end table | |
2872 | ||
2873 | @node Altering, Sequences, Symbols, Top | |
2874 | @chapter Altering Execution | |
2875 | ||
2876 | Once you think you have find an error in the program, you might want to | |
2877 | find out for certain whether correcting the apparent error would lead to | |
2878 | correct results in the rest of the run. You can find the answer by | |
2879 | experiment, using the GDB features for altering execution of the | |
2880 | program. | |
2881 | ||
2882 | For example, you can store new values into variables or memory | |
2883 | locations, give the program a signal, restart it at a different address, | |
2884 | or even return prematurely from a function to its caller. | |
2885 | ||
2886 | @menu | |
2887 | * Assignment:: Altering variable values or memory contents. | |
2888 | * Jumping:: Altering control flow. | |
2889 | * Signaling:: Making signals happen in the program. | |
2890 | * Returning:: Making a function return prematurely. | |
2891 | @end menu | |
2892 | ||
2893 | @node Assignment, Jumping, Altering, Altering | |
2894 | @section Assignment to Variables | |
2895 | ||
2896 | @cindex assignment | |
2897 | @cindex setting variables | |
2898 | To alter the value of a variable, evaluate an assignment expression. | |
2899 | @xref{Expressions}. For example, | |
2900 | ||
2901 | @example | |
2902 | print x=4 | |
2903 | @end example | |
2904 | ||
2905 | @noindent | |
2906 | would store the value 4 into the variable @code{x}, and then print | |
2907 | the value of the assignment expression (which is 4). | |
2908 | ||
2909 | All the assignment operators of C are supported, including the | |
2910 | incrementation operators @samp{++} and @samp{--}, and combining | |
2911 | assignments such as @samp{+=} and @samp{<<=}. | |
2912 | ||
2913 | @kindex set | |
2914 | @kindex set variable | |
2915 | If you are not interested in seeing the value of the assignment, use the | |
2916 | @samp{set} command instead of the @samp{print} command. @samp{set} is | |
2917 | really the same as @samp{print} except that the expression's value is not | |
2918 | printed and is not put in the value history (@pxref{Value History}). The | |
2919 | expression is evaluated only for side effects. | |
2920 | ||
2921 | Note that if the beginning of the argument string of the @samp{set} command | |
2922 | appears identical to a @samp{set} subcommand, it may be necessary to use | |
2923 | the @samp{set variable} command. This command is identical to @samp{set} | |
2924 | except for its lack of subcommands. | |
2925 | ||
2926 | GDB allows more implicit conversions in assignments than C does; you can | |
2927 | freely store an integer value into a pointer variable or vice versa, and | |
2928 | any structure can be converted to any other structure that is the same | |
2929 | length or shorter. | |
2930 | ||
2931 | To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} | |
2932 | construct to generate a value of specified type at a specified address | |
2933 | (@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer | |
2934 | to memory location 0x83040 as an integer (which implies a certain size | |
2935 | and representation in memory), and | |
2936 | ||
2937 | @example | |
2938 | set @{int@}0x83040 = 4 | |
2939 | @end example | |
2940 | ||
2941 | would store the value 4 into that memory location. | |
2942 | ||
2943 | @node Jumping, Signaling, Assignment, Altering | |
2944 | @section Continuing at a Different Address | |
2945 | ||
2946 | Ordinarily, when you continue the program, you do so at the place where | |
2947 | it stopped, with the @samp{cont} command. You can instead continue at | |
2948 | an address of your own choosing, with the following commands: | |
2949 | ||
2950 | @table @code | |
2951 | @item jump @var{linenum} | |
2952 | @kindex jump | |
2953 | Resume execution at line number @var{linenum}. Execution may stop | |
2954 | immediately if there is a breakpoint there. | |
2955 | ||
2956 | The @samp{jump} command does not change the current stack frame, or | |
2957 | the stack pointer, or the contents of any memory location or any | |
2958 | register other than the program counter. If line @var{linenum} is in | |
2959 | a different function from the one currently executing, the results may | |
2960 | be bizarre if the two functions expect different patterns of arguments or | |
2961 | of local variables. For this reason, the @samp{jump} command requests | |
2962 | confirmation if the specified line is not in the function currently | |
2963 | executing. However, even bizarre results are predictable based on | |
2964 | careful study of the machine-language code of the program. | |
2965 | ||
2966 | @item jump *@var{address} | |
2967 | Resume execution at the instruction at address @var{address}. | |
2968 | @end table | |
2969 | ||
2970 | You can get much the same effect as the @code{jump} command by storing a | |
2971 | new value into the register @code{$pc}. The difference is that this | |
2972 | does not start the program running; it only changes the address where it | |
2973 | @emph{will} run when it is continued. For example, | |
2974 | ||
2975 | @example | |
2976 | set $pc = 0x485 | |
2977 | @end example | |
2978 | ||
2979 | @noindent | |
2980 | causes the next @samp{cont} command or stepping command to execute at | |
2981 | address 0x485, rather than at the address where the program stopped. | |
2982 | @xref{Stepping}. | |
2983 | ||
2984 | The most common occasion to use the @samp{jump} command is when you have | |
2985 | stepped across a function call with @code{next}, and found that the | |
2986 | return value is incorrect. If all the relevant data appeared correct | |
2987 | before the function call, the error is probably in the function that | |
2988 | just returned. | |
2989 | ||
2990 | In general, your next step would now be to rerun the program and execute | |
2991 | up to this function call, and then step into it to see where it goes | |
2992 | astray. But this may be time consuming. If the function did not have | |
2993 | significant side effects, you could get the same information by resuming | |
2994 | execution just before the function call and stepping through it. To do this, | |
2995 | first put a breakpoint on that function; then, use the @samp{jump} command | |
2996 | to continue on the line with the function call. | |
2997 | ||
2998 | @node Signaling, Returning, Jumping, Altering | |
2999 | @section Giving the Program a Signal | |
3000 | ||
3001 | @table @code | |
3002 | @item signal @var{signalnum} | |
3003 | @kindex signal | |
3004 | Resume execution where the program stopped, but give it immediately the | |
3005 | signal number @var{signalnum}. | |
3006 | ||
3007 | Alternatively, if @var{signalnum} is zero, continue execution without | |
3008 | giving a signal. This is useful when the program stopped on account of | |
3009 | a signal and would ordinary see the signal when resumed with the | |
3010 | @samp{cont} command; @samp{signal 0} causes it to resume without a | |
3011 | signal. | |
3012 | @end table | |
3013 | ||
3014 | @node Returning,, Signaling, Altering | |
3015 | @section Returning from a Function | |
3016 | ||
3017 | @cindex returning from a function | |
3018 | @kindex return | |
3019 | You can cancel execution of a function call with the @samp{return} | |
3020 | command. This command has the effect of discarding the selected stack | |
3021 | frame (and all frames within it), so that control moves to the caller of | |
3022 | that function. You can think of this as making the discarded frame | |
3023 | return prematurely. | |
3024 | ||
3025 | First select the stack frame that you wish to return from | |
3026 | (@pxref{Selection}). Then type the @samp{return} command. If you wish | |
3027 | to specify the value to be returned, give that as an argument. | |
3028 | ||
3029 | This pops the selected stack frame (and any other frames inside of it), | |
3030 | leaving its caller as the innermost remaining frame. That frame becomes | |
3031 | selected. The specified value is stored in the registers used for | |
3032 | returning values of functions. | |
3033 | ||
3034 | The @samp{return} command does not resume execution; it leaves the | |
3035 | program stopped in the state that would exist if the function had just | |
3036 | returned. Contrast this with the @samp{finish} command | |
3037 | (@pxref{Stepping}), which resumes execution until the selected stack | |
3038 | frame returns @emph{naturally}. | |
3039 | ||
3040 | @node Sequences, Options, Altering, Top | |
3041 | @chapter Canned Sequences of Commands | |
3042 | ||
3043 | GDB provides two ways to store sequences of commands for execution as a | |
3044 | unit: user-defined commands and command files. | |
3045 | ||
3046 | @menu | |
3047 | * Define:: User-defined commands. | |
3048 | * Command Files:: Command files. | |
3049 | * Output:: Controlled output commands useful in | |
3050 | user-defined commands and command files. | |
3051 | @end menu | |
3052 | ||
3053 | @node Define, Command Files, Sequences, Sequences | |
3054 | @section User-Defined Commands | |
3055 | ||
3056 | @cindex user-defined command | |
3057 | A @dfn{user-defined command} is a sequence of GDB commands to which you | |
3058 | assign a new name as a command. This is done with the @samp{define} | |
3059 | command. | |
3060 | ||
3061 | @table @code | |
3062 | @item define @var{commandname} | |
3063 | @kindex define | |
3064 | Define a command named @var{commandname}. If there is already a command | |
3065 | by that name, you are asked to confirm that you want to redefine it. | |
3066 | ||
3067 | The definition of the command is made up of other GDB command lines, | |
3068 | which are given following the @samp{define} command. The end of these | |
3069 | commands is marked by a line containing @samp{end}. | |
3070 | ||
3071 | @item document @var{commandname} | |
3072 | @kindex document | |
3073 | Give documentation to the user-defined command @var{commandname}. The | |
3074 | command @var{commandname} must already be defined. This command reads | |
3075 | lines of documentation just as @samp{define} reads the lines of the | |
3076 | command definition, ending with @samp{end}. After the @samp{document} | |
3077 | command is finished, @samp{help} on command @var{commandname} will print | |
3078 | the documentation you have specified. | |
3079 | ||
3080 | You may use the @samp{document} command again to change the | |
3081 | documentation of a command. Redefining the command with @samp{define} | |
3082 | does not change the documentation. | |
3083 | @end table | |
3084 | ||
3085 | User-defined commands do not take arguments. When they are executed, the | |
3086 | commands of the definition are not printed. An error in any command | |
3087 | stops execution of the user-defined command. | |
3088 | ||
3089 | Commands that would ask for confirmation if used interactively proceed | |
3090 | without asking when used inside a user-defined command. Many GDB commands | |
3091 | that normally print messages to say what they are doing omit the messages | |
3092 | when used in user-defined command. | |
3093 | ||
3094 | @node Command Files, Output, Define, Sequences | |
3095 | @section Command Files | |
3096 | ||
3097 | @cindex command files | |
3098 | A command file for GDB is a file of lines that are GDB commands. Comments | |
3099 | (lines starting with @samp{#}) may also be included. An empty line in a | |
3100 | command file does nothing; it does not mean to repeat the last command, as | |
3101 | it would from the terminal. | |
3102 | ||
3103 | @cindex init file | |
3104 | @cindex @file{.gdbinit} | |
3105 | When GDB starts, it automatically executes its @dfn{init files}, command | |
3106 | files named @file{.gdbinit}. GDB reads the init file (if any) in your home | |
3107 | directory and then the init file (if any) in the current working | |
3108 | directory. (The init files are not executed if the @samp{-nx} option | |
3109 | is given.) You can also request the execution of a command file with the | |
3110 | @samp{source} command: | |
3111 | ||
3112 | @table @code | |
3113 | @item source @var{filename} | |
3114 | @kindex source | |
3115 | Execute the command file @var{filename}. | |
3116 | @end table | |
3117 | ||
3118 | The lines in a command file are executed sequentially. They are not | |
3119 | printed as they are executed. An error in any command terminates execution | |
3120 | of the command file. | |
3121 | ||
3122 | Commands that would ask for confirmation if used interactively proceed | |
3123 | without asking when used in a command file. Many GDB commands that | |
3124 | normally print messages to say what they are doing omit the messages | |
3125 | when used in a command file. | |
3126 | ||
3127 | @node Output,, Command Files, Sequences | |
3128 | @section Commands for Controlled Output | |
3129 | ||
3130 | During the execution of a command file or a user-defined command, the only | |
3131 | output that appears is what is explicitly printed by the commands of the | |
3132 | definition. This section describes three commands useful for generating | |
3133 | exactly the output you want. | |
3134 | ||
3135 | @table @code | |
3136 | @item echo @var{text} | |
3137 | @kindex echo | |
3138 | @comment I don't consider backslash-space a standard C escape sequence | |
3139 | @comment because it's not in ANSI. | |
3140 | Print @var{text}. Nonprinting characters can be included in @var{text} | |
3141 | using C escape sequences, such as @samp{\n} to print a newline. @b{No | |
3142 | newline will be printed unless you specify one.} In addition to the | |
3143 | standard C escape sequences a backslash followed by a space stands for a | |
3144 | space. This is useful for outputting a string with spaces at the | |
3145 | beginning or the end, since leading and trailing spaces are trimmed from | |
3146 | all arguments. Thus, to print @w{`` and foo = ''}, use the command | |
3147 | @w{``echo \ and foo = \ ''}. | |
3148 | @comment AAARGGG! How am I supposed to do @samp{ and foo = } and not | |
3149 | @comment have the spaces be invisible in TeX? | |
3150 | ||
3151 | A backslash at the end of @var{text} can be used, as in C, to continue | |
3152 | the command onto subsequent lines. For example, | |
3153 | ||
3154 | @example | |
3155 | echo This is some text\n\ | |
3156 | which is continued\n\ | |
3157 | onto several lines.\n | |
3158 | @end example | |
3159 | ||
3160 | produces the same output as | |
3161 | ||
3162 | @example | |
3163 | echo This is some text\n | |
3164 | echo which is continued\n | |
3165 | echo onto several lines.\n | |
3166 | @end example | |
3167 | ||
3168 | @item output @var{expression} | |
3169 | @kindex output | |
3170 | Print the value of @var{expression} and nothing but that value: no | |
3171 | newlines, no @samp{$@var{nn} = }. The value is not entered in the | |
3172 | value history either. @xref{Expressions} for more information on | |
3173 | expressions. | |
3174 | ||
3175 | @item output/@var{fmt} @var{expression} | |
3176 | Print the value of @var{expression} in format @var{fmt}. | |
3177 | @xref{Output formats}, for more information. | |
3178 | ||
3179 | @item printf @var{string}, @var{expressions}@dots{} | |
3180 | @kindex printf | |
3181 | Print the values of the @var{expressions} under the control of | |
3182 | @var{string}. The @var{expressions} are separated by commas and may | |
3183 | be either numbers or pointers. Their values are printed as specified | |
3184 | by @var{string}, exactly as if the program were to execute | |
3185 | ||
3186 | @example | |
3187 | printf (@var{string}, @var{expressions}@dots{}); | |
3188 | @end example | |
3189 | ||
3190 | For example, you can print two values in hex like this: | |
3191 | ||
3192 | @example | |
3193 | printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo | |
3194 | @end example | |
3195 | ||
3196 | The only backslash-escape sequences that you can use in the string are | |
3197 | the simple ones that consist of backslash followed by a letter. | |
3198 | @end table | |
3199 | ||
3200 | @node Options, Emacs, Sequences, Top | |
3201 | @chapter Options and Arguments for GDB | |
3202 | ||
3203 | When you invoke GDB, you can specify arguments telling it what files to | |
3204 | operate on and what other things to do. | |
3205 | ||
3206 | @menu | |
3207 | * Mode Options:: Options controlling modes of operation. | |
3208 | * File Options:: Options to specify files (executable, coredump, commands) | |
3209 | * Other Arguments:: Any other arguments without options | |
3210 | also specify files. | |
3211 | @end menu | |
3212 | ||
3213 | @node Mode Options, File Options, Options, Options | |
3214 | @section Mode Options | |
3215 | ||
3216 | @table @samp | |
3217 | @item -nx | |
3218 | Do not execute commands from the init files @file{.gdbinit}. | |
3219 | Normally, the commands in these files are executed after all the | |
3220 | command options and arguments have been processed. @xref{Command | |
3221 | Files}. | |
3222 | ||
3223 | @item -q | |
3224 | ``Quiet''. Do not print the usual introductory messages. | |
3225 | ||
3226 | @item -batch | |
3227 | Run in batch mode. Exit with code 0 after processing all the command | |
3228 | files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited). | |
3229 | Exit with nonzero status if an error occurs in executing the GDB | |
3230 | commands in the command files. | |
3231 | ||
3232 | @item -fullname | |
3233 | This option is used when Emacs runs GDB as a subprocess. It tells GDB | |
3234 | to output the full file name and line number in a standard, | |
3235 | recognizable fashion each time a stack frame is displayed (which | |
3236 | includes each time the program stops). This recognizable format looks | |
3237 | like two @samp{\032} characters, followed by the file name, line number | |
3238 | and character position separated by colons, and a newline. The | |
3239 | Emacs-to-GDB interface program uses the two @samp{\032} characters as | |
3240 | a signal to display the source code for the frame. | |
3241 | @end table | |
3242 | ||
3243 | @node File Options, Other Arguments, Mode Options, Options | |
3244 | @section File-specifying Options | |
3245 | ||
3246 | All the options and command line arguments given are processed | |
3247 | in sequential order. The order makes a difference when the | |
3248 | @samp{-x} option is used. | |
3249 | ||
3250 | @table @samp | |
3251 | @item -s @var{file} | |
3252 | Read symbol table from file @var{file}. | |
3253 | ||
3254 | @item -e @var{file} | |
3255 | Use file @var{file} as the executable file to execute when | |
3256 | appropriate, and for examining pure data in conjunction with a core | |
3257 | dump. | |
3258 | ||
3259 | @item -se @var{file} | |
3260 | Read symbol table from file @var{file} and use it as the executable | |
3261 | file. | |
3262 | ||
3263 | @item -c @var{file} | |
3264 | Use file @var{file} as a core dump to examine. | |
3265 | ||
3266 | @item -x @var{file} | |
3267 | Execute GDB commands from file @var{file}. | |
3268 | ||
3269 | @item -d @var{directory} | |
3270 | Add @var{directory} to the path to search for source files. | |
3271 | @end table | |
3272 | ||
3273 | @node Other Arguments,, File Options, Options | |
3274 | @section Other Arguments | |
3275 | ||
3276 | If there are arguments to GDB that are not options or associated with | |
3277 | options, the first one specifies the symbol table and executable file name | |
3278 | (as if it were preceded by @samp{-se}) and the second one specifies a core | |
3279 | dump file name (as if it were preceded by @samp{-c}). | |
3280 | ||
3281 | @node Emacs, Remote, Options, Top | |
3282 | @chapter Using GDB under GNU Emacs | |
3283 | ||
3284 | A special interface allows you to use GNU Emacs to view (and | |
3285 | edit) the source files for the program you are debugging with | |
3286 | GDB. | |
3287 | ||
3288 | To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the | |
3289 | executable file you want to debug as an argument. This command starts | |
3290 | GDB as a subprocess of Emacs, with input and output through a newly | |
3291 | created Emacs buffer. | |
3292 | ||
3293 | Using GDB under Emacs is just like using GDB normally except for two | |
3294 | things: | |
3295 | ||
3296 | @itemize @bullet | |
3297 | @item | |
3298 | All ``terminal'' input and output goes through the Emacs buffer. This | |
3299 | applies both to GDB commands and their output, and to the input and | |
3300 | output done by the program you are debugging. | |
3301 | ||
3302 | This is useful because it means that you can copy the text of previous | |
3303 | commands and input them again; you can even use parts of the output | |
3304 | in this way. | |
3305 | ||
3306 | All the facilities of Emacs's Shell mode are available for this purpose. | |
3307 | ||
3308 | @item | |
3309 | GDB displays source code through Emacs. Each time GDB displays a | |
3310 | stack frame, Emacs automatically finds the source file for that frame | |
3311 | and puts an arrow (@samp{=>}) at the left margin of the current line. | |
3312 | ||
3313 | Explicit GDB @samp{list} or search commands still produce output as | |
3314 | usual, but you probably will have no reason to use them. | |
3315 | @end itemize | |
3316 | ||
3317 | In the GDB I/O buffer, you can use these special Emacs commands: | |
3318 | ||
3319 | @table @kbd | |
3320 | @item M-s | |
3321 | Execute to another source line, like the GDB @samp{step} command. | |
3322 | ||
3323 | @item M-n | |
3324 | Execute to next source line in this function, skipping all function | |
3325 | calls, like the GDB @samp{next} command. | |
3326 | ||
3327 | @item M-i | |
3328 | Execute one instruction, like the GDB @samp{stepi} command. | |
3329 | ||
3330 | @item C-c C-f | |
3331 | Execute until exit from the selected stack frame, like the GDB | |
3332 | @samp{finish} command. | |
3333 | ||
3334 | @item M-c | |
3335 | @comment C-c C-p in emacs 19 | |
3336 | Continue execution of the program, like the GDB @samp{cont} command. | |
3337 | ||
3338 | @item M-u | |
3339 | @comment C-c C-u in emacs 19 | |
3340 | Go up the number of frames indicated by the numeric argument | |
3341 | (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}), | |
3342 | like the GDB @samp{up} command.@refill | |
3343 | ||
3344 | @item M-d | |
3345 | @comment C-c C-d in emacs 19 | |
3346 | Go down the number of frames indicated by the numeric argument, like the | |
3347 | GDB @samp{down} command. | |
3348 | @end table | |
3349 | ||
3350 | In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) | |
3351 | tells GDB to set a breakpoint on the source line point is on. | |
3352 | ||
3353 | The source files displayed in Emacs are in ordinary Emacs buffers | |
3354 | which are visiting the source files in the usual way. You can edit | |
3355 | the files with these buffers if you wish; but keep in mind that GDB | |
3356 | communicates with Emacs in terms of line numbers. If you add or | |
3357 | delete lines from the text, the line numbers that GDB knows will cease | |
3358 | to correspond properly to the code. | |
3359 | ||
3360 | @node Remote, Commands, Emacs, Top | |
3361 | @chapter Remote Kernel Debugging | |
3362 | ||
3363 | If you are trying to debug a program running on a machine that can't run | |
3364 | GDB in the usual way, it is often useful to use remote debugging. For | |
3365 | example, you might be debugging an operating system kernel, or debugging | |
3366 | a small system which does not have a general purpose operating system | |
3367 | powerful enough to run a full-featured debugger. Currently GDB supports | |
3368 | remote debugging over a serial connection. | |
3369 | ||
3370 | The program to be debugged on the remote machine needs to contain a | |
3371 | debugging device driver which talks to GDB over the serial line using the | |
3372 | protocol described below. The same version of GDB that is used ordinarily | |
3373 | can be used for this. Several sample remote debugging drivers are | |
3374 | distributed with GDB; see the @file{README} file in the GDB distribution for | |
3375 | more information. | |
3376 | ||
3377 | @menu | |
3378 | * Remote Commands:: Commands used to start and finish remote debugging. | |
3379 | @end menu | |
3380 | ||
3381 | For details of the communication protocol, see the comments in the GDB | |
3382 | source file @file{remote.c}. | |
3383 | ||
3384 | @node Remote Commands,, Remote, Remote | |
3385 | @section Commands for Remote Debugging | |
3386 | ||
3387 | To start remote debugging, first run GDB and specify as an executable file | |
3388 | the program that is running in the remote machine. This tells GDB how | |
3389 | to find the program's symbols and the contents of its pure text. Then | |
3390 | establish communication using the @samp{attach} command with a device | |
3391 | name rather than a pid as an argument. For example: | |
3392 | ||
3393 | @example | |
3394 | attach /dev/ttyd | |
3395 | @end example | |
3396 | ||
3397 | @noindent | |
3398 | if the serial line is connected to the device named @file{/dev/ttyd}. This | |
3399 | will stop the remote machine if it is not already stopped. | |
3400 | ||
3401 | Now you can use all the usual commands to examine and change data and to | |
3402 | step and continue the remote program. | |
3403 | ||
3404 | To resume the remote program and stop debugging it, use the @samp{detach} | |
3405 | command. | |
3406 | ||
3407 | @ignore | |
3408 | This material will be merged in when better Readline documentation | |
3409 | is done. | |
3410 | ||
3411 | @node GDB Readline, History Top ,Readline Top, Command Editing | |
3412 | @subsection GDB Readline | |
3413 | ||
3414 | You may control the behavior of command line editing in GDB with the | |
3415 | following commands: | |
3416 | ||
3417 | @table @code | |
3418 | @kindex set editing | |
3419 | @item set editing | |
3420 | @itemx set editing on | |
3421 | Enable command line editing (enabled by default). | |
3422 | ||
3423 | @item set editing off | |
3424 | Disable command line editing. | |
3425 | ||
3426 | @kindex set history file | |
3427 | @item set history file @var{filename} | |
3428 | Set the name of the GDB command history file to @var{filename}. This is | |
3429 | the file from which GDB will read an initial command history | |
3430 | list or to which it will write this list when it exits. This list is | |
3431 | accessed through history expansion or through the history | |
3432 | command editing characters listed below. This file defaults to the | |
3433 | value of the environmental variable @code{GDBHISTFILE}, or to | |
3434 | @code{./.gdb_history} if this variable is not set. | |
3435 | ||
3436 | @kindex set history write | |
3437 | @item set history write | |
3438 | @itemx set history write on | |
3439 | Enable the writing of the command history to the command history file | |
3440 | named above. This is enabled by default. | |
3441 | ||
3442 | @item set history write off | |
3443 | Disable the writing of the command history to the command history file. | |
3444 | ||
3445 | @kindex set history size | |
3446 | @item set history size @var{size} | |
3447 | Set the number of commands which GDB will keep in its history list. | |
3448 | This defaults to the value of the environmental variable | |
3449 | @code{HISTSIZE}, or to 256 if this variable is not set. | |
3450 | ||
3451 | @kindex info editing | |
3452 | @item info editing | |
3453 | Display the current settings relating to command line editing, and also | |
3454 | display the last ten commands in the command history. | |
3455 | ||
3456 | @item info editing @var{n} | |
3457 | Print ten commands centered on command number @var{n}. | |
3458 | ||
3459 | @item info editing + | |
3460 | Print ten commands just after the commands last printed. | |
3461 | @end table | |
3462 | ||
3463 | @node GDB History, , History Top, Command editing | |
3464 | @comment node-name, next, previous, up | |
3465 | Note that because of the additional meaning of @code{!} to GDB (as the | |
3466 | logical not operator in C), history expansion is off by default. If you | |
3467 | decide to enable history expansion with the @samp{set history expansion | |
3468 | on} command, you will need to follow @samp{!} with a space or a tab to | |
3469 | prevent it from being expanded. | |
3470 | ||
3471 | The commands to control history expansion are: | |
3472 | ||
3473 | @table @code | |
3474 | ||
3475 | @kindex set history expansion | |
3476 | @item set history expansion on | |
3477 | @itemx set history expansion | |
3478 | Enable history expansion. | |
3479 | ||
3480 | @item set history expansion off | |
3481 | Disable history expansion. History expansion is off by default. | |
3482 | ||
3483 | @end table | |
3484 | @end ignore | |
3485 | ||
3486 | @node Commands, Concepts, Remote, Top | |
3487 | @unnumbered Command Index | |
3488 | ||
3489 | @printindex ky | |
3490 | ||
3491 | @node Concepts, , Commands, Top | |
3492 | @unnumbered Concept Index | |
3493 | ||
3494 | @printindex cp | |
3495 | ||
3496 | @contents | |
3497 | @bye | |
3498 | ||
3499 | ||
3500 | ||
3501 | ||
3502 | Occasionally it is useful to execute a shell command from within GDB. | |
3503 | This can be done with the @samp{shell} command. | |
3504 | ||
3505 | @table @code | |
3506 | @item shell @var{shell command string} | |
3507 | @kindex shell | |
3508 | @cindex shell escape | |
3509 | Directs GDB to invoke an inferior shell to execute @var{shell command string}. | |
3510 | The environment variable @code{SHELL} is used if it exists, otherwise GDB | |
3511 | uses @samp{/bin/sh}. | |
3512 | @end table |