diff options
Diffstat (limited to 'gdb/gdb+.texinfo')
| -rw-r--r-- | gdb/gdb+.texinfo | 2795 |
1 files changed, 0 insertions, 2795 deletions
diff --git a/gdb/gdb+.texinfo b/gdb/gdb+.texinfo deleted file mode 100644 index 0591073..0000000 --- a/gdb/gdb+.texinfo +++ /dev/null @@ -1,2795 +0,0 @@ -\input texinfo -@setfilename ../info/gdb -@settitle GDB+, The GNU Debugger for GNU C++ -@ifinfo -This file documents the GNU debugger GDB+. - -Copyright (C) 1988 Richard M. Stallman. -Modified by Michael Tiemann - -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 for GNU C++ -@sp 4 -@center Second Edition, GDB+ version 2.5.0 -@sp 1 -@center February 1988 -@sp 5 -@center Richard M. Stallman -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1988 Richard M. Stallman. -Modified by Michael Tiemann - -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 - -@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}). - -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 GDB+s 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} -When performing incremental linking, the symbol table of an incrementally -linked file may be included in the link step, but GDB+ needs to be told -where that symbol table is in the address space. By issuing this command, -it is possible to symbolically debug programs which make use of incremental -loading in a completely natural fashion. - -@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}. - -@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} -@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. This command -can be abbreviated as short as @samp{set-e}. - -@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{unset-environment} makes a variable not be defined at -all, which is distinguishable from an empty value. This command can -be abbreviated @samp{unset}. -@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 -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. 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}. An explicit -redirection in @samp{run} overrides the @samp{tty} command. - -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. The program's -controlling terminal is your (GDB's) terminal, not the terminal that the -program is reading from; so if you want to type @kbd{C-c} to stop the -program, you must type it on your (GDB's) terminal. A @kbd{C-c} typed on -the program's terminal is available to the program as ordinary input. - -@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 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}). This is a silly thing to do in -the innermost stack frame because the program would stop immediately -after being started, but it is very useful with another stack frame, -because it will cause the program to stop as soon as control returns -to that frame. - -@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 @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 @var{bnums}@dots{} -@kindex enable -Enable the specified breakpoints. They become effective once again in -stopping the program, until you specify otherwise. - -@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 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. -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. - -@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. -@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+ options 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 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 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. - -When this happens, you have two 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. -@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 -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. - -@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}. - -@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). - -Contrast this with the @samp{return} command (@pxref{Returning}). - -@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. -@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 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 -options 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 @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. - -@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. - -In addition to supporting operators normally found in the C programming -language, GDB+ also supports some C++ constructs. For example, one can -call member functions (GDB+ automatically uses @code{this} when necessary), -and examine and manipulate pointers to members, pointers to member -functions (virtual or otherwise). - -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+ allows pointers to members and pointer to -member functions to be cast to any type and vice-versa. - -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}. It also supports the C++ -convention of qualifying a variable reference according to a type name (or -the global scope). This makes it easy to examing static class variables, -for example. - -@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. - -@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. - -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. - -@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{n} -@kindex undisplay -Remove item number @var{n} from the list of expressions to display. - -@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. Programs can store floating -point values in registers also, but there is currently no GDB+ command -to examine a specified register in floating point. (However, if the -variable in your program which is stored in the register is a floating -point variable, you can see the floating point value by examining -the variable.) - -Some machines have special floating point registers. GDB+ considers these -registers' values as floating point when you examine them explicitly. - -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 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. - -@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 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. -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 -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. - -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 his 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 may be useful when the program has received a signal -and the @samp{cont} command would allow the program to see that -signal. -@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. 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. - -@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 |