2 @setfilename ../info/gdb
3 @settitle GDB, The GNU Debugger
5 This file documents the GNU debugger GDB.
7 Copyright (C) 1988 Free Software Foundation, Inc.
9 Permission is granted to make and distribute verbatim copies of
10 this manual provided the copyright notice and this permission notice
11 are preserved on all copies.
14 Permission is granted to process this file through Tex and print the
15 results, provided the printed document carries copying permission
16 notice identical to this one except for the removal of this paragraph
17 (this paragraph not being relevant to the printed manual).
20 Permission is granted to copy and distribute modified versions of this
21 manual under the conditions for verbatim copying, provided also that the
22 sections entitled ``Distribution'' and ``GDB General Public License'' are
23 included exactly as in the original, and provided that the entire resulting
24 derived work is distributed under the terms of a permission notice
25 identical to this one.
27 Permission is granted to copy and distribute translations of this manual
28 into another language, under the above conditions for modified versions,
29 except that the sections entitled ``Distribution'' and ``GDB General Public
30 License'' may be included in a translation approved by the author instead
31 of in the original English.
34 @setchapternewpage odd
38 @center @titlefont{GDB Manual}
40 @center The GNU Source-Level Debugger
42 @center Third Edition, GDB version 3.1
46 @center Richard M. Stallman
48 @vskip 0pt plus 1filll
49 Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc.
51 Permission is granted to make and distribute verbatim copies of
52 this manual provided the copyright notice and this permission notice
53 are preserved on all copies.
55 Permission is granted to copy and distribute modified versions of this
56 manual under the conditions for verbatim copying, provided also that the
57 sections entitled ``Distribution'' and ``GDB General Public License'' are
58 included exactly as in the original, and provided that the entire resulting
59 derived work is distributed under the terms of a permission notice
60 identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions,
64 except that the sections entitled ``Distribution'' and ``GDB General Public
65 License'' may be included in a translation approved by the author instead
66 of in the original English.
70 @node Top, Commands,, (DIR)
71 @unnumbered Summary of GDB
73 The purpose of a debugger such as GDB is to allow you to execute another
74 program while examining what is going on inside it. We call the other
75 program ``your program'' or ``the program being debugged''.
77 GDB can do four kinds of things (plus other things in support of these):
81 Start the program, specifying anything that might affect its behavior.
84 Make the program stop on specified conditions.
87 Examine what has happened, when the program has stopped, so that you
91 Change things in the program, so you can correct the effects of one bug
92 and go on to learn about another without having to recompile first.
95 GDB can be used to debug programs written in C and C++. Pascal support
96 is being implemented, and Fortran support will be added when a GNU
97 Fortran compiler is written.
100 * License:: The GDB General Public License gives you permission
101 to redistribute GDB on certain terms; and also
102 explains that there is no warranty.
103 * Input:: GDB command syntax and input conventions.
104 * Files:: Specifying files for GDB to operate on.
105 * Options:: GDB arguments and options.
106 * Compilation::Compiling your program so you can debug it.
107 * Running:: Running your program under GDB.
108 * Stopping:: Making your program stop. Why it may stop. What to do then.
109 * Stack:: Examining your program's stack.
110 * Source:: Examining your program's source files.
111 * Data:: Examining data in your program.
112 * Symbols:: Examining the debugger's symbol table.
113 * Altering:: Altering things in your program.
114 * Sequences:: Canned command sequences for repeated use.
115 * Emacs:: Using GDB through GNU Emacs.
116 * Remote:: Remote kernel debugging across a serial line.
117 * Commands:: Index of GDB commands.
118 * Concepts:: Index of GDB concepts.
121 @node License, Input, Top, Top
122 @unnumbered GDB General Public License
123 @center (Clarified 11 Feb 1988)
125 The license agreements of most software companies keep you at the mercy
126 of those companies. By contrast, our general public license is intended to
127 give everyone the right to share GDB. To make sure that you get the rights
128 we want you to have, we need to make restrictions that forbid anyone to
129 deny you these rights or to ask you to surrender the rights. Hence this
132 Specifically, we want to make sure that you have the right to give away
133 copies of GDB, that you receive source code or else can get it if you want
134 it, that you can change GDB or use pieces of it in new free programs, and
135 that you know you can do these things.
137 To make sure that everyone has such rights, we have to forbid you to
138 deprive anyone else of these rights. For example, if you distribute copies
139 of GDB, you must give the recipients all the rights that you have. You
140 must make sure that they, too, receive or can get the source code. And you
141 must tell them their rights.
143 Also, for our own protection, we must make certain that everyone finds
144 out that there is no warranty for GDB. If GDB is modified by someone else
145 and passed on, we want its recipients to know that what they have is not
146 what we distributed, so that any problems introduced by others will not
147 reflect on our reputation.
149 Therefore we (Richard Stallman and the Free Software Foundation,
150 Inc.) make the following terms which say what you must do to be
151 allowed to distribute or change GDB.
153 @unnumberedsec Copying Policies
157 You may copy and distribute verbatim copies of GDB source code as you
158 receive it, in any medium, provided that you conspicuously and
159 appropriately publish on each file a valid copyright notice ``Copyright
160 @copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
161 is appropriate); keep intact the notices on all files that
162 refer to this License Agreement and to the absence of any warranty; and
163 give any other recipients of the GDB program a copy of this License
164 Agreement along with the program. You may charge a distribution fee
165 for the physical act of transferring a copy.
168 You may modify your copy or copies of GDB source code or any portion
169 of it, and copy and distribute such modifications under the terms of
170 Paragraph 1 above, provided that you also do the following:
174 cause the modified files to carry prominent notices stating
175 that you changed the files and the date of any change; and
178 cause the whole of any work that you distribute or publish, that
179 in whole or in part contains or is a derivative of GDB or any
180 part thereof, to be licensed at no charge to all third parties on
181 terms identical to those contained in this License Agreement
182 (except that you may choose to grant more extensive warranty
183 protection to some or all third parties, at your option).
186 if the modified program serves as a debugger, cause it, when
187 started running in the simplest and usual way, to print an
188 announcement including a valid copyright notice ``Copyright
189 @copyright{} 1988 Free Software Foundation, Inc.'' (or with the
190 year that is appropriate), saying that there is no warranty (or
191 else, saying that you provide a warranty) and that users may
192 redistribute the program under these conditions, and telling the
193 user how to view a copy of this License Agreement.
196 You may charge a distribution fee for the physical act of
197 transferring a copy, and you may at your option offer warranty
198 protection in exchange for a fee.
201 Mere aggregation of another unrelated program with this program (or its
202 derivative) on a volume of a storage or distribution medium does not bring
203 the other program under the scope of these terms.
206 You may copy and distribute GDB (or a portion or derivative of it,
207 under Paragraph 2) in object code or executable form under the terms
208 of Paragraphs 1 and 2 above provided that you also do one of the
213 accompany it with the complete corresponding machine-readable
214 source code, which must be distributed under the terms of
215 Paragraphs 1 and 2 above; or,
218 accompany it with a written offer, valid for at least three
219 years, to give any third party free (except for a nominal
220 shipping charge) a complete machine-readable copy of the
221 corresponding source code, to be distributed under the terms of
222 Paragraphs 1 and 2 above; or,
225 accompany it with the information you received as to where the
226 corresponding source code may be obtained. (This alternative is
227 allowed only for noncommercial distribution and only if you
228 received the program in object code or executable form alone.)
231 For an executable file, complete source code means all the source code
232 for all modules it contains; but, as a special exception, it need not
233 include source code for modules which are standard libraries that
234 accompany the operating system on which the executable file runs.
237 You may not copy, sublicense, distribute or transfer GDB except as
238 expressly provided under this License Agreement. Any attempt
239 otherwise to copy, sublicense, distribute or transfer GDB is void and
240 your rights to use GDB under this License agreement shall be
241 automatically terminated. However, parties who have received computer
242 software programs from you with this License Agreement will not have
243 their licenses terminated so long as such parties remain in full
247 If you wish to incorporate parts of GDB into other free programs whose
248 distribution conditions are different, write to the Free Software
249 Foundation. We have not yet worked out a simple rule that can be
250 stated here, but we will often permit this. We will be guided by the
251 two goals of preserving the free status of all derivatives our free
252 software and of promoting the sharing and reuse of software.
259 @unnumberedsec NO WARRANTY
261 BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
262 NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
263 WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
264 RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB ``AS IS''
265 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
266 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
267 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
268 AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GDB
269 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
270 SERVICING, REPAIR OR CORRECTION.
272 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
273 FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
274 MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
275 FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
276 SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
277 INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
278 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
279 FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
280 FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
281 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
284 @node Input, Files, License, Top
285 @chapter GDB Input Conventions
287 GDB is invoked with the shell command @samp{gdb}. Once started, it reads
288 commands from the terminal until you tell it to exit.
290 A GDB command is a single line of input. There is no limit on how long
291 it can be. It starts with a command name, which is followed by arguments
292 whose meaning depends on the command name. Some command names do not
295 GDB command names may always be abbreviated if the abbreviation is
296 unambiguous. Sometimes even ambiguous abbreviations are allowed; for
297 example, @samp{s} is specially defined as equivalent to @samp{step}
298 even though there are other commands whose names start with @samp{s}.
299 Possible command abbreviations are often stated in the documentation
300 of the individual commands.
302 A blank line as input to GDB means to repeat the previous command verbatim.
303 Certain commands do not allow themselves to be repeated this way; these are
304 commands for which unintentional repetition might cause trouble and which
305 you are unlikely to want to repeat. Certain others (@samp{list} and
306 @samp{x}) act differently when repeated because that is more useful.
308 A line of input starting with @samp{#} is a comment; it does nothing.
309 This is useful mainly in command files (@xref{Command Files}).
311 Occasionally it is useful to execute a shell command from within gdb.
312 This can be done with the @samp{shell} command, or the shell escape
316 @item shell @var{shell command string}
318 @item !@var{shell command string}
321 Directs GDB to invoke an inferior shell to execute @samp{shell command string}.
322 The environmental variable @samp{SHELL} is used if it exists, otherwise gdb
326 GDB @dfn{prompts} for commands with a string that is normally @samp{(gdb)}.
327 When debugging GDB with GDB, it is useful to change the prompt in one of
328 the GDBs so that you can distinguish them. This can be done with the
329 @samp{set prompt} command.
332 @item set prompt @var{newprompt}
334 Directs GDB to use @var{newprompt} as its prompt string henceforth.
339 To exit GDB, use the @samp{quit} command (abbreviated @samp{q}).
340 @kbd{Ctrl-c} will not exit from GDB, but rather will terminate the action
341 of any GDB command that is in progress and return to GDB command level.
342 It is safe to type @kbd{Ctrl-c} at any time because GDB does not allow
343 it to take effect until a time when it is safe.
345 @node Files, Options, Input, Top
346 @chapter Specifying GDB's Files
348 @cindex core dump file
349 @cindex executable file
351 GDB needs to know the filename of the program to be debugged. To debug a
352 core dump of a previous run, GDB must be told the filename of the core
356 * Arguments: File Arguments. Specifying files with arguments
357 (when you start GDB).
358 * Commands: File Commands. Specifying files with GDB commands.
361 @node File Arguments, File Commands, Files, Files
362 @section Specifying Files with Arguments
364 The usual way to specify the executable and core dump file names is with
365 two command arguments given when you start GDB. The first argument is used
366 as the file for execution and symbols, and the second argument (if any) is
367 used as the core dump file name. Thus,
374 specifies @file{progm} as the executable program and @file{core} as a core
375 dump file to examine. (You do not need to have a core dump file if what
376 you plan to do is debug the program interactively.)
378 @xref{Options}, for full information on command options and arguments for
381 @node File Commands,, File Arguments, Files
382 @section Specifying Files with Commands
384 Usually you specify the files for GDB to work with by giving arguments when
385 you invoke GDB. But occasionally it is necessary to change to a different
386 file during a GDB session. Or you may run GDB and forget to specify the
387 files you want to use. In these situations the GDB commands to specify new
391 @item exec-file @var{filename}
393 Specify that the program to be run is found in @var{filename}. If you
394 do not specify a directory and the file is not found in GDB's working
395 directory, GDB will use the environment variable @samp{PATH} as a list
396 of directories to search, just as the shell does when looking for a
399 @item symbol-file @var{filename}
401 Read symbol table information from file @var{filename}. @samp{PATH}
402 is searched when necessary. Most of the time you will use both the
403 @samp{exec-file} and @samp{symbol-file} commands on the same file.
405 @samp{symbol-file} with no argument clears out GDB's symbol table.
407 @item core-file @var{filename}
409 Specify the whereabouts of a core dump file to be used as the
410 ``contents of memory''. Note that the core dump contains only the
411 writable parts of memory; the read-only parts must come from the
414 @samp{core-file} with no argument specifies that no core file is
417 @item add-file @var{filename} @var{address}
419 The @samp{add-file} command takes two arguments, a file name, and the
420 address at which that file has been (or should be) dynamically loaded.
421 GDB will then treat that file as though it had always been dynamically
422 linked, and provide the user with all the normal GDB features, including
425 With the @samp{add-file} command, it is possible to debug code which was
426 not present in the initial load image of the program under test.
427 Suppose you have a program which can, while running, dynamically link a
428 program fragment into its address space. One program which does this is
429 KCL, a free common lisp implementation. The fragment will be loaded
430 into the main program's address space at some address, and the main
431 program can then call functions within the fragment by calculating (or
432 otherwise obtaining) their addresses.
436 Cancel running the program under GDB. This could be used if you wish
437 to debug a core dump instead. GDB ignores any core dump file if it is
438 actually running the program, so the @samp{kill} command is the only
439 sure way to go back to using the core dump file.
443 Print the names of the executable and core dump files currently in
444 use by GDB, and the file from which symbols were loaded.
447 While all three file-specifying commands allow both absolute and relative
448 file names as arguments, GDB always converts the file name to an absolute
449 one and remembers it that way.
451 The @samp{symbol-file} command causes GDB to forget the contents of its
452 convenience variables, the value history, and all breakpoints and
453 auto-display expressions. This is because they may contain pointers to the
454 internal data recording symbols and data types, which are part of the old
455 symbol table data being discarded inside GDB.
457 @node Options, Compilation, Files, Top
458 @chapter Options and Arguments for GDB
460 When you invoke GDB, you can pass commands telling it what files to
461 operate on and what other things to do.
464 * Mode Options:: Options controlling modes of operation.
465 * File Options:: Options to specify files (executable, coredump, commands)
466 * Other Arguments:: Any other arguments without options
470 @node Mode Options, File Options, Options, Options
471 @section Mode Options
475 Do not execute commands from the init files @file{.gdbinit}.
476 Normally, the commands in these files are executed after all the
477 command options and arguments have been processed. @xref{Command
481 ``Quiet''. Do not print the usual introductory messages.
484 Run in batch mode. Exit with code 1 after processing all the command
485 files specified with @samp{-x} (and @file{.gdbinit}, if not
486 inhibited). Exit also if, due to an error, GDB would otherwise
487 attempt to read a command from the terminal.
490 This option is used when Emacs runs GDB as a subprocess. It tells GDB
491 to output the full file name and line number in a standard,
492 recognizable fashion each time a stack frame is displayed (which
493 includes each time the program stops). This recognizable format looks
494 like two @samp{\032} characters, followed by the filename, line number
495 and character position separated by colons, and a newline. The
496 Emacs-to-GDB interface program uses the two @samp{\032} characters as
497 a signal to display the source code for the frame.
500 @node File Options, Other Arguments, Mode Options, Options
501 @section File-specifying Options
503 All the options and command line arguments given are processed
504 in sequential order. The order makes a difference when the
505 @samp{-x} command is used.
509 Read symbol table from file @var{file}.
512 Use file @var{file} as the executable file to execute when
513 appropriate, and for examining pure data in conjunction with a core
517 Read symbol table from file @var{file} and use it as the executable
521 Use file @var{file} as a core dump to examine.
524 Execute GDB commands from file @var{file}.
526 @item -d @var{directory}
527 Add @var{directory} to the path to search for source files.
530 @node Other Arguments,, File Options, Options
531 @section Other Arguments
533 If there are arguments to GDB that are not options or associated with
534 options, the first one specifies the symbol table and executable file name
535 (as if it were preceded by @samp{-se}) and the second one specifies a core
536 dump file name (as if it were preceded by @samp{-c}).
538 @node Compilation, Running, Options, Top
539 @chapter Compiling Your Program for Debugging
541 In order to debug a program effectively, you need to ask for debugging
542 information when you compile it. This information in the object file
543 describes the data type of each variable or function and the correspondence
544 between source line numbers and addresses in the executable code.
546 To request debugging information, specify the @samp{-g} option when you run
549 The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
550 together. This means that you cannot ask for optimization if you ask for
551 debugger information.
553 The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
554 possible to debug optimized code. We recommend that you @emph{always} use
555 @samp{-g} whenever you compile a program. You may think the program is
556 correct, but there's no sense in pushing your luck.
558 If you are using the GNU C compiler, the GNU assembler and the GNU linker,
559 you can choose between two formats of debugging information: the standard
560 Unix format, which is what you get with @samp{-g}, and GDB's own format,
561 which you request by using @samp{-gg} instead of @samp{-g}. This stores
562 debugging information in the executable file in a format much like that
563 which is used inside GDB. This has these advantages and disadvantages:
567 GDB can read @samp{-gg} format more than twice as fast as Unix
571 The @samp{-gg} format uses much more disk space than Unix format.
574 The Unix debuggers can understand only Unix format, so you cannot use
575 Unix source-level debuggers if you compile with @samp{-gg}. (The
576 @code{adb} debugger works with either format; it does not use this
577 information in any case.)
580 @node Running, Stopping, Compilation, Top
581 @chapter Running Your Program Under GDB
585 To start your program under GDB, use the @samp{run} command. The program
586 must already have been specified using the @samp{exec-file} command or with
587 an argument to GDB (@pxref{Files}); what @samp{run} does is create an
588 inferior process, load the program into it, and set it in motion.
590 The execution of a program is affected by certain information it receives
591 from its superior. GDB provides ways to specify them, which you must do
592 @i{before} starting the program. (You can change them after starting the
593 program, but such changes do not affect the program unless you start it
597 @item The @i{arguments.}
598 You specify the arguments to give the program as the arguments of the
601 @item The @i{environment.}
602 The program normally inherits its environment from GDB, but you can
603 use the GDB commands @samp{set environment} and
604 @samp{unset environment} to change parts of the environment that will
605 be given to the program.@refill
607 @item The @i{working directory.}
608 The program inherits its working directory from GDB. You can set GDB's
609 working directory with the @samp{cd} command in GDB.
612 After the @samp{run} command, the debugger does nothing but wait for your
613 program to stop. @xref{Stopping}.
615 Note that once your program has been started by the @samp{run} command,
616 you may evaluate expressions that involve calls to functions in the
617 inferior. @xref{Expressions}. If you wish to evaluate a function
618 simply for it's side affects, you may use the @samp{set} command.
622 * Arguments:: Specifying the arguments for your program.
623 * Environment:: Specifying the environment for your program.
624 * Working Directory:: Specifying the working directory for giving
625 to your program when it is run.
626 * Input/Output:: Specifying the program's standard input and output.
627 * Attach:: Debugging a process started outside GDB.
630 @node Arguments, Environment, Running, Running
631 @section Your Program's Arguments
633 @cindex arguments (to your program)
634 You specify the arguments to give the program as the arguments of the
635 @samp{run} command. They are passed to a shell, which expands wildcard
636 characters and performs redirection of I/O, and thence to the program.
638 @samp{run} with no arguments uses the same arguments used by the previous
642 The command @samp{set args} can be used to specify the arguments to be used
643 the next time the program is run. If @samp{set args} has no arguments, it
644 means to use no arguments the next time the program is run. If you have
645 run your program with arguments and want to run it again with no arguments,
646 this is the only way to do so.
648 @node Environment, Working Directory, Arguments, Running
649 @section Your Program's Environment
651 @cindex environment (of your program)
652 The @dfn{environment} consists of a set of @dfn{environment variables} and
653 their values. Environment variables conventionally record such things as
654 your user name, your home directory, your terminal type, and your search
655 path for programs to run. Usually you set up environment variables with
656 the shell and they are inherited by all the other programs you run. When
657 debugging, it can be useful to try running the program with different
658 environments without having to start the debugger over again.
661 @item info environment @var{varname}
662 @kindex info environment
663 Print the value of environment variable @var{varname} to be given to
664 your program when it is started. This command can be abbreviated
665 @samp{i env @var{varname}}.
667 @item info environment
668 Print the names and values of all environment variables to be given to
669 your program when it is started. This command can be abbreviated
672 @item set environment @var{varname} @var{value}
673 @item set environment @var{varname} = @var{value}
674 @kindex set environment
675 Sets environment variable @var{varname} to @var{value}, for your program
676 only, not for GDB itself. @var{value} may be any string; the values of
677 environment variables are just strings, and any interpretation is
678 supplied by your program itself. The @var{value} parameter is optional;
679 if it is eliminated, the variable is set to a null value. This command
680 can be abbreviated as short as @samp{set e}.
682 @item delete environment @var{varname}
683 @kindex delete environment
684 @item unset environment @var{varname}
685 @kindex unset environment
686 Remove variable @var{varname} from the environment to be passed to
687 your program. This is different from @samp{set env @var{varname} =}
688 because @samp{delete environment} makes a variable not be defined at
689 all, which is distinguishable from an empty value. This command can
690 be abbreviated @samp{d e}.
693 @node Working Directory, Input/Output, Environment, Running
694 @section Your Program's Working Directory
696 @cindex working directory (of your program)
697 Each time you start your program with @samp{run}, it inherits its working
698 directory from the current working directory of GDB. GDB's working
699 directory is initially whatever it inherited from its superior, but you can
700 specify the working directory for GDB with the @samp{cd} command.
702 The GDB working directory also serves as a default for the commands
703 that specify files for GDB to operate on. @xref{Files}.
706 @item cd @var{directory}
708 Set GDB's working directory to @var{directory}.
712 Print GDB's working directory.
715 @node Input/Output, Attach, Working Directory, Running
716 @section Your Program's Input and Output
719 @cindex controlling terminal
720 By default, the program you run under GDB does input and output to the same
721 terminal that GDB uses.
723 You can redirect the program's input and/or output using @samp{sh}-style
724 redirection commands in the @samp{run} command. For example,
731 starts the program, diverting its output to the file @file{outfile}.
734 Another way to specify where the program should do input and output is with
735 the @samp{tty} command. This command accepts a file name as argument, and
736 causes this file to be the default for future @samp{run} commands. It also
737 resets the controlling terminal for future @samp{run} commands. For
745 directs that processes started with subsequent @samp{run} commands default
746 to do input and output on the terminal @file{/dev/ttyb} and sets the
747 controlling terminal to @file{/dev/ttyb}. An explicit redirection in
748 @samp{run} overrides the @samp{tty} command's effect on input/output
751 When you use the @samp{tty} command or redirect input in the @samp{run}
752 command, the @emph{input for your program} comes from the specified file,
753 but the input for GDB still comes from your terminal.
755 @node Attach,, Input/Output, Running
756 @section Debugging an Already-Running Process
761 Some operating systems (in particular, Sun) allow GDB to begin debugging an
762 already-running process that was started outside of GDB. To do this you
763 must use the @samp{attach} command instead of the @samp{run} command.
765 The @samp{attach} command requires one argument, which is the process-id of
766 the process you want to debug. (The usual way to find out the process-id
767 of the process is with the @samp{ps} utility.)
769 The first thing GDB does after arranging to debug the process is to stop
770 it. You can examine and modify an attached process with all the GDB
771 commands that ordinarily available when you start processes with
772 @samp{run}. You can insert breakpoints; you can step and continue; you
773 can modify storage. If you would rather the process continue running,
774 use the @samp{continue} command after attaching.
776 When you are finished debugging the attached process, you can use the
777 @samp{detach} command to release it from GDB's control. Detaching
778 the process continues its execution. After the @samp{detach} command,
779 that process and GDB become completely independent once more, and you
780 are ready to @samp{attach} another process or start one with @samp{run}.
782 If you exit GDB or use the @samp{run} command while you have an attached
783 process, you kill that process. You will be asked for confirmation if you
784 try to do either of these things.
786 @node Stopping, Stack, Running, Top
787 @chapter Stopping and Continuing
789 When you run a program normally, it runs until exiting. The purpose
790 of using a debugger is so that you can stop it before that point;
791 or so that if the program runs into trouble you can find out why.
794 * Signals:: Fatal signals in your program just stop it;
795 then you can use GDB to see what is going on.
796 * Breakpoints:: Breakpoints let you stop your program when it
797 reaches a specified point in the code.
798 * Continuing:: Resuming execution until the next signal or breakpoint.
799 * Stepping:: Stepping runs the program a short distance and
800 then stops it wherever it has come to.
803 @node Signals, Breakpoints, Stopping, Stopping
806 A signal is an asynchronous event that can happen in a program. The
807 operating system defines the possible kinds of signals, and gives each kind
808 a name and a number. For example, @code{SIGINT} is the signal a program
809 gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
810 gets from referencing a place in memory far away from all the areas in use;
811 @code{SIGALRM} occurs when the alarm clock timer goes off (which happens
812 only if the program has requested an alarm).
814 Some signals, including @code{SIGALRM}, are a normal part of the
815 functioning of the program. Others, such as @code{SIGSEGV}, indicate
816 errors; these signals are @dfn{fatal} (kill the program immediately) if the
817 program has not specified in advance some other way to handle the signal.
818 @code{SIGINT} does not indicate an error in the program, but it is normally
819 fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
821 GDB has the ability to detect any occurrence of a signal in the program
822 running under GDB's control. You can tell GDB in advance what to do for
825 Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM}
826 (so as not to interfere with their role in the functioning of the program)
827 but to stop the program immediately whenever an error signal happens.
828 You can change these settings with the @samp{handle} command. You must
829 specify which signal you are talking about with its number.
834 Print a table of all the kinds of signals and how GDB has been told to
835 handle each one. You can use this to see the signal numbers of all
836 the defined types of signals.
838 @item handle @var{signalnum} @var{keywords}@dots{}
840 Change the way GDB handles signal @var{signalnum}. The @var{keywords}
841 say what change to make.
844 To use the @samp{handle} command you must know the code number of the
845 signal you are concerned with. To find the code number, type @samp{info
846 signal} which prints a table of signal names and numbers.
848 The keywords allowed by the handle command can be abbreviated. Their full
853 GDB should stop the program when this signal happens. This implies
854 the @samp{print} keyword as well.
857 GDB should print a message when this signal happens.
860 GDB should not stop the program when this signal happens. It may
861 still print a message telling you that the signal has come in.
864 GDB should not mention the occurrence of the signal at all. This
865 implies the @samp{nostop} keyword as well.
868 GDB should allow the program to see this signal; the program will be
869 able to handle the signal, or may be terminated if the signal is fatal
873 GDB should not allow the program to see this signal.
876 When a signal has been set to stop the program, the program cannot see the
877 signal until you continue. It will see the signal then, if @samp{pass} is
878 in effect for the signal in question @i{at that time}. In other words,
879 after GDB reports a signal, you can use the @samp{handle} command with
880 @samp{pass} or @samp{nopass} to control whether that signal will be seen by
881 the program when you later continue it.
883 You can also use the @samp{signal} command to prevent the program from
884 seeing a signal, or cause it to see a signal it normally would not see,
885 or to give it any signal at any time. @xref{Signaling}.
887 @node Breakpoints, Continuing, Signals, Stopping
891 A @dfn{breakpoint} makes your program stop whenever a certain point in the
892 program is reached. You set breakpoints explicitly with GDB commands,
893 specifying the place where the program should stop by line number, function
894 name or exact address in the program. You can add various other conditions
895 to control whether the program will stop.
897 Each breakpoint is assigned a number when it is created; these numbers are
898 successive integers starting with 1. In many of the commands for controlling
899 various features of breakpoints you use the breakpoint number to say which
900 breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
901 @dfn{disabled}; if disabled, it has no effect on the program until you
906 The command @samp{info break} prints a list of all breakpoints set and not
907 cleared, showing their numbers, where in the program they are, and any
908 special features in use for them. Disabled breakpoints are included in the
909 list, but marked as disabled. @samp{info break} with a breakpoint number
910 as argument lists only that breakpoint. The convenience variable @samp{$_}
911 and the default examining-address for the @samp{x} command are set to the
912 address of the last breakpoint listed (@pxref{Memory}).
915 * Set Breaks:: How to establish breakpoints.
916 * Clear Breaks:: How to remove breakpoints no longer needed.
917 * Disabling:: How to disable breakpoints (turn them off temporarily).
918 * Conditions:: Making extra conditions on whether to stop.
919 * Break Commands:: Commands to be executed at a breakpoint.
920 * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
923 @node Set Breaks, Clear Breaks, Breakpoints, Breakpoints
924 @subsection Setting Breakpoints
927 Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
928 You have several ways to say where the breakpoint should go.
931 @item break @var{function}
932 Set a breakpoint at entry to function @var{function}.
934 @item break @var{linenum}
935 Set a breakpoint at line @var{linenum} in the current source file.
936 That file is the last file whose source text was printed. This
937 breakpoint will stop the program just before it executes any of the
940 @item break @var{filename}:@var{linenum}
941 Set a breakpoint at line @var{linenum} in source file @var{filename}.
943 @item break @var{filename}:@var{function}
944 Set a breakpoint at entry to function @var{function} found in file
945 @var{filename}. Specifying a filename as well as a function name is
946 superfluous except when multiple files contain similarly named
949 @item break *@var{address}
950 Set a breakpoint at address @var{address}. You can use this to set
951 breakpoints in parts of the program which do not have debugging
952 information or source files.
955 Set a breakpoint at the next instruction to be executed in the selected
956 stack frame (@pxref{Stack}). In any selected frame but the innermost,
957 this will cause the program to stop as soon as control returns to that
958 frame. This is equivalent to a @samp{finish} command in the frame
959 inside the selected frame. If this is done in the innermost frame gdb
960 will stop the next time it reaches the current location; this may be
961 useful inside of loops. It does not stop at this breakpoint immediately
962 upon continuation of the program since no code would be executed if it
965 @item break @dots{} if @var{cond}
966 Set a breakpoint with condition @var{cond}; evaluate the expression
967 @var{cond} each time the breakpoint is reached, and stop only if the
968 value is nonzero. @samp{@dots{}} stands for one of the possible
969 arguments described above (or no argument) specifying where to break.
970 @xref{Conditions}, for more information on breakpoint conditions.
972 @item tbreak @var{args}
974 Set a breakpoint enabled only for one stop. @var{args} are the
975 same as in the @samp{break} command, and the breakpoint is set in the same
976 way, but the breakpoint is automatically @dfn{disabled} the first time it
980 GDB allows you to set any number of breakpoints at the same place in the
981 program. There is nothing silly or meaningless about this. When the
982 breakpoints are conditional, this is even useful (@pxref{Conditions}).
984 @node Clear Breaks, Disabling, Set Breaks, Breakpoints
985 @subsection Clearing Breakpoints
987 @cindex clear breakpoint
988 @cindex delete breakpoints
989 It is often necessary to eliminate a breakpoint once it has done its job
990 and you no longer want the program to stop there. This is called
991 @dfn{clearing} or @samp{deleting} the breakpoint. A breakpoint that
992 has been cleared no longer exists in any sense.
994 With the @samp{clear} command you can clear breakpoints according to where
995 they are in the program. With the @samp{delete} command you can clear
996 individual breakpoints by specifying their breakpoint numbers.
998 @b{It is not necessary to clear a breakpoint to proceed past it.} GDB
999 automatically ignores breakpoints in the first instruction to be executed
1000 when you continue execution at the same address where the program stopped.
1005 Clear any breakpoints at the next instruction to be executed in the
1006 selected stack frame (@pxref{Selection}). When the innermost frame
1007 is selected, this is a good way to clear a breakpoint that the program
1010 @item clear @var{function}
1011 @itemx clear @var{filename}:@var{function}
1012 Clear any breakpoints set at entry to the function @var{function}.
1014 @item clear @var{linenum}
1015 @item clear @var{filename}:@var{linenum}
1016 Clear any breakpoints set at or within the code of the specified line.
1018 @item delete @var{bnums}@dots{}
1020 Delete the breakpoints of the numbers specified as arguments.
1021 A breakpoint deleted is forgotten completely.
1024 @node Disabling, Conditions, Clear Breaks, Breakpoints
1025 @subsection Disabling Breakpoints
1027 @cindex disabled breakpoints
1028 @cindex enabled breakpoints
1029 Rather than clearing a breakpoint, you might prefer to @dfn{disable} it.
1030 This makes the breakpoint inoperative as if it had been cleared, but
1031 remembers the information on the breakpoint so that you can @dfn{enable}
1034 You disable and enable breakpoints with the @samp{enable} and
1035 @samp{disable} commands, specifying one or more breakpoint numbers as
1036 arguments. Use @samp{info break} to print a list of breakpoints if you
1037 don't know which breakpoint numbers to use.
1039 A breakpoint can have any of four different states of enablement:
1043 Enabled. The breakpoint will stop the program. A breakpoint made
1044 with the @samp{break} command starts out in this state.
1046 Disabled. The breakpoint has no effect on the program.
1048 Enabled once. The breakpoint will stop the program, but
1049 when it does so it will become disabled. A breakpoint made
1050 with the @samp{tbreak} command starts out in this state.
1052 Enabled for deletion. The breakpoint will stop the program, but
1053 immediately after it does so it will be deleted permanently.
1056 You change the state of enablement of a breakpoint with the following
1060 @item disable breakpoints @var{bnums}@dots{}
1061 @kindex disable breakpoints
1062 @item disable @var{bnums}@dots{}
1064 Disable the specified breakpoints. A disabled breakpoint has no
1065 effect but is not forgotten. All options such as ignore-counts,
1066 conditions and commands are remembered in case the breakpoint is
1067 enabled again later.
1069 @item enable breakpoints @var{bnums}@dots{}
1070 @kindex enable breakpoints
1071 @item enable @var{bnums}@dots{}
1073 Enable the specified breakpoints. They become effective once again in
1074 stopping the program, until you specify otherwise.
1076 @item enable breakpoints once @var{bnums}@dots{}
1077 @item enable once @var{bnums}@dots{}
1078 Enable the specified breakpoints temporarily. Each will be disabled
1079 again the next time it stops the program (unless you have used one of
1080 these commands to specify a different state before that time comes).
1082 @item enable breakpoints delete @var{bnums}@dots{}
1083 @item enable delete @var{bnums}@dots{}
1084 Enable the specified breakpoints to work once and then die. Each of
1085 the breakpoints will be deleted the next time it stops the program
1086 (unless you have used one of these commands to specify a different
1087 state before that time comes).
1090 Aside from the automatic disablement or deletion of a breakpoint when it
1091 stops the program, which happens only in certain states, the state of
1092 enablement of a breakpoint changes only when one of the commands above
1095 @node Conditions, Break Commands, Disabling, Breakpoints
1096 @subsection Break Conditions
1099 The simplest sort of breakpoint breaks every time the program reaches a
1100 specified place. You can also specify a @dfn{condition} for a breakpoint.
1101 A condition is just a boolean expression in your programming language
1102 (@xref{Expressions}). A breakpoint with a condition evaluates the
1103 expression each time the program reaches it, and the program stops
1104 only if the condition is true.
1106 Break conditions may have side effects, and may even call functions in your
1107 program. These may sound like strange things to do, but their effects are
1108 completely predictable unless there is another enabled breakpoint at the
1109 same address. (In that case, GDB might see the other breakpoint first and
1110 stop the program without checking the condition of this one.) Note that
1111 breakpoint commands are usually more convenient and flexible for the
1112 purpose of performing side effects when a breakpoint is reached
1113 (@pxref{Break Commands}).
1115 Break conditions can be specified when a breakpoint is set, by using
1116 @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}.
1117 They can also be changed at any time with the @samp{condition} command:
1120 @item condition @var{bnum} @var{expression}
1122 Specify @var{expression} as the break condition for breakpoint number
1123 @var{bnum}. From now on, this breakpoint will stop the program only if
1124 the value of @var{expression} is true (nonzero, in C). @var{expression}
1125 is not evaluated at the time the @samp{condition} command is given.
1128 @item condition @var{bnum}
1129 Remove the condition from breakpoint number @var{bnum}. It becomes
1130 an ordinary unconditional breakpoint.
1133 @cindex ignore count (of breakpoint)
1134 A special feature is provided for one kind of condition: to prevent the
1135 breakpoint from doing anything until it has been reached a certain number
1136 of times. This is done with the @dfn{ignore count} of the breakpoint.
1137 When the program reaches a breakpoint whose ignore count is positive, then
1138 instead of stopping, it just decrements the ignore count by one and
1142 @item ignore @var{bnum} @var{count}
1144 Set the ignore count of breakpoint number @var{bnum} to @var{count}.
1145 The next @var{count} times the breakpoint is reached, it will not stop.
1147 To make the breakpoint stop the next time it is reached, specify
1150 @item cont @var{count}
1151 Continue execution of the program, setting the ignore count of the
1152 breakpoint that the program stopped at to @var{count} minus one.
1153 Continuing through the breakpoint does not itself count as one of
1154 @var{count}. Thus, the program will not stop at this breakpoint until the
1155 @var{count}'th time it is hit.
1157 This command is allowed only when the program stopped due to a
1158 breakpoint. At other times, the argument to @samp{cont} is ignored.
1161 If a breakpoint has a positive ignore count and a condition, the condition
1162 is not checked. Once the ignore count reaches zero, the condition will
1163 start to be checked.
1165 Note that you could achieve the effect of the ignore count with a condition
1166 such as @samp{$foo-- <= 0} using a debugger convenience variable that is
1167 decremented each time. That is why the ignore count is considered a
1168 special case of a condition. @xref{Convenience Vars}.
1170 @node Break Commands, Error in Breakpoints, Conditions, Breakpoints
1171 @subsection Commands Executed on Breaking
1173 @cindex breakpoint commands
1174 You can give any breakpoint a series of commands to execute when the
1175 program stops due to that breakpoint. For example, you might want to
1176 print the values of certain expressions, or enable other breakpoints.
1179 @item commands @var{bnum}
1180 Specify commands for breakpoint number @var{bnum}. The commands
1181 themselves appear on the following lines. Type a line containing just
1182 @samp{end} to terminate the commands.
1184 To remove all commands from a breakpoint, use the command
1185 @samp{commands} and follow it immediately by @samp{end}; that is, give
1188 With no arguments, @samp{commands} refers to the last breakpoint set.
1191 It is possible for breakpoint commands to start the program up again.
1192 Simply use the @samp{cont} command, or @samp{step}, or any other command
1193 to resume execution. However, any remaining breakpoint commands are
1194 ignored. When the program stops again, GDB will act according to why
1195 that stop took place.
1198 If the first command specified is @samp{silent}, the usual message about
1199 stopping at a breakpoint is not printed. This may be desirable for
1200 breakpoints that are to print a specific message and then continue.
1201 If the remaining commands too print nothing, you will see no sign that
1202 the breakpoint was reached at all. @samp{silent} is not really a command;
1203 it is meaningful only at the beginning of the commands for a breakpoint.
1205 The commands @samp{echo} and @samp{output} that allow you to print precisely
1206 controlled output are often useful in silent breakpoints. @xref{Output}.
1208 For example, here is how you could use breakpoint commands to print the
1209 value of @code{x} at entry to @code{foo} whenever it is positive. We
1210 assume that the newly created breakpoint is number 4; @samp{break} will
1211 print the number that is assigned.
1224 One application for breakpoint commands is to correct one bug so you can
1225 test another. Put a breakpoint just after the erroneous line of code, give
1226 it a condition to detect the case in which something erroneous has been
1227 done, and give it commands to assign correct values to any variables that
1228 need them. End with the @samp{cont} command so that the program does not
1229 stop, and start with the @samp{silent} command so that no output is
1230 produced. Here is an example:
1241 One deficiency in the operation of automatically continuing breakpoints
1242 under Unix appears when your program uses raw mode for the terminal.
1243 GDB switches back to its own terminal modes (not raw) before executing
1244 commands, and then must switch back to raw mode when your program is
1245 continued. This causes any pending terminal input to be lost.
1247 In the GNU system, this will be fixed by changing the behavior of
1250 Under Unix, when you have this problem, you might be able to get around
1251 it by putting your actions into the breakpoint condition instead of
1252 commands. For example
1255 condition 5 (x = y + 4), 0
1259 is a condition expression (@xref{Expressions}) that will change @code{x}
1260 as needed, then always have the value 0 so the program will not stop.
1261 Loss of input is avoided here because break conditions are evaluated
1262 without changing the terminal modes. When you want to have nontrivial
1263 conditions for performing the side effects, the operators @samp{&&},
1264 @samp{||} and @samp{?@: @dots{} :@:} may be useful.
1266 @node Error in Breakpoints,, Break Commands, Breakpoints
1267 @subsection ``Cannot Insert Breakpoints'' Error
1269 Under some Unix systems, breakpoints cannot be used in a program if any
1270 other process is running that program. Attempting to run or continue
1271 the program with a breakpoint in this case will cause GDB to stop it.
1273 When this happens, you have three ways to proceed:
1277 Remove or disable the breakpoints, then continue.
1280 Suspend GDB, and copy the file containing the program to a new name.
1281 Resume GDB and use the @samp{exec-file} command to specify that GDB
1282 should run the program under that name. Then start the program again.
1285 Recompile the program so that the text is non-sharable (a.out format
1289 @node Continuing, Stepping, Breakpoints, Stopping
1292 After your program stops, most likely you will want it to run some more if
1293 the bug you are looking for has not happened yet.
1298 Continue running the program at the place where it stopped.
1301 If the program stopped at a breakpoint, the place to continue running
1302 is the address of the breakpoint. You might expect that continuing would
1303 just stop at the same breakpoint immediately. In fact, @samp{cont}
1304 takes special care to prevent that from happening. You do not need
1305 to clear the breakpoint to proceed through it after stopping at it.
1307 You can, however, specify an ignore-count for the breakpoint that the
1308 program stopped at, by means of an argument to the @samp{cont} command.
1311 If the program stopped because of a signal other than @code{SIGINT} or
1312 @code{SIGTRAP}, continuing will cause the program to see that signal.
1313 You may not want this to happen. For example, if the program stopped
1314 due to some sort of memory reference error, you might store correct
1315 values into the erroneous variables and continue, hoping to see more
1316 execution; but the program would probably terminate immediately as
1317 a result of the fatal signal once it sees the signal. To prevent this,
1318 you can continue with @samp{signal 0}. @xref{Signaling}. You can
1319 also act in advance to prevent the program from seeing certain kinds
1320 of signals, using the @samp{handle} command (@pxref{Signals}).
1322 @node Stepping,, Continuing, Stopping
1326 @dfn{Stepping} means setting your program in motion for a limited time, so
1327 that control will return automatically to the debugger after one line of
1328 code or one machine instruction. Breakpoints are active during stepping
1329 and the program will stop for them even if it has not gone as far as the
1330 stepping command specifies.
1335 Proceed the program until control reaches a different line, then stop
1336 it and return to the debugger. This command is abbreviated @samp{s}.
1338 @item step @var{count}
1339 Proceed as in @samp{step}, but do so @var{count} times. If a breakpoint
1340 or a signal not related to stepping is reached before @var{count} steps,
1341 stepping stops right away.
1343 This command may be given when control is within a routine for which
1344 there is no debugging information. In that case, execution will proceed
1345 until control reaches a different routine, or is about to return from
1346 this routine. An argument repeats this action.
1350 Similar to @samp{step}, but any function calls appearing within the line of
1351 code are executed without stopping. Execution stops when control reaches a
1352 different line of code at the stack level which was executing when the
1353 @samp{next} command was given. This command is abbreviated @samp{n}.
1355 An argument is a repeat count, as in @samp{step}.
1357 @samp{next} within a routine without debugging information acts as does
1358 @samp{step}, but any function calls appearing within the code of the
1359 routine are executed without stopping.
1363 Continue running until just after the selected stack frame returns
1364 (or until there is some other reason to stop, such as a fatal signal
1365 or a breakpoint). Print value returned by the selected stack frame (if
1368 Contrast this with the @samp{return} command (@pxref{Returning}).
1372 Proceed the program until control reaches a line greater than the current
1373 line, then stop is and return to the debugger. Control is also returned to
1374 the debugger if the program exits the current stack frame. Note that this
1375 form of the command uses single stepping, and hence is slower than
1376 @samp{until} with an argument. This command is abbreviated @samp{u}.
1378 @item until @var{location}
1379 Proceed the program until either the specified location is reached, or the
1380 current (innermost) stack frame returns. This form of the command uses
1381 breakpoints, and hence is quicker than @samp{until} without an argument.
1387 Proceed one machine instruction, then stop and return to the debugger.
1389 It is often useful to do @samp{display/i $pc} when stepping by machine
1390 instructions. This will cause the next instruction to be executed to
1391 be displayed automatically at each stop. @xref{Auto Display}.
1393 An argument is a repeat count, as in @samp{step}.
1399 Proceed one machine instruction, but if it is a subroutine call,
1400 proceed until the subroutine returns.
1402 An argument is a repeat count, as in @samp{next}.
1405 A typical technique for using stepping is to put a breakpoint
1406 (@pxref{Breakpoints}) at the beginning of the function or the section of
1407 the program in which a problem is believed to lie, and then step through
1408 the suspect area, examining the variables that are interesting, until the
1411 The @samp{cont} command can be used after stepping to resume execution
1412 until the next breakpoint or signal.
1414 @node Stack, Source, Stopping, Top
1415 @chapter Examining the Stack
1417 When your program has stopped, the first thing you need to know is where it
1418 stopped and how it got there.
1421 Each time your program performs a function call, the information about
1422 where in the program the call was made from is saved in a block of data
1423 called a @dfn{stack frame}. The frame also contains the arguments of the
1424 call and the local variables of the function that was called. All the
1425 stack frames are allocated in a region of memory called the @dfn{call
1428 When your program stops, the GDB commands for examining the stack allow you
1429 to see all of this information.
1431 One of the stack frames is @dfn{selected} by GDB and many GDB commands
1432 refer implicitly to the selected frame. In particular, whenever you ask
1433 GDB for the value of a variable in the program, the value is found in the
1434 selected frame. There are special GDB commands to select whichever frame
1435 you are interested in.
1437 When the program stops, GDB automatically selects the currently executing
1438 frame and describes it briefly as the @samp{frame} command does
1439 (@pxref{Frame Info, Info}).
1442 * Frames:: Explanation of stack frames and terminology.
1443 * Backtrace:: Summarizing many frames at once.
1444 * Selection:: How to select a stack frame.
1445 * Info: Frame Info, Commands to print information on stack frames.
1448 @node Frames, Backtrace, Stack, Stack
1449 @section Stack Frames
1452 The call stack is divided up into contiguous pieces called @dfn{frames};
1453 each frame is the data associated with one call to one function. The frame
1454 contains the arguments given to the function, the function's local
1455 variables, and the address at which the function is executing.
1457 @cindex initial frame
1458 @cindex outermost frame
1459 @cindex innermost frame
1460 When your program is started, the stack has only one frame, that of the
1461 function @code{main}. This is called the @dfn{initial} frame or the
1462 @dfn{outermost} frame. Each time a function is called, a new frame is
1463 made. Each time a function returns, the frame for that function invocation
1464 is eliminated. If a function is recursive, there can be many frames for
1465 the same function. The frame for the function in which execution is
1466 actually occurring is called the @dfn{innermost} frame. This is the most
1467 recently created of all the stack frames that still exist.
1469 @cindex frame pointer
1470 Inside your program, stack frames are identified by their addresses. A
1471 stack frame consists of many bytes, each of which has its own address; each
1472 kind of computer has a convention for choosing one of those bytes whose
1473 address serves as the address of the frame. Usually this address is kept
1474 in a register called the @dfn{frame pointer register} while execution is
1475 going on in that frame.
1477 @cindex frame number
1478 GDB assigns numbers to all existing stack frames, starting with zero for
1479 the innermost frame, one for the frame that called it, and so on upward.
1480 These numbers do not really exist in your program; they are to give you a
1481 way of talking about stack frames in GDB commands.
1483 @cindex selected frame
1484 Many GDB commands refer implicitly to one stack frame. GDB records a stack
1485 frame that is called the @dfn{selected} stack frame; you can select any
1486 frame using one set of GDB commands, and then other commands will operate
1487 on that frame. When your program stops, GDB automatically selects the
1490 @node Backtrace, Selection, Frames, Stack
1493 A backtrace is a summary of how the program got where it is. It shows one
1494 line per frame, for many frames, starting with the currently executing
1495 frame (frame zero), followed by its caller (frame one), and on up the
1501 Print a backtrace of the entire stack: one line per frame for all
1502 frames in the stack.
1504 You can stop the backtrace at any time by typing the system interrupt
1505 character, normally @kbd{Control-C}.
1507 @item backtrace @var{n}
1509 Similar, but stop after @var{n} frames.
1511 @item backtrace @var{-n}
1513 Similar, but print the outermost @var{n} frames instead of the
1517 Each line in a backtrace shows the frame number, the program counter, the
1518 function and its arguments, and the source file name and line number (if
1519 known). The program counter is omitted if is the beginning of the code for
1520 the source line. This is the same as the first of the two lines printed
1521 when you select a frame.
1523 @node Selection, Frame Info, Backtrace, Stack
1524 @section Selecting a Frame
1526 Most commands for examining the stack and other data in the program work on
1527 whichever stack frame is selected at the moment. Here are the commands for
1528 selecting a stack frame; all of them finish by printing a brief description
1529 of the stack frame just selected.
1534 Select frame number @var{n}. Recall that frame zero is the innermost
1535 (currently executing) frame, frame one is the frame that called the
1536 innermost one, and so on. The highest-numbered frame is @code{main}'s
1539 @item frame @var{addr}
1540 Select the frame at address @var{addr}. This is useful mainly if the
1541 chaining of stack frames has been damaged by a bug, making it
1542 impossible for GDB to assign numbers properly to all frames. In
1543 addition, this can be useful when the program has multiple stacks and
1544 switches between them.
1548 Select the frame @var{n} frames up from the frame previously selected.
1549 For positive numbers @var{n}, this advances toward the outermost
1550 frame, to higher frame numbers, to frames that have existed longer.
1551 @var{n} defaults to one.
1555 Select the frame @var{n} frames down from the frame previously
1556 selected. For positive numbers @var{n}, this advances toward the
1557 innermost frame, to lower frame numbers, to frames that were created
1558 more recently. @var{n} defaults to one.
1561 All of these commands end by printing some information on the frame that
1562 has been selected: the frame number, the function name, the arguments, the
1563 source file and line number of execution in that frame, and the text of
1564 that source line. For example:
1567 #3 main (argc=3, argv=??, env=??) at main.c, line 67
1568 67 read_input_file (argv[i]);
1571 After such a printout, the @samp{list} command with no arguments will print
1572 ten lines centered on the point of execution in the frame. @xref{List}.
1574 @node Frame Info,, Selection, Stack
1575 @section Information on a Frame
1577 There are several other commands to print information about the selected
1582 This command prints a brief description of the selected stack frame.
1583 It can be abbreviated @samp{f}. With an argument, this command is
1584 used to select a stack frame; with no argument, it does not change
1585 which frame is selected, but still prints the same information.
1589 This command prints a verbose description of the selected stack frame,
1590 including the address of the frame, the addresses of the next frame in
1591 (called by this frame) and the next frame out (caller of this frame),
1592 the address of the frame's arguments, the program counter saved in it
1593 (the address of execution in the caller frame), and which registers
1594 were saved in the frame. The verbose description is useful when
1595 something has gone wrong that has made the stack format fail to fit
1596 the usual conventions.
1598 @item info frame @var{addr}
1599 Print a verbose description of the frame at address @var{addr},
1600 without selecting that frame. The selected frame remains unchanged by
1605 Print the arguments of the selected frame, each on a separate line.
1609 Print the local variables of the selected frame, each on a separate
1610 line. These are all variables declared static or automatic within all
1611 program blocks that execution in this frame is currently inside of.
1614 @node Source, Data, Stack, Top
1615 @chapter Examining Source Files
1617 GDB knows which source files your program was compiled from, and
1618 can print parts of their text. When your program stops, GDB
1619 spontaneously prints the line it stopped in. Likewise, when you
1620 select a stack frame (@pxref{Selection}), GDB prints the line
1621 which execution in that frame has stopped in. You can also
1622 print parts of source files by explicit command.
1625 * List:: Using the @samp{list} command to print source files.
1626 * Search:: Commands for searching source files.
1627 * Source Path:: Specifying the directories to search for source files.
1630 @node List, Search, Source, Source
1631 @section Printing Source Lines
1634 To print lines from a source file, use the @samp{list} command
1635 (abbreviated @samp{l}). There are several ways to specify what part
1636 of the file you want to print.
1638 Here are the forms of the @samp{list} command most commonly used:
1641 @item list @var{linenum}
1642 Print ten lines centered around line number @var{linenum} in the
1643 current source file.
1645 @item list @var{function}
1646 Print ten lines centered around the beginning of function
1650 Print ten more lines. If the last lines printed were printed with a
1651 @samp{list} command, this prints ten lines following the last lines
1652 printed; however, if the last line printed was a solitary line printed
1653 as part of displaying a stack frame (@pxref{Stack}), this prints ten
1654 lines centered around that line.
1657 Print ten lines just before the lines last printed.
1660 Repeating a @samp{list} command with @key{RET} discards the argument,
1661 so it is equivalent to typing just @samp{list}. This is more useful
1662 than listing the same lines again. An exception is made for an
1663 argument of @samp{-}; that argument is preserved in repetition so that
1664 each repetition moves up in the file.
1666 In general, the @samp{list} command expects you to supply zero, one or two
1667 @dfn{linespecs}. Linespecs specify source lines; there are several ways
1668 of writing them but the effect is always to specify some source line.
1669 Here is a complete description of the possible arguments for @samp{list}:
1672 @item list @var{linespec}
1673 Print ten lines centered around the line specified by @var{linespec}.
1675 @item list @var{first},@var{last}
1676 Print lines from @var{first} to @var{last}. Both arguments are
1679 @item list ,@var{last}
1680 Print ten lines ending with @var{last}.
1682 @item list @var{first},
1683 Print ten lines starting with @var{first}.
1686 Print ten lines just after the lines last printed.
1689 Print ten lines just before the lines last printed.
1692 As described in the preceding table.
1695 Here are the ways of specifying a single source line---all the
1700 Specifies line @var{linenum} of the current source file.
1701 When a @samp{list} command has two linespecs, this refers to
1702 the same source file as the first linespec.
1705 Specifies the line @var{offset} lines after the last line printed.
1706 When used as the second linespec in a @samp{list} command that has
1707 two, this specifies the line @var{offset} lines down from the
1710 @item @minus{}@var{offset}
1711 Specifies the line @var{offset} lines before the last line printed.
1713 @item @var{filename}:@var{linenum}
1714 Specifies line @var{linenum} in the source file @var{filename}.
1716 @item @var{function}
1717 Specifies the line of the open-brace that begins the body of the
1718 function @var{function}.
1720 @item @var{filename}:@var{function}
1721 Specifies the line of the open-brace that begins the body of the
1722 function @var{function} in the file @var{filename}. The file name is
1723 needed with a function name only for disambiguation of identically
1724 named functions in different source files.
1726 @item *@var{address}
1727 Specifies the line containing the program address @var{address}.
1728 @var{address} may be any expression.
1731 One other command is used to map source lines to program addresses.
1734 @item info line @var{linenum}
1736 Print the starting and ending addresses of the compiled code for
1737 source line @var{linenum}.
1740 The default examine address for the @samp{x} command is changed to the
1741 starting address of the line, so that @samp{x/i} is sufficient to
1742 begin examining the machine code (@pxref{Memory}). Also, this address
1743 is saved as the value of the convenience variable @samp{$_}
1744 (@pxref{Convenience Vars}).
1747 @node Search, Source Path, List, Source
1748 @section Searching Source Files
1750 @kindex forward-search
1751 @kindex reverse-search
1753 There are two commands for searching through the current source file for a
1756 The command @samp{forward-search @var{regexp}} checks each line, starting
1757 with the one following the last line listed, for a match for @var{regexp}.
1758 It lists the line that is found. You can abbreviate the command name
1761 The command @samp{reverse-search @var{regexp}} checks each line, starting
1762 with the one before the last line listed and going backward, for a match
1763 for @var{regexp}. It lists the line that is found. You can abbreviate
1764 this command with as little as @samp{rev}.
1766 @node Source Path,, Search, Source
1767 @section Specifying Source Directories
1770 @cindex directories for source files
1771 Executable programs do not record the directories of the source files they
1772 were compiled from, just the names. GDB remembers a list of directories to
1773 search for source files; this is called the @dfn{source path}. Each time
1774 GDB wants a source file, it tries all the directories in the list, in the
1775 order they are present in the list, until it finds a file with the desired
1779 When you start GDB, its source path contains just the current working
1780 directory. To add other directories, use the @samp{directory} command.
1781 @b{Note that the search path for executable files and the working directory
1782 are @i{not} used for finding source files.}
1785 @item directory @var{dirname}
1786 Add directory @var{dirname} to the end of the source path.
1789 Reset the source path to just the current working directory of GDB.
1790 This requires confirmation.
1792 @samp{directory} with no argument can cause source files previously
1793 found by GDB to be found in a different directory. To make this work
1794 correctly, this command also clears out the tables GDB maintains
1795 about the source files it has already found.
1797 @item info directories
1798 @kindex info directories
1799 Print the source path: show which directories it contains.
1802 Because the @samp{directory} command adds to the end of the source path,
1803 it does not affect any file that GDB has already found. If the source
1804 path contains directories that you do not want, and these directories
1805 contain misleading files with names matching your source files, the
1806 way to correct the situation is as follows:
1810 Choose the directory you want at the beginning of the source path.
1811 Use the @samp{cd} command to make that the current working directory.
1814 Use @samp{directory} with no argument to reset the source path to just
1818 Use @samp{directory} with suitable arguments to add any other
1819 directories you want in the source path.
1822 @node Data, Symbols, Source, Top
1823 @chapter Examining Data
1825 @cindex printing data
1826 @cindex examining data
1828 The usual way of examining data in your program is with the @samp{print}
1829 command (abbreviated @samp{p}). It evaluates and prints the value of any
1830 valid expression of the language the program is written in (for now, C).
1838 where @var{exp} is any valid expression, and the value of @var{exp}
1839 is printed in a format appropriate to its data type.
1841 A more low-level way of examining data is with the @samp{x} command.
1842 It examines data in memory at a specified address and prints it in a
1845 GDB supports one command to modify the default format of displayed data:
1849 @kindex set array-max
1850 @samp{set array-max} sets the maximum number of elements of an array which
1851 will be printed. This limit also applies to the display of strings.
1855 * Expressions:: Expressions that can be computed and printed.
1856 * Variables:: Using your program's variables in expressions.
1857 * Assignment:: Setting your program's variables.
1858 * Arrays:: Examining part of memory as an array.
1859 * Formats:: Specifying formats for printing values.
1860 * Memory:: Examining memory explicitly.
1861 * Auto Display:: Printing certain expressions whenever program stops.
1862 * Value History:: Referring to values previously printed.
1863 * Convenience Vars:: Giving names to values for future reference.
1864 * Registers:: Referring to and storing in machine registers.
1867 @node Expressions, Variables, Data, Data
1868 @section Expressions
1871 Many different GDB commands accept an expression and compute its value.
1872 Any kind of constant, variable or operator defined by the programming
1873 language you are using is legal in an expression in GDB. This includes
1874 conditional expressions, function calls, casts and string constants.
1875 It unfortunately does not include symbols defined by preprocessor
1878 Casts are supported in all languages, not just in C, because it is so
1879 useful to cast a number into a pointer so as to examine a structure
1880 at that address in memory.
1882 GDB supports three kinds of operator in addition to those of programming
1887 @samp{@@} is a binary operator for treating parts of memory as arrays.
1888 @xref{Arrays}, for more information.
1891 @samp{::} allows you to specify a variable in terms of the file or
1892 function it is defined in. @xref{Variables}.
1894 @item @{@var{type}@} @var{addr}
1895 Refers to an object of type @var{type} stored at address @var{addr} in
1896 memory. @var{addr} may be any expression whose value is an integer or
1897 pointer (but parentheses are required around nonunary operators, just as in
1898 a cast). This construct is allowed regardless of what kind of data is
1899 officially supposed to reside at @var{addr}.@refill
1902 @node Variables, Arrays, Expressions, Data
1903 @section Program Variables
1905 The most common kind of expression to use is the name of a variable
1908 Variables in expressions are understood in the selected stack frame
1909 (@pxref{Selection}); they must either be global (or static) or be visible
1910 according to the scope rules of the programming language from the point of
1911 execution in that frame. This means that in the function
1926 the variable @code{a} is usable whenever the program is executing
1927 within the function @code{foo}, but the variable @code{b} is visible
1928 only while the program is executing inside the block in which @code{b}
1931 As a special exception, you can refer to a variable or function whose
1932 scope is a single source file even if the current execution point is not
1933 in this file. But it is possible to have more than one such variable
1934 or function with the same name (if they are in different source files).
1935 In such a case, it is not defined which one you will get. If you wish,
1936 you can specify any one of them using the colon-colon construct:
1939 @var{block}::@var{variable}
1943 Here @var{block} is the name of the source file whose variable you want.
1945 @node Arrays, Formats, Variables, Data
1946 @section Artificial Arrays
1948 @cindex artificial array
1949 It is often useful to print out several successive objects of the
1950 same type in memory; a section of an array, or an array of
1951 dynamically determined size for which only a pointer exists in the
1954 This can be done by constructing an @dfn{artificial array} with the
1955 binary operator @samp{@@}. The left operand of @samp{@@} should be
1956 the first element of the desired array, as an individual object.
1957 The right operand should be the length of the array. The result is
1958 an array value whose elements are all of the type of the left argument.
1959 The first element is actually the left argument; the second element
1960 comes from bytes of memory immediately following those that hold the
1961 first element, and so on. Here is an example. If a program says
1964 int *array = (int *) malloc (len * sizeof (int));
1968 you can print the contents of @code{array} with
1974 The left operand of @samp{@@} must reside in memory. Array values made
1975 with @samp{@@} in this way behave just like other arrays in terms of
1976 subscripting, and are coerced to pointers when used in expressions.
1977 (It would probably appear in an expression via the value history,
1978 after you had printed it out.)
1980 @node Formats, Memory, Arrays, Data
1983 @cindex formatted output
1984 @cindex output formats
1985 GDB normally prints all values according to their data types. Sometimes
1986 this is not what you want. For example, you might want to print a number
1987 in hex, or a pointer in decimal. Or you might want to view data in memory
1988 at a certain address as a character string or an instruction. These things
1989 can be done with @dfn{output formats}.
1991 The simplest use of output formats is to say how to print a value
1992 already computed. This is done by starting the arguments of the
1993 @samp{print} command with a slash and a format letter. The format
1994 letters supported are:
1998 Regard the bits of the value as an integer, and print the integer in
2002 Print as integer in signed decimal.
2005 Print as integer in unsigned decimal.
2008 Print as integer in octal.
2011 Print as an address, both absolute in hex and then relative
2012 to a symbol defined as an address below it.
2015 Regard as an integer and print it as a character constant.
2018 Regard the bits of the value as a floating point number and print
2019 using typical floating point syntax.
2022 For example, to print the program counter in hex (@pxref{Registers}), type
2029 Note that no space is required before the slash; this is because command
2030 names in GDB cannot contain a slash.
2032 To reprint the last value in the value history with a different format,
2033 you can use the @samp{print} command with just a format and no
2034 expression. For example, @samp{p/x} reprints the last value in hex.
2036 @node Memory, Auto Display, Formats, Data
2037 @subsection Examining Memory
2039 @cindex examining memory
2041 The command @samp{x} (for `examine') can be used to examine memory under
2042 explicit control of formats, without reference to the program's data types.
2044 @samp{x} is followed by a slash and an output format specification,
2045 followed by an expression for an address. The expression need not have
2046 a pointer value (though it may); it is used as an integer, as the
2047 address of a byte of memory. @xref{Expressions} for more information
2050 The output format in this case specifies both how big a unit of memory
2051 to examine and how to print the contents of that unit. It is done
2052 with one or two of the following letters:
2054 These letters specify just the size of unit to examine:
2058 Examine individual bytes.
2061 Examine halfwords (two bytes each).
2064 Examine words (four bytes each).
2067 Many assemblers and cpu designers still use `word' for a 16-bit quantity,
2068 as a holdover from specific predecessor machines of the 1970's that really
2069 did use two-byte words. But more generally the term `word' has always
2070 referred to the size of quantity that a machine normally operates on and
2071 stores in its registers. This is 32 bits for all the machines that GNU
2075 Examine giant words (8 bytes).
2078 These letters specify just the way to print the contents:
2082 Print as integers in unsigned hexadecimal.
2085 Print as integers in signed decimal.
2088 Print as integers in unsigned decimal.
2091 Print as integers in unsigned octal.
2094 Print as an address, both absolute in hex and then relative
2095 to a symbol defined as an address below it.
2098 Print as character constants.
2101 Print as floating point. This works only with sizes @samp{w} and
2105 Print a null-terminated string of characters. The specified unit size
2106 is ignored; instead, the unit is however many bytes it takes to reach
2107 a null character (including the null character).
2110 Print a machine instruction in assembler syntax (or nearly). The
2111 specified unit size is ignored; the number of bytes in an instruction
2112 varies depending on the type of machine, the opcode and the addressing
2116 If either the manner of printing or the size of unit fails to be specified,
2117 the default is to use the same one that was used last. If you don't want
2118 to use any letters after the slash, you can omit the slash as well.
2120 You can also omit the address to examine. Then the address used is
2121 just after the last unit examined. This is why string and instruction
2122 formats actually compute a unit-size based on the data: so that the
2123 next string or instruction examined will start in the right place.
2124 The @samp{print} command sometimes sets the default address for
2125 the @samp{x} command; when the value printed resides in memory, the
2126 default is set to examine the same location. @samp{info line} also
2127 sets the default for @samp{x}, to the address of the start of the
2128 machine code for the specified line and @samp{info breakpoints} sets
2129 it to the address of the last breakpoint listed.
2131 When you use @key{RET} to repeat an @samp{x} command, it does not repeat
2132 exactly the same: the address specified previously (if any) is ignored, so
2133 that the repeated command examines the successive locations in memory
2134 rather than the same ones.
2136 You can examine several consecutive units of memory with one command by
2137 writing a repeat-count after the slash (before the format letters, if any).
2138 The repeat count must be a decimal integer. It has the same effect as
2139 repeating the @samp{x} command that many times except that the output may
2140 be more compact with several units per line.
2147 Prints ten instructions starting with the one to be executed next in the
2148 selected frame. After doing this, you could print another ten following
2156 in which the format and address are allowed to default.
2160 The addresses and contents printed by the @samp{x} command are not put in
2161 the value history because there is often too much of them and they would
2162 get in the way. Instead, GDB makes these values available for subsequent
2163 use in expressions as values of the convenience variables @samp{$_} and
2166 After an @samp{x} command, the last address examined is available for use
2167 in expressions in the convenience variable @samp{$_}. The contents of that
2168 address, as examined, are available in the convenience variable @samp{$__}.
2170 If the @samp{x} command has a repeat count, the address and contents saved
2171 are from the last memory unit printed; this is not the same as the last
2172 address printed if several units were printed on the last line of output.
2174 @node Auto Display, Value History, Memory, Data
2175 @section Automatic Display
2177 If you find that you want to print the value of an expression frequently
2178 (to see how it changes), you might want to add it to the @dfn{automatic
2179 display list} so that GDB will print its value each time the program stops.
2180 Each expression added to the list is given a number to identify it;
2181 to remove an expression from the list, you specify that number.
2182 The automatic display looks like this:
2186 3: bar[5] = (struct hack *) 0x3804
2190 showing item numbers, expressions and their current values.
2193 @item display @var{exp}
2195 Add the expression @var{exp} to the list of expressions to display
2196 each time the program stops. @xref{Expressions}.
2198 @item display/@var{fmt} @var{exp}
2199 For @var{fmt} specifying only a display format and not a size or
2200 count, add the expression @var{exp} to the auto-display list but
2201 arranges to display it each time in the specified format @var{fmt}.
2203 @item display/@var{fmt} @var{addr}
2204 For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
2205 number of units, add the expression @var{addr} as a memory address to
2206 be examined each time the program stops. Examining means in effect
2207 doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
2209 @item undisplay @var{dnums}@dots{}
2211 @item delete display @var{dnums}@dots{}
2212 @kindex delete display
2213 Remove item numbers @var{dnums} from the list of expressions to display.
2215 @item disable display @var{dnums}@dots{}
2216 @kindex disable display
2217 Disable the display of item numbers @var{dnums}. A disabled display item
2218 has no effect but is not forgotten. It may be later enabled.
2220 @item enable display @var{dnums}@dots{}
2221 @kindex enable display
2222 Enable display of item numbers @var{dnums}. It becomes effective once
2223 again in auto display of its expression, until you specify otherwise.
2226 Display the current values of the expressions on the list, just as is
2227 done when the program stops.
2230 @kindex info display
2231 Print the list of expressions to display automatically, each one
2232 with its item number, but without showing the values.
2235 @node Value History, Convenience Vars, Auto Display, Data
2236 @section Value History
2238 @cindex value history
2239 Every value printed by the @samp{print} command is saved for the entire
2240 session in GDB's @dfn{value history} so that you can refer to it in
2245 The values printed are given @dfn{history numbers} for you to refer to them
2246 by. These are successive integers starting with 1. @samp{print} shows you
2247 the history number assigned to a value by printing @samp{$@var{n} = }
2248 before the value; here @var{n} is the history number.
2250 To refer to any previous value, use @samp{$} followed by the value's
2251 history number. The output printed by @samp{print} is designed to remind
2252 you of this. Just @samp{$} refers to the most recent value in the history,
2253 and @samp{$$} refers to the value before that.
2255 For example, suppose you have just printed a pointer to a structure and
2256 want to see the contents of the structure. It suffices to type
2262 If you have a chain of structures where the component @samp{next} points
2263 to the next one, you can print the contents of the next one with
2269 It might be useful to repeat this command many times by typing @key{RET}.
2271 Note that the history records values, not expressions. If the value of
2272 @code{x} is 4 and you type
2280 then the value recorded in the value history by the @samp{print} command
2281 remains 4 even though @code{x}'s value has changed.
2285 @kindex info history
2286 Print the last ten values in the value history, with their item
2287 numbers. This is like @samp{p $$9} repeated ten times, except that
2288 @samp{info history} does not change the history.
2290 @item info history @var{n}
2291 Print ten history values centered on history item number @var{n}.
2294 @node Convenience Vars, Registers, Value History, Data
2295 @section Convenience Variables
2297 @cindex convenience variables
2298 GDB provides @dfn{convenience variables} that you can use within GDB to
2299 hold on to a value and refer to it later. These variables exist entirely
2300 within GDB; they are not part of your program, and setting a convenience
2301 variable has no effect on further execution of your program. That's why
2302 you can use them freely.
2304 Convenience variables have names starting with @samp{$}. Any name starting
2305 with @samp{$} can be used for a convenience variable, unless it is one of
2306 the predefined set of register names (@pxref{Registers}).
2308 You can save a value in a convenience variable with an assignment
2309 expression, just as you would set a variable in your program. Example:
2312 set $foo = *object_ptr
2316 would save in @samp{$foo} the value contained in the object pointed to by
2319 Using a convenience variable for the first time creates it; but its value
2320 is @code{void} until you assign a new value. You can alter the value with
2321 another assignment at any time.
2323 Convenience variables have no fixed types. You can assign a convenience
2324 variable any type of value, even if it already has a value of a different
2325 type. The convenience variable as an expression has whatever type its
2329 @item info convenience
2330 @kindex info convenience
2331 Print a list of convenience variables used so far, and their values.
2332 Abbreviated @samp{i con}.
2335 One of the ways to use a convenience variable is as a counter to be
2336 incremented or a pointer to be advanced. For example:
2340 print bar[$i++]->contents
2341 @i{@dots{}repeat that command by typing @key{RET}.}
2344 Some convenience variables are created automatically by GDB and given
2345 values likely to be useful.
2349 The variable @samp{$_} is automatically set by the @samp{x} command to
2350 the last address examined (@pxref{Memory}). Other commands which
2351 provide a default address for @samp{x} to examine also set @samp{$_}
2352 to that address; these commands include @samp{info line} and @samp{info
2356 The variable @samp{$__} is automatically set by the @samp{x} command
2357 to the value found in the last address examined.
2360 @node Registers,, Convenience Vars, Data
2364 Machine register contents can be referred to in expressions as variables
2365 with names starting with @samp{$}. The names of registers are different
2366 for each machine; use @samp{info registers} to see the names used on your
2367 machine. The names @samp{$pc} and @samp{$sp} are used on all machines for
2368 the program counter register and the stack pointer. Often @samp{$fp} is
2369 used for a register that contains a pointer to the current stack frame.
2371 GDB always considers the contents of an ordinary register as an integer
2372 when the register is examined in this way. Some machines have special
2373 registers which can hold nothing but floating point; these registers are
2374 considered floating point. There is no way to refer to the contents of an
2375 ordinary register as floating point value (although you can @emph{print}
2376 it as a floating point value with @samp{print/f $@var{regname}}).
2378 Some registers have distinct ``raw'' and ``virtual'' data formats. This
2379 means that the data format in which the register contents are saved by the
2380 operating system is not the same one that your program normally sees. For
2381 example, the registers of the 68881 floating point coprocessor are always
2382 saved in ``extended'' format, but virtually all C programs expect to work with
2383 ``double'' format. In such cases, GDB normally works with the virtual
2384 format only (the format that makes sense for your program), but the
2385 @samp{info registers} command prints the data in both formats.
2387 Register values are relative to the selected stack frame
2388 (@pxref{Selection}). This means that you get the value that the register
2389 would contain if all stack frames farther in were exited and their saved
2390 registers restored. In order to see the real contents of all registers,
2391 you must select the innermost frame (with @samp{frame 0}).
2393 Some registers are never saved (typically those numbered zero or one)
2394 because they are used for returning function values; for these registers,
2395 relativization makes no difference.
2398 @item info registers
2399 @kindex info registers
2400 Print the names and relativized values of all registers.
2402 @item info registers @var{regname}
2403 Print the relativized value of register @var{regname}. @var{regname}
2404 may be any register name valid on the machine you are using, with
2405 or without the initial @samp{$}.
2408 @subsection Examples
2410 You could print the program counter in hex with
2417 or print the instruction to be executed next with
2424 or add four to the stack pointer with
2431 The last is a way of removing one word from the stack, on machines where
2432 stacks grow downward in memory (most machines, nowadays). This assumes
2433 that the innermost stack frame is selected. Setting @samp{$sp} is
2434 not allowed when other stack frames are selected.
2436 @node Symbols, Altering, Data, Top
2437 @chapter Examining the Symbol Table
2439 The commands described in this section allow you to make inquiries for
2440 information about the symbols (names of variables, functions and types)
2441 defined in your program. This information is found by GDB in the symbol
2442 table loaded by the @samp{symbol-file} command; it is inherent in the text
2443 of your program and does not change as the program executes.
2446 @item whatis @var{exp}
2448 Print the data type of expression @var{exp}. @var{exp} is not
2449 actually evaluated, and any side-effecting operations (such as
2450 assignments or function calls) inside it do not take place.
2454 Print the data type of @samp{$}, the last value in the value history.
2456 @item info address @var{symbol}
2457 @kindex info address
2458 Describe where the data for @var{symbol} is stored. For register
2459 variables, this says which register. For other automatic variables,
2460 this prints the stack-frame offset at which the variable is always
2461 stored. Note the contrast with @samp{print &@var{symbol}}, which does
2462 not work at all for register variables and for automatic variables
2463 prints the exact address of the current instantiation of the variable.
2465 @item ptype @var{typename}
2467 Print a description of data type @var{typename}. @var{typename} may be
2468 the name of a type, or for C code it may have the form
2469 @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
2470 @samp{enum @var{enum-tag}}.@refill
2473 @kindex info sources
2474 Print the names of all source files in the program for which there
2475 is debugging information.
2477 @item info functions
2478 @kindex info functions
2479 Print the names and data types of all defined functions.
2481 @item info functions @var{regexp}
2482 Print the names and data types of all defined functions
2483 whose names contain a match for regular expression @var{regexp}.
2484 Thus, @samp{info fun step} finds all functions whose names
2485 include @samp{step}; @samp{info fun ^step} finds those whose names
2486 start with @samp{step}.
2488 @item info variables
2489 @kindex info variables
2490 Print the names and data types of all variables that are declared
2491 outside of functions.
2493 @item info variables @var{regexp}
2494 Print the names and data types of all variables, declared outside of
2495 functions, whose names contain a match for regular expression
2500 Print all data types that are defined in the program.
2502 @item info types @var{regexp}
2503 Print all data types that are defined in the program whose names
2504 contain a match for regular expression @var{regexp}.
2507 @item info methods @var{regexp}
2508 @kindex info methods
2509 The @samp{info-methods} command permits the user to examine all defined
2510 methods within C@code{++} program, or (with the @var{regexp} argument) a
2511 specific set of methods found in the various C@code{++} classes. Many
2512 C@code{++} classes which implement a large number of differently typed
2513 methods implement a large number of methods as well. Thus, the
2514 @samp{ptype} command can give the user a tremendous overdose of
2515 information about what methods are associated with a given class. The
2516 @samp{info-methods} command filters these methods do to only those
2517 methods which match the regular-expression search key.
2519 @item printsyms @var{filename}
2521 Write a complete dump of the debugger's symbol data into the
2522 file @var{filename}.
2525 @node Altering, Sequences, Symbols, Top
2526 @chapter Altering Execution
2528 There are several ways to alter the execution of your program with GDB
2532 * Assignment:: Altering variable values or memory contents.
2533 * Jumping:: Altering control flow.
2534 * Signaling:: Making signals happen in the program.
2535 * Returning:: Making a function return prematurely.
2538 @node Assignment, Jumping, Altering, Altering
2539 @section Assignment to Variables
2542 @cindex setting variables
2543 To alter the value of a variable, evaluate an assignment expression.
2544 @xref{Expressions}. For example,
2551 would store the value 4 into the variable @code{x}, and then print
2552 the value of the assignment expression (which is 4).
2555 @kindex set variable
2556 If you are not interested in seeing the value of the assignment, use the
2557 @samp{set} command instead of the @samp{print} command. @samp{set} is
2558 really the same as @samp{print} except that the expression's value is not
2559 printed and is not put in the value history (@pxref{Value History}). The
2560 expression is evaluated only for side effects.
2562 Note that if the beginning of the argument string of the @samp{set} command
2563 appears identical to a @samp{set} subcommand, it may be necessary to use
2564 the @samp{set variable} command. This command is identical to @samp{set}
2565 except for its lack of subcommands.
2567 GDB allows more implicit conversions in assignments than C does; you can
2568 freely store an integer value into a pointer variable or vice versa, and
2569 any structure can be converted to any other structure that is the same
2572 In C, all the other assignment operators such as @samp{+=} and @samp{++}
2573 are supported as well.
2575 To store into arbitrary places in memory, use the @samp{@{@dots{}@}}
2576 construct to generate a value of specified type at a specified address
2577 (@pxref{Expressions}). For example,
2580 set @{int@}0x83040 = 4
2583 @node Jumping, Signaling, Assignment, Altering
2584 @section Continuing at a Different Address
2587 @item jump @var{linenum}
2589 Resume execution at line number @var{linenum}. Execution may stop
2590 immediately if there is a breakpoint there.
2592 The @samp{jump} command does not change the current stack frame, or
2593 the stack pointer, or the contents of any memory location or any
2594 register other than the program counter. If line @var{linenum} is in
2595 a different function from the one currently executing, the results may
2596 be wild if the two functions expect different patterns of arguments or
2597 of local variables. For this reason, the @samp{jump} command requests
2598 confirmation if the specified line is not in the function currently
2599 executing. However, even wild results are predictable based on
2600 changing the program counter.
2602 @item jump *@var{address}
2603 Resume execution at the instruction at address @var{address}.
2606 A similar effect can be obtained by storing a new value into the register
2607 @samp{$pc}, but not exactly the same.
2614 specifies the address at which execution will resume, but does not resume
2615 execution. That does not happen until you use the @samp{cont} command or a
2616 stepping command (@pxref{Stepping}).
2618 @node Signaling, Returning, Jumping, Altering
2619 @section Giving the Program a Signal
2622 @item signal @var{signalnum}
2624 Resume execution where the program stopped, but give it immediately
2625 the signal number @var{signalnum}.
2627 Alternatively, if @var{signalnum} is zero, continue execution and give
2628 no signal. This is useful when the program has received a signal
2629 but you don't want the program to see that signal; the @samp{cont} command
2630 would signal the program.
2633 @node Returning,, Signaling, Altering
2634 @section Returning from a Function
2636 @cindex returning from a function
2638 You can make any function call return immediately, using the @samp{return}
2641 First select the stack frame that you wish to return from
2642 (@pxref{Selection}). Then type the @samp{return} command. If you wish to
2643 specify the value to be returned, give that as an argument.
2645 This pops the selected stack frame (and any other frames inside of it),
2646 leaving its caller as the innermost remaining frame. That frame becomes
2647 selected. The specified value is stored in the registers used for
2648 returning values of functions.
2650 The @samp{return} command does not resume execution; it leaves the program
2651 stopped in the state that would exist if the function had just returned.
2652 Contrast this with the @samp{finish} command (@pxref{Stepping}), which
2653 resumes execution @i{until} the selected stack frame returns naturally.
2655 @node Sequences, Emacs, Altering, Top
2656 @chapter Canned Sequences of Commands
2658 GDB provides two ways to store sequences of commands for execution as a
2659 unit: user-defined commands and command files.
2662 * Define:: User-defined commands.
2663 * Command Files:: Command files.
2664 * Output:: Controlled output commands useful in
2665 user-defined commands and command files.
2668 @node Define, Command Files, Sequences, Sequences
2669 @section User-Defined Commands
2671 @cindex user-defined commands
2672 A @dfn{user-defined command} is a sequence of GDB commands to which you
2673 assign a new name as a command. This is done with the @samp{define}
2677 @item define @var{commandname}
2679 Define a command named @var{commandname}. If there is already a command
2680 by that name, you are asked to confirm that you want to redefine it.
2682 The definition of the command is made up of other GDB command lines,
2683 which are given following the @samp{define} command. The end of these
2684 commands is marked by a line containing @samp{end}.
2686 @item document @var{commandname}
2688 Give documentation to the user-defined command @var{commandname}. The
2689 command @var{commandname} must already be defined. This command reads
2690 lines of documentation just as @samp{define} reads the lines of the
2691 command definition, ending with @samp{end}. After the @samp{document} command is finished,
2692 @samp{help} on command @var{commandname} will print the documentation
2695 You may use the @samp{document} command again to change the
2696 documentation of a command. Redefining the command with @samp{define}
2697 does not change the documentation.
2700 User-defined commands do not take arguments. When they are executed, the
2701 commands of the definition are not printed. An error in any command
2702 stops execution of the user-defined command.
2704 Commands that would ask for confirmation if used interactively proceed
2705 without asking when used inside a user-defined command. Many GDB commands
2706 that normally print messages to say what they are doing omit the messages
2707 when used in user-defined command.
2709 @node Command Files, Output, Define, Sequences
2710 @section Command Files
2712 @cindex command files
2713 A command file for GDB is a file of lines that are GDB commands. Comments
2714 (lines starting with @samp{#}) may also be included. An empty line in a
2715 command file does nothing; it does not mean to repeat the last command, as
2716 it would from the terminal.
2720 When GDB starts, it automatically executes its @dfn{init files}, command
2721 files named @file{.gdbinit}. GDB reads the init file (if any) in your home
2722 directory and then the init file (if any) in the current working
2723 directory. (The init files are not executed if the @samp{-nx} option
2724 is given.) You can also request the execution of a command file with the
2725 @samp{source} command:
2728 @item source @var{filename}
2730 Execute the command file @var{filename}.
2733 The lines in a command file are executed sequentially. They are not
2734 printed as they are executed. An error in any command terminates execution
2735 of the command file.
2737 Commands that would ask for confirmation if used interactively proceed
2738 without asking when used in a command file. Many GDB commands that
2739 normally print messages to say what they are doing omit the messages
2740 when used in a command file.
2742 @node Output,, Command Files, Sequences
2743 @section Commands for Controlled Output
2745 During the execution of a command file or a user-defined command, the only
2746 output that appears is what is explicitly printed by the commands of the
2747 definition. This section describes three commands useful for generating
2748 exactly the output you want.
2751 @item echo @var{text}
2753 Print @var{text}. Nonprinting characters can be included in
2754 @var{text} using C escape sequences, such as @samp{\n} to print a
2755 newline. @b{No newline will be printed unless you specify one.}
2757 A backslash at the end of @var{text} is ignored. It is useful for
2758 outputting a string ending in spaces, since trailing spaces are
2759 trimmed from all arguments. A backslash at the beginning preserves
2760 leading spaces in the same way, because @samp{\ } as an escape
2761 sequence stands for a space. Thus, to print @samp{ and foo = }, do
2767 @item output @var{expression}
2769 Print the value of @var{expression} and nothing but that value: no
2770 newlines, no @samp{$@var{nn} = }. The value is not entered in the
2771 value history either. @xref{Expressions} for more information
2774 @item output/@var{fmt} @var{expression}
2775 Print the value of @var{expression} in format @var{fmt}.
2776 @xref{Formats}, for more information.
2778 @item printf @var{string}, @var{expressions}@dots{}
2780 Print the values of the @var{expressions} under the control of
2781 @var{string}. The @var{expressions} are separated by commas and may
2782 be either numbers or pointers. Their values are printed as specified
2783 by @var{string}, exactly as if the program were to execute
2786 printf (@var{string}, @var{expressions}@dots{});
2789 For example, you can print two values in hex like this:
2792 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
2795 The only backslash-escape sequences that you can use in the string are
2796 the simple ones that consist of backslash followed by a letter.
2799 @node Emacs, Remote, Sequences, Top
2800 @chapter Using GDB under GNU Emacs
2802 A special interface allows you to use GNU Emacs to view (and
2803 edit) the source files for the program you are debugging with
2806 To use this interface, use the command @kbd{M-x gdb} in Emacs.
2807 Give the executable file you want to debug as an argument. This
2808 command starts a GDB process as a subprocess of Emacs, with input
2809 and output through a newly created Emacs buffer.
2811 Using this GDB process is just like using GDB normally except for two things:
2815 All ``terminal'' input and output goes through the Emacs buffer. This
2816 applies both to GDB commands and their output, and to the input and
2817 output done by the program you are debugging.
2819 This is useful because it means that you can copy the text of previous
2820 commands and input them again; you can even use parts of the output
2823 All the facilities of Emacs's Shell mode are available for this purpose.
2826 GDB displays source code through Emacs. Each time GDB displays a
2827 stack frame, Emacs automatically finds the source file for that frame
2828 and puts an arrow (@samp{=>}) at the left margin of the current line.
2830 Explicit GDB @samp{list} or search commands still produce output as
2831 usual, but you probably will have no reason to use them.
2834 In the GDB I/O buffer, you can use these special Emacs commands:
2838 Execute to another source line, like the GDB @samp{step} command.
2841 Execute to next source line in this function, skipping all function
2842 calls, like the GDB @samp{next} command.
2845 Execute one instruction, like the GDB @samp{stepi} command.
2848 Move up one stack frame (and display that frame's source file in
2849 Emacs), like the GDB @samp{up} command.
2852 Move down one stack frame (and display that frame's source file in
2853 Emacs), like the GDB @samp{down} command. (This means that you cannot
2854 delete words in the usual fashion in the GDB buffer; I am guessing you
2855 won't often want to do that.)
2858 Execute until exit from the selected stack frame, like the GDB
2859 @samp{finish} command.
2862 In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
2863 tells GDB to set a breakpoint on the source line point is on.
2865 The source files displayed in Emacs are in ordinary Emacs buffers
2866 which are visiting the source files in the usual way. You can edit
2867 the files with these buffers if you wish; but keep in mind that GDB
2868 communicates with Emacs in terms of line numbers. If you add or
2869 delete lines from the text, the line numbers that GDB knows will cease
2870 to correspond properly to the code.
2872 @node Remote, Commands, Emacs, Top
2873 @chapter Remote Kernel Debugging
2875 GDB has a special facility for debugging a remote machine via a serial
2876 connection. This can be used for kernel debugging.
2878 The program to be debugged on the remote machine needs to contain a
2879 debugging device driver which talks to GDB over the serial line using the
2880 protocol described below. The same version of GDB that is used ordinarily
2881 can be used for this.
2884 * Remote Commands:: Commands used to start and finish remote debugging.
2887 For details of the communication protocol, see the comments in the GDB
2888 source file @file{remote.c}.
2890 @node Remote Commands,, Remote, Remote
2891 @section Commands for Remote Debugging
2893 To start remote debugging, first run GDB and specify as an executable file
2894 the program that is running in the remote machine. This tells GDB how
2895 to find the program's symbols and the contents of its pure text. Then
2896 establish communication using the @samp{attach} command with a device
2897 name rather than a pid as an argument. For example:
2904 if the serial line is connected to the device named @file{/dev/ttyd}. This
2905 will stop the remote machine if it is not already stopped.
2907 Now you can use all the usual commands to examine and change data and to
2908 step and continue the remote program.
2910 To resume the remote program and stop debugging it, use the @samp{detach}
2913 @node Commands, Concepts, Remote, Top
2914 @unnumbered Command Index
2918 @node Concepts,, Commands, Top
2919 @unnumbered Concept Index