Return to gdb+.texinfo CVS log

Up to [GNU Debugger] / gdb

Annotation of gdb/gdb+.texinfo, revision 1.1

1.1     ! root        1: \input texinfo
        !             2: @setfilename ../info/gdb
        !             3: @settitle GDB+, The GNU Debugger for GNU C++
        !             4: @ifinfo
        !             5: This file documents the GNU debugger GDB+.
        !             6: 
        !             7: Copyright (C) 1988 Richard M. Stallman.
        !             8: Modified by Michael Tiemann
        !             9: 
        !            10: Permission is granted to make and distribute verbatim copies of
        !            11: this manual provided the copyright notice and this permission notice
        !            12: are preserved on all copies.
        !            13: 
        !            14: @ignore
        !            15: Permission is granted to process this file through Tex and print the
        !            16: results, provided the printed document carries copying permission
        !            17: notice identical to this one except for the removal of this paragraph
        !            18: (this paragraph not being relevant to the printed manual).
        !            19: 
        !            20: @end ignore
        !            21: Permission is granted to copy and distribute modified versions of this
        !            22: manual under the conditions for verbatim copying, provided also that the
        !            23: sections entitled ``Distribution'' and ``GDB General Public License'' are
        !            24: included exactly as in the original, and provided that the entire resulting
        !            25: derived work is distributed under the terms of a permission notice
        !            26: identical to this one.
        !            27: 
        !            28: Permission is granted to copy and distribute translations of this manual
        !            29: into another language, under the above conditions for modified versions,
        !            30: except that the sections entitled ``Distribution'' and ``GDB General Public
        !            31: License'' may be included in a translation approved by the author instead
        !            32: of in the original English.
        !            33: @end ifinfo
        !            34: 
        !            35: @setchapternewpage odd
        !            36: @settitle GDB+ Manual
        !            37: @titlepage
        !            38: @sp 6
        !            39: @center @titlefont{GDB+ Manual}
        !            40: @sp 1
        !            41: @center The GNU Source-Level Debugger for GNU C++
        !            42: @sp 4
        !            43: @center Second Edition, GDB+ version 2.5.0
        !            44: @sp 1
        !            45: @center February 1988
        !            46: @sp 5
        !            47: @center Richard M. Stallman
        !            48: @page
        !            49: @vskip 0pt plus 1filll
        !            50: Copyright @copyright{} 1988 Richard M. Stallman.
        !            51: Modified by Michael Tiemann
        !            52: 
        !            53: Permission is granted to make and distribute verbatim copies of
        !            54: this manual provided the copyright notice and this permission notice
        !            55: are preserved on all copies.
        !            56: 
        !            57: Permission is granted to copy and distribute modified versions of this
        !            58: manual under the conditions for verbatim copying, provided also that the
        !            59: sections entitled ``Distribution'' and ``GDB General Public License'' are
        !            60: included exactly as in the original, and provided that the entire resulting
        !            61: derived work is distributed under the terms of a permission notice
        !            62: identical to this one.
        !            63: 
        !            64: Permission is granted to copy and distribute translations of this manual
        !            65: into another language, under the above conditions for modified versions,
        !            66: except that the sections entitled ``Distribution'' and ``GDB General Public
        !            67: License'' may be included in a translation approved by the author instead
        !            68: of in the original English.
        !            69: @end titlepage
        !            70: @page
        !            71: 
        !            72: @node Top, Commands,, (DIR)
        !            73: @unnumbered Summary of GDB+
        !            74: 
        !            75: The purpose of a debugger such as GDB+ is to allow you to execute another
        !            76: program while examining what is going on inside it.  We call the other
        !            77: program ``your program'' or ``the program being debugged''.
        !            78: 
        !            79: GDB+ can do four kinds of things (plus other things in support of these):
        !            80: 
        !            81: @enumerate
        !            82: @item
        !            83: Start the program, specifying anything that might affect its behavior.
        !            84: 
        !            85: @item
        !            86: Make the program stop on specified conditions.
        !            87: 
        !            88: @item
        !            89: Examine what has happened, when the program has stopped, so that you
        !            90: can see bugs happen.
        !            91: 
        !            92: @item
        !            93: Change things in the program, so you can correct the effects of one bug
        !            94: and go on to learn about another without having to recompile first.
        !            95: @end enumerate
        !            96: 
        !            97: @menu
        !            98: * License::    The GDB General Public License gives you permission
        !            99:               to redistribute GDB+ on certain terms; and also
        !           100:               explains that there is no warranty.
        !           101: * Input::      GDB+ command syntax and input conventions.
        !           102: * Files::      Specifying files for GDB+ to operate on.
        !           103: * Options::    GDB+ arguments and options.
        !           104: * Compilation::Compiling your program so you can debug it.
        !           105: * Running::    Running your program under GDB+.
        !           106: * Stopping::   Making your program stop.  Why it may stop.  What to do then.
        !           107: * Stack::      Examining your program's stack.
        !           108: * Source::     Examining your program's source files.
        !           109: * Data::       Examining data in your program.
        !           110: * Symbols::    Examining the debugger's symbol table.
        !           111: * Altering::   Altering things in your program.
        !           112: * Sequences::  Canned command sequences for repeated use.
        !           113: * Emacs::      Using GDB through GNU Emacs.
        !           114: * Remote::     Remote kernel debugging across a serial line.
        !           115: * Commands::   Index of GDB+ commands.
        !           116: * Concepts::   Index of GDB+ concepts.
        !           117: @end menu
        !           118: 
        !           119: @node License, Input, Top, Top
        !           120: @unnumbered GDB General Public License
        !           121: @center (Clarified 11 Feb 1988)
        !           122: 
        !           123:   The license agreements of most software companies keep you at the mercy
        !           124: of those companies.  By contrast, our general public license is intended to
        !           125: give everyone the right to share GDB.  To make sure that you get the rights
        !           126: we want you to have, we need to make restrictions that forbid anyone to
        !           127: deny you these rights or to ask you to surrender the rights.  Hence this
        !           128: license agreement.
        !           129: 
        !           130:   Specifically, we want to make sure that you have the right to give away
        !           131: copies of GDB, that you receive source code or else can get it if you want
        !           132: it, that you can change GDB or use pieces of it in new free programs, and
        !           133: that you know you can do these things.
        !           134: 
        !           135:   To make sure that everyone has such rights, we have to forbid you to
        !           136: deprive anyone else of these rights.  For example, if you distribute copies
        !           137: of GDB, you must give the recipients all the rights that you have.  You
        !           138: must make sure that they, too, receive or can get the source code.  And you
        !           139: must tell them their rights.
        !           140: 
        !           141:   Also, for our own protection, we must make certain that everyone finds
        !           142: out that there is no warranty for GDB.  If GDB is modified by someone else
        !           143: and passed on, we want its recipients to know that what they have is not
        !           144: what we distributed, so that any problems introduced by others will not
        !           145: reflect on our reputation.
        !           146: 
        !           147:   Therefore we (Richard Stallman and the Free Software Foundation,
        !           148: Inc.) make the following terms which say what you must do to be
        !           149: allowed to distribute or change GDB.
        !           150: 
        !           151: @unnumberedsec Copying Policies
        !           152: 
        !           153: @enumerate
        !           154: @item
        !           155: You may copy and distribute verbatim copies of GDB source code as you
        !           156: receive it, in any medium, provided that you conspicuously and
        !           157: appropriately publish on each file a valid copyright notice ``Copyright
        !           158: @copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
        !           159: is appropriate); keep intact the notices on all files that
        !           160: refer to this License Agreement and to the absence of any warranty; and
        !           161: give any other recipients of the GDB program a copy of this License
        !           162: Agreement along with the program.  You may charge a distribution fee
        !           163: for the physical act of transferring a copy.
        !           164: 
        !           165: @item
        !           166: You may modify your copy or copies of GDB source code or any portion
        !           167: of it, and copy and distribute such modifications under the terms of
        !           168: Paragraph 1 above, provided that you also do the following:
        !           169: 
        !           170: @itemize @bullet
        !           171: @item
        !           172: cause the modified files to carry prominent notices stating
        !           173: that you changed the files and the date of any change; and
        !           174: 
        !           175: @item
        !           176: cause the whole of any work that you distribute or publish, that
        !           177: in whole or in part contains or is a derivative of GDB or any
        !           178: part thereof, to be licensed at no charge to all third parties on
        !           179: terms identical to those contained in this License Agreement
        !           180: (except that you may choose to grant more extensive warranty
        !           181: protection to some or all third parties, at your option).
        !           182: 
        !           183: @item
        !           184: if the modified program serves as a debugger, cause it, when
        !           185: started running in the simplest and usual way, to print an
        !           186: announcement including a valid copyright notice ``Copyright
        !           187: @copyright{} 1988 Free Software Foundation, Inc.'' (or with the
        !           188: year that is appropriate), saying that there is no warranty (or
        !           189: else, saying that you provide a warranty) and that users may
        !           190: redistribute the program under these conditions, and telling the
        !           191: user how to view a copy of this License Agreement.
        !           192: 
        !           193: @item
        !           194: You may charge a distribution fee for the physical act of
        !           195: transferring a copy, and you may at your option offer warranty
        !           196: protection in exchange for a fee.
        !           197: @end itemize
        !           198: 
        !           199: Mere aggregation of another unrelated program with this program (or its
        !           200: derivative) on a volume of a storage or distribution medium does not bring
        !           201: the other program under the scope of these terms.
        !           202: 
        !           203: @item
        !           204: You may copy and distribute GDB (or a portion or derivative of it,
        !           205: under Paragraph 2) in object code or executable form under the terms
        !           206: of Paragraphs 1 and 2 above provided that you also do one of the
        !           207: following:
        !           208: 
        !           209: @itemize @bullet
        !           210: @item
        !           211: accompany it with the complete corresponding machine-readable
        !           212: source code, which must be distributed under the terms of
        !           213: Paragraphs 1 and 2 above; or,
        !           214: 
        !           215: @item
        !           216: accompany it with a written offer, valid for at least three
        !           217: years, to give any third party free (except for a nominal
        !           218: shipping charge) a complete machine-readable copy of the
        !           219: corresponding source code, to be distributed under the terms of
        !           220: Paragraphs 1 and 2 above; or,
        !           221: 
        !           222: @item
        !           223: accompany it with the information you received as to where the
        !           224: corresponding source code may be obtained.  (This alternative is
        !           225: allowed only for noncommercial distribution and only if you
        !           226: received the program in object code or executable form alone.)
        !           227: @end itemize
        !           228: 
        !           229: For an executable file, complete source code means all the source code
        !           230: for all modules it contains; but, as a special exception, it need not
        !           231: include source code for modules which are standard libraries that
        !           232: accompany the operating system on which the executable file runs.
        !           233: 
        !           234: @item
        !           235: You may not copy, sublicense, distribute or transfer GDB except as
        !           236: expressly provided under this License Agreement.  Any attempt
        !           237: otherwise to copy, sublicense, distribute or transfer GDB is void and
        !           238: your rights to use GDB under this License agreement shall be
        !           239: automatically terminated.  However, parties who have received computer
        !           240: software programs from you with this License Agreement will not have
        !           241: their licenses terminated so long as such parties remain in full
        !           242: compliance.
        !           243: 
        !           244: @item
        !           245: If you wish to incorporate parts of GDB into other free programs whose
        !           246: distribution conditions are different, write to the Free Software
        !           247: Foundation.  We have not yet worked out a simple rule that can be
        !           248: stated here, but we will often permit this.  We will be guided by the
        !           249: two goals of preserving the free status of all derivatives our free
        !           250: software and of promoting the sharing and reuse of software.
        !           251: @end enumerate
        !           252: 
        !           253: @iftex
        !           254: @vfil
        !           255: @eject
        !           256: @end iftex
        !           257: @unnumberedsec NO WARRANTY
        !           258: 
        !           259:   BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
        !           260: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
        !           261: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
        !           262: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB ``AS IS''
        !           263: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
        !           264: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        !           265: FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY
        !           266: AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE GDB
        !           267: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
        !           268: SERVICING, REPAIR OR CORRECTION.
        !           269: 
        !           270:  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
        !           271: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
        !           272: MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
        !           273: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
        !           274: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        !           275: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
        !           276: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
        !           277: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
        !           278: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
        !           279: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
        !           280: OTHER PARTY.
        !           281: 
        !           282: @node Input, Files, License, Top
        !           283: @chapter GDB+ Input Conventions
        !           284: 
        !           285: GDB+ is invoked with the shell command @samp{gdb+}.  Once started, it reads
        !           286: commands from the terminal until you tell it to exit.
        !           287: 
        !           288: A GDB+ command is a single line of input.  There is no limit on how long
        !           289: it can be.  It starts with a command name, which is followed by arguments
        !           290: whose meaning depends on the command name.  Some command names do not
        !           291: allow arguments.
        !           292: 
        !           293: GDB+ command names may always be abbreviated if the abbreviation is
        !           294: unambiguous.  Sometimes even ambiguous abbreviations are allowed; for
        !           295: example, @samp{s} is specially defined as equivalent to @samp{step}
        !           296: even though there are other commands whose names start with @samp{s}.
        !           297: Possible command abbreviations are often stated in the documentation
        !           298: of the individual commands.
        !           299: 
        !           300: A blank line as input to GDB+ means to repeat the previous command verbatim.
        !           301: Certain commands do not allow themselves to be repeated this way; these are
        !           302: commands for which unintentional repetition might cause trouble and which
        !           303: you are unlikely to want to repeat.  Certain others (@samp{list} and
        !           304: @samp{x}) act differently when repeated because that is more useful.
        !           305: 
        !           306: A line of input starting with @samp{#} is a comment; it does nothing.
        !           307: This is useful mainly in command files (@xref{Command Files}).
        !           308: 
        !           309: GDB+ @dfn{prompts} for commands with a string that is normally @samp{(gdb+)}.
        !           310: When debugging GDB+ with GDB+, it is useful to change the prompt in one of
        !           311: the GDB+s so that you can distinguish them.  This can be done with the
        !           312: @samp{set-prompt} command.
        !           313: 
        !           314: @table @code
        !           315: @item set-prompt @var{newprompt}
        !           316: @kindex set-prompt
        !           317: Directs GDB+ to use @var{newprompt} as its prompt string henceforth.
        !           318: @end table
        !           319: 
        !           320: @cindex exiting GDB+
        !           321: @kindex quit
        !           322: To exit GDB+, use the @samp{quit} command (abbreviated @samp{q}).
        !           323: @kbd{Ctrl-c} will not exit from GDB+, but rather will terminate the action
        !           324: of any GDB+ command that is in progress and return to GDB+ command level.
        !           325: It is safe to type @kbd{Ctrl-c} at any time because GDB+ does not allow
        !           326: it to take effect until a time when it is safe.
        !           327: 
        !           328: @node Files, Options, Input, Top
        !           329: @chapter Specifying GDB+'s Files
        !           330: 
        !           331: @cindex core dump file
        !           332: @cindex executable file
        !           333: @cindex symbol table
        !           334: GDB+ needs to know the filename of the program to be debugged.  To debug a
        !           335: core dump of a previous run, GDB+ must be told the filename of the core
        !           336: dump.
        !           337: 
        !           338: @menu
        !           339: * Arguments: File Arguments.   Specifying files with arguments
        !           340:                                 (when you start GDB+).
        !           341: * Commands: File Commands.     Specifying files with GDB+ commands.
        !           342: @end menu
        !           343: 
        !           344: @node File Arguments, File Commands, Files, Files
        !           345: @section Specifying Files with Arguments
        !           346: 
        !           347: The usual way to specify the executable and core dump file names is with
        !           348: two command arguments given when you start GDB+.  The first argument is used
        !           349: as the file for execution and symbols, and the second argument (if any) is
        !           350: used as the core dump file name.  Thus,
        !           351: 
        !           352: @example
        !           353: GDB+ progm core
        !           354: @end example
        !           355: 
        !           356: @noindent
        !           357: specifies @file{progm} as the executable program and @file{core} as a core
        !           358: dump file to examine.  (You do not need to have a core dump file if what
        !           359: you plan to do is debug the program interactively.)
        !           360: 
        !           361: @xref{Options}, for full information on command options and arguments for
        !           362: GDB+.
        !           363: 
        !           364: @node File Commands,, File Arguments, Files
        !           365: @section Specifying Files with Commands
        !           366: 
        !           367: Usually you specify the files for GDB+ to work with by giving arguments when
        !           368: you invoke GDB+.  But occasionally it is necessary to change to a different
        !           369: file during a GDB+ session.  Or you may run GDB+ and forget to specify the
        !           370: files you want to use.  In these situations the GDB+ commands to specify new
        !           371: files are useful.
        !           372: 
        !           373: @table @code
        !           374: @item exec-file @var{filename}
        !           375: @kindex exec-file
        !           376: Specify that the program to be run is found in @var{filename}.  If you
        !           377: do not specify a directory and the file is not found in GDB+'s working
        !           378: directory, GDB+ will use the environment variable @samp{PATH} as a list
        !           379: of directories to search, just as the shell does when looking for a
        !           380: program to run.
        !           381: 
        !           382: @item symbol-file @var{filename}
        !           383: @kindex symbol-file
        !           384: Read symbol table information from file @var{filename}.  @samp{PATH}
        !           385: is searched when necessary.  Most of the time you will use both the
        !           386: @samp{exec-file} and @samp{symbol-file} commands on the same file.
        !           387: 
        !           388: @samp{symbol-file} with no argument clears out GDB+'s symbol table.
        !           389: 
        !           390: @item core-file @var{filename}
        !           391: @kindex core-file
        !           392: Specify the whereabouts of a core dump file to be used as the
        !           393: ``contents of memory''.  Note that the core dump contains only the
        !           394: writable parts of memory; the read-only parts must come from the
        !           395: executable file.
        !           396: 
        !           397: @samp{core-file} with no argument specifies that no core file is
        !           398: to be used.
        !           399: 
        !           400: @item kill
        !           401: @kindex kill
        !           402: Cancel running the program under GDB+.  This could be used if you wish
        !           403: to debug a core dump instead.  GDB+ ignores any core dump file if it is
        !           404: actually running the program, so the @samp{kill} command is the only
        !           405: sure way to go back to using the core dump file.
        !           406: 
        !           407: @item info files
        !           408: @kindex info files
        !           409: Print the names of the executable and core dump files currently in
        !           410: use by GDB+, and the file from which symbols were loaded.
        !           411: @end table
        !           412: 
        !           413: While all three file-specifying commands allow both absolute and relative
        !           414: file names as arguments, GDB+ always converts the file name to an absolute
        !           415: one and remembers it that way.
        !           416: 
        !           417: The @samp{symbol-file} command causes GDB+ to forget the contents of its
        !           418: convenience variables, the value history, and all breakpoints and
        !           419: auto-display expressions.  This is because they may contain pointers to the
        !           420: internal data recording symbols and data types, which are part of the old
        !           421: symbol table data being discarded inside GDB+.
        !           422: 
        !           423: @node Options, Compilation, Files, Top
        !           424: @chapter Options and Arguments for GDB+
        !           425: 
        !           426: When you invoke GDB+, you can pass commands telling it what files to
        !           427: operate on and what other things to do.
        !           428: 
        !           429: @menu
        !           430: * Mode Options::     Options controlling modes of operation.
        !           431: * File Options::     Options to specify files (executable, coredump, commands)
        !           432: * Other Arguments::  Any other arguments without options
        !           433:                        also specify files.
        !           434: @end menu
        !           435: 
        !           436: @node Mode Options, File Options, Options, Options
        !           437: @section Mode Options
        !           438: 
        !           439: @table @samp
        !           440: @item -nx
        !           441: Do not execute commands from the init files @file{.gdbinit}.
        !           442: Normally, the commands in these files are executed after all the
        !           443: command options and arguments have been processed.  @xref{Command
        !           444: Files}.
        !           445: 
        !           446: @item -q
        !           447: ``Quiet''.  Do not print the usual introductory messages.
        !           448: 
        !           449: @item -batch
        !           450: Run in batch mode.  Exit with code 1 after processing all the command
        !           451: files specified with @samp{-x} (and @file{./.gdbinit}, if not inhibited).
        !           452: Exit also if, due to an error, GDB+ would otherwise attempt to read a
        !           453: command from the terminal.
        !           454: 
        !           455: @item -fullname
        !           456: This option is used when Emacs runs GDB as a subprocess.  It tells GDB
        !           457: to output the full file name and line number in a standard,
        !           458: recognizable fashion each time a stack frame is displayed (which
        !           459: includes each time the program stops).  This recognizable format looks
        !           460: like two @samp{\032} characters, followed by the filename, line number
        !           461: and character position separated by colons, and a newline.  The
        !           462: Emacs-to-GDB interface program uses the two @samp{\032} characters as
        !           463: a signal to display the source code for the frame.
        !           464: @end table
        !           465: 
        !           466: @node File Options, Other Arguments, Mode Options, Options
        !           467: @section File-specifying Options
        !           468: 
        !           469: All the options and command line arguments given are processed
        !           470: in sequential order.  The order makes a difference when the
        !           471: @samp{-x} command is used.
        !           472: 
        !           473: @table @samp
        !           474: @item -s @var{file}
        !           475: Read symbol table from file @var{file}.
        !           476: 
        !           477: @item -e @var{file}
        !           478: Use file @var{file} as the executable file to execute when
        !           479: appropriate, and for examining pure data in conjunction with a core
        !           480: dump.
        !           481: 
        !           482: @item -se @var{file}
        !           483: Read symbol table from file @var{file} and use it as the executable
        !           484: file.
        !           485: 
        !           486: @item -c @var{file}
        !           487: Use file @var{file} as a core dump to examine.
        !           488: 
        !           489: @item -x @var{file}
        !           490: Execute GDB+ commands from file @var{file}.
        !           491: 
        !           492: @item -d @var{directory}
        !           493: Add @var{directory} to the path to search for source files.
        !           494: @end table
        !           495: 
        !           496: @node Other Arguments,, File Options, Options
        !           497: @section Other Arguments
        !           498: 
        !           499: If there are arguments to GDB+ that are not options or associated with
        !           500: options, the first one specifies the symbol table and executable file name
        !           501: (as if it were preceded by @samp{-se}) and the second one specifies a core
        !           502: dump file name (as if it were preceded by @samp{-c}).
        !           503: 
        !           504: @node Compilation, Running, Options, Top
        !           505: @chapter Compiling Your Program for Debugging
        !           506: 
        !           507: In order to debug a program effectively, you need to ask for debugging
        !           508: information when you compile it.  This information in the object file
        !           509: describes the data type of each variable or function and the correspondence
        !           510: between source line numbers and addresses in the executable code.
        !           511: 
        !           512: To request debugging information, specify the @samp{-g} option when you run
        !           513: the compiler.
        !           514: 
        !           515: The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
        !           516: together.  This means that you cannot ask for optimization if you ask for
        !           517: debugger information.
        !           518: 
        !           519: The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
        !           520: possible to debug optimized code.  We recommend that you @emph{always} use
        !           521: @samp{-g} whenever you compile a program.  You may think the program is
        !           522: correct, but there's no sense in pushing your luck.
        !           523: 
        !           524: If you are using the GNU C compiler, the GNU assembler and the GNU linker,
        !           525: you can choose between two formats of debugging information: the standard
        !           526: Unix format, which is what you get with @samp{-g}, and GDB's own format,
        !           527: which you request by using @samp{-gg} instead of @samp{-g}.  This stores
        !           528: debugging information in the executable file in a format much like that
        !           529: which is used inside GDB.  This has these advantages and disadvantages:
        !           530: 
        !           531: @itemize @bullet
        !           532: @item
        !           533: GDB can read @samp{-gg} format more than twice as fast as Unix
        !           534: @samp{-g} format.
        !           535: 
        !           536: @item
        !           537: The @samp{-gg} format uses much more disk space than Unix format.
        !           538: 
        !           539: @item
        !           540: The Unix debuggers can understand only Unix format, so you cannot use
        !           541: Unix source-level debuggers if you compile with @samp{-gg}.  (The
        !           542: @code{adb} debugger works with either format; it does not use this
        !           543: information in any case.)
        !           544: @end itemize
        !           545: 
        !           546: @node Running, Stopping, Compilation, Top
        !           547: @chapter Running Your Program Under GDB+
        !           548: 
        !           549: @cindex running
        !           550: @kindex run
        !           551: To start your program under GDB+, use the @samp{run} command.  The program
        !           552: must already have been specified using the @samp{exec-file} command or with
        !           553: an argument to GDB+ (@pxref{Files}); what @samp{run} does is create an
        !           554: inferior process, load the program into it, and set it in motion.
        !           555: 
        !           556: The execution of a program is affected by certain information it receives
        !           557: from its superior.  GDB+ provides ways to specify them, which you must do
        !           558: @i{before} starting the program.  (You can change them after starting the
        !           559: program, but such changes do not affect the program unless you start it
        !           560: over again.)
        !           561: 
        !           562: @table @asis
        !           563: @item The @i{arguments.}
        !           564: You specify the arguments to give the program as the arguments of the
        !           565: @samp{run} command.
        !           566: 
        !           567: @item The @i{environment.}
        !           568: The program normally inherits its environment from GDB+, but you can
        !           569: use the GDB+ commands @samp{set-environment} and
        !           570: @samp{unset-environment} to change parts of the environment that will
        !           571: be given to the program.@refill
        !           572: 
        !           573: @item The @i{working directory.}
        !           574: The program inherits its working directory from GDB+.  You can set GDB+'s
        !           575: working directory with the @samp{cd} command in GDB+.
        !           576: @end table
        !           577: 
        !           578: After the @samp{run} command, the debugger does nothing but wait for your
        !           579: program to stop.  @xref{Stopping}.
        !           580: 
        !           581: @menu
        !           582: * Arguments::          Specifying the arguments for your program.
        !           583: * Environment::        Specifying the environment for your program.
        !           584: * Working Directory::  Specifying the working directory for giving
        !           585:                        to your program when it is run.
        !           586: * Input/Output::       Specifying the program's standard input and output.
        !           587: * Attach::             Debugging a process started outside GDB.
        !           588: @end menu
        !           589: 
        !           590: @node Arguments, Environment, Running, Running
        !           591: @section Your Program's Arguments
        !           592: 
        !           593: @cindex arguments (to your program)
        !           594: You specify the arguments to give the program as the arguments of the
        !           595: @samp{run} command.  They are passed to a shell, which expands wildcard
        !           596: characters and performs redirection of I/O, and thence to the program.
        !           597: 
        !           598: @samp{run} with no arguments uses the same arguments used by the previous
        !           599: @samp{run}.
        !           600: 
        !           601: @kindex set-args
        !           602: The command @samp{set-args} can be used to specify the arguments to be used
        !           603: the next time the program is run.  If @samp{set-args} has no arguments, it
        !           604: means to use no arguments the next time the program is run.  If you have
        !           605: run your program with arguments and want to run it again with no arguments,
        !           606: this is the only way to do so.
        !           607: 
        !           608: @node Environment, Working Directory, Arguments, Running
        !           609: @section Your Program's Environment
        !           610: 
        !           611: @cindex environment (of your program)
        !           612: The @dfn{environment} consists of a set of @dfn{environment variables} and
        !           613: their values.  Environment variables conventionally record such things as
        !           614: your user name, your home directory, your terminal type, and your search
        !           615: path for programs to run.  Usually you set up environment variables with
        !           616: the shell and they are inherited by all the other programs you run.  When
        !           617: debugging, it can be useful to try running the program with different
        !           618: environments without having to start the debugger over again.
        !           619: 
        !           620: @table @code
        !           621: @item info environment @var{varname}
        !           622: @kindex info environment
        !           623: Print the value of environment variable @var{varname} to be given to
        !           624: your program when it is started.  This command can be abbreviated
        !           625: @samp{i env @var{varname}}.
        !           626: 
        !           627: @item info environment
        !           628: Print the names and values of all environment variables to be given to
        !           629: your program when it is started.  This command can be abbreviated
        !           630: @samp{i env}.
        !           631: 
        !           632: @item set-environment @var{varname} @var{value}
        !           633: @kindex set-environment
        !           634: Sets environment variable @var{varname} to @var{value}, for your
        !           635: program only, not for GDB+ itself.  @var{value} may be any string; the
        !           636: values of environment variables are just strings, and any
        !           637: interpretation is supplied by your program itself.  This command
        !           638: can be abbreviated as short as @samp{set-e}.
        !           639: 
        !           640: @item unset-environment @var{varname}
        !           641: @kindex unset-environment
        !           642: Remove variable @var{varname} from the environment to be passed to
        !           643: your program.  This is different from @samp{set-env @var{varname} =}
        !           644: because @samp{unset-environment} makes a variable not be defined at
        !           645: all, which is distinguishable from an empty value.  This command can
        !           646: be abbreviated @samp{unset}.
        !           647: @end table
        !           648: 
        !           649: @node Working Directory, Input/Output, Environment, Running
        !           650: @section Your Program's Working Directory
        !           651: 
        !           652: @cindex working directory (of your program)
        !           653: Each time you start your program with @samp{run}, it inherits its working
        !           654: directory from the current working directory of GDB+.  GDB+'s working
        !           655: directory is initially whatever it inherited from its superior, but you can
        !           656: specify the working directory for GDB+ with the @samp{cd} command.
        !           657: 
        !           658: The GDB+ working directory also serves as a default for the commands
        !           659: that specify files for GDB+ to operate on.  @xref{Files}.
        !           660: 
        !           661: @table @code
        !           662: @item cd @var{directory}
        !           663: @kindex cd
        !           664: Set GDB+'s working directory to @var{directory}.
        !           665: 
        !           666: @item pwd
        !           667: @kindex pwd
        !           668: Print GDB+'s working directory.
        !           669: @end table
        !           670: 
        !           671: @node Input/Output, Attach, Working Directory, Running
        !           672: @section Your Program's Input and Output
        !           673: 
        !           674: @cindex redirection
        !           675: By default, the program you run under GDB does input and output to the same
        !           676: terminal that GDB uses.
        !           677: 
        !           678: You can redirect the program's input and/or output using @samp{sh}-style
        !           679: redirection commands in the @samp{run} command.  For example,
        !           680: 
        !           681: @example
        !           682: run > outfile
        !           683: @end example
        !           684: 
        !           685: @noindent
        !           686: starts the program, diverting its output to the file @file{outfile}.
        !           687: 
        !           688: @kindex tty
        !           689: Another way to specify where the program should do input and output is with
        !           690: the @samp{tty} command.  This command accepts a file name as argument, and
        !           691: causes this file to be the default for future @samp{run} commands.  For
        !           692: example,
        !           693: 
        !           694: @example
        !           695: tty /dev/ttyb
        !           696: @end example
        !           697: 
        !           698: @noindent
        !           699: directs that processes started with subsequent @samp{run} commands default
        !           700: to do input and output on the terminal @file{/dev/ttyb}.  An explicit
        !           701: redirection in @samp{run} overrides the @samp{tty} command.
        !           702: 
        !           703: When you use the @samp{tty} command or redirect input in the @samp{run}
        !           704: command, the @emph{input for your program} comes from the specified file,
        !           705: but the input for GDB still comes from your terminal.  The program's
        !           706: controlling terminal is your (GDB's) terminal, not the terminal that the
        !           707: program is reading from; so if you want to type @kbd{C-c} to stop the
        !           708: program, you must type it on your (GDB's) terminal.  A @kbd{C-c} typed on
        !           709: the program's terminal is available to the program as ordinary input.
        !           710: 
        !           711: @node Attach,, Input/Output, Running
        !           712: @section Debugging an Already-Running Process
        !           713: @kindex detach
        !           714: @kindex attach
        !           715: @cindex attach
        !           716: 
        !           717: Some operating systems (in particular, Sun) allow GDB to begin debugging an
        !           718: already-running process that was started outside of GDB.  To do this you
        !           719: must use the @samp{attach} command instead of the @samp{run} command.
        !           720: 
        !           721: The @samp{attach} command requires one argument, which is the process-id of
        !           722: the process you want to debug.  (The usual way to find out the process-id
        !           723: of the process is with the @samp{ps} utility.)
        !           724: 
        !           725: The first thing GDB after arranging to debug the process is to stop it.
        !           726: You can examine and modify an attached process with all the GDB commands
        !           727: that ordinarily available when you start processes with @samp{run}.  You
        !           728: can insert breakpoints; you can step and continue; you can modify storage.
        !           729: If you would rather the process continue running, use the @samp{continue}
        !           730: command after attaching.
        !           731: 
        !           732: When you are finished debugging the attached process, you can use the
        !           733: @samp{detach} command to release it from GDB's control.  Detaching
        !           734: the process continues its execution.  After the @samp{detach} command,
        !           735: that process and GDB become completely independent once more, and you
        !           736: are ready to @samp{attach} another process or start one with @samp{run}.
        !           737: 
        !           738: If you exit GDB or use the @samp{run} command while you have an attached
        !           739: process, you kill that process.  You will be asked for confirmation if you
        !           740: try to do either of these things.
        !           741: 
        !           742: @node Stopping, Stack, Running, Top
        !           743: @chapter Stopping and Continuing
        !           744: 
        !           745: When you run a program normally, it runs until exiting.  The purpose
        !           746: of using a debugger is so that you can stop it before that point;
        !           747: or so that if the program runs into trouble you can find out why.
        !           748: 
        !           749: @menu
        !           750: * Signals::      Fatal signals in your program just stop it;
        !           751:                  then you can use GDB+ to see what is going on.
        !           752: * Breakpoints::  Breakpoints let you stop your program when it
        !           753:                  reaches a specified point in the code.
        !           754: * Continuing::   Resuming execution until the next signal or breakpoint.
        !           755: * Stepping::     Stepping runs the program a short distance and
        !           756:                  then stops it wherever it has come to.
        !           757: @end menu
        !           758: 
        !           759: @node Signals, Breakpoints, Stopping, Stopping
        !           760: @section Signals
        !           761: 
        !           762: A signal is an asynchronous event that can happen in a program.  The
        !           763: operating system defines the possible kinds of signals, and gives each kind
        !           764: a name and a number.  For example, @code{SIGINT} is the signal a program
        !           765: gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
        !           766: gets from referencing a place in memory far away from all the areas in use;
        !           767: @code{SIGALRM} occurs when the alarm clock timer goes off (which happens
        !           768: only if the program has requested an alarm).
        !           769: 
        !           770: Some signals, including @code{SIGALRM}, are a normal part of the
        !           771: functioning of the program.  Others, such as @code{SIGSEGV}, indicate
        !           772: errors; these signals are @dfn{fatal} (kill the program immediately) if the
        !           773: program has not specified in advance some other way to handle the signal.
        !           774: @code{SIGINT} does not indicate an error in the program, but it is normally
        !           775: fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
        !           776: 
        !           777: GDB+ has the ability to detect any occurrence of a signal in the program
        !           778: running under GDB+'s control.  You can tell GDB+ in advance what to do for
        !           779: each kind of signal.
        !           780: 
        !           781: Normally, GDB+ is set up to ignore non-erroneous signals like @code{SIGALRM}
        !           782: (so as not to interfere with their role in the functioning of the program)
        !           783: but to stop the program immediately whenever an error signal happens.
        !           784: You can change these settings with the @samp{handle} command.  You must
        !           785: specify which signal you are talking about with its number.
        !           786: 
        !           787: @table @code
        !           788: @item info signal
        !           789: @kindex info signal
        !           790: Print a table of all the kinds of signals and how GDB+ has been told to
        !           791: handle each one.  You can use this to see the signal numbers of all
        !           792: the defined types of signals.
        !           793: 
        !           794: @item handle @var{signalnum} @var{keywords}@dots{}
        !           795: @kindex handle
        !           796: Change the way GDB+ handles signal @var{signalnum}.  The @var{keywords}
        !           797: say what change to make.
        !           798: @end table
        !           799: 
        !           800: To use the @samp{handle} command you must know the code number of the
        !           801: signal you are concerned with.  To find the code number, type @samp{info
        !           802: signal} which prints a table of signal names and numbers.
        !           803: 
        !           804: The keywords allowed by the handle command can be abbreviated.  Their full
        !           805: names are
        !           806: 
        !           807: @table @code
        !           808: @item stop
        !           809: GDB+ should stop the program when this signal happens.  This implies
        !           810: the @samp{print} keyword as well.
        !           811: 
        !           812: @item print
        !           813: GDB+ should print a message when this signal happens.
        !           814: 
        !           815: @item nostop
        !           816: GDB+ should not stop the program when this signal happens.  It may
        !           817: still print a message telling you that the signal has come in.
        !           818: 
        !           819: @item noprint
        !           820: GDB+ should not mention the occurrence of the signal at all.  This
        !           821: implies the @samp{nostop} keyword as well.
        !           822: 
        !           823: @item pass
        !           824: GDB+ should allow the program to see this signal; the program will be
        !           825: able to handle the signal, or may be terminated if the signal is fatal
        !           826: and not handled.
        !           827: 
        !           828: @item nopass
        !           829: GDB+ should not allow the program to see this signal.
        !           830: @end table
        !           831: 
        !           832: When a signal has been set to stop the program, the program cannot see the
        !           833: signal until you continue.  It will see the signal then, if @samp{pass} is
        !           834: in effect for the signal in question @i{at that time}.  In other words,
        !           835: after GDB+ reports a signal, you can use the @samp{handle} command with
        !           836: @samp{pass} or @samp{nopass} to control whether that signal will be seen by
        !           837: the program when you later continue it.
        !           838: 
        !           839: You can also use the @samp{signal} command to prevent the program from
        !           840: seeing a signal, or cause it to see a signal it normally would not see,
        !           841: or to give it any signal at any time.  @xref{Signaling}.
        !           842: 
        !           843: @node Breakpoints, Continuing, Signals, Stopping
        !           844: @section Breakpoints
        !           845: 
        !           846: @cindex breakpoints
        !           847: A @dfn{breakpoint} makes your program stop whenever a certain point in the
        !           848: program is reached.  You set breakpoints explicitly with GDB+ commands,
        !           849: specifying the place where the program should stop by line number, function
        !           850: name or exact address in the program.  You can add various other conditions
        !           851: to control whether the program will stop.
        !           852: 
        !           853: Each breakpoint is assigned a number when it is created; these numbers are
        !           854: successive integers starting with 1.  In many of the commands for controlling
        !           855: various features of breakpoints you use the breakpoint number to say which
        !           856: breakpoint you want to change.  Each breakpoint may be @dfn{enabled} or
        !           857: @dfn{disabled}; if disabled, it has no effect on the program until you
        !           858: enable it again.
        !           859: 
        !           860: @kindex info break
        !           861: @kindex $_
        !           862: The command @samp{info break} prints a list of all breakpoints set and not
        !           863: cleared, showing their numbers, where in the program they are, and any
        !           864: special features in use for them.  Disabled breakpoints are included in the
        !           865: list, but marked as disabled.  @samp{info break} with a breakpoint number
        !           866: as argument lists only that breakpoint.  The convenience variable @samp{$_}
        !           867: and the default examining-address for the @samp{x} command are set to the
        !           868: address of the last breakpoint listed (@pxref{Memory}).
        !           869: 
        !           870: @menu
        !           871: * Set Breaks::     How to establish breakpoints.
        !           872: * Clear Breaks::   How to remove breakpoints no longer needed.
        !           873: * Disabling::      How to disable breakpoints (turn them off temporarily).
        !           874: * Conditions::     Making extra conditions on whether to stop.
        !           875: * Break Commands:: Commands to be executed at a breakpoint.
        !           876: * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
        !           877: @end menu
        !           878: 
        !           879: @node Set Breaks, Clear Breaks, Breakpoints, Breakpoints
        !           880: @subsection Setting Breakpoints
        !           881: 
        !           882: @kindex break
        !           883: Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
        !           884: You have several ways to say where the breakpoint should go.
        !           885: 
        !           886: @table @code
        !           887: @item break @var{function}
        !           888: Set a breakpoint at entry to function @var{function}.
        !           889: 
        !           890: @item break @var{linenum}
        !           891: Set a breakpoint at line @var{linenum} in the current source file.
        !           892: That file is the last file whose source text was printed.  This
        !           893: breakpoint will stop the program just before it executes any of the
        !           894: code on that line.
        !           895: 
        !           896: @item break @var{filename}:@var{linenum}
        !           897: Set a breakpoint at line @var{linenum} in source file @var{filename}.
        !           898: 
        !           899: @item break @var{filename}:@var{function}
        !           900: Set a breakpoint at entry to function @var{function} found in file
        !           901: @var{filename}.  Specifying a filename as well as a function name is
        !           902: superfluous except when multiple files contain similarly named
        !           903: functions.
        !           904: 
        !           905: @item break *@var{address}
        !           906: Set a breakpoint at address @var{address}.  You can use this to set
        !           907: breakpoints in parts of the program which do not have debugging
        !           908: information or source files.
        !           909: 
        !           910: @item break
        !           911: Set a breakpoint at the next instruction to be executed in the
        !           912: selected stack frame (@pxref{Stack}).  This is a silly thing to do in
        !           913: the innermost stack frame because the program would stop immediately
        !           914: after being started, but it is very useful with another stack frame,
        !           915: because it will cause the program to stop as soon as control returns
        !           916: to that frame.
        !           917: 
        !           918: @item break @dots{} if @var{cond}
        !           919: Set a breakpoint with condition @var{cond}; evaluate the expression
        !           920: @var{cond} each time the breakpoint is reached, and stop only if the
        !           921: value is nonzero.  @samp{@dots{}} stands for one of the possible
        !           922: arguments described above (or no argument) specifying where to break.
        !           923: @xref{Conditions}, for more information on breakpoint conditions.
        !           924: 
        !           925: @item tbreak @var{args}
        !           926: @kindex tbreak
        !           927: Set a breakpoint enabled only for one stop.  @var{args} are the
        !           928: same as in the @samp{break} command, and the breakpoint is set in the same
        !           929: way, but the breakpoint is automatically @dfn{disabled} the first time it
        !           930: is hit.
        !           931: @end table
        !           932: 
        !           933: GDB allows you to set any number of breakpoints at the same place in the
        !           934: program.  There is nothing silly or meaningless about this.  When the
        !           935: breakpoints are conditional, this is even useful (@pxref{Conditions}).
        !           936: 
        !           937: @node Clear Breaks, Disabling, Set Breaks, Breakpoints
        !           938: @subsection Clearing Breakpoints
        !           939: 
        !           940: @cindex clear breakpoint
        !           941: @cindex delete breakpoints
        !           942: It is often necessary to eliminate a breakpoint once it has done its job
        !           943: and you no longer want the program to stop there.  This is called
        !           944: @dfn{clearing} or @samp{deleting} the breakpoint.  A breakpoint that
        !           945: has been cleared no longer exists in any sense.
        !           946: 
        !           947: With the @samp{clear} command you can clear breakpoints according to where
        !           948: they are in the program.  With the @samp{delete} command you can clear
        !           949: individual breakpoints by specifying their breakpoint numbers.
        !           950: 
        !           951: @b{It is not necessary to clear a breakpoint to proceed past it.}  GDB+
        !           952: automatically ignores breakpoints in the first instruction to be executed
        !           953: when you continue execution at the same address where the program stopped.
        !           954: 
        !           955: @table @code
        !           956: @item clear
        !           957: @kindex clear
        !           958: Clear any breakpoints at the next instruction to be executed in the
        !           959: selected stack frame (@pxref{Selection}).  When the innermost frame
        !           960: is selected, this is a good way to clear a breakpoint that the program
        !           961: just stopped at.
        !           962: 
        !           963: @item clear @var{function}
        !           964: @itemx clear @var{filename}:@var{function}
        !           965: Clear any breakpoints set at entry to the function @var{function}.
        !           966: 
        !           967: @item clear @var{linenum}
        !           968: @item clear @var{filename}:@var{linenum}
        !           969: Clear any breakpoints set at or within the code of the specified line.
        !           970: 
        !           971: @item delete @var{bnums}@dots{}
        !           972: @kindex delete
        !           973: Delete the breakpoints of the numbers specified as arguments.
        !           974: A breakpoint deleted is forgotten completely.
        !           975: @end table
        !           976: 
        !           977: @node Disabling, Conditions, Clear Breaks, Breakpoints
        !           978: @subsection Disabling Breakpoints
        !           979: 
        !           980: @cindex disabled breakpoints
        !           981: @cindex enabled breakpoints
        !           982: Rather than clearing a breakpoint, you might prefer to @dfn{disable} it.
        !           983: This makes the breakpoint inoperative as if it had been cleared, but
        !           984: remembers the information on the breakpoint so that you can @dfn{enable}
        !           985: it again later.
        !           986: 
        !           987: You disable and enable breakpoints with the @samp{enable} and
        !           988: @samp{disable} commands, specifying one or more breakpoint numbers as
        !           989: arguments.  Use @samp{info break} to print a list of breakpoints if you
        !           990: don't know which breakpoint numbers to use.
        !           991: 
        !           992: A breakpoint can have any of four different states of enablement:
        !           993: 
        !           994: @itemize @bullet
        !           995: @item
        !           996: Enabled.  The breakpoint will stop the program.  A breakpoint made
        !           997: with the @samp{break} command starts out in this state.
        !           998: @item
        !           999: Disabled.  The breakpoint has no effect on the program.
        !          1000: @item
        !          1001: Enabled once.  The breakpoint will stop the program, but
        !          1002: when it does so it will become disabled.  A breakpoint made
        !          1003: with the @samp{tbreak} command starts out in this state.
        !          1004: @item
        !          1005: Enabled for deletion.  The breakpoint will stop the program, but
        !          1006: immediately after it does so it will be deleted permanently.
        !          1007: @end itemize
        !          1008: 
        !          1009: You change the state of enablement of a breakpoint with the following
        !          1010: commands:
        !          1011: 
        !          1012: @table @code
        !          1013: @item disable @var{bnums}@dots{}
        !          1014: @kindex disable
        !          1015: Disable the specified breakpoints.  A disabled breakpoint has no
        !          1016: effect but is not forgotten.  All options such as ignore-counts,
        !          1017: conditions and commands are remembered in case the breakpoint is
        !          1018: enabled again later.
        !          1019: 
        !          1020: @item enable @var{bnums}@dots{}
        !          1021: @kindex enable
        !          1022: Enable the specified breakpoints.  They become effective once again in
        !          1023: stopping the program, until you specify otherwise.
        !          1024: 
        !          1025: @item enable once @var{bnums}@dots{}
        !          1026: Enable the specified breakpoints temporarily.  Each will be disabled
        !          1027: again the next time it stops the program (unless you have used one of
        !          1028: these commands to specify a different state before that time comes).
        !          1029: 
        !          1030: @item enable delete @var{bnums}@dots{}
        !          1031: Enable the specified breakpoints to work once and then die.  Each of
        !          1032: the breakpoints will be deleted the next time it stops the program
        !          1033: (unless you have used one of these commands to specify a different
        !          1034: state before that time comes).
        !          1035: @end table
        !          1036: 
        !          1037: Aside from the automatic disablement or deletion of a breakpoint when it
        !          1038: stops the program, which happens only in certain states, the state of
        !          1039: enablement of a breakpoint changes only when one of the commands above
        !          1040: is used.
        !          1041: 
        !          1042: @node Conditions, Break Commands, Disabling, Breakpoints
        !          1043: @subsection Break Conditions
        !          1044: 
        !          1045: @cindex conditions
        !          1046: The simplest sort of breakpoint breaks every time the program reaches a
        !          1047: specified place.  You can also specify a @dfn{condition} for a breakpoint.
        !          1048: A condition is just a boolean expression in your programming language.
        !          1049: A breakpoint with a condition evaluates the expression each time the
        !          1050: program reaches it, and the program stops only if the condition is true.
        !          1051: 
        !          1052: Break conditions may have side effects, and may even call functions in your
        !          1053: program.  These may sound like strange things to do, but their effects are
        !          1054: completely predictable unless there is another enabled breakpoint at the
        !          1055: same address.  (In that case, GDB+ might see the other breakpoint first and
        !          1056: stop the program without checking the condition of this one.)  Note that
        !          1057: breakpoint commands are usually more convenient and flexible for the
        !          1058: purpose of performing side effects when a breakpoint is reached
        !          1059: (@pxref{Break Commands}).
        !          1060: 
        !          1061: Break conditions can be specified when a breakpoint is set, by using
        !          1062: @samp{if} in the arguments to the @samp{break} command.  @xref{Set Breaks}.
        !          1063: They can also be changed at any time with the @samp{condition} command:
        !          1064: 
        !          1065: @table @code
        !          1066: @item condition @var{bnum} @var{expression}
        !          1067: @kindex condition
        !          1068: Specify @var{expression} as the break condition for breakpoint number
        !          1069: @var{bnum}.  From now on, this breakpoint will stop the program only if
        !          1070: the value of @var{expression} is true (nonzero, in C).  @var{expression}
        !          1071: is not evaluated at the time the @samp{condition} command is given.
        !          1072: 
        !          1073: @item condition @var{bnum}
        !          1074: Remove the condition from breakpoint number @var{bnum}.  It becomes
        !          1075: an ordinary unconditional breakpoint.
        !          1076: @end table
        !          1077: 
        !          1078: @cindex ignore count (of breakpoint)
        !          1079: A special feature is provided for one kind of condition: to prevent the
        !          1080: breakpoint from doing anything until it has been reached a certain number
        !          1081: of times.  This is done with the @dfn{ignore count} of the breakpoint.
        !          1082: When the program reaches a breakpoint whose ignore count is positive, then
        !          1083: instead of stopping, it just decrements the ignore count by one and
        !          1084: continues.
        !          1085: 
        !          1086: @table @code
        !          1087: @item ignore @var{bnum} @var{count}
        !          1088: @kindex ignore
        !          1089: Set the ignore count of breakpoint number @var{bnum} to @var{count}.
        !          1090: The next @var{count} times the breakpoint is reached, it will not stop.
        !          1091: 
        !          1092: To make the breakpoint stop the next time it is reached, specify
        !          1093: a count of zero.
        !          1094: 
        !          1095: @item cont @var{count}
        !          1096: Continue execution of the program, setting the ignore count of the
        !          1097: breakpoint that the program stopped at to @var{count} minus one.
        !          1098: Continuing through the breakpoint does not itself count as one of
        !          1099: @var{count}.  Thus, the program will not stop at this breakpoint until the
        !          1100: @var{count}'th time it is hit.
        !          1101: 
        !          1102: This command is allowed only when the program stopped due to a
        !          1103: breakpoint.  At other times, the argument to @samp{cont} is ignored.
        !          1104: @end table
        !          1105: 
        !          1106: If a breakpoint has a positive ignore count and a condition, the condition
        !          1107: is not checked.  Once the ignore count reaches zero, the condition will
        !          1108: start to be checked.
        !          1109: 
        !          1110: Note that you could achieve the effect of the ignore count with a condition
        !          1111: such as @samp{$foo-- <= 0} using a debugger convenience variable that is
        !          1112: decremented each time.  That is why the ignore count is considered a
        !          1113: special case of a condition.  @xref{Convenience Vars}.
        !          1114: 
        !          1115: @node Break Commands, Error in Breakpoints, Conditions, Breakpoints
        !          1116: @subsection Commands Executed on Breaking
        !          1117: 
        !          1118: @cindex breakpoint commands
        !          1119: You can give any breakpoint a series of commands to execute when the
        !          1120: program stops due to that breakpoint.  For example, you might want to
        !          1121: print the values of certain expressions, or enable other breakpoints.
        !          1122: 
        !          1123: @table @code
        !          1124: @item commands @var{bnum}
        !          1125: Specify commands for breakpoint number @var{bnum}.  The commands
        !          1126: themselves appear on the following lines.  Type a line containing just
        !          1127: @samp{end} to terminate the commands.
        !          1128: 
        !          1129: To remove all commands from a breakpoint, use the command
        !          1130: @samp{commands} and follow it immediately by @samp{end}; that is, give
        !          1131: no commands.
        !          1132: @end table
        !          1133: 
        !          1134: It is possible for breakpoint commands to start the program up again.
        !          1135: Simply use the @samp{cont} command, or @samp{step}, or any other command
        !          1136: to resume execution.  However, any remaining breakpoint commands are
        !          1137: ignored.  When the program stops again, GDB+ will act according to why
        !          1138: that stop took place.
        !          1139: 
        !          1140: @kindex silent
        !          1141: If the first command specified is @samp{silent}, the usual message about
        !          1142: stopping at a breakpoint is not printed.  This may be desirable for
        !          1143: breakpoints that are to print a specific message and then continue.
        !          1144: If the remaining commands too print nothing, you will see no sign that
        !          1145: the breakpoint was reached at all.  @samp{silent} is not really a command;
        !          1146: it is meaningful only at the beginning of the commands for a breakpoint.
        !          1147: 
        !          1148: The commands @samp{echo} and @samp{output} that allow you to print precisely
        !          1149: controlled output are often useful in silent breakpoints.  @xref{Output}.
        !          1150: 
        !          1151: For example, here is how you could use breakpoint commands to print the
        !          1152: value of @code{x} at entry to @code{foo} whenever it is positive.  We
        !          1153: assume that the newly created breakpoint is number 4; @samp{break} will
        !          1154: print the number that is assigned.
        !          1155: 
        !          1156: @example
        !          1157: break foo if x>0
        !          1158: commands 4
        !          1159: silent
        !          1160: echo x is\040
        !          1161: output x
        !          1162: echo \n
        !          1163: cont
        !          1164: end
        !          1165: @end example
        !          1166: 
        !          1167: One application for breakpoint commands is to correct one bug so you can
        !          1168: test another.  Put a breakpoint just after the erroneous line of code, give
        !          1169: it a condition to detect the case in which something erroneous has been
        !          1170: done, and give it commands to assign correct values to any variables that
        !          1171: need them.  End with the @samp{cont} command so that the program does not
        !          1172: stop, and start with the @samp{silent} command so that no output is
        !          1173: produced.  Here is an example:
        !          1174: 
        !          1175: @example
        !          1176: break 403
        !          1177: commands 5
        !          1178: silent
        !          1179: set x = y + 4
        !          1180: cont
        !          1181: end
        !          1182: @end example
        !          1183: 
        !          1184: One deficiency in the operation of automatically continuing breakpoints
        !          1185: under Unix appears when your program uses raw mode for the terminal.
        !          1186: GDB+ options back to its own terminal modes (not raw) before executing
        !          1187: commands, and then must switch back to raw mode when your program is
        !          1188: continued.  This causes any pending terminal input to be lost.
        !          1189: 
        !          1190: In the GNU system, this will be fixed by changing the behavior of
        !          1191: terminal modes.
        !          1192: 
        !          1193: Under Unix, when you have this problem, you might be able to get around
        !          1194: it by putting your actions into the breakpoint condition instead of
        !          1195: commands.  For example
        !          1196: 
        !          1197: @example
        !          1198: condition 5  (x = y + 4), 0
        !          1199: @end example
        !          1200: 
        !          1201: @noindent
        !          1202: is a condition expression that will change @code{x} as needed, then always
        !          1203: have the value 0 so the program will not stop.  Loss of input is avoided
        !          1204: here because break conditions are evaluated without changing the terminal
        !          1205: modes.  When you want to have nontrivial conditions for performing the side
        !          1206: effects, the operators @samp{&&}, @samp{||} and @samp{?@: @dots{} :@:} may be useful.
        !          1207: 
        !          1208: @node Error in Breakpoints,, Break Commands, Breakpoints
        !          1209: @subsection ``Cannot Insert Breakpoints'' Error
        !          1210: 
        !          1211: Under Unix, breakpoints cannot be used in a program if any other process
        !          1212: is running that program.  Attempting to run or continue the program with
        !          1213: a breakpoint in this case will cause GDB+ to stop it.
        !          1214: 
        !          1215: When this happens, you have two ways to proceed:
        !          1216: 
        !          1217: @enumerate
        !          1218: @item
        !          1219: Remove or disable the breakpoints, then continue.
        !          1220: 
        !          1221: @item
        !          1222: Suspend GDB+, and copy the file containing the program to a new name.
        !          1223: Resume GDB+ and use the @samp{exec-file} command to specify that GDB+
        !          1224: should run the program under that name.  Then start the program again.
        !          1225: @end enumerate
        !          1226: 
        !          1227: @node Continuing, Stepping, Breakpoints, Stopping
        !          1228: @section Continuing
        !          1229: 
        !          1230: After your program stops, most likely you will want it to run some more if
        !          1231: the bug you are looking for has not happened yet.
        !          1232: 
        !          1233: @table @code
        !          1234: @item cont
        !          1235: Continue running the program at the place where it stopped.
        !          1236: @end table
        !          1237: 
        !          1238: If the program stopped at a breakpoint, the place to continue running
        !          1239: is the address of the breakpoint.  You might expect that continuing would
        !          1240: just stop at the same breakpoint immediately.  In fact, @samp{cont}
        !          1241: takes special care to prevent that from happening.  You do not need
        !          1242: to clear the breakpoint to proceed through it after stopping at it.
        !          1243: 
        !          1244: You can, however, specify an ignore-count for the breakpoint that the
        !          1245: program stopped at, by means of an argument to the @samp{cont} command.
        !          1246: @xref{Conditions}.
        !          1247: 
        !          1248: If the program stopped because of a signal other than @code{SIGINT} or
        !          1249: @code{SIGTRAP}, continuing will cause the program to see that signal.
        !          1250: You may not want this to happen.  For example, if the program stopped
        !          1251: due to some sort of memory reference error, you might store correct
        !          1252: values into the erroneous variables and continue, hoping to see more
        !          1253: execution; but the program would probably terminate immediately as
        !          1254: a result of the fatal signal once it sees the signal.  To prevent this,
        !          1255: you can continue with @samp{signal 0}.  @xref{Signaling}.  You can
        !          1256: also act in advance to prevent the program from seeing certain kinds
        !          1257: of signals, using the @samp{handle} command (@pxref{Signals}).
        !          1258: 
        !          1259: @node Stepping,, Continuing, Stopping
        !          1260: @section Stepping
        !          1261: 
        !          1262: @cindex stepping
        !          1263: @dfn{Stepping} means setting your program in motion for a limited time, so
        !          1264: that control will return automatically to the debugger after one line of
        !          1265: code or one machine instruction.  Breakpoints are active during stepping
        !          1266: and the program will stop for them even if it has not gone as far as the
        !          1267: stepping command specifies.
        !          1268: 
        !          1269: @table @code
        !          1270: @item step
        !          1271: @kindex step
        !          1272: Proceed the program until control reaches a different line, then stop
        !          1273: it and return to the debugger.  This command is abbreviated @samp{s}.
        !          1274: 
        !          1275: @item step @var{count}
        !          1276: Proceed as in @samp{step}, but do so @var{count} times.  If a breakpoint
        !          1277: or a signal not related to stepping is reached before @var{count} steps,
        !          1278: stepping stops right away.
        !          1279: 
        !          1280: @item next
        !          1281: @kindex next
        !          1282: Similar to @samp{step}, but any function calls appearing within the line of
        !          1283: code are executed without stopping.  Execution stops when control reaches a
        !          1284: different line of code at the stack level which was executing when the
        !          1285: @samp{next} command was given.  This command is abbreviated @samp{n}.
        !          1286: 
        !          1287: An argument is a repeat count, as in @samp{step}.
        !          1288: 
        !          1289: @item finish
        !          1290: @kindex finish
        !          1291: Continue running until just after the selected stack frame returns
        !          1292: (or until there is some other reason to stop, such as a fatal signal
        !          1293: or a breakpoint).
        !          1294: 
        !          1295: Contrast this with the @samp{return} command (@pxref{Returning}).
        !          1296: 
        !          1297: @item stepi
        !          1298: @itemx si
        !          1299: @kindex stepi
        !          1300: @kindex si
        !          1301: Proceed one machine instruction, then stop and return to the debugger.
        !          1302: 
        !          1303: It is often useful to do @samp{display/i $pc} when stepping by machine
        !          1304: instructions.  This will cause the next instruction to be executed to
        !          1305: be displayed automatically at each stop.  @xref{Auto Display}.
        !          1306: 
        !          1307: An argument is a repeat count, as in @samp{step}.
        !          1308: 
        !          1309: @item nexti
        !          1310: @itemx ni
        !          1311: @kindex nexti
        !          1312: @kindex ni
        !          1313: Proceed one machine instruction, but if it is a subroutine call,
        !          1314: proceed until the subroutine returns.
        !          1315: 
        !          1316: An argument is a repeat count, as in @samp{next}.
        !          1317: @end table
        !          1318: 
        !          1319: A typical technique for using stepping is to put a breakpoint
        !          1320: (@pxref{Breakpoints}) at the beginning of the function or the section of
        !          1321: the program in which a problem is believed to lie, and then step through
        !          1322: the suspect area, examining the variables that are interesting, until the
        !          1323: problem happens.
        !          1324: 
        !          1325: The @samp{cont} command can be used after stepping to resume execution
        !          1326: until the next breakpoint or signal.
        !          1327: 
        !          1328: @node Stack, Source, Stopping, Top
        !          1329: @chapter Examining the Stack
        !          1330: 
        !          1331: When your program has stopped, the first thing you need to know is where it
        !          1332: stopped and how it got there.
        !          1333: 
        !          1334: @cindex call stack
        !          1335: Each time your program performs a function call, the information about
        !          1336: where in the program the call was made from is saved in a block of data
        !          1337: called a @dfn{stack frame}.  The frame also contains the arguments of the
        !          1338: call and the local variables of the function that was called.  All the
        !          1339: stack frames are allocated in a region of memory called the @dfn{call
        !          1340: stack}.
        !          1341: 
        !          1342: When your program stops, the GDB+ commands for examining the stack allow you
        !          1343: to see all of this information.
        !          1344: 
        !          1345: One of the stack frames is @dfn{selected} by GDB+ and many GDB+ commands
        !          1346: refer implicitly to the selected frame.  In particular, whenever you ask
        !          1347: GDB+ for the value of a variable in the program, the value is found in the
        !          1348: selected frame.  There are special GDB+ commands to select whichever frame
        !          1349: you are interested in.
        !          1350: 
        !          1351: When the program stops, GDB+ automatically selects the currently executing
        !          1352: frame and describes it briefly as the @samp{frame} command does
        !          1353: (@pxref{Frame Info, Info}).
        !          1354: 
        !          1355: @menu
        !          1356: * Frames::          Explanation of stack frames and terminology.
        !          1357: * Backtrace::       Summarizing many frames at once.
        !          1358: * Selection::       How to select a stack frame.
        !          1359: * Info: Frame Info, Commands to print information on stack frames.
        !          1360: @end menu
        !          1361: 
        !          1362: @node Frames, Backtrace, Stack, Stack
        !          1363: @section Stack Frames
        !          1364: 
        !          1365: @cindex frame
        !          1366: The call stack is divided up into contiguous pieces called @dfn{frames};
        !          1367: each frame is the data associated with one call to one function.  The frame
        !          1368: contains the arguments given to the function, the function's local
        !          1369: variables, and the address at which the function is executing.
        !          1370: 
        !          1371: @cindex initial frame
        !          1372: @cindex outermost frame
        !          1373: @cindex innermost frame
        !          1374: When your program is started, the stack has only one frame, that of the
        !          1375: function @code{main}.  This is called the @dfn{initial} frame or the
        !          1376: @dfn{outermost} frame.  Each time a function is called, a new frame is
        !          1377: made.  Each time a function returns, the frame for that function invocation
        !          1378: is eliminated.  If a function is recursive, there can be many frames for
        !          1379: the same function.  The frame for the function in which execution is
        !          1380: actually occurring is called the @dfn{innermost} frame.  This is the most
        !          1381: recently created of all the stack frames that still exist.
        !          1382: 
        !          1383: @cindex frame pointer
        !          1384: Inside your program, stack frames are identified by their addresses.  A
        !          1385: stack frame consists of many bytes, each of which has its own address; each
        !          1386: kind of computer has a convention for choosing one of those bytes whose
        !          1387: address serves as the address of the frame.  Usually this address is kept
        !          1388: in a register called the @dfn{frame pointer register} while execution is
        !          1389: going on in that frame.
        !          1390: 
        !          1391: @cindex frame number
        !          1392: GDB+ assigns numbers to all existing stack frames, starting with zero for
        !          1393: the innermost frame, one for the frame that called it, and so on upward.
        !          1394: These numbers do not really exist in your program; they are to give you a
        !          1395: way of talking about stack frames in GDB+ commands.
        !          1396: 
        !          1397: @cindex selected frame
        !          1398: Many GDB+ commands refer implicitly to one stack frame.  GDB+ records a stack
        !          1399: frame that is called the @dfn{selected} stack frame; you can select any
        !          1400: frame using one set of GDB+ commands, and then other commands will operate
        !          1401: on that frame.  When your program stops, GDB+ automatically selects the
        !          1402: innermost frame.
        !          1403: 
        !          1404: @node Backtrace, Selection, Frames, Stack
        !          1405: @section Backtraces
        !          1406: 
        !          1407: A backtrace is a summary of how the program got where it is.  It shows one
        !          1408: line per frame, for many frames, starting with the currently executing
        !          1409: frame (frame zero), followed by its caller (frame one), and on up the
        !          1410: stack.
        !          1411: 
        !          1412: @table @code
        !          1413: @item backtrace
        !          1414: @itemx bt
        !          1415: Print a backtrace of the entire stack: one line per frame for all
        !          1416: frames in the stack.
        !          1417: 
        !          1418: You can stop the backtrace at any time by typing the system interrupt
        !          1419: character, normally @kbd{Control-C}.
        !          1420: 
        !          1421: @item backtrace @var{n}
        !          1422: @itemx bt @var{n}
        !          1423: Similar, but stop after @var{n} frames.
        !          1424: @end table
        !          1425: 
        !          1426: Each line in a backtrace shows the frame number, the program counter, the
        !          1427: function and its arguments, and the source file name and line number (if
        !          1428: known).  The program counter is is omitted if is the beginning of the code for
        !          1429: the source line.  This is the same as the first of the two lines printed
        !          1430: when you select a frame.
        !          1431: 
        !          1432: @node Selection, Frame Info, Backtrace, Stack
        !          1433: @section Selecting a Frame
        !          1434: 
        !          1435: Most commands for examining the stack and other data in the program work on
        !          1436: whichever stack frame is selected at the moment.  Here are the commands for
        !          1437: selecting a stack frame; all of them finish by printing a brief description
        !          1438: of the stack frame just selected.
        !          1439: 
        !          1440: @table @code
        !          1441: @item frame @var{n}
        !          1442: @kindex frame
        !          1443: Select frame number @var{n}.  Recall that frame zero is the innermost
        !          1444: (currently executing) frame, frame one is the frame that called the
        !          1445: innermost one, and so on.  The highest-numbered frame is @code{main}'s
        !          1446: frame.
        !          1447: 
        !          1448: @item frame @var{addr}
        !          1449: Select the frame at address @var{addr}.  This is useful mainly if the
        !          1450: chaining of stack frames has been damaged by a bug, making it
        !          1451: impossible for GDB+ to assign numbers properly to all frames.  In
        !          1452: addition, this can be useful when the program has multiple stacks and
        !          1453: options between them.
        !          1454: 
        !          1455: @item up @var{n}
        !          1456: @kindex up
        !          1457: Select the frame @var{n} frames up from the frame previously selected.
        !          1458: For positive numbers @var{n}, this advances toward the outermost
        !          1459: frame, to higher frame numbers, to frames that have existed longer.
        !          1460: @var{n} defaults to one.
        !          1461: 
        !          1462: @item down @var{n}
        !          1463: @kindex down
        !          1464: Select the frame @var{n} frames down from the frame previously
        !          1465: selected.  For positive numbers @var{n}, this advances toward the
        !          1466: innermost frame, to lower frame numbers, to frames that were created
        !          1467: more recently.  @var{n} defaults to one.
        !          1468: @end table
        !          1469: 
        !          1470: All of these commands end by printing some information on the frame that
        !          1471: has been selected: the frame number, the function name, the arguments, the
        !          1472: source file and line number of execution in that frame, and the text of
        !          1473: that source line.  For example:
        !          1474: 
        !          1475: @example
        !          1476: #3  main (argc=3, argv=??, env=??) at main.c, line 67
        !          1477: 67        read_input_file (argv[i]);
        !          1478: @end example
        !          1479: 
        !          1480: After such a printout, the @samp{list} command with no arguments will print
        !          1481: ten lines centered on the point of execution in the frame.  @xref{List}.
        !          1482: 
        !          1483: @node Frame Info,, Selection, Stack
        !          1484: @section Information on a Frame
        !          1485: 
        !          1486: There are several other commands to print information about the selected
        !          1487: stack frame.
        !          1488: 
        !          1489: @table @code
        !          1490: @item frame
        !          1491: This command prints a brief description of the selected stack frame.
        !          1492: It can be abbreviated @samp{f}.  With an argument, this command is
        !          1493: used to select a stack frame; with no argument, it does not change
        !          1494: which frame is selected, but still prints the same information.
        !          1495: 
        !          1496: @item info frame
        !          1497: @kindex info frame
        !          1498: This command prints a verbose description of the selected stack frame,
        !          1499: including the address of the frame, the addresses of the next frame in
        !          1500: (called by this frame) and the next frame out (caller of this frame),
        !          1501: the address of the frame's arguments, the program counter saved in it
        !          1502: (the address of execution in the caller frame), and which registers
        !          1503: were saved in the frame.  The verbose description is useful when
        !          1504: something has gone wrong that has made the stack format fail to fit
        !          1505: the usual conventions.
        !          1506: 
        !          1507: @item info frame @var{addr}
        !          1508: Print a verbose description of the frame at address @var{addr},
        !          1509: without selecting that frame.  The selected frame remains unchanged by
        !          1510: this command.
        !          1511: 
        !          1512: @item info args
        !          1513: @kindex info args
        !          1514: Print the arguments of the selected frame, each on a separate line.
        !          1515: 
        !          1516: @item info locals
        !          1517: @kindex info locals
        !          1518: Print the local variables of the selected frame, each on a separate
        !          1519: line.  These are all variables declared static or automatic within all
        !          1520: program blocks that execution in this frame is currently inside of.
        !          1521: @end table
        !          1522: 
        !          1523: @node Source, Data, Stack, Top
        !          1524: @chapter Examining Source Files
        !          1525: 
        !          1526: GDB+ knows which source files your program was compiled from, and
        !          1527: can print parts of their text.  When your program stops, GDB+
        !          1528: spontaneously prints the line it stopped in.  Likewise, when you
        !          1529: select a stack frame (@pxref{Selection}), GDB+ prints the line
        !          1530: which execution in that frame has stopped in.  You can also
        !          1531: print parts of source files by explicit command.
        !          1532: 
        !          1533: @menu
        !          1534: * List::        Using the @samp{list} command to print source files.
        !          1535: * Search::      Commands for searching source files.
        !          1536: * Source Path:: Specifying the directories to search for source files.
        !          1537: @end menu
        !          1538: 
        !          1539: @node List, Search, Source, Source
        !          1540: @section Printing Source Lines
        !          1541: 
        !          1542: @kindex list
        !          1543: To print lines from a source file, use the @samp{list} command
        !          1544: (abbreviated @samp{l}).  There are several ways to specify what part
        !          1545: of the file you want to print.
        !          1546: 
        !          1547: Here are the forms of @samp{list} command most commonly used:
        !          1548: 
        !          1549: @table @code
        !          1550: @item list @var{linenum}
        !          1551: Print ten lines centered around line number @var{linenum} in the
        !          1552: current source file.
        !          1553: 
        !          1554: @item list @var{function}
        !          1555: Print ten lines centered around the beginning of function
        !          1556: @var{function}.
        !          1557: 
        !          1558: @item list
        !          1559: Print ten more lines.  If the last lines printed were printed with a
        !          1560: @samp{list} command, this prints ten lines following the last lines
        !          1561: printed; however, if the last line printed was a solitary line printed
        !          1562: as part of displaying a stack frame (@pxref{Stack}), this prints ten
        !          1563: lines centered around that line.
        !          1564: 
        !          1565: @item list @minus{}
        !          1566: Print ten lines just before the lines last printed.
        !          1567: @end table
        !          1568: 
        !          1569: Repeating a @samp{list} command with @key{RET} discards the argument,
        !          1570: so it is equivalent to typing just @samp{list}.  This is more useful
        !          1571: than listing the same lines again.  An exception is made for an
        !          1572: argument of @samp{-}; that argument is preserved in repetition so that
        !          1573: each repetition moves up in the file.
        !          1574: 
        !          1575: In general, the @samp{list} command expects you to supply zero, one or two
        !          1576: @dfn{linespecs}.  Linespecs specify source lines; there are several ways
        !          1577: of writing them but the effect is always to specify some source line.
        !          1578: Here is a complete description of the possible arguments for @samp{list}:
        !          1579: 
        !          1580: @table @code
        !          1581: @item list @var{linespec}
        !          1582: Print ten lines centered around the line specified by @var{linespec}.
        !          1583: 
        !          1584: @item list @var{first},@var{last}
        !          1585: Print lines from @var{first} to @var{last}.  Both arguments are
        !          1586: linespecs.
        !          1587: 
        !          1588: @item list ,@var{last}
        !          1589: Print ten lines ending with @var{last}.
        !          1590: 
        !          1591: @item list @var{first},
        !          1592: Print ten lines starting with @var{first}.
        !          1593: 
        !          1594: @item list +
        !          1595: Print ten lines just after the lines last printed.
        !          1596: 
        !          1597: @item list @minus{}
        !          1598: Print ten lines just before the lines last printed.
        !          1599: 
        !          1600: @item list
        !          1601: As described in the preceding table.
        !          1602: @end table
        !          1603: 
        !          1604: Here are the ways of specifying a single source line---all the
        !          1605: kinds of linespec.
        !          1606: 
        !          1607: @table @asis
        !          1608: @item @var{linenum}
        !          1609: Specifies line @var{linenum} of the current source file.
        !          1610: When a @samp{list} command has two linespecs, this refers to
        !          1611: the same source file as the first linespec.
        !          1612: 
        !          1613: @item +@var{offset}
        !          1614: Specifies the line @var{offset} lines after the last line printed.
        !          1615: When used as the second linespec in a @samp{list} command that has
        !          1616: two, this specifies the line @var{offset} lines down from the
        !          1617: first linespec.
        !          1618: 
        !          1619: @item @minus{}@var{offset}
        !          1620: Specifies the line @var{offset} lines before the last line printed.
        !          1621: 
        !          1622: @item @var{filename}:@var{linenum}
        !          1623: Specifies line @var{linenum} in the source file @var{filename}.
        !          1624: 
        !          1625: @item @var{function}
        !          1626: Specifies the line of the open-brace that begins the body of the
        !          1627: function @var{function}.
        !          1628: 
        !          1629: @item @var{filename}:@var{function}
        !          1630: Specifies the line of the open-brace that begins the body of the
        !          1631: function @var{function} in the file @var{filename}.  The file name is
        !          1632: needed with a function name only for disambiguation of identically
        !          1633: named functions in different source files.
        !          1634: 
        !          1635: @item *@var{address}
        !          1636: Specifies the line containing the program address @var{address}.
        !          1637: @var{address} may be any expression.
        !          1638: @end table
        !          1639: 
        !          1640: One other command is used to map source lines to program addresses.
        !          1641: 
        !          1642: @table @code
        !          1643: @item info line @var{linenum}
        !          1644: @kindex info line
        !          1645: Print the starting and ending addresses of the compiled code for
        !          1646: source line @var{linenum}.
        !          1647: 
        !          1648: @kindex $_
        !          1649: The default examine address for the @samp{x} command is changed to the
        !          1650: starting address of the line, so that @samp{x/i} is sufficient to
        !          1651: begin examining the machine code (@pxref{Memory}).  Also, this address
        !          1652: is saved as the value of the convenience variable @samp{$_}
        !          1653: (@pxref{Convenience Vars}).
        !          1654: @end table
        !          1655: 
        !          1656: @node Search, Source Path, List, Source
        !          1657: @section Searching Source Files
        !          1658: @cindex searching
        !          1659: @kindex forward-search
        !          1660: @kindex reverse-search
        !          1661: 
        !          1662: There are two commands for searching through the current source file for a
        !          1663: regular expression.
        !          1664: 
        !          1665: The command @samp{forward-search @var{regexp}} checks each line, starting
        !          1666: with the one following the last line listed, for a match for @var{regexp}.
        !          1667: It lists the line that is found.  You can abbreviate the command name
        !          1668: as @samp{fo}.
        !          1669: 
        !          1670: The command @samp{reverse-search @var{regexp}} checks each line, starting
        !          1671: with the one before the last line listed and going backward, for a match
        !          1672: for @var{regexp}.  It lists the line that is found.  You can abbreviate
        !          1673: this command with as little as @samp{rev}.
        !          1674: 
        !          1675: @node Source Path,, Search, Source
        !          1676: @section Specifying Source Directories
        !          1677: 
        !          1678: @cindex source path
        !          1679: @cindex directories for source files
        !          1680: Executable programs do not record the directories of the source files they
        !          1681: were compiled from, just the names.  GDB+ remembers a list of directories to
        !          1682: search for source files; this is called the @dfn{source path}.  Each time
        !          1683: GDB+ wants a source file, it tries all the directories in the list, in the
        !          1684: order they are present in the list, until it finds a file with the desired
        !          1685: name.
        !          1686: 
        !          1687: @kindex directory
        !          1688: When you start GDB+, its source path contains just the current working
        !          1689: directory.  To add other directories, use the @samp{directory} command.
        !          1690: @b{Note that the search path for executable files and the working directory
        !          1691: are @i{not} used for finding source files.}
        !          1692: 
        !          1693: @table @code
        !          1694: @item directory @var{dirname}
        !          1695: Add directory @var{dirname} to the end of the source path.
        !          1696: 
        !          1697: @item directory
        !          1698: Reset the source path to just the current working directory of GDB+.
        !          1699: This requires confirmation.
        !          1700: 
        !          1701: @samp{directory} with no argument can cause source files previously
        !          1702: found by GDB+ to be found in a different directory.  To make this work
        !          1703: correctly, this command also clears out the tables GDB+ maintains
        !          1704: about the source files it has already found.
        !          1705: 
        !          1706: @item info directories
        !          1707: @kindex info directories
        !          1708: Print the source path: show which directories it contains.
        !          1709: @end table
        !          1710: 
        !          1711: Because the @samp{directory} command adds to the end of the source path,
        !          1712: it does not affect any file that GDB+ has already found.  If the source
        !          1713: path contains directories that you do not want, and these directories
        !          1714: contain misleading files with names matching your source files, the
        !          1715: way to correct the situation is as follows:
        !          1716: 
        !          1717: @enumerate
        !          1718: @item
        !          1719: Choose the directory you want at the beginning of the source path.
        !          1720: Use the @samp{cd} command to make that the current working directory.
        !          1721: 
        !          1722: @item
        !          1723: Use @samp{directory} with no argument to reset the source path to just
        !          1724: that directory.
        !          1725: 
        !          1726: @item
        !          1727: Use @samp{directory} with suitable arguments to add any other
        !          1728: directories you want in the source path.
        !          1729: @end enumerate
        !          1730: 
        !          1731: @node Data, Symbols, Source, Top
        !          1732: @chapter Examining Data
        !          1733: 
        !          1734: @cindex printing data
        !          1735: @cindex examining data
        !          1736: @kindex print
        !          1737: The usual way of examining data in your program is with the @samp{print}
        !          1738: command (abbreviated @samp{p}).  It evaluates and prints the value of any
        !          1739: valid expression of the language the program is written in (for now, C).
        !          1740: You type
        !          1741: 
        !          1742: @example
        !          1743: print @var{exp}
        !          1744: @end example
        !          1745: 
        !          1746: @noindent
        !          1747: where @var{exp} is any valid expression, and the value of @var{exp}
        !          1748: is printed in a format appropriate to its data type.
        !          1749: 
        !          1750: A more low-level way of examining data is with the @samp{x} command.
        !          1751: It examines data in memory at a specified address and prints it in a
        !          1752: specified format.
        !          1753: 
        !          1754: @menu
        !          1755: * Expressions::      Expressions that can be computed and printed.
        !          1756: * Variables::        Using your program's variables in expressions.
        !          1757: * Assignment::       Setting your program's variables.
        !          1758: * Arrays::           Examining part of memory as an array.
        !          1759: * Formats::          Specifying formats for printing values.
        !          1760: * Memory::           Examining memory explicitly.
        !          1761: * Auto Display::     Printing certain expressions whenever program stops.
        !          1762: * Value History::    Referring to values previously printed.
        !          1763: * Convenience Vars:: Giving names to values for future reference.
        !          1764: * Registers::        Referring to and storing in machine registers.
        !          1765: @end menu
        !          1766: 
        !          1767: @node Expressions, Variables, Data, Data
        !          1768: @section Expressions
        !          1769: 
        !          1770: @cindex expressions
        !          1771: Many different GDB+ commands accept an expression and compute its value.
        !          1772: Any kind of constant, variable or operator defined by the programming
        !          1773: language you are using is legal in an expression in GDB+.  This includes
        !          1774: conditional expressions, function calls, casts and string constants.
        !          1775: 
        !          1776: In addition to supporting operators normally found in the C programming
        !          1777: language, GDB+ also supports some C++ constructs.  For example, one can
        !          1778: call member functions (GDB+ automatically uses @code{this} when necessary),
        !          1779: and examine and manipulate pointers to members, pointers to member
        !          1780: functions (virtual or otherwise).
        !          1781: 
        !          1782: Casts are supported in all languages, not just in C, because it is so
        !          1783: useful to cast a number into a pointer so as to examine a structure
        !          1784: at that address in memory.  GDB+ allows pointers to members and pointer to
        !          1785: member functions to be cast to any type and vice-versa.
        !          1786: 
        !          1787: GDB+ supports three kinds of operator in addition to those of programming
        !          1788: languages:
        !          1789: 
        !          1790: @table @code
        !          1791: @item @@
        !          1792: @samp{@@} is a binary operator for treating parts of memory as arrays.
        !          1793: @xref{Arrays}, for more information.
        !          1794: 
        !          1795: @item ::
        !          1796: @samp{::} allows you to specify a variable in terms of the file or
        !          1797: function it is defined in.  @xref{Variables}.  It also supports the C++
        !          1798: convention of qualifying a variable reference according to a type name (or
        !          1799: the global scope).  This makes it easy to examing static class variables,
        !          1800: for example.
        !          1801: 
        !          1802: @item @{@var{type}@} @var{addr}
        !          1803: Refers to an object of type @var{type} stored at address @var{addr} in
        !          1804: memory.  @var{addr} may be any expression whose value is an integer or
        !          1805: pointer (but parentheses are required around nonunary operators, just as in
        !          1806: a cast).  This construct is allowed regardless of what kind of data is
        !          1807: officially supposed to reside at @var{addr}.@refill
        !          1808: @end table
        !          1809: 
        !          1810: @node Variables, Arrays, Expressions, Data
        !          1811: @section Program Variables
        !          1812: 
        !          1813: The most common kind of expression to use is the name of a variable
        !          1814: in your program.
        !          1815: 
        !          1816: Variables in expressions are understood in the selected stack frame
        !          1817: (@pxref{Selection}); they must either be global (or static) or be visible
        !          1818: according to the scope rules of the programming language from the point of
        !          1819: execution in that frame.  This means that in the function
        !          1820: 
        !          1821: @example
        !          1822: foo (a)
        !          1823:      int a;
        !          1824: @{
        !          1825:   bar (a);
        !          1826:   @{
        !          1827:     int b = test ();
        !          1828:     bar (b);
        !          1829:   @}
        !          1830: @}
        !          1831: @end example
        !          1832: 
        !          1833: @noindent
        !          1834: the variable @code{a} is usable whenever the program is executing
        !          1835: within the function @code{foo}, but the variable @code{b} is visible
        !          1836: only while the program is executing inside the block in which @code{b}
        !          1837: is declared.
        !          1838: 
        !          1839: @node Arrays, Formats, Variables, Data
        !          1840: @section Artificial Arrays
        !          1841: 
        !          1842: @cindex artificial array
        !          1843: It is often useful to print out several successive objects of the
        !          1844: same type in memory; a section of an array, or an array of
        !          1845: dynamically determined size for which only a pointer exists in the
        !          1846: program.
        !          1847: 
        !          1848: This can be done by constructing an @dfn{artificial array} with the
        !          1849: binary operator @samp{@@}.  The left operand of @samp{@@} should be
        !          1850: the first element of the desired array, as an individual object.
        !          1851: The right operand should be the length of the array.  The result is
        !          1852: an array value whose elements are all of the type of the left argument.
        !          1853: The first element is actually the left argument; the second element
        !          1854: comes from bytes of memory immediately following those that hold the
        !          1855: first element, and so on.  Here is an example.  If a program says
        !          1856: 
        !          1857: @example
        !          1858: int *array = (int *) malloc (len * sizeof (int));
        !          1859: @end example
        !          1860: 
        !          1861: @noindent
        !          1862: you can print the contents of @code{array} with
        !          1863: 
        !          1864: @example
        !          1865: p *array@@len
        !          1866: @end example
        !          1867: 
        !          1868: The left operand of @samp{@@} must reside in memory.  Array values made
        !          1869: with @samp{@@} in this way behave just like other arrays in terms of
        !          1870: subscripting, and are coerced to pointers when used in expressions.
        !          1871: (It would probably appear in an expression via the value history,
        !          1872: after you had printed it out.)
        !          1873: 
        !          1874: @node Formats, Memory, Arrays, Data
        !          1875: @section Formats
        !          1876: 
        !          1877: @cindex formatted output
        !          1878: @cindex output formats
        !          1879: GDB+ normally prints all values according to their data types.  Sometimes
        !          1880: this is not what you want.  For example, you might want to print a number
        !          1881: in hex, or a pointer in decimal.  Or you might want to view data in memory
        !          1882: at a certain address as a character string or an instruction.  These things
        !          1883: can be done with @dfn{output formats}.
        !          1884: 
        !          1885: The simplest use of output formats is to say how to print a value
        !          1886: already computed.  This is done by starting the arguments of the
        !          1887: @samp{print} command with a slash and a format letter.  The format
        !          1888: letters supported are:
        !          1889: 
        !          1890: @table @samp
        !          1891: @item x
        !          1892: Regard the bits of the value as an integer, and print the integer in
        !          1893: hexadecimal.
        !          1894: 
        !          1895: @item d
        !          1896: Print as integer in signed decimal.
        !          1897: 
        !          1898: @item u
        !          1899: Print as integer in unsigned decimal.
        !          1900: 
        !          1901: @item o
        !          1902: Print as integer in octal.
        !          1903: 
        !          1904: @item a
        !          1905: Print as an address, both absolute in hex and then relative
        !          1906: to a symbol defined as an address below it.
        !          1907: 
        !          1908: @item c
        !          1909: Regard as an integer and print it as a character constant.
        !          1910: 
        !          1911: @item f
        !          1912: Regard the bits of the value as a floating point number and print
        !          1913: using typical floating point syntax.
        !          1914: @end table
        !          1915: 
        !          1916: For example, to print the program counter in hex (@pxref{Registers}), type
        !          1917: 
        !          1918: @example
        !          1919: p/x $pc
        !          1920: @end example
        !          1921: 
        !          1922: @noindent
        !          1923: Note that no space is required before the slash; this is because command
        !          1924: names in GDB+ cannot contain a slash.
        !          1925: 
        !          1926: To reprint the last value in the value history with a different format,
        !          1927: you can use the @samp{print} command with just a format and no
        !          1928: expression.  For example, @samp{p/x} reprints the last value in hex.
        !          1929: 
        !          1930: @node Memory, Auto Display, Formats, Data
        !          1931: @subsection Examining Memory
        !          1932: 
        !          1933: @cindex examining memory
        !          1934: @kindex x
        !          1935: The command @samp{x} (for `examine') can be used to examine memory under
        !          1936: explicit control of formats, without reference to the program's data types.
        !          1937: 
        !          1938: @samp{x} is followed by a slash and an output format specification,
        !          1939: followed by an expression for an address.  The expression need not have
        !          1940: a pointer value (though it may); it is used as an integer, as the
        !          1941: address of a byte of memory.
        !          1942: 
        !          1943: The output format in this case specifies both how big a unit of memory
        !          1944: to examine and how to print the contents of that unit.  It is done
        !          1945: with one or two of the following letters:
        !          1946: 
        !          1947: These letters specify just the size of unit to examine:
        !          1948: 
        !          1949: @table @samp
        !          1950: @item b
        !          1951: Examine individual bytes.
        !          1952: 
        !          1953: @item h
        !          1954: Examine halfwords (two bytes each).
        !          1955: 
        !          1956: @item w
        !          1957: Examine words (four bytes each).
        !          1958: 
        !          1959: @cindex word
        !          1960: Many assemblers and cpu designers still use `word' for a 16-bit quantity,
        !          1961: as a holdover from specific predecessor machines of the 1970's that really
        !          1962: did use two-byte words.  But more generally the term `word' has always
        !          1963: referred to the size of quantity that a machine normally operates on and
        !          1964: stores in its registers.  This is 32 bits for all the machines that GNU
        !          1965: runs on.
        !          1966: 
        !          1967: @item g
        !          1968: Examine giant words (8 bytes).
        !          1969: @end table
        !          1970: 
        !          1971: These letters specify just the way to print the contents:
        !          1972: 
        !          1973: @table @samp
        !          1974: @item x
        !          1975: Print as integers in unsigned hexadecimal.
        !          1976: 
        !          1977: @item d
        !          1978: Print as integers in signed decimal.
        !          1979: 
        !          1980: @item u
        !          1981: Print as integers in unsigned decimal.
        !          1982: 
        !          1983: @item o
        !          1984: Print as integers in unsigned octal.
        !          1985: 
        !          1986: @item a
        !          1987: Print as an address, both absolute in hex and then relative
        !          1988: to a symbol defined as an address below it.
        !          1989: 
        !          1990: @item c
        !          1991: Print as character constants.
        !          1992: 
        !          1993: @item f
        !          1994: Print as floating point.  This works only with sizes @samp{w} and
        !          1995: @samp{g}.
        !          1996: 
        !          1997: @item s
        !          1998: Print a null-terminated string of characters.  The specified unit size
        !          1999: is ignored; instead, the unit is however many bytes it takes to reach
        !          2000: a null character (including the null character).
        !          2001: 
        !          2002: @item i
        !          2003: Print a machine instruction in assembler syntax (or nearly).  The
        !          2004: specified unit size is ignored; the number of bytes in an instruction
        !          2005: varies depending on the type of machine, the opcode and the addressing
        !          2006: modes used.
        !          2007: @end table
        !          2008: 
        !          2009: If either the manner of printing or the size of unit fails to be specified,
        !          2010: the default is to use the same one that was used last.  If you don't want
        !          2011: to use any letters after the slash, you can omit the slash as well.
        !          2012: 
        !          2013: You can also omit the address to examine.  Then the address used is
        !          2014: just after the last unit examined.  This is why string and instruction
        !          2015: formats actually compute a unit-size based on the data: so that the
        !          2016: next string or instruction examined will start in the right place.
        !          2017: The @samp{print} command sometimes sets the default address for
        !          2018: the @samp{x} command; when the value printed resides in memory, the
        !          2019: default is set to examine the same location.  @samp{info line} also
        !          2020: sets the default for @samp{x}, to the address of the start of the
        !          2021: machine code for the specified line and @samp{info breakpoints} sets
        !          2022: it to the address of the last breakpoint listed.
        !          2023: 
        !          2024: When you use @key{RET} to repeat an @samp{x} command, it does not repeat
        !          2025: exactly the same: the address specified previously (if any) is ignored, so
        !          2026: that the repeated command examines the successive locations in memory
        !          2027: rather than the same ones.
        !          2028: 
        !          2029: You can examine several consecutive units of memory with one command by
        !          2030: writing a repeat-count after the slash (before the format letters, if any).
        !          2031: The repeat count must be a decimal integer.  It has the same effect as
        !          2032: repeating the @samp{x} command that many times except that the output may
        !          2033: be more compact with several units per line.
        !          2034: 
        !          2035: @example
        !          2036: x/10i $pc
        !          2037: @end example
        !          2038: 
        !          2039: @noindent
        !          2040: Prints ten instructions starting with the one to be executed next in the
        !          2041: selected frame.  After doing this, you could print another ten following
        !          2042: instructions with
        !          2043: 
        !          2044: @example
        !          2045: x/10
        !          2046: @end example
        !          2047: 
        !          2048: @noindent
        !          2049: in which the format and address are allowed to default.
        !          2050: 
        !          2051: @kindex $_
        !          2052: @kindex $__
        !          2053: The addresses and contents printed by the @samp{x} command are not put in
        !          2054: the value history because there is often too much of them and they would
        !          2055: get in the way.  Instead, GDB+ makes these values available for subsequent
        !          2056: use in expressions as values of the convenience variables @samp{$_} and
        !          2057: @samp{$__}.
        !          2058: 
        !          2059: After an @samp{x} command, the last address examined is available for use
        !          2060: in expressions in the convenience variable @samp{$_}.  The contents of that
        !          2061: address, as examined, are available in the convenience variable @samp{$__}.
        !          2062: 
        !          2063: If the @samp{x} command has a repeat count, the address and contents saved
        !          2064: are from the last memory unit printed; this is not the same as the last
        !          2065: address printed if several units were printed on the last line of output.
        !          2066: 
        !          2067: @node Auto Display, Value History, Memory, Data
        !          2068: @section Automatic Display
        !          2069: 
        !          2070: If you find that you want to print the value of an expression frequently
        !          2071: (to see how it changes), you might want to add it to the @dfn{automatic
        !          2072: display list} so that GDB+ will print its value each time the program stops.
        !          2073: Each expression added to the list is given a number to identify it;
        !          2074: to remove an expression from the list, you specify that number.
        !          2075: The automatic display looks like this:
        !          2076: 
        !          2077: @example
        !          2078: 2: foo = 38
        !          2079: 3: bar[5] = (struct hack *) 0x3804
        !          2080: @end example
        !          2081: 
        !          2082: @noindent
        !          2083: showing item numbers, expressions and their current values.
        !          2084: 
        !          2085: @table @code
        !          2086: @item display @var{exp}
        !          2087: @kindex display
        !          2088: Add the expression @var{exp} to the list of expressions to display
        !          2089: each time the program stops.
        !          2090: 
        !          2091: @item display/@var{fmt} @var{exp}
        !          2092: For @var{fmt} specifying only a display format and not a size or
        !          2093: count, add the expression @var{exp} to the auto-display list but
        !          2094: arranges to display it each time in the specified format @var{fmt}.
        !          2095: 
        !          2096: @item display/@var{fmt} @var{addr}
        !          2097: For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
        !          2098: number of units, add the expression @var{addr} as a memory address to
        !          2099: be examined each time the program stops.  Examining means in effect
        !          2100: doing @samp{x/@var{fmt} @var{addr}}.  @xref{Memory}.
        !          2101: 
        !          2102: @item undisplay @var{n}
        !          2103: @kindex undisplay
        !          2104: Remove item number @var{n} from the list of expressions to display.
        !          2105: 
        !          2106: @item display
        !          2107: Display the current values of the expressions on the list, just as is
        !          2108: done when the program stops.
        !          2109: 
        !          2110: @item info display
        !          2111: @kindex info display
        !          2112: Print the list of expressions to display automatically, each one
        !          2113: with its item number, but without showing the values.
        !          2114: @end table
        !          2115: 
        !          2116: @node Value History, Convenience Vars, Auto Display, Data
        !          2117: @section Value History
        !          2118: 
        !          2119: @cindex value history
        !          2120: Every value printed by the @samp{print} command is saved for the entire
        !          2121: session in GDB+'s @dfn{value history} so that you can refer to it in
        !          2122: other expressions.
        !          2123: 
        !          2124: @cindex $
        !          2125: @cindex $$
        !          2126: The values printed are given @dfn{history numbers} for you to refer to them
        !          2127: by.  These are successive integers starting with 1.  @samp{print} shows you
        !          2128: the history number assigned to a value by printing @samp{$@var{n} = }
        !          2129: before the value; here @var{n} is the history number.
        !          2130: 
        !          2131: To refer to any previous value, use @samp{$} followed by the value's
        !          2132: history number.  The output printed by @samp{print} is designed to remind
        !          2133: you of this.  Just @samp{$} refers to the most recent value in the history,
        !          2134: and @samp{$$} refers to the value before that.
        !          2135: 
        !          2136: For example, suppose you have just printed a pointer to a structure and
        !          2137: want to see the contents of the structure.  It suffices to type
        !          2138: 
        !          2139: @example
        !          2140: p *$
        !          2141: @end example
        !          2142: 
        !          2143: If you have a chain of structures where the component @samp{next} points
        !          2144: to the next one, you can print the contents of the next one with
        !          2145: 
        !          2146: @example
        !          2147: p *$.next
        !          2148: @end example
        !          2149: 
        !          2150: It might be useful to repeat this command many times by typing @key{RET}.
        !          2151: 
        !          2152: Note that the history records values, not expressions.  If the value of
        !          2153: @code{x} is 4 and you type
        !          2154: 
        !          2155: @example
        !          2156: print x
        !          2157: set x=5
        !          2158: @end example
        !          2159: 
        !          2160: @noindent
        !          2161: then the value recorded in the value history by the @samp{print} command
        !          2162: remains 4 even though @code{x}'s value has changed.
        !          2163: 
        !          2164: @table @code
        !          2165: @item info history
        !          2166: @kindex info history
        !          2167: Print the last ten values in the value history, with their item
        !          2168: numbers.  This is like @samp{p $$9} repeated ten times, except that
        !          2169: @samp{info history} does not change the history.
        !          2170: 
        !          2171: @item info history @var{n}
        !          2172: Print ten history values centered on history item number @var{n}.
        !          2173: @end table
        !          2174: 
        !          2175: @node Convenience Vars, Registers, Value History, Data
        !          2176: @section Convenience Variables
        !          2177: 
        !          2178: @cindex convenience variables
        !          2179: GDB+ provides @dfn{convenience variables} that you can use within GDB+ to
        !          2180: hold on to a value and refer to it later.  These variables exist entirely
        !          2181: within GDB+; they are not part of your program, and setting a convenience
        !          2182: variable has no effect on further execution of your program.  That's why
        !          2183: you can use them freely.
        !          2184: 
        !          2185: Convenience variables have names starting with @samp{$}.  Any name starting
        !          2186: with @samp{$} can be used for a convenience variable, unless it is one of
        !          2187: the predefined set of register names (@pxref{Registers}).
        !          2188: 
        !          2189: You can save a value in a convenience variable with an assignment
        !          2190: expression, just as you would set a variable in your program.  Example:
        !          2191: 
        !          2192: @example
        !          2193: set $foo = *object_ptr
        !          2194: @end example
        !          2195: 
        !          2196: @noindent
        !          2197: would save in @samp{$foo} the value contained in the object pointed to by
        !          2198: @code{object_ptr}.
        !          2199: 
        !          2200: Using a convenience variable for the first time creates it; but its value
        !          2201: is @code{void} until you assign a new value.  You can alter the value with
        !          2202: another assignment at any time.
        !          2203: 
        !          2204: Convenience variables have no fixed types.  You can assign a convenience
        !          2205: variable any type of value, even if it already has a value of a different
        !          2206: type.  The convenience variable as an expression has whatever type its
        !          2207: current value has.
        !          2208: 
        !          2209: @table @code
        !          2210: @item info convenience
        !          2211: @kindex info convenience
        !          2212: Print a list of convenience variables used so far, and their values.
        !          2213: Abbreviated @samp{i con}.
        !          2214: @end table
        !          2215: 
        !          2216: One of the ways to use a convenience variable is as a counter to be
        !          2217: incremented or a pointer to be advanced.  For example:
        !          2218: 
        !          2219: @example
        !          2220: set $i = 0
        !          2221: print bar[$i++]->contents
        !          2222: @i{@dots{}repeat that command by typing @key{RET}.}
        !          2223: @end example
        !          2224: 
        !          2225: Some convenience variables are created automatically by GDB+ and given
        !          2226: values likely to be useful.
        !          2227: 
        !          2228: @table @samp
        !          2229: @item $_
        !          2230: The variable @samp{$_} is automatically set by the @samp{x} command to
        !          2231: the last address examined (@pxref{Memory}).  Other commands which
        !          2232: provide a default address for @samp{x} to examine also set @samp{$_}
        !          2233: to that address; these commands include @samp{info line} and @samp{info
        !          2234: breakpoint}.
        !          2235: 
        !          2236: @item $__
        !          2237: The variable @samp{$__} is automatically set by the @samp{x} command
        !          2238: to the value found in the last address examined.
        !          2239: @end table
        !          2240: 
        !          2241: @node Registers,, Convenience Vars, Data
        !          2242: @section Registers
        !          2243: 
        !          2244: @cindex registers
        !          2245: Machine register contents can be referred to in expressions as variables
        !          2246: with names starting with @samp{$}.  The names of registers are different
        !          2247: for each machine; use @samp{info registers} to see the names used on your
        !          2248: machine.  The names @samp{$pc} and @samp{$sp} are used on all machines for
        !          2249: the program counter register and the stack pointer.  Often @samp{$fp} is
        !          2250: used for a register that contains a pointer to the current stack frame.
        !          2251: 
        !          2252: GDB+ always considers the contents of an ordinary register as an integer
        !          2253: when the register is examined in this way.  Programs can store floating
        !          2254: point values in registers also, but there is currently no GDB+ command
        !          2255: to examine a specified register in floating point.  (However, if the
        !          2256: variable in your program which is stored in the register is a floating
        !          2257: point variable, you can see the floating point value by examining
        !          2258: the variable.)
        !          2259: 
        !          2260: Some machines have special floating point registers.  GDB+ considers these
        !          2261: registers' values as floating point when you examine them explicitly.
        !          2262: 
        !          2263: Some registers have distinct ``raw'' and ``virtual'' data formats.  This
        !          2264: means that the data format in which the register contents are saved by the
        !          2265: operating system is not the same one that your program normally sees.  For
        !          2266: example, the registers of the 68881 floating point coprocessor are always
        !          2267: saved in ``extended'' format, but all C programs expect to work with
        !          2268: ``double'' format.  In such cases, GDB+ normally works with the virtual
        !          2269: format only (the format that makes sense for your program), but the
        !          2270: @samp{info registers} command prints the data in both formats.
        !          2271: 
        !          2272: Register values are relative to the selected stack frame
        !          2273: (@pxref{Selection}).  This means that you get the value that the register
        !          2274: would contain if all stack frames farther in were exited and their saved
        !          2275: registers restored.  In order to see the real contents of all registers,
        !          2276: you must select the innermost frame (with @samp{frame 0}).
        !          2277: 
        !          2278: Some registers are never saved (typically those numbered zero or one)
        !          2279: because they are used for returning function values; for these registers,
        !          2280: relativization makes no difference.
        !          2281: 
        !          2282: @table @code
        !          2283: @item info registers
        !          2284: @kindex info registers
        !          2285: Print the names and relativized values of all registers.
        !          2286: 
        !          2287: @item info registers @var{regname}
        !          2288: Print the relativized value of register @var{regname}.  @var{regname}
        !          2289: may be any register name valid on the machine you are using, with
        !          2290: or without the initial @samp{$}.
        !          2291: @end table
        !          2292: 
        !          2293: @subsection Examples
        !          2294: 
        !          2295: You could print the program counter in hex with
        !          2296: 
        !          2297: @example
        !          2298: p/x $pc
        !          2299: @end example
        !          2300: 
        !          2301: @noindent
        !          2302: or print the instruction to be executed next with
        !          2303: 
        !          2304: @example
        !          2305: x/i $pc
        !          2306: @end example
        !          2307: 
        !          2308: @noindent
        !          2309: or add four to the stack pointer with
        !          2310: 
        !          2311: @example
        !          2312: set $sp += 4
        !          2313: @end example
        !          2314: 
        !          2315: @noindent
        !          2316: The last is a way of removing one word from the stack, on machines where
        !          2317: stacks grow downward in memory (most machines, nowadays).  This assumes
        !          2318: that the innermost stack frame is selected.  Setting @samp{$sp} is
        !          2319: not allowed when other stack frames are selected.
        !          2320: 
        !          2321: @node Symbols, Altering, Data, Top
        !          2322: @chapter Examining the Symbol Table
        !          2323: 
        !          2324: The commands described in this section allow you to make inquiries for
        !          2325: information about the symbols (names of variables, functions and types)
        !          2326: defined in your program.  This information is found by GDB+ in the symbol
        !          2327: table loaded by the @samp{symbol-file} command; it is inherent in the text
        !          2328: of your program and does not change as the program executes.
        !          2329: 
        !          2330: @table @code
        !          2331: @item whatis @var{exp}
        !          2332: @kindex whatis
        !          2333: Print the data type of expression @var{exp}.  @var{exp} is not
        !          2334: actually evaluated, and any side-effecting operations (such as
        !          2335: assignments or function calls) inside it do not take place.
        !          2336: 
        !          2337: @item whatis
        !          2338: Print the data type of @samp{$}, the last value in the value history.
        !          2339: 
        !          2340: @item info address @var{symbol}
        !          2341: @kindex info address
        !          2342: Describe where the data for @var{symbol} is stored.  For register
        !          2343: variables, this says which register.  For other automatic variables,
        !          2344: this prints the stack-frame offset at which the variable is always
        !          2345: stored.  Note the contrast with @samp{print &@var{symbol}}, which does
        !          2346: not work at all for register variables and for automatic variables
        !          2347: prints the exact address of the current instantiation of the variable.
        !          2348: 
        !          2349: @item ptype @var{typename}
        !          2350: @kindex ptype
        !          2351: Print a description of data type @var{typename}.  @var{typename} may be
        !          2352: the name of a type, or for C code it may have the form
        !          2353: @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
        !          2354: @samp{enum @var{enum-tag}}.@refill
        !          2355: 
        !          2356: @item info sources
        !          2357: @kindex info sources
        !          2358: Print the names of all source files in the program for which there
        !          2359: is debugging information.
        !          2360: 
        !          2361: @item info functions
        !          2362: @kindex info functions
        !          2363: Print the names and data types of all defined functions.
        !          2364: 
        !          2365: @item info functions @var{regexp}
        !          2366: Print the names and data types of all defined functions
        !          2367: whose names contain a match for regular expression @var{regexp}.
        !          2368: Thus, @samp{info fun step} finds all functions whose names
        !          2369: include @samp{step}; @samp{info fun ^step} finds those whose names
        !          2370: start with @samp{step}.
        !          2371: 
        !          2372: @item info variables
        !          2373: @kindex info variables
        !          2374: Print the names and data types of all variables that are declared
        !          2375: outside of functions.
        !          2376: 
        !          2377: @item info variables @var{regexp}
        !          2378: Print the names and data types of all variables, declared outside of
        !          2379: functions, whose names contain a match for regular expression
        !          2380: @var{regexp}.
        !          2381: 
        !          2382: @item info types
        !          2383: @kindex info types
        !          2384: Print all data types that are defined in the program.
        !          2385: 
        !          2386: @item info types @var{regexp}
        !          2387: Print all data types that are defined in the program whose names
        !          2388: contain a match for regular expression @var{regexp}.
        !          2389: 
        !          2390: @item printsyms @var{filename}
        !          2391: @kindex printsyms
        !          2392: Write a complete dump of the debugger's symbol data into the
        !          2393: file @var{filename}.
        !          2394: @end table
        !          2395: 
        !          2396: @node Altering, Sequences, Symbols, Top
        !          2397: @chapter Altering Execution
        !          2398: 
        !          2399: There are several ways to alter the execution of your program with GDB+
        !          2400: commands.
        !          2401: 
        !          2402: @menu
        !          2403: * Assignment::    Altering variable values or memory contents.
        !          2404: * Jumping::       Altering control flow.
        !          2405: * Signaling::     Making signals happen in the program.
        !          2406: * Returning::     Making a function return prematurely.
        !          2407: @end menu
        !          2408: 
        !          2409: @node Assignment, Jumping, Altering, Altering
        !          2410: @section Assignment to Variables
        !          2411: 
        !          2412: @cindex assignment
        !          2413: @cindex setting variables
        !          2414: To alter the value of a variable, evaluate an assignment expression.
        !          2415: For example,
        !          2416: 
        !          2417: @example
        !          2418: print x=4
        !          2419: @end example
        !          2420: 
        !          2421: @noindent
        !          2422: would store the value 4 into the variable @code{x}, and then print
        !          2423: the value of the assignment expression (which is 4).
        !          2424: 
        !          2425: @kindex set
        !          2426: If you are not interested in seeing the value of the assignment, use the
        !          2427: @samp{set} command instead of the @samp{print} command.  @samp{set} is
        !          2428: really the same as @samp{print} except that the expression's value is not
        !          2429: printed and is not put in the value history (@pxref{Value History}).  The
        !          2430: expression is evaluated only for side effects.
        !          2431: 
        !          2432: GDB+ allows more implicit conversions in assignments than C does; you can
        !          2433: freely store an integer value into a pointer variable or vice versa, and
        !          2434: any structure can be converted to any other structure that is the same
        !          2435: length or shorter.
        !          2436: 
        !          2437: In C, all the other assignment operators such as @samp{+=} and @samp{++}
        !          2438: are supported as well.
        !          2439: 
        !          2440: To store into arbitrary places in memory, use the @samp{@{@dots{}@}}
        !          2441: construct to generate a value of specified type at a specified address
        !          2442: (@pxref{Expressions}).  For example,
        !          2443: 
        !          2444: @example
        !          2445: set @{int@}0x83040 = 4
        !          2446: @end example
        !          2447: 
        !          2448: @node Jumping, Signaling, Assignment, Altering
        !          2449: @section Continuing at a Different Address
        !          2450: 
        !          2451: @table @code
        !          2452: @item jump @var{linenum}
        !          2453: @kindex jump
        !          2454: Resume execution at line number @var{linenum}.  Execution may stop
        !          2455: immediately if there is a breakpoint there.
        !          2456: 
        !          2457: The @samp{jump} command does not change the current stack frame, or
        !          2458: the stack pointer, or the contents of any memory location or any
        !          2459: register other than the program counter.  If line @var{linenum} is in
        !          2460: a different function from the one currently executing, the results may
        !          2461: be wild if the two functions expect different patterns of arguments or
        !          2462: of local variables.  For his reason, the @samp{jump} command requests
        !          2463: confirmation if the specified line is not in the function currently
        !          2464: executing.  However, even wild results are predictable based on
        !          2465: changing the program counter.
        !          2466: 
        !          2467: @item jump *@var{address}
        !          2468: Resume execution at the instruction at address @var{address}.
        !          2469: @end table
        !          2470: 
        !          2471: A similar effect can be obtained by storing a new value into the register
        !          2472: @samp{$pc}, but not exactly the same.
        !          2473: 
        !          2474: @example
        !          2475: set $pc = 0x485
        !          2476: @end example
        !          2477: 
        !          2478: @noindent
        !          2479: specifies the address at which execution will resume, but does not resume
        !          2480: execution.  That does not happen until you use the @samp{cont} command or a
        !          2481: stepping command (@pxref{Stepping}).
        !          2482: 
        !          2483: @node Signaling, Returning, Jumping, Altering
        !          2484: @section Giving the Program a Signal
        !          2485: 
        !          2486: @table @code
        !          2487: @item signal @var{signalnum}
        !          2488: @kindex signal
        !          2489: Resume execution where the program stopped, but give it immediately
        !          2490: the signal number @var{signalnum}.
        !          2491: 
        !          2492: Alternatively, if @var{signalnum} is zero, continue execution and give
        !          2493: no signal.  This may be useful when the program has received a signal
        !          2494: and the @samp{cont} command would allow the program to see that
        !          2495: signal.
        !          2496: @end table
        !          2497: 
        !          2498: @node Returning,, Signaling, Altering
        !          2499: @section Returning from a Function
        !          2500: 
        !          2501: @cindex returning from a function
        !          2502: @kindex return
        !          2503: You can make any function call return immediately, using the @samp{return}
        !          2504: command.
        !          2505: 
        !          2506: First select the stack frame that you wish to return from
        !          2507: (@pxref{Selection}).  Then type the @samp{return} command.  If you wish to
        !          2508: specify the value to be returned, give that as an argument.
        !          2509: 
        !          2510: This pops the selected stack frame (and any other frames inside of it),
        !          2511: leaving its caller as the innermost remaining frame.  That frame becomes
        !          2512: selected.  The specified value is stored in the registers used for
        !          2513: returning values of functions.
        !          2514: 
        !          2515: The @samp{return} command does not resume execution; it leaves the program
        !          2516: stopped in the state that would exist if the function had just returned.
        !          2517: Contrast this with the @samp{finish} command (@pxref{Stepping}), which
        !          2518: resumes execution @i{until} the selected stack frame returns naturally.
        !          2519: 
        !          2520: @node Sequences, Emacs, Altering, Top
        !          2521: @chapter Canned Sequences of Commands
        !          2522: 
        !          2523: GDB+ provides two ways to store sequences of commands for execution as a
        !          2524: unit: user-defined commands and command files.
        !          2525: 
        !          2526: @menu
        !          2527: * Define::         User-defined commands.
        !          2528: * Command Files::  Command files.
        !          2529: * Output::         Controlled output commands useful in
        !          2530:                    user-defined commands and command files.
        !          2531: @end menu
        !          2532: 
        !          2533: @node Define, Command Files, Sequences, Sequences
        !          2534: @section User-Defined Commands
        !          2535: 
        !          2536: @cindex user-defined commands
        !          2537: A @dfn{user-defined command} is a sequence of GDB+ commands to which you
        !          2538: assign a new name as a command.  This is done with the @samp{define}
        !          2539: command.
        !          2540: 
        !          2541: @table @code
        !          2542: @item define @var{commandname}
        !          2543: @kindex define
        !          2544: Define a command named @var{commandname}.  If there is already a command
        !          2545: by that name, you are asked to confirm that you want to redefine it.
        !          2546: 
        !          2547: The definition of the command is made up of other GDB+ command lines,
        !          2548: which are given following the @samp{define} command.  The end of these
        !          2549: commands is marked by a line containing @samp{end}.
        !          2550: 
        !          2551: @item document @var{commandname}
        !          2552: @kindex document
        !          2553: Give documentation to the user-defined command @var{commandname}.  The
        !          2554: command @var{commandname} must already be defined.  This command reads
        !          2555: lines of documentation just as @samp{define} reads the lines of the
        !          2556: command definition.  After the @samp{document} command is finished,
        !          2557: @samp{help} on command @var{commandname} will print the documentation
        !          2558: you have specified.
        !          2559: 
        !          2560: You may use the @samp{document} command again to change the
        !          2561: documentation of a command.  Redefining the command with @samp{define}
        !          2562: does not change the documentation.
        !          2563: @end table
        !          2564: 
        !          2565: User-defined commands do not take arguments.  When they are executed, the
        !          2566: commands of the definition are not printed.  An error in any command
        !          2567: stops execution of the user-defined command.
        !          2568: 
        !          2569: Commands that would ask for confirmation if used interactively proceed
        !          2570: without asking when used inside a user-defined command.  Many GDB+ commands
        !          2571: that normally print messages to say what they are doing omit the messages
        !          2572: when used in user-defined command.
        !          2573: 
        !          2574: @node Command Files, Output, Define, Sequences
        !          2575: @section Command Files
        !          2576: 
        !          2577: @cindex command files
        !          2578: A command file for GDB+ is a file of lines that are GDB+ commands.  Comments
        !          2579: (lines starting with @samp{#}) may also be included.  An empty line in a
        !          2580: command file does nothing; it does not mean to repeat the last command, as
        !          2581: it would from the terminal.
        !          2582: 
        !          2583: @cindex init file
        !          2584: @cindex .gdbinit
        !          2585: When GDB+ starts, it automatically executes its @dfn{init files}, command
        !          2586: files named @file{.gdbinit}.  GDB+ reads the init file (if any) in your home
        !          2587: directory and then the init file (if any) in the current working
        !          2588: directory.  (The init files are not executed if the @samp{-nx} option
        !          2589: is given.)  You can also request the execution of a command file with the
        !          2590: @samp{source} command:
        !          2591: 
        !          2592: @table @code
        !          2593: @item source @var{filename}
        !          2594: @kindex source
        !          2595: Execute the command file @var{filename}.
        !          2596: @end table
        !          2597: 
        !          2598: The lines in a command file are executed sequentially.  They are not
        !          2599: printed as they are executed.  An error in any command terminates execution
        !          2600: of the command file.
        !          2601: 
        !          2602: Commands that would ask for confirmation if used interactively proceed
        !          2603: without asking when used in a command file.  Many GDB+ commands that
        !          2604: normally print messages to say what they are doing omit the messages
        !          2605: when used in a command file.
        !          2606: 
        !          2607: @node Output,, Command Files, Sequences
        !          2608: @section Commands for Controlled Output
        !          2609: 
        !          2610: During the execution of a command file or a user-defined command, the only
        !          2611: output that appears is what is explicitly printed by the commands of the
        !          2612: definition.  This section describes three commands useful for generating
        !          2613: exactly the output you want.
        !          2614: 
        !          2615: @table @code
        !          2616: @item echo @var{text}
        !          2617: @kindex echo
        !          2618: Print @var{text}.  Nonprinting characters can be included in
        !          2619: @var{text} using C escape sequences, such as @samp{\n} to print a
        !          2620: newline.  @b{No newline will be printed unless you specify one.}
        !          2621: 
        !          2622: A backslash at the end of @var{text} is ignored.  It is useful for
        !          2623: outputting a string ending in spaces, since trailing spaces are
        !          2624: trimmed from all arguments.  A backslash at the beginning preserves
        !          2625: leading spaces in the same way, because @samp{\ } as an escape
        !          2626: sequence stands for a space.  Thus, to print @samp{ and foo = }, do
        !          2627: 
        !          2628: @example
        !          2629: echo \ and foo = \
        !          2630: @end example
        !          2631: 
        !          2632: @item output @var{expression}
        !          2633: @kindex output
        !          2634: Print the value of @var{expression} and nothing but that value: no
        !          2635: newlines, no @samp{$@var{nn} = }.  The value is not entered in the
        !          2636: value history either.
        !          2637: 
        !          2638: @item output/@var{fmt} @var{expression}
        !          2639: Print the value of @var{expression} in format @var{fmt}.
        !          2640: @xref{Formats}, for more information.
        !          2641: 
        !          2642: @item printf @var{string}, @var{expressions}@dots{}
        !          2643: @kindex printf
        !          2644: Print the values of the @var{expressions} under the control of
        !          2645: @var{string}.  The @var{expressions} are separated by commas and may
        !          2646: be either numbers or pointers.  Their values are printed as specified
        !          2647: by @var{string}, exactly as if the program were to execute
        !          2648: 
        !          2649: @example
        !          2650: printf (@var{string}, @var{expressions}@dots{});
        !          2651: @end example
        !          2652: 
        !          2653: For example, you can print two values in hex like this:
        !          2654: 
        !          2655: @example
        !          2656: printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
        !          2657: @end example
        !          2658: 
        !          2659: The only backslash-escape sequences that you can use in the string are
        !          2660: the simple ones that consist of backslash followed by a letter.
        !          2661: @end table
        !          2662: 
        !          2663: @node Emacs, Remote, Sequences, Top
        !          2664: @chapter Using GDB under GNU Emacs
        !          2665: 
        !          2666: A special interface allows you to use GNU Emacs to view (and
        !          2667: edit) the source files for the program you are debugging with
        !          2668: GDB.
        !          2669: 
        !          2670: To use this interface, use the command @kbd{M-x gdb} in Emacs.
        !          2671: Give the executable file you want to debug as an argument.  This
        !          2672: command starts a GDB process as a subprocess of Emacs, with input
        !          2673: and output through a newly created Emacs buffer.
        !          2674: 
        !          2675: Using this GDB process is just like using GDB normally except for two things:
        !          2676: 
        !          2677: @itemize @bullet
        !          2678: @item
        !          2679: All ``terminal'' input and output goes through the Emacs buffer.  This
        !          2680: applies both to GDB commands and their output, and to the input and
        !          2681: output done by the program you are debugging.
        !          2682: 
        !          2683: This is useful because it means that you can copy the text of previous
        !          2684: commands and input them again; you can even use parts of the output
        !          2685: in this way.
        !          2686: 
        !          2687: All the facilities of Emacs's Shell mode are available for this purpose.
        !          2688: 
        !          2689: @item
        !          2690: GDB displays source code through Emacs.  Each time GDB displays a
        !          2691: stack frame, Emacs automatically finds the source file for that frame
        !          2692: and puts an arrow (@samp{=>}) at the left margin of the current line.
        !          2693: 
        !          2694: Explicit GDB @samp{list} or search commands still produce output as
        !          2695: usual, but you probably will have no reason to use them.
        !          2696: @end itemize
        !          2697: 
        !          2698: In the GDB I/O buffer, you can use these special Emacs commands:
        !          2699: 
        !          2700: @table @kbd
        !          2701: @item M-s
        !          2702: Execute to another source line, like the GDB @samp{step} command.
        !          2703: 
        !          2704: @item M-n
        !          2705: Execute to next source line in this function, skipping all function
        !          2706: calls, like the GDB @samp{next} command.
        !          2707: 
        !          2708: @item M-i
        !          2709: Execute one instruction, like the GDB @samp{stepi} command.
        !          2710: 
        !          2711: @item M-u
        !          2712: Move up one stack frame (and display that frame's source file in
        !          2713: Emacs), like the GDB @samp{up} command.
        !          2714: 
        !          2715: @item M-d
        !          2716: Move down one stack frame (and display that frame's source file in
        !          2717: Emacs), like the GDB @samp{down} command.  (This means that you cannot
        !          2718: delete words in the usual fashion in the GDB buffer; I am guessing you
        !          2719: won't often want to do that.)
        !          2720: 
        !          2721: @item C-c C-f
        !          2722: Execute until exit from the selected stack frame, like the GDB
        !          2723: @samp{finish} command.
        !          2724: @end table
        !          2725: 
        !          2726: In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
        !          2727: tells GDB to set a breakpoint on the source line point is on.
        !          2728: 
        !          2729: The source files displayed in Emacs are in ordinary Emacs buffers
        !          2730: which are visiting the source files in the usual way.  You can edit
        !          2731: the files with these buffers if you wish; but keep in mind that GDB
        !          2732: communicates with Emacs in terms of line numbers.  If you add or
        !          2733: delete lines from the text, the line numbers that GDB knows will cease
        !          2734: to correspond properly to the code.
        !          2735: 
        !          2736: @node Remote, Commands, Emacs, Top
        !          2737: @chapter Remote Kernel Debugging
        !          2738: 
        !          2739: GDB has a special facility for debugging a remote machine via a serial
        !          2740: connection.  This can be used for kernel debugging.
        !          2741: 
        !          2742: The program to be debugged on the remote machine needs to contain a
        !          2743: debugging device driver which talks to GDB over the serial line using the
        !          2744: protocol described below.  The same version of GDB that is used ordinarily
        !          2745: can be used for this.
        !          2746: 
        !          2747: @menu
        !          2748: * Remote Commands::       Commands used to start and finish remote debugging.
        !          2749: @end menu
        !          2750: 
        !          2751: For details of the communication protocol, see the comments in the GDB
        !          2752: source file @file{remote.c}.
        !          2753: 
        !          2754: @node Remote Commands,, Remote, Remote
        !          2755: @section Commands for Remote Debugging
        !          2756: 
        !          2757: To start remote debugging, first run GDB and specify as an executable file
        !          2758: the program that is running in the remote machine.  This tells GDB how
        !          2759: to find the program's symbols and the contents of its pure text.  Then
        !          2760: establish communication using the @samp{attach} command with a device
        !          2761: name rather than a pid as an argument.  For example:
        !          2762: 
        !          2763: @example
        !          2764: attach /dev/ttyd
        !          2765: @end example
        !          2766: 
        !          2767: @noindent
        !          2768: if the serial line is connected to the device named @file{/dev/ttyd}.  This
        !          2769: will stop the remote machine if it is not already stopped.
        !          2770: 
        !          2771: Now you can use all the usual commands to examine and change data and to
        !          2772: step and continue the remote program.
        !          2773: 
        !          2774: To resume the remote program and stop debugging it, use the @samp{detach}
        !          2775: command.
        !          2776: 
        !          2777: @node Commands, Concepts, Remote, Top
        !          2778: @unnumbered Command Index
        !          2779: 
        !          2780: @printindex ky
        !          2781: 
        !          2782: @node Concepts,, Commands, Top
        !          2783: @unnumbered Concept Index
        !          2784: 
        !          2785: @printindex cp
        !          2786: 
        !          2787: @contents
        !          2788: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.