Return to gdb.texinfo CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man

Annotation of 43BSDReno/contrib/emacs-18.55/man/gdb.texinfo, revision 1.1

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

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