diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 3520 |
1 files changed, 3520 insertions, 0 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo new file mode 100644 index 0000000..3de98f5 --- /dev/null +++ b/gdb/doc/gdb.texinfo @@ -0,0 +1,3520 @@ +\input texinfo +@setfilename gdb.info +@settitle GDB, The GNU Debugger +@synindex ky cp +@ifinfo +This file documents the GNU debugger GDB. + +Copyright (C) 1988, 1989 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@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 +section entitled ``GNU General Public License'' is 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 section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end ifinfo + +@setchapternewpage odd +@settitle GDB Manual +@titlepage +@sp 6 +@center @titlefont{GDB Manual} +@sp 1 +@center The GNU Source-Level Debugger +@sp 4 +@center Third Edition, GDB version 3.4 +@sp 1 +@center October 1989 +@sp 5 +@center Richard M. Stallman +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is 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 section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end titlepage +@page + +@node Top, Top, Top, (DIR) +@unnumbered Summary of GDB + +The purpose of a debugger such as GDB is to allow you to execute another +program while examining what is going on inside it. We call the other +program ``your program'' or ``the program being debugged''. + +GDB can do four kinds of things (plus other things in support of these): + +@enumerate +@item +Start the program, specifying anything that might affect its behavior. + +@item +Make the program stop on specified conditions. + +@item +Examine what has happened, when the program has stopped, so that you +can see bugs happen. + +@item +Change things in the program, so you can correct the effects of one bug +and go on to learn about another without having to recompile first. +@end enumerate + +GDB can be used to debug programs written in C and C++. Pascal support +is being implemented, and Fortran support will be added when a GNU +Fortran compiler is written. + +@menu +* License:: The GNU General Public License gives you permission + to redistribute GDB on certain terms; and also + explains that there is no warranty. +* User Interface:: GDB command syntax and input and output 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, User Interface, Top, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 1, February 1989 + +@display +Copyright @copyright{} 1989 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The license agreements of most software companies try to keep users +at the mercy of those companies. By contrast, our General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. The +General Public License applies to the Free Software Foundation's +software and to any other program whose authors commit to using it. +You can use it for your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Specifically, the General Public License is designed to make +sure that you have the freedom to give away or sell copies of free +software, that you receive source code or can get it if you want it, +that you can change the software or use pieces of it in new free +programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of a such a program, whether +gratis or for a fee, 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. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS +@end iftex +@ifinfo +@center TERMS AND CONDITIONS +@end ifinfo + +@enumerate +@item +This License Agreement applies to any program or other work which +contains a notice placed by the copyright holder saying it may be +distributed under the terms of this General Public License. The +``Program'', below, refers to any such program or work, and a ``work based +on the Program'' means either the Program or any work containing the +Program or a portion of it, either verbatim or with modifications. Each +licensee is addressed as ``you''. + +@item +You may copy and distribute verbatim copies of the Program's source +code as you receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice and +disclaimer of warranty; keep intact all the notices that refer to this +General Public License and to the absence of any warranty; and give any +other recipients of the Program a copy of this General Public License +along with the Program. You may charge a fee for the physical act of +transferring a copy. + +@item +You may modify your copy or copies of the Program 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 the Program or any part thereof, either +with or without modifications, to be licensed at no charge to all +third parties under the terms of this General Public License (except +that you may choose to grant warranty protection to some or all +third parties, at your option). + +@item +If the modified program normally reads commands interactively when +run, you must cause it, when started running for such interactive use +in the simplest and most usual way, to print or display an +announcement including an appropriate copyright notice and a notice +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 General +Public License. + +@item +You may charge a 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 independent work with the Program (or its +derivative) on a volume of a storage or distribution medium does not bring +the other work under the scope of these terms. + +@item +You may copy and distribute the Program (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 charge +for the cost of distribution) 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 + +Source code for a work means the preferred form of the work for making +modifications to it. 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, or for standard header files or definitions files that +accompany that operating system. + +@item +You may not copy, modify, sublicense, distribute or transfer the +Program except as expressly provided under this General Public License. +Any attempt otherwise to copy, modify, sublicense, distribute or transfer +the Program is void, and will automatically terminate your rights to use +the Program under this License. However, parties who have received +copies, or rights to use copies, from you under this General Public +License will not have their licenses terminated so long as such parties +remain in full compliance. + +@item +By copying, distributing or modifying the Program (or any work based +on the Program) you indicate your acceptance of this license to do so, +and all its terms and conditions. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the original +licensor to copy, distribute or modify the Program subject to these +terms and conditions. You may not impose any further restrictions on the +recipients' exercise of the rights granted herein. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of the license which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +the license, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``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 +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL +ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT +LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES +SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE +WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to humanity, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively convey +the exclusion of warranty; and each file should have at least the +``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 1, or (at your option) +any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items---whatever suits your +program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright interest in the +program `Gnomovision' (a program to direct compilers to make passes +at assemblers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +That's all there is to it! + +@node User Interface, Files, License, Top +@chapter GDB Input and Output 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. For example, the command +@samp{step} accepts an argument which is the number of times to step, +as in @samp{step 5}. You can also use the @samp{step} command with +no arguments. Some command names do not allow any arguments. + +@cindex abbreviation +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. + +@cindex repeating 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}). + +@cindex prompt +GDB indicates its readiness to read a command by printing a string +called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can +change the prompt string with the @samp{set prompt} command. For +instance, when debugging GDB with GDB, it is useful to change the prompt +in one of the GDBs so that you tell which one you are talking to. + +@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. + +@cindex screen size +@cindex pauses in output +Certain commands to GDB may produce large amounts of information output +to the screen. To help you read all of it, GDB pauses and asks you for +input at the end of each page of output. Type @key{RET} when you want +to continue the output. Normally GDB knows the size of the screen from +on the termcap data base together with the value of the @code{TERM} +environment variable; if this is not correct, you can override it with +the @samp{set screensize} command: + +@table @code +@item set screensize @var{lpp} +@itemx set screensize @var{lpp} @var{cpl} +@kindex set screensize +Specify a screen height of @var{lpp} lines and (optionally) a width of +@var{cpl} characters. If you omit @var{cpl}, the width does not change. + +If you specify a height of zero lines, GDB will not pause during output +no matter how long the output is. This is useful if output is to a file +or to an editor buffer. +@end table + +Also, GDB may at times produce more information about its own workings +than is of interest to the user. Some of these informational messages +can be turned on and off with the @samp{set verbose} command: + +@table @code +@kindex set verbose +@item set verbose off +Disables GDB's output of certain informational messages. + +@item set verbose on +Re-enables GDB's output of certain informational messages. +@end table + +Currently, the messages controlled by @samp{set verbose} are those which +announce that the symbol table for a source file is being read +(@pxref{File Commands}, in the description of the command +@samp{symbol-file}). +@c The following is the right way to do it, but emacs 18.55 doesn't support +@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo +@c is released. +@ignore +see @samp{symbol-file} in @ref{File Commands}). +@end ignore + +@node Files, Compilation, User Interface, Top +@chapter Specifying GDB's Files + +@cindex core dump file +@cindex executable file +@cindex symbol table +GDB needs to know the file name of the program to be debugged, both in +order to read its symbol table and in order to start the program. To +debug a core dump of a previous run, GDB must be told the file name 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 options and arguments for +invoking 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 @code{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}. @code{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. + +The @samp{symbol-file} command does not actually read the symbol table in +full right away. Instead, it scans the symbol table quickly to find +which source files and which symbols are present. The details are read +later, one source file at a time, when they are needed. + +The purpose of this two-stage reading strategy is to make GDB start up +faster. For the most part, it is invisible except for occasional +messages telling you that the symbol table details for a particular +source file are being read. (The @samp{set verbose} command controls +whether these messages are printed; @pxref{User Interface}). + +However, you will sometimes see in backtraces lines for functions in +source files whose data has not been read in; these lines omit some of +the information, such as argument values, which cannot be printed +without full details of the symbol table. + +When the symbol table is stored in COFF format, @samp{symbol-file} does +read the symbol table data in full right away. We haven't bothered to +implement the two-stage strategy for COFF. + +@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. + +Note that the core file is ignored when your program is actually running +under GDB. So, if you have been running the program and you wish to +debug a core file instead, you must kill the subprocess in which the +program is running. To do this, use the @samp{kill} command +(@pxref{Kill Process}). + +@item add-file @var{filename} @var{address} +@kindex add-file +@cindex dynamic linking +The @samp{add-file} command reads additional symbol table information +from the file @var{filename}. You would use this when that file has +been dynamically loaded into the program that is running. @var{address} +should be the memory address at which the file has been loaded; GDB cannot +figure this out for itself. + +The symbol table of the file @var{filename} is added to the symbol table +originally read with the @samp{symbol-file} command. You can use the +@samp{add-file} command any number of times; the new symbol data thus +read keeps adding to the old. The @samp{symbol-file} command forgets +all the symbol data GDB has read; that is the only time symbol data is +forgotten in GDB. + +@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 Compilation, Running, Files, 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. + +GDB no longer supports the debugging information produced by giving the +GNU C compiler the @samp{-gg} option, so do not use this option. + +@ignore +@comment As far as I know, there are no cases in which GDB will +@comment produce strange output in this case. (but no promises). +If your program includes archives made with the @code{ar} program, and +if the object files used as input to @code{ar} were compiled without the +@samp{-g} option and have names longer than 15 characters, GDB will get +confused reading the program's symbol table. No error message will be +given, but GDB may behave strangely. The reason for this problem is a +deficiency in the Unix archive file format, which cannot represent file +names longer than 15 characters. + +To avoid this problem, compile the archive members with the @samp{-g} +option or use shorter file names. Alternatively, use a version of GNU +@code{ar} dated more recently than August 1989. +@end ignore + +@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 this +information, which you must do @i{before} starting the program. (You +can change it after starting the program, but such changes do not affect +the program unless you start it over again.) This information may be +divided into three categories: + +@table @asis +@item The @i{arguments.} +You specify the arguments to give the program as the arguments of the +@samp{run} command. + +@item The @i{environment.} +The program normally inherits its environment from GDB, but you can +use the GDB commands @samp{set environment} and +@samp{unset environment} to change parts of the environment that will +be given to the program.@refill + +@item The @i{working directory.} +The program inherits its working directory from GDB. You can set GDB's +working directory with the @samp{cd} command in GDB. +@end table + +After the @samp{run} command, the debugger does nothing but wait for your +program to stop. @xref{Stopping}. + +Note that once your program has been started by the @samp{run} command, +you may evaluate expressions that involve calls to functions in the +inferior. @xref{Expressions}. If you wish to evaluate a function +simply for its side affects, you may use the @samp{set} command. +@xref{Assignment}. + +@menu +* Arguments:: Specifying the arguments for your program. +* Environment:: Specifying the environment for your program. +* Working Directory:: Specifying the working directory for giving + to your program when it is run. +* Input/Output:: Specifying the program's standard input and output. +* Attach:: Debugging a process started outside GDB. +* Kill Process:: Getting rid of the child process running your program. +@end menu + +@node Arguments, Environment, Running, Running +@section Your Program's Arguments + +@cindex arguments (to your program) +The arguments to your program are specified by 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} +@itemx set environment @var{varname} = @var{value} +@kindex set environment +Sets environment variable @var{varname} to @var{value}, for your program +only, not for GDB itself. @var{value} may be any string; the values of +environment variables are just strings, and any interpretation is +supplied by your program itself. The @var{value} parameter is optional; +if it is eliminated, the variable is set to a null value. This command +can be abbreviated as short as @samp{set e}. + +For example, this command: + +@example +set env USER = foo +@end example + +@noindent +tells the program, when subsequently run, to assume it is being run +on behalf of the user named @samp{foo}. + +@item delete environment @var{varname} +@itemx unset environment @var{varname} +@kindex delete environment +@kindex unset environment +Remove variable @var{varname} from the environment to be passed to your +program. This is different from @samp{set env @var{varname}@ =} because +@samp{delete environment} leaves the variable with no value, which is +distinguishable from an empty value. This command can be abbreviated +@samp{d e}. +@end table + +@node Working Directory, Input/Output, Environment, Running +@section Your Program's Working Directory + +@cindex working directory (of your program) +Each time you start your program with @samp{run}, it inherits its +working directory from the current working directory of GDB. GDB's +working directory is initially whatever it inherited from its parent +process (typically the shell), but you can specify a new working +directory in GDB with the @samp{cd} command. + +The GDB working directory also serves as a default for the commands +that specify files for GDB to operate on. @xref{Files}. + +@table @code +@item cd @var{directory} +@kindex cd +Set GDB's working directory to @var{directory}. + +@item pwd +@kindex pwd +Print GDB's working directory. +@end table + +@node Input/Output, Attach, Working Directory, Running +@section Your Program's Input and Output + +@cindex redirection +@cindex controlling terminal +By default, the program you run under GDB does input and output to the same +terminal that GDB uses. + +You can redirect the program's input and/or output using @samp{sh}-style +redirection commands in the @samp{run} command. For example, + +@example +run > outfile +@end example + +@noindent +starts the program, diverting its output to the file @file{outfile}. + +@kindex tty +Another way to specify where the program should do input and output is +with the @samp{tty} command. This command accepts a file name as +argument, and causes this file to be the default for future @samp{run} +commands. It also resets the controlling terminal for the child +process, for future @samp{run} commands. For example, + +@example +tty /dev/ttyb +@end example + +@noindent +directs that processes started with subsequent @samp{run} commands +default to do input and output on the terminal @file{/dev/ttyb} and have +that as their controlling terminal. + +An explicit redirection in @samp{run} overrides the @samp{tty} command's +effect on input/output redirection, but not its effect on the +controlling terminal. + +When you use the @samp{tty} command or redirect input in the @samp{run} +command, only the @emph{input for your program} is affected. The input +for GDB still comes from your terminal. + +@node Attach, Kill Process, Input/Output, Running +@section Debugging an Already-Running Process +@kindex detach +@kindex attach +@cindex attach + +Some operating systems allow GDB to debug an already-running process +that was started outside of GDB. To do this, you 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 @code{ps} utility.) + +The first thing GDB does after arranging to debug the process is to stop +it. You can examine and modify an attached process with all the GDB +commands that ordinarily available when you start processes with +@samp{run}. You can insert breakpoints; you can step and continue; you +can modify storage. If you would rather the process continue running, +you may use the @samp{continue} command after attaching GDB to the +process. + +When you have 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. + +The @samp{attach} command is also used to debug a remote machine via a +serial connection. @xref{Remote}, for more info. + +@node Kill Process,, Attach, Running +@section Killing the Child Process + +@table @code +@item kill +@kindex kill +Kill the child process in which the program being debugged is running +under GDB. + +This command is useful 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 make sure the core dump file +is used once again. + +It is also useful if you wish to run the program outside the debugger +for once and then go back to debugging it. + +The @samp{kill} command is also useful if you wish to recompile and +relink the program, since on many systems it is impossible to modify an +executable file which is running in a process. But, in this case, it is +just as good to exit GDB, since you will need to read a new symbol table +after the program is recompiled if you wish to debug the new version, +and restarting GDB is the easiest way to do that. +@end table + +@node Stopping, Stack, Running, Top +@chapter Stopping and Continuing + +When you run a program normally, it runs until it terminates. The +principal 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 +investigate and 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 +@cindex 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). + +@cindex fatal signals +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. + +@cindex handling signals +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. + +@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{signal} @var{keywords}@dots{} +@kindex handle +Change the way GDB handles signal @var{signal}. @var{signal} can be the +number of a signal or its name (with or without the @samp{SIG} at the +beginning). The @var{keywords} say what change to make. +@end table + +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 +deleted, 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 @code{$_} +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. +* Delete 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, Delete 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{+offset} +@itemx break @var{-offset} +Set a breakpoint some number of lines forward or back from the position +at which execution stopped in the currently selected frame. + +@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 file name as well as a function name is +superfluous except when multiple files contain similarly named +functions. + +@item break *@var{address} +Set a breakpoint at address @var{address}. You can use this to set +breakpoints in parts of the program which do not have debugging +information or source files. + +@item break +Set a breakpoint at the next instruction to be executed in the selected +stack frame (@pxref{Stack}). In any selected frame but the innermost, +this will cause the program to stop as soon as control returns to that +frame. This is equivalent to a @samp{finish} command in the frame +inside the selected frame. If this is done in the innermost frame, GDB +will stop the next time it reaches the current location; this may be +useful inside of loops. + +GDB normally ignores breakpoints when it resumes execution, until at +least one instruction has been executed. If it did not do this, you +would be unable to proceed past a breakpoint without first disabling the +breakpoint. This rule applies whether or not the breakpoint already +existed when the program stopped. + +@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 disabled the first time it +is hit. @xref{Disabling}. +@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 Delete Breaks, Disabling, Set Breaks, Breakpoints +@subsection Deleting Breakpoints + +@cindex clearing breakpoint +@cindex deleting 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{deleting} the breakpoint. A breakpoint that has been deleted no +longer exists in any sense; it is forgotten. + +With the @samp{clear} command you can delete breakpoints according to where +they are in the program. With the @samp{delete} command you can delete +individual breakpoints by specifying their breakpoint numbers. + +@b{It is not necessary to delete a breakpoint to proceed past it.} GDB +automatically ignores breakpoints in the first instruction to be executed +when you continue execution without changing the execution address. + +@table @code +@item clear +@kindex clear +Delete 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 delete a breakpoint that the program +just stopped at. + +@item clear @var{function} +@itemx clear @var{filename}:@var{function} +Delete any breakpoints set at entry to the function @var{function}. + +@item clear @var{linenum} +@itemx clear @var{filename}:@var{linenum} +Delete 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. +@end table + +@node Disabling, Conditions, Delete Breaks, Breakpoints +@subsection Disabling Breakpoints + +@cindex disabled breakpoints +@cindex enabled breakpoints +Rather than deleting a breakpoint, you might prefer to @dfn{disable} it. +This makes the breakpoint inoperative as if it had been deleted, but +remembers the information on the breakpoint so that you can @dfn{enable} +it again later. + +You disable and enable breakpoints with the @samp{enable} and +@samp{disable} commands, specifying one or more breakpoint numbers as +arguments. Use @samp{info break} to print a list of breakpoints if you +don't know which breakpoint numbers to use. + +A breakpoint can have any of four different states of enablement: + +@itemize @bullet +@item +Enabled. The breakpoint will stop the program. A breakpoint made +with the @samp{break} command starts out in this state. +@item +Disabled. The breakpoint has no effect on the program. +@item +Enabled once. The breakpoint will stop the program, but +when it does so it will become disabled. A breakpoint made +with the @samp{tbreak} command starts out in this state. +@item +Enabled for deletion. The breakpoint will stop the program, but +immediately after it does so it will be deleted permanently. +@end itemize + +You change the state of enablement of a breakpoint with the following +commands: + +@table @code +@item disable breakpoints @var{bnums}@dots{} +@itemx disable @var{bnums}@dots{} +@kindex disable breakpoints +@kindex disable +Disable the specified breakpoints. A disabled breakpoint has no +effect but is not forgotten. All options such as ignore-counts, +conditions and commands are remembered in case the breakpoint is +enabled again later. + +@item enable breakpoints @var{bnums}@dots{} +@itemx enable @var{bnums}@dots{} +@kindex enable breakpoints +@kindex enable +Enable the specified breakpoints. They become effective once again in +stopping the program, until you specify otherwise. + +@item enable breakpoints once @var{bnums}@dots{} +@itemx enable once @var{bnums}@dots{} +Enable the specified breakpoints temporarily. Each will be disabled +again the next time it stops the program (unless you have used one of +these commands to specify a different state before that time comes). + +@item enable breakpoints delete @var{bnums}@dots{} +@itemx 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 conditional breakpoints +@cindex breakpoint conditions + +The simplest sort of breakpoint breaks every time the program reaches a +specified place. You can also specify a @dfn{condition} for a +breakpoint. A condition is just a boolean expression in your +programming language. (@xref{Expressions}). A breakpoint with a +condition evaluates the expression each time the program reaches it, and +the program stops only if the condition is true. + +Break conditions may have side effects, and may even call functions in your +program. These may sound like strange things to do, but their effects are +completely predictable unless there is another enabled breakpoint at the +same address. (In that case, GDB might see the other breakpoint first and +stop the program without checking the condition of this one.) Note that +breakpoint commands are usually more convenient and flexible for the +purpose of performing side effects when a breakpoint is reached +(@pxref{Break Commands}). + +Break conditions can be specified when a breakpoint is set, by using +@samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}. +They can also be changed at any time with the @samp{condition} command: + +@table @code +@item condition @var{bnum} @var{expression} +@kindex condition +Specify @var{expression} as the break condition for breakpoint number +@var{bnum}. From now on, this breakpoint will stop the program only if +the value of @var{expression} is true (nonzero, in C). @var{expression} +is not evaluated at the time the @samp{condition} command is given. +@xref{Expressions}. + +@item condition @var{bnum} +Remove the condition from breakpoint number @var{bnum}. It becomes +an ordinary unconditional breakpoint. +@end table + +@cindex ignore count (of breakpoint) +A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the @dfn{ignore +count} of the breakpoint. Every breakpoint has an ignore count, which +is an integer. Most of the time, the ignore count is zero, and +therefore has no effect. But if the program reaches a breakpoint whose +ignore count is positive, then instead of stopping, it just decrements +the ignore count by one and continues. As a result, if the ignore count +value is @var{n}, the breakpoint will not stop the next @var{n} times it +is reached. + +@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. +Thus, the program will not stop at this breakpoint until the +@var{count}'th time it is reached. + +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 @w{@samp{$foo-- <= 0}} using a debugger convenience +variable that is decremented each time. @xref{Convenience Vars}. + +@node Break Commands, Error in Breakpoints, Conditions, Breakpoints +@subsection Commands Executed on Breaking + +@cindex breakpoint commands +You can give any breakpoint a series of commands to execute when the +program stops due to that breakpoint. For example, you might want to +print the values of certain expressions, or enable other breakpoints. + +@table @code +@item commands @var{bnum} +Specify commands for breakpoint number @var{bnum}. The commands +themselves appear on the following lines. Type a line containing just +@samp{end} to terminate the commands. + +To remove all commands from a breakpoint, use the command +@samp{commands} and follow it immediately by @samp{end}; that is, give +no commands. + +With no arguments, @samp{commands} refers to the last breakpoint set. +@end table + +It is possible for breakpoint commands to start the program up again. +Simply use the @samp{cont} command, or @samp{step}, or any other command +to resume execution. However, any remaining breakpoint commands are +ignored. When the program stops again, GDB will act according to the +cause of that stop. + +@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. + +@example +break foo if x>0 +commands +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 +silent +set x = y + 4 +cont +end +@end example + +One deficiency in the operation of automatically continuing breakpoints +under Unix appears when your program uses raw mode for the terminal. +GDB switches back to its own terminal modes (not raw) before executing +commands, and then must switch back to raw mode when your program is +continued. This causes any pending terminal input to be lost. + +In the GNU system, this will be fixed by changing the behavior of +terminal modes. + +Under Unix, when you have this problem, you might be able to get around +it by putting your actions into the breakpoint condition instead of +commands. For example + +@example +condition 5 (x = y + 4), 0 +@end example + +@noindent +specifies a condition expression (@xref{Expressions}) that will change +@code{x} as needed, then always have the value 0 so the program will not +stop. Loss of input is avoided here because break conditions are +evaluated without changing the terminal modes. When you want to have +nontrivial conditions for performing the side effects, the operators +@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. + +@node Error in Breakpoints,, Break Commands, Breakpoints +@subsection ``Cannot Insert Breakpoints'' Error + +Under some operating systems, breakpoints cannot be used in a program if +any other process is running that program. Attempting to run or +continue the program with a breakpoint in this case will cause GDB to +stop it. + +When this happens, you have three ways to proceed: + +@enumerate +@item +Remove or disable the breakpoints, then continue. + +@item +Suspend GDB, and copy the file containing the program to a new name. +Resume GDB and use the @samp{exec-file} command to specify that GDB +should run the program under that name. Then start the program again. + +@item +Relink the program so that the text segment is nonsharable, using the +linker option @samp{-N}. The operating system limitation may not apply +to nonsharable executables. +@end enumerate + +@node Continuing, Stepping, Breakpoints, Stopping +@section Continuing + +After your program stops, most likely you will want it to run some more if +the bug you are looking for has not happened yet. + +@table @code +@item cont +@kindex cont +Continue running the program at the place where it stopped. +@end table + +If the program stopped at a breakpoint, the place to continue running +is the address of the breakpoint. You might expect that continuing would +just stop at the same breakpoint immediately. In fact, @samp{cont} +takes special care to prevent that from happening. You do not need +to delete 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 +Continue running the program until control reaches a different line, +then stop it and return control to the debugger. This command is +abbreviated @samp{s}. + +This command may be given when control is within a function for which +there is no debugging information. In that case, execution will proceed +until control reaches a different function, or is about to return from +this function. An argument repeats this action. + +@item step @var{count} +Continue running as in @samp{step}, but do so @var{count} times. If a +breakpoint is reached or a signal not related to stepping occurs 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}. + +@samp{next} within a function without debugging information acts as does +@samp{step}, but any function calls appearing within the code of the +function are executed without stopping. + +@item finish +@kindex finish +Continue running until just after the selected stack frame returns (or +until there is some other reason to stop, such as a fatal signal or a +breakpoint). Print value returned by the selected stack frame (if any). + +Contrast this with the @samp{return} command (@pxref{Returning}). + +@item until +@kindex until +This command is used to avoid single stepping through a loop more than +once. It is like the @samp{next} command, except that when @samp{until} +encounters a jump, it automatically continues execution until the +program counter is greater than the address of the jump. + +This means that when you reach the end of a loop after single stepping +though it, @samp{until} will cause the program to continue execution +until the loop is exited. In contrast, a @samp{next} command at the end +of a loop will simply step back to the beginning of the loop, which +would force you to step through the next iteration. + +@samp{until} always stops the program if it attempts to exit the current +stack frame. + +@samp{until} may produce somewhat counterintuitive results if the order +of the source lines does not match the actual order of execution. For +example, in a typical C @code{for}-loop, the third expression in the +@code{for}-statement (the loop-step expression) is executed after the +statements in the body of the loop, but is written before them. +Therefore, the @samp{until} command would appear to step back to the +beginning of the loop when it advances to this expression. However, it +has not really done so, not in terms of the actual machine code. + +Note that @samp{until} with no argument works by means of single +instruction stepping, and hence is slower than @samp{until} with an +argument. + +@item until @var{location} +Continue running the program until either the specified location is +reached, or the current (innermost) stack frame returns. This form of +the command uses breakpoints, and hence is quicker than @samp{until} +without an argument. + +@item stepi +@itemx si +@kindex stepi +@kindex si +Execute 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 +Execute 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 +@cindex stack frame +The call stack is divided up into contiguous pieces called @dfn{stack +frames}, or @dfn{frames} for short; 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. + +@cindex frameless execution +Some functions can be compiled to run without a frame reserved for them +on the stack. This is occasionally done with heavily used library +functions to save the frame setup time. GDB has limited facilities for +dealing with these function invocations; if the innermost function +invocation has no stack frame, GDB will give it a virtual stack frame of +0 and correctly allow tracing of the function call chain. Results are +undefined if a function invocation besides the innermost one is +frameless. + +@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 +@kindex backtrace +@kindex 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 print only the innermost @var{n} frames. + +@item backtrace @var{-n} +@itemx bt @var{-n} +Similar, but print only the outermost @var{n} frames. +@end table + +@kindex where +@kindex info stack +The names @samp{where} and @samp{info stack} are additional aliases +for @samp{backtrace}. + +Every line in the backtrace shows the frame number, the function name +and the program counter value. + +If the function is in a source file whose symbol table data has been +fully read, the backtrace shows the source file name and line number, as +well as the arguments to the function. (The program counter value is +omitted if it is at the beginning of the code for that line number.) + +If the source file's symbol data has not been fully read, just scanned, +this extra information is replaced with an ellipsis. You can force the +symbol data for that frame's source file to be read by selecting the +frame. (@xref{Selection}). + +Here is an example of a backtrace. It was made with the command +@samp{bt 3}, so it shows the innermost three frames. + +@example +#0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) (/gp/rms/cc/rtlanal.c line 337) +#1 0x246b0 in expand_call (...) (...) +#2 0x21cfc in expand_expr (...) (...) +(More stack frames follow...) +@end example + +@noindent +The functions @code{expand_call} and @code{expand_expr} are in a file +whose symbol details have not been fully read. Full detail is available +for the function @code{rtx_equal_p}, which is in the file +@file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown +with their typed values. + +@node Selection, Frame Info, Backtrace, Stack +@section Selecting a Frame + +Most commands for examining the stack and other data in the program work on +whichever stack frame is selected at the moment. Here are the commands for +selecting a stack frame; all of them finish by printing a brief description +of the stack frame just selected. + +@table @code +@item frame @var{n} +@kindex frame +Select frame number @var{n}. Recall that frame zero is the innermost +(currently executing) frame, frame one is the frame that called the +innermost one, and so on. The highest-numbered frame is @code{main}'s +frame. + +@item frame @var{addr} +Select the frame at address @var{addr}. This is useful mainly if the +chaining of stack frames has been damaged by a bug, making it +impossible for GDB to assign numbers properly to all frames. In +addition, this can be useful when the program has multiple stacks and +switches between them. + +@item up @var{n} +@kindex up +Select the frame @var{n} frames up from the frame previously selected. +For positive numbers @var{n}, this advances toward the outermost +frame, to higher frame numbers, to frames that have existed longer. +@var{n} defaults to one. + +@item down @var{n} +@kindex down +Select the frame @var{n} frames down from the frame previously +selected. For positive numbers @var{n}, this advances toward the +innermost frame, to lower frame numbers, to frames that were created +more recently. @var{n} defaults to one. +@end table + +All of these commands end by printing some information on the frame that +has been selected: the frame number, the function name, the arguments, the +source file and line number of execution in that frame, and the text of +that source line. For example: + +@example +#3 main (argc=3, argv=??, env=??) at main.c, line 67 +67 read_input_file (argv[i]); +@end example + +After such a printout, the @samp{list} command with no arguments will print +ten lines centered on the point of execution in the frame. @xref{List}. + +@node Frame Info,, Selection, Stack +@section Information on a Frame + +There are several other commands to print information about the selected +stack frame. + +@table @code +@item frame +This command prints a brief description of the selected stack frame. +It can be abbreviated @samp{f}. With an argument, this command is +used to select a stack frame; with no argument, it does not change +which frame is selected, but still prints the same information. + +@item info frame +@kindex info frame +This command prints a verbose description of the selected stack frame, +including the address of the frame, the addresses of the next frame in +(called by this frame) and the next frame out (caller of this frame), +the address of the frame's arguments, the program counter saved in it +(the address of execution in the caller frame), and which registers +were saved in the frame. The verbose description is useful when +something has gone wrong that has made the stack format fail to fit +the usual conventions. + +@item info frame @var{addr} +Print a verbose description of the frame at address @var{addr}, +without selecting that frame. The selected frame remains unchanged by +this command. + +@item info args +@kindex info args +Print the arguments of the selected frame, each on a separate line. + +@item info locals +@kindex info locals +Print the local variables of the selected frame, each on a separate +line. These are all variables declared static or automatic within all +program blocks that execution in this frame is currently inside of. +@end table + +@node Source, Data, Stack, Top +@chapter Examining Source Files + +GDB knows which source files your program was compiled from, and +can print parts of their text. When your program stops, GDB +spontaneously prints the line it stopped in. Likewise, when you +select a stack frame (@pxref{Selection}), GDB prints the line +which execution in that frame has stopped in. You can also +print parts of source files by explicit command. + +@menu +* List:: Using the @samp{list} command to print source files. +* Search:: Commands for searching source files. +* Source Path:: Specifying the directories to search for source files. +@end menu + +@node List, Search, Source, Source +@section Printing Source Lines + +@kindex list +To print lines from a source file, use the @samp{list} command +(abbreviated @samp{l}). There are several ways to specify what part +of the file you want to print. + +Here are the forms of the @samp{list} command most commonly used: + +@table @code +@item list @var{linenum} +Print ten lines centered around line number @var{linenum} in the +current source file. + +@item list @var{function} +Print ten lines centered around the beginning of function +@var{function}. + +@item list +Print ten more lines. If the last lines printed were printed with a +@samp{list} command, this prints ten lines following the last lines +printed; however, if the last line printed was a solitary line printed +as part of displaying a stack frame (@pxref{Stack}), this prints ten +lines centered around that line. + +@item list - +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. + +@cindex linespec +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 - +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 @code +@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 -@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 @code{$_} +(@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 +from which they were compiled, 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. @b{Note that the executable search path is +@i{not} used for this purpose. Neither is the current working +directory, unless it happens to be in the source path.} + +@kindex directory +When you start GDB, its source path contains just the current working +directory. To add other directories, use the @samp{directory} command. + +@table @code +@item directory @var{dirnames...} +Add directory @var{dirname} to the end of the source path. Several +directory names may be given to this command, separated by whitespace or +@samp{:}. + +@item directory +Reset the source path to just the current working directory of GDB. +This requires confirmation. + +Since this command deletes directories from the search path, it may +change the directory in which a previously read source file will be +discovered. 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 to examine 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. +* Format Options:: Controlling how structures and arrays are printed. +* Output formats:: Specifying formats for printing values. +* Memory:: Examining memory explicitly. +* Auto Display:: Printing certain expressions whenever program stops. +* Value History:: Referring to values previously printed. +* Convenience Vars:: Giving names to values for future reference. +* Registers:: Referring to and storing in machine registers. +@end menu + +@node Expressions, Variables, Data, Data +@section Expressions + +@cindex expressions +Many different GDB commands accept an expression and compute its value. +Any kind of constant, variable or operator defined by the programming +language you are using is legal in an expression in GDB. This includes +conditional expressions, function calls, casts and string constants. +It unfortunately does not include symbols defined by preprocessor +@code{#define} commands. + +Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer so as to examine a structure +at that address in memory. + +GDB supports three kinds of operator in addition to those of programming +languages: + +@table @code +@item @@ +@samp{@@} is a binary operator for treating parts of memory as arrays. +@xref{Arrays}, for more information. + +@item :: +@samp{::} allows you to specify a variable in terms of the file or +function it is defined in. @xref{Variables}. + +@item @{@var{type}@} @var{addr} +Refers to an object of type @var{type} stored at address @var{addr} in +memory. @var{addr} may be any expression whose value is an integer or +pointer (but parentheses are required around nonunary operators, just as in +a cast). This construct is allowed regardless of what kind of data is +officially supposed to reside at @var{addr}.@refill +@end table + +@node Variables, Arrays, Expressions, Data +@section Program Variables + +The most common kind of expression to use is the name of a variable +in your program. + +Variables in expressions are understood in the selected stack frame +(@pxref{Selection}); they must either be global (or static) or be visible +according to the scope rules of the programming language from the point of +execution in that frame. This means that in the function + +@example +foo (a) + int a; +@{ + bar (a); + @{ + int b = test (); + bar (b); + @} +@} +@end example + +@noindent +the variable @code{a} is usable whenever the program is executing +within the function @code{foo}, but the variable @code{b} is visible +only while the program is executing inside the block in which @code{b} +is declared. + +As a special exception, you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable +or function with the same name (if they are in different source files). +In such a case, it is not defined which one you will get. If you wish, +you can specify any one of them using the colon-colon construct: + +@example +@var{block}::@var{variable} +@end example + +@noindent +Here @var{block} is the name of the source file whose variable you want. + +@node Arrays, Format options, 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 Format options, Output formats, Arrays, Data +@section Format options + +@cindex format options +GDB provides a few ways to control how arrays and structures are +printed. + +@table @code +@item info format +@kindex info format +Display the current settings for the format options. + +@item set array-max @var{number-of-elements} +@kindex set array-max +If GDB is printing a large array, it will stop printing after it has +printed the number of elements set by the @samp{set array-max} command. +This limit also applies to the display of strings. + +@item set prettyprint on +@kindex set prettyprint +Cause GDB to print structures in an indented format with one member per +line, like this: + +@example +$1 = @{ + next = 0x0, + flags = @{ + sweet = 1, + sour = 1 + @}, + meat = 0x54 "Pork" +@} +@end example + +@item set prettyprint off +Cause GDB to print structures in a compact format, like this: + +@example +$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat = 0x54 "Pork"@} +@end example + +This is the default format. + +@item set unionprint on +@kindex set unionprint +Tell GDB to print unions which are contained in structures. This is the +default setting. +@item set unionprint off +Tell GDB not to print unions which are contained in structures. + +For example, given the declarations + +@example +typedef enum @{Tree, Bug@} Species; +typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; +typedef enum @{Caterpiller, Cocoon, Butterfly@} Bug_forms; + +struct thing @{ + Species it; + union @{ + Tree_forms tree; + Bug_forms bug; + @} form; +@}; + +struct thing foo = @{Tree, @{Acorn@}@}; +@end example + +@noindent +with @samp{set unionprint on} in effect @samp{p foo} would print + +@example +$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} +@end example + +@noindent +and with @samp{set unionprint off} in effect it would print + +@example +$1 = @{it = Tree, form = @{...@}@} +@end example +@end table + +@node Output formats, Memory, Format options, Data +@section Output 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, Output formats, Data +@subsection Examining Memory + +@cindex examining memory +@kindex x +The command @samp{x} (for `examine') can be used to examine memory +without reference to the program's data types. The format in which you +wish to examine memory is instead explicitly specified. The allowable +formats are a superset of the formats described in the previous section. + +@samp{x} is followed by a slash and an output format specification, +followed by an expression for an address. The expression need not have +a pointer value (though it may); it is used as an integer, as the +address of a byte of memory. @xref{Expressions} for more information on +expressions. For example, @samp{x/4xw $sp} prints the four words of +memory above the stack pointer in hexadecimal. + +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 GDB +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. For example, + +@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 @code{$_} and +@code{$__}. + +After an @samp{x} command, the last address examined is available for use +in expressions in the convenience variable @code{$_}. The contents of that +address, as examined, are available in the convenience variable @code{$__}. + +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. + +@kindex disassemble +The specialized command @samp{disassemble} is also provided to dump a +range of memory as machine instructions. The default memory range is +the function surrounding the program counter of the selected frame. A +single argument to this command is a program counter value; the function +surrounding this value will be dumped. Two arguments (separated by one +or more spaces) specify a range of addresss (first inclusive, second +exclusive) to be dumped. + +@node Auto Display, Value History, Memory, Data +@section Automatic Display +@cindex automatic display +@cindex display of expressions + +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. + +If the expression refers to local variables, then it does not make sense +outside the lexical context for which it was set up. Such an expression +is printed only when execution is inside that lexical context. For +example, if you give the command @samp{display name} while inside a +function with an argument @code{name}, then this argument will be +displayed whenever the program stops inside that function, but not when +it stops elsewhere (since this argument doesn't exist elsewhere). + +@table @code +@item display @var{exp} +@kindex display +Add the expression @var{exp} to the list of expressions to display +each time the program stops. @xref{Expressions}. + +@item display/@var{fmt} @var{exp} +For @var{fmt} specifying only a display format and not a size or +count, add the expression @var{exp} to the auto-display list but +arranges to display it each time in the specified format @var{fmt}. + +@item display/@var{fmt} @var{addr} +For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a +number of units, add the expression @var{addr} as a memory address to +be examined each time the program stops. Examining means in effect +doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}. + +@item undisplay @var{dnums}@dots{} +@itemx delete display @var{dnums}@dots{} +@kindex delete display +@kindex undisplay +Remove item numbers @var{dnums} from the list of expressions to display. + +@item disable display @var{dnums}@dots{} +@kindex disable display +Disable the display of item numbers @var{dnums}. A disabled display +item is not printed automatically, but is not forgotten. It may be +reenabled later. + +@item enable display @var{dnums}@dots{} +@kindex enable display +Enable display of item numbers @var{dnums}. It becomes effective once +again in auto display of its expression, until you specify otherwise. + +@item display +Display the current values of the expressions on the list, just as is +done when the program stops. + +@item info display +@kindex info display +Print the list of expressions previously set up to display +automatically, each one with its item number, but without showing the +values. This includes disabled expressions, which are marked as such. +It also includes expressions which would not be displayed right now +because they refer to automatic variables not currently available. +@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 @code{$} +@cindex @code{$$} +@cindex history number +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{num} = } +before the value; here @var{num} 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 @code{$} refers to the most recent value in the history, +and @code{$$} 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 this: + +@example +p *$.next +@end example + +@noindent +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 this command: + +@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 the value of @code{x} has changed. + +@table @code +@item info values +@kindex info values +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 values} does not change the history. + +@item info values @var{n} +Print ten history values centered on history item number @var{n}. + +@item info values + +Print ten history values just after the values last printed. +@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 @code{$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 @code +@item $_ +The variable @code{$_} 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 @code{$_} +to that address; these commands include @samp{info line} and @samp{info +breakpoint}. + +@item $__ +The variable @code{$__} 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 @code{$pc} and @code{$sp} are used on all machines for +the program counter register and the stack pointer. Often @code{$fp} is +used for a register that contains a pointer to the current stack frame, +and @code{$ps} is used for a register that contains the processor +status. These standard register names may be available on your machine +even though the @code{info registers} command displays them with a +different name. For example, on the SPARC, @code{info registers} +displays the processor status register as @code{$psr} but you can also +refer to it as @code{$ps}. + +GDB always considers the contents of an ordinary register as an integer +when the register is examined in this way. Some machines have special +registers which can hold nothing but floating point; these registers are +considered floating point. There is no way to refer to the contents of an +ordinary register as floating point value (although you can @emph{print} +it as a floating point value with @samp{print/f $@var{regname}}). + +Some registers have distinct ``raw'' and ``virtual'' data formats. This +means that the data format in which the register contents are saved by the +operating system is not the same one that your program normally sees. For +example, the registers of the 68881 floating point coprocessor are always +saved in ``extended'' format, but 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 @code{$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 info address @var{symbol} +@kindex info address +Describe where the data for @var{symbol} is stored. For a register +variable, this says which register it is kept in. For a non-register +local variable, 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 a register variables, and for a stack local variable prints +the exact address of the current instantiation of the variable. + +@item whatis @var{exp} +@kindex whatis +Print the data type of expression @var{exp}. @var{exp} is not +actually evaluated, and any side-effecting operations (such as +assignments or function calls) inside it do not take place. +@xref{Expressions}. + +@item whatis +Print the data type of @code{$}, the last value in the value history. + +@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 ptype @var{exp} +Print a description of the type of expression @var{exp}. This is like +@samp{whatis} except it prints a detailed description, instead of just +the name of the type. For example, if the type of a variable is +@samp{struct complex @{double real; double imag;@}}, @samp{whatis} will +print @samp{struct complex} and @samp{ptype} will print @samp{struct +complex @{double real; double imag;@}} + +@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 (i.e., except for local variables). + +@item info variables @var{regexp} +Print the names and data types of all variables (except for local +variables) whose names contain a match for regular expression +@var{regexp}. + +@ignore +Uncomment this only if the implementation is fixed. +@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}. +@end ignore + +@ignore +This was never implemented. +@item info methods +@itemx info methods @var{regexp} +@kindex info methods +The @samp{info-methods} command permits the user to examine all defined +methods within C++ program, or (with the @var{regexp} argument) a +specific set of methods found in the various C++ classes. Many +C++ classes provide a large number of methods. Thus, the output +from the @samp{ptype} command can be overwhelming and hard to use. The +@samp{info-methods} command filters the methods, printing only those +which match the regular-expression @var{regexp}. +@end ignore + +@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 + +Once you think you have find an error in the program, you might want to +find out for certain whether correcting the apparent error would lead to +correct results in the rest of the run. You can find the answer by +experiment, using the GDB features for altering execution of the +program. + +For example, you can store new values into variables or memory +locations, give the program a signal, restart it at a different address, +or even return prematurely from a function to its caller. + +@menu +* Assignment:: Altering variable values or memory contents. +* Jumping:: Altering control flow. +* Signaling:: Making signals happen in the program. +* Returning:: Making a function return prematurely. +@end menu + +@node Assignment, Jumping, Altering, Altering +@section Assignment to Variables + +@cindex assignment +@cindex setting variables +To alter the value of a variable, evaluate an assignment expression. +@xref{Expressions}. For example, + +@example +print x=4 +@end example + +@noindent +would store the value 4 into the variable @code{x}, and then print +the value of the assignment expression (which is 4). + +All the assignment operators of C are supported, including the +incrementation operators @samp{++} and @samp{--}, and combining +assignments such as @samp{+=} and @samp{<<=}. + +@kindex set +@kindex set variable +If you are not interested in seeing the value of the assignment, use the +@samp{set} command instead of the @samp{print} command. @samp{set} is +really the same as @samp{print} except that the expression's value is not +printed and is not put in the value history (@pxref{Value History}). The +expression is evaluated only for side effects. + +Note that if the beginning of the argument string of the @samp{set} command +appears identical to a @samp{set} subcommand, it may be necessary to use +the @samp{set variable} command. This command is identical to @samp{set} +except for its lack of subcommands. + +GDB allows more implicit conversions in assignments than C does; you can +freely store an integer value into a pointer variable or vice versa, and +any structure can be converted to any other structure that is the same +length or shorter. + +To store values 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, @code{@{int@}0x83040} would refer +to memory location 0x83040 as an integer (which implies a certain size +and representation in memory), and + +@example +set @{int@}0x83040 = 4 +@end example + +would store the value 4 into that memory location. + +@node Jumping, Signaling, Assignment, Altering +@section Continuing at a Different Address + +Ordinarily, when you continue the program, you do so at the place where +it stopped, with the @samp{cont} command. You can instead continue at +an address of your own choosing, with the following commands: + +@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 bizarre if the two functions expect different patterns of arguments or +of local variables. For this reason, the @samp{jump} command requests +confirmation if the specified line is not in the function currently +executing. However, even bizarre results are predictable based on +careful study of the machine-language code of the program. + +@item jump *@var{address} +Resume execution at the instruction at address @var{address}. +@end table + +You can get much the same effect as the @code{jump} command by storing a +new value into the register @code{$pc}. The difference is that this +does not start the program running; it only changes the address where it +@emph{will} run when it is continued. For example, + +@example +set $pc = 0x485 +@end example + +@noindent +causes the next @samp{cont} command or stepping command to execute at +address 0x485, rather than at the address where the program stopped. +@xref{Stepping}. + +The most common occasion to use the @samp{jump} command is when you have +stepped across a function call with @code{next}, and found that the +return value is incorrect. If all the relevant data appeared correct +before the function call, the error is probably in the function that +just returned. + +In general, your next step would now be to rerun the program and execute +up to this function call, and then step into it to see where it goes +astray. But this may be time consuming. If the function did not have +significant side effects, you could get the same information by resuming +execution just before the function call and stepping through it. To do this, +first put a breakpoint on that function; then, use the @samp{jump} command +to continue on the line with the function call. + +@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 without +giving a signal. This is useful when the program stopped on account of +a signal and would ordinary see the signal when resumed with the +@samp{cont} command; @samp{signal 0} causes it to resume without a +signal. +@end table + +@node Returning,, Signaling, Altering +@section Returning from a Function + +@cindex returning from a function +@kindex return +You can cancel execution of a function call with the @samp{return} +command. This command has the effect of discarding the selected stack +frame (and all frames within it), so that control moves to the caller of +that function. You can think of this as making the discarded frame +return prematurely. + +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 until the selected stack +frame returns @emph{naturally}. + +@node Sequences, Options, 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 command +A @dfn{user-defined command} is a sequence of GDB commands to which you +assign a new name as a command. This is done with the @samp{define} +command. + +@table @code +@item define @var{commandname} +@kindex define +Define a command named @var{commandname}. If there is already a command +by that name, you are asked to confirm that you want to redefine it. + +The definition of the command is made up of other GDB command lines, +which are given following the @samp{define} command. The end of these +commands is marked by a line containing @samp{end}. + +@item document @var{commandname} +@kindex document +Give documentation to the user-defined command @var{commandname}. The +command @var{commandname} must already be defined. This command reads +lines of documentation just as @samp{define} reads the lines of the +command definition, ending with @samp{end}. After the @samp{document} +command is finished, @samp{help} on command @var{commandname} will print +the documentation you have specified. + +You may use the @samp{document} command again to change the +documentation of a command. Redefining the command with @samp{define} +does not change the documentation. +@end table + +User-defined commands do not take arguments. When they are executed, the +commands of the definition are not printed. An error in any command +stops execution of the user-defined command. + +Commands that would ask for confirmation if used interactively proceed +without asking when used inside a user-defined command. Many GDB commands +that normally print messages to say what they are doing omit the messages +when used in user-defined command. + +@node Command Files, Output, Define, Sequences +@section Command Files + +@cindex command files +A command file for GDB is a file of lines that are GDB commands. Comments +(lines starting with @samp{#}) may also be included. An empty line in a +command file does nothing; it does not mean to repeat the last command, as +it would from the terminal. + +@cindex init file +@cindex @file{.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 +@comment I don't consider backslash-space a standard C escape sequence +@comment because it's not in ANSI. +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.} In addition to the +standard C escape sequences a backslash followed by a space stands for a +space. This is useful for outputting a string with spaces at the +beginning or the end, since leading and trailing spaces are trimmed from +all arguments. Thus, to print @w{`` and foo = ''}, use the command +@w{``echo \ and foo = \ ''}. +@comment AAARGGG! How am I supposed to do @samp{ and foo = } and not +@comment have the spaces be invisible in TeX? + +A backslash at the end of @var{text} can be used, as in C, to continue +the command onto subsequent lines. For example, + +@example +echo This is some text\n\ +which is continued\n\ +onto several lines.\n +@end example + +produces the same output as + +@example +echo This is some text\n +echo which is continued\n +echo onto several lines.\n +@end example + +@item output @var{expression} +@kindex output +Print the value of @var{expression} and nothing but that value: no +newlines, no @samp{$@var{nn} = }. The value is not entered in the +value history either. @xref{Expressions} for more information on +expressions. + +@item output/@var{fmt} @var{expression} +Print the value of @var{expression} in format @var{fmt}. +@xref{Output 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 Options, Emacs, Sequences, Top +@chapter Options and Arguments for GDB + +When you invoke GDB, you can specify arguments 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 0 after processing all the command +files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited). +Exit with nonzero status if an error occurs in executing the GDB +commands in the command files. + +@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 file name, 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} option 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 Emacs, Remote, Options, 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 +GDB as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. + +Using GDB under Emacs 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 C-c C-f +Execute until exit from the selected stack frame, like the GDB +@samp{finish} command. + +@item M-c +@comment C-c C-p in emacs 19 +Continue execution of the program, like the GDB @samp{cont} command. + +@item M-u +@comment C-c C-u in emacs 19 +Go up the number of frames indicated by the numeric argument +(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}), +like the GDB @samp{up} command.@refill + +@item M-d +@comment C-c C-d in emacs 19 +Go down the number of frames indicated by the numeric argument, like the +GDB @samp{down} 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 + +If you are trying to debug a program running on a machine that can't run +GDB in the usual way, it is often useful to use remote debugging. For +example, you might be debugging an operating system kernel, or debugging +a small system which does not have a general purpose operating system +powerful enough to run a full-featured debugger. Currently GDB supports +remote debugging over a serial connection. + +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. Several sample remote debugging drivers are +distributed with GDB; see the @file{README} file in the GDB distribution for +more information. + +@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. + +@ignore +This material will be merged in when better Readline documentation +is done. + +@node GDB Readline, History Top ,Readline Top, Command Editing +@subsection GDB Readline + +You may control the behavior of command line editing in GDB with the +following commands: + +@table @code +@kindex set editing +@item set editing +@itemx set editing on +Enable command line editing (enabled by default). + +@item set editing off +Disable command line editing. + +@kindex set history file +@item set history file @var{filename} +Set the name of the GDB command history file to @var{filename}. This is +the file from which GDB will read an initial command history +list or to which it will write this list when it exits. This list is +accessed through history expansion or through the history +command editing characters listed below. This file defaults to the +value of the environmental variable @code{GDBHISTFILE}, or to +@code{./.gdb_history} if this variable is not set. + +@kindex set history write +@item set history write +@itemx set history write on +Enable the writing of the command history to the command history file +named above. This is enabled by default. + +@item set history write off +Disable the writing of the command history to the command history file. + +@kindex set history size +@item set history size @var{size} +Set the number of commands which GDB will keep in its history list. +This defaults to the value of the environmental variable +@code{HISTSIZE}, or to 256 if this variable is not set. + +@kindex info editing +@item info editing +Display the current settings relating to command line editing, and also +display the last ten commands in the command history. + +@item info editing @var{n} +Print ten commands centered on command number @var{n}. + +@item info editing + +Print ten commands just after the commands last printed. +@end table + +@node GDB History, , History Top, Command editing +@comment node-name, next, previous, up +Note that because of the additional meaning of @code{!} to GDB (as the +logical not operator in C), history expansion is off by default. If you +decide to enable history expansion with the @samp{set history expansion +on} command, you will need to follow @samp{!} with a space or a tab to +prevent it from being expanded. + +The commands to control history expansion are: + +@table @code + +@kindex set history expansion +@item set history expansion on +@itemx set history expansion +Enable history expansion. + +@item set history expansion off +Disable history expansion. History expansion is off by default. + +@end table +@end ignore + +@node Commands, Concepts, Remote, Top +@unnumbered Command Index + +@printindex ky + +@node Concepts, , Commands, Top +@unnumbered Concept Index + +@printindex cp + +@contents +@bye + + + + +Occasionally it is useful to execute a shell command from within GDB. +This can be done with the @samp{shell} command. + +@table @code +@item shell @var{shell command string} +@kindex shell +@cindex shell escape +Directs GDB to invoke an inferior shell to execute @var{shell command string}. +The environment variable @code{SHELL} is used if it exists, otherwise GDB +uses @samp{/bin/sh}. +@end table |