diff options
Diffstat (limited to 'gdb/gdb.texinfo')
| -rw-r--r-- | gdb/gdb.texinfo | 2924 |
1 files changed, 2924 insertions, 0 deletions
diff --git a/gdb/gdb.texinfo b/gdb/gdb.texinfo new file mode 100644 index 0000000..db83964 --- /dev/null +++ b/gdb/gdb.texinfo @@ -0,0 +1,2924 @@ +\input texinfo +@setfilename ../info/gdb +@settitle GDB, The GNU Debugger +@ifinfo +This file documents the GNU debugger GDB. + +Copyright (C) 1988 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``Distribution'' and ``GDB General Public License'' are +included exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``Distribution'' and ``GDB General Public +License'' may be included in a translation approved by the author instead +of in the original English. +@end ifinfo + +@setchapternewpage odd +@settitle GDB Manual +@titlepage +@sp 6 +@center @titlefont{GDB Manual} +@sp 1 +@center The GNU Source-Level Debugger +@sp 4 +@center Third Edition, GDB version 3.1 +@sp 1 +@center January 1989 +@sp 5 +@center Richard M. Stallman +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``Distribution'' and ``GDB General Public License'' are +included exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``Distribution'' and ``GDB General Public +License'' may be included in a translation approved by the author instead +of in the original English. +@end titlepage +@page + +@node Top, Commands,, (DIR) +@unnumbered Summary of GDB + +The purpose of a debugger such as GDB is to allow you to execute another +program while examining what is going on inside it. We call the other +program ``your program'' or ``the program being debugged''. + +GDB can do four kinds of things (plus other things in support of these): + +@enumerate +@item +Start the program, specifying anything that might affect its behavior. + +@item +Make the program stop on specified conditions. + +@item +Examine what has happened, when the program has stopped, so that you +can see bugs happen. + +@item +Change things in the program, so you can correct the effects of one bug +and go on to learn about another without having to recompile first. +@end enumerate + +GDB can be used to debug programs written in C and C++. Pascal support +is being implemented, and Fortran support will be added when a GNU +Fortran compiler is written. + +@menu +* License:: The GDB General Public License gives you permission + to redistribute GDB on certain terms; and also + explains that there is no warranty. +* Input:: GDB command syntax and input conventions. +* Files:: Specifying files for GDB to operate on. +* Options:: GDB arguments and options. +* Compilation::Compiling your program so you can debug it. +* Running:: Running your program under GDB. +* Stopping:: Making your program stop. Why it may stop. What to do then. +* Stack:: Examining your program's stack. +* Source:: Examining your program's source files. +* Data:: Examining data in your program. +* Symbols:: Examining the debugger's symbol table. +* Altering:: Altering things in your program. +* Sequences:: Canned command sequences for repeated use. +* Emacs:: Using GDB through GNU Emacs. +* Remote:: Remote kernel debugging across a serial line. +* Commands:: Index of GDB commands. +* Concepts:: Index of GDB concepts. +@end menu + +@node License, Input, Top, Top +@unnumbered GDB General Public License +@center (Clarified 11 Feb 1988) + + The license agreements of most software companies keep you at the mercy +of those companies. By contrast, our general public license is intended to +give everyone the right to share GDB. To make sure that you get the rights +we want you to have, we need to make restrictions that forbid anyone to +deny you these rights or to ask you to surrender the rights. Hence this +license agreement. + + Specifically, we want to make sure that you have the right to give away +copies of GDB, that you receive source code or else can get it if you want +it, that you can change GDB or use pieces of it in new free programs, and +that you know you can do these things. + + To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute copies +of GDB, you must give the recipients all the rights that you have. You +must make sure that they, too, receive or can get the source code. And you +must tell them their rights. + + Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for GDB. If GDB is modified by someone else +and passed on, we want its recipients to know that what they have is not +what we distributed, so that any problems introduced by others will not +reflect on our reputation. + + Therefore we (Richard Stallman and the Free Software Foundation, +Inc.) make the following terms which say what you must do to be +allowed to distribute or change GDB. + +@unnumberedsec Copying Policies + +@enumerate +@item +You may copy and distribute verbatim copies of GDB source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each file a valid copyright notice ``Copyright +@copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year +is appropriate); keep intact the notices on all files that +refer to this License Agreement and to the absence of any warranty; and +give any other recipients of the GDB program a copy of this License +Agreement along with the program. You may charge a distribution fee +for the physical act of transferring a copy. + +@item +You may modify your copy or copies of GDB source code or any portion +of it, and copy and distribute such modifications under the terms of +Paragraph 1 above, provided that you also do the following: + +@itemize @bullet +@item +cause the modified files to carry prominent notices stating +that you changed the files and the date of any change; and + +@item +cause the whole of any work that you distribute or publish, that +in whole or in part contains or is a derivative of GDB or any +part thereof, to be licensed at no charge to all third parties on +terms identical to those contained in this License Agreement +(except that you may choose to grant more extensive warranty +protection to some or all third parties, at your option). + +@item +if the modified program serves as a debugger, cause it, when +started running in the simplest and usual way, to print an +announcement including a valid copyright notice ``Copyright +@copyright{} 1988 Free Software Foundation, Inc.'' (or with the +year that is appropriate), saying that there is no warranty (or +else, saying that you provide a warranty) and that users may +redistribute the program under these conditions, and telling the +user how to view a copy of this License Agreement. + +@item +You may charge a distribution fee for the physical act of +transferring a copy, and you may at your option offer warranty +protection in exchange for a fee. +@end itemize + +Mere aggregation of another unrelated program with this program (or its +derivative) on a volume of a storage or distribution medium does not bring +the other program under the scope of these terms. + +@item +You may copy and distribute GDB (or a portion or derivative of it, +under Paragraph 2) in object code or executable form under the terms +of Paragraphs 1 and 2 above provided that you also do one of the +following: + +@itemize @bullet +@item +accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with a written offer, valid for at least three +years, to give any third party free (except for a nominal +shipping charge) a complete machine-readable copy of the +corresponding source code, to be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with the information you received as to where the +corresponding source code may be obtained. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form alone.) +@end itemize + +For an executable file, complete source code means all the source code +for all modules it contains; but, as a special exception, it need not +include source code for modules which are standard libraries that +accompany the operating system on which the executable file runs. + +@item +You may not copy, sublicense, distribute or transfer GDB except as +expressly provided under this License Agreement. Any attempt +otherwise to copy, sublicense, distribute or transfer GDB is void and +your rights to use GDB under this License agreement shall be +automatically terminated. However, parties who have received computer +software programs from you with this License Agreement will not have +their licenses terminated so long as such parties remain in full +compliance. + +@item +If you wish to incorporate parts of GDB into other free programs whose +distribution conditions are different, write to the Free Software +Foundation. We have not yet worked out a simple rule that can be +stated here, but we will often permit this. We will be guided by the +two goals of preserving the free status of all derivatives our free +software and of promoting the sharing and reuse of software. +@end enumerate + +@iftex +@vfil +@eject +@end iftex +@unnumberedsec NO WARRANTY + + BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY +NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT +WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC, +RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB ``AS IS'' +WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, +BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY +AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GDB +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY +SERVICING, REPAIR OR CORRECTION. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE +FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY +MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER +SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR +INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA +BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A +FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY +FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY +OTHER PARTY. + +@node Input, Files, License, Top +@chapter GDB Input Conventions + +GDB is invoked with the shell command @samp{gdb}. Once started, it reads +commands from the terminal until you tell it to exit. + +A GDB command is a single line of input. There is no limit on how long +it can be. It starts with a command name, which is followed by arguments +whose meaning depends on the command name. Some command names do not +allow arguments. + +GDB command names may always be abbreviated if the abbreviation is +unambiguous. Sometimes even ambiguous abbreviations are allowed; for +example, @samp{s} is specially defined as equivalent to @samp{step} +even though there are other commands whose names start with @samp{s}. +Possible command abbreviations are often stated in the documentation +of the individual commands. + +A blank line as input to GDB means to repeat the previous command verbatim. +Certain commands do not allow themselves to be repeated this way; these are +commands for which unintentional repetition might cause trouble and which +you are unlikely to want to repeat. Certain others (@samp{list} and +@samp{x}) act differently when repeated because that is more useful. + +A line of input starting with @samp{#} is a comment; it does nothing. +This is useful mainly in command files (@xref{Command Files}). + +Occasionally it is useful to execute a shell command from within gdb. +This can be done with the @samp{shell} command, or the shell escape +character @samp{!}. + +@table @code +@item shell @var{shell command string} +@kindex shell +@item !@var{shell command string} +@kindex ! +@cindex shell escape +Directs GDB to invoke an inferior shell to execute @samp{shell command string}. +The environmental variable @samp{SHELL} is used if it exists, otherwise gdb +uses @samp{/bin/sh}. +@end table + +GDB @dfn{prompts} for commands with a string that is normally @samp{(gdb)}. +When debugging GDB with GDB, it is useful to change the prompt in one of +the GDBs so that you can distinguish them. This can be done with the +@samp{set prompt} command. + +@table @code +@item set prompt @var{newprompt} +@kindex set prompt +Directs GDB to use @var{newprompt} as its prompt string henceforth. +@end table + +@cindex exiting GDB +@kindex quit +To exit GDB, use the @samp{quit} command (abbreviated @samp{q}). +@kbd{Ctrl-c} will not exit from GDB, but rather will terminate the action +of any GDB command that is in progress and return to GDB command level. +It is safe to type @kbd{Ctrl-c} at any time because GDB does not allow +it to take effect until a time when it is safe. + +@node Files, Options, Input, Top +@chapter Specifying GDB's Files + +@cindex core dump file +@cindex executable file +@cindex symbol table +GDB needs to know the filename of the program to be debugged. To debug a +core dump of a previous run, GDB must be told the filename of the core +dump. + +@menu +* Arguments: File Arguments. Specifying files with arguments + (when you start GDB). +* Commands: File Commands. Specifying files with GDB commands. +@end menu + +@node File Arguments, File Commands, Files, Files +@section Specifying Files with Arguments + +The usual way to specify the executable and core dump file names is with +two command arguments given when you start GDB. The first argument is used +as the file for execution and symbols, and the second argument (if any) is +used as the core dump file name. Thus, + +@example +gdb progm core +@end example + +@noindent +specifies @file{progm} as the executable program and @file{core} as a core +dump file to examine. (You do not need to have a core dump file if what +you plan to do is debug the program interactively.) + +@xref{Options}, for full information on command options and arguments for +GDB. + +@node File Commands,, File Arguments, Files +@section Specifying Files with Commands + +Usually you specify the files for GDB to work with by giving arguments when +you invoke GDB. But occasionally it is necessary to change to a different +file during a GDB session. Or you may run GDB and forget to specify the +files you want to use. In these situations the GDB commands to specify new +files are useful. + +@table @code +@item exec-file @var{filename} +@kindex exec-file +Specify that the program to be run is found in @var{filename}. If you +do not specify a directory and the file is not found in GDB's working +directory, GDB will use the environment variable @samp{PATH} as a list +of directories to search, just as the shell does when looking for a +program to run. + +@item symbol-file @var{filename} +@kindex symbol-file +Read symbol table information from file @var{filename}. @samp{PATH} +is searched when necessary. Most of the time you will use both the +@samp{exec-file} and @samp{symbol-file} commands on the same file. + +@samp{symbol-file} with no argument clears out GDB's symbol table. + +@item core-file @var{filename} +@kindex core-file +Specify the whereabouts of a core dump file to be used as the +``contents of memory''. Note that the core dump contains only the +writable parts of memory; the read-only parts must come from the +executable file. + +@samp{core-file} with no argument specifies that no core file is +to be used. + +@item add-file @var{filename} @var{address} +@kindex add-file +The @samp{add-file} command takes two arguments, a file name, and the +address at which that file has been (or should be) dynamically loaded. +GDB will then treat that file as though it had always been dynamically +linked, and provide the user with all the normal GDB features, including +symbolic debugging. + +With the @samp{add-file} command, it is possible to debug code which was +not present in the initial load image of the program under test. +Suppose you have a program which can, while running, dynamically link a +program fragment into its address space. One program which does this is +KCL, a free common lisp implementation. The fragment will be loaded +into the main program's address space at some address, and the main +program can then call functions within the fragment by calculating (or +otherwise obtaining) their addresses. + +@item kill +@kindex kill +Cancel running the program under GDB. This could be used if you wish +to debug a core dump instead. GDB ignores any core dump file if it is +actually running the program, so the @samp{kill} command is the only +sure way to go back to using the core dump file. + +@item info files +@kindex info files +Print the names of the executable and core dump files currently in +use by GDB, and the file from which symbols were loaded. +@end table + +While all three file-specifying commands allow both absolute and relative +file names as arguments, GDB always converts the file name to an absolute +one and remembers it that way. + +The @samp{symbol-file} command causes GDB to forget the contents of its +convenience variables, the value history, and all breakpoints and +auto-display expressions. This is because they may contain pointers to the +internal data recording symbols and data types, which are part of the old +symbol table data being discarded inside GDB. + +@node Options, Compilation, Files, Top +@chapter Options and Arguments for GDB + +When you invoke GDB, you can pass commands telling it what files to +operate on and what other things to do. + +@menu +* Mode Options:: Options controlling modes of operation. +* File Options:: Options to specify files (executable, coredump, commands) +* Other Arguments:: Any other arguments without options + also specify files. +@end menu + +@node Mode Options, File Options, Options, Options +@section Mode Options + +@table @samp +@item -nx +Do not execute commands from the init files @file{.gdbinit}. +Normally, the commands in these files are executed after all the +command options and arguments have been processed. @xref{Command +Files}. + +@item -q +``Quiet''. Do not print the usual introductory messages. + +@item -batch +Run in batch mode. Exit with code 1 after processing all the command +files specified with @samp{-x} (and @file{.gdbinit}, if not +inhibited). Exit also if, due to an error, GDB would otherwise +attempt to read a command from the terminal. + +@item -fullname +This option is used when Emacs runs GDB as a subprocess. It tells GDB +to output the full file name and line number in a standard, +recognizable fashion each time a stack frame is displayed (which +includes each time the program stops). This recognizable format looks +like two @samp{\032} characters, followed by the filename, line number +and character position separated by colons, and a newline. The +Emacs-to-GDB interface program uses the two @samp{\032} characters as +a signal to display the source code for the frame. +@end table + +@node File Options, Other Arguments, Mode Options, Options +@section File-specifying Options + +All the options and command line arguments given are processed +in sequential order. The order makes a difference when the +@samp{-x} command is used. + +@table @samp +@item -s @var{file} +Read symbol table from file @var{file}. + +@item -e @var{file} +Use file @var{file} as the executable file to execute when +appropriate, and for examining pure data in conjunction with a core +dump. + +@item -se @var{file} +Read symbol table from file @var{file} and use it as the executable +file. + +@item -c @var{file} +Use file @var{file} as a core dump to examine. + +@item -x @var{file} +Execute GDB commands from file @var{file}. + +@item -d @var{directory} +Add @var{directory} to the path to search for source files. +@end table + +@node Other Arguments,, File Options, Options +@section Other Arguments + +If there are arguments to GDB that are not options or associated with +options, the first one specifies the symbol table and executable file name +(as if it were preceded by @samp{-se}) and the second one specifies a core +dump file name (as if it were preceded by @samp{-c}). + +@node Compilation, Running, Options, Top +@chapter Compiling Your Program for Debugging + +In order to debug a program effectively, you need to ask for debugging +information when you compile it. This information in the object file +describes the data type of each variable or function and the correspondence +between source line numbers and addresses in the executable code. + +To request debugging information, specify the @samp{-g} option when you run +the compiler. + +The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options +together. This means that you cannot ask for optimization if you ask for +debugger information. + +The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it +possible to debug optimized code. We recommend that you @emph{always} use +@samp{-g} whenever you compile a program. You may think the program is +correct, but there's no sense in pushing your luck. + +If you are using the GNU C compiler, the GNU assembler and the GNU linker, +you can choose between two formats of debugging information: the standard +Unix format, which is what you get with @samp{-g}, and GDB's own format, +which you request by using @samp{-gg} instead of @samp{-g}. This stores +debugging information in the executable file in a format much like that +which is used inside GDB. This has these advantages and disadvantages: + +@itemize @bullet +@item +GDB can read @samp{-gg} format more than twice as fast as Unix +@samp{-g} format. + +@item +The @samp{-gg} format uses much more disk space than Unix format. + +@item +The Unix debuggers can understand only Unix format, so you cannot use +Unix source-level debuggers if you compile with @samp{-gg}. (The +@code{adb} debugger works with either format; it does not use this +information in any case.) +@end itemize + +@node Running, Stopping, Compilation, Top +@chapter Running Your Program Under GDB + +@cindex running +@kindex run +To start your program under GDB, use the @samp{run} command. The program +must already have been specified using the @samp{exec-file} command or with +an argument to GDB (@pxref{Files}); what @samp{run} does is create an +inferior process, load the program into it, and set it in motion. + +The execution of a program is affected by certain information it receives +from its superior. GDB provides ways to specify them, which you must do +@i{before} starting the program. (You can change them after starting the +program, but such changes do not affect the program unless you start it +over again.) + +@table @asis +@item The @i{arguments.} +You specify the arguments to give the program as the arguments of the +@samp{run} command. + +@item The @i{environment.} +The program normally inherits its environment from GDB, but you can +use the GDB commands @samp{set environment} and +@samp{unset environment} to change parts of the environment that will +be given to the program.@refill + +@item The @i{working directory.} +The program inherits its working directory from GDB. You can set GDB's +working directory with the @samp{cd} command in GDB. +@end table + +After the @samp{run} command, the debugger does nothing but wait for your +program to stop. @xref{Stopping}. + +Note that once your program has been started by the @samp{run} command, +you may evaluate expressions that involve calls to functions in the +inferior. @xref{Expressions}. If you wish to evaluate a function +simply for it's side affects, you may use the @samp{set} command. +@xref{Assignment}. + +@menu +* Arguments:: Specifying the arguments for your program. +* Environment:: Specifying the environment for your program. +* Working Directory:: Specifying the working directory for giving + to your program when it is run. +* Input/Output:: Specifying the program's standard input and output. +* Attach:: Debugging a process started outside GDB. +@end menu + +@node Arguments, Environment, Running, Running +@section Your Program's Arguments + +@cindex arguments (to your program) +You specify the arguments to give the program as the arguments of the +@samp{run} command. They are passed to a shell, which expands wildcard +characters and performs redirection of I/O, and thence to the program. + +@samp{run} with no arguments uses the same arguments used by the previous +@samp{run}. + +@kindex set args +The command @samp{set args} can be used to specify the arguments to be used +the next time the program is run. If @samp{set args} has no arguments, it +means to use no arguments the next time the program is run. If you have +run your program with arguments and want to run it again with no arguments, +this is the only way to do so. + +@node Environment, Working Directory, Arguments, Running +@section Your Program's Environment + +@cindex environment (of your program) +The @dfn{environment} consists of a set of @dfn{environment variables} and +their values. Environment variables conventionally record such things as +your user name, your home directory, your terminal type, and your search +path for programs to run. Usually you set up environment variables with +the shell and they are inherited by all the other programs you run. When +debugging, it can be useful to try running the program with different +environments without having to start the debugger over again. + +@table @code +@item info environment @var{varname} +@kindex info environment +Print the value of environment variable @var{varname} to be given to +your program when it is started. This command can be abbreviated +@samp{i env @var{varname}}. + +@item info environment +Print the names and values of all environment variables to be given to +your program when it is started. This command can be abbreviated +@samp{i env}. + +@item set environment @var{varname} @var{value} +@item set environment @var{varname} = @var{value} +@kindex set environment +Sets environment variable @var{varname} to @var{value}, for your program +only, not for GDB itself. @var{value} may be any string; the values of +environment variables are just strings, and any interpretation is +supplied by your program itself. The @var{value} parameter is optional; +if it is eliminated, the variable is set to a null value. This command +can be abbreviated as short as @samp{set e}. + +@item delete environment @var{varname} +@kindex delete environment +@item unset environment @var{varname} +@kindex unset environment +Remove variable @var{varname} from the environment to be passed to +your program. This is different from @samp{set env @var{varname} =} +because @samp{delete environment} makes a variable not be defined at +all, which is distinguishable from an empty value. This command can +be abbreviated @samp{d e}. +@end table + +@node Working Directory, Input/Output, Environment, Running +@section Your Program's Working Directory + +@cindex working directory (of your program) +Each time you start your program with @samp{run}, it inherits its working +directory from the current working directory of GDB. GDB's working +directory is initially whatever it inherited from its superior, but you can +specify the working directory for GDB with the @samp{cd} command. + +The GDB working directory also serves as a default for the commands +that specify files for GDB to operate on. @xref{Files}. + +@table @code +@item cd @var{directory} +@kindex cd +Set GDB's working directory to @var{directory}. + +@item pwd +@kindex pwd +Print GDB's working directory. +@end table + +@node Input/Output, Attach, Working Directory, Running +@section Your Program's Input and Output + +@cindex redirection +@cindex controlling terminal +By default, the program you run under GDB does input and output to the same +terminal that GDB uses. + +You can redirect the program's input and/or output using @samp{sh}-style +redirection commands in the @samp{run} command. For example, + +@example +run > outfile +@end example + +@noindent +starts the program, diverting its output to the file @file{outfile}. + +@kindex tty +Another way to specify where the program should do input and output is with +the @samp{tty} command. This command accepts a file name as argument, and +causes this file to be the default for future @samp{run} commands. It also +resets the controlling terminal for future @samp{run} commands. For +example, + +@example +tty /dev/ttyb +@end example + +@noindent +directs that processes started with subsequent @samp{run} commands default +to do input and output on the terminal @file{/dev/ttyb} and sets the +controlling terminal to @file{/dev/ttyb}. An explicit redirection in +@samp{run} overrides the @samp{tty} command's effect on input/output +redirection. + +When you use the @samp{tty} command or redirect input in the @samp{run} +command, the @emph{input for your program} comes from the specified file, +but the input for GDB still comes from your terminal. + +@node Attach,, Input/Output, Running +@section Debugging an Already-Running Process +@kindex detach +@kindex attach +@cindex attach + +Some operating systems (in particular, Sun) allow GDB to begin debugging an +already-running process that was started outside of GDB. To do this you +must use the @samp{attach} command instead of the @samp{run} command. + +The @samp{attach} command requires one argument, which is the process-id of +the process you want to debug. (The usual way to find out the process-id +of the process is with the @samp{ps} utility.) + +The first thing GDB does after arranging to debug the process is to stop +it. You can examine and modify an attached process with all the GDB +commands that ordinarily available when you start processes with +@samp{run}. You can insert breakpoints; you can step and continue; you +can modify storage. If you would rather the process continue running, +use the @samp{continue} command after attaching. + +When you are finished debugging the attached process, you can use the +@samp{detach} command to release it from GDB's control. Detaching +the process continues its execution. After the @samp{detach} command, +that process and GDB become completely independent once more, and you +are ready to @samp{attach} another process or start one with @samp{run}. + +If you exit GDB or use the @samp{run} command while you have an attached +process, you kill that process. You will be asked for confirmation if you +try to do either of these things. + +@node Stopping, Stack, Running, Top +@chapter Stopping and Continuing + +When you run a program normally, it runs until exiting. The purpose +of using a debugger is so that you can stop it before that point; +or so that if the program runs into trouble you can find out why. + +@menu +* Signals:: Fatal signals in your program just stop it; + then you can use GDB to see what is going on. +* Breakpoints:: Breakpoints let you stop your program when it + reaches a specified point in the code. +* Continuing:: Resuming execution until the next signal or breakpoint. +* Stepping:: Stepping runs the program a short distance and + then stops it wherever it has come to. +@end menu + +@node Signals, Breakpoints, Stopping, Stopping +@section Signals + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each kind +a name and a number. For example, @code{SIGINT} is the signal a program +gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program +gets from referencing a place in memory far away from all the areas in use; +@code{SIGALRM} occurs when the alarm clock timer goes off (which happens +only if the program has requested an alarm). + +Some signals, including @code{SIGALRM}, are a normal part of the +functioning of the program. Others, such as @code{SIGSEGV}, indicate +errors; these signals are @dfn{fatal} (kill the program immediately) if the +program has not specified in advance some other way to handle the signal. +@code{SIGINT} does not indicate an error in the program, but it is normally +fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program. + +GDB has the ability to detect any occurrence of a signal in the program +running under GDB's control. You can tell GDB in advance what to do for +each kind of signal. + +Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM} +(so as not to interfere with their role in the functioning of the program) +but to stop the program immediately whenever an error signal happens. +You can change these settings with the @samp{handle} command. You must +specify which signal you are talking about with its number. + +@table @code +@item info signal +@kindex info signal +Print a table of all the kinds of signals and how GDB has been told to +handle each one. You can use this to see the signal numbers of all +the defined types of signals. + +@item handle @var{signalnum} @var{keywords}@dots{} +@kindex handle +Change the way GDB handles signal @var{signalnum}. The @var{keywords} +say what change to make. +@end table + +To use the @samp{handle} command you must know the code number of the +signal you are concerned with. To find the code number, type @samp{info +signal} which prints a table of signal names and numbers. + +The keywords allowed by the handle command can be abbreviated. Their full +names are + +@table @code +@item stop +GDB should stop the program when this signal happens. This implies +the @samp{print} keyword as well. + +@item print +GDB should print a message when this signal happens. + +@item nostop +GDB should not stop the program when this signal happens. It may +still print a message telling you that the signal has come in. + +@item noprint +GDB should not mention the occurrence of the signal at all. This +implies the @samp{nostop} keyword as well. + +@item pass +GDB should allow the program to see this signal; the program will be +able to handle the signal, or may be terminated if the signal is fatal +and not handled. + +@item nopass +GDB should not allow the program to see this signal. +@end table + +When a signal has been set to stop the program, the program cannot see the +signal until you continue. It will see the signal then, if @samp{pass} is +in effect for the signal in question @i{at that time}. In other words, +after GDB reports a signal, you can use the @samp{handle} command with +@samp{pass} or @samp{nopass} to control whether that signal will be seen by +the program when you later continue it. + +You can also use the @samp{signal} command to prevent the program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. @xref{Signaling}. + +@node Breakpoints, Continuing, Signals, Stopping +@section Breakpoints + +@cindex breakpoints +A @dfn{breakpoint} makes your program stop whenever a certain point in the +program is reached. You set breakpoints explicitly with GDB commands, +specifying the place where the program should stop by line number, function +name or exact address in the program. You can add various other conditions +to control whether the program will stop. + +Each breakpoint is assigned a number when it is created; these numbers are +successive integers starting with 1. In many of the commands for controlling +various features of breakpoints you use the breakpoint number to say which +breakpoint you want to change. Each breakpoint may be @dfn{enabled} or +@dfn{disabled}; if disabled, it has no effect on the program until you +enable it again. + +@kindex info break +@kindex $_ +The command @samp{info break} prints a list of all breakpoints set and not +cleared, showing their numbers, where in the program they are, and any +special features in use for them. Disabled breakpoints are included in the +list, but marked as disabled. @samp{info break} with a breakpoint number +as argument lists only that breakpoint. The convenience variable @samp{$_} +and the default examining-address for the @samp{x} command are set to the +address of the last breakpoint listed (@pxref{Memory}). + +@menu +* Set Breaks:: How to establish breakpoints. +* Clear Breaks:: How to remove breakpoints no longer needed. +* Disabling:: How to disable breakpoints (turn them off temporarily). +* Conditions:: Making extra conditions on whether to stop. +* Break Commands:: Commands to be executed at a breakpoint. +* Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do. +@end menu + +@node Set Breaks, Clear Breaks, Breakpoints, Breakpoints +@subsection Setting Breakpoints + +@kindex break +Breakpoints are set with the @samp{break} command (abbreviated @samp{b}). +You have several ways to say where the breakpoint should go. + +@table @code +@item break @var{function} +Set a breakpoint at entry to function @var{function}. + +@item break @var{linenum} +Set a breakpoint at line @var{linenum} in the current source file. +That file is the last file whose source text was printed. This +breakpoint will stop the program just before it executes any of the +code on that line. + +@item break @var{filename}:@var{linenum} +Set a breakpoint at line @var{linenum} in source file @var{filename}. + +@item break @var{filename}:@var{function} +Set a breakpoint at entry to function @var{function} found in file +@var{filename}. Specifying a filename as well as a function name is +superfluous except when multiple files contain similarly named +functions. + +@item break *@var{address} +Set a breakpoint at address @var{address}. You can use this to set +breakpoints in parts of the program which do not have debugging +information or source files. + +@item break +Set a breakpoint at the next instruction to be executed in the selected +stack frame (@pxref{Stack}). In any selected frame but the innermost, +this will cause the program to stop as soon as control returns to that +frame. This is equivalent to a @samp{finish} command in the frame +inside the selected frame. If this is done in the innermost frame gdb +will stop the next time it reaches the current location; this may be +useful inside of loops. It does not stop at this breakpoint immediately +upon continuation of the program since no code would be executed if it +did. + +@item break @dots{} if @var{cond} +Set a breakpoint with condition @var{cond}; evaluate the expression +@var{cond} each time the breakpoint is reached, and stop only if the +value is nonzero. @samp{@dots{}} stands for one of the possible +arguments described above (or no argument) specifying where to break. +@xref{Conditions}, for more information on breakpoint conditions. + +@item tbreak @var{args} +@kindex tbreak +Set a breakpoint enabled only for one stop. @var{args} are the +same as in the @samp{break} command, and the breakpoint is set in the same +way, but the breakpoint is automatically @dfn{disabled} the first time it +is hit. +@end table + +GDB allows you to set any number of breakpoints at the same place in the +program. There is nothing silly or meaningless about this. When the +breakpoints are conditional, this is even useful (@pxref{Conditions}). + +@node Clear Breaks, Disabling, Set Breaks, Breakpoints +@subsection Clearing Breakpoints + +@cindex clear breakpoint +@cindex delete breakpoints +It is often necessary to eliminate a breakpoint once it has done its job +and you no longer want the program to stop there. This is called +@dfn{clearing} or @samp{deleting} the breakpoint. A breakpoint that +has been cleared no longer exists in any sense. + +With the @samp{clear} command you can clear breakpoints according to where +they are in the program. With the @samp{delete} command you can clear +individual breakpoints by specifying their breakpoint numbers. + +@b{It is not necessary to clear a breakpoint to proceed past it.} GDB +automatically ignores breakpoints in the first instruction to be executed +when you continue execution at the same address where the program stopped. + +@table @code +@item clear +@kindex clear +Clear any breakpoints at the next instruction to be executed in the +selected stack frame (@pxref{Selection}). When the innermost frame +is selected, this is a good way to clear a breakpoint that the program +just stopped at. + +@item clear @var{function} +@itemx clear @var{filename}:@var{function} +Clear any breakpoints set at entry to the function @var{function}. + +@item clear @var{linenum} +@item clear @var{filename}:@var{linenum} +Clear any breakpoints set at or within the code of the specified line. + +@item delete @var{bnums}@dots{} +@kindex delete +Delete the breakpoints of the numbers specified as arguments. +A breakpoint deleted is forgotten completely. +@end table + +@node Disabling, Conditions, Clear Breaks, Breakpoints +@subsection Disabling Breakpoints + +@cindex disabled breakpoints +@cindex enabled breakpoints +Rather than clearing a breakpoint, you might prefer to @dfn{disable} it. +This makes the breakpoint inoperative as if it had been cleared, but +remembers the information on the breakpoint so that you can @dfn{enable} +it again later. + +You disable and enable breakpoints with the @samp{enable} and +@samp{disable} commands, specifying one or more breakpoint numbers as +arguments. Use @samp{info break} to print a list of breakpoints if you +don't know which breakpoint numbers to use. + +A breakpoint can have any of four different states of enablement: + +@itemize @bullet +@item +Enabled. The breakpoint will stop the program. A breakpoint made +with the @samp{break} command starts out in this state. +@item +Disabled. The breakpoint has no effect on the program. +@item +Enabled once. The breakpoint will stop the program, but +when it does so it will become disabled. A breakpoint made +with the @samp{tbreak} command starts out in this state. +@item +Enabled for deletion. The breakpoint will stop the program, but +immediately after it does so it will be deleted permanently. +@end itemize + +You change the state of enablement of a breakpoint with the following +commands: + +@table @code +@item disable breakpoints @var{bnums}@dots{} +@kindex disable breakpoints +@item disable @var{bnums}@dots{} +@kindex disable +Disable the specified breakpoints. A disabled breakpoint has no +effect but is not forgotten. All options such as ignore-counts, +conditions and commands are remembered in case the breakpoint is +enabled again later. + +@item enable breakpoints @var{bnums}@dots{} +@kindex enable breakpoints +@item enable @var{bnums}@dots{} +@kindex enable +Enable the specified breakpoints. They become effective once again in +stopping the program, until you specify otherwise. + +@item enable breakpoints once @var{bnums}@dots{} +@item enable once @var{bnums}@dots{} +Enable the specified breakpoints temporarily. Each will be disabled +again the next time it stops the program (unless you have used one of +these commands to specify a different state before that time comes). + +@item enable breakpoints delete @var{bnums}@dots{} +@item enable delete @var{bnums}@dots{} +Enable the specified breakpoints to work once and then die. Each of +the breakpoints will be deleted the next time it stops the program +(unless you have used one of these commands to specify a different +state before that time comes). +@end table + +Aside from the automatic disablement or deletion of a breakpoint when it +stops the program, which happens only in certain states, the state of +enablement of a breakpoint changes only when one of the commands above +is used. + +@node Conditions, Break Commands, Disabling, Breakpoints +@subsection Break Conditions + +@cindex conditions +The simplest sort of breakpoint breaks every time the program reaches a +specified place. You can also specify a @dfn{condition} for a breakpoint. +A condition is just a boolean expression in your programming language +(@xref{Expressions}). A breakpoint with a condition evaluates the +expression each time the program reaches it, and the program stops +only if the condition is true. + +Break conditions may have side effects, and may even call functions in your +program. These may sound like strange things to do, but their effects are +completely predictable unless there is another enabled breakpoint at the +same address. (In that case, GDB might see the other breakpoint first and +stop the program without checking the condition of this one.) Note that +breakpoint commands are usually more convenient and flexible for the +purpose of performing side effects when a breakpoint is reached +(@pxref{Break Commands}). + +Break conditions can be specified when a breakpoint is set, by using +@samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}. +They can also be changed at any time with the @samp{condition} command: + +@table @code +@item condition @var{bnum} @var{expression} +@kindex condition +Specify @var{expression} as the break condition for breakpoint number +@var{bnum}. From now on, this breakpoint will stop the program only if +the value of @var{expression} is true (nonzero, in C). @var{expression} +is not evaluated at the time the @samp{condition} command is given. +@xref{Expressions}. + +@item condition @var{bnum} +Remove the condition from breakpoint number @var{bnum}. It becomes +an ordinary unconditional breakpoint. +@end table + +@cindex ignore count (of breakpoint) +A special feature is provided for one kind of condition: to prevent the +breakpoint from doing anything until it has been reached a certain number +of times. This is done with the @dfn{ignore count} of the breakpoint. +When the program reaches a breakpoint whose ignore count is positive, then +instead of stopping, it just decrements the ignore count by one and +continues. + +@table @code +@item ignore @var{bnum} @var{count} +@kindex ignore +Set the ignore count of breakpoint number @var{bnum} to @var{count}. +The next @var{count} times the breakpoint is reached, it will not stop. + +To make the breakpoint stop the next time it is reached, specify +a count of zero. + +@item cont @var{count} +Continue execution of the program, setting the ignore count of the +breakpoint that the program stopped at to @var{count} minus one. +Continuing through the breakpoint does not itself count as one of +@var{count}. Thus, the program will not stop at this breakpoint until the +@var{count}'th time it is hit. + +This command is allowed only when the program stopped due to a +breakpoint. At other times, the argument to @samp{cont} is ignored. +@end table + +If a breakpoint has a positive ignore count and a condition, the condition +is not checked. Once the ignore count reaches zero, the condition will +start to be checked. + +Note that you could achieve the effect of the ignore count with a condition +such as @samp{$foo-- <= 0} using a debugger convenience variable that is +decremented each time. That is why the ignore count is considered a +special case of a condition. @xref{Convenience Vars}. + +@node Break Commands, Error in Breakpoints, Conditions, Breakpoints +@subsection Commands Executed on Breaking + +@cindex breakpoint commands +You can give any breakpoint a series of commands to execute when the +program stops due to that breakpoint. For example, you might want to +print the values of certain expressions, or enable other breakpoints. + +@table @code +@item commands @var{bnum} +Specify commands for breakpoint number @var{bnum}. The commands +themselves appear on the following lines. Type a line containing just +@samp{end} to terminate the commands. + +To remove all commands from a breakpoint, use the command +@samp{commands} and follow it immediately by @samp{end}; that is, give +no commands. + +With no arguments, @samp{commands} refers to the last breakpoint set. +@end table + +It is possible for breakpoint commands to start the program up again. +Simply use the @samp{cont} command, or @samp{step}, or any other command +to resume execution. However, any remaining breakpoint commands are +ignored. When the program stops again, GDB will act according to why +that stop took place. + +@kindex silent +If the first command specified is @samp{silent}, the usual message about +stopping at a breakpoint is not printed. This may be desirable for +breakpoints that are to print a specific message and then continue. +If the remaining commands too print nothing, you will see no sign that +the breakpoint was reached at all. @samp{silent} is not really a command; +it is meaningful only at the beginning of the commands for a breakpoint. + +The commands @samp{echo} and @samp{output} that allow you to print precisely +controlled output are often useful in silent breakpoints. @xref{Output}. + +For example, here is how you could use breakpoint commands to print the +value of @code{x} at entry to @code{foo} whenever it is positive. We +assume that the newly created breakpoint is number 4; @samp{break} will +print the number that is assigned. + +@example +break foo if x>0 +commands 4 +silent +echo x is\040 +output x +echo \n +cont +end +@end example + +One application for breakpoint commands is to correct one bug so you can +test another. Put a breakpoint just after the erroneous line of code, give +it a condition to detect the case in which something erroneous has been +done, and give it commands to assign correct values to any variables that +need them. End with the @samp{cont} command so that the program does not +stop, and start with the @samp{silent} command so that no output is +produced. Here is an example: + +@example +break 403 +commands 5 +silent +set x = y + 4 +cont +end +@end example + +One deficiency in the operation of automatically continuing breakpoints +under Unix appears when your program uses raw mode for the terminal. +GDB switches back to its own terminal modes (not raw) before executing +commands, and then must switch back to raw mode when your program is +continued. This causes any pending terminal input to be lost. + +In the GNU system, this will be fixed by changing the behavior of +terminal modes. + +Under Unix, when you have this problem, you might be able to get around +it by putting your actions into the breakpoint condition instead of +commands. For example + +@example +condition 5 (x = y + 4), 0 +@end example + +@noindent +is a condition expression (@xref{Expressions}) that will change @code{x} +as needed, then always have the value 0 so the program will not stop. +Loss of input is avoided here because break conditions are evaluated +without changing the terminal modes. When you want to have nontrivial +conditions for performing the side effects, the operators @samp{&&}, +@samp{||} and @samp{?@: @dots{} :@:} may be useful. + +@node Error in Breakpoints,, Break Commands, Breakpoints +@subsection ``Cannot Insert Breakpoints'' Error + +Under some Unix systems, breakpoints cannot be used in a program if any +other process is running that program. Attempting to run or continue +the program with a breakpoint in this case will cause GDB to stop it. + +When this happens, you have three ways to proceed: + +@enumerate +@item +Remove or disable the breakpoints, then continue. + +@item +Suspend GDB, and copy the file containing the program to a new name. +Resume GDB and use the @samp{exec-file} command to specify that GDB +should run the program under that name. Then start the program again. + +@item +Recompile the program so that the text is non-sharable (a.out format +OMAGIC). +@end enumerate + +@node Continuing, Stepping, Breakpoints, Stopping +@section Continuing + +After your program stops, most likely you will want it to run some more if +the bug you are looking for has not happened yet. + +@table @code +@item cont +@kindex cont +Continue running the program at the place where it stopped. +@end table + +If the program stopped at a breakpoint, the place to continue running +is the address of the breakpoint. You might expect that continuing would +just stop at the same breakpoint immediately. In fact, @samp{cont} +takes special care to prevent that from happening. You do not need +to clear the breakpoint to proceed through it after stopping at it. + +You can, however, specify an ignore-count for the breakpoint that the +program stopped at, by means of an argument to the @samp{cont} command. +@xref{Conditions}. + +If the program stopped because of a signal other than @code{SIGINT} or +@code{SIGTRAP}, continuing will cause the program to see that signal. +You may not want this to happen. For example, if the program stopped +due to some sort of memory reference error, you might store correct +values into the erroneous variables and continue, hoping to see more +execution; but the program would probably terminate immediately as +a result of the fatal signal once it sees the signal. To prevent this, +you can continue with @samp{signal 0}. @xref{Signaling}. You can +also act in advance to prevent the program from seeing certain kinds +of signals, using the @samp{handle} command (@pxref{Signals}). + +@node Stepping,, Continuing, Stopping +@section Stepping + +@cindex stepping +@dfn{Stepping} means setting your program in motion for a limited time, so +that control will return automatically to the debugger after one line of +code or one machine instruction. Breakpoints are active during stepping +and the program will stop for them even if it has not gone as far as the +stepping command specifies. + +@table @code +@item step +@kindex step +Proceed the program until control reaches a different line, then stop +it and return to the debugger. This command is abbreviated @samp{s}. + +@item step @var{count} +Proceed as in @samp{step}, but do so @var{count} times. If a breakpoint +or a signal not related to stepping is reached before @var{count} steps, +stepping stops right away. + +This command may be given when control is within a routine for which +there is no debugging information. In that case, execution will proceed +until control reaches a different routine, or is about to return from +this routine. An argument repeats this action. + +@item next +@kindex next +Similar to @samp{step}, but any function calls appearing within the line of +code are executed without stopping. Execution stops when control reaches a +different line of code at the stack level which was executing when the +@samp{next} command was given. This command is abbreviated @samp{n}. + +An argument is a repeat count, as in @samp{step}. + +@samp{next} within a routine without debugging information acts as does +@samp{step}, but any function calls appearing within the code of the +routine are executed without stopping. + +@item finish +@kindex finish +Continue running until just after the selected stack frame returns +(or until there is some other reason to stop, such as a fatal signal +or a breakpoint). Print value returned by the selected stack frame (if +any). + +Contrast this with the @samp{return} command (@pxref{Returning}). + +@item until +@kindex until +Proceed the program until control reaches a line greater than the current +line, then stop is and return to the debugger. Control is also returned to +the debugger if the program exits the current stack frame. Note that this +form of the command uses single stepping, and hence is slower than +@samp{until} with an argument. This command is abbreviated @samp{u}. + +@item until @var{location} +Proceed the program until either the specified location is reached, or the +current (innermost) stack frame returns. This form of the command uses +breakpoints, and hence is quicker than @samp{until} without an argument. + +@item stepi +@itemx si +@kindex stepi +@kindex si +Proceed one machine instruction, then stop and return to the debugger. + +It is often useful to do @samp{display/i $pc} when stepping by machine +instructions. This will cause the next instruction to be executed to +be displayed automatically at each stop. @xref{Auto Display}. + +An argument is a repeat count, as in @samp{step}. + +@item nexti +@itemx ni +@kindex nexti +@kindex ni +Proceed one machine instruction, but if it is a subroutine call, +proceed until the subroutine returns. + +An argument is a repeat count, as in @samp{next}. +@end table + +A typical technique for using stepping is to put a breakpoint +(@pxref{Breakpoints}) at the beginning of the function or the section of +the program in which a problem is believed to lie, and then step through +the suspect area, examining the variables that are interesting, until the +problem happens. + +The @samp{cont} command can be used after stepping to resume execution +until the next breakpoint or signal. + +@node Stack, Source, Stopping, Top +@chapter Examining the Stack + +When your program has stopped, the first thing you need to know is where it +stopped and how it got there. + +@cindex call stack +Each time your program performs a function call, the information about +where in the program the call was made from is saved in a block of data +called a @dfn{stack frame}. The frame also contains the arguments of the +call and the local variables of the function that was called. All the +stack frames are allocated in a region of memory called the @dfn{call +stack}. + +When your program stops, the GDB commands for examining the stack allow you +to see all of this information. + +One of the stack frames is @dfn{selected} by GDB and many GDB commands +refer implicitly to the selected frame. In particular, whenever you ask +GDB for the value of a variable in the program, the value is found in the +selected frame. There are special GDB commands to select whichever frame +you are interested in. + +When the program stops, GDB automatically selects the currently executing +frame and describes it briefly as the @samp{frame} command does +(@pxref{Frame Info, Info}). + +@menu +* Frames:: Explanation of stack frames and terminology. +* Backtrace:: Summarizing many frames at once. +* Selection:: How to select a stack frame. +* Info: Frame Info, Commands to print information on stack frames. +@end menu + +@node Frames, Backtrace, Stack, Stack +@section Stack Frames + +@cindex frame +The call stack is divided up into contiguous pieces called @dfn{frames}; +each frame is the data associated with one call to one function. The frame +contains the arguments given to the function, the function's local +variables, and the address at which the function is executing. + +@cindex initial frame +@cindex outermost frame +@cindex innermost frame +When your program is started, the stack has only one frame, that of the +function @code{main}. This is called the @dfn{initial} frame or the +@dfn{outermost} frame. Each time a function is called, a new frame is +made. Each time a function returns, the frame for that function invocation +is eliminated. If a function is recursive, there can be many frames for +the same function. The frame for the function in which execution is +actually occurring is called the @dfn{innermost} frame. This is the most +recently created of all the stack frames that still exist. + +@cindex frame pointer +Inside your program, stack frames are identified by their addresses. A +stack frame consists of many bytes, each of which has its own address; each +kind of computer has a convention for choosing one of those bytes whose +address serves as the address of the frame. Usually this address is kept +in a register called the @dfn{frame pointer register} while execution is +going on in that frame. + +@cindex frame number +GDB assigns numbers to all existing stack frames, starting with zero for +the innermost frame, one for the frame that called it, and so on upward. +These numbers do not really exist in your program; they are to give you a +way of talking about stack frames in GDB commands. + +@cindex selected frame +Many GDB commands refer implicitly to one stack frame. GDB records a stack +frame that is called the @dfn{selected} stack frame; you can select any +frame using one set of GDB commands, and then other commands will operate +on that frame. When your program stops, GDB automatically selects the +innermost frame. + +@node Backtrace, Selection, Frames, Stack +@section Backtraces + +A backtrace is a summary of how the program got where it is. It shows one +line per frame, for many frames, starting with the currently executing +frame (frame zero), followed by its caller (frame one), and on up the +stack. + +@table @code +@item backtrace +@itemx bt +Print a backtrace of the entire stack: one line per frame for all +frames in the stack. + +You can stop the backtrace at any time by typing the system interrupt +character, normally @kbd{Control-C}. + +@item backtrace @var{n} +@itemx bt @var{n} +Similar, but stop after @var{n} frames. + +@item backtrace @var{-n} +@itemx bt @var{-n} +Similar, but print the outermost @var{n} frames instead of the +innermost. +@end table + +Each line in a backtrace shows the frame number, the program counter, the +function and its arguments, and the source file name and line number (if +known). The program counter is omitted if is the beginning of the code for +the source line. This is the same as the first of the two lines printed +when you select a frame. + +@node Selection, Frame Info, Backtrace, Stack +@section Selecting a Frame + +Most commands for examining the stack and other data in the program work on +whichever stack frame is selected at the moment. Here are the commands for +selecting a stack frame; all of them finish by printing a brief description +of the stack frame just selected. + +@table @code +@item frame @var{n} +@kindex frame +Select frame number @var{n}. Recall that frame zero is the innermost +(currently executing) frame, frame one is the frame that called the +innermost one, and so on. The highest-numbered frame is @code{main}'s +frame. + +@item frame @var{addr} +Select the frame at address @var{addr}. This is useful mainly if the +chaining of stack frames has been damaged by a bug, making it +impossible for GDB to assign numbers properly to all frames. In +addition, this can be useful when the program has multiple stacks and +switches between them. + +@item up @var{n} +@kindex up +Select the frame @var{n} frames up from the frame previously selected. +For positive numbers @var{n}, this advances toward the outermost +frame, to higher frame numbers, to frames that have existed longer. +@var{n} defaults to one. + +@item down @var{n} +@kindex down +Select the frame @var{n} frames down from the frame previously +selected. For positive numbers @var{n}, this advances toward the +innermost frame, to lower frame numbers, to frames that were created +more recently. @var{n} defaults to one. +@end table + +All of these commands end by printing some information on the frame that +has been selected: the frame number, the function name, the arguments, the +source file and line number of execution in that frame, and the text of +that source line. For example: + +@example +#3 main (argc=3, argv=??, env=??) at main.c, line 67 +67 read_input_file (argv[i]); +@end example + +After such a printout, the @samp{list} command with no arguments will print +ten lines centered on the point of execution in the frame. @xref{List}. + +@node Frame Info,, Selection, Stack +@section Information on a Frame + +There are several other commands to print information about the selected +stack frame. + +@table @code +@item frame +This command prints a brief description of the selected stack frame. +It can be abbreviated @samp{f}. With an argument, this command is +used to select a stack frame; with no argument, it does not change +which frame is selected, but still prints the same information. + +@item info frame +@kindex info frame +This command prints a verbose description of the selected stack frame, +including the address of the frame, the addresses of the next frame in +(called by this frame) and the next frame out (caller of this frame), +the address of the frame's arguments, the program counter saved in it +(the address of execution in the caller frame), and which registers +were saved in the frame. The verbose description is useful when +something has gone wrong that has made the stack format fail to fit +the usual conventions. + +@item info frame @var{addr} +Print a verbose description of the frame at address @var{addr}, +without selecting that frame. The selected frame remains unchanged by +this command. + +@item info args +@kindex info args +Print the arguments of the selected frame, each on a separate line. + +@item info locals +@kindex info locals +Print the local variables of the selected frame, each on a separate +line. These are all variables declared static or automatic within all +program blocks that execution in this frame is currently inside of. +@end table + +@node Source, Data, Stack, Top +@chapter Examining Source Files + +GDB knows which source files your program was compiled from, and +can print parts of their text. When your program stops, GDB +spontaneously prints the line it stopped in. Likewise, when you +select a stack frame (@pxref{Selection}), GDB prints the line +which execution in that frame has stopped in. You can also +print parts of source files by explicit command. + +@menu +* List:: Using the @samp{list} command to print source files. +* Search:: Commands for searching source files. +* Source Path:: Specifying the directories to search for source files. +@end menu + +@node List, Search, Source, Source +@section Printing Source Lines + +@kindex list +To print lines from a source file, use the @samp{list} command +(abbreviated @samp{l}). There are several ways to specify what part +of the file you want to print. + +Here are the forms of the @samp{list} command most commonly used: + +@table @code +@item list @var{linenum} +Print ten lines centered around line number @var{linenum} in the +current source file. + +@item list @var{function} +Print ten lines centered around the beginning of function +@var{function}. + +@item list +Print ten more lines. If the last lines printed were printed with a +@samp{list} command, this prints ten lines following the last lines +printed; however, if the last line printed was a solitary line printed +as part of displaying a stack frame (@pxref{Stack}), this prints ten +lines centered around that line. + +@item list @minus{} +Print ten lines just before the lines last printed. +@end table + +Repeating a @samp{list} command with @key{RET} discards the argument, +so it is equivalent to typing just @samp{list}. This is more useful +than listing the same lines again. An exception is made for an +argument of @samp{-}; that argument is preserved in repetition so that +each repetition moves up in the file. + +In general, the @samp{list} command expects you to supply zero, one or two +@dfn{linespecs}. Linespecs specify source lines; there are several ways +of writing them but the effect is always to specify some source line. +Here is a complete description of the possible arguments for @samp{list}: + +@table @code +@item list @var{linespec} +Print ten lines centered around the line specified by @var{linespec}. + +@item list @var{first},@var{last} +Print lines from @var{first} to @var{last}. Both arguments are +linespecs. + +@item list ,@var{last} +Print ten lines ending with @var{last}. + +@item list @var{first}, +Print ten lines starting with @var{first}. + +@item list + +Print ten lines just after the lines last printed. + +@item list @minus{} +Print ten lines just before the lines last printed. + +@item list +As described in the preceding table. +@end table + +Here are the ways of specifying a single source line---all the +kinds of linespec. + +@table @asis +@item @var{linenum} +Specifies line @var{linenum} of the current source file. +When a @samp{list} command has two linespecs, this refers to +the same source file as the first linespec. + +@item +@var{offset} +Specifies the line @var{offset} lines after the last line printed. +When used as the second linespec in a @samp{list} command that has +two, this specifies the line @var{offset} lines down from the +first linespec. + +@item @minus{}@var{offset} +Specifies the line @var{offset} lines before the last line printed. + +@item @var{filename}:@var{linenum} +Specifies line @var{linenum} in the source file @var{filename}. + +@item @var{function} +Specifies the line of the open-brace that begins the body of the +function @var{function}. + +@item @var{filename}:@var{function} +Specifies the line of the open-brace that begins the body of the +function @var{function} in the file @var{filename}. The file name is +needed with a function name only for disambiguation of identically +named functions in different source files. + +@item *@var{address} +Specifies the line containing the program address @var{address}. +@var{address} may be any expression. +@end table + +One other command is used to map source lines to program addresses. + +@table @code +@item info line @var{linenum} +@kindex info line +Print the starting and ending addresses of the compiled code for +source line @var{linenum}. + +@kindex $_ +The default examine address for the @samp{x} command is changed to the +starting address of the line, so that @samp{x/i} is sufficient to +begin examining the machine code (@pxref{Memory}). Also, this address +is saved as the value of the convenience variable @samp{$_} +(@pxref{Convenience Vars}). +@end table + +@node Search, Source Path, List, Source +@section Searching Source Files +@cindex searching +@kindex forward-search +@kindex reverse-search + +There are two commands for searching through the current source file for a +regular expression. + +The command @samp{forward-search @var{regexp}} checks each line, starting +with the one following the last line listed, for a match for @var{regexp}. +It lists the line that is found. You can abbreviate the command name +as @samp{fo}. + +The command @samp{reverse-search @var{regexp}} checks each line, starting +with the one before the last line listed and going backward, for a match +for @var{regexp}. It lists the line that is found. You can abbreviate +this command with as little as @samp{rev}. + +@node Source Path,, Search, Source +@section Specifying Source Directories + +@cindex source path +@cindex directories for source files +Executable programs do not record the directories of the source files they +were compiled from, just the names. GDB remembers a list of directories to +search for source files; this is called the @dfn{source path}. Each time +GDB wants a source file, it tries all the directories in the list, in the +order they are present in the list, until it finds a file with the desired +name. + +@kindex directory +When you start GDB, its source path contains just the current working +directory. To add other directories, use the @samp{directory} command. +@b{Note that the search path for executable files and the working directory +are @i{not} used for finding source files.} + +@table @code +@item directory @var{dirname} +Add directory @var{dirname} to the end of the source path. + +@item directory +Reset the source path to just the current working directory of GDB. +This requires confirmation. + +@samp{directory} with no argument can cause source files previously +found by GDB to be found in a different directory. To make this work +correctly, this command also clears out the tables GDB maintains +about the source files it has already found. + +@item info directories +@kindex info directories +Print the source path: show which directories it contains. +@end table + +Because the @samp{directory} command adds to the end of the source path, +it does not affect any file that GDB has already found. If the source +path contains directories that you do not want, and these directories +contain misleading files with names matching your source files, the +way to correct the situation is as follows: + +@enumerate +@item +Choose the directory you want at the beginning of the source path. +Use the @samp{cd} command to make that the current working directory. + +@item +Use @samp{directory} with no argument to reset the source path to just +that directory. + +@item +Use @samp{directory} with suitable arguments to add any other +directories you want in the source path. +@end enumerate + +@node Data, Symbols, Source, Top +@chapter Examining Data + +@cindex printing data +@cindex examining data +@kindex print +The usual way of examining data in your program is with the @samp{print} +command (abbreviated @samp{p}). It evaluates and prints the value of any +valid expression of the language the program is written in (for now, C). +You type + +@example +print @var{exp} +@end example + +@noindent +where @var{exp} is any valid expression, and the value of @var{exp} +is printed in a format appropriate to its data type. + +A more low-level way of examining data is with the @samp{x} command. +It examines data in memory at a specified address and prints it in a +specified format. + +GDB supports one command to modify the default format of displayed data: + +@table @samp +@item set array-max +@kindex set array-max +@samp{set array-max} sets the maximum number of elements of an array which +will be printed. This limit also applies to the display of strings. +@end table + +@menu +* Expressions:: Expressions that can be computed and printed. +* Variables:: Using your program's variables in expressions. +* Assignment:: Setting your program's variables. +* Arrays:: Examining part of memory as an array. +* Formats:: Specifying formats for printing values. +* Memory:: Examining memory explicitly. +* Auto Display:: Printing certain expressions whenever program stops. +* Value History:: Referring to values previously printed. +* Convenience Vars:: Giving names to values for future reference. +* Registers:: Referring to and storing in machine registers. +@end menu + +@node Expressions, Variables, Data, Data +@section Expressions + +@cindex expressions +Many different GDB commands accept an expression and compute its value. +Any kind of constant, variable or operator defined by the programming +language you are using is legal in an expression in GDB. This includes +conditional expressions, function calls, casts and string constants. +It unfortunately does not include symbols defined by preprocessor +#define commands. + +Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer so as to examine a structure +at that address in memory. + +GDB supports three kinds of operator in addition to those of programming +languages: + +@table @code +@item @@ +@samp{@@} is a binary operator for treating parts of memory as arrays. +@xref{Arrays}, for more information. + +@item :: +@samp{::} allows you to specify a variable in terms of the file or +function it is defined in. @xref{Variables}. + +@item @{@var{type}@} @var{addr} +Refers to an object of type @var{type} stored at address @var{addr} in +memory. @var{addr} may be any expression whose value is an integer or +pointer (but parentheses are required around nonunary operators, just as in +a cast). This construct is allowed regardless of what kind of data is +officially supposed to reside at @var{addr}.@refill +@end table + +@node Variables, Arrays, Expressions, Data +@section Program Variables + +The most common kind of expression to use is the name of a variable +in your program. + +Variables in expressions are understood in the selected stack frame +(@pxref{Selection}); they must either be global (or static) or be visible +according to the scope rules of the programming language from the point of +execution in that frame. This means that in the function + +@example +foo (a) + int a; +@{ + bar (a); + @{ + int b = test (); + bar (b); + @} +@} +@end example + +@noindent +the variable @code{a} is usable whenever the program is executing +within the function @code{foo}, but the variable @code{b} is visible +only while the program is executing inside the block in which @code{b} +is declared. + +As a special exception, you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable +or function with the same name (if they are in different source files). +In such a case, it is not defined which one you will get. If you wish, +you can specify any one of them using the colon-colon construct: + +@example +@var{block}::@var{variable} +@end example + +@noindent +Here @var{block} is the name of the source file whose variable you want. + +@node Arrays, Formats, Variables, Data +@section Artificial Arrays + +@cindex artificial array +It is often useful to print out several successive objects of the +same type in memory; a section of an array, or an array of +dynamically determined size for which only a pointer exists in the +program. + +This can be done by constructing an @dfn{artificial array} with the +binary operator @samp{@@}. The left operand of @samp{@@} should be +the first element of the desired array, as an individual object. +The right operand should be the length of the array. The result is +an array value whose elements are all of the type of the left argument. +The first element is actually the left argument; the second element +comes from bytes of memory immediately following those that hold the +first element, and so on. Here is an example. If a program says + +@example +int *array = (int *) malloc (len * sizeof (int)); +@end example + +@noindent +you can print the contents of @code{array} with + +@example +p *array@@len +@end example + +The left operand of @samp{@@} must reside in memory. Array values made +with @samp{@@} in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +(It would probably appear in an expression via the value history, +after you had printed it out.) + +@node Formats, Memory, Arrays, Data +@section Formats + +@cindex formatted output +@cindex output formats +GDB normally prints all values according to their data types. Sometimes +this is not what you want. For example, you might want to print a number +in hex, or a pointer in decimal. Or you might want to view data in memory +at a certain address as a character string or an instruction. These things +can be done with @dfn{output formats}. + +The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the +@samp{print} command with a slash and a format letter. The format +letters supported are: + +@table @samp +@item x +Regard the bits of the value as an integer, and print the integer in +hexadecimal. + +@item d +Print as integer in signed decimal. + +@item u +Print as integer in unsigned decimal. + +@item o +Print as integer in octal. + +@item a +Print as an address, both absolute in hex and then relative +to a symbol defined as an address below it. + +@item c +Regard as an integer and print it as a character constant. + +@item f +Regard the bits of the value as a floating point number and print +using typical floating point syntax. +@end table + +For example, to print the program counter in hex (@pxref{Registers}), type + +@example +p/x $pc +@end example + +@noindent +Note that no space is required before the slash; this is because command +names in GDB cannot contain a slash. + +To reprint the last value in the value history with a different format, +you can use the @samp{print} command with just a format and no +expression. For example, @samp{p/x} reprints the last value in hex. + +@node Memory, Auto Display, Formats, Data +@subsection Examining Memory + +@cindex examining memory +@kindex x +The command @samp{x} (for `examine') can be used to examine memory under +explicit control of formats, without reference to the program's data types. + +@samp{x} is followed by a slash and an output format specification, +followed by an expression for an address. The expression need not have +a pointer value (though it may); it is used as an integer, as the +address of a byte of memory. @xref{Expressions} for more information +on expressions. + +The output format in this case specifies both how big a unit of memory +to examine and how to print the contents of that unit. It is done +with one or two of the following letters: + +These letters specify just the size of unit to examine: + +@table @samp +@item b +Examine individual bytes. + +@item h +Examine halfwords (two bytes each). + +@item w +Examine words (four bytes each). + +@cindex word +Many assemblers and cpu designers still use `word' for a 16-bit quantity, +as a holdover from specific predecessor machines of the 1970's that really +did use two-byte words. But more generally the term `word' has always +referred to the size of quantity that a machine normally operates on and +stores in its registers. This is 32 bits for all the machines that GNU +runs on. + +@item g +Examine giant words (8 bytes). +@end table + +These letters specify just the way to print the contents: + +@table @samp +@item x +Print as integers in unsigned hexadecimal. + +@item d +Print as integers in signed decimal. + +@item u +Print as integers in unsigned decimal. + +@item o +Print as integers in unsigned octal. + +@item a +Print as an address, both absolute in hex and then relative +to a symbol defined as an address below it. + +@item c +Print as character constants. + +@item f +Print as floating point. This works only with sizes @samp{w} and +@samp{g}. + +@item s +Print a null-terminated string of characters. The specified unit size +is ignored; instead, the unit is however many bytes it takes to reach +a null character (including the null character). + +@item i +Print a machine instruction in assembler syntax (or nearly). The +specified unit size is ignored; the number of bytes in an instruction +varies depending on the type of machine, the opcode and the addressing +modes used. +@end table + +If either the manner of printing or the size of unit fails to be specified, +the default is to use the same one that was used last. If you don't want +to use any letters after the slash, you can omit the slash as well. + +You can also omit the address to examine. Then the address used is +just after the last unit examined. This is why string and instruction +formats actually compute a unit-size based on the data: so that the +next string or instruction examined will start in the right place. +The @samp{print} command sometimes sets the default address for +the @samp{x} command; when the value printed resides in memory, the +default is set to examine the same location. @samp{info line} also +sets the default for @samp{x}, to the address of the start of the +machine code for the specified line and @samp{info breakpoints} sets +it to the address of the last breakpoint listed. + +When you use @key{RET} to repeat an @samp{x} command, it does not repeat +exactly the same: the address specified previously (if any) is ignored, so +that the repeated command examines the successive locations in memory +rather than the same ones. + +You can examine several consecutive units of memory with one command by +writing a repeat-count after the slash (before the format letters, if any). +The repeat count must be a decimal integer. It has the same effect as +repeating the @samp{x} command that many times except that the output may +be more compact with several units per line. + +@example +x/10i $pc +@end example + +@noindent +Prints ten instructions starting with the one to be executed next in the +selected frame. After doing this, you could print another ten following +instructions with + +@example +x/10 +@end example + +@noindent +in which the format and address are allowed to default. + +@kindex $_ +@kindex $__ +The addresses and contents printed by the @samp{x} command are not put in +the value history because there is often too much of them and they would +get in the way. Instead, GDB makes these values available for subsequent +use in expressions as values of the convenience variables @samp{$_} and +@samp{$__}. + +After an @samp{x} command, the last address examined is available for use +in expressions in the convenience variable @samp{$_}. The contents of that +address, as examined, are available in the convenience variable @samp{$__}. + +If the @samp{x} command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of output. + +@node Auto Display, Value History, Memory, Data +@section Automatic Display + +If you find that you want to print the value of an expression frequently +(to see how it changes), you might want to add it to the @dfn{automatic +display list} so that GDB will print its value each time the program stops. +Each expression added to the list is given a number to identify it; +to remove an expression from the list, you specify that number. +The automatic display looks like this: + +@example +2: foo = 38 +3: bar[5] = (struct hack *) 0x3804 +@end example + +@noindent +showing item numbers, expressions and their current values. + +@table @code +@item display @var{exp} +@kindex display +Add the expression @var{exp} to the list of expressions to display +each time the program stops. @xref{Expressions}. + +@item display/@var{fmt} @var{exp} +For @var{fmt} specifying only a display format and not a size or +count, add the expression @var{exp} to the auto-display list but +arranges to display it each time in the specified format @var{fmt}. + +@item display/@var{fmt} @var{addr} +For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a +number of units, add the expression @var{addr} as a memory address to +be examined each time the program stops. Examining means in effect +doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}. + +@item undisplay @var{dnums}@dots{} +@kindex undisplay +@item delete display @var{dnums}@dots{} +@kindex delete display +Remove item numbers @var{dnums} from the list of expressions to display. + +@item disable display @var{dnums}@dots{} +@kindex disable display +Disable the display of item numbers @var{dnums}. A disabled display item +has no effect but is not forgotten. It may be later enabled. + +@item enable display @var{dnums}@dots{} +@kindex enable display +Enable display of item numbers @var{dnums}. It becomes effective once +again in auto display of its expression, until you specify otherwise. + +@item display +Display the current values of the expressions on the list, just as is +done when the program stops. + +@item info display +@kindex info display +Print the list of expressions to display automatically, each one +with its item number, but without showing the values. +@end table + +@node Value History, Convenience Vars, Auto Display, Data +@section Value History + +@cindex value history +Every value printed by the @samp{print} command is saved for the entire +session in GDB's @dfn{value history} so that you can refer to it in +other expressions. + +@cindex $ +@cindex $$ +The values printed are given @dfn{history numbers} for you to refer to them +by. These are successive integers starting with 1. @samp{print} shows you +the history number assigned to a value by printing @samp{$@var{n} = } +before the value; here @var{n} is the history number. + +To refer to any previous value, use @samp{$} followed by the value's +history number. The output printed by @samp{print} is designed to remind +you of this. Just @samp{$} refers to the most recent value in the history, +and @samp{$$} refers to the value before that. + +For example, suppose you have just printed a pointer to a structure and +want to see the contents of the structure. It suffices to type + +@example +p *$ +@end example + +If you have a chain of structures where the component @samp{next} points +to the next one, you can print the contents of the next one with + +@example +p *$.next +@end example + +It might be useful to repeat this command many times by typing @key{RET}. + +Note that the history records values, not expressions. If the value of +@code{x} is 4 and you type + +@example +print x +set x=5 +@end example + +@noindent +then the value recorded in the value history by the @samp{print} command +remains 4 even though @code{x}'s value has changed. + +@table @code +@item info history +@kindex info history +Print the last ten values in the value history, with their item +numbers. This is like @samp{p $$9} repeated ten times, except that +@samp{info history} does not change the history. + +@item info history @var{n} +Print ten history values centered on history item number @var{n}. +@end table + +@node Convenience Vars, Registers, Value History, Data +@section Convenience Variables + +@cindex convenience variables +GDB provides @dfn{convenience variables} that you can use within GDB to +hold on to a value and refer to it later. These variables exist entirely +within GDB; they are not part of your program, and setting a convenience +variable has no effect on further execution of your program. That's why +you can use them freely. + +Convenience variables have names starting with @samp{$}. Any name starting +with @samp{$} can be used for a convenience variable, unless it is one of +the predefined set of register names (@pxref{Registers}). + +You can save a value in a convenience variable with an assignment +expression, just as you would set a variable in your program. Example: + +@example +set $foo = *object_ptr +@end example + +@noindent +would save in @samp{$foo} the value contained in the object pointed to by +@code{object_ptr}. + +Using a convenience variable for the first time creates it; but its value +is @code{void} until you assign a new value. You can alter the value with +another assignment at any time. + +Convenience variables have no fixed types. You can assign a convenience +variable any type of value, even if it already has a value of a different +type. The convenience variable as an expression has whatever type its +current value has. + +@table @code +@item info convenience +@kindex info convenience +Print a list of convenience variables used so far, and their values. +Abbreviated @samp{i con}. +@end table + +One of the ways to use a convenience variable is as a counter to be +incremented or a pointer to be advanced. For example: + +@example +set $i = 0 +print bar[$i++]->contents +@i{@dots{}repeat that command by typing @key{RET}.} +@end example + +Some convenience variables are created automatically by GDB and given +values likely to be useful. + +@table @samp +@item $_ +The variable @samp{$_} is automatically set by the @samp{x} command to +the last address examined (@pxref{Memory}). Other commands which +provide a default address for @samp{x} to examine also set @samp{$_} +to that address; these commands include @samp{info line} and @samp{info +breakpoint}. + +@item $__ +The variable @samp{$__} is automatically set by the @samp{x} command +to the value found in the last address examined. +@end table + +@node Registers,, Convenience Vars, Data +@section Registers + +@cindex registers +Machine register contents can be referred to in expressions as variables +with names starting with @samp{$}. The names of registers are different +for each machine; use @samp{info registers} to see the names used on your +machine. The names @samp{$pc} and @samp{$sp} are used on all machines for +the program counter register and the stack pointer. Often @samp{$fp} is +used for a register that contains a pointer to the current stack frame. + +GDB always considers the contents of an ordinary register as an integer +when the register is examined in this way. Some machines have special +registers which can hold nothing but floating point; these registers are +considered floating point. There is no way to refer to the contents of an +ordinary register as floating point value (although you can @emph{print} +it as a floating point value with @samp{print/f $@var{regname}}). + +Some registers have distinct ``raw'' and ``virtual'' data formats. This +means that the data format in which the register contents are saved by the +operating system is not the same one that your program normally sees. For +example, the registers of the 68881 floating point coprocessor are always +saved in ``extended'' format, but virtually all C programs expect to work with +``double'' format. In such cases, GDB normally works with the virtual +format only (the format that makes sense for your program), but the +@samp{info registers} command prints the data in both formats. + +Register values are relative to the selected stack frame +(@pxref{Selection}). This means that you get the value that the register +would contain if all stack frames farther in were exited and their saved +registers restored. In order to see the real contents of all registers, +you must select the innermost frame (with @samp{frame 0}). + +Some registers are never saved (typically those numbered zero or one) +because they are used for returning function values; for these registers, +relativization makes no difference. + +@table @code +@item info registers +@kindex info registers +Print the names and relativized values of all registers. + +@item info registers @var{regname} +Print the relativized value of register @var{regname}. @var{regname} +may be any register name valid on the machine you are using, with +or without the initial @samp{$}. +@end table + +@subsection Examples + +You could print the program counter in hex with + +@example +p/x $pc +@end example + +@noindent +or print the instruction to be executed next with + +@example +x/i $pc +@end example + +@noindent +or add four to the stack pointer with + +@example +set $sp += 4 +@end example + +@noindent +The last is a way of removing one word from the stack, on machines where +stacks grow downward in memory (most machines, nowadays). This assumes +that the innermost stack frame is selected. Setting @samp{$sp} is +not allowed when other stack frames are selected. + +@node Symbols, Altering, Data, Top +@chapter Examining the Symbol Table + +The commands described in this section allow you to make inquiries for +information about the symbols (names of variables, functions and types) +defined in your program. This information is found by GDB in the symbol +table loaded by the @samp{symbol-file} command; it is inherent in the text +of your program and does not change as the program executes. + +@table @code +@item whatis @var{exp} +@kindex whatis +Print the data type of expression @var{exp}. @var{exp} is not +actually evaluated, and any side-effecting operations (such as +assignments or function calls) inside it do not take place. +@xref{Expressions}. + +@item whatis +Print the data type of @samp{$}, the last value in the value history. + +@item info address @var{symbol} +@kindex info address +Describe where the data for @var{symbol} is stored. For register +variables, this says which register. For other automatic variables, +this prints the stack-frame offset at which the variable is always +stored. Note the contrast with @samp{print &@var{symbol}}, which does +not work at all for register variables and for automatic variables +prints the exact address of the current instantiation of the variable. + +@item ptype @var{typename} +@kindex ptype +Print a description of data type @var{typename}. @var{typename} may be +the name of a type, or for C code it may have the form +@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or +@samp{enum @var{enum-tag}}.@refill + +@item info sources +@kindex info sources +Print the names of all source files in the program for which there +is debugging information. + +@item info functions +@kindex info functions +Print the names and data types of all defined functions. + +@item info functions @var{regexp} +Print the names and data types of all defined functions +whose names contain a match for regular expression @var{regexp}. +Thus, @samp{info fun step} finds all functions whose names +include @samp{step}; @samp{info fun ^step} finds those whose names +start with @samp{step}. + +@item info variables +@kindex info variables +Print the names and data types of all variables that are declared +outside of functions. + +@item info variables @var{regexp} +Print the names and data types of all variables, declared outside of +functions, whose names contain a match for regular expression +@var{regexp}. + +@item info types +@kindex info types +Print all data types that are defined in the program. + +@item info types @var{regexp} +Print all data types that are defined in the program whose names +contain a match for regular expression @var{regexp}. + +@item info methods +@item info methods @var{regexp} +@kindex info methods +The @samp{info-methods} command permits the user to examine all defined +methods within C@code{++} program, or (with the @var{regexp} argument) a +specific set of methods found in the various C@code{++} classes. Many +C@code{++} classes which implement a large number of differently typed +methods implement a large number of methods as well. Thus, the +@samp{ptype} command can give the user a tremendous overdose of +information about what methods are associated with a given class. The +@samp{info-methods} command filters these methods do to only those +methods which match the regular-expression search key. + +@item printsyms @var{filename} +@kindex printsyms +Write a complete dump of the debugger's symbol data into the +file @var{filename}. +@end table + +@node Altering, Sequences, Symbols, Top +@chapter Altering Execution + +There are several ways to alter the execution of your program with GDB +commands. + +@menu +* Assignment:: Altering variable values or memory contents. +* Jumping:: Altering control flow. +* Signaling:: Making signals happen in the program. +* Returning:: Making a function return prematurely. +@end menu + +@node Assignment, Jumping, Altering, Altering +@section Assignment to Variables + +@cindex assignment +@cindex setting variables +To alter the value of a variable, evaluate an assignment expression. +@xref{Expressions}. For example, + +@example +print x=4 +@end example + +@noindent +would store the value 4 into the variable @code{x}, and then print +the value of the assignment expression (which is 4). + +@kindex set +@kindex set variable +If you are not interested in seeing the value of the assignment, use the +@samp{set} command instead of the @samp{print} command. @samp{set} is +really the same as @samp{print} except that the expression's value is not +printed and is not put in the value history (@pxref{Value History}). The +expression is evaluated only for side effects. + +Note that if the beginning of the argument string of the @samp{set} command +appears identical to a @samp{set} subcommand, it may be necessary to use +the @samp{set variable} command. This command is identical to @samp{set} +except for its lack of subcommands. + +GDB allows more implicit conversions in assignments than C does; you can +freely store an integer value into a pointer variable or vice versa, and +any structure can be converted to any other structure that is the same +length or shorter. + +In C, all the other assignment operators such as @samp{+=} and @samp{++} +are supported as well. + +To store into arbitrary places in memory, use the @samp{@{@dots{}@}} +construct to generate a value of specified type at a specified address +(@pxref{Expressions}). For example, + +@example +set @{int@}0x83040 = 4 +@end example + +@node Jumping, Signaling, Assignment, Altering +@section Continuing at a Different Address + +@table @code +@item jump @var{linenum} +@kindex jump +Resume execution at line number @var{linenum}. Execution may stop +immediately if there is a breakpoint there. + +The @samp{jump} command does not change the current stack frame, or +the stack pointer, or the contents of any memory location or any +register other than the program counter. If line @var{linenum} is in +a different function from the one currently executing, the results may +be wild if the two functions expect different patterns of arguments or +of local variables. For this reason, the @samp{jump} command requests +confirmation if the specified line is not in the function currently +executing. However, even wild results are predictable based on +changing the program counter. + +@item jump *@var{address} +Resume execution at the instruction at address @var{address}. +@end table + +A similar effect can be obtained by storing a new value into the register +@samp{$pc}, but not exactly the same. + +@example +set $pc = 0x485 +@end example + +@noindent +specifies the address at which execution will resume, but does not resume +execution. That does not happen until you use the @samp{cont} command or a +stepping command (@pxref{Stepping}). + +@node Signaling, Returning, Jumping, Altering +@section Giving the Program a Signal + +@table @code +@item signal @var{signalnum} +@kindex signal +Resume execution where the program stopped, but give it immediately +the signal number @var{signalnum}. + +Alternatively, if @var{signalnum} is zero, continue execution and give +no signal. This is useful when the program has received a signal +but you don't want the program to see that signal; the @samp{cont} command +would signal the program. +@end table + +@node Returning,, Signaling, Altering +@section Returning from a Function + +@cindex returning from a function +@kindex return +You can make any function call return immediately, using the @samp{return} +command. + +First select the stack frame that you wish to return from +(@pxref{Selection}). Then type the @samp{return} command. If you wish to +specify the value to be returned, give that as an argument. + +This pops the selected stack frame (and any other frames inside of it), +leaving its caller as the innermost remaining frame. That frame becomes +selected. The specified value is stored in the registers used for +returning values of functions. + +The @samp{return} command does not resume execution; it leaves the program +stopped in the state that would exist if the function had just returned. +Contrast this with the @samp{finish} command (@pxref{Stepping}), which +resumes execution @i{until} the selected stack frame returns naturally. + +@node Sequences, Emacs, Altering, Top +@chapter Canned Sequences of Commands + +GDB provides two ways to store sequences of commands for execution as a +unit: user-defined commands and command files. + +@menu +* Define:: User-defined commands. +* Command Files:: Command files. +* Output:: Controlled output commands useful in + user-defined commands and command files. +@end menu + +@node Define, Command Files, Sequences, Sequences +@section User-Defined Commands + +@cindex user-defined commands +A @dfn{user-defined command} is a sequence of GDB commands to which you +assign a new name as a command. This is done with the @samp{define} +command. + +@table @code +@item define @var{commandname} +@kindex define +Define a command named @var{commandname}. If there is already a command +by that name, you are asked to confirm that you want to redefine it. + +The definition of the command is made up of other GDB command lines, +which are given following the @samp{define} command. The end of these +commands is marked by a line containing @samp{end}. + +@item document @var{commandname} +@kindex document +Give documentation to the user-defined command @var{commandname}. The +command @var{commandname} must already be defined. This command reads +lines of documentation just as @samp{define} reads the lines of the +command definition, ending with @samp{end}. After the @samp{document} command is finished, +@samp{help} on command @var{commandname} will print the documentation +you have specified. + +You may use the @samp{document} command again to change the +documentation of a command. Redefining the command with @samp{define} +does not change the documentation. +@end table + +User-defined commands do not take arguments. When they are executed, the +commands of the definition are not printed. An error in any command +stops execution of the user-defined command. + +Commands that would ask for confirmation if used interactively proceed +without asking when used inside a user-defined command. Many GDB commands +that normally print messages to say what they are doing omit the messages +when used in user-defined command. + +@node Command Files, Output, Define, Sequences +@section Command Files + +@cindex command files +A command file for GDB is a file of lines that are GDB commands. Comments +(lines starting with @samp{#}) may also be included. An empty line in a +command file does nothing; it does not mean to repeat the last command, as +it would from the terminal. + +@cindex init file +@cindex .gdbinit +When GDB starts, it automatically executes its @dfn{init files}, command +files named @file{.gdbinit}. GDB reads the init file (if any) in your home +directory and then the init file (if any) in the current working +directory. (The init files are not executed if the @samp{-nx} option +is given.) You can also request the execution of a command file with the +@samp{source} command: + +@table @code +@item source @var{filename} +@kindex source +Execute the command file @var{filename}. +@end table + +The lines in a command file are executed sequentially. They are not +printed as they are executed. An error in any command terminates execution +of the command file. + +Commands that would ask for confirmation if used interactively proceed +without asking when used in a command file. Many GDB commands that +normally print messages to say what they are doing omit the messages +when used in a command file. + +@node Output,, Command Files, Sequences +@section Commands for Controlled Output + +During the execution of a command file or a user-defined command, the only +output that appears is what is explicitly printed by the commands of the +definition. This section describes three commands useful for generating +exactly the output you want. + +@table @code +@item echo @var{text} +@kindex echo +Print @var{text}. Nonprinting characters can be included in +@var{text} using C escape sequences, such as @samp{\n} to print a +newline. @b{No newline will be printed unless you specify one.} + +A backslash at the end of @var{text} is ignored. It is useful for +outputting a string ending in spaces, since trailing spaces are +trimmed from all arguments. A backslash at the beginning preserves +leading spaces in the same way, because @samp{\ } as an escape +sequence stands for a space. Thus, to print @samp{ and foo = }, do + +@example +echo \ and foo = \ +@end example + +@item output @var{expression} +@kindex output +Print the value of @var{expression} and nothing but that value: no +newlines, no @samp{$@var{nn} = }. The value is not entered in the +value history either. @xref{Expressions} for more information +on expressions. + +@item output/@var{fmt} @var{expression} +Print the value of @var{expression} in format @var{fmt}. +@xref{Formats}, for more information. + +@item printf @var{string}, @var{expressions}@dots{} +@kindex printf +Print the values of the @var{expressions} under the control of +@var{string}. The @var{expressions} are separated by commas and may +be either numbers or pointers. Their values are printed as specified +by @var{string}, exactly as if the program were to execute + +@example +printf (@var{string}, @var{expressions}@dots{}); +@end example + +For example, you can print two values in hex like this: + +@example +printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo +@end example + +The only backslash-escape sequences that you can use in the string are +the simple ones that consist of backslash followed by a letter. +@end table + +@node Emacs, Remote, Sequences, Top +@chapter Using GDB under GNU Emacs + +A special interface allows you to use GNU Emacs to view (and +edit) the source files for the program you are debugging with +GDB. + +To use this interface, use the command @kbd{M-x gdb} in Emacs. +Give the executable file you want to debug as an argument. This +command starts a GDB process as a subprocess of Emacs, with input +and output through a newly created Emacs buffer. + +Using this GDB process is just like using GDB normally except for two things: + +@itemize @bullet +@item +All ``terminal'' input and output goes through the Emacs buffer. This +applies both to GDB commands and their output, and to the input and +output done by the program you are debugging. + +This is useful because it means that you can copy the text of previous +commands and input them again; you can even use parts of the output +in this way. + +All the facilities of Emacs's Shell mode are available for this purpose. + +@item +GDB displays source code through Emacs. Each time GDB displays a +stack frame, Emacs automatically finds the source file for that frame +and puts an arrow (@samp{=>}) at the left margin of the current line. + +Explicit GDB @samp{list} or search commands still produce output as +usual, but you probably will have no reason to use them. +@end itemize + +In the GDB I/O buffer, you can use these special Emacs commands: + +@table @kbd +@item M-s +Execute to another source line, like the GDB @samp{step} command. + +@item M-n +Execute to next source line in this function, skipping all function +calls, like the GDB @samp{next} command. + +@item M-i +Execute one instruction, like the GDB @samp{stepi} command. + +@item M-u +Move up one stack frame (and display that frame's source file in +Emacs), like the GDB @samp{up} command. + +@item M-d +Move down one stack frame (and display that frame's source file in +Emacs), like the GDB @samp{down} command. (This means that you cannot +delete words in the usual fashion in the GDB buffer; I am guessing you +won't often want to do that.) + +@item C-c C-f +Execute until exit from the selected stack frame, like the GDB +@samp{finish} command. +@end table + +In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) +tells GDB to set a breakpoint on the source line point is on. + +The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit +the files with these buffers if you wish; but keep in mind that GDB +communicates with Emacs in terms of line numbers. If you add or +delete lines from the text, the line numbers that GDB knows will cease +to correspond properly to the code. + +@node Remote, Commands, Emacs, Top +@chapter Remote Kernel Debugging + +GDB has a special facility for debugging a remote machine via a serial +connection. This can be used for kernel debugging. + +The program to be debugged on the remote machine needs to contain a +debugging device driver which talks to GDB over the serial line using the +protocol described below. The same version of GDB that is used ordinarily +can be used for this. + +@menu +* Remote Commands:: Commands used to start and finish remote debugging. +@end menu + +For details of the communication protocol, see the comments in the GDB +source file @file{remote.c}. + +@node Remote Commands,, Remote, Remote +@section Commands for Remote Debugging + +To start remote debugging, first run GDB and specify as an executable file +the program that is running in the remote machine. This tells GDB how +to find the program's symbols and the contents of its pure text. Then +establish communication using the @samp{attach} command with a device +name rather than a pid as an argument. For example: + +@example +attach /dev/ttyd +@end example + +@noindent +if the serial line is connected to the device named @file{/dev/ttyd}. This +will stop the remote machine if it is not already stopped. + +Now you can use all the usual commands to examine and change data and to +step and continue the remote program. + +To resume the remote program and stop debugging it, use the @samp{detach} +command. + +@node Commands, Concepts, Remote, Top +@unnumbered Command Index + +@printindex ky + +@node Concepts,, Commands, Top +@unnumbered Concept Index + +@printindex cp + +@contents +@bye |