diff options
Diffstat (limited to 'gdb/RCS/gdb.texinfo,v')
| -rw-r--r-- | gdb/RCS/gdb.texinfo,v | 3009 |
1 files changed, 3009 insertions, 0 deletions
diff --git a/gdb/RCS/gdb.texinfo,v b/gdb/RCS/gdb.texinfo,v new file mode 100644 index 0000000..ff38f18 --- /dev/null +++ b/gdb/RCS/gdb.texinfo,v @@ -0,0 +1,3009 @@ +head 1.2; +access ; +symbols ; +locks ; strict; +comment @@; + + +1.2 +date 89.02.10.01.41.38; author gnu; state Exp; +branches ; +next 1.1; + +1.1 +date 89.02.10.00.33.03; author gnu; state Exp; +branches ; +next ; + + +desc +@@ + + +1.2 +log +@Improve doc in various ways, mostly xref{Expressions} so you can +find out what an expression is (I had trouble finding it, since +it's in a nested menu somewhere.) +@ +text +@\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 +@ + + +1.1 +log +@Initial revision +@ +text +@d617 3 +a619 2 +inferior. If you wish to evaluate a function simply for it's side +affects, you may use the @@samp{set} command. @@xref{Assignment}. +d1101 4 +a1104 3 +A condition is just a boolean expression in your programming language. +A breakpoint with a condition evaluates the expression each time the +program reaches it, and the program stops only if the condition is true. +d1126 1 +d1259 6 +a1264 5 +is a condition expression 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. +d1269 3 +a1271 3 +Under Unix, 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. +d1875 2 +d2047 2 +a2048 1 +address of a byte of memory. +d2196 1 +a2196 1 +each time the program stops. +d2382 1 +a2382 1 +saved in ``extended'' format, but all C programs expect to work with +d2451 1 +d2544 1 +a2544 1 +For example, +d2628 3 +a2630 3 +no signal. This may be useful when the program has received a signal +and the @@samp{cont} command would allow the program to see that +signal. +d2691 1 +a2691 1 +command definition. After the @@samp{document} command is finished, +d2771 2 +a2772 1 +value history either. +@ |