3 @settitle GDB, The GNU Debugger
6 This file documents the GNU debugger GDB.
8 Copyright (C) 1988, 1989 Free Software Foundation, Inc.
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.
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).
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
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
35 @setchapternewpage odd
39 @center @titlefont{GDB}
41 @center The GNU Source-Level Debugger
43 @center Third Edition, GDB version 4.0
47 @center Richard M. Stallman
48 @center (Revised by Cygnus Support)
51 @par@hskip -@parfillskip@hfill $Revision$
52 @par@hskip -@parfillskip@hfill @TeX{}info @texinfoversion
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1988, 1989, 1990 Free Software Foundation, Inc.
56 Permission is granted to make and distribute verbatim copies of
57 this manual provided the copyright notice and this permission notice
58 are preserved on all copies.
60 Permission is granted to copy and distribute modified versions of this
61 manual under the conditions for verbatim copying, provided also that the
62 section entitled ``GNU General Public License'' is included exactly as
63 in the original, and provided that the entire resulting derived work is
64 distributed under the terms of a permission notice identical to this
67 Permission is granted to copy and distribute translations of this manual
68 into another language, under the above conditions for modified versions,
69 except that the section entitled ``GNU General Public License'' may be
70 included in a translation approved by the author instead of in the
75 @node Top, Top, Top, (DIR)
76 @unnumbered Summary of GDB
78 The purpose of a debugger such as GDB is to allow you to execute another
79 program while examining what is going on inside it. We call the other
80 program ``your program'' or ``the program being debugged''.
82 GDB can do four kinds of things (plus other things in support of these):
86 Start the program, specifying anything that might affect its behavior.
89 Make the program stop on specified conditions.
92 Examine what has happened, when the program has stopped, so that you
96 Change things in the program, so you can correct the effects of one bug
97 and go on to learn about another without having to recompile first.
100 GDB can be used to debug programs written in C and C++. Pascal support
101 is being implemented, and Fortran support will be added when a GNU
102 Fortran compiler is written.
105 * License:: The GNU General Public License gives you permission
106 to redistribute GDB on certain terms; and also
107 explains that there is no warranty.
108 * User Interface:: GDB command syntax and input and output conventions.
109 * Files:: Specifying files for GDB to operate on.
110 * Options:: GDB arguments and options.
111 * Compilation::Compiling your program so you can debug it.
112 * Running:: Running your program under GDB.
113 * Stopping:: Making your program stop. Why it may stop. What to do then.
114 * Stack:: Examining your program's stack.
115 * Source:: Examining your program's source files.
116 * Data:: Examining data in your program.
117 * Symbols:: Examining the debugger's symbol table.
118 * Altering:: Altering things in your program.
119 * Sequences:: Canned command sequences for repeated use.
120 * Emacs:: Using GDB through GNU Emacs.
121 * Remote:: Remote kernel debugging across a serial line.
122 * GDB Bugs:: How to report bugs (if you want to get them fixed).
123 * Commands:: Index of GDB commands.
124 * Concepts:: Index of GDB concepts.
127 @node License, User Interface, Top, Top
128 @unnumbered GNU GENERAL PUBLIC LICENSE
129 @center Version 1, February 1989
132 Copyright @copyright{} 1989 Free Software Foundation, Inc.
133 675 Mass Ave, Cambridge, MA 02139, USA
135 Everyone is permitted to copy and distribute verbatim copies
136 of this license document, but changing it is not allowed.
139 @unnumberedsec Preamble
141 The license agreements of most software companies try to keep users
142 at the mercy of those companies. By contrast, our General Public
143 License is intended to guarantee your freedom to share and change free
144 software---to make sure the software is free for all its users. The
145 General Public License applies to the Free Software Foundation's
146 software and to any other program whose authors commit to using it.
147 You can use it for your programs, too.
149 When we speak of free software, we are referring to freedom, not
150 price. Specifically, the General Public License is designed to make
151 sure that you have the freedom to give away or sell copies of free
152 software, that you receive source code or can get it if you want it,
153 that you can change the software or use pieces of it in new free
154 programs; and that you know you can do these things.
156 To protect your rights, we need to make restrictions that forbid
157 anyone to deny you these rights or to ask you to surrender the rights.
158 These restrictions translate to certain responsibilities for you if you
159 distribute copies of the software, or if you modify it.
161 For example, if you distribute copies of a such a program, whether
162 gratis or for a fee, you must give the recipients all the rights that
163 you have. You must make sure that they, too, receive or can get the
164 source code. And you must tell them their rights.
166 We protect your rights with two steps: (1) copyright the software, and
167 (2) offer you this license which gives you legal permission to copy,
168 distribute and/or modify the software.
170 Also, for each author's protection and ours, we want to make certain
171 that everyone understands that there is no warranty for this free
172 software. If the software is modified by someone else and passed on, we
173 want its recipients to know that what they have is not the original, so
174 that any problems introduced by others will not reflect on the original
175 authors' reputations.
177 The precise terms and conditions for copying, distribution and
181 @unnumberedsec TERMS AND CONDITIONS
184 @center TERMS AND CONDITIONS
189 This License Agreement applies to any program or other work which
190 contains a notice placed by the copyright holder saying it may be
191 distributed under the terms of this General Public License. The
192 ``Program'', below, refers to any such program or work, and a ``work based
193 on the Program'' means either the Program or any work containing the
194 Program or a portion of it, either verbatim or with modifications. Each
195 licensee is addressed as ``you''.
198 You may copy and distribute verbatim copies of the Program's source
199 code as you receive it, in any medium, provided that you conspicuously and
200 appropriately publish on each copy an appropriate copyright notice and
201 disclaimer of warranty; keep intact all the notices that refer to this
202 General Public License and to the absence of any warranty; and give any
203 other recipients of the Program a copy of this General Public License
204 along with the Program. You may charge a fee for the physical act of
208 You may modify your copy or copies of the Program or any portion of
209 it, and copy and distribute such modifications under the terms of Paragraph
210 1 above, provided that you also do the following:
214 cause the modified files to carry prominent notices stating that
215 you changed the files and the date of any change; and
218 cause the whole of any work that you distribute or publish, that
219 in whole or in part contains the Program or any part thereof, either
220 with or without modifications, to be licensed at no charge to all
221 third parties under the terms of this General Public License (except
222 that you may choose to grant warranty protection to some or all
223 third parties, at your option).
226 If the modified program normally reads commands interactively when
227 run, you must cause it, when started running for such interactive use
228 in the simplest and most usual way, to print or display an
229 announcement including an appropriate copyright notice and a notice
230 that there is no warranty (or else, saying that you provide a
231 warranty) and that users may redistribute the program under these
232 conditions, and telling the user how to view a copy of this General
236 You may charge a fee for the physical act of transferring a
237 copy, and you may at your option offer warranty protection in
241 Mere aggregation of another independent work with the Program (or its
242 derivative) on a volume of a storage or distribution medium does not bring
243 the other work under the scope of these terms.
246 You may copy and distribute the Program (or a portion or derivative of
247 it, under Paragraph 2) in object code or executable form under the terms of
248 Paragraphs 1 and 2 above provided that you also do one of the following:
252 accompany it with the complete corresponding machine-readable
253 source code, which must be distributed under the terms of
254 Paragraphs 1 and 2 above; or,
257 accompany it with a written offer, valid for at least three
258 years, to give any third party free (except for a nominal charge
259 for the cost of distribution) a complete machine-readable copy of the
260 corresponding source code, to be distributed under the terms of
261 Paragraphs 1 and 2 above; or,
264 accompany it with the information you received as to where the
265 corresponding source code may be obtained. (This alternative is
266 allowed only for noncommercial distribution and only if you
267 received the program in object code or executable form alone.)
270 Source code for a work means the preferred form of the work for making
271 modifications to it. For an executable file, complete source code means
272 all the source code for all modules it contains; but, as a special
273 exception, it need not include source code for modules which are standard
274 libraries that accompany the operating system on which the executable
275 file runs, or for standard header files or definitions files that
276 accompany that operating system.
279 You may not copy, modify, sublicense, distribute or transfer the
280 Program except as expressly provided under this General Public License.
281 Any attempt otherwise to copy, modify, sublicense, distribute or transfer
282 the Program is void, and will automatically terminate your rights to use
283 the Program under this License. However, parties who have received
284 copies, or rights to use copies, from you under this General Public
285 License will not have their licenses terminated so long as such parties
286 remain in full compliance.
289 By copying, distributing or modifying the Program (or any work based
290 on the Program) you indicate your acceptance of this license to do so,
291 and all its terms and conditions.
294 Each time you redistribute the Program (or any work based on the
295 Program), the recipient automatically receives a license from the original
296 licensor to copy, distribute or modify the Program subject to these
297 terms and conditions. You may not impose any further restrictions on the
298 recipients' exercise of the rights granted herein.
301 The Free Software Foundation may publish revised and/or new versions
302 of the General Public License from time to time. Such new versions will
303 be similar in spirit to the present version, but may differ in detail to
304 address new problems or concerns.
306 Each version is given a distinguishing version number. If the Program
307 specifies a version number of the license which applies to it and ``any
308 later version'', you have the option of following the terms and conditions
309 either of that version or of any later version published by the Free
310 Software Foundation. If the Program does not specify a version number of
311 the license, you may choose any version ever published by the Free Software
315 If you wish to incorporate parts of the Program into other free
316 programs whose distribution conditions are different, write to the author
317 to ask for permission. For software which is copyrighted by the Free
318 Software Foundation, write to the Free Software Foundation; we sometimes
319 make exceptions for this. Our decision will be guided by the two goals
320 of preserving the free status of all derivatives of our free software and
321 of promoting the sharing and reuse of software generally.
331 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
332 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
333 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
334 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
335 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
336 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
337 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
338 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
339 REPAIR OR CORRECTION.
342 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
343 ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
344 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
345 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
346 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
347 LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
348 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
349 WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
350 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
354 @heading END OF TERMS AND CONDITIONS
357 @center END OF TERMS AND CONDITIONS
361 @unnumberedsec Appendix: How to Apply These Terms to Your New Programs
363 If you develop a new program, and you want it to be of the greatest
364 possible use to humanity, the best way to achieve this is to make it
365 free software which everyone can redistribute and change under these
368 To do so, attach the following notices to the program. It is safest to
369 attach them to the start of each source file to most effectively convey
370 the exclusion of warranty; and each file should have at least the
371 ``copyright'' line and a pointer to where the full notice is found.
374 @var{one line to give the program's name and a brief idea of what it does.}
375 Copyright (C) 19@var{yy} @var{name of author}
377 This program is free software; you can redistribute it and/or modify
378 it under the terms of the GNU General Public License as published by
379 the Free Software Foundation; either version 1, or (at your option)
382 This program is distributed in the hope that it will be useful,
383 but WITHOUT ANY WARRANTY; without even the implied warranty of
384 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
385 GNU General Public License for more details.
387 You should have received a copy of the GNU General Public License
388 along with this program; if not, write to the Free Software
389 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
392 Also add information on how to contact you by electronic and paper mail.
394 If the program is interactive, make it output a short notice like this
395 when it starts in an interactive mode:
398 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
399 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
400 This is free software, and you are welcome to redistribute it
401 under certain conditions; type `show c' for details.
404 The hypothetical commands `show w' and `show c' should show the
405 appropriate parts of the General Public License. Of course, the
406 commands you use may be called something other than `show w' and `show
407 c'; they could even be mouse-clicks or menu items---whatever suits your
410 You should also get your employer (if you work as a programmer) or your
411 school, if any, to sign a ``copyright disclaimer'' for the program, if
412 necessary. Here a sample; alter the names:
415 Yoyodyne, Inc., hereby disclaims all copyright interest in the
416 program `Gnomovision' (a program to direct compilers to make passes
417 at assemblers) written by James Hacker.
419 @var{signature of Ty Coon}, 1 April 1989
420 Ty Coon, President of Vice
423 That's all there is to it!
425 @node User Interface, Files, License, Top
426 @chapter GDB Input and Output Conventions
428 GDB is invoked with the shell command @samp{gdb}. Once started, it reads
429 commands from the terminal until you tell it to exit.
431 A GDB command is a single line of input. There is no limit on how long
432 it can be. It starts with a command name, which is followed by arguments
433 whose meaning depends on the command name. For example, the command
434 @samp{step} accepts an argument which is the number of times to step,
435 as in @samp{step 5}. You can also use the @samp{step} command with
436 no arguments. Some command names do not allow any arguments.
439 GDB command names may always be abbreviated if the abbreviation is
440 unambiguous. Sometimes even ambiguous abbreviations are allowed; for
441 example, @samp{s} is specially defined as equivalent to @samp{step}
442 even though there are other commands whose names start with @samp{s}.
443 Possible command abbreviations are often stated in the documentation
444 of the individual commands.
446 @cindex repeating commands
447 A blank line as input to GDB means to repeat the previous command verbatim.
448 Certain commands do not allow themselves to be repeated this way; these are
449 commands for which unintentional repetition might cause trouble and which
450 you are unlikely to want to repeat. Certain others (@samp{list} and
451 @samp{x}) act differently when repeated because that is more useful.
453 A line of input starting with @samp{#} is a comment; it does nothing.
454 This is useful mainly in command files (@xref{Command Files}).
457 GDB indicates its readiness to read a command by printing a string
458 called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can
459 change the prompt string with the @samp{set prompt} command. For
460 instance, when debugging GDB with GDB, it is useful to change the prompt
461 in one of the GDBs so that you tell which one you are talking to.
464 @item set prompt @var{newprompt}
466 Directs GDB to use @samp{newprompt} as its prompt string henceforth.
469 Prints the line: Gdb's prompt is: @samp{your-prompt}
474 To exit GDB, use the @samp{quit} command (abbreviated @samp{q}), or type
475 an end-of-file character (usually @ctrl{d}). An interrupt (often
476 @ctrl{c}) will not exit from GDB, but rather will terminate the action
477 of any GDB command that is in progress and return to GDB command level.
478 It is safe to type the interrupt character at any time because GDB does
479 not allow it to take effect until a time when it is safe.
482 @cindex command line editing
483 @cindex history substitution
484 GDB now reads its input commands via the @code{readline} interface.
485 This GNU library provides consistant behaviour for programs which
486 provide a command line interface to the user. From the point
487 of view of the user, the advantages are @samp{emacs}-style or @samp{vi}-style
488 inline editing of commands, @samp{csh}-like history substitution,
489 and a storage and recall of command history across debugging sessions.
491 You may control the behavior of command line editing in GDB with the
497 @itemx set editing on
498 Enable command line editing (enabled by default).
500 @item set editing off
501 Disable command line editing.
505 Display the current settings relating to command line editing, and also
506 display the last ten commands in the command history.
508 @item info editing @var{n}
509 Print ten commands centered on command number @var{n}.
512 Print ten commands just after the commands last printed.
514 @kindex set history file
515 @item set history file @var{filename}
516 Set the name of the GDB command history file to @samp{filename}. This is
517 the file from which GDB will read an initial command history
518 list or to which it will write this list when it exits. This list is
519 accessed through history expansion or through the history
520 command editing characters listed below. This file defaults to the
521 value of the environmental variable @code{GDBHISTFILE}, or to
522 @code{./.gdb_history} if this variable is not set.
524 @kindex set history write
525 @item set history write
526 @itemx set history write on
527 Make GDB record command history in a file, whose name may be specified with the
528 @samp{set history file} command. By default, this option is disabled.
530 @item set history write off
531 Make GDB stop recording command history in a file.
533 @kindex set history size
534 @item set history size @var{size}
535 Set the number of commands which GDB will keep in its history list.
536 This defaults to the value of the environmental variable
537 @code{HISTSIZE}, or to 256 if this variable is not set.
540 @cindex history expansion
542 The commands to control history expansion are:
546 @kindex set history expansion
547 @item set history expansion on
548 @itemx set history expansion
549 Enable history expansion. History expansion is off by default.
551 @item set history expansion off
552 Disable history expansion.
556 Because of the additional meaning of `@code{!}' to GDB (as the logical
557 not operator in C), history expansion is off by default. If you decide
558 to enable history expansion with the @samp{set history expansion on}
559 command, you will need to follow @samp{!} (when it is part of an
560 expression) with a space or a tab to prevent it from being expanded.
563 The @code{readline} code comes with more complete documentation of
564 editing and history expansion features. Users unfamiliar with @samp{emacs}
565 or @samp{vi} may wish to read it. @xref{Command Line Editing}.
567 Occasionally it is useful to execute a shell command from within GDB.
568 This can be done with the @samp{shell} command.
571 @item shell @var{command string}
574 Directs GDB to invoke an inferior shell to execute @var{command string}.
575 The environment variable @code{SHELL} is used if it exists, otherwise GDB
578 @item make @var{target}
581 Causes GDB to execute an inferior @code{make} program with the specified
582 arguments. This is equivalent to @samp{shell make @var{target}}.
586 @cindex pauses in output
587 Certain commands to GDB may produce large amounts of information output
588 to the screen. To help you read all of it, GDB pauses and asks you for
589 input at the end of each page of output. Type @key{RET} when you want
590 to continue the output. Normally GDB knows the size of the screen from
591 the termcap data base together with the value of the @code{TERM}
592 environment variable and the @code{stty rows} and @code{stty cols}
593 settings. If this is not correct, you can override it with
594 the @samp{set screen-height} and @samp{set screen-width} commands:
597 @item set screen-height @var{lpp}
598 @item set screen-width @var{cpl}
599 @kindex set screen-height
600 @kindex set screen-width
601 Specify a screen height of @var{lpp} lines and a screen width of
602 @var{cpl} characters.
604 If you specify a height of zero lines, GDB will not pause during output
605 no matter how long the output is. This is useful if output is to a file
606 or to an editor buffer.
609 By default, GDB is silent about its inner workings. If you are running
610 on a slow machine, you may want to use the @samp{set verbose} command.
611 It will make GDB tell you when it does a lengthy internal operation, so
612 you won't think it has crashed.
614 Currently, the messages controlled by @samp{set verbose} are those which
615 announce that the symbol table for a source file is being read
616 (@pxref{File Commands}, in the description of the command
618 @c The following is the right way to do it, but emacs 18.55 doesn't support
619 @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
622 see @samp{symbol-file} in @ref{File Commands}).
628 Enables GDB's output of certain informational messages.
630 @item set verbose off
631 Disables GDB's output of certain informational messages.
635 By default, GDB asks what sometimes seem to be a lot of stupid
636 questions. For example, if you try to run a program which is already
641 The program being debugged has been started already.
642 Start it from the beginning? (y or n)
645 If you're willing to unflinchingly face the consequences of your own
646 commands, you can disable this ``feature'':
649 @kindex set stupidity
651 @cindex stupid questions
652 @item set stupidity off
653 Disables stupid questions.
655 @item set stupidity on
656 Enables stupid questions (the default).
659 @node Files, Compilation, User Interface, Top
660 @chapter Specifying GDB's Files
662 @cindex core dump file
663 @cindex executable file
665 GDB needs to know the file name of the program to be debugged, both in
666 order to read its symbol table and in order to start the program. To
667 debug a core dump of a previous run, GDB must be told the file name of
671 * Arguments: File Arguments. Specifying files with arguments
672 (when you start GDB).
673 * Commands: File Commands. Specifying files with GDB commands.
676 @node File Arguments, File Commands, Files, Files
677 @section Specifying Files with Arguments
679 The usual way to specify the executable and core dump file names is with
680 two command arguments given when you start GDB. The first argument is used
681 as the file for execution and symbols, and the second argument (if any) is
682 used as the core dump file name. Thus,
689 specifies @file{progm} as the executable program and @file{core} as a core
690 dump file to examine. (You do not need to have a core dump file if what
691 you plan to do is debug the program interactively.)
693 @xref{Options}, for full information on options and arguments for
696 @node File Commands,, File Arguments, Files
697 @section Specifying Files with Commands
699 Usually you specify the files for GDB to work with by giving arguments when
700 you invoke GDB. But occasionally it is necessary to change to a different
701 file during a GDB session. Or you may run GDB and forget to specify the
702 files you want to use. In these situations the GDB commands to specify new
706 @item file @var{filename}
708 Use @var{file} as the program to be debugged. It is read for its
709 symbols, for getting the contents of pure memory, and it is the program
710 executed when you use the @samp{run} command. If you do not specify a
711 directory and the file is not found in GDB's working directory, GDB will
712 use the environment variable @code{PATH} as a list of directories to
713 search, just as the shell does when looking for a program to run.
715 @samp{file} with no argument makes both executable file and symbol
716 table become unspecified.
718 @item exec-file @var{filename}
720 Specify that the program to be run (but not the symbol table) is found
721 in @var{filename}. GDB will search the environment variable @code{PATH}
722 if necessary to locate the program.
724 @item symbol-file @var{filename}
726 Read symbol table information from file @var{filename}. @code{PATH} is
727 searched when necessary. Use the @samp{file} command to get both symbol
728 table and program to run from the same file.
730 @samp{symbol-file} with no argument clears out GDB's symbol table.
732 On some systems, the @samp{symbol-file} command does not actually read
733 the symbol table in full right away. Instead, it scans the symbol table
734 quickly to find which source files and which symbols are present. The
735 details are read later, one source file at a time, when they are needed.
737 The purpose of this two-stage reading strategy is to make GDB start up
738 faster. For the most part, it is invisible except for occasional pauses
739 while the symbol table details for a particular source file are being
740 read. (The @samp{set verbose} command can turn these pauses into
741 messages if desired. @xref{User Interface}).
743 When the symbol table is stored in COFF format, @samp{symbol-file} does
744 read the symbol table data in full right away. We haven't bothered to
745 implement the two-stage strategy for COFF yet.
747 @item core @var{filename}
749 Specify the whereabouts of a core dump file to be used as the
750 ``contents of memory''. Note that the core dump contains only the
751 writable parts of memory; the read-only parts must come from the
754 @samp{core-file} with no argument specifies that no core file is
757 Note that the core file is ignored when your program is actually running
758 under GDB. So, if you have been running the program and you wish to
759 debug a core file instead, you must kill the subprocess in which the
760 program is running. To do this, use the @samp{kill} command
761 (@pxref{Kill Process}).
763 @item add-file @var{filename} @var{address}
764 @itemx load @var{filename} @var{address}
767 @cindex dynamic linking
768 The @samp{add-file} command reads additional symbol table information
769 from the file @var{filename}. You would use this when that file has
770 been dynamically loaded into the program that is running. @var{address}
771 should be the memory address at which the file has been loaded; GDB cannot
772 figure this out for itself.
774 When debugging with some targets (@pxref{Targets}), this command will
775 also cause the file to be dynamically loaded into the target system.
776 @comment FIXME: "some" is obnoxious. Currently this is only VxWorks.
777 @comment ---pesch 18dec1990
779 The symbol table of the file @var{filename} is added to the symbol table
780 originally read with the @samp{symbol-file} command. You can use the
781 @samp{add-file} command any number of times; the new symbol data thus
782 read keeps adding to the old. The @samp{symbol-file} command forgets
783 all the symbol data GDB has read.
787 Print the names of the executable and core dump files currently in
788 use by GDB, and the file from which symbols were loaded, as well as the
789 stack of current targets (@pxref{Targets}).
793 While all three file-specifying commands allow both absolute and relative
794 file names as arguments, GDB always converts the file name to an absolute
795 one and remembers it that way.
797 The @samp{symbol-file} command causes GDB to forget the contents of its
798 convenience variables, the value history, and all breakpoints and
799 auto-display expressions. This is because they may contain pointers to the
800 internal data recording symbols and data types, which are part of the old
801 symbol table data being discarded inside GDB.
803 @kindex shared-library
805 @cindex shared libraries
807 GDB supports the SunOS shared library format. Symbols from a shared
808 library cannot be referenced before the shared library has been linked
809 with the program. (That is to say, after one types @samp{run} and
810 the function @code{main()} has been entered; or when examining core
811 files.) Once the shared library has been linked in, you can use the
815 @item sharedlibrary @var{regex}
816 @itemx share @var{regex}
817 Load shared object library symbols for files matching a UNIX regular
822 Load symbols for all shared libraries.
825 @itemx info sharedlibrary
826 @kindex info sharedlibrary
828 Print the names of the shared libraries which are currently loaded.
832 @node Compilation, Targets, Files, Top
833 @chapter Compiling Your Program for Debugging
835 In order to debug a program effectively, you need to ask for debugging
836 information when you compile it. This information in the object file
837 describes the data type of each variable or function and the correspondence
838 between source line numbers and addresses in the executable code.
840 To request debugging information, specify the @samp{-g} option when you run
843 The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
844 together. This means that you cannot ask for optimization if you ask for
845 debugger information.
847 The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
848 possible to debug optimized code. We recommend that you @emph{always} use
849 @samp{-g} whenever you compile a program. You may think the program is
850 correct, but there's no sense in pushing your luck.
852 Some things do not work as well with @samp{-g -O} as with just
853 @samp{-g}, particularly on machines with instruction scheduling. If in
854 doubt, recompile with @samp{-g} alone, and if this fixes the problem,
855 please report it as a bug (including a test case---@pxref{GDB Bugs}).
857 Older versions of the GNU C compiler, GCC, permitted a variant option
858 @samp{-gg} for debugging information. GDB no longer supports this format;
859 if your GNU C compiler has this option, do not use it.
862 @comment As far as I know, there are no cases in which GDB will
863 @comment produce strange output in this case. (but no promises).
864 If your program includes archives made with the @code{ar} program, and
865 if the object files used as input to @code{ar} were compiled without the
866 @samp{-g} option and have names longer than 15 characters, GDB will get
867 confused reading the program's symbol table. No error message will be
868 given, but GDB may behave strangely. The reason for this problem is a
869 deficiency in the Unix archive file format, which cannot represent file
870 names longer than 15 characters.
872 To avoid this problem, compile the archive members with the @samp{-g}
873 option or use shorter file names. Alternatively, use a version of GNU
874 @code{ar} dated more recently than August 1989.
877 @node Targets, Running, Compilation, Top
878 @chapter Specifying a Debugging Target
879 @cindex debugging target
881 Often, you will be able to run GDB in the same host environment as the
882 program you are debugging; in that case, the debugging target is
883 specified as a side effect of the @samp{file} or @samp{core} commands.
884 When you need more flexibility---for example, running GDB on a
885 physically separate host, controlling standalone systems over a
886 serial port, or realtime systems over a TCP/IP connection---you can use
887 the @samp{target} command.
890 @item target @var{type} @var{parameters}
891 Connects the GDB host environment to a target machine or process. A
892 target is typically a protocol for talking to debugging facilities. You
893 use the argument @var{type} to specify the type or protocol of the
894 target machine; for example, @samp{target child} for Unix child processes, or
895 @samp{target vxworks} for a TCP/IP link to a VxWorks system.
897 Further @var{parameters} are interpreted by the target protocol, but
898 typically include things like device names or host names to connect
899 with, process numbers, and baud rates. Executing
904 @noindent{}(without any parameters) will issue a message about what
905 parameters are required for that target type.
909 Targets are managed as a stack, so that you may (for example) specify
910 a core file as a target without abandoning a running program; when
911 you're done with the core file, you can return to the previous target
912 using @samp{detach}. The related command @samp{attach} provides you
913 with an alternative way of stacking a new target. @xref{Attach}.
917 Displays the names of all targets available.
920 To display the targets currently stacked, use the @samp{info files}
921 command (@pxref{File Commands}).
923 @node Running, Stopping, Targets, Top
924 @chapter Running Your Program Under GDB
928 To start your program under GDB, use the @samp{run} command. Except on
929 VxWorks, the program must already have been specified using the
930 @samp{file} or @samp{exec-file} command, or with an argument to GDB
931 (@pxref{Files}); what @samp{run} does is create an inferior process,
932 load the program into it, and set it in motion.
934 The execution of a program is affected by certain information it
935 receives from its superior. GDB provides ways to specify this
936 information, which you must do @i{before} starting the program. (You
937 can change it after starting the program, but such changes do not affect
938 the program unless you start it over again.) This information may be
939 divided into three categories:
942 @item The @i{arguments.}
943 You specify the arguments to give the program as the arguments of the
946 @item The @i{environment.}
947 The program normally inherits its environment from GDB, but you can
948 use the GDB commands @samp{set environment} and
949 @samp{unset environment} to change parts of the environment that will
950 be given to the program.@refill
952 @item The @i{working directory.}
953 The program inherits its working directory from GDB. You can set GDB's
954 working directory with the @samp{cd} command in GDB.
957 When you issue the @samp{run} command, your program begins to execute
958 immediately. @xref{Stopping}, for discussion of how to arrange for your
961 Note that once your program has been started by the @samp{run} command,
962 you may evaluate expressions that involve calls to functions in the
963 inferior, using the @samp{print} or @samp{call} commands. @xref{Data}.
965 If your program's timestamp has changed since the last time GDB read its
966 symbols, GDB will discard its symbol table and re-read it from your
967 program. In this process, it tries to retain your current breakpoints.
970 * Arguments:: Specifying the arguments for your program.
971 * Environment:: Specifying the environment for your program.
972 * Working Directory:: Specifying the working directory for giving
973 to your program when it is run.
974 * Input/Output:: Specifying the program's standard input and output.
975 * Attach:: Debugging a process started outside GDB.
976 * Kill Process:: Getting rid of the child process running your program.
979 @node Arguments, Environment, Running, Running
980 @section Your Program's Arguments
982 @cindex arguments (to your program)
983 The arguments to your program are specified by the arguments of the
984 @samp{run} command. They are passed to a shell, which expands wildcard
985 characters and performs redirection of I/O, and thence to the program.
987 @samp{run} with no arguments uses the same arguments used by the previous
991 The command @samp{set args} can be used to specify the arguments to be used
992 the next time the program is run. If @samp{set args} has no arguments, it
993 means to use no arguments the next time the program is run. If you have
994 run your program with arguments and want to run it again with no arguments,
995 this is the only way to do so.
997 @node Environment, Working Directory, Arguments, Running
998 @section Your Program's Environment
1000 @cindex environment (of your program)
1001 The @dfn{environment} consists of a set of @dfn{environment variables} and
1002 their values. Environment variables conventionally record such things as
1003 your user name, your home directory, your terminal type, and your search
1004 path for programs to run. Usually you set up environment variables with
1005 the shell and they are inherited by all the other programs you run. When
1006 debugging, it can be useful to try running the program with different
1007 environments without having to start the debugger over again.
1010 @item info environment @var{varname}
1011 @kindex info environment
1012 Print the value of environment variable @var{varname} to be given to
1013 your program when it is started. This command can be abbreviated
1014 @samp{i env @var{varname}}.
1016 @item info environment
1017 Print the names and values of all environment variables to be given to
1018 your program when it is started. This command can be abbreviated
1021 @item set environment @var{varname} @var{value}
1022 @itemx set environment @var{varname} = @var{value}
1023 @kindex set environment
1024 Sets environment variable @var{varname} to @var{value}, for your program
1025 only, not for GDB itself. @var{value} may be any string; the values of
1026 environment variables are just strings, and any interpretation is
1027 supplied by your program itself. The @var{value} parameter is optional;
1028 if it is eliminated, the variable is set to a null value. This command
1029 can be abbreviated as @samp{set e}.
1031 For example, this command:
1038 tells the program, when subsequently run, to assume it is being run
1039 on behalf of the user named @samp{foo}.
1041 @item delete environment @var{varname}
1042 @itemx unset environment @var{varname}
1043 @kindex delete environment
1044 @kindex unset environment
1045 Remove variable @var{varname} from the environment to be passed to your
1046 program. This is different from @samp{set env @var{varname}@ =} because
1047 @samp{delete environment} leaves the variable with no value, which is
1048 distinguishable from an empty value. This command can be abbreviated
1052 @node Working Directory, Input/Output, Environment, Running
1053 @section Your Program's Working Directory
1055 @cindex working directory (of your program)
1056 Each time you start your program with @samp{run}, it inherits its
1057 working directory from the current working directory of GDB. GDB's
1058 working directory is initially whatever it inherited from its parent
1059 process (typically the shell), but you can specify a new working
1060 directory in GDB with the @samp{cd} command.
1062 The GDB working directory also serves as a default for the commands
1063 that specify files for GDB to operate on. @xref{Files}.
1066 @item cd @var{directory}
1068 Set GDB's working directory to @var{directory}.
1072 Print GDB's working directory.
1075 @node Input/Output, Attach, Working Directory, Running
1076 @section Your Program's Input and Output
1079 @cindex controlling terminal
1080 By default, the program you run under GDB does input and output to the same
1081 terminal that GDB uses.
1083 You can redirect the program's input and/or output using @samp{sh}-style
1084 redirection commands in the @samp{run} command. For example,
1091 starts the program, diverting its output to the file @file{outfile}.
1094 Another way to specify where the program should do input and output is
1095 with the @samp{tty} command. This command accepts a file name as
1096 argument, and causes this file to be the default for future @samp{run}
1097 commands. It also resets the controlling terminal for the child
1098 process, for future @samp{run} commands. For example,
1105 directs that processes started with subsequent @samp{run} commands
1106 default to do input and output on the terminal @file{/dev/ttyb} and have
1107 that as their controlling terminal.
1109 An explicit redirection in @samp{run} overrides the @samp{tty} command's
1110 effect on input/output redirection, but not its effect on the
1111 controlling terminal.
1113 When you use the @samp{tty} command or redirect input in the @samp{run}
1114 command, only the @emph{input for your program} is affected. The input
1115 for GDB still comes from your terminal.
1117 @node Attach, Kill Process, Input/Output, Running
1118 @section Debugging an Already-Running Process
1124 @item attach @var{process--id}
1125 @itemx attach @var{device}
1126 This command attaches to another target, of the same type as your last
1127 @samp{target} command (@samp{info files} will show your target stack).
1128 The command may take as argument a process ID or a device file.
1130 You specify a process ID to debug an already-running process that was
1131 started outside of GDB. (The usual way to find out the process-id of
1132 the process is with the @code{ps} utility, or with the @code{jobs -l}
1133 shell command.) In this case, you must have permission to send the
1134 process a signal, and it must have the same effective user ID as the
1138 When using @samp{attach}, you should first use the @samp{file} command
1139 to specify the program running in the process and load its symbol table.
1141 The first thing GDB does after arranging to debug the process is to stop
1142 it. You can examine and modify an attached process with all the GDB
1143 commands that ordinarily available when you start processes with
1144 @samp{run}. You can insert breakpoints; you can step and continue; you
1145 can modify storage. If you would rather the process continue running,
1146 you may use the @samp{continue} command after attaching GDB to the
1149 When you have finished debugging the attached process, you can use the
1150 @samp{detach} command to release it from GDB's control. Detaching
1151 the process continues its execution. After the @samp{detach} command,
1152 that process and GDB become completely independent once more, and you
1153 are ready to @samp{attach} another process or start one with @samp{run}.
1155 If you exit GDB or use the @samp{run} command while you have an attached
1156 process, you kill that process. By default, you will be asked for
1157 confirmation if you try to do either of these things; you can control
1158 whether or not this happens by using the @samp{set stupidity} command
1159 (@pxref{User Interface}).
1161 The @samp{attach} command is also used to debug a remote machine via a
1162 serial connection. @xref{Remote}, for more info.
1164 @node Kill Process,, Attach, Running
1165 @section Killing the Child Process
1170 Kill the child process in which the program being debugged is running
1174 This command is useful if you wish to debug a core dump instead. GDB
1175 ignores any core dump file if it is actually running the program, so the
1176 @samp{kill} command is the only sure way to make sure the core dump file
1179 On some operating systems, you can't execute your program in another
1180 process while it is active inside GDB. The @samp{kill} command is also
1181 useful in this situation, if you wish to run the program outside the
1184 The @samp{kill} command is also useful if you wish to recompile and
1185 relink the program, since on many systems it is impossible to modify an
1186 executable file which is running in a process. In this case, when you
1187 next type @samp{run}, GDB will notice that the file has changed, and
1188 will re-read the symbol table (while trying to preserve your current
1189 breakpoint settings).
1191 @node Stopping, Stack, Running, Top
1192 @chapter Stopping and Continuing
1194 When you run a program normally, it runs until it terminates. The
1195 principal purpose of using a debugger is so that you can stop it before
1196 that point; or so that if the program runs into trouble you can
1197 investigate and find out why.
1200 * Signals:: Fatal signals in your program just stop it;
1201 then you can use GDB to see what is going on.
1202 * Breakpoints:: Breakpoints let you stop your program when it
1203 reaches a specified point in the code.
1204 an expression changes.
1205 * Continuing:: Resuming execution until the next signal or breakpoint.
1206 * Stepping:: Stepping runs the program a short distance and
1207 then stops it wherever it has come to.
1210 @node Signals, Breakpoints, Stopping, Stopping
1214 A signal is an asynchronous event that can happen in a program. The
1215 operating system defines the possible kinds of signals, and gives each kind
1216 a name and a number. For example, @code{SIGINT} is the signal a program
1217 gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
1218 gets from referencing a place in memory far away from all the areas in use;
1219 @code{SIGALRM} occurs when the alarm clock timer goes off (which happens
1220 only if the program has requested an alarm).
1222 @cindex fatal signals
1223 Some signals, including @code{SIGALRM}, are a normal part of the
1224 functioning of the program. Others, such as @code{SIGSEGV}, indicate
1225 errors; these signals are @dfn{fatal} (kill the program immediately) if the
1226 program has not specified in advance some other way to handle the signal.
1227 @code{SIGINT} does not indicate an error in the program, but it is normally
1228 fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
1230 GDB has the ability to detect any occurrence of a signal in the program
1231 running under GDB's control. You can tell GDB in advance what to do for
1232 each kind of signal.
1234 @cindex handling signals
1235 Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM}
1236 (so as not to interfere with their role in the functioning of the program)
1237 but to stop the program immediately whenever an error signal happens.
1238 You can change these settings with the @samp{handle} command.
1243 Print a table of all the kinds of signals and how GDB has been told to
1244 handle each one. You can use this to see the signal numbers of all
1245 the defined types of signals.
1247 @item handle @var{signal} @var{keywords}@dots{}
1249 Change the way GDB handles signal @var{signal}. @var{signal} can be the
1250 number of a signal or its name (with or without the @samp{SIG} at the
1251 beginning). The @var{keywords} say what change to make.
1254 The keywords allowed by the handle command can be abbreviated. Their full
1259 GDB should stop the program when this signal happens. This implies
1260 the @samp{print} keyword as well.
1263 GDB should print a message when this signal happens.
1266 GDB should not stop the program when this signal happens. It may
1267 still print a message telling you that the signal has come in.
1270 GDB should not mention the occurrence of the signal at all. This
1271 implies the @samp{nostop} keyword as well.
1274 GDB should allow the program to see this signal; the program will be
1275 able to handle the signal, or may be terminated if the signal is fatal
1279 GDB should not allow the program to see this signal.
1282 When a signal has been set to stop the program, the program cannot see the
1283 signal until you continue. It will see the signal then, if @samp{pass} is
1284 in effect for the signal in question @i{at that time}. In other words,
1285 after GDB reports a signal, you can use the @samp{handle} command with
1286 @samp{pass} or @samp{nopass} to control whether that signal will be seen by
1287 the program when you later continue it.
1289 You can also use the @samp{signal} command to prevent the program from
1290 seeing a signal, or cause it to see a signal it normally would not see,
1291 or to give it any signal at any time. @xref{Signaling}.
1293 @node Breakpoints, Watchpoints Continuing, Signals, Stopping
1294 @section Breakpoints
1297 A @dfn{breakpoint} makes your program stop whenever a certain point in the
1298 program is reached. You set breakpoints explicitly with GDB commands,
1299 specifying the place where the program should stop by line number, function
1300 name or exact address in the program. You can add various other conditions
1301 to control whether the program will stop.
1303 Each breakpoint is assigned a number when it is created; these numbers are
1304 successive integers starting with 1. In many of the commands for controlling
1305 various features of breakpoints you use the breakpoint number to say which
1306 breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
1307 @dfn{disabled}; if disabled, it has no effect on the program until you
1314 The command @samp{info break} prints a list of all breakpoints set and not
1315 deleted, showing their numbers, where in the program they are, and any
1316 special features in use for them. Disabled breakpoints are included in the
1317 list, but marked as disabled. @samp{info break} with a breakpoint number
1318 as argument lists only that breakpoint. The convenience variable @code{$_}
1319 and the default examining-address for the @samp{x} command are set to the
1320 address of the last breakpoint listed (@pxref{Memory}).
1324 This command prints a list of watchpoints.
1327 A @dfn{watchpoint} is a special breakpoint that stops your program when
1328 the value of an expression changes. You can use a watchpoint to stop
1329 execution whenever the value of an expression changes, without having to
1330 predict a particular place in the inferior process where this may
1331 happen. Aside from the different syntax in setting a watchpoint, it is
1332 managed exactly like any other breakpoint and is enabled, disabled, and
1333 deleted exactly like any other breakpoint.
1340 * Set Breaks:: How to establish breakpoints.
1341 * Delete Breaks:: How to remove breakpoints no longer needed.
1342 * Disabling:: How to disable breakpoints (turn them off temporarily).
1343 * Conditions:: Making extra conditions on whether to stop.
1344 * Break Commands:: Commands to be executed at a breakpoint.
1345 * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
1348 @node Set Breaks, Delete Breaks, Breakpoints, Breakpoints
1349 @subsection Setting Breakpoints
1353 Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
1354 Watchpoints are set with the @samp{watch} command.
1356 You have several ways to say where the breakpoint should go.
1359 @item break @var{function}
1360 Set a breakpoint at entry to function @var{function}.
1362 @item break @var{+offset}
1363 @itemx break @var{-offset}
1364 Set a breakpoint some number of lines forward or back from the position
1365 at which execution stopped in the currently selected frame.
1367 @item break @var{linenum}
1368 Set a breakpoint at line @var{linenum} in the current source file.
1369 That file is the last file whose source text was printed. This
1370 breakpoint will stop the program just before it executes any of the
1373 @item break @var{filename}:@var{linenum}
1374 Set a breakpoint at line @var{linenum} in source file @var{filename}.
1376 @item break @var{filename}:@var{function}
1377 Set a breakpoint at entry to function @var{function} found in file
1378 @var{filename}. Specifying a file name as well as a function name is
1379 superfluous except when multiple files contain similarly named
1382 @item break *@var{address}
1383 Set a breakpoint at address @var{address}. You can use this to set
1384 breakpoints in parts of the program which do not have debugging
1385 information or source files.
1388 Set a breakpoint at the next instruction to be executed in the selected
1389 stack frame (@pxref{Stack}). In any selected frame but the innermost,
1390 this will cause the program to stop as soon as control returns to that
1391 frame. This is equivalent to a @samp{finish} command in the frame
1392 inside the selected frame. If this is done in the innermost frame, GDB
1393 will stop the next time it reaches the current location; this may be
1394 useful inside of loops.
1396 GDB normally ignores breakpoints when it resumes execution, until at
1397 least one instruction has been executed. If it did not do this, you
1398 would be unable to proceed past a breakpoint without first disabling the
1399 breakpoint. This rule applies whether or not the breakpoint already
1400 existed when the program stopped.
1402 @item break @dots{} if @var{cond}
1403 Set a breakpoint with condition @var{cond}; evaluate the expression
1404 @var{cond} each time the breakpoint is reached, and stop only if the
1405 value is nonzero. @samp{@dots{}} stands for one of the possible
1406 arguments described above (or no argument) specifying where to break.
1407 @xref{Conditions}, for more information on breakpoint conditions.
1409 @item tbreak @var{args}
1411 Set a breakpoint enabled only for one stop. @var{args} are the
1412 same as in the @samp{break} command, and the breakpoint is set in the same
1413 way, but the breakpoint is automatically disabled the first time it
1414 is hit. @xref{Disabling}.
1416 @item rbreak @var{regex}
1418 Set a breakpoint on all functions matching @var{regex}. This is
1419 useful for setting breakpoints on overloaded functions that are not
1420 members of any special classes. This command sets an unconditional
1421 breakpoint on all matches, printing a list of all breakpoints it set.
1422 Once these breakpoints are set, they are treated just like the
1423 breakpoints set with the @samp{break} command. They can be deleted,
1424 disabled, made conditional, etc., in the standard ways.
1427 @item watch @var{expr}
1428 Set a watchpoint for an expression.
1431 GDB allows you to set any number of breakpoints at the same place in the
1432 program. There is nothing silly or meaningless about this. When the
1433 breakpoints are conditional, this is even useful (@pxref{Conditions}).
1435 @node Delete Breaks, Disabling, Set Breaks, Breakpoints
1436 @subsection Deleting Breakpoints
1438 @cindex clearing breakpoints and watchpoints
1439 @cindex deleting breakpoints and watchpoints
1440 It is often necessary to eliminate a breakpoint once it has done its job
1441 and you no longer want the program to stop there. This is called
1442 @dfn{deleting} the breakpoint. A breakpoint that has been deleted no
1443 longer exists in any sense; it is forgotten.
1445 With the @samp{clear} command you can delete breakpoints according to where
1446 they are in the program. With the @samp{delete} command you can delete
1447 individual breakpoints by specifying their breakpoint numbers.
1449 @b{It is not necessary to delete a breakpoint to proceed past it.} GDB
1450 automatically ignores breakpoints in the first instruction to be executed
1451 when you continue execution without changing the execution address.
1456 Delete any breakpoints at the next instruction to be executed in the
1457 selected stack frame (@pxref{Selection}). When the innermost frame
1458 is selected, this is a good way to delete a breakpoint that the program
1461 @item clear @var{function}
1462 @itemx clear @var{filename}:@var{function}
1463 Delete any breakpoints set at entry to the function @var{function}.
1465 @item clear @var{linenum}
1466 @itemx clear @var{filename}:@var{linenum}
1467 Delete any breakpoints set at or within the code of the specified line.
1469 @item delete @var{bnums}@dots{}
1471 Delete the breakpoints of the numbers specified as arguments.
1474 @node Disabling, Conditions, Delete Breaks, Breakpoints
1475 @subsection Disabling Breakpoints
1477 @cindex disabled breakpoints
1478 @cindex enabled breakpoints
1479 Rather than deleting a breakpoint, you might prefer to @dfn{disable} it.
1480 This makes the breakpoint inoperative as if it had been deleted, but
1481 remembers the information on the breakpoint so that you can @dfn{enable}
1484 You disable and enable breakpoints with the @samp{enable} and
1485 @samp{disable} commands, specifying one or more breakpoint numbers as
1486 arguments. Use @samp{info break} to print a list of breakpoints if you
1487 don't know which breakpoint numbers to use.
1489 A breakpoint can have any of four different states of enablement:
1493 Enabled. The breakpoint will stop the program. A breakpoint made
1494 with the @samp{break} command starts out in this state.
1496 Disabled. The breakpoint has no effect on the program.
1498 Enabled once. The breakpoint will stop the program, but
1499 when it does so it will become disabled. A breakpoint made
1500 with the @samp{tbreak} command starts out in this state.
1502 Enabled for deletion. The breakpoint will stop the program, but
1503 immediately after it does so it will be deleted permanently.
1506 You can use the following commands to enable or disable a breakpoint:
1509 @item disable breakpoints @var{bnums}@dots{}
1510 @itemx disable @var{bnums}@dots{}
1511 @kindex disable breakpoints
1513 Disable the specified breakpoints. A disabled breakpoint has no
1514 effect but is not forgotten. All options such as ignore-counts,
1515 conditions and commands are remembered in case the breakpoint is
1516 enabled again later.
1518 @item enable breakpoints @var{bnums}@dots{}
1519 @itemx enable @var{bnums}@dots{}
1520 @kindex enable breakpoints
1522 Enable the specified breakpoints. They become effective once again in
1523 stopping the program, until you specify otherwise.
1525 @item enable breakpoints once @var{bnums}@dots{}
1526 @itemx enable once @var{bnums}@dots{}
1527 Enable the specified breakpoints temporarily. Each will be disabled
1528 again the next time it stops the program (unless you have used one of
1529 these commands to specify a different state before that time comes).
1531 @item enable breakpoints delete @var{bnums}@dots{}
1532 @itemx enable delete @var{bnums}@dots{}
1533 Enable the specified breakpoints to work once and then die. Each of
1534 the breakpoints will be deleted the next time it stops the program
1535 (unless you have used one of these commands to specify a different
1536 state before that time comes).
1539 Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks},
1540 breakpoints that you set are enabled or disabled only when you use one
1541 of the commands above. (The command @samp{until} can set and delete a
1542 breakpoint on its own, but it will not change the state of your
1545 @node Conditions, Break Commands, Disabling, Breakpoints
1546 @subsection Break Conditions
1547 @cindex conditional breakpoints
1548 @cindex breakpoint conditions
1550 The simplest sort of breakpoint breaks every time the program reaches a
1551 specified place. You can also specify a @dfn{condition} for a
1552 breakpoint. A condition is just a boolean expression in your
1553 programming language. (@xref{Expressions}). A breakpoint with a
1554 condition evaluates the expression each time the program reaches it, and
1555 the program stops only if the condition is true.
1557 Break conditions may have side effects, and may even call functions in your
1558 program. These may sound like strange things to do, but their effects are
1559 completely predictable unless there is another enabled breakpoint at the
1560 same address. (In that case, GDB might see the other breakpoint first and
1561 stop the program without checking the condition of this one.) Note that
1562 breakpoint commands are usually more convenient and flexible for the
1563 purpose of performing side effects when a breakpoint is reached
1564 (@pxref{Break Commands}).
1566 Break conditions can be specified when a breakpoint is set, by using
1567 @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}.
1568 They can also be changed at any time with the @samp{condition} command:
1571 @item condition @var{bnum} @var{expression}
1573 Specify @var{expression} as the break condition for breakpoint number
1574 @var{bnum}. From now on, this breakpoint will stop the program only if
1575 the value of @var{expression} is true (nonzero, in C). @var{expression}
1576 is not evaluated at the time the @samp{condition} command is given.
1579 @item condition @var{bnum}
1580 Remove the condition from breakpoint number @var{bnum}. It becomes
1581 an ordinary unconditional breakpoint.
1584 @cindex ignore count (of breakpoint)
1585 A special case of a breakpoint condition is to stop only when the
1586 breakpoint has been reached a certain number of times. This is so
1587 useful that there is a special way to do it, using the @dfn{ignore
1588 count} of the breakpoint. Every breakpoint has an ignore count, which
1589 is an integer. Most of the time, the ignore count is zero, and
1590 therefore has no effect. But if the program reaches a breakpoint whose
1591 ignore count is positive, then instead of stopping, it just decrements
1592 the ignore count by one and continues. As a result, if the ignore count
1593 value is @var{n}, the breakpoint will not stop the next @var{n} times it
1597 @item ignore @var{bnum} @var{count}
1599 Set the ignore count of breakpoint number @var{bnum} to @var{count}.
1600 The next @var{count} times the breakpoint is reached, your program's
1601 execution will not stop; other than to decrement the ignore count, GDB
1604 To make the breakpoint stop the next time it is reached, specify
1607 @item cont @var{count}
1608 Continue execution of the program, setting the ignore count of the
1609 breakpoint that the program stopped at to @var{count} minus one.
1610 Thus, the program will not stop at this breakpoint until the
1611 @var{count}'th time it is reached.
1613 This command is allowed only when the program stopped due to a
1614 breakpoint. At other times, the argument to @samp{cont} is ignored.
1617 If a breakpoint has a positive ignore count and a condition, the condition
1618 is not checked. Once the ignore count reaches zero, the condition will
1619 start to be checked.
1621 Note that you could achieve the effect of the ignore count with a
1622 condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience
1623 variable that is decremented each time. @xref{Convenience Vars}.
1625 @node Break Commands, Error in Breakpoints, Conditions, Breakpoints
1626 @subsection Commands Executed on Breaking
1628 @cindex breakpoint commands
1629 You can give any breakpoint a series of commands to execute when the
1630 program stops due to that breakpoint. For example, you might want to
1631 print the values of certain expressions, or enable other breakpoints.
1634 @item commands @var{bnum}
1635 Specify commands for breakpoint number @var{bnum}. The commands
1636 themselves appear on the following lines. Type a line containing just
1637 @samp{end} to terminate the commands.
1639 To remove all commands from a breakpoint, use the command
1640 @samp{commands} and follow it immediately by @samp{end}; that is, give
1643 With no arguments, @samp{commands} refers to the last breakpoint set.
1646 You can use breakpoint commands to start the program up again.
1647 Simply use the @samp{cont} command, or @samp{step}, or any other command
1648 to resume execution. However, any remaining breakpoint commands are
1649 ignored. When the program stops again, GDB will act according to the
1653 If the first command specified is @samp{silent}, the usual message about
1654 stopping at a breakpoint is not printed. This may be desirable for
1655 breakpoints that are to print a specific message and then continue.
1656 If the remaining commands too print nothing, you will see no sign that
1657 the breakpoint was reached at all. @samp{silent} is not really a command;
1658 it is meaningful only at the beginning of the commands for a breakpoint.
1660 The commands @samp{echo} and @samp{output} that allow you to print precisely
1661 controlled output are often useful in silent breakpoints. @xref{Output}.
1663 For example, here is how you could use breakpoint commands to print the
1664 value of @code{x} at entry to @code{foo} whenever it is positive.
1677 One application for breakpoint commands is to correct one bug so you can
1678 test another. Put a breakpoint just after the erroneous line of code, give
1679 it a condition to detect the case in which something erroneous has been
1680 done, and give it commands to assign correct values to any variables that
1681 need them. End with the @samp{cont} command so that the program does not
1682 stop, and start with the @samp{silent} command so that no output is
1683 produced. Here is an example:
1694 One deficiency in the operation of automatically continuing breakpoints
1695 under Unix appears when your program uses raw mode for the terminal.
1696 GDB switches back to its own terminal modes (not raw) before executing
1697 commands, and then must switch back to raw mode when your program is
1698 continued. This causes any pending terminal input to be lost.
1700 In the GNU system, this will be fixed by changing the behavior of
1703 Under Unix, when you have this problem, you might be able to get around
1704 it by putting your actions into the breakpoint condition instead of
1705 commands. For example
1708 condition 5 (x = y + 4), 0
1712 specifies a condition expression (@xref{Expressions}) that will change
1713 @code{x} as needed, then always have the value 0 so the program will not
1714 stop. Loss of input is avoided here because break conditions are
1715 evaluated without changing the terminal modes. When you want to have
1716 nontrivial conditions for performing the side effects, the operators
1717 @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
1719 @node Error in Breakpoints,, Break Commands, Breakpoints
1720 @subsection ``Cannot Insert Breakpoints'' Error
1722 Under some operating systems, breakpoints cannot be used in a program if
1723 any other process is running that program. Attempting to run or
1724 continue a program with a breakpoint in this case will cause GDB to
1727 When this happens, you have three ways to proceed:
1731 Remove or disable the breakpoints, then continue.
1734 Suspend GDB, and copy the file containing the program to a new name.
1735 Resume GDB and use the @samp{exec-file} command to specify that GDB
1736 should run the program under that name. Then start the program again.
1739 Relink the program so that the text segment is nonsharable, using the
1740 linker option @samp{-N}. The operating system limitation may not apply
1741 to nonsharable executables.
1744 @node Continuing, Stepping, Breakpoints, Stopping
1747 After your program stops, most likely you will want it to run some more if
1748 the bug you are looking for has not happened yet.
1753 Continue running the program at the place where it stopped.
1756 If the program stopped at a breakpoint, the place to continue running
1757 is the address of the breakpoint. You might expect that continuing would
1758 just stop at the same breakpoint immediately. In fact, @samp{cont}
1759 takes special care to prevent that from happening. You do not need
1760 to delete the breakpoint to proceed through it after stopping at it.
1762 You can, however, specify an ignore-count for the breakpoint that the
1763 program stopped at, by means of an argument to the @samp{cont} command.
1766 If the program stopped because of a signal other than @code{SIGINT} or
1767 @code{SIGTRAP}, continuing will cause the program to see that signal.
1768 You may not want this to happen. For example, if the program stopped
1769 due to some sort of memory reference error, you might store correct
1770 values into the erroneous variables and continue, hoping to see more
1771 execution; but the program would probably terminate immediately as
1772 a result of the fatal signal once it sees the signal. To prevent this,
1773 you can continue with @samp{signal 0}. @xref{Signaling}. You can
1774 also act in advance to prevent the program from seeing certain kinds
1775 of signals, using the @samp{handle} command (@pxref{Signals}).
1777 @node Stepping,, Continuing, Stopping
1781 @dfn{Stepping} means setting your program in motion for a limited time, so
1782 that control will return automatically to the debugger after one line of
1783 code or one machine instruction. Breakpoints are active during stepping
1784 and the program will stop for them even if it has not gone as far as the
1785 stepping command specifies.
1790 Continue running the program until control reaches a different line,
1791 then stop it and return control to the debugger. This command is
1792 abbreviated @samp{s}.
1794 This command may be given when control is within a function for which
1795 there is no debugging information. In that case, execution will proceed
1796 until control reaches a different function, or is about to return from
1797 this function. An argument repeats this action.
1799 @item step @var{count}
1800 Continue running as in @samp{step}, but do so @var{count} times. If a
1801 breakpoint is reached or a signal not related to stepping occurs before
1802 @var{count} steps, stepping stops right away.
1806 Similar to @samp{step}, but any function calls appearing within the line of
1807 code are executed without stopping. Execution stops when control reaches a
1808 different line of code at the stack level which was executing when the
1809 @samp{next} command was given. This command is abbreviated @samp{n}.
1811 An argument is a repeat count, as in @samp{step}.
1813 @samp{next} within a function without debugging information acts as does
1814 @samp{step}, but any function calls appearing within the code of the
1815 function are executed without stopping.
1819 Continue running until just after the selected stack frame returns (or
1820 until there is some other reason to stop, such as a fatal signal or a
1821 breakpoint). Print value returned by the selected stack frame (if any).
1823 Contrast this with the @samp{return} command (@pxref{Returning}).
1827 This command is used to avoid single stepping through a loop more than
1828 once. It is like the @samp{next} command, except that when @samp{until}
1829 encounters a jump, it automatically continues execution until the
1830 program counter is greater than the address of the jump.
1832 This means that when you reach the end of a loop after single stepping
1833 though it, @samp{until} will cause the program to continue execution
1834 until the loop is exited. In contrast, a @samp{next} command at the end
1835 of a loop will simply step back to the beginning of the loop, which
1836 would force you to step through the next iteration.
1838 @samp{until} always stops the program if it attempts to exit the current
1841 @samp{until} may produce somewhat counterintuitive results if the order
1842 of the source lines does not match the actual order of execution. For
1843 example, in a typical C @code{for}-loop, the third expression in the
1844 @code{for}-statement (the loop-step expression) is executed after the
1845 statements in the body of the loop, but is written before them.
1846 Therefore, the @samp{until} command would appear to step back to the
1847 beginning of the loop when it advances to this expression. However, it
1848 has not really done so, not in terms of the actual machine code.
1850 Note that @samp{until} with no argument works by means of single
1851 instruction stepping, and hence is slower than @samp{until} with an
1854 @item until @var{location}
1855 Continue running the program until either the specified location is
1856 reached, or the current (innermost) stack frame returns. @var{location}
1857 is any of the forms of argument acceptable to @samp{break} (@pxref{Set
1858 Breaks}). This form of the command uses breakpoints, and hence is
1859 quicker than @samp{until} without an argument.
1865 Execute one machine instruction, then stop and return to the debugger.
1867 It is often useful to do @samp{display/i $pc} when stepping by machine
1868 instructions. This will cause the next instruction to be executed to
1869 be displayed automatically at each stop. @xref{Auto Display}.
1871 An argument is a repeat count, as in @samp{step}.
1877 Execute one machine instruction, but if it is a subroutine call,
1878 proceed until the subroutine returns.
1880 An argument is a repeat count, as in @samp{next}.
1883 A typical technique for using stepping is to put a breakpoint
1884 (@pxref{Breakpoints}) at the beginning of the function or the section of
1885 the program in which a problem is believed to lie, and then step through
1886 the suspect area, examining the variables that are interesting, until the
1889 The @samp{cont} command can be used after stepping to resume execution
1890 until the next breakpoint or signal.
1892 @node Stack, Source, Stopping, Top
1893 @chapter Examining the Stack
1895 When your program has stopped, the first thing you need to know is where it
1896 stopped and how it got there.
1899 Each time your program performs a function call, the information about
1900 where in the program the call was made from is saved in a block of data
1901 called a @dfn{stack frame}. The frame also contains the arguments of the
1902 call and the local variables of the function that was called. All the
1903 stack frames are allocated in a region of memory called the @dfn{call
1906 When your program stops, the GDB commands for examining the stack allow you
1907 to see all of this information.
1909 One of the stack frames is @dfn{selected} by GDB and many GDB commands
1910 refer implicitly to the selected frame. In particular, whenever you ask
1911 GDB for the value of a variable in the program, the value is found in the
1912 selected frame. There are special GDB commands to select whichever frame
1913 you are interested in.
1915 When the program stops, GDB automatically selects the currently executing
1916 frame and describes it briefly as the @samp{frame} command does
1917 (@pxref{Frame Info, Info}).
1920 * Frames:: Explanation of stack frames and terminology.
1921 * Backtrace:: Summarizing many frames at once.
1922 * Selection:: How to select a stack frame.
1923 * Info: Frame Info, Commands to print information on stack frames.
1924 * Exception Handling: How GDB supports exception handling for C++.
1927 @node Frames, Backtrace, Stack, Stack
1928 @section Stack Frames
1932 The call stack is divided up into contiguous pieces called @dfn{stack
1933 frames}, or @dfn{frames} for short; each frame is the data associated
1934 with one call to one function. The frame contains the arguments given
1935 to the function, the function's local variables, and the address at
1936 which the function is executing.
1938 @cindex initial frame
1939 @cindex outermost frame
1940 @cindex innermost frame
1941 When your program is started, the stack has only one frame, that of the
1942 function @code{main}. This is called the @dfn{initial} frame or the
1943 @dfn{outermost} frame. Each time a function is called, a new frame is
1944 made. Each time a function returns, the frame for that function invocation
1945 is eliminated. If a function is recursive, there can be many frames for
1946 the same function. The frame for the function in which execution is
1947 actually occurring is called the @dfn{innermost} frame. This is the most
1948 recently created of all the stack frames that still exist.
1950 @cindex frame pointer
1951 Inside your program, stack frames are identified by their addresses. A
1952 stack frame consists of many bytes, each of which has its own address; each
1953 kind of computer has a convention for choosing one of those bytes whose
1954 address serves as the address of the frame. Usually this address is kept
1955 in a register called the @dfn{frame pointer register} while execution is
1956 going on in that frame.
1958 @cindex frame number
1959 GDB assigns numbers to all existing stack frames, starting with zero for
1960 the innermost frame, one for the frame that called it, and so on upward.
1961 These numbers do not really exist in your program; they are to give you a
1962 way of talking about stack frames in GDB commands.
1964 @cindex selected frame
1965 Many GDB commands refer implicitly to one stack frame. GDB records a stack
1966 frame that is called the @dfn{selected} stack frame; you can select any
1967 frame using one set of GDB commands, and then other commands will operate
1968 on that frame. When your program stops, GDB automatically selects the
1971 @cindex frameless execution
1972 Some functions can be compiled to run without a frame reserved for them
1973 on the stack. This is occasionally done with heavily used library
1974 functions to save the frame setup time. GDB has limited facilities for
1975 dealing with these function invocations; if the innermost function
1976 invocation has no stack frame, GDB will give it a virtual stack frame of
1977 0 and correctly allow tracing of the function call chain. Results are
1978 undefined if a function invocation besides the innermost one is
1981 @node Backtrace, Selection, Frames, Stack
1984 A backtrace is a summary of how the program got where it is. It shows one
1985 line per frame, for many frames, starting with the currently executing
1986 frame (frame zero), followed by its caller (frame one), and on up the
1994 Print a backtrace of the entire stack: one line per frame for all
1995 frames in the stack.
1997 You can stop the backtrace at any time by typing the system interrupt
1998 character, normally @kbd{Control-C}.
2000 @item backtrace @var{n}
2002 Similar, but print only the innermost @var{n} frames.
2004 @item backtrace @var{-n}
2006 Similar, but print only the outermost @var{n} frames.
2011 The names @samp{where} and @samp{info stack} are additional aliases
2012 for @samp{backtrace}.
2014 Every line in the backtrace shows the frame number, the function name
2015 and the program counter value.
2017 If the function is in a source file whose symbol table data has been
2018 fully read, the backtrace shows the source file name and line number, as
2019 well as the arguments to the function. (The program counter value is
2020 omitted if it is at the beginning of the code for that line number.)
2022 Here is an example of a backtrace. It was made with the command
2023 @samp{bt 3}, so it shows the innermost three frames.
2026 #0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \
2027 (/gp/rms/cc/rtlanal.c line 337)
2028 #1 0x246b0 in expand_call (...) (...)
2029 #2 0x21cfc in expand_expr (...) (...)
2030 (More stack frames follow...)
2034 The functions @code{expand_call} and @code{expand_expr} are in a file
2035 whose symbol details have not been fully read. Full detail is available
2036 for the function @code{rtx_equal_p}, which is in the file
2037 @file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown
2038 with their typed values.
2040 @node Selection, Frame Info, Backtrace, Stack
2041 @section Selecting a Frame
2043 Most commands for examining the stack and other data in the program work on
2044 whichever stack frame is selected at the moment. Here are the commands for
2045 selecting a stack frame; all of them finish by printing a brief description
2046 of the stack frame just selected.
2051 Select frame number @var{n}. Recall that frame zero is the innermost
2052 (currently executing) frame, frame one is the frame that called the
2053 innermost one, and so on. The highest-numbered frame is @code{main}'s
2056 @item frame @var{addr}
2057 Select the frame at address @var{addr}. This is useful mainly if the
2058 chaining of stack frames has been damaged by a bug, making it
2059 impossible for GDB to assign numbers properly to all frames. In
2060 addition, this can be useful when the program has multiple stacks and
2061 switches between them.
2065 Select the frame @var{n} frames up from the frame previously selected.
2066 For positive numbers @var{n}, this advances toward the outermost
2067 frame, to higher frame numbers, to frames that have existed longer.
2068 @var{n} defaults to one.
2072 Select the frame @var{n} frames down from the frame previously
2073 selected. For positive numbers @var{n}, this advances toward the
2074 innermost frame, to lower frame numbers, to frames that were created
2075 more recently. @var{n} defaults to one.
2078 All of these commands end by printing some information on the frame that
2079 has been selected: the frame number, the function name, the arguments, the
2080 source file and line number of execution in that frame, and the text of
2081 that source line. For example:
2084 #3 main (argc=3, argv=??, env=??) at main.c, line 67
2085 67 read_input_file (argv[i]);
2088 After such a printout, the @samp{list} command with no arguments will print
2089 ten lines centered on the point of execution in the frame. @xref{List}.
2091 @node Frame Info, Exception Handling, Selection, Stack
2092 @section Information on a Frame
2094 There are several other commands to print information about the selected
2099 This command prints a brief description of the selected stack frame.
2100 It can be abbreviated @samp{f}. With an argument, this command is
2101 used to select a stack frame; with no argument, it does not change
2102 which frame is selected, but still prints the same information.
2106 This command prints a verbose description of the selected stack frame,
2107 including the address of the frame, the addresses of the next frame in
2108 (called by this frame) and the next frame out (caller of this frame),
2109 the address of the frame's arguments, the program counter saved in it
2110 (the address of execution in the caller frame), and which registers
2111 were saved in the frame. The verbose description is useful when
2112 something has gone wrong that has made the stack format fail to fit
2113 the usual conventions.
2115 @item info frame @var{addr}
2116 Print a verbose description of the frame at address @var{addr},
2117 without selecting that frame. The selected frame remains unchanged by
2122 Print the arguments of the selected frame, each on a separate line.
2126 Print the local variables of the selected frame, each on a separate
2127 line. These are all variables declared static or automatic within all
2128 program blocks that execution in this frame is currently inside of.
2132 Print a list of all the exception handlers that are active in the
2133 current stack frame given the current value of @code{pc}. To see
2134 other exception handlers of higher frames, visit the higher frame
2135 (using the @samp{up} command) and type @samp{info catch}.
2138 @node Exception Handling,, Frame Info, Stack
2140 Some languages, such as GNU C++, implement exception handling. GDB
2141 can be used to examine what caused the program to raise an exception
2142 and to list the exceptions the program is prepared to handle at a
2143 given point in time.
2145 @cindex raise exceptions
2146 GNU C++ raises an exception by calling a library function named
2147 @code{__raise_exception} which has the following ANSI C interface:
2150 /* ADDR is where the exception identifier is stored.
2151 ID is the exception identifier. */
2152 void __raise_exception (void **addr, void *id);
2156 You can make the debugger catch all exceptions @emph{before} any stack
2157 unwinding takes place: set a breakpoint on @code{__raise_exception}
2158 (@pxref{Breakpoints}). If you set a breakpoint in an exception handler
2159 instead, it may not be easy to find out where the exception was raised.
2161 By using a conditional breakpoint (@xref{Conditions}), you can cause
2162 the debugger to stop only when a specific exception is raised.
2163 Multiple conditional breakpoints can be used to stop the program when
2164 any of a number of exceptions are raised.
2166 @cindex catch exceptions
2167 To examine the exceptions that a piece of a program is prepared to
2168 catch, the @samp{info catch} function is used. This function shows
2169 all exception handlers that are active in the current frame (for the
2170 current value of the program counter). By traversing frames (using
2171 the @samp{up} and @samp{down} commands), other exception handlers can
2174 Breakpoints can be set at active exception handlers by using the
2175 @samp{catch} command. The syntax is @samp{catch @var{exceptions}},
2176 where @var{exceptions} is a list of names of exceptions to catch.
2178 There are currently some limitations to exception handling in GDB.
2179 These will be corrected in a future release.
2182 @item If you call a function interactively it will normally return
2183 control to the user when it has finished executing. If the call
2184 raises an exception however, the call may bypass the mechanism that
2185 returns control to the user and cause the program to simply continue
2186 running until it hits a breakpoint, catches a signal that GDB is
2187 listening for, or exits.
2188 @item You cannot raise an exception interactively.
2189 @item You cannot interactively install an exception handler.
2192 @node Source, Data, Stack, Top
2193 @chapter Examining Source Files
2195 GDB knows which source files your program was compiled from, and
2196 can print parts of their text. When your program stops, GDB
2197 spontaneously prints the line it stopped in. Likewise, when you
2198 select a stack frame (@pxref{Selection}), GDB prints the line
2199 which execution in that frame has stopped in. You can also
2200 print parts of source files by explicit command.
2203 * List:: Using the @samp{list} command to print source files.
2204 * Search:: Commands for searching source files.
2205 * Source Path:: Specifying the directories to search for source files.
2208 @node List, Search, Source, Source
2209 @section Printing Source Lines
2212 To print lines from a source file, use the @samp{list} command
2213 (abbreviated @samp{l}). There are several ways to specify what part
2214 of the file you want to print.
2216 Here are the forms of the @samp{list} command most commonly used:
2219 @item list @var{linenum}
2220 Print ten lines centered around line number @var{linenum} in the
2221 current source file.
2223 @item list @var{function}
2224 Print ten lines centered around the beginning of function
2228 Print ten more lines. If the last lines printed were printed with a
2229 @samp{list} command, this prints ten lines following the last lines
2230 printed; however, if the last line printed was a solitary line printed
2231 as part of displaying a stack frame (@pxref{Stack}), this prints ten
2232 lines centered around that line.
2235 Print ten lines just before the lines last printed.
2238 Repeating a @samp{list} command with @key{RET} discards the argument,
2239 so it is equivalent to typing just @samp{list}. This is more useful
2240 than listing the same lines again. An exception is made for an
2241 argument of @samp{-}; that argument is preserved in repetition so that
2242 each repetition moves up in the file.
2245 In general, the @samp{list} command expects you to supply zero, one or two
2246 @dfn{linespecs}. Linespecs specify source lines; there are several ways
2247 of writing them but the effect is always to specify some source line.
2248 Here is a complete description of the possible arguments for @samp{list}:
2251 @item list @var{linespec}
2252 Print ten lines centered around the line specified by @var{linespec}.
2254 @item list @var{first},@var{last}
2255 Print lines from @var{first} to @var{last}. Both arguments are
2258 @item list ,@var{last}
2259 Print ten lines ending with @var{last}.
2261 @item list @var{first},
2262 Print ten lines starting with @var{first}.
2265 Print ten lines just after the lines last printed.
2268 Print ten lines just before the lines last printed.
2271 As described in the preceding table.
2274 Here are the ways of specifying a single source line---all the
2279 Specifies line @var{linenum} of the current source file.
2280 When a @samp{list} command has two linespecs, this refers to
2281 the same source file as the first linespec.
2284 Specifies the line @var{offset} lines after the last line printed.
2285 When used as the second linespec in a @samp{list} command that has
2286 two, this specifies the line @var{offset} lines down from the
2290 Specifies the line @var{offset} lines before the last line printed.
2292 @item @var{filename}:@var{linenum}
2293 Specifies line @var{linenum} in the source file @var{filename}.
2295 @item @var{function}
2296 Specifies the line of the open-brace that begins the body of the
2297 function @var{function}.
2299 @item @var{filename}:@var{function}
2300 Specifies the line of the open-brace that begins the body of the
2301 function @var{function} in the file @var{filename}. The file name is
2302 needed with a function name only for disambiguation of identically
2303 named functions in different source files.
2305 @item *@var{address}
2306 Specifies the line containing the program address @var{address}.
2307 @var{address} may be any expression.
2310 One other command is used to map source lines to program addresses.
2313 @item info line @var{linenum}
2315 Print the starting and ending addresses of the compiled code for
2316 source line @var{linenum}.
2319 The default examine address for the @samp{x} command is changed to the
2320 starting address of the line, so that @samp{x/i} is sufficient to
2321 begin examining the machine code (@pxref{Memory}). Also, this address
2322 is saved as the value of the convenience variable @code{$_}
2323 (@pxref{Convenience Vars}).
2326 @node Search, Source Path, List, Source
2327 @section Searching Source Files
2329 @kindex forward-search
2330 @kindex reverse-search
2332 There are two commands for searching through the current source file for a
2335 The command @samp{forward-search @var{regexp}} checks each line, starting
2336 with the one following the last line listed, for a match for @var{regexp}.
2337 It lists the line that is found. You can abbreviate the command name
2340 The command @samp{reverse-search @var{regexp}} checks each line, starting
2341 with the one before the last line listed and going backward, for a match
2342 for @var{regexp}. It lists the line that is found. You can abbreviate
2343 this command with as little as @samp{rev}.
2345 @node Source Path,, Search, Source
2346 @section Specifying Source Directories
2349 @cindex directories for source files
2350 Executable programs sometimes do not record the directories of the source
2351 files from which they were compiled, just the names. Even when they do,
2352 the directories could be moved between the compilation and your debugging
2353 session. GDB remembers a list of directories to search for source files;
2354 this is called the @dfn{source path}. Each time GDB wants a source file,
2355 it tries all the directories in the list, in the order they are present
2356 in the list, until it finds a file with the desired name. @b{Note that
2357 the executable search path is @i{not} used for this purpose. Neither is
2358 the current working directory, unless it happens to be in the source
2361 If it can't find a source file in the source path, and the object program
2362 records what directory it was compiled in, GDB tries that directory too.
2363 If the source path is empty, and there is no record of the compilation
2364 directory, GDB will, as a last resort, look in the current directory.
2366 Whenever you reset or rearrange the source path, GDB will clear out
2367 any information it has cached about where source files are found, where
2368 each line is in the file, etc.
2371 When you start GDB, its source path is empty.
2372 To add other directories, use the @samp{directory} command.
2375 @item directory @var{dirnames...}
2376 Add directory @var{dirname} to the front of the source path. Several
2377 directory names may be given to this command, separated by whitespace or
2378 @samp{:}. If a name is already in the source path, it is moved to the
2379 front of the path, so it will be searched sooner.
2382 Reset the source path to empty again. This requires confirmation.
2384 @item info directories
2385 @kindex info directories
2386 Print the source path: show which directories it contains.
2389 Because the @samp{directory} command, when used with arguments, adds to
2390 the front of the source path, it can affect files that GDB has already
2391 found. If the source path contains directories that you do not want,
2392 and these directories contain misleading files with names matching your
2393 source files, the way to correct the situation is as follows:
2397 Use @samp{directory} with no argument to reset the source path to empty.
2400 Use @samp{directory} with suitable arguments to add any other
2401 directories you want in the source path. You can add all the directories
2405 @node Data, Symbols, Source, Top
2406 @chapter Examining Data
2408 @cindex printing data
2409 @cindex examining data
2411 The usual way to examine data in your program is with the @samp{print}
2412 command (abbreviated @samp{p}). It evaluates and prints the value of any
2413 valid expression of the language the program is written in (for now, C
2422 where @var{exp} is any valid expression (in the source language), and
2423 the value of @var{exp} is printed in a format appropriate to its data
2426 A more low-level way of examining data is with the @samp{x} command.
2427 It examines data in memory at a specified address and prints it in a
2431 * Expressions:: Expressions that can be computed and printed.
2432 * Variables:: Using your program's variables in expressions.
2433 * Assignment:: Setting your program's variables.
2434 * Arrays:: Examining part of memory as an array.
2435 * Format Options:: Controlling how structures and arrays are printed.
2436 * Output formats:: Specifying formats for printing values.
2437 * Memory:: Examining memory explicitly.
2438 * Auto Display:: Printing certain expressions whenever program stops.
2439 * Value History:: Referring to values previously printed.
2440 * Convenience Vars:: Giving names to values for future reference.
2441 * Registers:: Referring to and storing in machine registers.
2444 @node Expressions, Variables, Data, Data
2445 @section Expressions
2448 Many different GDB commands accept an expression and compute its value.
2449 Any kind of constant, variable or operator defined by the programming
2450 language you are using is legal in an expression in GDB. This includes
2451 conditional expressions, function calls, casts and string constants.
2452 It unfortunately does not include symbols defined by preprocessor
2453 @code{#define} commands.
2455 Casts are supported in all languages, not just in C, because it is so
2456 useful to cast a number into a pointer so as to examine a structure
2457 at that address in memory.
2459 GDB supports three kinds of operator in addition to those of programming
2464 @samp{@@} is a binary operator for treating parts of memory as arrays.
2465 @xref{Arrays}, for more information.
2468 @samp{::} allows you to specify a variable in terms of the file or
2469 function it is defined in. @xref{Variables}.
2471 @item @{@var{type}@} @var{addr}
2472 Refers to an object of type @var{type} stored at address @var{addr} in
2473 memory. @var{addr} may be any expression whose value is an integer or
2474 pointer (but parentheses are required around nonunary operators, just as in
2475 a cast). This construct is allowed regardless of what kind of data is
2476 officially supposed to reside at @var{addr}.@refill
2479 @node Variables, Arrays, Expressions, Data
2480 @section Program Variables
2482 The most common kind of expression to use is the name of a variable
2485 Variables in expressions are understood in the selected stack frame
2486 (@pxref{Selection}); they must either be global (or static) or be visible
2487 according to the scope rules of the programming language from the point of
2488 execution in that frame. This means that in the function
2503 the variable @code{a} is usable whenever the program is executing
2504 within the function @code{foo}, but the variable @code{b} is visible
2505 only while the program is executing inside the block in which @code{b}
2508 As a special exception, you can refer to a variable or function whose
2509 scope is a single source file even if the current execution point is not
2510 in this file. But it is possible to have more than one such variable
2511 or function with the same name (if they are in different source files).
2512 In such a case, it is not defined which one you will get. If you wish,
2513 you can specify any one of them using the colon-colon construct:
2516 @var{block}::@var{variable}
2520 Here @var{block} is the name of the source file whose variable you want.
2522 @node Arrays, Format options, Variables, Data
2523 @section Artificial Arrays
2525 @cindex artificial array
2526 It is often useful to print out several successive objects of the
2527 same type in memory; a section of an array, or an array of
2528 dynamically determined size for which only a pointer exists in the
2531 This can be done by constructing an @dfn{artificial array} with the
2532 binary operator @samp{@@}. The left operand of @samp{@@} should be
2533 the first element of the desired array, as an individual object.
2534 The right operand should be the length of the array. The result is
2535 an array value whose elements are all of the type of the left argument.
2536 The first element is actually the left argument; the second element
2537 comes from bytes of memory immediately following those that hold the
2538 first element, and so on. Here is an example. If a program says
2541 int *array = (int *) malloc (len * sizeof (int));
2545 you can print the contents of @code{array} with
2551 The left operand of @samp{@@} must reside in memory. Array values made
2552 with @samp{@@} in this way behave just like other arrays in terms of
2553 subscripting, and are coerced to pointers when used in expressions.
2554 (It would probably appear in an expression via the value history,
2555 after you had printed it out.)
2557 @node Format options, Output formats, Arrays, Data
2558 @section Format options
2560 @cindex format options
2561 GDB provides a few ways to control how arrays and structures are
2567 Display the current settings for the format options.
2569 @item set array-max @var{number-of-elements}
2570 @kindex set array-max
2571 If GDB is printing a large array, it will stop printing after it has
2572 printed the number of elements set by the @samp{set array-max} command.
2573 This limit also applies to the display of strings.
2575 @item set arrayprint
2576 @itemx set arrayprint on
2577 @kindex set arrayprint
2578 GDB will pretty print arrays. This format is more convenient to read,
2579 but uses more space. The default is off.
2581 @item set arrayprint off.
2582 Return to compressed format for arrays.
2585 @itemx set vtblprint on
2586 @kindex set vtblprint
2588 Pretty print C++ virtual function tables. The default is off.
2590 @item set vtblprint off
2591 Do not pretty print C++ virtual arrays.
2593 @item set addressprint
2594 @item set adressprint on
2595 @kindex set addressprint
2596 GDB will print memory addresses in stack traces and structure values.
2599 @item set addressprint off
2600 Do not print addresses.
2602 GDB will pretty print C++ virtual function tables. The default is off.
2604 @item set prettyprint on
2605 @kindex set prettyprint
2606 Cause GDB to print structures in an indented format with one member per
2620 @item set prettyprint off
2621 Cause GDB to print structures in a compact format, like this:
2624 $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
2629 This is the default format.
2631 @item set unionprint on
2632 @kindex set unionprint
2633 Tell GDB to print unions which are contained in structures. This is the
2635 @item set unionprint off
2636 Tell GDB not to print unions which are contained in structures.
2638 For example, given the declarations
2641 typedef enum @{Tree, Bug@} Species;
2642 typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
2643 typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
2653 struct thing foo = @{Tree, @{Acorn@}@};
2657 with @samp{set unionprint on} in effect @samp{p foo} would print
2660 $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
2664 and with @samp{set unionprint off} in effect it would print
2667 $1 = @{it = Tree, form = @{...@}@}
2671 @node Output formats, Memory, Format options, Data
2672 @section Output formats
2674 @cindex formatted output
2675 @cindex output formats
2676 GDB normally prints all values according to their data types. Sometimes
2677 this is not what you want. For example, you might want to print a number
2678 in hex, or a pointer in decimal. Or you might want to view data in memory
2679 at a certain address as a character string or an instruction. These things
2680 can be done with @dfn{output formats}.
2682 The simplest use of output formats is to say how to print a value
2683 already computed. This is done by starting the arguments of the
2684 @samp{print} command with a slash and a format letter. The format
2685 letters supported are:
2689 Regard the bits of the value as an integer, and print the integer in
2693 Print as integer in signed decimal.
2696 Print as integer in unsigned decimal.
2699 Print as integer in octal.
2702 Print as an address, both absolute in hex and as an offset from the
2703 nearest preceding symbol.
2706 Regard as an integer and print it as a character constant.
2709 Regard the bits of the value as a floating point number and print
2710 using typical floating point syntax.
2713 For example, to print the program counter in hex (@pxref{Registers}), type
2720 Note that no space is required before the slash; this is because command
2721 names in GDB cannot contain a slash.
2723 To reprint the last value in the value history with a different format,
2724 you can use the @samp{print} command with just a format and no
2725 expression. For example, @samp{p/x} reprints the last value in hex.
2727 @node Memory, Auto Display, Output formats, Data
2728 @subsection Examining Memory
2730 @cindex examining memory
2732 The command @samp{x} (for `examine') can be used to examine memory
2733 without reference to the program's data types. The format in which you
2734 wish to examine memory is instead explicitly specified. The allowable
2735 formats are a superset of the formats described in the previous section.
2737 @samp{x} is followed by a slash and an output format specification,
2738 followed by an expression for an address. The expression need not have
2739 a pointer value (though it may); it is used as an integer, as the
2740 address of a byte of memory. @xref{Expressions} for more information on
2741 expressions. For example, @samp{x/4xw $sp} prints the four words of
2742 memory above the stack pointer in hexadecimal.
2744 The output format in this case specifies both how big a unit of memory
2745 to examine and how to print the contents of that unit. It is done
2746 with one or two of the following letters:
2748 These letters specify just the size of unit to examine:
2752 Examine individual bytes.
2755 Examine halfwords (two bytes each).
2758 Examine words (four bytes each).
2761 Many assemblers and cpu designers still use `word' for a 16-bit quantity,
2762 as a holdover from specific predecessor machines of the 1970's that really
2763 did use two-byte words. But more generally the term `word' has always
2764 referred to the size of quantity that a machine normally operates on and
2765 stores in its registers. This is 32 bits for all the machines that GDB
2769 Examine giant words (8 bytes).
2772 These letters specify just the way to print the contents:
2776 Print as integers in unsigned hexadecimal.
2779 Print as integers in signed decimal.
2782 Print as integers in unsigned decimal.
2785 Print as integers in unsigned octal.
2788 Print as an address, both absolute in hex and then relative
2789 to a symbol defined as an address below it.
2792 Print as character constants.
2795 Print as floating point. This works only with sizes @samp{w} and
2799 Print a null-terminated string of characters. The specified unit size
2800 is ignored; instead, the unit is however many bytes it takes to reach
2801 a null character (including the null character).
2804 Print a machine instruction in assembler syntax (or nearly). The
2805 specified unit size is ignored; the number of bytes in an instruction
2806 varies depending on the type of machine, the opcode and the addressing
2810 If either the manner of printing or the size of unit fails to be specified,
2811 the default is to use the same one that was used last. If you don't want
2812 to use any letters after the slash, you can omit the slash as well.
2814 You can also omit the address to examine. Then the address used is
2815 just after the last unit examined. This is why string and instruction
2816 formats actually compute a unit-size based on the data: so that the
2817 next string or instruction examined will start in the right place.
2818 The @samp{print} command sometimes sets the default address for
2819 the @samp{x} command; when the value printed resides in memory, the
2820 default is set to examine the same location. @samp{info line} also
2821 sets the default for @samp{x}, to the address of the start of the
2822 machine code for the specified line and @samp{info breakpoints} sets
2823 it to the address of the last breakpoint listed.
2825 When you use @key{RET} to repeat an @samp{x} command, it does not repeat
2826 exactly the same: the address specified previously (if any) is ignored, so
2827 that the repeated command examines the successive locations in memory
2828 rather than the same ones.
2830 You can examine several consecutive units of memory with one command by
2831 writing a repeat-count after the slash (before the format letters, if any).
2832 The repeat count must be a decimal integer. It has the same effect as
2833 repeating the @samp{x} command that many times except that the output may
2834 be more compact with several units per line. For example,
2841 prints ten instructions starting with the one to be executed next in the
2842 selected frame. After doing this, you could print another ten following
2850 in which the format and address are allowed to default.
2854 The addresses and contents printed by the @samp{x} command are not put in
2855 the value history because there is often too much of them and they would
2856 get in the way. Instead, GDB makes these values available for subsequent
2857 use in expressions as values of the convenience variables @code{$_} and
2860 After an @samp{x} command, the last address examined is available for use
2861 in expressions in the convenience variable @code{$_}. The contents of that
2862 address, as examined, are available in the convenience variable @code{$__}.
2864 If the @samp{x} command has a repeat count, the address and contents saved
2865 are from the last memory unit printed; this is not the same as the last
2866 address printed if several units were printed on the last line of output.
2869 The specialized command @samp{disassemble} is also provided to dump a
2870 range of memory as machine instructions. The default memory range is
2871 the function surrounding the program counter of the selected frame. A
2872 single argument to this command is a program counter value; the function
2873 surrounding this value will be dumped. Two arguments (separated by one
2874 or more spaces) specify a range of addresss (first inclusive, second
2875 exclusive) to be dumped.
2877 @node Auto Display, Value History, Memory, Data
2878 @section Automatic Display
2879 @cindex automatic display
2880 @cindex display of expressions
2882 If you find that you want to print the value of an expression frequently
2883 (to see how it changes), you might want to add it to the @dfn{automatic
2884 display list} so that GDB will print its value each time the program stops.
2885 Each expression added to the list is given a number to identify it;
2886 to remove an expression from the list, you specify that number.
2887 The automatic display looks like this:
2891 3: bar[5] = (struct hack *) 0x3804
2895 showing item numbers, expressions and their current values.
2897 If the expression refers to local variables, then it does not make sense
2898 outside the lexical context for which it was set up. Such an expression
2899 is disabled when execution enters a context where one of its variables
2900 is not defined. For example, if you give the command
2901 @samp{display name} while inside a function with an argument
2902 @code{name}, then this argument will be displayed while the program
2903 continues to stop inside that function. When it stops elsewhere---where
2904 there is no variable @samp{name}---display is disabled. The next time
2905 your program stops where @samp{name} is meaningful, you can enable the
2906 display expression once again.
2909 @item display @var{exp}
2911 Add the expression @var{exp} to the list of expressions to display
2912 each time the program stops. @xref{Expressions}.
2914 @item display/@var{fmt} @var{exp}
2915 For @var{fmt} specifying only a display format and not a size or
2916 count, add the expression @var{exp} to the auto-display list but
2917 arranges to display it each time in the specified format @var{fmt}.
2919 @item display/@var{fmt} @var{addr}
2920 For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
2921 number of units, add the expression @var{addr} as a memory address to
2922 be examined each time the program stops. Examining means in effect
2923 doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
2925 @item undisplay @var{dnums}@dots{}
2926 @itemx delete display @var{dnums}@dots{}
2927 @kindex delete display
2929 Remove item numbers @var{dnums} from the list of expressions to display.
2931 @item disable display @var{dnums}@dots{}
2932 @kindex disable display
2933 Disable the display of item numbers @var{dnums}. A disabled display
2934 item is not printed automatically, but is not forgotten. It may be
2937 @item enable display @var{dnums}@dots{}
2938 @kindex enable display
2939 Enable display of item numbers @var{dnums}. It becomes effective once
2940 again in auto display of its expression, until you specify otherwise.
2943 Display the current values of the expressions on the list, just as is
2944 done when the program stops.
2947 @kindex info display
2948 Print the list of expressions previously set up to display
2949 automatically, each one with its item number, but without showing the
2950 values. This includes disabled expressions, which are marked as such.
2951 It also includes expressions which would not be displayed right now
2952 because they refer to automatic variables not currently available.
2955 @node Value History, Convenience Vars, Auto Display, Data
2956 @section Value History
2958 @cindex value history
2959 Every value printed by the @samp{print} command is saved for the entire
2960 session in GDB's @dfn{value history} so that you can refer to it in
2965 @cindex history number
2966 The values printed are given @dfn{history numbers} for you to refer to them
2967 by. These are successive integers starting with 1. @samp{print} shows you
2968 the history number assigned to a value by printing @samp{$@var{num} = }
2969 before the value; here @var{num} is the history number.
2971 To refer to any previous value, use @samp{$} followed by the value's
2972 history number. The output printed by @samp{print} is designed to remind
2973 you of this. Just @code{$} refers to the most recent value in the history,
2974 and @code{$$} refers to the value before that.
2976 For example, suppose you have just printed a pointer to a structure and
2977 want to see the contents of the structure. It suffices to type
2983 If you have a chain of structures where the component @samp{next} points
2984 to the next one, you can print the contents of the next one with this:
2991 It might be useful to repeat this command many times by typing @key{RET}.
2993 Note that the history records values, not expressions. If the value of
2994 @code{x} is 4 and you type this command:
3002 then the value recorded in the value history by the @samp{print} command
3003 remains 4 even though the value of @code{x} has changed.
3008 Print the last ten values in the value history, with their item
3009 numbers. This is like @samp{p $$9} repeated ten times, except that
3010 @samp{info values} does not change the history.
3012 @item info values @var{n}
3013 Print ten history values centered on history item number @var{n}.
3016 Print ten history values just after the values last printed.
3019 @node Convenience Vars, Registers, Value History, Data
3020 @section Convenience Variables
3022 @cindex convenience variables
3023 GDB provides @dfn{convenience variables} that you can use within GDB to
3024 hold on to a value and refer to it later. These variables exist entirely
3025 within GDB; they are not part of your program, and setting a convenience
3026 variable has no effect on further execution of your program. That's why
3027 you can use them freely.
3029 Convenience variables have names starting with @samp{$}. Any name starting
3030 with @samp{$} can be used for a convenience variable, unless it is one of
3031 the predefined set of register names (@pxref{Registers}).
3033 You can save a value in a convenience variable with an assignment
3034 expression, just as you would set a variable in your program. Example:
3037 set $foo = *object_ptr
3041 would save in @code{$foo} the value contained in the object pointed to by
3044 Using a convenience variable for the first time creates it; but its value
3045 is @code{void} until you assign a new value. You can alter the value with
3046 another assignment at any time.
3048 Convenience variables have no fixed types. You can assign a convenience
3049 variable any type of value, even if it already has a value of a different
3050 type. The convenience variable as an expression has whatever type its
3054 @item info convenience
3055 @kindex info convenience
3056 Print a list of convenience variables used so far, and their values.
3057 Abbreviated @samp{i con}.
3060 One of the ways to use a convenience variable is as a counter to be
3061 incremented or a pointer to be advanced. For example:
3065 print bar[$i++]->contents
3066 @i{@dots{}repeat that command by typing @key{RET}.}
3069 Some convenience variables are created automatically by GDB and given
3070 values likely to be useful.
3074 The variable @code{$_} is automatically set by the @samp{x} command to
3075 the last address examined (@pxref{Memory}). Other commands which
3076 provide a default address for @samp{x} to examine also set @code{$_}
3077 to that address; these commands include @samp{info line} and @samp{info
3081 The variable @code{$__} is automatically set by the @samp{x} command
3082 to the value found in the last address examined.
3085 @node Registers,, Convenience Vars, Data
3089 Machine register contents can be referred to in expressions as variables
3090 with names starting with @samp{$}. The names of registers are different
3091 for each machine; use @samp{info registers} to see the names used on your
3092 machine. The names @code{$pc} and @code{$sp} are used on all machines for
3093 the program counter register and the stack pointer. Often @code{$fp} is
3094 used for a register that contains a pointer to the current stack frame,
3095 and @code{$ps} is used for a register that contains the processor
3096 status. These standard register names may be available on your machine
3097 even though the @code{info registers} command displays them with a
3098 different name. For example, on the SPARC, @code{info registers}
3099 displays the processor status register as @code{$psr} but you can also
3100 refer to it as @code{$ps}.
3102 GDB always considers the contents of an ordinary register as an integer
3103 when the register is examined in this way. Some machines have special
3104 registers which can hold nothing but floating point; these registers are
3105 considered floating point. There is no way to refer to the contents of an
3106 ordinary register as floating point value (although you can @emph{print}
3107 it as a floating point value with @samp{print/f $@var{regname}}).
3109 Some registers have distinct ``raw'' and ``virtual'' data formats. This
3110 means that the data format in which the register contents are saved by the
3111 operating system is not the same one that your program normally sees. For
3112 example, the registers of the 68881 floating point coprocessor are always
3113 saved in ``extended'' format, but all C programs expect to work with
3114 ``double'' format. In such cases, GDB normally works with the virtual
3115 format only (the format that makes sense for your program), but the
3116 @samp{info registers} command prints the data in both formats.
3118 Register values are relative to the selected stack frame
3119 (@pxref{Selection}). This means that you get the value that the register
3120 would contain if all stack frames farther in were exited and their saved
3121 registers restored. In order to see the real contents of all registers,
3122 you must select the innermost frame (with @samp{frame 0}).
3124 Some registers are never saved (typically those numbered zero or one)
3125 because they are used for returning function values; for these registers,
3126 relativization makes no difference.
3129 @item info registers
3130 @kindex info registers
3131 Print the names and relativized values of all registers.
3133 @item info registers @var{regname}
3134 Print the relativized value of register @var{regname}. @var{regname}
3135 may be any register name valid on the machine you are using, with
3136 or without the initial @samp{$}.
3139 @subsection Examples
3141 You could print the program counter in hex with
3148 or print the instruction to be executed next with
3155 or add four to the stack pointer with
3162 The last is a way of removing one word from the stack, on machines where
3163 stacks grow downward in memory (most machines, nowadays). This assumes
3164 that the innermost stack frame is selected. Setting @code{$sp} is
3165 not allowed when other stack frames are selected.
3167 @node Symbols, Altering, Data, Top
3168 @chapter Examining the Symbol Table
3170 The commands described in this section allow you to inquire about the
3171 symbols (names of variables, functions and types) defined in your
3172 program. This information is found by GDB in the symbol table loaded by
3173 the @samp{symbol-file} command; it is inherent in the text of your
3174 program and does not change as the program executes.
3177 @item info address @var{symbol}
3178 @kindex info address
3179 Describe where the data for @var{symbol} is stored. For a register
3180 variable, this says which register it is kept in. For a non-register
3181 local variable, this prints the stack-frame offset at which the variable
3184 Note the contrast with @samp{print &@var{symbol}}, which does not work
3185 at all for a register variables, and for a stack local variable prints
3186 the exact address of the current instantiation of the variable.
3188 @item whatis @var{exp}
3190 Print the data type of expression @var{exp}. @var{exp} is not
3191 actually evaluated, and any side-effecting operations (such as
3192 assignments or function calls) inside it do not take place.
3196 Print the data type of @code{$}, the last value in the value history.
3198 @item ptype @var{typename}
3200 Print a description of data type @var{typename}. @var{typename} may be
3201 the name of a type, or for C code it may have the form
3202 @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
3203 @samp{enum @var{enum-tag}}.@refill
3205 @item ptype @var{exp}
3206 Print a description of the type of expression @var{exp}. This is like
3207 @samp{whatis} except it prints a detailed description, instead of just
3208 the name of the type. For example, if the type of a variable is
3209 @samp{struct complex @{double real; double imag;@}}, @samp{whatis} will
3210 print @samp{struct complex} and @samp{ptype} will print @samp{struct
3211 complex @{double real; double imag;@}}
3214 @kindex info sources
3215 Print the names of all source files in the program for which there
3216 is debugging information.
3218 @item info functions
3219 @kindex info functions
3220 Print the names and data types of all defined functions.
3222 @item info functions @var{regexp}
3223 Print the names and data types of all defined functions
3224 whose names contain a match for regular expression @var{regexp}.
3225 Thus, @samp{info fun step} finds all functions whose names
3226 include @samp{step}; @samp{info fun ^step} finds those whose names
3227 start with @samp{step}.
3229 @item info variables
3230 @kindex info variables
3231 Print the names and data types of all variables that are declared
3232 outside of functions (i.e., except for local variables).
3234 @item info variables @var{regexp}
3235 Print the names and data types of all variables (except for local
3236 variables) whose names contain a match for regular expression
3241 This was never implemented.
3243 @itemx info methods @var{regexp}
3244 @kindex info methods
3245 The @samp{info-methods} command permits the user to examine all defined
3246 methods within C++ program, or (with the @var{regexp} argument) a
3247 specific set of methods found in the various C++ classes. Many
3248 C++ classes provide a large number of methods. Thus, the output
3249 from the @samp{ptype} command can be overwhelming and hard to use. The
3250 @samp{info-methods} command filters the methods, printing only those
3251 which match the regular-expression @var{regexp}.
3254 @item printsyms @var{filename}
3256 Write a complete dump of the debugger's symbol data into the
3257 file @var{filename}.
3260 @node Altering, Sequences, Symbols, Top
3261 @chapter Altering Execution
3263 Once you think you have found an error in the program, you might want to
3264 find out for certain whether correcting the apparent error would lead to
3265 correct results in the rest of the run. You can find the answer by
3266 experiment, using the GDB features for altering execution of the
3269 For example, you can store new values into variables or memory
3270 locations, give the program a signal, restart it at a different address,
3271 or even return prematurely from a function to its caller.
3274 * Assignment:: Altering variable values or memory contents.
3275 * Jumping:: Altering control flow.
3276 * Signaling:: Making signals happen in the program.
3277 * Returning:: Making a function return prematurely.
3280 @node Assignment, Jumping, Altering, Altering
3281 @section Assignment to Variables
3284 @cindex setting variables
3285 To alter the value of a variable, evaluate an assignment expression.
3286 @xref{Expressions}. For example,
3293 would store the value 4 into the variable @code{x}, and then print
3294 the value of the assignment expression (which is 4).
3296 All the assignment operators of C are supported, including the
3297 incrementation operators @samp{++} and @samp{--}, and combining
3298 assignments such as @samp{+=} and @samp{<<=}.
3301 @kindex set variable
3302 If you are not interested in seeing the value of the assignment, use the
3303 @samp{set} command instead of the @samp{print} command. @samp{set} is
3304 really the same as @samp{print} except that the expression's value is not
3305 printed and is not put in the value history (@pxref{Value History}). The
3306 expression is evaluated only for side effects.
3308 Note that if the beginning of the argument string of the @samp{set} command
3309 appears identical to a @samp{set} subcommand, it may be necessary to use
3310 the @samp{set variable} command. This command is identical to @samp{set}
3311 except for its lack of subcommands.
3313 GDB allows more implicit conversions in assignments than C does; you can
3314 freely store an integer value into a pointer variable or vice versa, and
3315 any structure can be converted to any other structure that is the same
3317 @comment FIXME: how do structs align/pad in these conversions?
3318 @comment /pesch@cygnus.com 18dec1990
3320 To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
3321 construct to generate a value of specified type at a specified address
3322 (@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer
3323 to memory location 0x83040 as an integer (which implies a certain size
3324 and representation in memory), and
3327 set @{int@}0x83040 = 4
3330 would store the value 4 into that memory location.
3332 @node Jumping, Signaling, Assignment, Altering
3333 @section Continuing at a Different Address
3335 Ordinarily, when you continue the program, you do so at the place where
3336 it stopped, with the @samp{cont} command. You can instead continue at
3337 an address of your own choosing, with the following commands:
3340 @item jump @var{linenum}
3342 Resume execution at line number @var{linenum}. Execution may stop
3343 immediately if there is a breakpoint there.
3345 The @samp{jump} command does not change the current stack frame, or
3346 the stack pointer, or the contents of any memory location or any
3347 register other than the program counter. If line @var{linenum} is in
3348 a different function from the one currently executing, the results may
3349 be bizarre if the two functions expect different patterns of arguments or
3350 of local variables. For this reason, the @samp{jump} command requests
3351 confirmation if the specified line is not in the function currently
3352 executing. However, even bizarre results are predictable based on
3353 careful study of the machine-language code of the program.
3355 @item jump *@var{address}
3356 Resume execution at the instruction at address @var{address}.
3359 You can get much the same effect as the @code{jump} command by storing a
3360 new value into the register @code{$pc}. The difference is that this
3361 does not start the program running; it only changes the address where it
3362 @emph{will} run when it is continued. For example,
3369 causes the next @samp{cont} command or stepping command to execute at
3370 address 0x485, rather than at the address where the program stopped.
3373 The most common occasion to use the @samp{jump} command is when you have
3374 stepped across a function call with @code{next}, and found that the
3375 return value is incorrect. If all the relevant data appeared correct
3376 before the function call, the error is probably in the function that
3379 In general, your next step would now be to rerun the program and execute
3380 up to this function call, and then step into it to see where it goes
3381 astray. But this may be time consuming. If the function did not have
3382 significant side effects, you could get the same information by resuming
3383 execution just before the function call and stepping through it. To do this,
3384 first put a breakpoint on that function; then, use the @samp{jump} command
3385 to continue on the line with the function call.
3387 @node Signaling, Returning, Jumping, Altering
3388 @section Giving the Program a Signal
3391 @item signal @var{signalnum}
3393 Resume execution where the program stopped, but give it immediately the
3394 signal number @var{signalnum}.
3396 Alternatively, if @var{signalnum} is zero, continue execution without
3397 giving a signal. This is useful when the program stopped on account of
3398 a signal and would ordinary see the signal when resumed with the
3399 @samp{cont} command; @samp{signal 0} causes it to resume without a
3403 @node Returning,, Signaling, Altering
3404 @section Returning from a Function
3406 @cindex returning from a function
3408 You can cancel execution of a function call with the @samp{return}
3409 command. This command has the effect of discarding the selected stack
3410 frame (and all frames within it), so that control moves to the caller of
3411 that function. You can think of this as making the discarded frame
3414 First select the stack frame that you wish to return from
3415 (@pxref{Selection}). Then type the @samp{return} command. If you wish
3416 to specify the value to be returned, give that as an argument.
3418 This pops the selected stack frame (and any other frames inside of it),
3419 leaving its caller as the innermost remaining frame. That frame becomes
3420 selected. The specified value is stored in the registers used for
3421 returning values of functions.
3423 The @samp{return} command does not resume execution; it leaves the
3424 program stopped in the state that would exist if the function had just
3425 returned. Contrast this with the @samp{finish} command
3426 (@pxref{Stepping}), which resumes execution until the selected stack
3427 frame returns @emph{naturally}.
3429 @node Sequences, Options, Altering, Top
3430 @chapter Canned Sequences of Commands
3432 GDB provides two ways to store sequences of commands for execution as a
3433 unit: user-defined commands and command files.
3436 * Define:: User-defined commands.
3437 * Command Files:: Command files.
3438 * Output:: Controlled output commands useful in
3439 user-defined commands and command files.
3442 @node Define, Command Files, Sequences, Sequences
3443 @section User-Defined Commands
3445 @cindex user-defined command
3446 A @dfn{user-defined command} is a sequence of GDB commands to which you
3447 assign a new name as a command. This is done with the @samp{define}
3451 @item define @var{commandname}
3453 Define a command named @var{commandname}. If there is already a command
3454 by that name, you are asked to confirm that you want to redefine it.
3456 The definition of the command is made up of other GDB command lines,
3457 which are given following the @samp{define} command. The end of these
3458 commands is marked by a line containing @samp{end}.
3460 @item document @var{commandname}
3462 Give documentation to the user-defined command @var{commandname}. The
3463 command @var{commandname} must already be defined. This command reads
3464 lines of documentation just as @samp{define} reads the lines of the
3465 command definition, ending with @samp{end}. After the @samp{document}
3466 command is finished, @samp{help} on command @var{commandname} will print
3467 the documentation you have specified.
3469 You may use the @samp{document} command again to change the
3470 documentation of a command. Redefining the command with @samp{define}
3471 does not change the documentation.
3474 User-defined commands do not take arguments. When they are executed, the
3475 commands of the definition are not printed. An error in any command
3476 stops execution of the user-defined command.
3478 Commands that would ask for confirmation if used interactively proceed
3479 without asking when used inside a user-defined command. Many GDB commands
3480 that normally print messages to say what they are doing omit the messages
3481 when used in user-defined command.
3483 @node Command Files, Output, Define, Sequences
3484 @section Command Files
3486 @cindex command files
3487 A command file for GDB is a file of lines that are GDB commands. Comments
3488 (lines starting with @samp{#}) may also be included. An empty line in a
3489 command file does nothing; it does not mean to repeat the last command, as
3490 it would from the terminal.
3493 @cindex @file{.gdbinit}
3494 When GDB starts, it first executes commands from its @dfn{init files}.
3495 These are files named @file{.gdbinit}. GDB reads the init file (if any)
3496 in your home directory and then the init file (if any) in the current
3497 working directory. (The init files are not executed if the @samp{-nx}
3498 option is given.) You can also request the execution of a command file
3499 with the @samp{source} command:
3502 @item source @var{filename}
3504 Execute the command file @var{filename}.
3507 The lines in a command file are executed sequentially. They are not
3508 printed as they are executed. An error in any command terminates execution
3509 of the command file.
3511 Commands that would ask for confirmation if used interactively proceed
3512 without asking when used in a command file. Many GDB commands that
3513 normally print messages to say what they are doing omit the messages
3514 when used in a command file.
3516 @node Output,, Command Files, Sequences
3517 @section Commands for Controlled Output
3519 During the execution of a command file or a user-defined command, the only
3520 output that appears is what is explicitly printed by the commands of the
3521 definition. This section describes three commands useful for generating
3522 exactly the output you want.
3525 @item echo @var{text}
3527 @comment I don't consider backslash-space a standard C escape sequence
3528 @comment because it's not in ANSI.
3529 Print @var{text}. Nonprinting characters can be included in @var{text}
3530 using C escape sequences, such as @samp{\n} to print a newline. @b{No
3531 newline will be printed unless you specify one.} In addition to the
3532 standard C escape sequences a backslash followed by a space stands for a
3533 space. This is useful for outputting a string with spaces at the
3534 beginning or the end, since leading and trailing spaces are otherwise
3535 trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the
3536 command @samp{echo \@ and foo = \@ }.
3537 @comment FIXME: verify hard copy actually issues enspaces for '@ '! Will this
3538 @comment confuse texinfo?
3540 A backslash at the end of @var{text} can be used, as in C, to continue
3541 the command onto subsequent lines. For example,
3544 echo This is some text\n\
3545 which is continued\n\
3546 onto several lines.\n
3549 produces the same output as
3552 echo This is some text\n
3553 echo which is continued\n
3554 echo onto several lines.\n
3557 @item output @var{expression}
3559 Print the value of @var{expression} and nothing but that value: no
3560 newlines, no @samp{$@var{nn} = }. The value is not entered in the
3561 value history either. @xref{Expressions} for more information on
3564 @item output/@var{fmt} @var{expression}
3565 Print the value of @var{expression} in format @var{fmt}.
3566 @xref{Output formats}, for more information.
3568 @item printf @var{string}, @var{expressions}@dots{}
3570 Print the values of the @var{expressions} under the control of
3571 @var{string}. The @var{expressions} are separated by commas and may
3572 be either numbers or pointers. Their values are printed as specified
3573 by @var{string}, exactly as if the program were to execute
3576 printf (@var{string}, @var{expressions}@dots{});
3579 For example, you can print two values in hex like this:
3582 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
3585 The only backslash-escape sequences that you can use in the string are
3586 the simple ones that consist of backslash followed by a letter.
3589 @node Options, Emacs, Sequences, Top
3590 @chapter Options and Arguments for GDB
3592 When you invoke GDB, you can specify arguments telling it what files to
3593 operate on and what other things to do.
3596 * Mode Options:: Options controlling modes of operation.
3597 * File Options:: Options to specify files (executable, coredump, commands)
3598 * Other Arguments:: Any other arguments without options
3602 @node Mode Options, File Options, Options, Options
3603 @section Mode Options
3607 Do not execute commands from the init files @file{.gdbinit}.
3608 Normally, the commands in these files are executed after all the
3609 command options and arguments have been processed. @xref{Command
3613 ``Quiet''. Do not print the usual introductory messages.
3616 Run in batch mode. Exit with code 0 after processing all the command
3617 files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited).
3618 Exit with nonzero status if an error occurs in executing the GDB
3619 commands in the command files.
3622 This option is used when Emacs runs GDB as a subprocess. It tells GDB
3623 to output the full file name and line number in a standard,
3624 recognizable fashion each time a stack frame is displayed (which
3625 includes each time the program stops). This recognizable format looks
3626 like two @samp{\032} characters, followed by the file name, line number
3627 and character position separated by colons, and a newline. The
3628 Emacs-to-GDB interface program uses the two @samp{\032} characters as
3629 a signal to display the source code for the frame.
3632 @node File Options, Other Arguments, Mode Options, Options
3633 @section File-specifying Options
3635 All the options and command line arguments given are processed
3636 in sequential order. The order makes a difference when the
3637 @samp{-x} option is used.
3641 Read symbol table from file @var{file}.
3644 Use file @var{file} as the executable file to execute when
3645 appropriate, and for examining pure data in conjunction with a core
3648 @item -se @var{file}
3649 Read symbol table from file @var{file} and use it as the executable
3653 Use file @var{file} as a core dump to examine.
3656 Execute GDB commands from file @var{file}.
3658 @item -d @var{directory}
3659 Add @var{directory} to the path to search for source files.
3662 @node Other Arguments,, File Options, Options
3663 @section Other Arguments
3665 If there are arguments to GDB that are not options or associated with
3666 options, the first one specifies the symbol table and executable file name
3667 (as if it were preceded by @samp{-se}) and the second one specifies a core
3668 dump file name (as if it were preceded by @samp{-c}).
3670 @node Emacs, Remote, Options, Top
3671 @chapter Using GDB under GNU Emacs
3674 A special interface allows you to use GNU Emacs to view (and
3675 edit) the source files for the program you are debugging with
3678 To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
3679 executable file you want to debug as an argument. This command starts
3680 GDB as a subprocess of Emacs, with input and output through a newly
3681 created Emacs buffer.
3683 Using GDB under Emacs is just like using GDB normally except for two
3688 All ``terminal'' input and output goes through the Emacs buffer. This
3689 applies both to GDB commands and their output, and to the input and
3690 output done by the program you are debugging.
3692 This is useful because it means that you can copy the text of previous
3693 commands and input them again; you can even use parts of the output
3696 All the facilities of Emacs's Shell mode are available for this purpose.
3699 GDB displays source code through Emacs. Each time GDB displays a
3700 stack frame, Emacs automatically finds the source file for that frame
3701 and puts an arrow (@samp{=>}) at the left margin of the current line.
3702 Emacs uses a separate buffer for source display, and splits the window
3703 to show both your GDB session and the source.
3705 Explicit GDB @samp{list} or search commands still produce output as
3706 usual, but you probably will have no reason to use them.
3709 In the GDB I/O buffer, you can use these special Emacs commands:
3713 Execute to another source line, like the GDB @samp{step} command.
3716 Execute to next source line in this function, skipping all function
3717 calls, like the GDB @samp{next} command.
3720 Execute one instruction, like the GDB @samp{stepi} command.
3723 Execute until exit from the selected stack frame, like the GDB
3724 @samp{finish} command.
3727 @comment C-c C-p in emacs 19
3728 Continue execution of the program, like the GDB @samp{cont} command.
3731 @comment C-c C-u in emacs 19
3732 Go up the number of frames indicated by the numeric argument
3733 (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
3734 like the GDB @samp{up} command.@refill
3737 @comment C-c C-d in emacs 19
3738 Go down the number of frames indicated by the numeric argument, like the
3739 GDB @samp{down} command.
3742 In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
3743 tells GDB to set a breakpoint on the source line point is on.
3745 The source files displayed in Emacs are in ordinary Emacs buffers
3746 which are visiting the source files in the usual way. You can edit
3747 the files with these buffers if you wish; but keep in mind that GDB
3748 communicates with Emacs in terms of line numbers. If you add or
3749 delete lines from the text, the line numbers that GDB knows will cease
3750 to correspond properly to the code.
3752 @comment The following dropped because Epoch is nonstandard. Reactivate
3753 @comment if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
3755 @kindex emacs epoch environment
3759 Version 18 of Emacs has a built-in window system called the @samp{epoch}
3760 environment. Users of this environment can use a new command,
3761 @samp{inspect} which performs identically to @samp{print} except that
3762 each value is printed in its own window.
3765 @node Remote, Commands, Emacs, Top
3766 @chapter Remote Kernel Debugging
3768 If you are trying to debug a program running on a machine that can't run
3769 GDB in the usual way, it is often useful to use remote debugging. For
3770 example, you might be debugging an operating system kernel, or debugging
3771 a small system which does not have a general purpose operating system
3772 powerful enough to run a full-featured debugger. Currently GDB supports
3773 remote debugging over a serial connection.
3775 The program to be debugged on the remote machine needs to contain a
3776 debugging device driver which talks to GDB over the serial line using the
3777 protocol described below. The same version of GDB that is used ordinarily
3778 can be used for this. Several sample remote debugging drivers are
3779 distributed with GDB; see the @file{README} file in the GDB distribution for
3783 * Remote Commands:: Commands used to start and finish remote debugging.
3786 For details of the communication protocol, see the comments in the GDB
3787 source file @file{remote.c}.
3789 @node Remote Commands, GDB Bugs, Remote, Remote
3790 @section Commands for Remote Debugging
3792 To start remote debugging, first run GDB and specify as an executable file
3793 the program that is running in the remote machine. This tells GDB how
3794 to find the program's symbols and the contents of its pure text. Then
3795 establish communication using the @samp{attach} command with a device
3796 name rather than a pid as an argument. For example:
3803 if the serial line is connected to the device named @file{/dev/ttyd}. This
3804 will stop the remote machine if it is not already stopped.
3806 Now you can use all the usual commands to examine and change data and to
3807 step and continue the remote program.
3809 To resume the remote program and stop debugging it, use the @samp{detach}
3812 @node GDB Bugs, , Remote Commands, Top
3813 @comment node-name, next, previous, up
3814 @chapter Reporting Bugs in GDB
3816 @cindex Reporting Bugs in GDB
3818 Your bug reports play an essential role in making GDB reliable.
3820 Reporting a bug may help you by bringing a solution to your problem, or it
3821 may not. But in any case the important function of a bug report is to help
3822 the entire community by making the next version of GDB work better. Bug
3823 reports are your contribution to the maintenance of GDB.
3825 In order for a bug report to serve its purpose, you must include the
3826 information that makes for fixing the bug.
3829 * Criteria: Bug Criteria. Have you really found a bug?
3830 * Reporting: Bug Reporting. How to report a bug effectively.
3831 * Known: Trouble. Known problems.
3832 * Help: Service. Where to ask for help.
3835 @node Bug Criteria, Bug Reporting, Bugs, Bugs
3836 @section Have You Found a Bug?
3837 @cindex Bug Criteria
3839 If you are not sure whether you have found a bug, here are some guidelines:
3843 @cindex Fatal Signal
3845 If the debugger gets a fatal signal, for any input whatever, that is a
3846 GDB bug. Reliable debuggers never crash.
3849 @cindex error on Valid Input
3850 If GDB produces an error message for valid input, that is a bug.
3853 @cindex Invalid Input
3854 If GDB does not produce an error message for invalid input,
3855 that is a bug. However, you should note that your idea of
3856 ``invalid input'' might be my idea of ``an extension'' or ``support
3857 for traditional practice''.
3860 If you are an experienced user of debugging tools, your suggestions
3861 for improvement of GDB are welcome in any case.
3864 @node Bug Reporting,, Bug Criteria, Bugs
3865 @section How to Report Bugs
3867 @cindex Compiler Bugs, Reporting
3869 Send bug reports for GDB to one of these addresses:
3872 bug-gdb@@prep.ai.mit.edu
3873 @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
3876 @strong{Do not send bug reports to @samp{info-gdb}, or to any
3877 newsgroups.} Most users of GDB do not want to receive bug reports.
3878 Those that do, have asked to be on @samp{bug-gcc}.
3880 The mailing list @samp{bug-gcc} has a newsgroup which serves as a
3881 repeater. The mailing list and the newsgroup carry exactly the same
3882 messages. Often people think of posting bug reports to the newsgroup
3883 instead of mailing them. This appears to work, but it has one problem
3884 which can be crucial: a newsgroup posting does not contain a mail path
3885 back to the sender. Thus, if I need to ask for more information, I
3886 may be unable to reach you. For this reason, it is better to send bug
3887 reports to the mailing list.
3889 As a last resort, send bug reports on paper to:
3897 The fundamental principle of reporting bugs usefully is this:
3898 @strong{report all the facts}. If you are not sure whether to state a
3899 fact or leave it out, state it!
3901 Often people omit facts because they think they know what causes the
3902 problem and they conclude that some details don't matter. Thus, you might
3903 assume that the name of the variable you use in an example does not matter.
3904 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
3905 stray memory reference which happens to fetch from the location where that
3906 name is stored in memory; perhaps, if the name were different, the contents
3907 of that location would fool the debugger into doing the right thing despite
3908 the bug. Play it safe and give a specific, complete example. That is the
3909 easiest thing for you to do, and the most helpful.
3911 Keep in mind that the purpose of a bug report is to enable me to fix
3912 the bug if it is not known. It isn't very important what happens if
3913 the bug is already known. Therefore, always write your bug reports on
3914 the assumption that the bug is not known.
3916 Sometimes people give a few sketchy facts and ask, ``Does this ring a
3917 bell?'' Those bug reports are useless, and I urge everyone to
3918 @emph{refuse to respond to them} except to chide the sender to report
3921 To enable me to fix the bug, you should include all these things:
3925 The version of GDB. GDB announces it on startup.
3927 Without this, I won't know whether there is any point in looking for
3928 the bug in the current version of GDB.
3932 A complete input file, and all necessary source files, that will
3933 reproduce the bug. Run your source files through the C
3934 preprocessor by doing @samp{gcc -E @var{sourcefile} > @var{outfile}},
3935 then include the contents of @var{outfile} in the bug report. (Any
3936 @samp{-I}, @samp{-D} or @samp{-U} options that you used in actual
3937 compilation should also be used when doing this.)
3939 A single statement is not enough of an example. In order to compile
3940 it, it must be embedded in a function definition; and the bug might
3941 depend on the details of how this is done.
3943 Without a real example I can compile, all I can do about your bug
3944 report is wish you luck. It would be futile to try to guess how to
3948 The command arguments you gave GCC or G++ to compile that example and
3949 observe the bug. For example, did you use @samp{-O}? To guarantee
3950 you won't omit something important, list them all.
3952 If I were to try to guess the arguments, I would probably guess wrong
3953 and then I would not encounter the bug.
3956 The type of machine you are using, and the operating system name and
3960 A description of what behavior you observe that you believe is
3961 incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
3962 incorrect assembler instruction in the output.''
3964 Of course, if the bug is that GDB gets a fatal signal, then I
3965 will certainly notice it. But if the bug is incorrect output, I might
3966 not notice unless it is glaringly wrong.
3968 Even if the problem you experience is a fatal signal, you should still
3969 say so explicitly. Suppose something strange is going on, such as,
3970 your copy of GDB is out of synch, or you have encountered a
3971 bug in the C library on your system. (This has happened!) Your copy
3972 might crash and mine would not. If you @i{told} me to expect a crash,
3973 then when mine fails to crash, I would know that the bug was not
3974 happening for me. If you had not told me to expect a crash, then I
3975 would not be able to draw any conclusion from my observations.
3978 If you wish to suggest changes to the GDB source, send me context
3979 diffs. If you even discuss something in the GDB source, refer to
3980 it by context, not by line number.
3982 The line numbers in my development sources don't match those in your
3983 sources. Your line numbers would convey no useful information to me.
3987 Here are some things that are not necessary:
3991 A description of the envelope of the bug.
3993 Often people who encounter a bug spend a lot of time investigating
3994 which changes to the input file will make the bug go away and which
3995 changes will not affect it.
3997 This is often time consuming and not very useful, because the way I
3998 will find the bug is by running a single example under the debugger
3999 with breakpoints, not by pure deduction from a series of examples.
4000 I recommend that you save your time for something else.
4002 Of course, if you can find a simpler example to report @emph{instead}
4003 of the original one, that is a convenience for me. Errors in the
4004 output will be easier to spot, running under the debugger will take
4007 However, simplification is not vital; if you don't want to do this,
4008 report the bug anyway and send me the entire test case you used.
4011 A patch for the bug.
4013 A patch for the bug does help me if it is a good one. But don't omit
4014 the necessary information, such as the test case, on the assumption that
4015 a patch is all I need. I might see problems with your patch and decide
4016 to fix the problem another way, or I might not understand it at all.
4018 Sometimes with a program as complicated as GDB it is very hard to
4019 construct an example that will make the program follow a certain path
4020 through the code. If you don't send me the example, I won't be able
4021 to construct one, so I won't be able to verify that the bug is fixed.
4023 And if I can't understand what bug you are trying to fix, or why your
4024 patch should be an improvement, I won't install it. A test case will
4025 help me to understand.
4028 A guess about what the bug is or what it depends on.
4030 Such guesses are usually wrong. Even I can't guess right about such
4031 things without first using the debugger to find the facts.
4034 @include readline/inc-readline.texinfo
4035 @include readline/inc-history.texinfo
4037 @node Commands, Concepts, Remote, Top
4038 @unnumbered Command Index
4042 @node Concepts, , Commands, Top
4043 @unnumbered Concept Index