9 date 89.02.10.01.41.38; author gnu; state Exp;
14 date 89.02.10.00.33.03; author gnu; state Exp;
25 @Improve doc in various ways, mostly xref{Expressions} so you can
26 find out what an expression is (I had trouble finding it, since
27 it's in a nested menu somewhere.)
31 @@setfilename ../info/gdb
32 @@settitle GDB, The GNU Debugger
34 This file documents the GNU debugger GDB.
36 Copyright (C) 1988 Free Software Foundation, Inc.
38 Permission is granted to make and distribute verbatim copies of
39 this manual provided the copyright notice and this permission notice
40 are preserved on all copies.
43 Permission is granted to process this file through Tex and print the
44 results, provided the printed document carries copying permission
45 notice identical to this one except for the removal of this paragraph
46 (this paragraph not being relevant to the printed manual).
49 Permission is granted to copy and distribute modified versions of this
50 manual under the conditions for verbatim copying, provided also that the
51 sections entitled ``Distribution'' and ``GDB General Public License'' are
52 included exactly as in the original, and provided that the entire resulting
53 derived work is distributed under the terms of a permission notice
54 identical to this one.
56 Permission is granted to copy and distribute translations of this manual
57 into another language, under the above conditions for modified versions,
58 except that the sections entitled ``Distribution'' and ``GDB General Public
59 License'' may be included in a translation approved by the author instead
60 of in the original English.
63 @@setchapternewpage odd
67 @@center @@titlefont{GDB Manual}
69 @@center The GNU Source-Level Debugger
71 @@center Third Edition, GDB version 3.1
75 @@center Richard M. Stallman
77 @@vskip 0pt plus 1filll
78 Copyright @@copyright{} 1988, 1989 Free Software Foundation, Inc.
80 Permission is granted to make and distribute verbatim copies of
81 this manual provided the copyright notice and this permission notice
82 are preserved on all copies.
84 Permission is granted to copy and distribute modified versions of this
85 manual under the conditions for verbatim copying, provided also that the
86 sections entitled ``Distribution'' and ``GDB General Public License'' are
87 included exactly as in the original, and provided that the entire resulting
88 derived work is distributed under the terms of a permission notice
89 identical to this one.
91 Permission is granted to copy and distribute translations of this manual
92 into another language, under the above conditions for modified versions,
93 except that the sections entitled ``Distribution'' and ``GDB General Public
94 License'' may be included in a translation approved by the author instead
95 of in the original English.
99 @@node Top, Commands,, (DIR)
100 @@unnumbered Summary of GDB
102 The purpose of a debugger such as GDB is to allow you to execute another
103 program while examining what is going on inside it. We call the other
104 program ``your program'' or ``the program being debugged''.
106 GDB can do four kinds of things (plus other things in support of these):
110 Start the program, specifying anything that might affect its behavior.
113 Make the program stop on specified conditions.
116 Examine what has happened, when the program has stopped, so that you
120 Change things in the program, so you can correct the effects of one bug
121 and go on to learn about another without having to recompile first.
124 GDB can be used to debug programs written in C and C++. Pascal support
125 is being implemented, and Fortran support will be added when a GNU
126 Fortran compiler is written.
129 * License:: The GDB General Public License gives you permission
130 to redistribute GDB on certain terms; and also
131 explains that there is no warranty.
132 * Input:: GDB command syntax and input conventions.
133 * Files:: Specifying files for GDB to operate on.
134 * Options:: GDB arguments and options.
135 * Compilation::Compiling your program so you can debug it.
136 * Running:: Running your program under GDB.
137 * Stopping:: Making your program stop. Why it may stop. What to do then.
138 * Stack:: Examining your program's stack.
139 * Source:: Examining your program's source files.
140 * Data:: Examining data in your program.
141 * Symbols:: Examining the debugger's symbol table.
142 * Altering:: Altering things in your program.
143 * Sequences:: Canned command sequences for repeated use.
144 * Emacs:: Using GDB through GNU Emacs.
145 * Remote:: Remote kernel debugging across a serial line.
146 * Commands:: Index of GDB commands.
147 * Concepts:: Index of GDB concepts.
150 @@node License, Input, Top, Top
151 @@unnumbered GDB General Public License
152 @@center (Clarified 11 Feb 1988)
154 The license agreements of most software companies keep you at the mercy
155 of those companies. By contrast, our general public license is intended to
156 give everyone the right to share GDB. To make sure that you get the rights
157 we want you to have, we need to make restrictions that forbid anyone to
158 deny you these rights or to ask you to surrender the rights. Hence this
161 Specifically, we want to make sure that you have the right to give away
162 copies of GDB, that you receive source code or else can get it if you want
163 it, that you can change GDB or use pieces of it in new free programs, and
164 that you know you can do these things.
166 To make sure that everyone has such rights, we have to forbid you to
167 deprive anyone else of these rights. For example, if you distribute copies
168 of GDB, you must give the recipients all the rights that you have. You
169 must make sure that they, too, receive or can get the source code. And you
170 must tell them their rights.
172 Also, for our own protection, we must make certain that everyone finds
173 out that there is no warranty for GDB. If GDB is modified by someone else
174 and passed on, we want its recipients to know that what they have is not
175 what we distributed, so that any problems introduced by others will not
176 reflect on our reputation.
178 Therefore we (Richard Stallman and the Free Software Foundation,
179 Inc.) make the following terms which say what you must do to be
180 allowed to distribute or change GDB.
182 @@unnumberedsec Copying Policies
186 You may copy and distribute verbatim copies of GDB source code as you
187 receive it, in any medium, provided that you conspicuously and
188 appropriately publish on each file a valid copyright notice ``Copyright
189 @@copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
190 is appropriate); keep intact the notices on all files that
191 refer to this License Agreement and to the absence of any warranty; and
192 give any other recipients of the GDB program a copy of this License
193 Agreement along with the program. You may charge a distribution fee
194 for the physical act of transferring a copy.
197 You may modify your copy or copies of GDB source code or any portion
198 of it, and copy and distribute such modifications under the terms of
199 Paragraph 1 above, provided that you also do the following:
203 cause the modified files to carry prominent notices stating
204 that you changed the files and the date of any change; and
207 cause the whole of any work that you distribute or publish, that
208 in whole or in part contains or is a derivative of GDB or any
209 part thereof, to be licensed at no charge to all third parties on
210 terms identical to those contained in this License Agreement
211 (except that you may choose to grant more extensive warranty
212 protection to some or all third parties, at your option).
215 if the modified program serves as a debugger, cause it, when
216 started running in the simplest and usual way, to print an
217 announcement including a valid copyright notice ``Copyright
218 @@copyright{} 1988 Free Software Foundation, Inc.'' (or with the
219 year that is appropriate), saying that there is no warranty (or
220 else, saying that you provide a warranty) and that users may
221 redistribute the program under these conditions, and telling the
222 user how to view a copy of this License Agreement.
225 You may charge a distribution fee for the physical act of
226 transferring a copy, and you may at your option offer warranty
227 protection in exchange for a fee.
230 Mere aggregation of another unrelated program with this program (or its
231 derivative) on a volume of a storage or distribution medium does not bring
232 the other program under the scope of these terms.
235 You may copy and distribute GDB (or a portion or derivative of it,
236 under Paragraph 2) in object code or executable form under the terms
237 of Paragraphs 1 and 2 above provided that you also do one of the
242 accompany it with the complete corresponding machine-readable
243 source code, which must be distributed under the terms of
244 Paragraphs 1 and 2 above; or,
247 accompany it with a written offer, valid for at least three
248 years, to give any third party free (except for a nominal
249 shipping charge) a complete machine-readable copy of the
250 corresponding source code, to be distributed under the terms of
251 Paragraphs 1 and 2 above; or,
254 accompany it with the information you received as to where the
255 corresponding source code may be obtained. (This alternative is
256 allowed only for noncommercial distribution and only if you
257 received the program in object code or executable form alone.)
260 For an executable file, complete source code means all the source code
261 for all modules it contains; but, as a special exception, it need not
262 include source code for modules which are standard libraries that
263 accompany the operating system on which the executable file runs.
266 You may not copy, sublicense, distribute or transfer GDB except as
267 expressly provided under this License Agreement. Any attempt
268 otherwise to copy, sublicense, distribute or transfer GDB is void and
269 your rights to use GDB under this License agreement shall be
270 automatically terminated. However, parties who have received computer
271 software programs from you with this License Agreement will not have
272 their licenses terminated so long as such parties remain in full
276 If you wish to incorporate parts of GDB into other free programs whose
277 distribution conditions are different, write to the Free Software
278 Foundation. We have not yet worked out a simple rule that can be
279 stated here, but we will often permit this. We will be guided by the
280 two goals of preserving the free status of all derivatives our free
281 software and of promoting the sharing and reuse of software.
288 @@unnumberedsec NO WARRANTY
290 BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
291 NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
292 WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
293 RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB ``AS IS''
294 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
295 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
296 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
297 AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GDB
298 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
299 SERVICING, REPAIR OR CORRECTION.
301 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
302 FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
303 MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
304 FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
305 SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
306 INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
307 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
308 FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
309 FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
310 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
313 @@node Input, Files, License, Top
314 @@chapter GDB Input Conventions
316 GDB is invoked with the shell command @@samp{gdb}. Once started, it reads
317 commands from the terminal until you tell it to exit.
319 A GDB command is a single line of input. There is no limit on how long
320 it can be. It starts with a command name, which is followed by arguments
321 whose meaning depends on the command name. Some command names do not
324 GDB command names may always be abbreviated if the abbreviation is
325 unambiguous. Sometimes even ambiguous abbreviations are allowed; for
326 example, @@samp{s} is specially defined as equivalent to @@samp{step}
327 even though there are other commands whose names start with @@samp{s}.
328 Possible command abbreviations are often stated in the documentation
329 of the individual commands.
331 A blank line as input to GDB means to repeat the previous command verbatim.
332 Certain commands do not allow themselves to be repeated this way; these are
333 commands for which unintentional repetition might cause trouble and which
334 you are unlikely to want to repeat. Certain others (@@samp{list} and
335 @@samp{x}) act differently when repeated because that is more useful.
337 A line of input starting with @@samp{#} is a comment; it does nothing.
338 This is useful mainly in command files (@@xref{Command Files}).
340 Occasionally it is useful to execute a shell command from within gdb.
341 This can be done with the @@samp{shell} command, or the shell escape
345 @@item shell @@var{shell command string}
347 @@item !@@var{shell command string}
349 @@cindex shell escape
350 Directs GDB to invoke an inferior shell to execute @@samp{shell command string}.
351 The environmental variable @@samp{SHELL} is used if it exists, otherwise gdb
352 uses @@samp{/bin/sh}.
355 GDB @@dfn{prompts} for commands with a string that is normally @@samp{(gdb)}.
356 When debugging GDB with GDB, it is useful to change the prompt in one of
357 the GDBs so that you can distinguish them. This can be done with the
358 @@samp{set prompt} command.
361 @@item set prompt @@var{newprompt}
363 Directs GDB to use @@var{newprompt} as its prompt string henceforth.
368 To exit GDB, use the @@samp{quit} command (abbreviated @@samp{q}).
369 @@kbd{Ctrl-c} will not exit from GDB, but rather will terminate the action
370 of any GDB command that is in progress and return to GDB command level.
371 It is safe to type @@kbd{Ctrl-c} at any time because GDB does not allow
372 it to take effect until a time when it is safe.
374 @@node Files, Options, Input, Top
375 @@chapter Specifying GDB's Files
377 @@cindex core dump file
378 @@cindex executable file
379 @@cindex symbol table
380 GDB needs to know the filename of the program to be debugged. To debug a
381 core dump of a previous run, GDB must be told the filename of the core
385 * Arguments: File Arguments. Specifying files with arguments
386 (when you start GDB).
387 * Commands: File Commands. Specifying files with GDB commands.
390 @@node File Arguments, File Commands, Files, Files
391 @@section Specifying Files with Arguments
393 The usual way to specify the executable and core dump file names is with
394 two command arguments given when you start GDB. The first argument is used
395 as the file for execution and symbols, and the second argument (if any) is
396 used as the core dump file name. Thus,
403 specifies @@file{progm} as the executable program and @@file{core} as a core
404 dump file to examine. (You do not need to have a core dump file if what
405 you plan to do is debug the program interactively.)
407 @@xref{Options}, for full information on command options and arguments for
410 @@node File Commands,, File Arguments, Files
411 @@section Specifying Files with Commands
413 Usually you specify the files for GDB to work with by giving arguments when
414 you invoke GDB. But occasionally it is necessary to change to a different
415 file during a GDB session. Or you may run GDB and forget to specify the
416 files you want to use. In these situations the GDB commands to specify new
420 @@item exec-file @@var{filename}
422 Specify that the program to be run is found in @@var{filename}. If you
423 do not specify a directory and the file is not found in GDB's working
424 directory, GDB will use the environment variable @@samp{PATH} as a list
425 of directories to search, just as the shell does when looking for a
428 @@item symbol-file @@var{filename}
430 Read symbol table information from file @@var{filename}. @@samp{PATH}
431 is searched when necessary. Most of the time you will use both the
432 @@samp{exec-file} and @@samp{symbol-file} commands on the same file.
434 @@samp{symbol-file} with no argument clears out GDB's symbol table.
436 @@item core-file @@var{filename}
438 Specify the whereabouts of a core dump file to be used as the
439 ``contents of memory''. Note that the core dump contains only the
440 writable parts of memory; the read-only parts must come from the
443 @@samp{core-file} with no argument specifies that no core file is
446 @@item add-file @@var{filename} @@var{address}
448 The @@samp{add-file} command takes two arguments, a file name, and the
449 address at which that file has been (or should be) dynamically loaded.
450 GDB will then treat that file as though it had always been dynamically
451 linked, and provide the user with all the normal GDB features, including
454 With the @@samp{add-file} command, it is possible to debug code which was
455 not present in the initial load image of the program under test.
456 Suppose you have a program which can, while running, dynamically link a
457 program fragment into its address space. One program which does this is
458 KCL, a free common lisp implementation. The fragment will be loaded
459 into the main program's address space at some address, and the main
460 program can then call functions within the fragment by calculating (or
461 otherwise obtaining) their addresses.
465 Cancel running the program under GDB. This could be used if you wish
466 to debug a core dump instead. GDB ignores any core dump file if it is
467 actually running the program, so the @@samp{kill} command is the only
468 sure way to go back to using the core dump file.
472 Print the names of the executable and core dump files currently in
473 use by GDB, and the file from which symbols were loaded.
476 While all three file-specifying commands allow both absolute and relative
477 file names as arguments, GDB always converts the file name to an absolute
478 one and remembers it that way.
480 The @@samp{symbol-file} command causes GDB to forget the contents of its
481 convenience variables, the value history, and all breakpoints and
482 auto-display expressions. This is because they may contain pointers to the
483 internal data recording symbols and data types, which are part of the old
484 symbol table data being discarded inside GDB.
486 @@node Options, Compilation, Files, Top
487 @@chapter Options and Arguments for GDB
489 When you invoke GDB, you can pass commands telling it what files to
490 operate on and what other things to do.
493 * Mode Options:: Options controlling modes of operation.
494 * File Options:: Options to specify files (executable, coredump, commands)
495 * Other Arguments:: Any other arguments without options
499 @@node Mode Options, File Options, Options, Options
500 @@section Mode Options
504 Do not execute commands from the init files @@file{.gdbinit}.
505 Normally, the commands in these files are executed after all the
506 command options and arguments have been processed. @@xref{Command
510 ``Quiet''. Do not print the usual introductory messages.
513 Run in batch mode. Exit with code 1 after processing all the command
514 files specified with @@samp{-x} (and @@file{.gdbinit}, if not
515 inhibited). Exit also if, due to an error, GDB would otherwise
516 attempt to read a command from the terminal.
519 This option is used when Emacs runs GDB as a subprocess. It tells GDB
520 to output the full file name and line number in a standard,
521 recognizable fashion each time a stack frame is displayed (which
522 includes each time the program stops). This recognizable format looks
523 like two @@samp{\032} characters, followed by the filename, line number
524 and character position separated by colons, and a newline. The
525 Emacs-to-GDB interface program uses the two @@samp{\032} characters as
526 a signal to display the source code for the frame.
529 @@node File Options, Other Arguments, Mode Options, Options
530 @@section File-specifying Options
532 All the options and command line arguments given are processed
533 in sequential order. The order makes a difference when the
534 @@samp{-x} command is used.
537 @@item -s @@var{file}
538 Read symbol table from file @@var{file}.
540 @@item -e @@var{file}
541 Use file @@var{file} as the executable file to execute when
542 appropriate, and for examining pure data in conjunction with a core
545 @@item -se @@var{file}
546 Read symbol table from file @@var{file} and use it as the executable
549 @@item -c @@var{file}
550 Use file @@var{file} as a core dump to examine.
552 @@item -x @@var{file}
553 Execute GDB commands from file @@var{file}.
555 @@item -d @@var{directory}
556 Add @@var{directory} to the path to search for source files.
559 @@node Other Arguments,, File Options, Options
560 @@section Other Arguments
562 If there are arguments to GDB that are not options or associated with
563 options, the first one specifies the symbol table and executable file name
564 (as if it were preceded by @@samp{-se}) and the second one specifies a core
565 dump file name (as if it were preceded by @@samp{-c}).
567 @@node Compilation, Running, Options, Top
568 @@chapter Compiling Your Program for Debugging
570 In order to debug a program effectively, you need to ask for debugging
571 information when you compile it. This information in the object file
572 describes the data type of each variable or function and the correspondence
573 between source line numbers and addresses in the executable code.
575 To request debugging information, specify the @@samp{-g} option when you run
578 The Unix C compiler is unable to handle the @@samp{-g} and @@samp{-O} options
579 together. This means that you cannot ask for optimization if you ask for
580 debugger information.
582 The GNU C compiler supports @@samp{-g} with or without @@samp{-O}, making it
583 possible to debug optimized code. We recommend that you @@emph{always} use
584 @@samp{-g} whenever you compile a program. You may think the program is
585 correct, but there's no sense in pushing your luck.
587 If you are using the GNU C compiler, the GNU assembler and the GNU linker,
588 you can choose between two formats of debugging information: the standard
589 Unix format, which is what you get with @@samp{-g}, and GDB's own format,
590 which you request by using @@samp{-gg} instead of @@samp{-g}. This stores
591 debugging information in the executable file in a format much like that
592 which is used inside GDB. This has these advantages and disadvantages:
596 GDB can read @@samp{-gg} format more than twice as fast as Unix
600 The @@samp{-gg} format uses much more disk space than Unix format.
603 The Unix debuggers can understand only Unix format, so you cannot use
604 Unix source-level debuggers if you compile with @@samp{-gg}. (The
605 @@code{adb} debugger works with either format; it does not use this
606 information in any case.)
609 @@node Running, Stopping, Compilation, Top
610 @@chapter Running Your Program Under GDB
614 To start your program under GDB, use the @@samp{run} command. The program
615 must already have been specified using the @@samp{exec-file} command or with
616 an argument to GDB (@@pxref{Files}); what @@samp{run} does is create an
617 inferior process, load the program into it, and set it in motion.
619 The execution of a program is affected by certain information it receives
620 from its superior. GDB provides ways to specify them, which you must do
621 @@i{before} starting the program. (You can change them after starting the
622 program, but such changes do not affect the program unless you start it
626 @@item The @@i{arguments.}
627 You specify the arguments to give the program as the arguments of the
630 @@item The @@i{environment.}
631 The program normally inherits its environment from GDB, but you can
632 use the GDB commands @@samp{set environment} and
633 @@samp{unset environment} to change parts of the environment that will
634 be given to the program.@@refill
636 @@item The @@i{working directory.}
637 The program inherits its working directory from GDB. You can set GDB's
638 working directory with the @@samp{cd} command in GDB.
641 After the @@samp{run} command, the debugger does nothing but wait for your
642 program to stop. @@xref{Stopping}.
644 Note that once your program has been started by the @@samp{run} command,
645 you may evaluate expressions that involve calls to functions in the
646 inferior. @@xref{Expressions}. If you wish to evaluate a function
647 simply for it's side affects, you may use the @@samp{set} command.
651 * Arguments:: Specifying the arguments for your program.
652 * Environment:: Specifying the environment for your program.
653 * Working Directory:: Specifying the working directory for giving
654 to your program when it is run.
655 * Input/Output:: Specifying the program's standard input and output.
656 * Attach:: Debugging a process started outside GDB.
659 @@node Arguments, Environment, Running, Running
660 @@section Your Program's Arguments
662 @@cindex arguments (to your program)
663 You specify the arguments to give the program as the arguments of the
664 @@samp{run} command. They are passed to a shell, which expands wildcard
665 characters and performs redirection of I/O, and thence to the program.
667 @@samp{run} with no arguments uses the same arguments used by the previous
671 The command @@samp{set args} can be used to specify the arguments to be used
672 the next time the program is run. If @@samp{set args} has no arguments, it
673 means to use no arguments the next time the program is run. If you have
674 run your program with arguments and want to run it again with no arguments,
675 this is the only way to do so.
677 @@node Environment, Working Directory, Arguments, Running
678 @@section Your Program's Environment
680 @@cindex environment (of your program)
681 The @@dfn{environment} consists of a set of @@dfn{environment variables} and
682 their values. Environment variables conventionally record such things as
683 your user name, your home directory, your terminal type, and your search
684 path for programs to run. Usually you set up environment variables with
685 the shell and they are inherited by all the other programs you run. When
686 debugging, it can be useful to try running the program with different
687 environments without having to start the debugger over again.
690 @@item info environment @@var{varname}
691 @@kindex info environment
692 Print the value of environment variable @@var{varname} to be given to
693 your program when it is started. This command can be abbreviated
694 @@samp{i env @@var{varname}}.
696 @@item info environment
697 Print the names and values of all environment variables to be given to
698 your program when it is started. This command can be abbreviated
701 @@item set environment @@var{varname} @@var{value}
702 @@item set environment @@var{varname} = @@var{value}
703 @@kindex set environment
704 Sets environment variable @@var{varname} to @@var{value}, for your program
705 only, not for GDB itself. @@var{value} may be any string; the values of
706 environment variables are just strings, and any interpretation is
707 supplied by your program itself. The @@var{value} parameter is optional;
708 if it is eliminated, the variable is set to a null value. This command
709 can be abbreviated as short as @@samp{set e}.
711 @@item delete environment @@var{varname}
712 @@kindex delete environment
713 @@item unset environment @@var{varname}
714 @@kindex unset environment
715 Remove variable @@var{varname} from the environment to be passed to
716 your program. This is different from @@samp{set env @@var{varname} =}
717 because @@samp{delete environment} makes a variable not be defined at
718 all, which is distinguishable from an empty value. This command can
719 be abbreviated @@samp{d e}.
722 @@node Working Directory, Input/Output, Environment, Running
723 @@section Your Program's Working Directory
725 @@cindex working directory (of your program)
726 Each time you start your program with @@samp{run}, it inherits its working
727 directory from the current working directory of GDB. GDB's working
728 directory is initially whatever it inherited from its superior, but you can
729 specify the working directory for GDB with the @@samp{cd} command.
731 The GDB working directory also serves as a default for the commands
732 that specify files for GDB to operate on. @@xref{Files}.
735 @@item cd @@var{directory}
737 Set GDB's working directory to @@var{directory}.
741 Print GDB's working directory.
744 @@node Input/Output, Attach, Working Directory, Running
745 @@section Your Program's Input and Output
748 @@cindex controlling terminal
749 By default, the program you run under GDB does input and output to the same
750 terminal that GDB uses.
752 You can redirect the program's input and/or output using @@samp{sh}-style
753 redirection commands in the @@samp{run} command. For example,
760 starts the program, diverting its output to the file @@file{outfile}.
763 Another way to specify where the program should do input and output is with
764 the @@samp{tty} command. This command accepts a file name as argument, and
765 causes this file to be the default for future @@samp{run} commands. It also
766 resets the controlling terminal for future @@samp{run} commands. For
774 directs that processes started with subsequent @@samp{run} commands default
775 to do input and output on the terminal @@file{/dev/ttyb} and sets the
776 controlling terminal to @@file{/dev/ttyb}. An explicit redirection in
777 @@samp{run} overrides the @@samp{tty} command's effect on input/output
780 When you use the @@samp{tty} command or redirect input in the @@samp{run}
781 command, the @@emph{input for your program} comes from the specified file,
782 but the input for GDB still comes from your terminal.
784 @@node Attach,, Input/Output, Running
785 @@section Debugging an Already-Running Process
790 Some operating systems (in particular, Sun) allow GDB to begin debugging an
791 already-running process that was started outside of GDB. To do this you
792 must use the @@samp{attach} command instead of the @@samp{run} command.
794 The @@samp{attach} command requires one argument, which is the process-id of
795 the process you want to debug. (The usual way to find out the process-id
796 of the process is with the @@samp{ps} utility.)
798 The first thing GDB does after arranging to debug the process is to stop
799 it. You can examine and modify an attached process with all the GDB
800 commands that ordinarily available when you start processes with
801 @@samp{run}. You can insert breakpoints; you can step and continue; you
802 can modify storage. If you would rather the process continue running,
803 use the @@samp{continue} command after attaching.
805 When you are finished debugging the attached process, you can use the
806 @@samp{detach} command to release it from GDB's control. Detaching
807 the process continues its execution. After the @@samp{detach} command,
808 that process and GDB become completely independent once more, and you
809 are ready to @@samp{attach} another process or start one with @@samp{run}.
811 If you exit GDB or use the @@samp{run} command while you have an attached
812 process, you kill that process. You will be asked for confirmation if you
813 try to do either of these things.
815 @@node Stopping, Stack, Running, Top
816 @@chapter Stopping and Continuing
818 When you run a program normally, it runs until exiting. The purpose
819 of using a debugger is so that you can stop it before that point;
820 or so that if the program runs into trouble you can find out why.
823 * Signals:: Fatal signals in your program just stop it;
824 then you can use GDB to see what is going on.
825 * Breakpoints:: Breakpoints let you stop your program when it
826 reaches a specified point in the code.
827 * Continuing:: Resuming execution until the next signal or breakpoint.
828 * Stepping:: Stepping runs the program a short distance and
829 then stops it wherever it has come to.
832 @@node Signals, Breakpoints, Stopping, Stopping
835 A signal is an asynchronous event that can happen in a program. The
836 operating system defines the possible kinds of signals, and gives each kind
837 a name and a number. For example, @@code{SIGINT} is the signal a program
838 gets when you type @@kbd{Ctrl-c}; @@code{SIGSEGV} is the signal a program
839 gets from referencing a place in memory far away from all the areas in use;
840 @@code{SIGALRM} occurs when the alarm clock timer goes off (which happens
841 only if the program has requested an alarm).
843 Some signals, including @@code{SIGALRM}, are a normal part of the
844 functioning of the program. Others, such as @@code{SIGSEGV}, indicate
845 errors; these signals are @@dfn{fatal} (kill the program immediately) if the
846 program has not specified in advance some other way to handle the signal.
847 @@code{SIGINT} does not indicate an error in the program, but it is normally
848 fatal so it can carry out the purpose of @@kbd{Ctrl-c}: to kill the program.
850 GDB has the ability to detect any occurrence of a signal in the program
851 running under GDB's control. You can tell GDB in advance what to do for
854 Normally, GDB is set up to ignore non-erroneous signals like @@code{SIGALRM}
855 (so as not to interfere with their role in the functioning of the program)
856 but to stop the program immediately whenever an error signal happens.
857 You can change these settings with the @@samp{handle} command. You must
858 specify which signal you are talking about with its number.
863 Print a table of all the kinds of signals and how GDB has been told to
864 handle each one. You can use this to see the signal numbers of all
865 the defined types of signals.
867 @@item handle @@var{signalnum} @@var{keywords}@@dots{}
869 Change the way GDB handles signal @@var{signalnum}. The @@var{keywords}
870 say what change to make.
873 To use the @@samp{handle} command you must know the code number of the
874 signal you are concerned with. To find the code number, type @@samp{info
875 signal} which prints a table of signal names and numbers.
877 The keywords allowed by the handle command can be abbreviated. Their full
882 GDB should stop the program when this signal happens. This implies
883 the @@samp{print} keyword as well.
886 GDB should print a message when this signal happens.
889 GDB should not stop the program when this signal happens. It may
890 still print a message telling you that the signal has come in.
893 GDB should not mention the occurrence of the signal at all. This
894 implies the @@samp{nostop} keyword as well.
897 GDB should allow the program to see this signal; the program will be
898 able to handle the signal, or may be terminated if the signal is fatal
902 GDB should not allow the program to see this signal.
905 When a signal has been set to stop the program, the program cannot see the
906 signal until you continue. It will see the signal then, if @@samp{pass} is
907 in effect for the signal in question @@i{at that time}. In other words,
908 after GDB reports a signal, you can use the @@samp{handle} command with
909 @@samp{pass} or @@samp{nopass} to control whether that signal will be seen by
910 the program when you later continue it.
912 You can also use the @@samp{signal} command to prevent the program from
913 seeing a signal, or cause it to see a signal it normally would not see,
914 or to give it any signal at any time. @@xref{Signaling}.
916 @@node Breakpoints, Continuing, Signals, Stopping
917 @@section Breakpoints
920 A @@dfn{breakpoint} makes your program stop whenever a certain point in the
921 program is reached. You set breakpoints explicitly with GDB commands,
922 specifying the place where the program should stop by line number, function
923 name or exact address in the program. You can add various other conditions
924 to control whether the program will stop.
926 Each breakpoint is assigned a number when it is created; these numbers are
927 successive integers starting with 1. In many of the commands for controlling
928 various features of breakpoints you use the breakpoint number to say which
929 breakpoint you want to change. Each breakpoint may be @@dfn{enabled} or
930 @@dfn{disabled}; if disabled, it has no effect on the program until you
935 The command @@samp{info break} prints a list of all breakpoints set and not
936 cleared, showing their numbers, where in the program they are, and any
937 special features in use for them. Disabled breakpoints are included in the
938 list, but marked as disabled. @@samp{info break} with a breakpoint number
939 as argument lists only that breakpoint. The convenience variable @@samp{$_}
940 and the default examining-address for the @@samp{x} command are set to the
941 address of the last breakpoint listed (@@pxref{Memory}).
944 * Set Breaks:: How to establish breakpoints.
945 * Clear Breaks:: How to remove breakpoints no longer needed.
946 * Disabling:: How to disable breakpoints (turn them off temporarily).
947 * Conditions:: Making extra conditions on whether to stop.
948 * Break Commands:: Commands to be executed at a breakpoint.
949 * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
952 @@node Set Breaks, Clear Breaks, Breakpoints, Breakpoints
953 @@subsection Setting Breakpoints
956 Breakpoints are set with the @@samp{break} command (abbreviated @@samp{b}).
957 You have several ways to say where the breakpoint should go.
960 @@item break @@var{function}
961 Set a breakpoint at entry to function @@var{function}.
963 @@item break @@var{linenum}
964 Set a breakpoint at line @@var{linenum} in the current source file.
965 That file is the last file whose source text was printed. This
966 breakpoint will stop the program just before it executes any of the
969 @@item break @@var{filename}:@@var{linenum}
970 Set a breakpoint at line @@var{linenum} in source file @@var{filename}.
972 @@item break @@var{filename}:@@var{function}
973 Set a breakpoint at entry to function @@var{function} found in file
974 @@var{filename}. Specifying a filename as well as a function name is
975 superfluous except when multiple files contain similarly named
978 @@item break *@@var{address}
979 Set a breakpoint at address @@var{address}. You can use this to set
980 breakpoints in parts of the program which do not have debugging
981 information or source files.
984 Set a breakpoint at the next instruction to be executed in the selected
985 stack frame (@@pxref{Stack}). In any selected frame but the innermost,
986 this will cause the program to stop as soon as control returns to that
987 frame. This is equivalent to a @@samp{finish} command in the frame
988 inside the selected frame. If this is done in the innermost frame gdb
989 will stop the next time it reaches the current location; this may be
990 useful inside of loops. It does not stop at this breakpoint immediately
991 upon continuation of the program since no code would be executed if it
994 @@item break @@dots{} if @@var{cond}
995 Set a breakpoint with condition @@var{cond}; evaluate the expression
996 @@var{cond} each time the breakpoint is reached, and stop only if the
997 value is nonzero. @@samp{@@dots{}} stands for one of the possible
998 arguments described above (or no argument) specifying where to break.
999 @@xref{Conditions}, for more information on breakpoint conditions.
1001 @@item tbreak @@var{args}
1003 Set a breakpoint enabled only for one stop. @@var{args} are the
1004 same as in the @@samp{break} command, and the breakpoint is set in the same
1005 way, but the breakpoint is automatically @@dfn{disabled} the first time it
1009 GDB allows you to set any number of breakpoints at the same place in the
1010 program. There is nothing silly or meaningless about this. When the
1011 breakpoints are conditional, this is even useful (@@pxref{Conditions}).
1013 @@node Clear Breaks, Disabling, Set Breaks, Breakpoints
1014 @@subsection Clearing Breakpoints
1016 @@cindex clear breakpoint
1017 @@cindex delete breakpoints
1018 It is often necessary to eliminate a breakpoint once it has done its job
1019 and you no longer want the program to stop there. This is called
1020 @@dfn{clearing} or @@samp{deleting} the breakpoint. A breakpoint that
1021 has been cleared no longer exists in any sense.
1023 With the @@samp{clear} command you can clear breakpoints according to where
1024 they are in the program. With the @@samp{delete} command you can clear
1025 individual breakpoints by specifying their breakpoint numbers.
1027 @@b{It is not necessary to clear a breakpoint to proceed past it.} GDB
1028 automatically ignores breakpoints in the first instruction to be executed
1029 when you continue execution at the same address where the program stopped.
1034 Clear any breakpoints at the next instruction to be executed in the
1035 selected stack frame (@@pxref{Selection}). When the innermost frame
1036 is selected, this is a good way to clear a breakpoint that the program
1039 @@item clear @@var{function}
1040 @@itemx clear @@var{filename}:@@var{function}
1041 Clear any breakpoints set at entry to the function @@var{function}.
1043 @@item clear @@var{linenum}
1044 @@item clear @@var{filename}:@@var{linenum}
1045 Clear any breakpoints set at or within the code of the specified line.
1047 @@item delete @@var{bnums}@@dots{}
1049 Delete the breakpoints of the numbers specified as arguments.
1050 A breakpoint deleted is forgotten completely.
1053 @@node Disabling, Conditions, Clear Breaks, Breakpoints
1054 @@subsection Disabling Breakpoints
1056 @@cindex disabled breakpoints
1057 @@cindex enabled breakpoints
1058 Rather than clearing a breakpoint, you might prefer to @@dfn{disable} it.
1059 This makes the breakpoint inoperative as if it had been cleared, but
1060 remembers the information on the breakpoint so that you can @@dfn{enable}
1063 You disable and enable breakpoints with the @@samp{enable} and
1064 @@samp{disable} commands, specifying one or more breakpoint numbers as
1065 arguments. Use @@samp{info break} to print a list of breakpoints if you
1066 don't know which breakpoint numbers to use.
1068 A breakpoint can have any of four different states of enablement:
1072 Enabled. The breakpoint will stop the program. A breakpoint made
1073 with the @@samp{break} command starts out in this state.
1075 Disabled. The breakpoint has no effect on the program.
1077 Enabled once. The breakpoint will stop the program, but
1078 when it does so it will become disabled. A breakpoint made
1079 with the @@samp{tbreak} command starts out in this state.
1081 Enabled for deletion. The breakpoint will stop the program, but
1082 immediately after it does so it will be deleted permanently.
1085 You change the state of enablement of a breakpoint with the following
1089 @@item disable breakpoints @@var{bnums}@@dots{}
1090 @@kindex disable breakpoints
1091 @@item disable @@var{bnums}@@dots{}
1093 Disable the specified breakpoints. A disabled breakpoint has no
1094 effect but is not forgotten. All options such as ignore-counts,
1095 conditions and commands are remembered in case the breakpoint is
1096 enabled again later.
1098 @@item enable breakpoints @@var{bnums}@@dots{}
1099 @@kindex enable breakpoints
1100 @@item enable @@var{bnums}@@dots{}
1102 Enable the specified breakpoints. They become effective once again in
1103 stopping the program, until you specify otherwise.
1105 @@item enable breakpoints once @@var{bnums}@@dots{}
1106 @@item enable once @@var{bnums}@@dots{}
1107 Enable the specified breakpoints temporarily. Each will be disabled
1108 again the next time it stops the program (unless you have used one of
1109 these commands to specify a different state before that time comes).
1111 @@item enable breakpoints delete @@var{bnums}@@dots{}
1112 @@item enable delete @@var{bnums}@@dots{}
1113 Enable the specified breakpoints to work once and then die. Each of
1114 the breakpoints will be deleted the next time it stops the program
1115 (unless you have used one of these commands to specify a different
1116 state before that time comes).
1119 Aside from the automatic disablement or deletion of a breakpoint when it
1120 stops the program, which happens only in certain states, the state of
1121 enablement of a breakpoint changes only when one of the commands above
1124 @@node Conditions, Break Commands, Disabling, Breakpoints
1125 @@subsection Break Conditions
1128 The simplest sort of breakpoint breaks every time the program reaches a
1129 specified place. You can also specify a @@dfn{condition} for a breakpoint.
1130 A condition is just a boolean expression in your programming language
1131 (@@xref{Expressions}). A breakpoint with a condition evaluates the
1132 expression each time the program reaches it, and the program stops
1133 only if the condition is true.
1135 Break conditions may have side effects, and may even call functions in your
1136 program. These may sound like strange things to do, but their effects are
1137 completely predictable unless there is another enabled breakpoint at the
1138 same address. (In that case, GDB might see the other breakpoint first and
1139 stop the program without checking the condition of this one.) Note that
1140 breakpoint commands are usually more convenient and flexible for the
1141 purpose of performing side effects when a breakpoint is reached
1142 (@@pxref{Break Commands}).
1144 Break conditions can be specified when a breakpoint is set, by using
1145 @@samp{if} in the arguments to the @@samp{break} command. @@xref{Set Breaks}.
1146 They can also be changed at any time with the @@samp{condition} command:
1149 @@item condition @@var{bnum} @@var{expression}
1151 Specify @@var{expression} as the break condition for breakpoint number
1152 @@var{bnum}. From now on, this breakpoint will stop the program only if
1153 the value of @@var{expression} is true (nonzero, in C). @@var{expression}
1154 is not evaluated at the time the @@samp{condition} command is given.
1155 @@xref{Expressions}.
1157 @@item condition @@var{bnum}
1158 Remove the condition from breakpoint number @@var{bnum}. It becomes
1159 an ordinary unconditional breakpoint.
1162 @@cindex ignore count (of breakpoint)
1163 A special feature is provided for one kind of condition: to prevent the
1164 breakpoint from doing anything until it has been reached a certain number
1165 of times. This is done with the @@dfn{ignore count} of the breakpoint.
1166 When the program reaches a breakpoint whose ignore count is positive, then
1167 instead of stopping, it just decrements the ignore count by one and
1171 @@item ignore @@var{bnum} @@var{count}
1173 Set the ignore count of breakpoint number @@var{bnum} to @@var{count}.
1174 The next @@var{count} times the breakpoint is reached, it will not stop.
1176 To make the breakpoint stop the next time it is reached, specify
1179 @@item cont @@var{count}
1180 Continue execution of the program, setting the ignore count of the
1181 breakpoint that the program stopped at to @@var{count} minus one.
1182 Continuing through the breakpoint does not itself count as one of
1183 @@var{count}. Thus, the program will not stop at this breakpoint until the
1184 @@var{count}'th time it is hit.
1186 This command is allowed only when the program stopped due to a
1187 breakpoint. At other times, the argument to @@samp{cont} is ignored.
1190 If a breakpoint has a positive ignore count and a condition, the condition
1191 is not checked. Once the ignore count reaches zero, the condition will
1192 start to be checked.
1194 Note that you could achieve the effect of the ignore count with a condition
1195 such as @@samp{$foo-- <= 0} using a debugger convenience variable that is
1196 decremented each time. That is why the ignore count is considered a
1197 special case of a condition. @@xref{Convenience Vars}.
1199 @@node Break Commands, Error in Breakpoints, Conditions, Breakpoints
1200 @@subsection Commands Executed on Breaking
1202 @@cindex breakpoint commands
1203 You can give any breakpoint a series of commands to execute when the
1204 program stops due to that breakpoint. For example, you might want to
1205 print the values of certain expressions, or enable other breakpoints.
1208 @@item commands @@var{bnum}
1209 Specify commands for breakpoint number @@var{bnum}. The commands
1210 themselves appear on the following lines. Type a line containing just
1211 @@samp{end} to terminate the commands.
1213 To remove all commands from a breakpoint, use the command
1214 @@samp{commands} and follow it immediately by @@samp{end}; that is, give
1217 With no arguments, @@samp{commands} refers to the last breakpoint set.
1220 It is possible for breakpoint commands to start the program up again.
1221 Simply use the @@samp{cont} command, or @@samp{step}, or any other command
1222 to resume execution. However, any remaining breakpoint commands are
1223 ignored. When the program stops again, GDB will act according to why
1224 that stop took place.
1227 If the first command specified is @@samp{silent}, the usual message about
1228 stopping at a breakpoint is not printed. This may be desirable for
1229 breakpoints that are to print a specific message and then continue.
1230 If the remaining commands too print nothing, you will see no sign that
1231 the breakpoint was reached at all. @@samp{silent} is not really a command;
1232 it is meaningful only at the beginning of the commands for a breakpoint.
1234 The commands @@samp{echo} and @@samp{output} that allow you to print precisely
1235 controlled output are often useful in silent breakpoints. @@xref{Output}.
1237 For example, here is how you could use breakpoint commands to print the
1238 value of @@code{x} at entry to @@code{foo} whenever it is positive. We
1239 assume that the newly created breakpoint is number 4; @@samp{break} will
1240 print the number that is assigned.
1253 One application for breakpoint commands is to correct one bug so you can
1254 test another. Put a breakpoint just after the erroneous line of code, give
1255 it a condition to detect the case in which something erroneous has been
1256 done, and give it commands to assign correct values to any variables that
1257 need them. End with the @@samp{cont} command so that the program does not
1258 stop, and start with the @@samp{silent} command so that no output is
1259 produced. Here is an example:
1270 One deficiency in the operation of automatically continuing breakpoints
1271 under Unix appears when your program uses raw mode for the terminal.
1272 GDB switches back to its own terminal modes (not raw) before executing
1273 commands, and then must switch back to raw mode when your program is
1274 continued. This causes any pending terminal input to be lost.
1276 In the GNU system, this will be fixed by changing the behavior of
1279 Under Unix, when you have this problem, you might be able to get around
1280 it by putting your actions into the breakpoint condition instead of
1281 commands. For example
1284 condition 5 (x = y + 4), 0
1288 is a condition expression (@@xref{Expressions}) that will change @@code{x}
1289 as needed, then always have the value 0 so the program will not stop.
1290 Loss of input is avoided here because break conditions are evaluated
1291 without changing the terminal modes. When you want to have nontrivial
1292 conditions for performing the side effects, the operators @@samp{&&},
1293 @@samp{||} and @@samp{?@@: @@dots{} :@@:} may be useful.
1295 @@node Error in Breakpoints,, Break Commands, Breakpoints
1296 @@subsection ``Cannot Insert Breakpoints'' Error
1298 Under some Unix systems, breakpoints cannot be used in a program if any
1299 other process is running that program. Attempting to run or continue
1300 the program with a breakpoint in this case will cause GDB to stop it.
1302 When this happens, you have three ways to proceed:
1306 Remove or disable the breakpoints, then continue.
1309 Suspend GDB, and copy the file containing the program to a new name.
1310 Resume GDB and use the @@samp{exec-file} command to specify that GDB
1311 should run the program under that name. Then start the program again.
1314 Recompile the program so that the text is non-sharable (a.out format
1318 @@node Continuing, Stepping, Breakpoints, Stopping
1319 @@section Continuing
1321 After your program stops, most likely you will want it to run some more if
1322 the bug you are looking for has not happened yet.
1327 Continue running the program at the place where it stopped.
1330 If the program stopped at a breakpoint, the place to continue running
1331 is the address of the breakpoint. You might expect that continuing would
1332 just stop at the same breakpoint immediately. In fact, @@samp{cont}
1333 takes special care to prevent that from happening. You do not need
1334 to clear the breakpoint to proceed through it after stopping at it.
1336 You can, however, specify an ignore-count for the breakpoint that the
1337 program stopped at, by means of an argument to the @@samp{cont} command.
1340 If the program stopped because of a signal other than @@code{SIGINT} or
1341 @@code{SIGTRAP}, continuing will cause the program to see that signal.
1342 You may not want this to happen. For example, if the program stopped
1343 due to some sort of memory reference error, you might store correct
1344 values into the erroneous variables and continue, hoping to see more
1345 execution; but the program would probably terminate immediately as
1346 a result of the fatal signal once it sees the signal. To prevent this,
1347 you can continue with @@samp{signal 0}. @@xref{Signaling}. You can
1348 also act in advance to prevent the program from seeing certain kinds
1349 of signals, using the @@samp{handle} command (@@pxref{Signals}).
1351 @@node Stepping,, Continuing, Stopping
1355 @@dfn{Stepping} means setting your program in motion for a limited time, so
1356 that control will return automatically to the debugger after one line of
1357 code or one machine instruction. Breakpoints are active during stepping
1358 and the program will stop for them even if it has not gone as far as the
1359 stepping command specifies.
1364 Proceed the program until control reaches a different line, then stop
1365 it and return to the debugger. This command is abbreviated @@samp{s}.
1367 @@item step @@var{count}
1368 Proceed as in @@samp{step}, but do so @@var{count} times. If a breakpoint
1369 or a signal not related to stepping is reached before @@var{count} steps,
1370 stepping stops right away.
1372 This command may be given when control is within a routine for which
1373 there is no debugging information. In that case, execution will proceed
1374 until control reaches a different routine, or is about to return from
1375 this routine. An argument repeats this action.
1379 Similar to @@samp{step}, but any function calls appearing within the line of
1380 code are executed without stopping. Execution stops when control reaches a
1381 different line of code at the stack level which was executing when the
1382 @@samp{next} command was given. This command is abbreviated @@samp{n}.
1384 An argument is a repeat count, as in @@samp{step}.
1386 @@samp{next} within a routine without debugging information acts as does
1387 @@samp{step}, but any function calls appearing within the code of the
1388 routine are executed without stopping.
1392 Continue running until just after the selected stack frame returns
1393 (or until there is some other reason to stop, such as a fatal signal
1394 or a breakpoint). Print value returned by the selected stack frame (if
1397 Contrast this with the @@samp{return} command (@@pxref{Returning}).
1401 Proceed the program until control reaches a line greater than the current
1402 line, then stop is and return to the debugger. Control is also returned to
1403 the debugger if the program exits the current stack frame. Note that this
1404 form of the command uses single stepping, and hence is slower than
1405 @@samp{until} with an argument. This command is abbreviated @@samp{u}.
1407 @@item until @@var{location}
1408 Proceed the program until either the specified location is reached, or the
1409 current (innermost) stack frame returns. This form of the command uses
1410 breakpoints, and hence is quicker than @@samp{until} without an argument.
1416 Proceed one machine instruction, then stop and return to the debugger.
1418 It is often useful to do @@samp{display/i $pc} when stepping by machine
1419 instructions. This will cause the next instruction to be executed to
1420 be displayed automatically at each stop. @@xref{Auto Display}.
1422 An argument is a repeat count, as in @@samp{step}.
1428 Proceed one machine instruction, but if it is a subroutine call,
1429 proceed until the subroutine returns.
1431 An argument is a repeat count, as in @@samp{next}.
1434 A typical technique for using stepping is to put a breakpoint
1435 (@@pxref{Breakpoints}) at the beginning of the function or the section of
1436 the program in which a problem is believed to lie, and then step through
1437 the suspect area, examining the variables that are interesting, until the
1440 The @@samp{cont} command can be used after stepping to resume execution
1441 until the next breakpoint or signal.
1443 @@node Stack, Source, Stopping, Top
1444 @@chapter Examining the Stack
1446 When your program has stopped, the first thing you need to know is where it
1447 stopped and how it got there.
1450 Each time your program performs a function call, the information about
1451 where in the program the call was made from is saved in a block of data
1452 called a @@dfn{stack frame}. The frame also contains the arguments of the
1453 call and the local variables of the function that was called. All the
1454 stack frames are allocated in a region of memory called the @@dfn{call
1457 When your program stops, the GDB commands for examining the stack allow you
1458 to see all of this information.
1460 One of the stack frames is @@dfn{selected} by GDB and many GDB commands
1461 refer implicitly to the selected frame. In particular, whenever you ask
1462 GDB for the value of a variable in the program, the value is found in the
1463 selected frame. There are special GDB commands to select whichever frame
1464 you are interested in.
1466 When the program stops, GDB automatically selects the currently executing
1467 frame and describes it briefly as the @@samp{frame} command does
1468 (@@pxref{Frame Info, Info}).
1471 * Frames:: Explanation of stack frames and terminology.
1472 * Backtrace:: Summarizing many frames at once.
1473 * Selection:: How to select a stack frame.
1474 * Info: Frame Info, Commands to print information on stack frames.
1477 @@node Frames, Backtrace, Stack, Stack
1478 @@section Stack Frames
1481 The call stack is divided up into contiguous pieces called @@dfn{frames};
1482 each frame is the data associated with one call to one function. The frame
1483 contains the arguments given to the function, the function's local
1484 variables, and the address at which the function is executing.
1486 @@cindex initial frame
1487 @@cindex outermost frame
1488 @@cindex innermost frame
1489 When your program is started, the stack has only one frame, that of the
1490 function @@code{main}. This is called the @@dfn{initial} frame or the
1491 @@dfn{outermost} frame. Each time a function is called, a new frame is
1492 made. Each time a function returns, the frame for that function invocation
1493 is eliminated. If a function is recursive, there can be many frames for
1494 the same function. The frame for the function in which execution is
1495 actually occurring is called the @@dfn{innermost} frame. This is the most
1496 recently created of all the stack frames that still exist.
1498 @@cindex frame pointer
1499 Inside your program, stack frames are identified by their addresses. A
1500 stack frame consists of many bytes, each of which has its own address; each
1501 kind of computer has a convention for choosing one of those bytes whose
1502 address serves as the address of the frame. Usually this address is kept
1503 in a register called the @@dfn{frame pointer register} while execution is
1504 going on in that frame.
1506 @@cindex frame number
1507 GDB assigns numbers to all existing stack frames, starting with zero for
1508 the innermost frame, one for the frame that called it, and so on upward.
1509 These numbers do not really exist in your program; they are to give you a
1510 way of talking about stack frames in GDB commands.
1512 @@cindex selected frame
1513 Many GDB commands refer implicitly to one stack frame. GDB records a stack
1514 frame that is called the @@dfn{selected} stack frame; you can select any
1515 frame using one set of GDB commands, and then other commands will operate
1516 on that frame. When your program stops, GDB automatically selects the
1519 @@node Backtrace, Selection, Frames, Stack
1520 @@section Backtraces
1522 A backtrace is a summary of how the program got where it is. It shows one
1523 line per frame, for many frames, starting with the currently executing
1524 frame (frame zero), followed by its caller (frame one), and on up the
1530 Print a backtrace of the entire stack: one line per frame for all
1531 frames in the stack.
1533 You can stop the backtrace at any time by typing the system interrupt
1534 character, normally @@kbd{Control-C}.
1536 @@item backtrace @@var{n}
1538 Similar, but stop after @@var{n} frames.
1540 @@item backtrace @@var{-n}
1541 @@itemx bt @@var{-n}
1542 Similar, but print the outermost @@var{n} frames instead of the
1546 Each line in a backtrace shows the frame number, the program counter, the
1547 function and its arguments, and the source file name and line number (if
1548 known). The program counter is omitted if is the beginning of the code for
1549 the source line. This is the same as the first of the two lines printed
1550 when you select a frame.
1552 @@node Selection, Frame Info, Backtrace, Stack
1553 @@section Selecting a Frame
1555 Most commands for examining the stack and other data in the program work on
1556 whichever stack frame is selected at the moment. Here are the commands for
1557 selecting a stack frame; all of them finish by printing a brief description
1558 of the stack frame just selected.
1561 @@item frame @@var{n}
1563 Select frame number @@var{n}. Recall that frame zero is the innermost
1564 (currently executing) frame, frame one is the frame that called the
1565 innermost one, and so on. The highest-numbered frame is @@code{main}'s
1568 @@item frame @@var{addr}
1569 Select the frame at address @@var{addr}. This is useful mainly if the
1570 chaining of stack frames has been damaged by a bug, making it
1571 impossible for GDB to assign numbers properly to all frames. In
1572 addition, this can be useful when the program has multiple stacks and
1573 switches between them.
1577 Select the frame @@var{n} frames up from the frame previously selected.
1578 For positive numbers @@var{n}, this advances toward the outermost
1579 frame, to higher frame numbers, to frames that have existed longer.
1580 @@var{n} defaults to one.
1582 @@item down @@var{n}
1584 Select the frame @@var{n} frames down from the frame previously
1585 selected. For positive numbers @@var{n}, this advances toward the
1586 innermost frame, to lower frame numbers, to frames that were created
1587 more recently. @@var{n} defaults to one.
1590 All of these commands end by printing some information on the frame that
1591 has been selected: the frame number, the function name, the arguments, the
1592 source file and line number of execution in that frame, and the text of
1593 that source line. For example:
1596 #3 main (argc=3, argv=??, env=??) at main.c, line 67
1597 67 read_input_file (argv[i]);
1600 After such a printout, the @@samp{list} command with no arguments will print
1601 ten lines centered on the point of execution in the frame. @@xref{List}.
1603 @@node Frame Info,, Selection, Stack
1604 @@section Information on a Frame
1606 There are several other commands to print information about the selected
1611 This command prints a brief description of the selected stack frame.
1612 It can be abbreviated @@samp{f}. With an argument, this command is
1613 used to select a stack frame; with no argument, it does not change
1614 which frame is selected, but still prints the same information.
1618 This command prints a verbose description of the selected stack frame,
1619 including the address of the frame, the addresses of the next frame in
1620 (called by this frame) and the next frame out (caller of this frame),
1621 the address of the frame's arguments, the program counter saved in it
1622 (the address of execution in the caller frame), and which registers
1623 were saved in the frame. The verbose description is useful when
1624 something has gone wrong that has made the stack format fail to fit
1625 the usual conventions.
1627 @@item info frame @@var{addr}
1628 Print a verbose description of the frame at address @@var{addr},
1629 without selecting that frame. The selected frame remains unchanged by
1634 Print the arguments of the selected frame, each on a separate line.
1637 @@kindex info locals
1638 Print the local variables of the selected frame, each on a separate
1639 line. These are all variables declared static or automatic within all
1640 program blocks that execution in this frame is currently inside of.
1643 @@node Source, Data, Stack, Top
1644 @@chapter Examining Source Files
1646 GDB knows which source files your program was compiled from, and
1647 can print parts of their text. When your program stops, GDB
1648 spontaneously prints the line it stopped in. Likewise, when you
1649 select a stack frame (@@pxref{Selection}), GDB prints the line
1650 which execution in that frame has stopped in. You can also
1651 print parts of source files by explicit command.
1654 * List:: Using the @@samp{list} command to print source files.
1655 * Search:: Commands for searching source files.
1656 * Source Path:: Specifying the directories to search for source files.
1659 @@node List, Search, Source, Source
1660 @@section Printing Source Lines
1663 To print lines from a source file, use the @@samp{list} command
1664 (abbreviated @@samp{l}). There are several ways to specify what part
1665 of the file you want to print.
1667 Here are the forms of the @@samp{list} command most commonly used:
1670 @@item list @@var{linenum}
1671 Print ten lines centered around line number @@var{linenum} in the
1672 current source file.
1674 @@item list @@var{function}
1675 Print ten lines centered around the beginning of function
1679 Print ten more lines. If the last lines printed were printed with a
1680 @@samp{list} command, this prints ten lines following the last lines
1681 printed; however, if the last line printed was a solitary line printed
1682 as part of displaying a stack frame (@@pxref{Stack}), this prints ten
1683 lines centered around that line.
1685 @@item list @@minus{}
1686 Print ten lines just before the lines last printed.
1689 Repeating a @@samp{list} command with @@key{RET} discards the argument,
1690 so it is equivalent to typing just @@samp{list}. This is more useful
1691 than listing the same lines again. An exception is made for an
1692 argument of @@samp{-}; that argument is preserved in repetition so that
1693 each repetition moves up in the file.
1695 In general, the @@samp{list} command expects you to supply zero, one or two
1696 @@dfn{linespecs}. Linespecs specify source lines; there are several ways
1697 of writing them but the effect is always to specify some source line.
1698 Here is a complete description of the possible arguments for @@samp{list}:
1701 @@item list @@var{linespec}
1702 Print ten lines centered around the line specified by @@var{linespec}.
1704 @@item list @@var{first},@@var{last}
1705 Print lines from @@var{first} to @@var{last}. Both arguments are
1708 @@item list ,@@var{last}
1709 Print ten lines ending with @@var{last}.
1711 @@item list @@var{first},
1712 Print ten lines starting with @@var{first}.
1715 Print ten lines just after the lines last printed.
1717 @@item list @@minus{}
1718 Print ten lines just before the lines last printed.
1721 As described in the preceding table.
1724 Here are the ways of specifying a single source line---all the
1728 @@item @@var{linenum}
1729 Specifies line @@var{linenum} of the current source file.
1730 When a @@samp{list} command has two linespecs, this refers to
1731 the same source file as the first linespec.
1733 @@item +@@var{offset}
1734 Specifies the line @@var{offset} lines after the last line printed.
1735 When used as the second linespec in a @@samp{list} command that has
1736 two, this specifies the line @@var{offset} lines down from the
1739 @@item @@minus{}@@var{offset}
1740 Specifies the line @@var{offset} lines before the last line printed.
1742 @@item @@var{filename}:@@var{linenum}
1743 Specifies line @@var{linenum} in the source file @@var{filename}.
1745 @@item @@var{function}
1746 Specifies the line of the open-brace that begins the body of the
1747 function @@var{function}.
1749 @@item @@var{filename}:@@var{function}
1750 Specifies the line of the open-brace that begins the body of the
1751 function @@var{function} in the file @@var{filename}. The file name is
1752 needed with a function name only for disambiguation of identically
1753 named functions in different source files.
1755 @@item *@@var{address}
1756 Specifies the line containing the program address @@var{address}.
1757 @@var{address} may be any expression.
1760 One other command is used to map source lines to program addresses.
1763 @@item info line @@var{linenum}
1765 Print the starting and ending addresses of the compiled code for
1766 source line @@var{linenum}.
1769 The default examine address for the @@samp{x} command is changed to the
1770 starting address of the line, so that @@samp{x/i} is sufficient to
1771 begin examining the machine code (@@pxref{Memory}). Also, this address
1772 is saved as the value of the convenience variable @@samp{$_}
1773 (@@pxref{Convenience Vars}).
1776 @@node Search, Source Path, List, Source
1777 @@section Searching Source Files
1779 @@kindex forward-search
1780 @@kindex reverse-search
1782 There are two commands for searching through the current source file for a
1785 The command @@samp{forward-search @@var{regexp}} checks each line, starting
1786 with the one following the last line listed, for a match for @@var{regexp}.
1787 It lists the line that is found. You can abbreviate the command name
1790 The command @@samp{reverse-search @@var{regexp}} checks each line, starting
1791 with the one before the last line listed and going backward, for a match
1792 for @@var{regexp}. It lists the line that is found. You can abbreviate
1793 this command with as little as @@samp{rev}.
1795 @@node Source Path,, Search, Source
1796 @@section Specifying Source Directories
1798 @@cindex source path
1799 @@cindex directories for source files
1800 Executable programs do not record the directories of the source files they
1801 were compiled from, just the names. GDB remembers a list of directories to
1802 search for source files; this is called the @@dfn{source path}. Each time
1803 GDB wants a source file, it tries all the directories in the list, in the
1804 order they are present in the list, until it finds a file with the desired
1808 When you start GDB, its source path contains just the current working
1809 directory. To add other directories, use the @@samp{directory} command.
1810 @@b{Note that the search path for executable files and the working directory
1811 are @@i{not} used for finding source files.}
1814 @@item directory @@var{dirname}
1815 Add directory @@var{dirname} to the end of the source path.
1818 Reset the source path to just the current working directory of GDB.
1819 This requires confirmation.
1821 @@samp{directory} with no argument can cause source files previously
1822 found by GDB to be found in a different directory. To make this work
1823 correctly, this command also clears out the tables GDB maintains
1824 about the source files it has already found.
1826 @@item info directories
1827 @@kindex info directories
1828 Print the source path: show which directories it contains.
1831 Because the @@samp{directory} command adds to the end of the source path,
1832 it does not affect any file that GDB has already found. If the source
1833 path contains directories that you do not want, and these directories
1834 contain misleading files with names matching your source files, the
1835 way to correct the situation is as follows:
1839 Choose the directory you want at the beginning of the source path.
1840 Use the @@samp{cd} command to make that the current working directory.
1843 Use @@samp{directory} with no argument to reset the source path to just
1847 Use @@samp{directory} with suitable arguments to add any other
1848 directories you want in the source path.
1851 @@node Data, Symbols, Source, Top
1852 @@chapter Examining Data
1854 @@cindex printing data
1855 @@cindex examining data
1857 The usual way of examining data in your program is with the @@samp{print}
1858 command (abbreviated @@samp{p}). It evaluates and prints the value of any
1859 valid expression of the language the program is written in (for now, C).
1867 where @@var{exp} is any valid expression, and the value of @@var{exp}
1868 is printed in a format appropriate to its data type.
1870 A more low-level way of examining data is with the @@samp{x} command.
1871 It examines data in memory at a specified address and prints it in a
1874 GDB supports one command to modify the default format of displayed data:
1877 @@item set array-max
1878 @@kindex set array-max
1879 @@samp{set array-max} sets the maximum number of elements of an array which
1880 will be printed. This limit also applies to the display of strings.
1884 * Expressions:: Expressions that can be computed and printed.
1885 * Variables:: Using your program's variables in expressions.
1886 * Assignment:: Setting your program's variables.
1887 * Arrays:: Examining part of memory as an array.
1888 * Formats:: Specifying formats for printing values.
1889 * Memory:: Examining memory explicitly.
1890 * Auto Display:: Printing certain expressions whenever program stops.
1891 * Value History:: Referring to values previously printed.
1892 * Convenience Vars:: Giving names to values for future reference.
1893 * Registers:: Referring to and storing in machine registers.
1896 @@node Expressions, Variables, Data, Data
1897 @@section Expressions
1899 @@cindex expressions
1900 Many different GDB commands accept an expression and compute its value.
1901 Any kind of constant, variable or operator defined by the programming
1902 language you are using is legal in an expression in GDB. This includes
1903 conditional expressions, function calls, casts and string constants.
1904 It unfortunately does not include symbols defined by preprocessor
1907 Casts are supported in all languages, not just in C, because it is so
1908 useful to cast a number into a pointer so as to examine a structure
1909 at that address in memory.
1911 GDB supports three kinds of operator in addition to those of programming
1916 @@samp{@@@@} is a binary operator for treating parts of memory as arrays.
1917 @@xref{Arrays}, for more information.
1920 @@samp{::} allows you to specify a variable in terms of the file or
1921 function it is defined in. @@xref{Variables}.
1923 @@item @@{@@var{type}@@} @@var{addr}
1924 Refers to an object of type @@var{type} stored at address @@var{addr} in
1925 memory. @@var{addr} may be any expression whose value is an integer or
1926 pointer (but parentheses are required around nonunary operators, just as in
1927 a cast). This construct is allowed regardless of what kind of data is
1928 officially supposed to reside at @@var{addr}.@@refill
1931 @@node Variables, Arrays, Expressions, Data
1932 @@section Program Variables
1934 The most common kind of expression to use is the name of a variable
1937 Variables in expressions are understood in the selected stack frame
1938 (@@pxref{Selection}); they must either be global (or static) or be visible
1939 according to the scope rules of the programming language from the point of
1940 execution in that frame. This means that in the function
1955 the variable @@code{a} is usable whenever the program is executing
1956 within the function @@code{foo}, but the variable @@code{b} is visible
1957 only while the program is executing inside the block in which @@code{b}
1960 As a special exception, you can refer to a variable or function whose
1961 scope is a single source file even if the current execution point is not
1962 in this file. But it is possible to have more than one such variable
1963 or function with the same name (if they are in different source files).
1964 In such a case, it is not defined which one you will get. If you wish,
1965 you can specify any one of them using the colon-colon construct:
1968 @@var{block}::@@var{variable}
1972 Here @@var{block} is the name of the source file whose variable you want.
1974 @@node Arrays, Formats, Variables, Data
1975 @@section Artificial Arrays
1977 @@cindex artificial array
1978 It is often useful to print out several successive objects of the
1979 same type in memory; a section of an array, or an array of
1980 dynamically determined size for which only a pointer exists in the
1983 This can be done by constructing an @@dfn{artificial array} with the
1984 binary operator @@samp{@@@@}. The left operand of @@samp{@@@@} should be
1985 the first element of the desired array, as an individual object.
1986 The right operand should be the length of the array. The result is
1987 an array value whose elements are all of the type of the left argument.
1988 The first element is actually the left argument; the second element
1989 comes from bytes of memory immediately following those that hold the
1990 first element, and so on. Here is an example. If a program says
1993 int *array = (int *) malloc (len * sizeof (int));
1997 you can print the contents of @@code{array} with
2003 The left operand of @@samp{@@@@} must reside in memory. Array values made
2004 with @@samp{@@@@} in this way behave just like other arrays in terms of
2005 subscripting, and are coerced to pointers when used in expressions.
2006 (It would probably appear in an expression via the value history,
2007 after you had printed it out.)
2009 @@node Formats, Memory, Arrays, Data
2012 @@cindex formatted output
2013 @@cindex output formats
2014 GDB normally prints all values according to their data types. Sometimes
2015 this is not what you want. For example, you might want to print a number
2016 in hex, or a pointer in decimal. Or you might want to view data in memory
2017 at a certain address as a character string or an instruction. These things
2018 can be done with @@dfn{output formats}.
2020 The simplest use of output formats is to say how to print a value
2021 already computed. This is done by starting the arguments of the
2022 @@samp{print} command with a slash and a format letter. The format
2023 letters supported are:
2027 Regard the bits of the value as an integer, and print the integer in
2031 Print as integer in signed decimal.
2034 Print as integer in unsigned decimal.
2037 Print as integer in octal.
2040 Print as an address, both absolute in hex and then relative
2041 to a symbol defined as an address below it.
2044 Regard as an integer and print it as a character constant.
2047 Regard the bits of the value as a floating point number and print
2048 using typical floating point syntax.
2051 For example, to print the program counter in hex (@@pxref{Registers}), type
2058 Note that no space is required before the slash; this is because command
2059 names in GDB cannot contain a slash.
2061 To reprint the last value in the value history with a different format,
2062 you can use the @@samp{print} command with just a format and no
2063 expression. For example, @@samp{p/x} reprints the last value in hex.
2065 @@node Memory, Auto Display, Formats, Data
2066 @@subsection Examining Memory
2068 @@cindex examining memory
2070 The command @@samp{x} (for `examine') can be used to examine memory under
2071 explicit control of formats, without reference to the program's data types.
2073 @@samp{x} is followed by a slash and an output format specification,
2074 followed by an expression for an address. The expression need not have
2075 a pointer value (though it may); it is used as an integer, as the
2076 address of a byte of memory. @@xref{Expressions} for more information
2079 The output format in this case specifies both how big a unit of memory
2080 to examine and how to print the contents of that unit. It is done
2081 with one or two of the following letters:
2083 These letters specify just the size of unit to examine:
2087 Examine individual bytes.
2090 Examine halfwords (two bytes each).
2093 Examine words (four bytes each).
2096 Many assemblers and cpu designers still use `word' for a 16-bit quantity,
2097 as a holdover from specific predecessor machines of the 1970's that really
2098 did use two-byte words. But more generally the term `word' has always
2099 referred to the size of quantity that a machine normally operates on and
2100 stores in its registers. This is 32 bits for all the machines that GNU
2104 Examine giant words (8 bytes).
2107 These letters specify just the way to print the contents:
2111 Print as integers in unsigned hexadecimal.
2114 Print as integers in signed decimal.
2117 Print as integers in unsigned decimal.
2120 Print as integers in unsigned octal.
2123 Print as an address, both absolute in hex and then relative
2124 to a symbol defined as an address below it.
2127 Print as character constants.
2130 Print as floating point. This works only with sizes @@samp{w} and
2134 Print a null-terminated string of characters. The specified unit size
2135 is ignored; instead, the unit is however many bytes it takes to reach
2136 a null character (including the null character).
2139 Print a machine instruction in assembler syntax (or nearly). The
2140 specified unit size is ignored; the number of bytes in an instruction
2141 varies depending on the type of machine, the opcode and the addressing
2145 If either the manner of printing or the size of unit fails to be specified,
2146 the default is to use the same one that was used last. If you don't want
2147 to use any letters after the slash, you can omit the slash as well.
2149 You can also omit the address to examine. Then the address used is
2150 just after the last unit examined. This is why string and instruction
2151 formats actually compute a unit-size based on the data: so that the
2152 next string or instruction examined will start in the right place.
2153 The @@samp{print} command sometimes sets the default address for
2154 the @@samp{x} command; when the value printed resides in memory, the
2155 default is set to examine the same location. @@samp{info line} also
2156 sets the default for @@samp{x}, to the address of the start of the
2157 machine code for the specified line and @@samp{info breakpoints} sets
2158 it to the address of the last breakpoint listed.
2160 When you use @@key{RET} to repeat an @@samp{x} command, it does not repeat
2161 exactly the same: the address specified previously (if any) is ignored, so
2162 that the repeated command examines the successive locations in memory
2163 rather than the same ones.
2165 You can examine several consecutive units of memory with one command by
2166 writing a repeat-count after the slash (before the format letters, if any).
2167 The repeat count must be a decimal integer. It has the same effect as
2168 repeating the @@samp{x} command that many times except that the output may
2169 be more compact with several units per line.
2176 Prints ten instructions starting with the one to be executed next in the
2177 selected frame. After doing this, you could print another ten following
2185 in which the format and address are allowed to default.
2189 The addresses and contents printed by the @@samp{x} command are not put in
2190 the value history because there is often too much of them and they would
2191 get in the way. Instead, GDB makes these values available for subsequent
2192 use in expressions as values of the convenience variables @@samp{$_} and
2195 After an @@samp{x} command, the last address examined is available for use
2196 in expressions in the convenience variable @@samp{$_}. The contents of that
2197 address, as examined, are available in the convenience variable @@samp{$__}.
2199 If the @@samp{x} command has a repeat count, the address and contents saved
2200 are from the last memory unit printed; this is not the same as the last
2201 address printed if several units were printed on the last line of output.
2203 @@node Auto Display, Value History, Memory, Data
2204 @@section Automatic Display
2206 If you find that you want to print the value of an expression frequently
2207 (to see how it changes), you might want to add it to the @@dfn{automatic
2208 display list} so that GDB will print its value each time the program stops.
2209 Each expression added to the list is given a number to identify it;
2210 to remove an expression from the list, you specify that number.
2211 The automatic display looks like this:
2215 3: bar[5] = (struct hack *) 0x3804
2219 showing item numbers, expressions and their current values.
2222 @@item display @@var{exp}
2224 Add the expression @@var{exp} to the list of expressions to display
2225 each time the program stops. @@xref{Expressions}.
2227 @@item display/@@var{fmt} @@var{exp}
2228 For @@var{fmt} specifying only a display format and not a size or
2229 count, add the expression @@var{exp} to the auto-display list but
2230 arranges to display it each time in the specified format @@var{fmt}.
2232 @@item display/@@var{fmt} @@var{addr}
2233 For @@var{fmt} @@samp{i} or @@samp{s}, or including a unit-size or a
2234 number of units, add the expression @@var{addr} as a memory address to
2235 be examined each time the program stops. Examining means in effect
2236 doing @@samp{x/@@var{fmt} @@var{addr}}. @@xref{Memory}.
2238 @@item undisplay @@var{dnums}@@dots{}
2240 @@item delete display @@var{dnums}@@dots{}
2241 @@kindex delete display
2242 Remove item numbers @@var{dnums} from the list of expressions to display.
2244 @@item disable display @@var{dnums}@@dots{}
2245 @@kindex disable display
2246 Disable the display of item numbers @@var{dnums}. A disabled display item
2247 has no effect but is not forgotten. It may be later enabled.
2249 @@item enable display @@var{dnums}@@dots{}
2250 @@kindex enable display
2251 Enable display of item numbers @@var{dnums}. It becomes effective once
2252 again in auto display of its expression, until you specify otherwise.
2255 Display the current values of the expressions on the list, just as is
2256 done when the program stops.
2259 @@kindex info display
2260 Print the list of expressions to display automatically, each one
2261 with its item number, but without showing the values.
2264 @@node Value History, Convenience Vars, Auto Display, Data
2265 @@section Value History
2267 @@cindex value history
2268 Every value printed by the @@samp{print} command is saved for the entire
2269 session in GDB's @@dfn{value history} so that you can refer to it in
2274 The values printed are given @@dfn{history numbers} for you to refer to them
2275 by. These are successive integers starting with 1. @@samp{print} shows you
2276 the history number assigned to a value by printing @@samp{$@@var{n} = }
2277 before the value; here @@var{n} is the history number.
2279 To refer to any previous value, use @@samp{$} followed by the value's
2280 history number. The output printed by @@samp{print} is designed to remind
2281 you of this. Just @@samp{$} refers to the most recent value in the history,
2282 and @@samp{$$} refers to the value before that.
2284 For example, suppose you have just printed a pointer to a structure and
2285 want to see the contents of the structure. It suffices to type
2291 If you have a chain of structures where the component @@samp{next} points
2292 to the next one, you can print the contents of the next one with
2298 It might be useful to repeat this command many times by typing @@key{RET}.
2300 Note that the history records values, not expressions. If the value of
2301 @@code{x} is 4 and you type
2309 then the value recorded in the value history by the @@samp{print} command
2310 remains 4 even though @@code{x}'s value has changed.
2314 @@kindex info history
2315 Print the last ten values in the value history, with their item
2316 numbers. This is like @@samp{p $$9} repeated ten times, except that
2317 @@samp{info history} does not change the history.
2319 @@item info history @@var{n}
2320 Print ten history values centered on history item number @@var{n}.
2323 @@node Convenience Vars, Registers, Value History, Data
2324 @@section Convenience Variables
2326 @@cindex convenience variables
2327 GDB provides @@dfn{convenience variables} that you can use within GDB to
2328 hold on to a value and refer to it later. These variables exist entirely
2329 within GDB; they are not part of your program, and setting a convenience
2330 variable has no effect on further execution of your program. That's why
2331 you can use them freely.
2333 Convenience variables have names starting with @@samp{$}. Any name starting
2334 with @@samp{$} can be used for a convenience variable, unless it is one of
2335 the predefined set of register names (@@pxref{Registers}).
2337 You can save a value in a convenience variable with an assignment
2338 expression, just as you would set a variable in your program. Example:
2341 set $foo = *object_ptr
2345 would save in @@samp{$foo} the value contained in the object pointed to by
2348 Using a convenience variable for the first time creates it; but its value
2349 is @@code{void} until you assign a new value. You can alter the value with
2350 another assignment at any time.
2352 Convenience variables have no fixed types. You can assign a convenience
2353 variable any type of value, even if it already has a value of a different
2354 type. The convenience variable as an expression has whatever type its
2358 @@item info convenience
2359 @@kindex info convenience
2360 Print a list of convenience variables used so far, and their values.
2361 Abbreviated @@samp{i con}.
2364 One of the ways to use a convenience variable is as a counter to be
2365 incremented or a pointer to be advanced. For example:
2369 print bar[$i++]->contents
2370 @@i{@@dots{}repeat that command by typing @@key{RET}.}
2373 Some convenience variables are created automatically by GDB and given
2374 values likely to be useful.
2378 The variable @@samp{$_} is automatically set by the @@samp{x} command to
2379 the last address examined (@@pxref{Memory}). Other commands which
2380 provide a default address for @@samp{x} to examine also set @@samp{$_}
2381 to that address; these commands include @@samp{info line} and @@samp{info
2385 The variable @@samp{$__} is automatically set by the @@samp{x} command
2386 to the value found in the last address examined.
2389 @@node Registers,, Convenience Vars, Data
2393 Machine register contents can be referred to in expressions as variables
2394 with names starting with @@samp{$}. The names of registers are different
2395 for each machine; use @@samp{info registers} to see the names used on your
2396 machine. The names @@samp{$pc} and @@samp{$sp} are used on all machines for
2397 the program counter register and the stack pointer. Often @@samp{$fp} is
2398 used for a register that contains a pointer to the current stack frame.
2400 GDB always considers the contents of an ordinary register as an integer
2401 when the register is examined in this way. Some machines have special
2402 registers which can hold nothing but floating point; these registers are
2403 considered floating point. There is no way to refer to the contents of an
2404 ordinary register as floating point value (although you can @@emph{print}
2405 it as a floating point value with @@samp{print/f $@@var{regname}}).
2407 Some registers have distinct ``raw'' and ``virtual'' data formats. This
2408 means that the data format in which the register contents are saved by the
2409 operating system is not the same one that your program normally sees. For
2410 example, the registers of the 68881 floating point coprocessor are always
2411 saved in ``extended'' format, but virtually all C programs expect to work with
2412 ``double'' format. In such cases, GDB normally works with the virtual
2413 format only (the format that makes sense for your program), but the
2414 @@samp{info registers} command prints the data in both formats.
2416 Register values are relative to the selected stack frame
2417 (@@pxref{Selection}). This means that you get the value that the register
2418 would contain if all stack frames farther in were exited and their saved
2419 registers restored. In order to see the real contents of all registers,
2420 you must select the innermost frame (with @@samp{frame 0}).
2422 Some registers are never saved (typically those numbered zero or one)
2423 because they are used for returning function values; for these registers,
2424 relativization makes no difference.
2427 @@item info registers
2428 @@kindex info registers
2429 Print the names and relativized values of all registers.
2431 @@item info registers @@var{regname}
2432 Print the relativized value of register @@var{regname}. @@var{regname}
2433 may be any register name valid on the machine you are using, with
2434 or without the initial @@samp{$}.
2437 @@subsection Examples
2439 You could print the program counter in hex with
2446 or print the instruction to be executed next with
2453 or add four to the stack pointer with
2460 The last is a way of removing one word from the stack, on machines where
2461 stacks grow downward in memory (most machines, nowadays). This assumes
2462 that the innermost stack frame is selected. Setting @@samp{$sp} is
2463 not allowed when other stack frames are selected.
2465 @@node Symbols, Altering, Data, Top
2466 @@chapter Examining the Symbol Table
2468 The commands described in this section allow you to make inquiries for
2469 information about the symbols (names of variables, functions and types)
2470 defined in your program. This information is found by GDB in the symbol
2471 table loaded by the @@samp{symbol-file} command; it is inherent in the text
2472 of your program and does not change as the program executes.
2475 @@item whatis @@var{exp}
2477 Print the data type of expression @@var{exp}. @@var{exp} is not
2478 actually evaluated, and any side-effecting operations (such as
2479 assignments or function calls) inside it do not take place.
2480 @@xref{Expressions}.
2483 Print the data type of @@samp{$}, the last value in the value history.
2485 @@item info address @@var{symbol}
2486 @@kindex info address
2487 Describe where the data for @@var{symbol} is stored. For register
2488 variables, this says which register. For other automatic variables,
2489 this prints the stack-frame offset at which the variable is always
2490 stored. Note the contrast with @@samp{print &@@var{symbol}}, which does
2491 not work at all for register variables and for automatic variables
2492 prints the exact address of the current instantiation of the variable.
2494 @@item ptype @@var{typename}
2496 Print a description of data type @@var{typename}. @@var{typename} may be
2497 the name of a type, or for C code it may have the form
2498 @@samp{struct @@var{struct-tag}}, @@samp{union @@var{union-tag}} or
2499 @@samp{enum @@var{enum-tag}}.@@refill
2502 @@kindex info sources
2503 Print the names of all source files in the program for which there
2504 is debugging information.
2506 @@item info functions
2507 @@kindex info functions
2508 Print the names and data types of all defined functions.
2510 @@item info functions @@var{regexp}
2511 Print the names and data types of all defined functions
2512 whose names contain a match for regular expression @@var{regexp}.
2513 Thus, @@samp{info fun step} finds all functions whose names
2514 include @@samp{step}; @@samp{info fun ^step} finds those whose names
2515 start with @@samp{step}.
2517 @@item info variables
2518 @@kindex info variables
2519 Print the names and data types of all variables that are declared
2520 outside of functions.
2522 @@item info variables @@var{regexp}
2523 Print the names and data types of all variables, declared outside of
2524 functions, whose names contain a match for regular expression
2529 Print all data types that are defined in the program.
2531 @@item info types @@var{regexp}
2532 Print all data types that are defined in the program whose names
2533 contain a match for regular expression @@var{regexp}.
2536 @@item info methods @@var{regexp}
2537 @@kindex info methods
2538 The @@samp{info-methods} command permits the user to examine all defined
2539 methods within C@@code{++} program, or (with the @@var{regexp} argument) a
2540 specific set of methods found in the various C@@code{++} classes. Many
2541 C@@code{++} classes which implement a large number of differently typed
2542 methods implement a large number of methods as well. Thus, the
2543 @@samp{ptype} command can give the user a tremendous overdose of
2544 information about what methods are associated with a given class. The
2545 @@samp{info-methods} command filters these methods do to only those
2546 methods which match the regular-expression search key.
2548 @@item printsyms @@var{filename}
2550 Write a complete dump of the debugger's symbol data into the
2551 file @@var{filename}.
2554 @@node Altering, Sequences, Symbols, Top
2555 @@chapter Altering Execution
2557 There are several ways to alter the execution of your program with GDB
2561 * Assignment:: Altering variable values or memory contents.
2562 * Jumping:: Altering control flow.
2563 * Signaling:: Making signals happen in the program.
2564 * Returning:: Making a function return prematurely.
2567 @@node Assignment, Jumping, Altering, Altering
2568 @@section Assignment to Variables
2571 @@cindex setting variables
2572 To alter the value of a variable, evaluate an assignment expression.
2573 @@xref{Expressions}. For example,
2580 would store the value 4 into the variable @@code{x}, and then print
2581 the value of the assignment expression (which is 4).
2584 @@kindex set variable
2585 If you are not interested in seeing the value of the assignment, use the
2586 @@samp{set} command instead of the @@samp{print} command. @@samp{set} is
2587 really the same as @@samp{print} except that the expression's value is not
2588 printed and is not put in the value history (@@pxref{Value History}). The
2589 expression is evaluated only for side effects.
2591 Note that if the beginning of the argument string of the @@samp{set} command
2592 appears identical to a @@samp{set} subcommand, it may be necessary to use
2593 the @@samp{set variable} command. This command is identical to @@samp{set}
2594 except for its lack of subcommands.
2596 GDB allows more implicit conversions in assignments than C does; you can
2597 freely store an integer value into a pointer variable or vice versa, and
2598 any structure can be converted to any other structure that is the same
2601 In C, all the other assignment operators such as @@samp{+=} and @@samp{++}
2602 are supported as well.
2604 To store into arbitrary places in memory, use the @@samp{@@{@@dots{}@@}}
2605 construct to generate a value of specified type at a specified address
2606 (@@pxref{Expressions}). For example,
2609 set @@{int@@}0x83040 = 4
2612 @@node Jumping, Signaling, Assignment, Altering
2613 @@section Continuing at a Different Address
2616 @@item jump @@var{linenum}
2618 Resume execution at line number @@var{linenum}. Execution may stop
2619 immediately if there is a breakpoint there.
2621 The @@samp{jump} command does not change the current stack frame, or
2622 the stack pointer, or the contents of any memory location or any
2623 register other than the program counter. If line @@var{linenum} is in
2624 a different function from the one currently executing, the results may
2625 be wild if the two functions expect different patterns of arguments or
2626 of local variables. For this reason, the @@samp{jump} command requests
2627 confirmation if the specified line is not in the function currently
2628 executing. However, even wild results are predictable based on
2629 changing the program counter.
2631 @@item jump *@@var{address}
2632 Resume execution at the instruction at address @@var{address}.
2635 A similar effect can be obtained by storing a new value into the register
2636 @@samp{$pc}, but not exactly the same.
2643 specifies the address at which execution will resume, but does not resume
2644 execution. That does not happen until you use the @@samp{cont} command or a
2645 stepping command (@@pxref{Stepping}).
2647 @@node Signaling, Returning, Jumping, Altering
2648 @@section Giving the Program a Signal
2651 @@item signal @@var{signalnum}
2653 Resume execution where the program stopped, but give it immediately
2654 the signal number @@var{signalnum}.
2656 Alternatively, if @@var{signalnum} is zero, continue execution and give
2657 no signal. This is useful when the program has received a signal
2658 but you don't want the program to see that signal; the @@samp{cont} command
2659 would signal the program.
2662 @@node Returning,, Signaling, Altering
2663 @@section Returning from a Function
2665 @@cindex returning from a function
2667 You can make any function call return immediately, using the @@samp{return}
2670 First select the stack frame that you wish to return from
2671 (@@pxref{Selection}). Then type the @@samp{return} command. If you wish to
2672 specify the value to be returned, give that as an argument.
2674 This pops the selected stack frame (and any other frames inside of it),
2675 leaving its caller as the innermost remaining frame. That frame becomes
2676 selected. The specified value is stored in the registers used for
2677 returning values of functions.
2679 The @@samp{return} command does not resume execution; it leaves the program
2680 stopped in the state that would exist if the function had just returned.
2681 Contrast this with the @@samp{finish} command (@@pxref{Stepping}), which
2682 resumes execution @@i{until} the selected stack frame returns naturally.
2684 @@node Sequences, Emacs, Altering, Top
2685 @@chapter Canned Sequences of Commands
2687 GDB provides two ways to store sequences of commands for execution as a
2688 unit: user-defined commands and command files.
2691 * Define:: User-defined commands.
2692 * Command Files:: Command files.
2693 * Output:: Controlled output commands useful in
2694 user-defined commands and command files.
2697 @@node Define, Command Files, Sequences, Sequences
2698 @@section User-Defined Commands
2700 @@cindex user-defined commands
2701 A @@dfn{user-defined command} is a sequence of GDB commands to which you
2702 assign a new name as a command. This is done with the @@samp{define}
2706 @@item define @@var{commandname}
2708 Define a command named @@var{commandname}. If there is already a command
2709 by that name, you are asked to confirm that you want to redefine it.
2711 The definition of the command is made up of other GDB command lines,
2712 which are given following the @@samp{define} command. The end of these
2713 commands is marked by a line containing @@samp{end}.
2715 @@item document @@var{commandname}
2717 Give documentation to the user-defined command @@var{commandname}. The
2718 command @@var{commandname} must already be defined. This command reads
2719 lines of documentation just as @@samp{define} reads the lines of the
2720 command definition, ending with @@samp{end}. After the @@samp{document} command is finished,
2721 @@samp{help} on command @@var{commandname} will print the documentation
2724 You may use the @@samp{document} command again to change the
2725 documentation of a command. Redefining the command with @@samp{define}
2726 does not change the documentation.
2729 User-defined commands do not take arguments. When they are executed, the
2730 commands of the definition are not printed. An error in any command
2731 stops execution of the user-defined command.
2733 Commands that would ask for confirmation if used interactively proceed
2734 without asking when used inside a user-defined command. Many GDB commands
2735 that normally print messages to say what they are doing omit the messages
2736 when used in user-defined command.
2738 @@node Command Files, Output, Define, Sequences
2739 @@section Command Files
2741 @@cindex command files
2742 A command file for GDB is a file of lines that are GDB commands. Comments
2743 (lines starting with @@samp{#}) may also be included. An empty line in a
2744 command file does nothing; it does not mean to repeat the last command, as
2745 it would from the terminal.
2749 When GDB starts, it automatically executes its @@dfn{init files}, command
2750 files named @@file{.gdbinit}. GDB reads the init file (if any) in your home
2751 directory and then the init file (if any) in the current working
2752 directory. (The init files are not executed if the @@samp{-nx} option
2753 is given.) You can also request the execution of a command file with the
2754 @@samp{source} command:
2757 @@item source @@var{filename}
2759 Execute the command file @@var{filename}.
2762 The lines in a command file are executed sequentially. They are not
2763 printed as they are executed. An error in any command terminates execution
2764 of the command file.
2766 Commands that would ask for confirmation if used interactively proceed
2767 without asking when used in a command file. Many GDB commands that
2768 normally print messages to say what they are doing omit the messages
2769 when used in a command file.
2771 @@node Output,, Command Files, Sequences
2772 @@section Commands for Controlled Output
2774 During the execution of a command file or a user-defined command, the only
2775 output that appears is what is explicitly printed by the commands of the
2776 definition. This section describes three commands useful for generating
2777 exactly the output you want.
2780 @@item echo @@var{text}
2782 Print @@var{text}. Nonprinting characters can be included in
2783 @@var{text} using C escape sequences, such as @@samp{\n} to print a
2784 newline. @@b{No newline will be printed unless you specify one.}
2786 A backslash at the end of @@var{text} is ignored. It is useful for
2787 outputting a string ending in spaces, since trailing spaces are
2788 trimmed from all arguments. A backslash at the beginning preserves
2789 leading spaces in the same way, because @@samp{\ } as an escape
2790 sequence stands for a space. Thus, to print @@samp{ and foo = }, do
2796 @@item output @@var{expression}
2798 Print the value of @@var{expression} and nothing but that value: no
2799 newlines, no @@samp{$@@var{nn} = }. The value is not entered in the
2800 value history either. @@xref{Expressions} for more information
2803 @@item output/@@var{fmt} @@var{expression}
2804 Print the value of @@var{expression} in format @@var{fmt}.
2805 @@xref{Formats}, for more information.
2807 @@item printf @@var{string}, @@var{expressions}@@dots{}
2809 Print the values of the @@var{expressions} under the control of
2810 @@var{string}. The @@var{expressions} are separated by commas and may
2811 be either numbers or pointers. Their values are printed as specified
2812 by @@var{string}, exactly as if the program were to execute
2815 printf (@@var{string}, @@var{expressions}@@dots{});
2818 For example, you can print two values in hex like this:
2821 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
2824 The only backslash-escape sequences that you can use in the string are
2825 the simple ones that consist of backslash followed by a letter.
2828 @@node Emacs, Remote, Sequences, Top
2829 @@chapter Using GDB under GNU Emacs
2831 A special interface allows you to use GNU Emacs to view (and
2832 edit) the source files for the program you are debugging with
2835 To use this interface, use the command @@kbd{M-x gdb} in Emacs.
2836 Give the executable file you want to debug as an argument. This
2837 command starts a GDB process as a subprocess of Emacs, with input
2838 and output through a newly created Emacs buffer.
2840 Using this GDB process is just like using GDB normally except for two things:
2844 All ``terminal'' input and output goes through the Emacs buffer. This
2845 applies both to GDB commands and their output, and to the input and
2846 output done by the program you are debugging.
2848 This is useful because it means that you can copy the text of previous
2849 commands and input them again; you can even use parts of the output
2852 All the facilities of Emacs's Shell mode are available for this purpose.
2855 GDB displays source code through Emacs. Each time GDB displays a
2856 stack frame, Emacs automatically finds the source file for that frame
2857 and puts an arrow (@@samp{=>}) at the left margin of the current line.
2859 Explicit GDB @@samp{list} or search commands still produce output as
2860 usual, but you probably will have no reason to use them.
2863 In the GDB I/O buffer, you can use these special Emacs commands:
2867 Execute to another source line, like the GDB @@samp{step} command.
2870 Execute to next source line in this function, skipping all function
2871 calls, like the GDB @@samp{next} command.
2874 Execute one instruction, like the GDB @@samp{stepi} command.
2877 Move up one stack frame (and display that frame's source file in
2878 Emacs), like the GDB @@samp{up} command.
2881 Move down one stack frame (and display that frame's source file in
2882 Emacs), like the GDB @@samp{down} command. (This means that you cannot
2883 delete words in the usual fashion in the GDB buffer; I am guessing you
2884 won't often want to do that.)
2887 Execute until exit from the selected stack frame, like the GDB
2888 @@samp{finish} command.
2891 In any source file, the Emacs command @@kbd{C-x SPC} (@@code{gdb-break})
2892 tells GDB to set a breakpoint on the source line point is on.
2894 The source files displayed in Emacs are in ordinary Emacs buffers
2895 which are visiting the source files in the usual way. You can edit
2896 the files with these buffers if you wish; but keep in mind that GDB
2897 communicates with Emacs in terms of line numbers. If you add or
2898 delete lines from the text, the line numbers that GDB knows will cease
2899 to correspond properly to the code.
2901 @@node Remote, Commands, Emacs, Top
2902 @@chapter Remote Kernel Debugging
2904 GDB has a special facility for debugging a remote machine via a serial
2905 connection. This can be used for kernel debugging.
2907 The program to be debugged on the remote machine needs to contain a
2908 debugging device driver which talks to GDB over the serial line using the
2909 protocol described below. The same version of GDB that is used ordinarily
2910 can be used for this.
2913 * Remote Commands:: Commands used to start and finish remote debugging.
2916 For details of the communication protocol, see the comments in the GDB
2917 source file @@file{remote.c}.
2919 @@node Remote Commands,, Remote, Remote
2920 @@section Commands for Remote Debugging
2922 To start remote debugging, first run GDB and specify as an executable file
2923 the program that is running in the remote machine. This tells GDB how
2924 to find the program's symbols and the contents of its pure text. Then
2925 establish communication using the @@samp{attach} command with a device
2926 name rather than a pid as an argument. For example:
2933 if the serial line is connected to the device named @@file{/dev/ttyd}. This
2934 will stop the remote machine if it is not already stopped.
2936 Now you can use all the usual commands to examine and change data and to
2937 step and continue the remote program.
2939 To resume the remote program and stop debugging it, use the @@samp{detach}
2942 @@node Commands, Concepts, Remote, Top
2943 @@unnumbered Command Index
2947 @@node Concepts,, Commands, Top
2948 @@unnumbered Concept Index
2964 inferior. If you wish to evaluate a function simply for it's side
2965 affects, you may use the @@samp{set} command. @@xref{Assignment}.
2968 A condition is just a boolean expression in your programming language.
2969 A breakpoint with a condition evaluates the expression each time the
2970 program reaches it, and the program stops only if the condition is true.
2974 is a condition expression that will change @@code{x} as needed, then always
2975 have the value 0 so the program will not stop. Loss of input is avoided
2976 here because break conditions are evaluated without changing the terminal
2977 modes. When you want to have nontrivial conditions for performing the side
2978 effects, the operators @@samp{&&}, @@samp{||} and @@samp{?@@: @@dots{} :@@:} may be useful.
2981 Under Unix, breakpoints cannot be used in a program if any other process
2982 is running that program. Attempting to run or continue the program with
2983 a breakpoint in this case will cause GDB to stop it.
2987 address of a byte of memory.
2990 each time the program stops.
2993 saved in ``extended'' format, but all C programs expect to work with
3000 no signal. This may be useful when the program has received a signal
3001 and the @@samp{cont} command would allow the program to see that
3005 command definition. After the @@samp{document} command is finished,
3008 value history either.