Return to gdb-2 CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/info/gdb-2, 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: Stack, Prev: Stopping, Up: Top, Next: Source
        !            28: 
        !            29: Examining the Stack
        !            30: *******************
        !            31: 
        !            32: When your program has stopped, the first thing you need to know is where it
        !            33: stopped and how it got there.
        !            34: 
        !            35: Each time your program performs a function call, the information about
        !            36: where in the program the call was made from is saved in a block of data
        !            37: called a "stack frame".  The frame also contains the arguments of the
        !            38: call and the local variables of the function that was called.  All the
        !            39: stack frames are allocated in a region of memory called the "call
        !            40: stack".
        !            41: 
        !            42: When your program stops, the GDB commands for examining the stack allow you
        !            43: to see all of this information.
        !            44: 
        !            45: One of the stack frames is "selected" by GDB and many GDB commands
        !            46: refer implicitly to the selected frame.  In particular, whenever you ask
        !            47: GDB for the value of a variable in the program, the value is found in the
        !            48: selected frame.  There are special GDB commands to select whichever frame
        !            49: you are interested in.
        !            50: 
        !            51: When the program stops, GDB automatically selects the currently executing
        !            52: frame and describes it briefly as the `frame' command does
        !            53: (*Note Info: Frame Info.).
        !            54: 
        !            55: * Menu:
        !            56: 
        !            57: * Frames::          Explanation of stack frames and terminology.
        !            58: * Backtrace::       Summarizing many frames at once.
        !            59: * Selection::       How to select a stack frame.
        !            60: * Info: Frame Info, Commands to print information on stack frames.
        !            61: 
        !            62: 
        !            63: File: gdb  Node: Frames, Prev: Stack, Up: Stack, Next: Backtrace
        !            64: 
        !            65: Stack Frames
        !            66: ============
        !            67: 
        !            68: The call stack is divided up into contiguous pieces called "frames";
        !            69: each frame is the data associated with one call to one function.  The frame
        !            70: contains the arguments given to the function, the function's local
        !            71: variables, and the address at which the function is executing.
        !            72: 
        !            73: When your program is started, the stack has only one frame, that of the
        !            74: function `main'.  This is called the "initial" frame or the
        !            75: "outermost" frame.  Each time a function is called, a new frame is
        !            76: made.  Each time a function returns, the frame for that function invocation
        !            77: is eliminated.  If a function is recursive, there can be many frames for
        !            78: the same function.  The frame for the function in which execution is
        !            79: actually occurring is called the "innermost" frame.  This is the most
        !            80: recently created of all the stack frames that still exist.
        !            81: 
        !            82: Inside your program, stack frames are identified by their addresses.  A
        !            83: stack frame consists of many bytes, each of which has its own address; each
        !            84: kind of computer has a convention for choosing one of those bytes whose
        !            85: address serves as the address of the frame.  Usually this address is kept
        !            86: in a register called the "frame pointer register" while execution is
        !            87: going on in that frame.
        !            88: 
        !            89: GDB assigns numbers to all existing stack frames, starting with zero for
        !            90: the innermost frame, one for the frame that called it, and so on upward.
        !            91: These numbers do not really exist in your program; they are to give you a
        !            92: way of talking about stack frames in GDB commands.
        !            93: 
        !            94: Many GDB commands refer implicitly to one stack frame.  GDB records a stack
        !            95: frame that is called the "selected" stack frame; you can select any
        !            96: frame using one set of GDB commands, and then other commands will operate
        !            97: on that frame.  When your program stops, GDB automatically selects the
        !            98: innermost frame.
        !            99: 
        !           100: 
        !           101: File: gdb  Node: Backtrace, Prev: Frames, Up: Stack, Next: Selection
        !           102: 
        !           103: Backtraces
        !           104: ==========
        !           105: 
        !           106: A backtrace is a summary of how the program got where it is.  It shows one
        !           107: line per frame, for many frames, starting with the currently executing
        !           108: frame (frame zero), followed by its caller (frame one), and on up the
        !           109: stack.
        !           110: 
        !           111: `backtrace'     
        !           112: `bt'     
        !           113:      Print a backtrace of the entire stack: one line per frame for all
        !           114:      frames in the stack.
        !           115:      
        !           116:      You can stop the backtrace at any time by typing the system interrupt
        !           117:      character, normally `Control-C'.
        !           118:      
        !           119: `backtrace N'     
        !           120: `bt N'     
        !           121:      Similar, but stop after N frames.
        !           122: 
        !           123: Each line in a backtrace shows the frame number, the program counter, the
        !           124: function and its arguments, and the source file name and line number (if
        !           125: known).  The program counter is omitted if is the beginning of the code for
        !           126: the source line.  This is the same as the first of the two lines printed
        !           127: when you select a frame.
        !           128: 
        !           129: 
        !           130: File: gdb  Node: Selection, Prev: Backtrace, Up: Stack, Next: Frame Info
        !           131: 
        !           132: Selecting a Frame
        !           133: =================
        !           134: 
        !           135: Most commands for examining the stack and other data in the program work on
        !           136: whichever stack frame is selected at the moment.  Here are the commands for
        !           137: selecting a stack frame; all of them finish by printing a brief description
        !           138: of the stack frame just selected.
        !           139: 
        !           140: `frame N'     
        !           141:      Select frame number N.  Recall that frame zero is the innermost
        !           142:      (currently executing) frame, frame one is the frame that called the
        !           143:      innermost one, and so on.  The highest-numbered frame is `main''s
        !           144:      frame.
        !           145:      
        !           146: `frame ADDR'     
        !           147:      Select the frame at address ADDR.  This is useful mainly if the
        !           148:      chaining of stack frames has been damaged by a bug, making it
        !           149:      impossible for GDB to assign numbers properly to all frames.  In
        !           150:      addition, this can be useful when the program has multiple stacks and
        !           151:      options between them.
        !           152:      
        !           153: `up N'     
        !           154:      Select the frame N frames up from the frame previously selected.
        !           155:      For positive numbers N, this advances toward the outermost
        !           156:      frame, to higher frame numbers, to frames that have existed longer.
        !           157:      N defaults to one.
        !           158:      
        !           159: `down N'     
        !           160:      Select the frame N frames down from the frame previously
        !           161:      selected.  For positive numbers N, this advances toward the
        !           162:      innermost frame, to lower frame numbers, to frames that were created
        !           163:      more recently.  N defaults to one.
        !           164: 
        !           165: All of these commands end by printing some information on the frame that
        !           166: has been selected: the frame number, the function name, the arguments, the
        !           167: source file and line number of execution in that frame, and the text of
        !           168: that source line.  For example:
        !           169: 
        !           170:      #3  main (argc=3, argv=??, env=??) at main.c, line 67
        !           171:      67        read_input_file (argv[i]);
        !           172: 
        !           173: After such a printout, the `list' command with no arguments will print
        !           174: ten lines centered on the point of execution in the frame.  *Note List::.
        !           175: 
        !           176: 
        !           177: File: gdb  Node: Frame Info, Prev: Selection, Up: Stack
        !           178: 
        !           179: Information on a Frame
        !           180: ======================
        !           181: 
        !           182: There are several other commands to print information about the selected
        !           183: stack frame.
        !           184: 
        !           185: `frame'     
        !           186:      This command prints a brief description of the selected stack frame.
        !           187:      It can be abbreviated `f'.  With an argument, this command is
        !           188:      used to select a stack frame; with no argument, it does not change
        !           189:      which frame is selected, but still prints the same information.
        !           190:      
        !           191: `info frame'     
        !           192:      This command prints a verbose description of the selected stack frame,
        !           193:      including the address of the frame, the addresses of the next frame in
        !           194:      (called by this frame) and the next frame out (caller of this frame),
        !           195:      the address of the frame's arguments, the program counter saved in it
        !           196:      (the address of execution in the caller frame), and which registers
        !           197:      were saved in the frame.  The verbose description is useful when
        !           198:      something has gone wrong that has made the stack format fail to fit
        !           199:      the usual conventions.
        !           200:      
        !           201: `info frame ADDR'     
        !           202:      Print a verbose description of the frame at address ADDR,
        !           203:      without selecting that frame.  The selected frame remains unchanged by
        !           204:      this command.
        !           205:      
        !           206: `info args'     
        !           207:      Print the arguments of the selected frame, each on a separate line.
        !           208:      
        !           209: `info locals'     
        !           210:      Print the local variables of the selected frame, each on a separate
        !           211:      line.  These are all variables declared static or automatic within all
        !           212:      program blocks that execution in this frame is currently inside of.
        !           213: 
        !           214: 
        !           215: File: gdb  Node: Source, Prev: Stack, Up: Top, Next: Data
        !           216: 
        !           217: Examining Source Files
        !           218: **********************
        !           219: 
        !           220: GDB knows which source files your program was compiled from, and
        !           221: can print parts of their text.  When your program stops, GDB
        !           222: spontaneously prints the line it stopped in.  Likewise, when you
        !           223: select a stack frame (*Note Selection::), GDB prints the line
        !           224: which execution in that frame has stopped in.  You can also
        !           225: print parts of source files by explicit command.
        !           226: 
        !           227: * Menu:
        !           228: 
        !           229: * List::        Using the `list' command to print source files.
        !           230: * Search::      Commands for searching source files.
        !           231: * Source Path:: Specifying the directories to search for source files.
        !           232: 
        !           233: 
        !           234: File: gdb  Node: List, Prev: Source, Up: Source, Next: Search
        !           235: 
        !           236: Printing Source Lines
        !           237: =====================
        !           238: 
        !           239: To print lines from a source file, use the `list' command
        !           240: (abbreviated `l').  There are several ways to specify what part
        !           241: of the file you want to print.
        !           242: 
        !           243: Here are the forms of `list' command most commonly used:
        !           244: 
        !           245: `list LINENUM'     
        !           246:      Print ten lines centered around line number LINENUM in the
        !           247:      current source file.
        !           248:      
        !           249: `list FUNCTION'     
        !           250:      Print ten lines centered around the beginning of function
        !           251:      FUNCTION.
        !           252:      
        !           253: `list'     
        !           254:      Print ten more lines.  If the last lines printed were printed with a
        !           255:      `list' command, this prints ten lines following the last lines
        !           256:      printed; however, if the last line printed was a solitary line printed
        !           257:      as part of displaying a stack frame (*Note Stack::), this prints ten
        !           258:      lines centered around that line.
        !           259:      
        !           260: `list -'     
        !           261:      Print ten lines just before the lines last printed.
        !           262: 
        !           263: Repeating a `list' command with RET discards the argument,
        !           264: so it is equivalent to typing just `list'.  This is more useful
        !           265: than listing the same lines again.  An exception is made for an
        !           266: argument of `-'; that argument is preserved in repetition so that
        !           267: each repetition moves up in the file.
        !           268: 
        !           269: In general, the `list' command expects you to supply zero, one or two
        !           270: "linespecs".  Linespecs specify source lines; there are several ways
        !           271: of writing them but the effect is always to specify some source line.
        !           272: Here is a complete description of the possible arguments for `list':
        !           273: 
        !           274: `list LINESPEC'     
        !           275:      Print ten lines centered around the line specified by LINESPEC.
        !           276:      
        !           277: `list FIRST,LAST'     
        !           278:      Print lines from FIRST to LAST.  Both arguments are
        !           279:      linespecs.
        !           280:      
        !           281: `list ,LAST'     
        !           282:      Print ten lines ending with LAST.
        !           283:      
        !           284: `list FIRST,'     
        !           285:      Print ten lines starting with FIRST.
        !           286:      
        !           287: `list +'     
        !           288:      Print ten lines just after the lines last printed.
        !           289:      
        !           290: `list -'     
        !           291:      Print ten lines just before the lines last printed.
        !           292:      
        !           293: `list'     
        !           294:      As described in the preceding table.
        !           295: 
        !           296: Here are the ways of specifying a single source line---all the
        !           297: kinds of linespec.
        !           298: 
        !           299: LINENUM     
        !           300:      Specifies line LINENUM of the current source file.
        !           301:      When a `list' command has two linespecs, this refers to
        !           302:      the same source file as the first linespec.
        !           303:      
        !           304: +OFFSET     
        !           305:      Specifies the line OFFSET lines after the last line printed.
        !           306:      When used as the second linespec in a `list' command that has
        !           307:      two, this specifies the line OFFSET lines down from the
        !           308:      first linespec.
        !           309:      
        !           310: -OFFSET     
        !           311:      Specifies the line OFFSET lines before the last line printed.
        !           312:      
        !           313: FILENAME:LINENUM     
        !           314:      Specifies line LINENUM in the source file FILENAME.
        !           315:      
        !           316: FUNCTION     
        !           317:      Specifies the line of the open-brace that begins the body of the
        !           318:      function FUNCTION.
        !           319:      
        !           320: FILENAME:FUNCTION     
        !           321:      Specifies the line of the open-brace that begins the body of the
        !           322:      function FUNCTION in the file FILENAME.  The file name is
        !           323:      needed with a function name only for disambiguation of identically
        !           324:      named functions in different source files.
        !           325:      
        !           326: *ADDRESS     
        !           327:      Specifies the line containing the program address ADDRESS.
        !           328:      ADDRESS may be any expression.
        !           329: 
        !           330: One other command is used to map source lines to program addresses.
        !           331: 
        !           332: `info line LINENUM'     
        !           333:      Print the starting and ending addresses of the compiled code for
        !           334:      source line LINENUM.
        !           335:      
        !           336:      The default examine address for the `x' command is changed to the
        !           337:      starting address of the line, so that `x/i' is sufficient to
        !           338:      begin examining the machine code (*Note Memory::).  Also, this address
        !           339:      is saved as the value of the convenience variable `$_'
        !           340:      (*Note Convenience Vars::).
        !           341: 
        !           342: 
        !           343: File: gdb  Node: Search, Prev: List, Up: Source, Next: Source Path
        !           344: 
        !           345: Searching Source Files
        !           346: ======================
        !           347: 
        !           348: There are two commands for searching through the current source file for a
        !           349: regular expression.
        !           350: 
        !           351: The command `forward-search REGEXP' checks each line, starting
        !           352: with the one following the last line listed, for a match for REGEXP.
        !           353: It lists the line that is found.  You can abbreviate the command name
        !           354: as `fo'.
        !           355: 
        !           356: The command `reverse-search REGEXP' checks each line, starting
        !           357: with the one before the last line listed and going backward, for a match
        !           358: for REGEXP.  It lists the line that is found.  You can abbreviate
        !           359: this command with as little as `rev'.
        !           360: 
        !           361: 
        !           362: File: gdb  Node: Source Path, Prev: Search, Up: Source
        !           363: 
        !           364: Specifying Source Directories
        !           365: =============================
        !           366: 
        !           367: Executable programs do not record the directories of the source files they
        !           368: were compiled from, just the names.  GDB remembers a list of directories to
        !           369: search for source files; this is called the "source path".  Each time
        !           370: GDB wants a source file, it tries all the directories in the list, in the
        !           371: order they are present in the list, until it finds a file with the desired
        !           372: name.
        !           373: 
        !           374: When you start GDB, its source path contains just the current working
        !           375: directory.  To add other directories, use the `directory' command.
        !           376: Note that the search path for executable files and the working directory
        !           377: are not used for finding source files.
        !           378: 
        !           379: `directory DIRNAME'     
        !           380:      Add directory DIRNAME to the end of the source path.
        !           381:      
        !           382: `directory'     
        !           383:      Reset the source path to just the current working directory of GDB.
        !           384:      This requires confirmation.
        !           385:      
        !           386:      `directory' with no argument can cause source files previously
        !           387:      found by GDB to be found in a different directory.  To make this work
        !           388:      correctly, this command also clears out the tables GDB maintains
        !           389:      about the source files it has already found.
        !           390:      
        !           391: `info directories'     
        !           392:      Print the source path: show which directories it contains.
        !           393: 
        !           394: Because the `directory' command adds to the end of the source path,
        !           395: it does not affect any file that GDB has already found.  If the source
        !           396: path contains directories that you do not want, and these directories
        !           397: contain misleading files with names matching your source files, the
        !           398: way to correct the situation is as follows:
        !           399: 
        !           400:   1. Choose the directory you want at the beginning of the source path.
        !           401:      Use the `cd' command to make that the current working directory.
        !           402:      
        !           403:   2. Use `directory' with no argument to reset the source path to just
        !           404:      that directory.
        !           405:      
        !           406:   3. Use `directory' with suitable arguments to add any other
        !           407:      directories you want in the source path.
        !           408: 
        !           409: 
        !           410: File: gdb  Node: Data, Prev: Source, Up: Top, Next: Symbols
        !           411: 
        !           412: Examining Data
        !           413: **************
        !           414: 
        !           415: The usual way of examining data in your program is with the `print'
        !           416: command (abbreviated `p').  It evaluates and prints the value of any
        !           417: valid expression of the language the program is written in (for now, C).
        !           418: You type
        !           419: 
        !           420:      print EXP
        !           421: 
        !           422: where EXP is any valid expression, and the value of EXP
        !           423: is printed in a format appropriate to its data type.
        !           424: 
        !           425: A more low-level way of examining data is with the `x' command.
        !           426: It examines data in memory at a specified address and prints it in a
        !           427: specified format.
        !           428: 
        !           429: * Menu:
        !           430: 
        !           431: * Expressions::      Expressions that can be computed and printed.
        !           432: * Variables::        Using your program's variables in expressions.
        !           433: * Assignment::       Setting your program's variables.
        !           434: * Arrays::           Examining part of memory as an array.
        !           435: * Formats::          Specifying formats for printing values.
        !           436: * Memory::           Examining memory explicitly.
        !           437: * Auto Display::     Printing certain expressions whenever program stops.
        !           438: * Value History::    Referring to values previously printed.
        !           439: * Convenience Vars:: Giving names to values for future reference.
        !           440: * Registers::        Referring to and storing in machine registers.
        !           441: 
        !           442: 
        !           443: File: gdb  Node: Expressions, Prev: Data, Up: Data, Next: Variables
        !           444: 
        !           445: Expressions
        !           446: ===========
        !           447: 
        !           448: Many different GDB commands accept an expression and compute its value.
        !           449: Any kind of constant, variable or operator defined by the programming
        !           450: language you are using is legal in an expression in GDB.  This includes
        !           451: conditional expressions, function calls, casts and string constants.
        !           452: 
        !           453: Casts are supported in all languages, not just in C, because it is so
        !           454: useful to cast a number into a pointer so as to examine a structure
        !           455: at that address in memory.
        !           456: 
        !           457: GDB supports three kinds of operator in addition to those of programming
        !           458: languages:
        !           459: 
        !           460: `@'     
        !           461:      `@' is a binary operator for treating parts of memory as arrays.
        !           462:      *Note Arrays::, for more information.
        !           463:      
        !           464: `::'     
        !           465:      `::' allows you to specify a variable in terms of the file or
        !           466:      function it is defined in.  *Note Variables::.
        !           467:      
        !           468: `{TYPE} ADDR'     
        !           469:      Refers to an object of type TYPE stored at address ADDR in memory.
        !           470:      ADDR may be any expression whose value is an integer or pointer (but
        !           471:      parentheses are required around nonunary operators, just as in a
        !           472:      cast).  This construct is allowed regardless of what kind of data is
        !           473:      officially supposed to reside at ADDR.
        !           474: 
        !           475: 
        !           476: File: gdb  Node: Variables, Prev: Expressions, Up: Data, Next: Arrays
        !           477: 
        !           478: Program Variables
        !           479: =================
        !           480: 
        !           481: The most common kind of expression to use is the name of a variable
        !           482: in your program.
        !           483: 
        !           484: Variables in expressions are understood in the selected stack frame
        !           485: (*Note Selection::); they must either be global (or static) or be visible
        !           486: according to the scope rules of the programming language from the point of
        !           487: execution in that frame.  This means that in the function
        !           488: 
        !           489:      foo (a)
        !           490:           int a;
        !           491:      {
        !           492:        bar (a);
        !           493:        {
        !           494:          int b = test ();
        !           495:          bar (b);
        !           496:        }
        !           497:      }
        !           498: 
        !           499: the variable `a' is usable whenever the program is executing
        !           500: within the function `foo', but the variable `b' is visible
        !           501: only while the program is executing inside the block in which `b'
        !           502: is declared.
        !           503: 
        !           504: 
        !           505: File: gdb  Node: Arrays, Prev: Variables, Up: Data, Next: Formats
        !           506: 
        !           507: Artificial Arrays
        !           508: =================
        !           509: 
        !           510: It is often useful to print out several successive objects of the
        !           511: same type in memory; a section of an array, or an array of
        !           512: dynamically determined size for which only a pointer exists in the
        !           513: program.
        !           514: 
        !           515: This can be done by constructing an "artificial array" with the
        !           516: binary operator `@'.  The left operand of `@' should be
        !           517: the first element of the desired array, as an individual object.
        !           518: The right operand should be the length of the array.  The result is
        !           519: an array value whose elements are all of the type of the left argument.
        !           520: The first element is actually the left argument; the second element
        !           521: comes from bytes of memory immediately following those that hold the
        !           522: first element, and so on.  Here is an example.  If a program says
        !           523: 
        !           524:      int *array = (int *) malloc (len * sizeof (int));
        !           525: 
        !           526: you can print the contents of `array' with
        !           527: 
        !           528:      p *array@len
        !           529: 
        !           530: The left operand of `@' must reside in memory.  Array values made
        !           531: with `@' in this way behave just like other arrays in terms of
        !           532: subscripting, and are coerced to pointers when used in expressions.
        !           533: (It would probably appear in an expression via the value history,
        !           534: after you had printed it out.)
        !           535: 
        !           536: 
        !           537: File: gdb  Node: Formats, Prev: Arrays, Up: Data, Next: Memory
        !           538: 
        !           539: Formats
        !           540: =======
        !           541: 
        !           542: GDB normally prints all values according to their data types.  Sometimes
        !           543: this is not what you want.  For example, you might want to print a number
        !           544: in hex, or a pointer in decimal.  Or you might want to view data in memory
        !           545: at a certain address as a character string or an instruction.  These things
        !           546: can be done with "output formats".
        !           547: 
        !           548: The simplest use of output formats is to say how to print a value
        !           549: already computed.  This is done by starting the arguments of the
        !           550: `print' command with a slash and a format letter.  The format
        !           551: letters supported are:
        !           552: 
        !           553: `x'     
        !           554:      Regard the bits of the value as an integer, and print the integer in
        !           555:      hexadecimal.
        !           556:      
        !           557: `d'     
        !           558:      Print as integer in signed decimal.
        !           559:      
        !           560: `u'     
        !           561:      Print as integer in unsigned decimal.
        !           562:      
        !           563: `o'     
        !           564:      Print as integer in octal.
        !           565:      
        !           566: `a'     
        !           567:      Print as an address, both absolute in hex and then relative
        !           568:      to a symbol defined as an address below it.
        !           569:      
        !           570: `c'     
        !           571:      Regard as an integer and print it as a character constant.
        !           572:      
        !           573: `f'     
        !           574:      Regard the bits of the value as a floating point number and print
        !           575:      using typical floating point syntax.
        !           576: 
        !           577: For example, to print the program counter in hex (*Note Registers::), type
        !           578: 
        !           579:      p/x $pc
        !           580: 
        !           581: Note that no space is required before the slash; this is because command
        !           582: names in GDB cannot contain a slash.
        !           583: 
        !           584: To reprint the last value in the value history with a different format,
        !           585: you can use the `print' command with just a format and no
        !           586: expression.  For example, `p/x' reprints the last value in hex.
        !           587: 
        !           588: 
        !           589: File: gdb  Node: Memory, Prev: Formats, Up: Data, Next: Auto Display
        !           590: 
        !           591: Examining Memory
        !           592: ----------------
        !           593: 
        !           594: The command `x' (for `examine') can be used to examine memory under
        !           595: explicit control of formats, without reference to the program's data types.
        !           596: 
        !           597: `x' is followed by a slash and an output format specification,
        !           598: followed by an expression for an address.  The expression need not have
        !           599: a pointer value (though it may); it is used as an integer, as the
        !           600: address of a byte of memory.
        !           601: 
        !           602: The output format in this case specifies both how big a unit of memory
        !           603: to examine and how to print the contents of that unit.  It is done
        !           604: with one or two of the following letters:
        !           605: 
        !           606: These letters specify just the size of unit to examine:
        !           607: 
        !           608: `b'     
        !           609:      Examine individual bytes.
        !           610:      
        !           611: `h'     
        !           612:      Examine halfwords (two bytes each).
        !           613:      
        !           614: `w'     
        !           615:      Examine words (four bytes each).
        !           616:      
        !           617:      Many assemblers and cpu designers still use `word' for a 16-bit quantity,
        !           618:      as a holdover from specific predecessor machines of the 1970's that really
        !           619:      did use two-byte words.  But more generally the term `word' has always
        !           620:      referred to the size of quantity that a machine normally operates on and
        !           621:      stores in its registers.  This is 32 bits for all the machines that GNU
        !           622:      runs on.
        !           623:      
        !           624: `g'     
        !           625:      Examine giant words (8 bytes).
        !           626: 
        !           627: These letters specify just the way to print the contents:
        !           628: 
        !           629: `x'     
        !           630:      Print as integers in unsigned hexadecimal.
        !           631:      
        !           632: `d'     
        !           633:      Print as integers in signed decimal.
        !           634:      
        !           635: `u'     
        !           636:      Print as integers in unsigned decimal.
        !           637:      
        !           638: `o'     
        !           639:      Print as integers in unsigned octal.
        !           640:      
        !           641: `a'     
        !           642:      Print as an address, both absolute in hex and then relative
        !           643:      to a symbol defined as an address below it.
        !           644:      
        !           645: `c'     
        !           646:      Print as character constants.
        !           647:      
        !           648: `f'     
        !           649:      Print as floating point.  This works only with sizes `w' and
        !           650:      `g'.
        !           651:      
        !           652: `s'     
        !           653:      Print a null-terminated string of characters.  The specified unit size
        !           654:      is ignored; instead, the unit is however many bytes it takes to reach
        !           655:      a null character (including the null character).
        !           656:      
        !           657: `i'     
        !           658:      Print a machine instruction in assembler syntax (or nearly).  The
        !           659:      specified unit size is ignored; the number of bytes in an instruction
        !           660:      varies depending on the type of machine, the opcode and the addressing
        !           661:      modes used.
        !           662: 
        !           663: If either the manner of printing or the size of unit fails to be specified,
        !           664: the default is to use the same one that was used last.  If you don't want
        !           665: to use any letters after the slash, you can omit the slash as well.
        !           666: 
        !           667: You can also omit the address to examine.  Then the address used is
        !           668: just after the last unit examined.  This is why string and instruction
        !           669: formats actually compute a unit-size based on the data: so that the
        !           670: next string or instruction examined will start in the right place.
        !           671: The `print' command sometimes sets the default address for
        !           672: the `x' command; when the value printed resides in memory, the
        !           673: default is set to examine the same location.  `info line' also
        !           674: sets the default for `x', to the address of the start of the
        !           675: machine code for the specified line and `info breakpoints' sets
        !           676: it to the address of the last breakpoint listed.
        !           677: 
        !           678: When you use RET to repeat an `x' command, it does not repeat
        !           679: exactly the same: the address specified previously (if any) is ignored, so
        !           680: that the repeated command examines the successive locations in memory
        !           681: rather than the same ones.
        !           682: 
        !           683: You can examine several consecutive units of memory with one command by
        !           684: writing a repeat-count after the slash (before the format letters, if any).
        !           685: The repeat count must be a decimal integer.  It has the same effect as
        !           686: repeating the `x' command that many times except that the output may
        !           687: be more compact with several units per line.
        !           688: 
        !           689:      x/10i $pc
        !           690: 
        !           691: Prints ten instructions starting with the one to be executed next in the
        !           692: selected frame.  After doing this, you could print another ten following
        !           693: instructions with
        !           694: 
        !           695:      x/10
        !           696: 
        !           697: in which the format and address are allowed to default.
        !           698: 
        !           699: The addresses and contents printed by the `x' command are not put in
        !           700: the value history because there is often too much of them and they would
        !           701: get in the way.  Instead, GDB makes these values available for subsequent
        !           702: use in expressions as values of the convenience variables `$_' and
        !           703: `$__'.
        !           704: 
        !           705: After an `x' command, the last address examined is available for use
        !           706: in expressions in the convenience variable `$_'.  The contents of that
        !           707: address, as examined, are available in the convenience variable `$__'.
        !           708: 
        !           709: If the `x' command has a repeat count, the address and contents saved
        !           710: are from the last memory unit printed; this is not the same as the last
        !           711: address printed if several units were printed on the last line of output.
        !           712: 
        !           713: 
        !           714: File: gdb  Node: Auto Display, Prev: Memory, Up: Data, Next: Value History
        !           715: 
        !           716: Automatic Display
        !           717: =================
        !           718: 
        !           719: If you find that you want to print the value of an expression frequently
        !           720: (to see how it changes), you might want to add it to the "automatic
        !           721: display list" so that GDB will print its value each time the program stops.
        !           722: Each expression added to the list is given a number to identify it;
        !           723: to remove an expression from the list, you specify that number.
        !           724: The automatic display looks like this:
        !           725: 
        !           726:      2: foo = 38
        !           727:      3: bar[5] = (struct hack *) 0x3804
        !           728: 
        !           729: showing item numbers, expressions and their current values.
        !           730: 
        !           731: `display EXP'     
        !           732:      Add the expression EXP to the list of expressions to display
        !           733:      each time the program stops.
        !           734:      
        !           735: `display/FMT EXP'     
        !           736:      For FMT specifying only a display format and not a size or
        !           737:      count, add the expression EXP to the auto-display list but
        !           738:      arranges to display it each time in the specified format FMT.
        !           739:      
        !           740: `display/FMT ADDR'     
        !           741:      For FMT `i' or `s', or including a unit-size or a
        !           742:      number of units, add the expression ADDR as a memory address to
        !           743:      be examined each time the program stops.  Examining means in effect
        !           744:      doing `x/FMT ADDR'.  *Note Memory::.
        !           745:      
        !           746: `undisplay N'     
        !           747:      Remove item number N from the list of expressions to display.
        !           748:      
        !           749: `display'     
        !           750:      Display the current values of the expressions on the list, just as is
        !           751:      done when the program stops.
        !           752:      
        !           753: `info display'     
        !           754:      Print the list of expressions to display automatically, each one
        !           755:      with its item number, but without showing the values.
        !           756: 
        !           757: 
        !           758: File: gdb  Node: Value History, Prev: Auto Display, Up: Data, Next: Convenience Vars
        !           759: 
        !           760: Value History
        !           761: =============
        !           762: 
        !           763: Every value printed by the `print' command is saved for the entire
        !           764: session in GDB's "value history" so that you can refer to it in
        !           765: other expressions.
        !           766: 
        !           767: The values printed are given "history numbers" for you to refer to them
        !           768: by.  These are successive integers starting with 1.  `print' shows you
        !           769: the history number assigned to a value by printing `$N = '
        !           770: before the value; here N is the history number.
        !           771: 
        !           772: To refer to any previous value, use `$' followed by the value's
        !           773: history number.  The output printed by `print' is designed to remind
        !           774: you of this.  Just `$' refers to the most recent value in the history,
        !           775: and `$$' refers to the value before that.
        !           776: 
        !           777: For example, suppose you have just printed a pointer to a structure and
        !           778: want to see the contents of the structure.  It suffices to type
        !           779: 
        !           780:      p *$
        !           781: 
        !           782: If you have a chain of structures where the component `next' points
        !           783: to the next one, you can print the contents of the next one with
        !           784: 
        !           785:      p *$.next
        !           786: 
        !           787: It might be useful to repeat this command many times by typing RET.
        !           788: 
        !           789: Note that the history records values, not expressions.  If the value of
        !           790: `x' is 4 and you type
        !           791: 
        !           792:      print x
        !           793:      set x=5
        !           794: 
        !           795: then the value recorded in the value history by the `print' command
        !           796: remains 4 even though `x''s value has changed.
        !           797: 
        !           798: `info history'     
        !           799:      Print the last ten values in the value history, with their item
        !           800:      numbers.  This is like `p $$9' repeated ten times, except that
        !           801:      `info history' does not change the history.
        !           802:      
        !           803: `info history N'     
        !           804:      Print ten history values centered on history item number N.
        !           805: 
        !           806: 
        !           807: File: gdb  Node: Convenience Vars, Prev: Value History, Up: Data, Next: Registers
        !           808: 
        !           809: Convenience Variables
        !           810: =====================
        !           811: 
        !           812: GDB provides "convenience variables" that you can use within GDB to
        !           813: hold on to a value and refer to it later.  These variables exist entirely
        !           814: within GDB; they are not part of your program, and setting a convenience
        !           815: variable has no effect on further execution of your program.  That's why
        !           816: you can use them freely.
        !           817: 
        !           818: Convenience variables have names starting with `$'.  Any name starting
        !           819: with `$' can be used for a convenience variable, unless it is one of
        !           820: the predefined set of register names (*Note Registers::).
        !           821: 
        !           822: You can save a value in a convenience variable with an assignment
        !           823: expression, just as you would set a variable in your program.  Example:
        !           824: 
        !           825:      set $foo = *object_ptr
        !           826: 
        !           827: would save in `$foo' the value contained in the object pointed to by
        !           828: `object_ptr'.
        !           829: 
        !           830: Using a convenience variable for the first time creates it; but its value
        !           831: is `void' until you assign a new value.  You can alter the value with
        !           832: another assignment at any time.
        !           833: 
        !           834: Convenience variables have no fixed types.  You can assign a convenience
        !           835: variable any type of value, even if it already has a value of a different
        !           836: type.  The convenience variable as an expression has whatever type its
        !           837: current value has.
        !           838: 
        !           839: `info convenience'     
        !           840:      Print a list of convenience variables used so far, and their values.
        !           841:      Abbreviated `i con'.
        !           842: 
        !           843: One of the ways to use a convenience variable is as a counter to be
        !           844: incremented or a pointer to be advanced.  For example:
        !           845: 
        !           846:      set $i = 0
        !           847:      print bar[$i++]->contents
        !           848:      ...repeat that command by typing RET.
        !           849: 
        !           850: Some convenience variables are created automatically by GDB and given
        !           851: values likely to be useful.
        !           852: 
        !           853: `$_'     
        !           854:      The variable `$_' is automatically set by the `x' command to
        !           855:      the last address examined (*Note Memory::).  Other commands which
        !           856:      provide a default address for `x' to examine also set `$_'
        !           857:      to that address; these commands include `info line' and `info
        !           858:      breakpoint'.
        !           859:      
        !           860: `$__'     
        !           861:      The variable `$__' is automatically set by the `x' command
        !           862:      to the value found in the last address examined.
        !           863: 
        !           864: 
        !           865: File: gdb  Node: Registers, Prev: Convenience Vars, Up: Data
        !           866: 
        !           867: Registers
        !           868: =========
        !           869: 
        !           870: Machine register contents can be referred to in expressions as variables
        !           871: with names starting with `$'.  The names of registers are different
        !           872: for each machine; use `info registers' to see the names used on your
        !           873: machine.  The names `$pc' and `$sp' are used on all machines for
        !           874: the program counter register and the stack pointer.  Often `$fp' is
        !           875: used for a register that contains a pointer to the current stack frame.
        !           876: 
        !           877: GDB always considers the contents of an ordinary register as an integer
        !           878: when the register is examined in this way.  Programs can store floating
        !           879: point values in registers also, but there is currently no GDB command
        !           880: to examine a specified register in floating point.  (However, if the
        !           881: variable in your program which is stored in the register is a floating
        !           882: point variable, you can see the floating point value by examining
        !           883: the variable.)
        !           884: 
        !           885: Some machines have special floating point registers.  GDB considers these
        !           886: registers' values as floating point when you examine them explicitly.
        !           887: 
        !           888: Some registers have distinct "raw" and "virtual" data formats.  This
        !           889: means that the data format in which the register contents are saved by the
        !           890: operating system is not the same one that your program normally sees.  For
        !           891: example, the registers of the 68881 floating point coprocessor are always
        !           892: saved in "extended" format, but all C programs expect to work with
        !           893: "double" format.  In such cases, GDB normally works with the virtual
        !           894: format only (the format that makes sense for your program), but the
        !           895: `info registers' command prints the data in both formats.
        !           896: 
        !           897: Register values are relative to the selected stack frame
        !           898: (*Note Selection::).  This means that you get the value that the register
        !           899: would contain if all stack frames farther in were exited and their saved
        !           900: registers restored.  In order to see the real contents of all registers,
        !           901: you must select the innermost frame (with `frame 0').
        !           902: 
        !           903: Some registers are never saved (typically those numbered zero or one)
        !           904: because they are used for returning function values; for these registers,
        !           905: relativization makes no difference.
        !           906: 
        !           907: `info registers'     
        !           908:      Print the names and relativized values of all registers.
        !           909:      
        !           910: `info registers REGNAME'     
        !           911:      Print the relativized value of register REGNAME.  REGNAME
        !           912:      may be any register name valid on the machine you are using, with
        !           913:      or without the initial `$'.
        !           914: 
        !           915: 
        !           916: Examples
        !           917: --------
        !           918: 
        !           919: You could print the program counter in hex with
        !           920: 
        !           921:      p/x $pc
        !           922: 
        !           923: or print the instruction to be executed next with
        !           924: 
        !           925:      x/i $pc
        !           926: 
        !           927: or add four to the stack pointer with
        !           928: 
        !           929:      set $sp += 4
        !           930: 
        !           931: The last is a way of removing one word from the stack, on machines where
        !           932: stacks grow downward in memory (most machines, nowadays).  This assumes
        !           933: that the innermost stack frame is selected.  Setting `$sp' is
        !           934: not allowed when other stack frames are selected.
        !           935: 
        !           936: 
        !           937: File: gdb  Node: Symbols, Prev: Data, Up: Top, Next: Altering
        !           938: 
        !           939: Examining the Symbol Table
        !           940: **************************
        !           941: 
        !           942: The commands described in this section allow you to make inquiries for
        !           943: information about the symbols (names of variables, functions and types)
        !           944: defined in your program.  This information is found by GDB in the symbol
        !           945: table loaded by the `symbol-file' command; it is inherent in the text
        !           946: of your program and does not change as the program executes.
        !           947: 
        !           948: `whatis EXP'     
        !           949:      Print the data type of expression EXP.  EXP is not
        !           950:      actually evaluated, and any side-effecting operations (such as
        !           951:      assignments or function calls) inside it do not take place.
        !           952:      
        !           953: `whatis'     
        !           954:      Print the data type of `$', the last value in the value history.
        !           955:      
        !           956: `info address SYMBOL'     
        !           957:      Describe where the data for SYMBOL is stored.  For register
        !           958:      variables, this says which register.  For other automatic variables,
        !           959:      this prints the stack-frame offset at which the variable is always
        !           960:      stored.  Note the contrast with `print &SYMBOL', which does
        !           961:      not work at all for register variables and for automatic variables
        !           962:      prints the exact address of the current instantiation of the variable.
        !           963:      
        !           964: `ptype TYPENAME'     
        !           965:      Print a description of data type TYPENAME.  TYPENAME may be the name
        !           966:      of a type, or for C code it may have the form `struct STRUCT-TAG',
        !           967:      `union UNION-TAG' or `enum ENUM-TAG'.
        !           968:      
        !           969: `info sources'     
        !           970:      Print the names of all source files in the program for which there
        !           971:      is debugging information.
        !           972:      
        !           973: `info functions'     
        !           974:      Print the names and data types of all defined functions.
        !           975:      
        !           976: `info functions REGEXP'     
        !           977:      Print the names and data types of all defined functions
        !           978:      whose names contain a match for regular expression REGEXP.
        !           979:      Thus, `info fun step' finds all functions whose names
        !           980:      include `step'; `info fun ^step' finds those whose names
        !           981:      start with `step'.
        !           982:      
        !           983: `info variables'     
        !           984:      Print the names and data types of all variables that are declared
        !           985:      outside of functions.
        !           986:      
        !           987: `info variables REGEXP'     
        !           988:      Print the names and data types of all variables, declared outside of
        !           989:      functions, whose names contain a match for regular expression
        !           990:      REGEXP.
        !           991:      
        !           992: `info types'     
        !           993:      Print all data types that are defined in the program.
        !           994:      
        !           995: `info types REGEXP'     
        !           996:      Print all data types that are defined in the program whose names
        !           997:      contain a match for regular expression REGEXP.
        !           998:      
        !           999: `printsyms FILENAME'     
        !          1000:      Write a complete dump of the debugger's symbol data into the
        !          1001:      file FILENAME.
        !          1002: 
        !          1003: 
        !          1004: File: gdb  Node: Altering, Prev: Symbols, Up: Top, Next: Sequences
        !          1005: 
        !          1006: Altering Execution
        !          1007: ******************
        !          1008: 
        !          1009: There are several ways to alter the execution of your program with GDB
        !          1010: commands.
        !          1011: 
        !          1012: * Menu:
        !          1013: 
        !          1014: * Assignment::    Altering variable values or memory contents.
        !          1015: * Jumping::       Altering control flow.
        !          1016: * Signaling::     Making signals happen in the program.
        !          1017: * Returning::     Making a function return prematurely.
        !          1018: 
        !          1019: 
        !          1020: File: gdb  Node: Assignment, Prev: Altering, Up: Altering, Next: Jumping
        !          1021: 
        !          1022: Assignment to Variables
        !          1023: =======================
        !          1024: 
        !          1025: To alter the value of a variable, evaluate an assignment expression.
        !          1026: For example,
        !          1027: 
        !          1028:      print x=4
        !          1029: 
        !          1030: would store the value 4 into the variable `x', and then print
        !          1031: the value of the assignment expression (which is 4).
        !          1032: 
        !          1033: If you are not interested in seeing the value of the assignment, use the
        !          1034: `set' command instead of the `print' command.  `set' is
        !          1035: really the same as `print' except that the expression's value is not
        !          1036: printed and is not put in the value history (*Note Value History::).  The
        !          1037: expression is evaluated only for side effects.
        !          1038: 
        !          1039: GDB allows more implicit conversions in assignments than C does; you can
        !          1040: freely store an integer value into a pointer variable or vice versa, and
        !          1041: any structure can be converted to any other structure that is the same
        !          1042: length or shorter.
        !          1043: 
        !          1044: In C, all the other assignment operators such as `+=' and `++'
        !          1045: are supported as well.
        !          1046: 
        !          1047: To store into arbitrary places in memory, use the `{...}'
        !          1048: construct to generate a value of specified type at a specified address
        !          1049: (*Note Expressions::).  For example,
        !          1050: 
        !          1051:      set {int}0x83040 = 4
        !          1052: 
        !          1053: 
        !          1054: File: gdb  Node: Jumping, Prev: Assignment, Up: Altering, Next: Signaling
        !          1055: 
        !          1056: Continuing at a Different Address
        !          1057: =================================
        !          1058: 
        !          1059: `jump LINENUM'     
        !          1060:      Resume execution at line number LINENUM.  Execution may stop
        !          1061:      immediately if there is a breakpoint there.
        !          1062:      
        !          1063:      The `jump' command does not change the current stack frame, or
        !          1064:      the stack pointer, or the contents of any memory location or any
        !          1065:      register other than the program counter.  If line LINENUM is in
        !          1066:      a different function from the one currently executing, the results may
        !          1067:      be wild if the two functions expect different patterns of arguments or
        !          1068:      of local variables.  For his reason, the `jump' command requests
        !          1069:      confirmation if the specified line is not in the function currently
        !          1070:      executing.  However, even wild results are predictable based on
        !          1071:      changing the program counter.
        !          1072:      
        !          1073: `jump *ADDRESS'     
        !          1074:      Resume execution at the instruction at address ADDRESS.
        !          1075: 
        !          1076: A similar effect can be obtained by storing a new value into the register
        !          1077: `$pc', but not exactly the same.
        !          1078: 
        !          1079:      set $pc = 0x485
        !          1080: 
        !          1081: specifies the address at which execution will resume, but does not resume
        !          1082: execution.  That does not happen until you use the `cont' command or a
        !          1083: stepping command (*Note Stepping::).
        !          1084: 
        !          1085: 
        !          1086: File: gdb  Node: Signaling, Prev: Jumping, Up: Altering, Next: Returning
        !          1087: 
        !          1088: Giving the Program a Signal
        !          1089: ===========================
        !          1090: 
        !          1091: `signal SIGNALNUM'     
        !          1092:      Resume execution where the program stopped, but give it immediately
        !          1093:      the signal number SIGNALNUM.
        !          1094:      
        !          1095:      Alternatively, if SIGNALNUM is zero, continue execution and give
        !          1096:      no signal.  This may be useful when the program has received a signal
        !          1097:      and the `cont' command would allow the program to see that
        !          1098:      signal.
        !          1099: 
        !          1100: 
        !          1101: File: gdb  Node: Returning, Prev: Signaling, Up: Altering
        !          1102: 
        !          1103: Returning from a Function
        !          1104: =========================
        !          1105: 
        !          1106: You can make any function call return immediately, using the `return'
        !          1107: command.
        !          1108: 
        !          1109: First select the stack frame that you wish to return from
        !          1110: (*Note Selection::).  Then type the `return' command.  If you wish to
        !          1111: specify the value to be returned, give that as an argument.
        !          1112: 
        !          1113: This pops the selected stack frame (and any other frames inside of it),
        !          1114: leaving its caller as the innermost remaining frame.  That frame becomes
        !          1115: selected.  The specified value is stored in the registers used for
        !          1116: returning values of functions.
        !          1117: 
        !          1118: The `return' command does not resume execution; it leaves the program
        !          1119: stopped in the state that would exist if the function had just returned.
        !          1120: Contrast this with the `finish' command (*Note Stepping::), which
        !          1121: resumes execution until the selected stack frame returns naturally.
        !          1122: 
        !          1123: 
        !          1124: File: gdb  Node: Sequences, Prev: Altering, Up: Top, Next: Emacs
        !          1125: 
        !          1126: Canned Sequences of Commands
        !          1127: ****************************
        !          1128: 
        !          1129: GDB provides two ways to store sequences of commands for execution as a
        !          1130: unit: user-defined commands and command files.
        !          1131: 
        !          1132: * Menu:
        !          1133: 
        !          1134: * Define::         User-defined commands.
        !          1135: * Command Files::  Command files.
        !          1136: * Output::         Controlled output commands useful in
        !          1137:                    user-defined commands and command files.
        !          1138: 
        !          1139: 
        !          1140: File: gdb  Node: Define, Prev: Sequences, Up: Sequences, Next: Command Files
        !          1141: 
        !          1142: User-Defined Commands
        !          1143: =====================
        !          1144: 
        !          1145: A "user-defined command" is a sequence of GDB commands to which you
        !          1146: assign a new name as a command.  This is done with the `define'
        !          1147: command.
        !          1148: 
        !          1149: `define COMMANDNAME'     
        !          1150:      Define a command named COMMANDNAME.  If there is already a command
        !          1151:      by that name, you are asked to confirm that you want to redefine it.
        !          1152:      
        !          1153:      The definition of the command is made up of other GDB command lines,
        !          1154:      which are given following the `define' command.  The end of these
        !          1155:      commands is marked by a line containing `end'.
        !          1156:      
        !          1157: `document COMMANDNAME'     
        !          1158:      Give documentation to the user-defined command COMMANDNAME.  The
        !          1159:      command COMMANDNAME must already be defined.  This command reads
        !          1160:      lines of documentation just as `define' reads the lines of the
        !          1161:      command definition.  After the `document' command is finished,
        !          1162:      `help' on command COMMANDNAME will print the documentation
        !          1163:      you have specified.
        !          1164:      
        !          1165:      You may use the `document' command again to change the
        !          1166:      documentation of a command.  Redefining the command with `define'
        !          1167:      does not change the documentation.
        !          1168: 
        !          1169: User-defined commands do not take arguments.  When they are executed, the
        !          1170: commands of the definition are not printed.  An error in any command
        !          1171: stops execution of the user-defined command.
        !          1172: 
        !          1173: Commands that would ask for confirmation if used interactively proceed
        !          1174: without asking when used inside a user-defined command.  Many GDB commands
        !          1175: that normally print messages to say what they are doing omit the messages
        !          1176: when used in user-defined command.
        !          1177: 
        !          1178: 
        !          1179: File: gdb  Node: Command Files, Prev: Define, Up: Sequences, Next: Output
        !          1180: 
        !          1181: Command Files
        !          1182: =============
        !          1183: 
        !          1184: A command file for GDB is a file of lines that are GDB commands.  Comments
        !          1185: (lines starting with `#') may also be included.  An empty line in a
        !          1186: command file does nothing; it does not mean to repeat the last command, as
        !          1187: it would from the terminal.
        !          1188: 
        !          1189: When GDB starts, it automatically executes its "init files", command
        !          1190: files named `.gdbinit'.  GDB reads the init file (if any) in your home
        !          1191: directory and then the init file (if any) in the current working
        !          1192: directory.  (The init files are not executed if the `-nx' option
        !          1193: is given.)  You can also request the execution of a command file with the
        !          1194: `source' command:
        !          1195: 
        !          1196: `source FILENAME'     
        !          1197:      Execute the command file FILENAME.
        !          1198: 
        !          1199: The lines in a command file are executed sequentially.  They are not
        !          1200: printed as they are executed.  An error in any command terminates execution
        !          1201: of the command file.
        !          1202: 
        !          1203: Commands that would ask for confirmation if used interactively proceed
        !          1204: without asking when used in a command file.  Many GDB commands that
        !          1205: normally print messages to say what they are doing omit the messages
        !          1206: when used in a command file.
        !          1207: 
        !          1208: 
        !          1209: File: gdb  Node: Output, Prev: Command Files, Up: Sequences
        !          1210: 
        !          1211: Commands for Controlled Output
        !          1212: ==============================
        !          1213: 
        !          1214: During the execution of a command file or a user-defined command, the only
        !          1215: output that appears is what is explicitly printed by the commands of the
        !          1216: definition.  This section describes three commands useful for generating
        !          1217: exactly the output you want.
        !          1218: 
        !          1219: `echo TEXT'     
        !          1220:      Print TEXT.  Nonprinting characters can be included in
        !          1221:      TEXT using C escape sequences, such as `\n' to print a
        !          1222:      newline.  No newline will be printed unless you specify one.
        !          1223:      
        !          1224:      A backslash at the end of TEXT is ignored.  It is useful for
        !          1225:      outputting a string ending in spaces, since trailing spaces are
        !          1226:      trimmed from all arguments.  A backslash at the beginning preserves
        !          1227:      leading spaces in the same way, because `\ ' as an escape
        !          1228:      sequence stands for a space.  Thus, to print ` and foo = ', do
        !          1229:      
        !          1230:           echo \ and foo = \
        !          1231:      
        !          1232: `output EXPRESSION'     
        !          1233:      Print the value of EXPRESSION and nothing but that value: no
        !          1234:      newlines, no `$NN = '.  The value is not entered in the
        !          1235:      value history either.
        !          1236:      
        !          1237: `output/FMT EXPRESSION'     
        !          1238:      Print the value of EXPRESSION in format FMT.
        !          1239:      *Note Formats::, for more information.
        !          1240:      
        !          1241: `printf STRING, EXPRESSIONS...'     
        !          1242:      Print the values of the EXPRESSIONS under the control of
        !          1243:      STRING.  The EXPRESSIONS are separated by commas and may
        !          1244:      be either numbers or pointers.  Their values are printed as specified
        !          1245:      by STRING, exactly as if the program were to execute
        !          1246:      
        !          1247:           printf (STRING, EXPRESSIONS...);
        !          1248:      
        !          1249:      For example, you can print two values in hex like this:
        !          1250:      
        !          1251:           printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
        !          1252:      
        !          1253:      The only backslash-escape sequences that you can use in the string are
        !          1254:      the simple ones that consist of backslash followed by a letter.
        !          1255: 
        !          1256: 
        !          1257: File: gdb  Node: Emacs, Prev: Sequences, Up: Top, Next: Remote
        !          1258: 
        !          1259: Using GDB under GNU Emacs
        !          1260: *************************
        !          1261: 
        !          1262: A special interface allows you to use GNU Emacs to view (and
        !          1263: edit) the source files for the program you are debugging with
        !          1264: GDB.
        !          1265: 
        !          1266: To use this interface, use the command `M-x gdb' in Emacs.
        !          1267: Give the executable file you want to debug as an argument.  This
        !          1268: command starts a GDB process as a subprocess of Emacs, with input
        !          1269: and output through a newly created Emacs buffer.
        !          1270: 
        !          1271: Using this GDB process is just like using GDB normally except for two things:
        !          1272: 
        !          1273:    * All "terminal" input and output goes through the Emacs buffer.  This
        !          1274:      applies both to GDB commands and their output, and to the input and
        !          1275:      output done by the program you are debugging.
        !          1276:      
        !          1277:      This is useful because it means that you can copy the text of previous
        !          1278:      commands and input them again; you can even use parts of the output
        !          1279:      in this way.
        !          1280:      
        !          1281:      All the facilities of Emacs's Shell mode are available for this purpose.
        !          1282:      
        !          1283:    * GDB displays source code through Emacs.  Each time GDB displays a
        !          1284:      stack frame, Emacs automatically finds the source file for that frame
        !          1285:      and puts an arrow (`=>') at the left margin of the current line.
        !          1286:      
        !          1287:      Explicit GDB `list' or search commands still produce output as
        !          1288:      usual, but you probably will have no reason to use them.
        !          1289: 
        !          1290: In the GDB I/O buffer, you can use these special Emacs commands:
        !          1291: 
        !          1292: `M-s'     
        !          1293:      Execute to another source line, like the GDB `step' command.
        !          1294:      
        !          1295: `M-n'     
        !          1296:      Execute to next source line in this function, skipping all function
        !          1297:      calls, like the GDB `next' command.
        !          1298:      
        !          1299: `M-i'     
        !          1300:      Execute one instruction, like the GDB `stepi' command.
        !          1301:      
        !          1302: `M-u'     
        !          1303:      Move up one stack frame (and display that frame's source file in
        !          1304:      Emacs), like the GDB `up' command.
        !          1305:      
        !          1306: `M-d'     
        !          1307:      Move down one stack frame (and display that frame's source file in
        !          1308:      Emacs), like the GDB `down' command.  (This means that you cannot
        !          1309:      delete words in the usual fashion in the GDB buffer; I am guessing you
        !          1310:      won't often want to do that.)
        !          1311:      
        !          1312: `C-c C-f'     
        !          1313:      Execute until exit from the selected stack frame, like the GDB
        !          1314:      `finish' command.
        !          1315: 
        !          1316: In any source file, the Emacs command `C-x SPC' (`gdb-break')
        !          1317: tells GDB to set a breakpoint on the source line point is on.
        !          1318: 
        !          1319: The source files displayed in Emacs are in ordinary Emacs buffers
        !          1320: which are visiting the source files in the usual way.  You can edit
        !          1321: the files with these buffers if you wish; but keep in mind that GDB
        !          1322: communicates with Emacs in terms of line numbers.  If you add or
        !          1323: delete lines from the text, the line numbers that GDB knows will cease
        !          1324: to correspond properly to the code.
        !          1325: 
        !          1326: 
        !          1327: File: gdb  Node: Remote, Prev: Emacs, Up: Top, Next: Commands
        !          1328: 
        !          1329: Remote Kernel Debugging
        !          1330: ***********************
        !          1331: 
        !          1332: GDB has a special facility for debugging a remote machine via a serial
        !          1333: connection.  This can be used for kernel debugging.
        !          1334: 
        !          1335: The program to be debugged on the remote machine needs to contain a
        !          1336: debugging device driver which talks to GDB over the serial line using the
        !          1337: protocol described below.  The same version of GDB that is used ordinarily
        !          1338: can be used for this.
        !          1339: 
        !          1340: * Menu:
        !          1341: 
        !          1342: * Remote Commands::       Commands used to start and finish remote debugging.
        !          1343: 
        !          1344: For details of the communication protocol, see the comments in the GDB
        !          1345: source file `remote.c'.
        !          1346: 
        !          1347: 
        !          1348: File: gdb  Node: Remote Commands, Prev: Remote, Up: Remote
        !          1349: 
        !          1350: Commands for Remote Debugging
        !          1351: =============================
        !          1352: 
        !          1353: To start remote debugging, first run GDB and specify as an executable file
        !          1354: the program that is running in the remote machine.  This tells GDB how
        !          1355: to find the program's symbols and the contents of its pure text.  Then
        !          1356: establish communication using the `attach' command with a device
        !          1357: name rather than a pid as an argument.  For example:
        !          1358: 
        !          1359:      attach /dev/ttyd
        !          1360: 
        !          1361: if the serial line is connected to the device named `/dev/ttyd'.  This
        !          1362: will stop the remote machine if it is not already stopped.
        !          1363: 
        !          1364: Now you can use all the usual commands to examine and change data and to
        !          1365: step and continue the remote program.
        !          1366: 
        !          1367: To resume the remote program and stop debugging it, use the `detach'
        !          1368: command.
        !          1369: 
        !          1370: 

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