Return to gdb-1 CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/info/gdb-1, revision 1.1

1.1     ! root        1: Info file gdb, produced by texinfo-format-buffer   -*-Text-*-
        !             2: from file gdb.texinfo
        !             3: 
        !             4: This file documents the GNU debugger GDB.
        !             5: 
        !             6: Copyright (C) 1988 Free Software Foundation, Inc.
        !             7: 
        !             8: Permission is granted to make and distribute verbatim copies of
        !             9: this manual provided the copyright notice and this permission notice
        !            10: are preserved on all copies.
        !            11: 
        !            12: Permission is granted to copy and distribute modified versions of this
        !            13: manual under the conditions for verbatim copying, provided also that the
        !            14: sections entitled "Distribution" and "GDB General Public License" are
        !            15: included exactly as in the original, and provided that the entire resulting
        !            16: derived work is distributed under the terms of a permission notice
        !            17: identical to this one.
        !            18: 
        !            19: Permission is granted to copy and distribute translations of this manual
        !            20: into another language, under the above conditions for modified versions,
        !            21: except that the sections entitled "Distribution" and "GDB General Public
        !            22: License" may be included in a translation approved by the author instead
        !            23: of in the original English.
        !            24: 
        !            25: 
        !            26: 
        !            27: File: gdb  Node: Top, Up: (DIR), Next: Commands
        !            28: 
        !            29: Summary of GDB
        !            30: **************
        !            31: 
        !            32: The purpose of a debugger such as GDB is to allow you to execute another
        !            33: program while examining what is going on inside it.  We call the other
        !            34: program "your program" or "the program being debugged".
        !            35: 
        !            36: GDB can do four kinds of things (plus other things in support of these):
        !            37: 
        !            38:   1. Start the program, specifying anything that might affect its behavior.
        !            39:      
        !            40:   2. Make the program stop on specified conditions.
        !            41:      
        !            42:   3. Examine what has happened, when the program has stopped, so that you
        !            43:      can see bugs happen.
        !            44:      
        !            45:   4. Change things in the program, so you can correct the effects of one bug
        !            46:      and go on to learn about another without having to recompile first.
        !            47: 
        !            48: * Menu:
        !            49: 
        !            50: * License::    The GDB General Public License gives you permission
        !            51:               to redistribute GDB on certain terms; and also
        !            52:               explains that there is no warranty.
        !            53: * Input::      GDB command syntax and input conventions.
        !            54: * Files::      Specifying files for GDB to operate on.
        !            55: * Options::    GDB arguments and options.
        !            56: * Compilation::Compiling your program so you can debug it.
        !            57: * Running::    Running your program under GDB.
        !            58: * Stopping::   Making your program stop.  Why it may stop.  What to do then.
        !            59: * Stack::      Examining your program's stack.
        !            60: * Source::     Examining your program's source files.
        !            61: * Data::       Examining data in your program.
        !            62: * Symbols::    Examining the debugger's symbol table.
        !            63: * Altering::   Altering things in your program.
        !            64: * Sequences::  Canned command sequences for repeated use.
        !            65: * Emacs::      Using GDB through GNU Emacs.
        !            66: * Remote::     Remote kernel debugging across a serial line.
        !            67: * Commands::   Index of GDB commands.
        !            68: * Concepts::   Index of GDB concepts.
        !            69: 
        !            70: 
        !            71: File: gdb  Node: License, Prev: Top, Up: Top, Next: Input
        !            72: 
        !            73: GDB General Public License
        !            74: **************************
        !            75:                           (Clarified 11 Feb 1988)
        !            76: 
        !            77:   The license agreements of most software companies keep you at the mercy
        !            78: of those companies.  By contrast, our general public license is intended to
        !            79: give everyone the right to share GDB.  To make sure that you get the rights
        !            80: we want you to have, we need to make restrictions that forbid anyone to
        !            81: deny you these rights or to ask you to surrender the rights.  Hence this
        !            82: license agreement.
        !            83: 
        !            84:   Specifically, we want to make sure that you have the right to give away
        !            85: copies of GDB, that you receive source code or else can get it if you want
        !            86: it, that you can change GDB or use pieces of it in new free programs, and
        !            87: that you know you can do these things.
        !            88: 
        !            89:   To make sure that everyone has such rights, we have to forbid you to
        !            90: deprive anyone else of these rights.  For example, if you distribute copies
        !            91: of GDB, you must give the recipients all the rights that you have.  You
        !            92: must make sure that they, too, receive or can get the source code.  And you
        !            93: must tell them their rights.
        !            94: 
        !            95:   Also, for our own protection, we must make certain that everyone finds
        !            96: out that there is no warranty for GDB.  If GDB is modified by someone else
        !            97: and passed on, we want its recipients to know that what they have is not
        !            98: what we distributed, so that any problems introduced by others will not
        !            99: reflect on our reputation.
        !           100: 
        !           101:   Therefore we (Richard Stallman and the Free Software Foundation,
        !           102: Inc.) make the following terms which say what you must do to be
        !           103: allowed to distribute or change GDB.
        !           104: 
        !           105: 
        !           106: Copying Policies
        !           107: ================
        !           108: 
        !           109:   1. You may copy and distribute verbatim copies of GDB source code as you
        !           110:      receive it, in any medium, provided that you conspicuously and
        !           111:      appropriately publish on each file a valid copyright notice "Copyright
        !           112:      (C) 1988 Free Software Foundation, Inc." (or with whatever year
        !           113:      is appropriate); keep intact the notices on all files that
        !           114:      refer to this License Agreement and to the absence of any warranty; and
        !           115:      give any other recipients of the GDB program a copy of this License
        !           116:      Agreement along with the program.  You may charge a distribution fee
        !           117:      for the physical act of transferring a copy.
        !           118:      
        !           119:   2. You may modify your copy or copies of GDB source code or any portion
        !           120:      of it, and copy and distribute such modifications under the terms of
        !           121:      Paragraph 1 above, provided that you also do the following:
        !           122:      
        !           123:         * cause the modified files to carry prominent notices stating
        !           124:           that you changed the files and the date of any change; and
        !           125:           
        !           126:         * cause the whole of any work that you distribute or publish, that
        !           127:           in whole or in part contains or is a derivative of GDB or any
        !           128:           part thereof, to be licensed at no charge to all third parties on
        !           129:           terms identical to those contained in this License Agreement
        !           130:           (except that you may choose to grant more extensive warranty
        !           131:           protection to some or all third parties, at your option).
        !           132:           
        !           133:         * if the modified program serves as a debugger, cause it, when
        !           134:           started running in the simplest and usual way, to print an
        !           135:           announcement including a valid copyright notice "Copyright
        !           136:           (C) 1988 Free Software Foundation, Inc." (or with the
        !           137:           year that is appropriate), saying that there is no warranty (or
        !           138:           else, saying that you provide a warranty) and that users may
        !           139:           redistribute the program under these conditions, and telling the
        !           140:           user how to view a copy of this License Agreement.
        !           141:           
        !           142:         * You may charge a distribution fee for the physical act of
        !           143:           transferring a copy, and you may at your option offer warranty
        !           144:           protection in exchange for a fee.
        !           145:      
        !           146:      Mere aggregation of another unrelated program with this program (or its
        !           147:      derivative) on a volume of a storage or distribution medium does not bring
        !           148:      the other program under the scope of these terms.
        !           149:      
        !           150:   3. You may copy and distribute GDB (or a portion or derivative of it,
        !           151:      under Paragraph 2) in object code or executable form under the terms
        !           152:      of Paragraphs 1 and 2 above provided that you also do one of the
        !           153:      following:
        !           154:      
        !           155:         * accompany it with the complete corresponding machine-readable
        !           156:           source code, which must be distributed under the terms of
        !           157:           Paragraphs 1 and 2 above; or,
        !           158:           
        !           159:         * accompany it with a written offer, valid for at least three
        !           160:           years, to give any third party free (except for a nominal
        !           161:           shipping charge) a complete machine-readable copy of the
        !           162:           corresponding source code, to be distributed under the terms of
        !           163:           Paragraphs 1 and 2 above; or,
        !           164:           
        !           165:         * accompany it with the information you received as to where the
        !           166:           corresponding source code may be obtained.  (This alternative is
        !           167:           allowed only for noncommercial distribution and only if you
        !           168:           received the program in object code or executable form alone.)
        !           169:      
        !           170:      For an executable file, complete source code means all the source code
        !           171:      for all modules it contains; but, as a special exception, it need not
        !           172:      include source code for modules which are standard libraries that
        !           173:      accompany the operating system on which the executable file runs.
        !           174:      
        !           175:   4. You may not copy, sublicense, distribute or transfer GDB except as
        !           176:      expressly provided under this License Agreement.  Any attempt
        !           177:      otherwise to copy, sublicense, distribute or transfer GDB is void and
        !           178:      your rights to use GDB under this License agreement shall be
        !           179:      automatically terminated.  However, parties who have received computer
        !           180:      software programs from you with this License Agreement will not have
        !           181:      their licenses terminated so long as such parties remain in full
        !           182:      compliance.
        !           183:      
        !           184:   5. If you wish to incorporate parts of GDB into other free programs whose
        !           185:      distribution conditions are different, write to the Free Software
        !           186:      Foundation.  We have not yet worked out a simple rule that can be
        !           187:      stated here, but we will often permit this.  We will be guided by the
        !           188:      two goals of preserving the free status of all derivatives our free
        !           189:      software and of promoting the sharing and reuse of software.
        !           190: 
        !           191: 
        !           192: NO WARRANTY
        !           193: ===========
        !           194: 
        !           195:   BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
        !           196: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
        !           197: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
        !           198: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB "AS IS"
        !           199: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
        !           200: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        !           201: FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY
        !           202: AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE GDB
        !           203: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
        !           204: SERVICING, REPAIR OR CORRECTION.
        !           205: 
        !           206:  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
        !           207: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
        !           208: MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
        !           209: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
        !           210: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        !           211: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
        !           212: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
        !           213: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
        !           214: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
        !           215: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
        !           216: OTHER PARTY.
        !           217: 
        !           218: 
        !           219: File: gdb  Node: Input, Prev: License, Up: Top, Next: Files
        !           220: 
        !           221: GDB Input Conventions
        !           222: *********************
        !           223: 
        !           224: GDB is invoked with the shell command `gdb'.  Once started, it reads
        !           225: commands from the terminal until you tell it to exit.
        !           226: 
        !           227: A GDB command is a single line of input.  There is no limit on how long
        !           228: it can be.  It starts with a command name, which is followed by arguments
        !           229: whose meaning depends on the command name.  Some command names do not
        !           230: allow arguments.
        !           231: 
        !           232: GDB command names may always be abbreviated if the abbreviation is
        !           233: unambiguous.  Sometimes even ambiguous abbreviations are allowed; for
        !           234: example, `s' is specially defined as equivalent to `step'
        !           235: even though there are other commands whose names start with `s'.
        !           236: Possible command abbreviations are often stated in the documentation
        !           237: of the individual commands.
        !           238: 
        !           239: A blank line as input to GDB means to repeat the previous command verbatim.
        !           240: Certain commands do not allow themselves to be repeated this way; these are
        !           241: commands for which unintentional repetition might cause trouble and which
        !           242: you are unlikely to want to repeat.  Certain others (`list' and
        !           243: `x') act differently when repeated because that is more useful.
        !           244: 
        !           245: A line of input starting with `#' is a comment; it does nothing.
        !           246: This is useful mainly in command files (*Note Command Files::).
        !           247: 
        !           248: GDB "prompts" for commands with a string that is normally `(gdb)'.
        !           249: When debugging GDB with GDB, it is useful to change the prompt in one of
        !           250: the GDBs so that you can distinguish them.  This can be done with the
        !           251: `set-prompt' command.
        !           252: 
        !           253: `set-prompt NEWPROMPT'     
        !           254:      Directs GDB to use NEWPROMPT as its prompt string henceforth.
        !           255: 
        !           256: To exit GDB, use the `quit' command (abbreviated `q').
        !           257: `Ctrl-c' will not exit from GDB, but rather will terminate the action
        !           258: of any GDB command that is in progress and return to GDB command level.
        !           259: It is safe to type `Ctrl-c' at any time because GDB does not allow
        !           260: it to take effect until a time when it is safe.
        !           261: 
        !           262: 
        !           263: File: gdb  Node: Files, Prev: Input, Up: Top, Next: Options
        !           264: 
        !           265: Specifying GDB's Files
        !           266: **********************
        !           267: 
        !           268: GDB needs to know the filename of the program to be debugged.  To debug a
        !           269: core dump of a previous run, GDB must be told the filename of the core
        !           270: dump.
        !           271: 
        !           272: * Menu:
        !           273: 
        !           274: * Arguments: File Arguments.   Specifying files with arguments
        !           275:                                 (when you start GDB).
        !           276: * Commands: File Commands.     Specifying files with GDB commands.
        !           277: 
        !           278: 
        !           279: File: gdb  Node: File Arguments, Prev: Files, Up: Files, Next: File Commands
        !           280: 
        !           281: Specifying Files with Arguments
        !           282: ===============================
        !           283: 
        !           284: The usual way to specify the executable and core dump file names is with
        !           285: two command arguments given when you start GDB.  The first argument is used
        !           286: as the file for execution and symbols, and the second argument (if any) is
        !           287: used as the core dump file name.  Thus,
        !           288: 
        !           289:      gdb progm core
        !           290: 
        !           291: specifies `progm' as the executable program and `core' as a core
        !           292: dump file to examine.  (You do not need to have a core dump file if what
        !           293: you plan to do is debug the program interactively.)
        !           294: 
        !           295: *Note Options::, for full information on command options and arguments for
        !           296: GDB.
        !           297: 
        !           298: 
        !           299: File: gdb  Node: File Commands, Prev: File Arguments, Up: Files
        !           300: 
        !           301: Specifying Files with Commands
        !           302: ==============================
        !           303: 
        !           304: Usually you specify the files for GDB to work with by giving arguments when
        !           305: you invoke GDB.  But occasionally it is necessary to change to a different
        !           306: file during a GDB session.  Or you may run GDB and forget to specify the
        !           307: files you want to use.  In these situations the GDB commands to specify new
        !           308: files are useful.
        !           309: 
        !           310: `exec-file FILENAME'     
        !           311:      Specify that the program to be run is found in FILENAME.  If you
        !           312:      do not specify a directory and the file is not found in GDB's working
        !           313:      directory, GDB will use the environment variable `PATH' as a list
        !           314:      of directories to search, just as the shell does when looking for a
        !           315:      program to run.
        !           316:      
        !           317: `symbol-file FILENAME'     
        !           318:      Read symbol table information from file FILENAME.  `PATH'
        !           319:      is searched when necessary.  Most of the time you will use both the
        !           320:      `exec-file' and `symbol-file' commands on the same file.
        !           321:      
        !           322:      `symbol-file' with no argument clears out GDB's symbol table.
        !           323:      
        !           324: `core-file FILENAME'     
        !           325:      Specify the whereabouts of a core dump file to be used as the
        !           326:      "contents of memory".  Note that the core dump contains only the
        !           327:      writable parts of memory; the read-only parts must come from the
        !           328:      executable file.
        !           329:      
        !           330:      `core-file' with no argument specifies that no core file is
        !           331:      to be used.
        !           332:      
        !           333: `kill'     
        !           334:      Cancel running the program under GDB.  This could be used if you wish
        !           335:      to debug a core dump instead.  GDB ignores any core dump file if it is
        !           336:      actually running the program, so the `kill' command is the only
        !           337:      sure way to go back to using the core dump file.
        !           338:      
        !           339: `info files'     
        !           340:      Print the names of the executable and core dump files currently in
        !           341:      use by GDB, and the file from which symbols were loaded.
        !           342: 
        !           343: While all three file-specifying commands allow both absolute and relative
        !           344: file names as arguments, GDB always converts the file name to an absolute
        !           345: one and remembers it that way.
        !           346: 
        !           347: The `symbol-file' command causes GDB to forget the contents of its
        !           348: convenience variables, the value history, and all breakpoints and
        !           349: auto-display expressions.  This is because they may contain pointers to the
        !           350: internal data recording symbols and data types, which are part of the old
        !           351: symbol table data being discarded inside GDB.
        !           352: 
        !           353: 
        !           354: File: gdb  Node: Options, Prev: Files, Up: Top, Next: Compilation
        !           355: 
        !           356: Options and Arguments for GDB
        !           357: *****************************
        !           358: 
        !           359: When you invoke GDB, you can pass commands telling it what files to
        !           360: operate on and what other things to do.
        !           361: 
        !           362: * Menu:
        !           363: 
        !           364: * Mode Options::     Options controlling modes of operation.
        !           365: * File Options::     Options to specify files (executable, coredump, commands)
        !           366: * Other Arguments::  Any other arguments without options
        !           367:                        also specify files.
        !           368: 
        !           369: 
        !           370: File: gdb  Node: Mode Options, Prev: Options, Up: Options, Next: File Options
        !           371: 
        !           372: Mode Options
        !           373: ============
        !           374: 
        !           375: `-nx'     
        !           376:      Do not execute commands from the init files `.gdbinit'.
        !           377:      Normally, the commands in these files are executed after all the
        !           378:      command options and arguments have been processed.  *Note Command Files::.
        !           379:      
        !           380: `-q'     
        !           381:      "Quiet".  Do not print the usual introductory messages.
        !           382:      
        !           383: `-batch'     
        !           384:      Run in batch mode.  Exit with code 1 after processing all the command
        !           385:      files specified with `-x' (and `.gdbinit', if not
        !           386:      inhibited).  Exit also if, due to an error, GDB would otherwise
        !           387:      attempt to read a command from the terminal.
        !           388:      
        !           389: `-fullname'     
        !           390:      This option is used when Emacs runs GDB as a subprocess.  It tells GDB
        !           391:      to output the full file name and line number in a standard,
        !           392:      recognizable fashion each time a stack frame is displayed (which
        !           393:      includes each time the program stops).  This recognizable format looks
        !           394:      like two `\032' characters, followed by the filename, line number
        !           395:      and character position separated by colons, and a newline.  The
        !           396:      Emacs-to-GDB interface program uses the two `\032' characters as
        !           397:      a signal to display the source code for the frame.
        !           398: 
        !           399: 
        !           400: File: gdb  Node: File Options, Prev: Mode Options, Up: Options, Next: Other Arguments
        !           401: 
        !           402: File-specifying Options
        !           403: =======================
        !           404: 
        !           405: All the options and command line arguments given are processed
        !           406: in sequential order.  The order makes a difference when the
        !           407: `-x' command is used.
        !           408: 
        !           409: `-s FILE'     
        !           410:      Read symbol table from file FILE.
        !           411:      
        !           412: `-e FILE'     
        !           413:      Use file FILE as the executable file to execute when
        !           414:      appropriate, and for examining pure data in conjunction with a core
        !           415:      dump.
        !           416:      
        !           417: `-se FILE'     
        !           418:      Read symbol table from file FILE and use it as the executable
        !           419:      file.
        !           420:      
        !           421: `-c FILE'     
        !           422:      Use file FILE as a core dump to examine.
        !           423:      
        !           424: `-x FILE'     
        !           425:      Execute GDB commands from file FILE.
        !           426:      
        !           427: `-d DIRECTORY'     
        !           428:      Add DIRECTORY to the path to search for source files.
        !           429: 
        !           430: 
        !           431: File: gdb  Node: Other Arguments, Prev: File Options, Up: Options
        !           432: 
        !           433: Other Arguments
        !           434: ===============
        !           435: 
        !           436: If there are arguments to GDB that are not options or associated with
        !           437: options, the first one specifies the symbol table and executable file name
        !           438: (as if it were preceded by `-se') and the second one specifies a core
        !           439: dump file name (as if it were preceded by `-c').
        !           440: 
        !           441: 
        !           442: File: gdb  Node: Compilation, Prev: Options, Up: Top, Next: Running
        !           443: 
        !           444: Compiling Your Program for Debugging
        !           445: ************************************
        !           446: 
        !           447: In order to debug a program effectively, you need to ask for debugging
        !           448: information when you compile it.  This information in the object file
        !           449: describes the data type of each variable or function and the correspondence
        !           450: between source line numbers and addresses in the executable code.
        !           451: 
        !           452: To request debugging information, specify the `-g' option when you run
        !           453: the compiler.
        !           454: 
        !           455: The Unix C compiler is unable to handle the `-g' and `-O' options
        !           456: together.  This means that you cannot ask for optimization if you ask for
        !           457: debugger information.
        !           458: 
        !           459: The GNU C compiler supports `-g' with or without `-O', making it
        !           460: possible to debug optimized code.  We recommend that you *always* use
        !           461: `-g' whenever you compile a program.  You may think the program is
        !           462: correct, but there's no sense in pushing your luck.
        !           463: 
        !           464: If you are using the GNU C compiler, the GNU assembler and the GNU linker,
        !           465: you can choose between two formats of debugging information: the standard
        !           466: Unix format, which is what you get with `-g', and GDB's own format,
        !           467: which you request by using `-gg' instead of `-g'.  This stores
        !           468: debugging information in the executable file in a format much like that
        !           469: which is used inside GDB.  This has these advantages and disadvantages:
        !           470: 
        !           471:    * GDB can read `-gg' format more than twice as fast as Unix
        !           472:      `-g' format.
        !           473:      
        !           474:    * The `-gg' format uses much more disk space than Unix format.
        !           475:      
        !           476:    * The Unix debuggers can understand only Unix format, so you cannot use
        !           477:      Unix source-level debuggers if you compile with `-gg'.  (The
        !           478:      `adb' debugger works with either format; it does not use this
        !           479:      information in any case.)
        !           480: 
        !           481: 
        !           482: File: gdb  Node: Running, Prev: Compilation, Up: Top, Next: Stopping
        !           483: 
        !           484: Running Your Program Under GDB
        !           485: ******************************
        !           486: 
        !           487: To start your program under GDB, use the `run' command.  The program
        !           488: must already have been specified using the `exec-file' command or with
        !           489: an argument to GDB (*Note Files::); what `run' does is create an
        !           490: inferior process, load the program into it, and set it in motion.
        !           491: 
        !           492: The execution of a program is affected by certain information it receives
        !           493: from its superior.  GDB provides ways to specify them, which you must do
        !           494: before starting the program.  (You can change them after starting the
        !           495: program, but such changes do not affect the program unless you start it
        !           496: over again.)
        !           497: 
        !           498: The arguments.     
        !           499:      You specify the arguments to give the program as the arguments of the
        !           500:      `run' command.
        !           501:      
        !           502: The environment.     
        !           503:      The program normally inherits its environment from GDB, but you can
        !           504:      use the GDB commands `set-environment' and `unset-environment' to
        !           505:      change parts of the environment that will be given to the program.
        !           506:      
        !           507: The working directory.     
        !           508:      The program inherits its working directory from GDB.  You can set GDB's
        !           509:      working directory with the `cd' command in GDB.
        !           510: 
        !           511: After the `run' command, the debugger does nothing but wait for your
        !           512: program to stop.  *Note Stopping::.
        !           513: 
        !           514: * Menu:
        !           515: 
        !           516: * Arguments::          Specifying the arguments for your program.
        !           517: * Environment::        Specifying the environment for your program.
        !           518: * Working Directory::  Specifying the working directory for giving
        !           519:                        to your program when it is run.
        !           520: * Input/Output::       Specifying the program's standard input and output.
        !           521: * Attach::             Debugging a process started outside GDB.
        !           522: 
        !           523: 
        !           524: File: gdb  Node: Arguments, Prev: Running, Up: Running, Next: Environment
        !           525: 
        !           526: Your Program's Arguments
        !           527: ========================
        !           528: 
        !           529: You specify the arguments to give the program as the arguments of the
        !           530: `run' command.  They are passed to a shell, which expands wildcard
        !           531: characters and performs redirection of I/O, and thence to the program.
        !           532: 
        !           533: `run' with no arguments uses the same arguments used by the previous
        !           534: `run'.
        !           535: 
        !           536: The command `set-args' can be used to specify the arguments to be used
        !           537: the next time the program is run.  If `set-args' has no arguments, it
        !           538: means to use no arguments the next time the program is run.  If you have
        !           539: run your program with arguments and want to run it again with no arguments,
        !           540: this is the only way to do so.
        !           541: 
        !           542: 
        !           543: File: gdb  Node: Environment, Prev: Arguments, Up: Running, Next: Working Directory
        !           544: 
        !           545: Your Program's Environment
        !           546: ==========================
        !           547: 
        !           548: The "environment" consists of a set of "environment variables" and
        !           549: their values.  Environment variables conventionally record such things as
        !           550: your user name, your home directory, your terminal type, and your search
        !           551: path for programs to run.  Usually you set up environment variables with
        !           552: the shell and they are inherited by all the other programs you run.  When
        !           553: debugging, it can be useful to try running the program with different
        !           554: environments without having to start the debugger over again.
        !           555: 
        !           556: `info environment VARNAME'     
        !           557:      Print the value of environment variable VARNAME to be given to
        !           558:      your program when it is started.  This command can be abbreviated
        !           559:      `i env VARNAME'.
        !           560:      
        !           561: `info environment'     
        !           562:      Print the names and values of all environment variables to be given to
        !           563:      your program when it is started.  This command can be abbreviated
        !           564:      `i env'.
        !           565:      
        !           566: `set-environment VARNAME VALUE'     
        !           567:      Sets environment variable VARNAME to VALUE, for your
        !           568:      program only, not for GDB itself.  VALUE may be any string; the
        !           569:      values of environment variables are just strings, and any
        !           570:      interpretation is supplied by your program itself.  This command
        !           571:      can be abbreviated as short as `set-e'.
        !           572:      
        !           573: `unset-environment VARNAME'     
        !           574:      Remove variable VARNAME from the environment to be passed to
        !           575:      your program.  This is different from `set-env VARNAME ='
        !           576:      because `unset-environment' makes a variable not be defined at
        !           577:      all, which is distinguishable from an empty value.  This command can
        !           578:      be abbreviated `unset'.
        !           579: 
        !           580: 
        !           581: File: gdb  Node: Working Directory, Prev: Environment, Up: Running, Next: Input/Output
        !           582: 
        !           583: Your Program's Working Directory
        !           584: ================================
        !           585: 
        !           586: Each time you start your program with `run', it inherits its working
        !           587: directory from the current working directory of GDB.  GDB's working
        !           588: directory is initially whatever it inherited from its superior, but you can
        !           589: specify the working directory for GDB with the `cd' command.
        !           590: 
        !           591: The GDB working directory also serves as a default for the commands
        !           592: that specify files for GDB to operate on.  *Note Files::.
        !           593: 
        !           594: `cd DIRECTORY'     
        !           595:      Set GDB's working directory to DIRECTORY.
        !           596:      
        !           597: `pwd'     
        !           598:      Print GDB's working directory.
        !           599: 
        !           600: 
        !           601: File: gdb  Node: Input/Output, Prev: Working Directory, Up: Running, Next: Attach
        !           602: 
        !           603: Your Program's Input and Output
        !           604: ===============================
        !           605: 
        !           606: By default, the program you run under GDB does input and output to the same
        !           607: terminal that GDB uses.
        !           608: 
        !           609: You can redirect the program's input and/or output using `sh'-style
        !           610: redirection commands in the `run' command.  For example,
        !           611: 
        !           612:      run > outfile
        !           613: 
        !           614: starts the program, diverting its output to the file `outfile'.
        !           615: 
        !           616: Another way to specify where the program should do input and output is with
        !           617: the `tty' command.  This command accepts a file name as argument, and
        !           618: causes this file to be the default for future `run' commands.  For
        !           619: example,
        !           620: 
        !           621:      tty /dev/ttyb
        !           622: 
        !           623: directs that processes started with subsequent `run' commands default
        !           624: to do input and output on the terminal `/dev/ttyb'.  An explicit
        !           625: redirection in `run' overrides the `tty' command.
        !           626: 
        !           627: When you use the `tty' command or redirect input in the `run'
        !           628: command, the *input for your program* comes from the specified file,
        !           629: but the input for GDB still comes from your terminal.  The program's
        !           630: controlling terminal is your (GDB's) terminal, not the terminal that the
        !           631: program is reading from; so if you want to type `C-c' to stop the
        !           632: program, you must type it on your (GDB's) terminal.  A `C-c' typed on
        !           633: the program's terminal is available to the program as ordinary input.
        !           634: 
        !           635: 
        !           636: File: gdb  Node: Attach, Prev: Input/Output, Up: Running
        !           637: 
        !           638: Debugging an Already-Running Process
        !           639: ====================================
        !           640: 
        !           641: Some operating systems (in particular, Sun) allow GDB to begin debugging an
        !           642: already-running process that was started outside of GDB.  To do this you
        !           643: must use the `attach' command instead of the `run' command.
        !           644: 
        !           645: The `attach' command requires one argument, which is the process-id of
        !           646: the process you want to debug.  (The usual way to find out the process-id
        !           647: of the process is with the `ps' utility.)
        !           648: 
        !           649: The first thing GDB after arranging to debug the process is to stop it.
        !           650: You can examine and modify an attached process with all the GDB commands
        !           651: that ordinarily available when you start processes with `run'.  You
        !           652: can insert breakpoints; you can step and continue; you can modify storage.
        !           653: If you would rather the process continue running, use the `continue'
        !           654: command after attaching.
        !           655: 
        !           656: When you are finished debugging the attached process, you can use the
        !           657: `detach' command to release it from GDB's control.  Detaching
        !           658: the process continues its execution.  After the `detach' command,
        !           659: that process and GDB become completely independent once more, and you
        !           660: are ready to `attach' another process or start one with `run'.
        !           661: 
        !           662: If you exit GDB or use the `run' command while you have an attached
        !           663: process, you kill that process.  You will be asked for confirmation if you
        !           664: try to do either of these things.
        !           665: 
        !           666: 
        !           667: File: gdb  Node: Stopping, Prev: Running, Up: Top, Next: Stack
        !           668: 
        !           669: Stopping and Continuing
        !           670: ***********************
        !           671: 
        !           672: When you run a program normally, it runs until exiting.  The purpose
        !           673: of using a debugger is so that you can stop it before that point;
        !           674: or so that if the program runs into trouble you can find out why.
        !           675: 
        !           676: * Menu:
        !           677: 
        !           678: * Signals::      Fatal signals in your program just stop it;
        !           679:                  then you can use GDB to see what is going on.
        !           680: * Breakpoints::  Breakpoints let you stop your program when it
        !           681:                  reaches a specified point in the code.
        !           682: * Continuing::   Resuming execution until the next signal or breakpoint.
        !           683: * Stepping::     Stepping runs the program a short distance and
        !           684:                  then stops it wherever it has come to.
        !           685: 
        !           686: 
        !           687: File: gdb  Node: Signals, Prev: Stopping, Up: Stopping, Next: Breakpoints
        !           688: 
        !           689: Signals
        !           690: =======
        !           691: 
        !           692: A signal is an asynchronous event that can happen in a program.  The
        !           693: operating system defines the possible kinds of signals, and gives each kind
        !           694: a name and a number.  For example, `SIGINT' is the signal a program
        !           695: gets when you type `Ctrl-c'; `SIGSEGV' is the signal a program
        !           696: gets from referencing a place in memory far away from all the areas in use;
        !           697: `SIGALRM' occurs when the alarm clock timer goes off (which happens
        !           698: only if the program has requested an alarm).
        !           699: 
        !           700: Some signals, including `SIGALRM', are a normal part of the
        !           701: functioning of the program.  Others, such as `SIGSEGV', indicate
        !           702: errors; these signals are "fatal" (kill the program immediately) if the
        !           703: program has not specified in advance some other way to handle the signal.
        !           704: `SIGINT' does not indicate an error in the program, but it is normally
        !           705: fatal so it can carry out the purpose of `Ctrl-c': to kill the program.
        !           706: 
        !           707: GDB has the ability to detect any occurrence of a signal in the program
        !           708: running under GDB's control.  You can tell GDB in advance what to do for
        !           709: each kind of signal.
        !           710: 
        !           711: Normally, GDB is set up to ignore non-erroneous signals like `SIGALRM'
        !           712: (so as not to interfere with their role in the functioning of the program)
        !           713: but to stop the program immediately whenever an error signal happens.
        !           714: You can change these settings with the `handle' command.  You must
        !           715: specify which signal you are talking about with its number.
        !           716: 
        !           717: `info signal'     
        !           718:      Print a table of all the kinds of signals and how GDB has been told to
        !           719:      handle each one.  You can use this to see the signal numbers of all
        !           720:      the defined types of signals.
        !           721:      
        !           722: `handle SIGNALNUM KEYWORDS...'     
        !           723:      Change the way GDB handles signal SIGNALNUM.  The KEYWORDS
        !           724:      say what change to make.
        !           725: 
        !           726: To use the `handle' command you must know the code number of the
        !           727: signal you are concerned with.  To find the code number, type `info
        !           728: signal' which prints a table of signal names and numbers.
        !           729: 
        !           730: The keywords allowed by the handle command can be abbreviated.  Their full
        !           731: names are
        !           732: 
        !           733: `stop'     
        !           734:      GDB should stop the program when this signal happens.  This implies
        !           735:      the `print' keyword as well.
        !           736:      
        !           737: `print'     
        !           738:      GDB should print a message when this signal happens.
        !           739:      
        !           740: `nostop'     
        !           741:      GDB should not stop the program when this signal happens.  It may
        !           742:      still print a message telling you that the signal has come in.
        !           743:      
        !           744: `noprint'     
        !           745:      GDB should not mention the occurrence of the signal at all.  This
        !           746:      implies the `nostop' keyword as well.
        !           747:      
        !           748: `pass'     
        !           749:      GDB should allow the program to see this signal; the program will be
        !           750:      able to handle the signal, or may be terminated if the signal is fatal
        !           751:      and not handled.
        !           752:      
        !           753: `nopass'     
        !           754:      GDB should not allow the program to see this signal.
        !           755: 
        !           756: When a signal has been set to stop the program, the program cannot see the
        !           757: signal until you continue.  It will see the signal then, if `pass' is
        !           758: in effect for the signal in question at that time.  In other words,
        !           759: after GDB reports a signal, you can use the `handle' command with
        !           760: `pass' or `nopass' to control whether that signal will be seen by
        !           761: the program when you later continue it.
        !           762: 
        !           763: You can also use the `signal' command to prevent the program from
        !           764: seeing a signal, or cause it to see a signal it normally would not see,
        !           765: or to give it any signal at any time.  *Note Signaling::.
        !           766: 
        !           767: 
        !           768: File: gdb  Node: Breakpoints, Prev: Signals, Up: Stopping, Next: Continuing
        !           769: 
        !           770: Breakpoints
        !           771: ===========
        !           772: 
        !           773: A "breakpoint" makes your program stop whenever a certain point in the
        !           774: program is reached.  You set breakpoints explicitly with GDB commands,
        !           775: specifying the place where the program should stop by line number, function
        !           776: name or exact address in the program.  You can add various other conditions
        !           777: to control whether the program will stop.
        !           778: 
        !           779: Each breakpoint is assigned a number when it is created; these numbers are
        !           780: successive integers starting with 1.  In many of the commands for controlling
        !           781: various features of breakpoints you use the breakpoint number to say which
        !           782: breakpoint you want to change.  Each breakpoint may be "enabled" or
        !           783: "disabled"; if disabled, it has no effect on the program until you
        !           784: enable it again.
        !           785: 
        !           786: The command `info break' prints a list of all breakpoints set and not
        !           787: cleared, showing their numbers, where in the program they are, and any
        !           788: special features in use for them.  Disabled breakpoints are included in the
        !           789: list, but marked as disabled.  `info break' with a breakpoint number
        !           790: as argument lists only that breakpoint.  The convenience variable `$_'
        !           791: and the default examining-address for the `x' command are set to the
        !           792: address of the last breakpoint listed (*Note Memory::).
        !           793: 
        !           794: * Menu:
        !           795: 
        !           796: * Set Breaks::     How to establish breakpoints.
        !           797: * Clear Breaks::   How to remove breakpoints no longer needed.
        !           798: * Disabling::      How to disable breakpoints (turn them off temporarily).
        !           799: * Conditions::     Making extra conditions on whether to stop.
        !           800: * Break Commands:: Commands to be executed at a breakpoint.
        !           801: * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
        !           802: 
        !           803: 
        !           804: File: gdb  Node: Set Breaks, Prev: Breakpoints, Up: Breakpoints, Next: Clear Breaks
        !           805: 
        !           806: Setting Breakpoints
        !           807: -------------------
        !           808: 
        !           809: Breakpoints are set with the `break' command (abbreviated `b').
        !           810: You have several ways to say where the breakpoint should go.
        !           811: 
        !           812: `break FUNCTION'     
        !           813:      Set a breakpoint at entry to function FUNCTION.
        !           814:      
        !           815: `break LINENUM'     
        !           816:      Set a breakpoint at line LINENUM in the current source file.
        !           817:      That file is the last file whose source text was printed.  This
        !           818:      breakpoint will stop the program just before it executes any of the
        !           819:      code on that line.
        !           820:      
        !           821: `break FILENAME:LINENUM'     
        !           822:      Set a breakpoint at line LINENUM in source file FILENAME.
        !           823:      
        !           824: `break FILENAME:FUNCTION'     
        !           825:      Set a breakpoint at entry to function FUNCTION found in file
        !           826:      FILENAME.  Specifying a filename as well as a function name is
        !           827:      superfluous except when multiple files contain similarly named
        !           828:      functions.
        !           829:      
        !           830: `break *ADDRESS'     
        !           831:      Set a breakpoint at address ADDRESS.  You can use this to set
        !           832:      breakpoints in parts of the program which do not have debugging
        !           833:      information or source files.
        !           834:      
        !           835: `break'     
        !           836:      Set a breakpoint at the next instruction to be executed in the
        !           837:      selected stack frame (*Note Stack::).  This is a silly thing to do in
        !           838:      the innermost stack frame because the program would stop immediately
        !           839:      after being started, but it is very useful with another stack frame,
        !           840:      because it will cause the program to stop as soon as control returns
        !           841:      to that frame.
        !           842:      
        !           843: `break ... if COND'     
        !           844:      Set a breakpoint with condition COND; evaluate the expression
        !           845:      COND each time the breakpoint is reached, and stop only if the
        !           846:      value is nonzero.  `...' stands for one of the possible
        !           847:      arguments described above (or no argument) specifying where to break.
        !           848:      *Note Conditions::, for more information on breakpoint conditions.
        !           849:      
        !           850: `tbreak ARGS'     
        !           851:      Set a breakpoint enabled only for one stop.  ARGS are the
        !           852:      same as in the `break' command, and the breakpoint is set in the same
        !           853:      way, but the breakpoint is automatically "disabled" the first time it
        !           854:      is hit.
        !           855: 
        !           856: GDB allows you to set any number of breakpoints at the same place in the
        !           857: program.  There is nothing silly or meaningless about this.  When the
        !           858: breakpoints are conditional, this is even useful (*Note Conditions::).
        !           859: 
        !           860: 
        !           861: File: gdb  Node: Clear Breaks, Prev: Set Breaks, Up: Breakpoints, Next: Disabling
        !           862: 
        !           863: Clearing Breakpoints
        !           864: --------------------
        !           865: 
        !           866: It is often necessary to eliminate a breakpoint once it has done its job
        !           867: and you no longer want the program to stop there.  This is called
        !           868: "clearing" or `deleting' the breakpoint.  A breakpoint that
        !           869: has been cleared no longer exists in any sense.
        !           870: 
        !           871: With the `clear' command you can clear breakpoints according to where
        !           872: they are in the program.  With the `delete' command you can clear
        !           873: individual breakpoints by specifying their breakpoint numbers.
        !           874: 
        !           875: It is not necessary to clear a breakpoint to proceed past it.  GDB
        !           876: automatically ignores breakpoints in the first instruction to be executed
        !           877: when you continue execution at the same address where the program stopped.
        !           878: 
        !           879: `clear'     
        !           880:      Clear any breakpoints at the next instruction to be executed in the
        !           881:      selected stack frame (*Note Selection::).  When the innermost frame
        !           882:      is selected, this is a good way to clear a breakpoint that the program
        !           883:      just stopped at.
        !           884:      
        !           885: `clear FUNCTION'     
        !           886: `clear FILENAME:FUNCTION'     
        !           887:      Clear any breakpoints set at entry to the function FUNCTION.
        !           888:      
        !           889: `clear LINENUM'     
        !           890: `clear FILENAME:LINENUM'     
        !           891:      Clear any breakpoints set at or within the code of the specified line.
        !           892:      
        !           893: `delete BNUMS...'     
        !           894:      Delete the breakpoints of the numbers specified as arguments.
        !           895:      A breakpoint deleted is forgotten completely.
        !           896: 
        !           897: 
        !           898: File: gdb  Node: Disabling, Prev: Clear Breaks, Up: Breakpoints, Next: Conditions
        !           899: 
        !           900: Disabling Breakpoints
        !           901: ---------------------
        !           902: 
        !           903: Rather than clearing a breakpoint, you might prefer to "disable" it.
        !           904: This makes the breakpoint inoperative as if it had been cleared, but
        !           905: remembers the information on the breakpoint so that you can "enable"
        !           906: it again later.
        !           907: 
        !           908: You disable and enable breakpoints with the `enable' and
        !           909: `disable' commands, specifying one or more breakpoint numbers as
        !           910: arguments.  Use `info break' to print a list of breakpoints if you
        !           911: don't know which breakpoint numbers to use.
        !           912: 
        !           913: A breakpoint can have any of four different states of enablement:
        !           914: 
        !           915:    * Enabled.  The breakpoint will stop the program.  A breakpoint made
        !           916:      with the `break' command starts out in this state.
        !           917:    * Disabled.  The breakpoint has no effect on the program.
        !           918:    * Enabled once.  The breakpoint will stop the program, but
        !           919:      when it does so it will become disabled.  A breakpoint made
        !           920:      with the `tbreak' command starts out in this state.
        !           921:    * Enabled for deletion.  The breakpoint will stop the program, but
        !           922:      immediately after it does so it will be deleted permanently.
        !           923: 
        !           924: You change the state of enablement of a breakpoint with the following
        !           925: commands:
        !           926: 
        !           927: `disable BNUMS...'     
        !           928:      Disable the specified breakpoints.  A disabled breakpoint has no
        !           929:      effect but is not forgotten.  All options such as ignore-counts,
        !           930:      conditions and commands are remembered in case the breakpoint is
        !           931:      enabled again later.
        !           932:      
        !           933: `enable BNUMS...'     
        !           934:      Enable the specified breakpoints.  They become effective once again in
        !           935:      stopping the program, until you specify otherwise.
        !           936:      
        !           937: `enable once BNUMS...'     
        !           938:      Enable the specified breakpoints temporarily.  Each will be disabled
        !           939:      again the next time it stops the program (unless you have used one of
        !           940:      these commands to specify a different state before that time comes).
        !           941:      
        !           942: `enable delete BNUMS...'     
        !           943:      Enable the specified breakpoints to work once and then die.  Each of
        !           944:      the breakpoints will be deleted the next time it stops the program
        !           945:      (unless you have used one of these commands to specify a different
        !           946:      state before that time comes).
        !           947: 
        !           948: Aside from the automatic disablement or deletion of a breakpoint when it
        !           949: stops the program, which happens only in certain states, the state of
        !           950: enablement of a breakpoint changes only when one of the commands above
        !           951: is used.
        !           952: 
        !           953: 
        !           954: File: gdb  Node: Conditions, Prev: Disabling, Up: Breakpoints, Next: Break Commands
        !           955: 
        !           956: Break Conditions
        !           957: ----------------
        !           958: 
        !           959: The simplest sort of breakpoint breaks every time the program reaches a
        !           960: specified place.  You can also specify a "condition" for a breakpoint.
        !           961: A condition is just a boolean expression in your programming language.
        !           962: A breakpoint with a condition evaluates the expression each time the
        !           963: program reaches it, and the program stops only if the condition is true.
        !           964: 
        !           965: Break conditions may have side effects, and may even call functions in your
        !           966: program.  These may sound like strange things to do, but their effects are
        !           967: completely predictable unless there is another enabled breakpoint at the
        !           968: same address.  (In that case, GDB might see the other breakpoint first and
        !           969: stop the program without checking the condition of this one.)  Note that
        !           970: breakpoint commands are usually more convenient and flexible for the
        !           971: purpose of performing side effects when a breakpoint is reached
        !           972: (*Note Break Commands::).
        !           973: 
        !           974: Break conditions can be specified when a breakpoint is set, by using
        !           975: `if' in the arguments to the `break' command.  *Note Set Breaks::.
        !           976: They can also be changed at any time with the `condition' command:
        !           977: 
        !           978: `condition BNUM EXPRESSION'     
        !           979:      Specify EXPRESSION as the break condition for breakpoint number
        !           980:      BNUM.  From now on, this breakpoint will stop the program only if
        !           981:      the value of EXPRESSION is true (nonzero, in C).  EXPRESSION
        !           982:      is not evaluated at the time the `condition' command is given.
        !           983:      
        !           984: `condition BNUM'     
        !           985:      Remove the condition from breakpoint number BNUM.  It becomes
        !           986:      an ordinary unconditional breakpoint.
        !           987: 
        !           988: A special feature is provided for one kind of condition: to prevent the
        !           989: breakpoint from doing anything until it has been reached a certain number
        !           990: of times.  This is done with the "ignore count" of the breakpoint.
        !           991: When the program reaches a breakpoint whose ignore count is positive, then
        !           992: instead of stopping, it just decrements the ignore count by one and
        !           993: continues.
        !           994: 
        !           995: `ignore BNUM COUNT'     
        !           996:      Set the ignore count of breakpoint number BNUM to COUNT.
        !           997:      The next COUNT times the breakpoint is reached, it will not stop.
        !           998:      
        !           999:      To make the breakpoint stop the next time it is reached, specify
        !          1000:      a count of zero.
        !          1001:      
        !          1002: `cont COUNT'     
        !          1003:      Continue execution of the program, setting the ignore count of the
        !          1004:      breakpoint that the program stopped at to COUNT minus one.
        !          1005:      Continuing through the breakpoint does not itself count as one of
        !          1006:      COUNT.  Thus, the program will not stop at this breakpoint until the
        !          1007:      COUNT'th time it is hit.
        !          1008:      
        !          1009:      This command is allowed only when the program stopped due to a
        !          1010:      breakpoint.  At other times, the argument to `cont' is ignored.
        !          1011: 
        !          1012: If a breakpoint has a positive ignore count and a condition, the condition
        !          1013: is not checked.  Once the ignore count reaches zero, the condition will
        !          1014: start to be checked.
        !          1015: 
        !          1016: Note that you could achieve the effect of the ignore count with a condition
        !          1017: such as `$foo-- <= 0' using a debugger convenience variable that is
        !          1018: decremented each time.  That is why the ignore count is considered a
        !          1019: special case of a condition.  *Note Convenience Vars::.
        !          1020: 
        !          1021: 
        !          1022: File: gdb  Node: Break Commands, Prev: Conditions, Up: Breakpoints, Next: Error in Breakpoints
        !          1023: 
        !          1024: Commands Executed on Breaking
        !          1025: -----------------------------
        !          1026: 
        !          1027: You can give any breakpoint a series of commands to execute when the
        !          1028: program stops due to that breakpoint.  For example, you might want to
        !          1029: print the values of certain expressions, or enable other breakpoints.
        !          1030: 
        !          1031: `commands BNUM'     
        !          1032:      Specify commands for breakpoint number BNUM.  The commands
        !          1033:      themselves appear on the following lines.  Type a line containing just
        !          1034:      `end' to terminate the commands.
        !          1035:      
        !          1036:      To remove all commands from a breakpoint, use the command
        !          1037:      `commands' and follow it immediately by `end'; that is, give
        !          1038:      no commands.
        !          1039: 
        !          1040: It is possible for breakpoint commands to start the program up again.
        !          1041: Simply use the `cont' command, or `step', or any other command
        !          1042: to resume execution.  However, any remaining breakpoint commands are
        !          1043: ignored.  When the program stops again, GDB will act according to why
        !          1044: that stop took place.
        !          1045: 
        !          1046: If the first command specified is `silent', the usual message about
        !          1047: stopping at a breakpoint is not printed.  This may be desirable for
        !          1048: breakpoints that are to print a specific message and then continue.
        !          1049: If the remaining commands too print nothing, you will see no sign that
        !          1050: the breakpoint was reached at all.  `silent' is not really a command;
        !          1051: it is meaningful only at the beginning of the commands for a breakpoint.
        !          1052: 
        !          1053: The commands `echo' and `output' that allow you to print precisely
        !          1054: controlled output are often useful in silent breakpoints.  *Note Output::.
        !          1055: 
        !          1056: For example, here is how you could use breakpoint commands to print the
        !          1057: value of `x' at entry to `foo' whenever it is positive.  We
        !          1058: assume that the newly created breakpoint is number 4; `break' will
        !          1059: print the number that is assigned.
        !          1060: 
        !          1061:      break foo if x>0
        !          1062:      commands 4
        !          1063:      silent
        !          1064:      echo x is\040
        !          1065:      output x
        !          1066:      echo \n
        !          1067:      cont
        !          1068:      end
        !          1069: 
        !          1070: One application for breakpoint commands is to correct one bug so you can
        !          1071: test another.  Put a breakpoint just after the erroneous line of code, give
        !          1072: it a condition to detect the case in which something erroneous has been
        !          1073: done, and give it commands to assign correct values to any variables that
        !          1074: need them.  End with the `cont' command so that the program does not
        !          1075: stop, and start with the `silent' command so that no output is
        !          1076: produced.  Here is an example:
        !          1077: 
        !          1078:      break 403
        !          1079:      commands 5
        !          1080:      silent
        !          1081:      set x = y + 4
        !          1082:      cont
        !          1083:      end
        !          1084: 
        !          1085: One deficiency in the operation of automatically continuing breakpoints
        !          1086: under Unix appears when your program uses raw mode for the terminal.
        !          1087: GDB options back to its own terminal modes (not raw) before executing
        !          1088: commands, and then must switch back to raw mode when your program is
        !          1089: continued.  This causes any pending terminal input to be lost.
        !          1090: 
        !          1091: In the GNU system, this will be fixed by changing the behavior of
        !          1092: terminal modes.
        !          1093: 
        !          1094: Under Unix, when you have this problem, you might be able to get around
        !          1095: it by putting your actions into the breakpoint condition instead of
        !          1096: commands.  For example
        !          1097: 
        !          1098:      condition 5  (x = y + 4), 0
        !          1099: 
        !          1100: is a condition expression that will change `x' as needed, then always
        !          1101: have the value 0 so the program will not stop.  Loss of input is avoided
        !          1102: here because break conditions are evaluated without changing the terminal
        !          1103: modes.  When you want to have nontrivial conditions for performing the side
        !          1104: effects, the operators `&&', `||' and `? ... :' may be useful.
        !          1105: 
        !          1106: 
        !          1107: File: gdb  Node: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints
        !          1108: 
        !          1109: "Cannot Insert Breakpoints" Error
        !          1110: ---------------------------------
        !          1111: 
        !          1112: Under Unix, breakpoints cannot be used in a program if any other process
        !          1113: is running that program.  Attempting to run or continue the program with
        !          1114: a breakpoint in this case will cause GDB to stop it.
        !          1115: 
        !          1116: When this happens, you have two ways to proceed:
        !          1117: 
        !          1118:   1. Remove or disable the breakpoints, then continue.
        !          1119:      
        !          1120:   2. Suspend GDB, and copy the file containing the program to a new name.
        !          1121:      Resume GDB and use the `exec-file' command to specify that GDB
        !          1122:      should run the program under that name.  Then start the program again.
        !          1123: 
        !          1124: 
        !          1125: File: gdb  Node: Continuing, Prev: Breakpoints, Up: Stopping, Next: Stepping
        !          1126: 
        !          1127: Continuing
        !          1128: ==========
        !          1129: 
        !          1130: After your program stops, most likely you will want it to run some more if
        !          1131: the bug you are looking for has not happened yet.
        !          1132: 
        !          1133: `cont'     
        !          1134:      Continue running the program at the place where it stopped.
        !          1135: 
        !          1136: If the program stopped at a breakpoint, the place to continue running
        !          1137: is the address of the breakpoint.  You might expect that continuing would
        !          1138: just stop at the same breakpoint immediately.  In fact, `cont'
        !          1139: takes special care to prevent that from happening.  You do not need
        !          1140: to clear the breakpoint to proceed through it after stopping at it.
        !          1141: 
        !          1142: You can, however, specify an ignore-count for the breakpoint that the
        !          1143: program stopped at, by means of an argument to the `cont' command.
        !          1144: *Note Conditions::.
        !          1145: 
        !          1146: If the program stopped because of a signal other than `SIGINT' or
        !          1147: `SIGTRAP', continuing will cause the program to see that signal.
        !          1148: You may not want this to happen.  For example, if the program stopped
        !          1149: due to some sort of memory reference error, you might store correct
        !          1150: values into the erroneous variables and continue, hoping to see more
        !          1151: execution; but the program would probably terminate immediately as
        !          1152: a result of the fatal signal once it sees the signal.  To prevent this,
        !          1153: you can continue with `signal 0'.  *Note Signaling::.  You can
        !          1154: also act in advance to prevent the program from seeing certain kinds
        !          1155: of signals, using the `handle' command (*Note Signals::).
        !          1156: 
        !          1157: 
        !          1158: File: gdb  Node: Stepping, Prev: Continuing, Up: Stopping
        !          1159: 
        !          1160: Stepping
        !          1161: ========
        !          1162: 
        !          1163: "Stepping" means setting your program in motion for a limited time, so
        !          1164: that control will return automatically to the debugger after one line of
        !          1165: code or one machine instruction.  Breakpoints are active during stepping
        !          1166: and the program will stop for them even if it has not gone as far as the
        !          1167: stepping command specifies.
        !          1168: 
        !          1169: `step'     
        !          1170:      Proceed the program until control reaches a different line, then stop
        !          1171:      it and return to the debugger.  This command is abbreviated `s'.
        !          1172:      
        !          1173: `step COUNT'     
        !          1174:      Proceed as in `step', but do so COUNT times.  If a breakpoint
        !          1175:      or a signal not related to stepping is reached before COUNT steps,
        !          1176:      stepping stops right away.
        !          1177:      
        !          1178: `next'     
        !          1179:      Similar to `step', but any function calls appearing within the line of
        !          1180:      code are executed without stopping.  Execution stops when control reaches a
        !          1181:      different line of code at the stack level which was executing when the
        !          1182:      `next' command was given.  This command is abbreviated `n'.
        !          1183:      
        !          1184:      An argument is a repeat count, as in `step'.
        !          1185:      
        !          1186: `finish'     
        !          1187:      Continue running until just after the selected stack frame returns
        !          1188:      (or until there is some other reason to stop, such as a fatal signal
        !          1189:      or a breakpoint).
        !          1190:      
        !          1191:      Contrast this with the `return' command (*Note Returning::).
        !          1192:      
        !          1193: `stepi'     
        !          1194: `si'     
        !          1195:      Proceed one machine instruction, then stop and return to the debugger.
        !          1196:      
        !          1197:      It is often useful to do `display/i $pc' when stepping by machine
        !          1198:      instructions.  This will cause the next instruction to be executed to
        !          1199:      be displayed automatically at each stop.  *Note Auto Display::.
        !          1200:      
        !          1201:      An argument is a repeat count, as in `step'.
        !          1202:      
        !          1203: `nexti'     
        !          1204: `ni'     
        !          1205:      Proceed one machine instruction, but if it is a subroutine call,
        !          1206:      proceed until the subroutine returns.
        !          1207:      
        !          1208:      An argument is a repeat count, as in `next'.
        !          1209: 
        !          1210: A typical technique for using stepping is to put a breakpoint
        !          1211: (*Note Breakpoints::) at the beginning of the function or the section of
        !          1212: the program in which a problem is believed to lie, and then step through
        !          1213: the suspect area, examining the variables that are interesting, until the
        !          1214: problem happens.
        !          1215: 
        !          1216: The `cont' command can be used after stepping to resume execution
        !          1217: until the next breakpoint or signal.
        !          1218: 
        !          1219: 

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