diff options
Diffstat (limited to 'gdb/RCS/gdb.texinfo,v')
| -rw-r--r-- | gdb/RCS/gdb.texinfo,v | 3009 |
1 files changed, 0 insertions, 3009 deletions
diff --git a/gdb/RCS/gdb.texinfo,v b/gdb/RCS/gdb.texinfo,v deleted file mode 100644 index ff38f18..0000000 --- a/gdb/RCS/gdb.texinfo,v +++ /dev/null @@ -1,3009 +0,0 @@ -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. -@ |