This is gdb.info, produced by makeinfo version 4.7 from ./gdb.texinfo. INFO-DIR-SECTION Software development START-INFO-DIR-ENTRY * Gdb: (gdb). The GNU debugger. END-INFO-DIR-ENTRY This file documents the GNU debugger GDB. This is the Ninth Edition, of `Debugging with GDB: the GNU Source-Level Debugger' for GDB Version 6.3. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Free Software" and "Free Software Needs Free Documentation", with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. (a) The Free Software Foundation's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 12.4.3.2 Built-in functions and procedures .......................................... Modula-2 also makes available several built-in procedures and functions. In describing these, the following metavariables are used: A represents an `ARRAY' variable. C represents a `CHAR' constant or variable. I represents a variable or constant of integral type. M represents an identifier that belongs to a set. Generally used in the same function with the metavariable S. The type of S should be `SET OF MTYPE' (where MTYPE is the type of M). N represents a variable or constant of integral or floating-point type. R represents a variable or constant of floating-point type. T represents a type. V represents a variable. X represents a variable or constant of one of many types. See the explanation of the function for details. All Modula-2 built-in procedures also return a result, described below. `ABS(N)' Returns the absolute value of N. `CAP(C)' If C is a lower case letter, it returns its upper case equivalent, otherwise it returns its argument. `CHR(I)' Returns the character whose ordinal value is I. `DEC(V)' Decrements the value in the variable V by one. Returns the new value. `DEC(V,I)' Decrements the value in the variable V by I. Returns the new value. `EXCL(M,S)' Removes the element M from the set S. Returns the new set. `FLOAT(I)' Returns the floating point equivalent of the integer I. `HIGH(A)' Returns the index of the last member of A. `INC(V)' Increments the value in the variable V by one. Returns the new value. `INC(V,I)' Increments the value in the variable V by I. Returns the new value. `INCL(M,S)' Adds the element M to the set S if it is not already there. Returns the new set. `MAX(T)' Returns the maximum value of the type T. `MIN(T)' Returns the minimum value of the type T. `ODD(I)' Returns boolean TRUE if I is an odd number. `ORD(X)' Returns the ordinal value of its argument. For example, the ordinal value of a character is its ASCII value (on machines supporting the ASCII character set). X must be of an ordered type, which include integral, character and enumerated types. `SIZE(X)' Returns the size of its argument. X can be a variable or a type. `TRUNC(R)' Returns the integral part of R. `VAL(T,I)' Returns the member of the type T whose ordinal value is I. _Warning:_ Sets and their operations are not yet supported, so GDB treats the use of procedures `INCL' and `EXCL' as an error.  File: gdb.info, Node: M2 Constants, Next: M2 Defaults, Prev: Built-In Func/Proc, Up: Modula-2 12.4.3.3 Constants .................. GDB allows you to express the constants of Modula-2 in the following ways: * Integer constants are simply a sequence of digits. When used in an expression, a constant is interpreted to be type-compatible with the rest of the expression. Hexadecimal integers are specified by a trailing `H', and octal integers by a trailing `B'. * Floating point constants appear as a sequence of digits, followed by a decimal point and another sequence of digits. An optional exponent can then be specified, in the form `E[+|-]NNN', where `[+|-]NNN' is the desired exponent. All of the digits of the floating point constant must be valid decimal (base 10) digits. * Character constants consist of a single character enclosed by a pair of like quotes, either single (`'') or double (`"'). They may also be expressed by their ordinal value (their ASCII value, usually) followed by a `C'. * String constants consist of a sequence of characters enclosed by a pair of like quotes, either single (`'') or double (`"'). Escape sequences in the style of C are also allowed. *Note C and C++ constants: C Constants, for a brief explanation of escape sequences. * Enumerated constants consist of an enumerated identifier. * Boolean constants consist of the identifiers `TRUE' and `FALSE'. * Pointer constants consist of integral values only. * Set constants are not yet supported.  File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Constants, Up: Modula-2 12.4.3.4 Modula-2 defaults .......................... If type and range checking are set automatically by GDB, they both default to `on' whenever the working language changes to Modula-2. This happens regardless of whether you or GDB selected the working language. If you allow GDB to set the language automatically, then entering code compiled from a file whose name ends with `.mod' sets the working language to Modula-2. *Note Having GDB set the language automatically: Automatically, for further details.  File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 12.4.3.5 Deviations from standard Modula-2 .......................................... A few changes have been made to make Modula-2 programs easier to debug. This is done primarily via loosening its type strictness: * Unlike in standard Modula-2, pointer constants can be formed by integers. This allows you to modify pointer variables during debugging. (In standard Modula-2, the actual address contained in a pointer variable is hidden from you; it can only be modified through direct assignment to another pointer variable or expression that returned a pointer.) * C escape sequences can be used in strings and characters to represent non-printable characters. GDB prints out strings with these escape sequences embedded. Single non-printable characters are printed using the `CHR(NNN)' format. * The assignment operator (`:=') returns the value of its right-hand argument. * All built-in procedures both modify _and_ return their argument.  File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 12.4.3.6 Modula-2 type and range checks ....................................... _Warning:_ in this release, GDB does not yet perform type or range checking. GDB considers two Modula-2 variables type equivalent if: * They are of types that have been declared equivalent via a `TYPE T1 = T2' statement * They have been declared on the same line. (Note: This is true of the GNU Modula-2 compiler, but it may not be true of other compilers.) As long as type checking is enabled, any attempt to combine variables whose types are not equivalent is an error. Range checking is done on all mathematical operations, assignment, array index bounds, and all built-in functions and procedures.  File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 12.4.3.7 The scope operators `::' and `.' ......................................... There are a few subtle differences between the Modula-2 scope operator (`.') and the GDB scope operator (`::'). The two have similar syntax: MODULE . ID SCOPE :: ID where SCOPE is the name of a module or a procedure, MODULE the name of a module, and ID is any declared identifier within your program, except another module. Using the `::' operator makes GDB search the scope specified by SCOPE for the identifier ID. If it is not found in the specified scope, then GDB searches all scopes enclosing the one specified by SCOPE. Using the `.' operator makes GDB search the current scope for the identifier specified by ID that was imported from the definition module specified by MODULE. With this operator, it is an error if the identifier ID was not imported from definition module MODULE, or if ID is not an identifier in MODULE.  File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 12.4.3.8 GDB and Modula-2 ......................... Some GDB commands have little use when debugging Modula-2 programs. Five subcommands of `set print' and `show print' apply specifically to C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. The first four apply to C++, and the last to the C `union' type, which has no direct analogue in Modula-2. The `@' operator (*note Expressions: Expressions.), while available with any language, is not useful with Modula-2. Its intent is to aid the debugging of "dynamic arrays", which cannot be created in Modula-2 as they can in C or C++. However, because an address can be specified by an integral constant, the construct `{TYPE}ADREXP' is still useful. In GDB scripts, the Modula-2 inequality operator `#' is interpreted as the beginning of a comment. Use `<>' instead.  File: gdb.info, Node: Ada, Prev: Modula-2, Up: Support 12.4.4 Ada ---------- The extensions made to GDB for Ada only support output from the GNU Ada (GNAT) compiler. Other Ada compilers are not currently supported, and attempting to debug executables produced by them is most likely to be difficult. * Menu: * Ada Mode Intro:: General remarks on the Ada syntax and semantics supported by Ada mode in GDB. * Omissions from Ada:: Restrictions on the Ada expression syntax. * Additions to Ada:: Extensions of the Ada expression syntax. * Stopping Before Main Program:: Debugging the program during elaboration. * Ada Glitches:: Known peculiarities of Ada mode.  File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada 12.4.4.1 Introduction ..................... The Ada mode of GDB supports a fairly large subset of Ada expression syntax, with some extensions. The philosophy behind the design of this subset is * That GDB should provide basic literals and access to operations for arithmetic, dereferencing, field selection, indexing, and subprogram calls, leaving more sophisticated computations to subprograms written into the program (which therefore may be called from GDB). * That type safety and strict adherence to Ada language restrictions are not particularly important to the GDB user. * That brevity is important to the GDB user. Thus, for brevity, the debugger acts as if there were implicit `with' and `use' clauses in effect for all user-written packages, making it unnecessary to fully qualify most names with their packages, regardless of context. Where this causes ambiguity, GDB asks the user's intent. The debugger will start in Ada mode if it detects an Ada main program. As for other languages, it will enter Ada mode when stopped in a program that was translated from an Ada source file. While in Ada mode, you may use `-' for comments. This is useful mostly for documenting command files. The standard GDB comment (`#') still works at the beginning of a line in Ada mode, but not in the middle (to allow based literals). The debugger supports limited overloading. Given a subprogram call in which the function symbol has multiple definitions, it will use the number of actual parameters and some information about their types to attempt to narrow the set of definitions. It also makes very limited use of context, preferring procedures to functions in the context of the `call' command, and functions to procedures elsewhere.  File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada 12.4.4.2 Omissions from Ada ........................... Here are the notable omissions from the subset: * Only a subset of the attributes are supported: - 'First, 'Last, and 'Length on array objects (not on types and subtypes). - 'Min and 'Max. - 'Pos and 'Val. - 'Tag. - 'Range on array objects (not subtypes), but only as the right operand of the membership (`in') operator. - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT extension). - 'Address. * The names in `Characters.Latin_1' are not available and concatenation is not implemented. Thus, escape characters in strings are not currently available. * Equality tests (`=' and `/=') on arrays test for bitwise equality of representations. They will generally work correctly for strings and arrays whose elements have integer or enumeration types. They may not work correctly for arrays whose element types have user-defined equality, for arrays of real values (in particular, IEEE-conformant floating point, because of negative zeroes and NaNs), and for arrays whose elements contain unused bits with indeterminate values. * The other component-by-component array operations (`and', `or', `xor', `not', and relational tests other than equality) are not implemented. * There are no record or array aggregates. * Calls to dispatching subprograms are not implemented. * The overloading algorithm is much more limited (i.e., less selective) than that of real Ada. It makes only limited use of the context in which a subexpression appears to resolve its meaning, and it is much looser in its rules for allowing type matches. As a result, some function calls will be ambiguous, and the user will be asked to choose the proper resolution. * The `new' operator is not implemented. * Entry calls are not implemented. * Aside from printing, arithmetic operations on the native VAX floating-point formats are not supported. * It is not possible to slice a packed array.  File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada 12.4.4.3 Additions to Ada ......................... As it does for other languages, GDB makes certain generic extensions to Ada (*note Expressions::): * If the expression E is a variable residing in memory (typically a local variable or array element) and N is a positive integer, then `E@N' displays the values of E and the N-1 adjacent variables following it in memory as an array. In Ada, this operator is generally not necessary, since its prime use is in displaying parts of an array, and slicing will usually do this in Ada. However, there are occasional uses when debugging programs in which certain debugging information has been optimized away. * `B::VAR' means "the variable named VAR that appears in function or file B." When B is a file name, you must typically surround it in single quotes. * The expression `{TYPE} ADDR' means "the variable of type TYPE that appears at address ADDR." * A name starting with `$' is a convenience variable (*note Convenience Vars::) or a machine register (*note Registers::). In addition, GDB provides a few other shortcuts and outright additions specific to Ada: * The assignment statement is allowed as an expression, returning its right-hand operand as its value. Thus, you may enter set x := y + 3 print A(tmp := y + 1) * The semicolon is allowed as an "operator," returning as its value the value of its right-hand operand. This allows, for example, complex conditional breaks: break f condition 1 (report(i); k += 1; A(k) > 100) * Rather than use catenation and symbolic character names to introduce special characters into strings, one may instead use a special bracket notation, which is also used to print strings. A sequence of characters of the form `["XX"]' within a string or character literal denotes the (single) character whose numeric encoding is XX in hexadecimal. The sequence of characters `["""]' also denotes a single quotation mark in strings. For example, "One line.["0a"]Next line.["0a"]" contains an ASCII newline character (`Ada.Characters.Latin_1.LF') after each period. * The subtype used as a prefix for the attributes 'Pos, 'Min, and 'Max is optional (and is ignored in any case). For example, it is valid to write print 'max(x, y) * When printing arrays, GDB uses positional notation when the array has a lower bound of 1, and uses a modified named notation otherwise. For example, a one-dimensional array of three integers with a lower bound of 3 might print as (3 => 10, 17, 1) That is, in contrast to valid Ada, only the first component has a `=>' clause. * You may abbreviate attributes in expressions with any unique, multi-character subsequence of their names (an exact match gets preference). For example, you may use a'len, a'gth, or a'lh in place of a'length. * Since Ada is case-insensitive, the debugger normally maps identifiers you type to lower case. The GNAT compiler uses upper-case characters for some of its internal identifiers, which are normally of no interest to users. For the rare occasions when you actually have to look at them, enclose them in angle brackets to avoid the lower-case mapping. For example, gdb print [0] * Printing an object of class-wide type or dereferencing an access-to-class-wide value will display all the components of the object's specific type (as indicated by its run-time tag). Likewise, component selection on such a value will operate on the specific type of the object.  File: gdb.info, Node: Stopping Before Main Program, Next: Ada Glitches, Prev: Additions to Ada, Up: Ada 12.4.4.4 Stopping at the Very Beginning ....................................... It is sometimes necessary to debug the program during elaboration, and before reaching the main procedure. As defined in the Ada Reference Manual, the elaboration code is invoked from a procedure called `adainit'. To run your program up to the beginning of elaboration, simply use the following two commands: `tbreak adainit' and `run'.  File: gdb.info, Node: Ada Glitches, Prev: Stopping Before Main Program, Up: Ada 12.4.4.5 Known Peculiarities of Ada Mode ........................................ Besides the omissions listed previously (*note Omissions from Ada::), we know of several problems with and limitations of Ada mode in GDB, some of which will be fixed with planned future releases of the debugger and the GNU Ada compiler. * Currently, the debugger has insufficient information to determine whether certain pointers represent pointers to objects or the objects themselves. Thus, the user may have to tack an extra `.all' after an expression to get it printed properly. * Static constants that the compiler chooses not to materialize as objects in storage are invisible to the debugger. * Named parameter associations in function argument lists are ignored (the argument lists are treated as positional). * Many useful library packages are currently invisible to the debugger. * Fixed-point arithmetic, conversions, input, and output is carried out using floating-point arithmetic, and may give results that only approximate those on the host machine. * The type of the 'Address attribute may not be `System.Address'. * The GNAT compiler never generates the prefix `Standard' for any of the standard symbols defined by the Ada language. GDB knows about this: it will strip the prefix from names when you use it, and will never look for a name you have so qualified among local symbols, nor match against symbols in other packages or subprograms. If you have defined entities anywhere in your program other than parameters and local variables whose simple names match names in `Standard', GNAT's lack of qualification here can cause confusion. When this happens, you can usually resolve the confusion by qualifying the problematic names with package `Standard' explicitly.  File: gdb.info, Node: Unsupported languages, Prev: Support, Up: Languages 12.5 Unsupported languages ========================== In addition to the other fully-supported programming languages, GDB also provides a pseudo-language, called `minimal'. It does not represent a real programming language, but provides a set of capabilities close to what the C or assembly languages provide. This should allow most simple operations to be performed while debugging an application that uses a language currently not supported by GDB. If the language is set to `auto', GDB will automatically select this language if the current frame corresponds to an unsupported language.  File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top 13 Examining the Symbol Table ***************************** The commands described in this chapter allow you to inquire about the symbols (names of variables, functions and types) defined in your program. This information is inherent in the text of your program and does not change as your program executes. GDB finds it in your program's symbol table, in the file indicated when you started GDB (*note Choosing files: File Options.), or by one of the file-management commands (*note Commands to specify files: Files.). Occasionally, you may need to refer to symbols that contain unusual characters, which GDB ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other source files (*note Program variables: Variables.). File names are recorded in object files as debugging symbols, but GDB would ordinarily parse a typical file name, like `foo.c', as the three words `foo' `.' `c'. To allow GDB to recognize `foo.c' as a single symbol, enclose it in single quotes; for example, p 'foo.c'::x looks up the value of `x' in the scope of the file `foo.c'. `info address SYMBOL' Describe where the data for SYMBOL is stored. For a register variable, this says which register it is kept in. For a non-register local variable, this prints the stack-frame offset at which the variable is always stored. Note the contrast with `print &SYMBOL', which does not work at all for a register variable, and for a stack local variable prints the exact address of the current instantiation of the variable. `info symbol ADDR' Print the name of a symbol which is stored at the address ADDR. If no symbol is stored exactly at ADDR, GDB prints the nearest symbol and an offset from it: (gdb) info symbol 0x54320 _initialize_vx + 396 in section .text This is the opposite of the `info address' command. You can use it to find out the name of a variable or a function given its address. `whatis EXPR' Print the data type of expression EXPR. EXPR is not actually evaluated, and any side-effecting operations (such as assignments or function calls) inside it do not take place. *Note Expressions: Expressions. `whatis' Print the data type of `$', the last value in the value history. `ptype TYPENAME' Print a description of data type TYPENAME. TYPENAME may be the name of a type, or for C code it may have the form `class CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. `ptype EXPR' `ptype' Print a description of the type of expression EXPR. `ptype' differs from `whatis' by printing a detailed description, instead of just the name of the type. For example, for this variable declaration: struct complex {double real; double imag;} v; the two commands give this output: (gdb) whatis v type = struct complex (gdb) ptype v type = struct complex { double real; double imag; } As with `whatis', using `ptype' without an argument refers to the type of `$', the last value in the value history. `info types REGEXP' `info types' Print a brief description of all types whose names match REGEXP (or all types in your program, if you supply no argument). Each complete typename is matched as though it were a complete line; thus, `i type value' gives information on all types in your program whose names include the string `value', but `i type ^value$' gives information only on types whose complete name is `value'. This command differs from `ptype' in two ways: first, like `whatis', it does not print a detailed description; second, it lists all source files where a type is defined. `info scope ADDR' List all the variables local to a particular scope. This command accepts a location--a function name, a source line, or an address preceded by a `*', and prints all the variables local to the scope defined by that location. For example: (gdb) info scope command_line_handler Scope for command_line_handler: Symbol rl is an argument at stack/frame offset 8, length 4. Symbol linebuffer is in static storage at address 0x150a18, length 4. Symbol linelength is in static storage at address 0x150a1c, length 4. Symbol p is a local variable in register $esi, length 4. Symbol p1 is a local variable in register $ebx, length 4. Symbol nline is a local variable in register $edx, length 4. Symbol repeat is a local variable at frame offset -8, length 4. This command is especially useful for determining what data to collect during a "trace experiment", see *Note collect: Tracepoint Actions. `info source' Show information about the current source file--that is, the source file for the function containing the current point of execution: * the name of the source file, and the directory containing it, * the directory it was compiled in, * its length, in lines, * which programming language it is written in, * whether the executable includes debugging information for that file, and if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and * whether the debugging information includes information about preprocessor macros. `info sources' Print the names of all source files in your program for which there is debugging information, organized into two lists: files whose symbols have already been read, and files whose symbols will be read when needed. `info functions' Print the names and data types of all defined functions. `info functions REGEXP' Print the names and data types of all defined functions whose names contain a match for regular expression REGEXP. Thus, `info fun step' finds all functions whose names include `step'; `info fun ^step' finds those whose names start with `step'. If a function name contains characters that conflict with the regular expression language (eg. `operator*()'), they may be quoted with a backslash. `info variables' Print the names and data types of all variables that are declared outside of functions (i.e. excluding local variables). `info variables REGEXP' Print the names and data types of all variables (except for local variables) whose names contain a match for regular expression REGEXP. `info classes' `info classes REGEXP' Display all Objective-C classes in your program, or (with the REGEXP argument) all those matching a particular regular expression. `info selectors' `info selectors REGEXP' Display all Objective-C selectors in your program, or (with the REGEXP argument) all those matching a particular regular expression. Some systems allow individual object files that make up your program to be replaced without stopping and restarting your program. For example, in VxWorks you can simply recompile a defective object file and keep on running. If you are running on one of these systems, you can allow GDB to reload the symbols for automatically relinked modules: `set symbol-reloading on' Replace symbol definitions for the corresponding source file when an object file with a particular name is seen again. `set symbol-reloading off' Do not replace symbol definitions when encountering object files of the same name more than once. This is the default state; if you are not running on a system that permits automatic relinking of modules, you should leave `symbol-reloading' off, since otherwise GDB may discard symbols when linking large programs, that may contain several modules (from different directories or libraries) with the same name. `show symbol-reloading' Show the current `on' or `off' setting. `set opaque-type-resolution on' Tell GDB to resolve opaque types. An opaque type is a type declared as a pointer to a `struct', `class', or `union'--for example, `struct MyType *'--that is used in one source file although the full declaration of `struct MyType' is in another source file. The default is on. A change in the setting of this subcommand will not take effect until the next time symbols for a file are loaded. `set opaque-type-resolution off' Tell GDB not to resolve opaque types. In this case, the type is printed as follows: {} `show opaque-type-resolution' Show whether opaque types are resolved or not. `maint print symbols FILENAME' `maint print psymbols FILENAME' `maint print msymbols FILENAME' Write a dump of debugging symbol data into the file FILENAME. These commands are used to debug the GDB symbol-reading code. Only symbols with debugging data are included. If you use `maint print symbols', GDB includes all the symbols for which it has already collected full details: that is, FILENAME reflects symbols for only those files whose symbols GDB has read. You can use the command `info sources' to find out which files these are. If you use `maint print psymbols' instead, the dump shows information about symbols that GDB only knows partially--that is, symbols defined in files that GDB has skimmed, but not yet read completely. Finally, `maint print msymbols' dumps just the minimal symbol information required for each object file from which GDB has read some symbols. *Note Commands to specify files: Files, for a discussion of how GDB reads symbols (in the description of `symbol-file'). `maint info symtabs [ REGEXP ]' `maint info psymtabs [ REGEXP ]' List the `struct symtab' or `struct partial_symtab' structures whose names match REGEXP. If REGEXP is not given, list them all. The output includes expressions which you can copy into a GDB debugging this one to examine a particular structure in more detail. For example: (gdb) maint info psymtabs dwarf2read { objfile /home/gnu/build/gdb/gdb ((struct objfile *) 0x82e69d0) { psymtab /home/gnu/src/gdb/dwarf2read.c ((struct partial_symtab *) 0x8474b10) readin no fullname (null) text addresses 0x814d3c8 -- 0x8158074 globals (* (struct partial_symbol **) 0x8507a08 @ 9) statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) dependencies (none) } } (gdb) maint info symtabs (gdb) We see that there is one partial symbol table whose filename contains the string `dwarf2read', belonging to the `gdb' executable; and we see that GDB has not read in any symtabs yet at all. If we set a breakpoint on a function, that will cause GDB to read the symtab for the compilation unit containing that function: (gdb) break dwarf2_psymtab_to_symtab Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, line 1574. (gdb) maint info symtabs { objfile /home/gnu/build/gdb/gdb ((struct objfile *) 0x82e69d0) { symtab /home/gnu/src/gdb/dwarf2read.c ((struct symtab *) 0x86c1f38) dirname (null) fullname (null) blockvector ((struct blockvector *) 0x86c1bd0) (primary) debugformat DWARF 2 } } (gdb)  File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top 14 Altering Execution ********************* Once you think you have found an error in your program, you might want to find out for certain whether correcting the apparent error would lead to correct results in the rest of the run. You can find the answer by experiment, using the GDB features for altering execution of the program. For example, you can store new values into variables or memory locations, give your program a signal, restart it at a different address, or even return prematurely from a function. * Menu: * Assignment:: Assignment to variables * Jumping:: Continuing at a different address * Signaling:: Giving your program a signal * Returning:: Returning from a function * Calling:: Calling your program's functions * Patching:: Patching your program  File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering 14.1 Assignment to variables ============================ To alter the value of a variable, evaluate an assignment expression. *Note Expressions: Expressions. For example, print x=4 stores the value 4 into the variable `x', and then prints the value of the assignment expression (which is 4). *Note Using GDB with Different Languages: Languages, for more information on operators in supported languages. If you are not interested in seeing the value of the assignment, use the `set' command instead of the `print' command. `set' is really the same as `print' except that the expression's value is not printed and is not put in the value history (*note Value history: Value History.). The expression is evaluated only for its effects. If the beginning of the argument string of the `set' command appears identical to a `set' subcommand, use the `set variable' command instead of just `set'. This command is identical to `set' except for its lack of subcommands. For example, if your program has a variable `width', you get an error if you try to set a new value with just `set width=13', because GDB has the command `set width': (gdb) whatis width type = double (gdb) p width $4 = 13 (gdb) set width=47 Invalid syntax in expression. The invalid expression, of course, is `=47'. In order to actually set the program's variable `width', use (gdb) set var width=47 Because the `set' command has many subcommands that can conflict with the names of program variables, it is a good idea to use the `set variable' command instead of just `set'. For example, if your program has a variable `g', you run into problems if you try to set a new value with just `set g=4', because GDB has the command `set gnutarget', abbreviated `set g': (gdb) whatis g type = double (gdb) p g $1 = 1 (gdb) set g=4 (gdb) p g $2 = 1 (gdb) r The program being debugged has been started already. Start it from the beginning? (y or n) y Starting program: /home/smith/cc_progs/a.out "/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target. (gdb) show g The current BFD target is "=4". The program variable `g' did not change, and you silently set the `gnutarget' to an invalid value. In order to set the variable `g', use (gdb) set var g=4 GDB allows more implicit conversions in assignments than C; you can freely store an integer value into a pointer variable or vice versa, and you can convert any structure to any other structure that is the same length or shorter. To store values into arbitrary places in memory, use the `{...}' construct to generate a value of specified type at a specified address (*note Expressions: Expressions.). For example, `{int}0x83040' refers to memory location `0x83040' as an integer (which implies a certain size and representation in memory), and set {int}0x83040 = 4 stores the value 4 into that memory location.  File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering 14.2 Continuing at a different address ====================================== Ordinarily, when you continue your program, you do so at the place where it stopped, with the `continue' command. You can instead continue at an address of your own choosing, with the following commands: `jump LINESPEC' Resume execution at line LINESPEC. Execution stops again immediately if there is a breakpoint there. *Note Printing source lines: List, for a description of the different forms of LINESPEC. It is common practice to use the `tbreak' command in conjunction with `jump'. *Note Setting breakpoints: Set Breaks. The `jump' command does not change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter. If line LINESPEC is in a different function from the one currently executing, the results may be bizarre if the two functions expect different patterns of arguments or of local variables. For this reason, the `jump' command requests confirmation if the specified line is not in the function currently executing. However, even bizarre results are predictable if you are well acquainted with the machine-language code of your program. `jump *ADDRESS' Resume execution at the instruction at address ADDRESS. On many systems, you can get much the same effect as the `jump' command by storing a new value into the register `$pc'. The difference is that this does not start your program running; it only changes the address of where it _will_ run when you continue. For example, set $pc = 0x485 makes the next `continue' command or stepping command execute at address `0x485', rather than at the address where your program stopped. *Note Continuing and stepping: Continuing and Stepping. The most common occasion to use the `jump' command is to back up--perhaps with more breakpoints set--over a portion of a program that has already executed, in order to examine its execution in more detail.  File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering 14.3 Giving your program a signal ================================= `signal SIGNAL' Resume execution where your program stopped, but immediately give it the signal SIGNAL. SIGNAL can be the name or the number of a signal. For example, on many systems `signal 2' and `signal SIGINT' are both ways of sending an interrupt signal. Alternatively, if SIGNAL is zero, continue execution without giving a signal. This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with the `continue' command; `signal 0' causes it to resume without a signal. `signal' does not repeat when you press a second time after executing the command. Invoking the `signal' command is not the same as invoking the `kill' utility from the shell. Sending a signal with `kill' causes GDB to decide what to do with the signal depending on the signal handling tables (*note Signals::). The `signal' command passes the signal directly to your program.  File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering 14.4 Returning from a function ============================== `return' `return EXPRESSION' You can cancel execution of a function call with the `return' command. If you give an EXPRESSION argument, its value is used as the function's return value. When you use `return', GDB discards the selected stack frame (and all frames within it). You can think of this as making the discarded frame return prematurely. If you wish to specify a value to be returned, give that value as the argument to `return'. This pops the selected stack frame (*note Selecting a frame: Selection.), and any other frames inside of it, leaving its caller as the innermost remaining frame. That frame becomes selected. The specified value is stored in the registers used for returning values of functions. The `return' command does not resume execution; it leaves the program stopped in the state that would exist if the function had just returned. In contrast, the `finish' command (*note Continuing and stepping: Continuing and Stepping.) resumes execution until the selected stack frame returns naturally.  File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering 14.5 Calling program functions ============================== `call EXPR' Evaluate the expression EXPR without displaying `void' returned values. You can use this variant of the `print' command if you want to execute a function from your program, but without cluttering the output with `void' returned values. If the result is not void, it is printed and saved in the value history.  File: gdb.info, Node: Patching, Prev: Calling, Up: Altering 14.6 Patching programs ====================== By default, GDB opens the file containing your program's executable code (or the corefile) read-only. This prevents accidental alterations to machine code; but it also prevents you from intentionally patching your program's binary. If you'd like to be able to patch the binary, you can specify that explicitly with the `set write' command. For example, you might want to turn on internal debugging flags, or even to make emergency repairs. `set write on' `set write off' If you specify `set write on', GDB opens executable and core files for both reading and writing; if you specify `set write off' (the default), GDB opens them read-only. If you have already loaded a file, you must load it again (using the `exec-file' or `core-file' command) after changing `set write', for your new setting to take effect. `show write' Display whether executable files and core files are opened for writing as well as reading.  File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top 15 GDB Files ************ GDB needs to know the file name of the program to be debugged, both in order to read its symbol table and in order to start your program. To debug a core dump of a previous run, you must also tell GDB the name of the core dump file. * Menu: * Files:: Commands to specify files * Separate Debug Files:: Debugging information in separate files * Symbol Errors:: Errors reading symbol files  File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files 15.1 Commands to specify files ============================== You may want to specify executable and core dump file names. The usual way to do this is at start-up time, using the arguments to GDB's start-up commands (*note Getting In and Out of GDB: Invocation.). Occasionally it is necessary to change to a different file during a GDB session. Or you may run GDB and forget to specify a file you want to use. In these situations the GDB commands to specify new files are useful. `file FILENAME' Use FILENAME as the program to be debugged. It is read for its symbols and for the contents of pure memory. It is also the program executed when you use the `run' command. If you do not specify a directory and the file is not found in the GDB working directory, GDB uses the environment variable `PATH' as a list of directories to search, just as the shell does when looking for a program to run. You can change the value of this variable, for both GDB and your program, using the `path' command. On systems with memory-mapped files, an auxiliary file named `FILENAME.syms' may hold symbol table information for FILENAME. If so, GDB maps in the symbol table from `FILENAME.syms', starting up more quickly. See the descriptions of the file options `-mapped' and `-readnow' (available on the command line, and with the commands `file', `symbol-file', or `add-symbol-file', described below), for more information. `file' `file' with no argument makes GDB discard any information it has on both executable file and the symbol table. `exec-file [ FILENAME ]' Specify that the program to be run (but not the symbol table) is found in FILENAME. GDB searches the environment variable `PATH' if necessary to locate your program. Omitting FILENAME means to discard information on the executable file. `symbol-file [ FILENAME ]' Read symbol table information from file FILENAME. `PATH' is searched when necessary. Use the `file' command to get both symbol table and program to run from the same file. `symbol-file' with no argument clears out GDB information on your program's symbol table. The `symbol-file' command causes GDB to forget the contents of its convenience variables, the value history, and all breakpoints and auto-display expressions. This is because they may contain pointers to the internal data recording symbols and data types, which are part of the old symbol table data being discarded inside GDB. `symbol-file' does not repeat if you press again after executing it once. When GDB is configured for a particular environment, it understands debugging information in whatever format is the standard generated for that environment; you may use either a GNU compiler, or other compilers that adhere to the local conventions. Best results are usually obtained from GNU compilers; for example, using `gcc' you can generate debugging information for optimized code. For most kinds of object files, with the exception of old SVR3 systems using COFF, the `symbol-file' command does not normally read the symbol table in full right away. Instead, it scans the symbol table quickly to find which source files and which symbols are present. The details are read later, one source file at a time, as they are needed. The purpose of this two-stage reading strategy is to make GDB start up faster. For the most part, it is invisible except for occasional pauses while the symbol table details for a particular source file are being read. (The `set verbose' command can turn these pauses into messages if desired. *Note Optional warnings and messages: Messages/Warnings.) We have not implemented the two-stage strategy for COFF yet. When the symbol table is stored in COFF format, `symbol-file' reads the symbol table data in full right away. Note that "stabs-in-COFF" still does the two-stage strategy, since the debug info is actually in stabs format. `symbol-file FILENAME [ -readnow ] [ -mapped ]' `file FILENAME [ -readnow ] [ -mapped ]' You can override the GDB two-stage strategy for reading symbol tables by using the `-readnow' option with any of the commands that load symbol table information, if you want to be sure GDB has the entire symbol table available. If memory-mapped files are available on your system through the `mmap' system call, you can use another option, `-mapped', to cause GDB to write the symbols for your program into a reusable file. Future GDB debugging sessions map in symbol information from this auxiliary symbol file (if the program has not changed), rather than spending time reading the symbol table from the executable program. Using the `-mapped' option has the same effect as starting GDB with the `-mapped' command-line option. You can use both options together, to make sure the auxiliary symbol file has all the symbol information for your program. The auxiliary symbol file for a program called MYPROG is called `MYPROG.syms'. Once this file exists (so long as it is newer than the corresponding executable), GDB always attempts to use it when you debug MYPROG; no special options or commands are needed. The `.syms' file is specific to the host machine where you run GDB. It holds an exact image of the internal GDB symbol table. It cannot be shared across multiple host platforms. `core-file [ FILENAME ]' `core' Specify the whereabouts of a core dump file to be used as the "contents of memory". Traditionally, core files contain only some parts of the address space of the process that generated them; GDB can access the executable file itself for other parts. `core-file' with no argument specifies that no core file is to be used. Note that the core file is ignored when your program is actually running under GDB. So, if you have been running your program and you wish to debug a core file instead, you must kill the subprocess in which the program is running. To do this, use the `kill' command (*note Killing the child process: Kill Process.). `add-symbol-file FILENAME ADDRESS' `add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]' `add-symbol-file FILENAME -sSECTION ADDRESS ...' The `add-symbol-file' command reads additional symbol table information from the file FILENAME. You would use this command when FILENAME has been dynamically loaded (by some other means) into the program that is running. ADDRESS should be the memory address at which the file has been loaded; GDB cannot figure this out for itself. You can additionally specify an arbitrary number of `-sSECTION ADDRESS' pairs, to give an explicit section name and base address for that section. You can specify any ADDRESS as an expression. The symbol table of the file FILENAME is added to the symbol table originally read with the `symbol-file' command. You can use the `add-symbol-file' command any number of times; the new symbol data thus read keeps adding to the old. To discard all old symbol data instead, use the `symbol-file' command without any arguments. Although FILENAME is typically a shared library file, an executable file, or some other object file which has been fully relocated for loading into a process, you can also load symbolic information from relocatable `.o' files, as long as: * the file's symbolic information refers only to linker symbols defined in that file, not to symbols defined by other object files, * every section the file's symbolic information refers to has actually been loaded into the inferior, as it appears in the file, and * you can determine the address at which every section was loaded, and provide these to the `add-symbol-file' command. Some embedded operating systems, like Sun Chorus and VxWorks, can load relocatable files into an already running program; such systems typically make the requirements above easy to meet. However, it's important to recognize that many native systems use complex link procedures (`.linkonce' section factoring and C++ constructor table assembly, for example) that make the requirements difficult to meet. In general, one cannot assume that using `add-symbol-file' to read a relocatable object file's symbolic information will have the same effect as linking the relocatable object file into the program in the normal way. `add-symbol-file' does not repeat if you press after using it. You can use the `-mapped' and `-readnow' options just as with the `symbol-file' command, to change how GDB manages the symbol table information for FILENAME. `add-shared-symbol-file' The `add-shared-symbol-file' command can be used only under Harris' CXUX operating system for the Motorola 88k. GDB automatically looks for shared libraries, however if GDB does not find yours, you can run `add-shared-symbol-file'. It takes no arguments. `section' The `section' command changes the base address of section SECTION of the exec file to ADDR. This can be used if the exec file does not contain section addresses, (such as in the a.out format), or when the addresses specified in the file itself are wrong. Each section must be changed separately. The `info files' command, described below, lists all the sections and their addresses. `info files' `info target' `info files' and `info target' are synonymous; both print the current target (*note Specifying a Debugging Target: Targets.), including the names of the executable and core dump files currently in use by GDB, and the files from which symbols were loaded. The command `help target' lists all possible targets rather than current ones. `maint info sections' Another command that can give you extra information about program sections is `maint info sections'. In addition to the section information displayed by `info files', this command displays the flags and file offset of each section in the executable and core dump files. In addition, `maint info sections' provides the following command options (which may be arbitrarily combined): `ALLOBJ' Display sections for all loaded object files, including shared libraries. `SECTIONS' Display info only for named SECTIONS. `SECTION-FLAGS' Display info only for sections for which SECTION-FLAGS are true. The section flags that GDB currently knows about are: `ALLOC' Section will have space allocated in the process when loaded. Set for all sections except those containing debug information. `LOAD' Section will be loaded from the file into the child process memory. Set for pre-initialized code and data, clear for `.bss' sections. `RELOC' Section needs to be relocated before loading. `READONLY' Section cannot be modified by the child process. `CODE' Section contains executable code only. `DATA' Section contains data only (no executable code). `ROM' Section will reside in ROM. `CONSTRUCTOR' Section contains data for constructor/destructor lists. `HAS_CONTENTS' Section is not empty. `NEVER_LOAD' An instruction to the linker to not output the section. `COFF_SHARED_LIBRARY' A notification to the linker that the section contains COFF shared library information. `IS_COMMON' Section contains common symbols. `set trust-readonly-sections on' Tell GDB that readonly sections in your object file really are read-only (i.e. that their contents will not change). In that case, GDB can fetch values from these sections out of the object file, rather than from the target program. For some targets (notably embedded ones), this can be a significant enhancement to debugging performance. The default is off. `set trust-readonly-sections off' Tell GDB not to trust readonly sections. This means that the contents of the section might change while the program is running, and must therefore be fetched from the target when needed. All file-specifying commands allow both absolute and relative file names as arguments. GDB always converts the file name to an absolute file name and remembers it that way. GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared libraries. GDB automatically loads symbol definitions from shared libraries when you use the `run' command, or when you examine a core file. (Before you issue the `run' command, GDB does not understand references to a function in a shared library, however--unless you are debugging a core file). On HP-UX, if the program loads a library explicitly, GDB automatically loads the symbols at the time of the `shl_load' call. There are times, however, when you may wish to not automatically load symbol definitions from shared libraries, such as when they are particularly large or there are many of them. To control the automatic loading of shared library symbols, use the commands: `set auto-solib-add MODE' If MODE is `on', symbols from all shared object libraries will be loaded automatically when the inferior begins execution, you attach to an independently started inferior, or when the dynamic linker informs GDB that a new library has been loaded. If MODE is `off', symbols must be loaded manually, using the `sharedlibrary' command. The default value is `on'. `show auto-solib-add' Display the current autoloading mode. To explicitly load shared library symbols, use the `sharedlibrary' command: `info share' `info sharedlibrary' Print the names of the shared libraries which are currently loaded. `sharedlibrary REGEX' `share REGEX' Load shared object library symbols for files matching a Unix regular expression. As with files loaded automatically, it only loads shared libraries required by your program for a core file or after typing `run'. If REGEX is omitted all shared libraries required by your program are loaded. On some systems, such as HP-UX systems, GDB supports autoloading shared library symbols until a limiting threshold size is reached. This provides the benefit of allowing autoloading to remain on by default, but avoids autoloading excessively large shared libraries, up to a threshold that is initially set, but which you can modify if you wish. Beyond that threshold, symbols from shared libraries must be explicitly loaded. To load these symbols, use the command `sharedlibrary FILENAME'. The base address of the shared library is determined automatically by GDB and need not be specified. To display or set the threshold, use the commands: `set auto-solib-limit THRESHOLD' Set the autoloading size threshold, in an integral number of megabytes. If THRESHOLD is nonzero and shared library autoloading is enabled, symbols from all shared object libraries will be loaded until the total size of the loaded shared library symbols exceeds this threshold. Otherwise, symbols must be loaded manually, using the `sharedlibrary' command. The default threshold is 100 (i.e. 100 Mb). `show auto-solib-limit' Display the current autoloading size threshold, in megabytes. Shared libraries are also supported in many cross or remote debugging configurations. A copy of the target's libraries need to be present on the host system; they need to be the same as the target libraries, although the copies on the target can be stripped as long as the copies on the host are not. You need to tell GDB where the target libraries are, so that it can load the correct copies--otherwise, it may try to load the host's libraries. GDB has two variables to specify the search directories for target libraries. `set solib-absolute-prefix PATH' If this variable is set, PATH will be used as a prefix for any absolute shared library paths; many runtime loaders store the absolute paths to the shared library in the target program's memory. If you use `solib-absolute-prefix' to find shared libraries, they need to be laid out in the same way that they are on the target, with e.g. a `/usr/lib' hierarchy under PATH. You can set the default value of `solib-absolute-prefix' by using the configure-time `--with-sysroot' option. `show solib-absolute-prefix' Display the current shared library prefix. `set solib-search-path PATH' If this variable is set, PATH is a colon-separated list of directories to search for shared libraries. `solib-search-path' is used after `solib-absolute-prefix' fails to locate the library, or if the path to the library is relative instead of absolute. If you want to use `solib-search-path' instead of `solib-absolute-prefix', be sure to set `solib-absolute-prefix' to a nonexistant directory to prevent GDB from finding your host's libraries. `show solib-search-path' Display the current shared library search path.  File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files 15.2 Debugging Information in Separate Files ============================================ GDB allows you to put a program's debugging information in a file separate from the executable itself, in a way that allows GDB to find and load the debugging information automatically. Since debugging information can be very large -- sometimes larger than the executable code itself -- some systems distribute debugging information for their executables in separate files, which users can install only when they need to debug a problem. If an executable's debugging information has been extracted to a separate file, the executable should contain a "debug link" giving the name of the debugging information file (with no directory components), and a checksum of its contents. (The exact form of a debug link is described below.) If the full name of the directory containing the executable is EXECDIR, and the executable has a debug link that specifies the name DEBUGFILE, then GDB will automatically search for the debugging information file in three places: * the directory containing the executable file (that is, it will look for a file named `EXECDIR/DEBUGFILE', * a subdirectory of that directory named `.debug' (that is, the file `EXECDIR/.debug/DEBUGFILE', and * a subdirectory of the global debug file directory that includes the executable's full path, and the name from the link (that is, the file `GLOBALDEBUGDIR/EXECDIR/DEBUGFILE', where GLOBALDEBUGDIR is the global debug file directory, and EXECDIR has been turned into a relative path). GDB checks under each of these names for a debugging information file whose checksum matches that given in the link, and reads the debugging information from the first one it finds. So, for example, if you ask GDB to debug `/usr/bin/ls', which has a link containing the name `ls.debug', and the global debug directory is `/usr/lib/debug', then GDB will look for debug information in `/usr/bin/ls.debug', `/usr/bin/.debug/ls.debug', and `/usr/lib/debug/usr/bin/ls.debug'. You can set the global debugging info directory's name, and view the name GDB is currently using. `set debug-file-directory DIRECTORY' Set the directory which GDB searches for separate debugging information files to DIRECTORY. `show debug-file-directory' Show the directory GDB searches for separate debugging information files. A debug link is a special section of the executable file named `.gnu_debuglink'. The section must contain: * A filename, with any leading directory components removed, followed by a zero byte, * zero to three bytes of padding, as needed to reach the next four-byte boundary within the section, and * a four-byte CRC checksum, stored in the same endianness used for the executable file itself. The checksum is computed on the debugging information file's full contents by the function given below, passing zero as the CRC argument. Any executable file format can carry a debug link, as long as it can contain a section named `.gnu_debuglink' with the contents described above. The debugging information file itself should be an ordinary executable, containing a full set of linker symbols, sections, and debugging information. The sections of the debugging information file should have the same names, addresses and sizes as the original file, but they need not contain any data -- much like a `.bss' section in an ordinary executable. As of December 2002, there is no standard GNU utility to produce separated executable / debugging information file pairs. Ulrich Drepper's `elfutils' package, starting with version 0.53, contains a version of the `strip' command such that the command `strip foo -f foo.debug' removes the debugging information from the executable file `foo', places it in the file `foo.debug', and leaves behind a debug link in `foo'. Since there are many different ways to compute CRC's (different polynomials, reversals, byte ordering, etc.), the simplest way to describe the CRC used in `.gnu_debuglink' sections is to give the complete code for a function that computes it: unsigned long gnu_debuglink_crc32 (unsigned long crc, unsigned char *buf, size_t len) { static const unsigned long crc32_table[256] = { 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d }; unsigned char *end; crc = ~crc & 0xffffffff; for (end = buf + len; buf < end; ++buf) crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); return ~crc & 0xffffffff; }  File: gdb.info, Node: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files 15.3 Errors reading symbol files ================================ While reading a symbol file, GDB occasionally encounters problems, such as symbol types it does not recognize, or known bugs in compiler output. By default, GDB does not notify you of such problems, since they are relatively common and primarily of interest to people debugging compilers. If you are interested in seeing information about ill-constructed symbol tables, you can either ask GDB to print only one message about each such type of problem, no matter how many times the problem occurs; or you can ask GDB to print more messages, to see how many times the problems occur, with the `set complaints' command (*note Optional warnings and messages: Messages/Warnings.). The messages currently printed, and their meanings, include: `inner block not inside outer block in SYMBOL' The symbol information shows where symbol scopes begin and end (such as at the start of a function or a block of statements). This error indicates that an inner scope block is not fully contained in its outer scope blocks. GDB circumvents the problem by treating the inner block as if it had the same scope as the outer block. In the error message, SYMBOL may be shown as "`(don't know)'" if the outer block is not a function. `block at ADDRESS out of order' The symbol information for symbol scope blocks should occur in order of increasing addresses. This error indicates that it does not do so. GDB does not circumvent this problem, and has trouble locating symbols in the source file whose symbols it is reading. (You can often determine what source file is affected by specifying `set verbose on'. *Note Optional warnings and messages: Messages/Warnings.) `bad block start address patched' The symbol information for a symbol scope block has a start address smaller than the address of the preceding source line. This is known to occur in the SunOS 4.1.1 (and earlier) C compiler. GDB circumvents the problem by treating the symbol scope block as starting on the previous source line. `bad string table offset in symbol N' Symbol number N contains a pointer into the string table which is larger than the size of the string table. GDB circumvents the problem by considering the symbol to have the name `foo', which may cause other problems if many symbols end up with this name. `unknown symbol type `0xNN'' The symbol information contains new data types that GDB does not yet know how to read. `0xNN' is the symbol type of the uncomprehended information, in hexadecimal. GDB circumvents the error by ignoring this symbol information. This usually allows you to debug your program, though certain symbols are not accessible. If you encounter such a problem and feel like debugging it, you can debug `gdb' with itself, breakpoint on `complain', then go up to the function `read_dbx_symtab' and examine `*bufp' to see the symbol. `stub type has NULL name' GDB could not find the full definition for a struct or class. `const/volatile indicator missing (ok if using g++ v1.x), got...' The symbol information for a C++ member function is missing some information that recent versions of the compiler should have output for it. `info mismatch between compiler and debugger' GDB could not parse a type specification output by the compiler.  File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top 16 Specifying a Debugging Target ******************************** A "target" is the execution environment occupied by your program. Often, GDB runs in the same host environment as your program; in that case, the debugging target is specified as a side effect when you use the `file' or `core' commands. When you need more flexibility--for example, running GDB on a physically separate host, or controlling a standalone system over a serial port or a realtime system over a TCP/IP connection--you can use the `target' command to specify one of the target types configured for GDB (*note Commands for managing targets: Target Commands.). * Menu: * Active Targets:: Active targets * Target Commands:: Commands for managing targets * Byte Order:: Choosing target byte order * Remote:: Remote debugging * KOD:: Kernel Object Display  File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets 16.1 Active targets =================== There are three classes of targets: processes, core files, and executable files. GDB can work concurrently on up to three active targets, one in each class. This allows you to (for example) start a process and inspect its activity without abandoning your work on a core file. For example, if you execute `gdb a.out', then the executable file `a.out' is the only active target. If you designate a core file as well--presumably from a prior run that crashed and coredumped--then GDB has two active targets and uses them in tandem, looking first in the corefile target, then in the executable file, to satisfy requests for memory addresses. (Typically, these two classes of target are complementary, since core files contain only a program's read-write memory--variables and so on--plus machine status, while executable files contain only the program text and initialized data.) When you type `run', your executable file becomes an active process target as well. When a process target is active, all GDB commands requesting memory addresses refer to that target; addresses in an active core file or executable file target are obscured while the process target is active. Use the `core-file' and `exec-file' commands to select a new core file or executable target (*note Commands to specify files: Files.). To specify as a target a process that is already running, use the `attach' command (*note Debugging an already-running process: Attach.).  File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets 16.2 Commands for managing targets ================================== `target TYPE PARAMETERS' Connects the GDB host environment to a target machine or process. A target is typically a protocol for talking to debugging facilities. You use the argument TYPE to specify the type or protocol of the target machine. Further PARAMETERS are interpreted by the target protocol, but typically include things like device names or host names to connect with, process numbers, and baud rates. The `target' command does not repeat if you press again after executing the command. `help target' Displays the names of all targets available. To display targets currently selected, use either `info target' or `info files' (*note Commands to specify files: Files.). `help target NAME' Describe a particular target, including any parameters necessary to select it. `set gnutarget ARGS' GDB uses its own library BFD to read your files. GDB knows whether it is reading an "executable", a "core", or a ".o" file; however, you can specify the file format with the `set gnutarget' command. Unlike most `target' commands, with `gnutarget' the `target' refers to a program, not a machine. _Warning:_ To specify a file format with `set gnutarget', you must know the actual BFD name. *Note Commands to specify files: Files. `show gnutarget' Use the `show gnutarget' command to display what file format `gnutarget' is set to read. If you have not set `gnutarget', GDB will determine the file format for each file automatically, and `show gnutarget' displays `The current BDF target is "auto"'. Here are some common targets (available, or not, depending on the GDB configuration): `target exec PROGRAM' An executable file. `target exec PROGRAM' is the same as `exec-file PROGRAM'. `target core FILENAME' A core dump file. `target core FILENAME' is the same as `core-file FILENAME'. `target remote DEV' Remote serial target in GDB-specific protocol. The argument DEV specifies what serial device to use for the connection (e.g. `/dev/ttya'). *Note Remote debugging: Remote. `target remote' supports the `load' command. This is only useful if you have some other way of getting the stub to the target system, and you can put it somewhere in memory where it won't get clobbered by the download. `target sim' Builtin CPU simulator. GDB includes simulators for most architectures. In general, target sim load run works; however, you cannot assume that a specific memory map, device drivers, or even basic I/O is available, although some simulators do provide these. For info about any processor-specific simulator details, see the appropriate section in *Note Embedded Processors: Embedded Processors. Some configurations may include these targets as well: `target nrom DEV' NetROM ROM emulator. This target only supports downloading. Different targets are available on different configurations of GDB; your configuration may have more or fewer targets. Many remote targets require you to download the executable's code once you've successfully established a connection. `load FILENAME' Depending on what remote debugging facilities are configured into GDB, the `load' command may be available. Where it exists, it is meant to make FILENAME (an executable) available for debugging on the remote system--by downloading, or dynamic linking, for example. `load' also records the FILENAME symbol table in GDB, like the `add-symbol-file' command. If your GDB does not have a `load' command, attempting to execute it gets the error message "`You can't do that when your target is ...'" The file is loaded at whatever address is specified in the executable. For some object file formats, you can specify the load address when you link the program; for other formats, like a.out, the object file format specifies a fixed address. `load' does not repeat if you press again after using it.  File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets 16.3 Choosing target byte order =============================== Some types of processors, such as the MIPS, PowerPC, and Renesas SH, offer the ability to run either big-endian or little-endian byte orders. Usually the executable or symbol will include a bit to designate the endian-ness, and you will not need to worry about which to use. However, you may still find it useful to adjust GDB's idea of processor endian-ness manually. `set endian big' Instruct GDB to assume the target is big-endian. `set endian little' Instruct GDB to assume the target is little-endian. `set endian auto' Instruct GDB to use the byte order associated with the executable. `show endian' Display GDB's current idea of the target byte order. Note that these commands merely adjust interpretation of symbolic data on the host, and that they have absolutely no effect on the target system.  File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets 16.4 Remote debugging ===================== If you are trying to debug a program running on a machine that cannot run GDB in the usual way, it is often useful to use remote debugging. For example, you might use remote debugging on an operating system kernel, or on a small system which does not have a general purpose operating system powerful enough to run a full-featured debugger. Some configurations of GDB have special serial or TCP/IP interfaces to make this work with particular debugging targets. In addition, GDB comes with a generic serial protocol (specific to GDB, but not specific to any particular target system) which you can use if you write the remote stubs--the code that runs on the remote system to communicate with GDB. Other remote targets may be available in your configuration of GDB; use `help target' to list them.  File: gdb.info, Node: KOD, Prev: Remote, Up: Targets 16.5 Kernel Object Display ========================== Some targets support kernel object display. Using this facility, GDB communicates specially with the underlying operating system and can display information about operating system-level objects such as mutexes and other synchronization objects. Exactly which objects can be displayed is determined on a per-OS basis. Use the `set os' command to set the operating system. This tells GDB which kernel object display module to initialize: (gdb) set os cisco The associated command `show os' displays the operating system set with the `set os' command; if no operating system has been set, `show os' will display an empty string `""'. If `set os' succeeds, GDB will display some information about the operating system, and will create a new `info' command which can be used to query the target. The `info' command is named after the operating system: (gdb) info cisco List of Cisco Kernel Objects Object Description any Any and all objects Further subcommands can be used to query about particular objects known by the kernel. There is currently no way to determine whether a given operating system is supported other than to try setting it with `set os NAME', where NAME is the name of the operating system you want to try.  File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top 17 Debugging remote programs **************************** * Menu: * Connecting:: Connecting to a remote target * Server:: Using the gdbserver program * NetWare:: Using the gdbserve.nlm program * Remote configuration:: Remote configuration * remote stub:: Implementing a remote stub  File: gdb.info, Node: Connecting, Next: Server, Up: Remote Debugging 17.1 Connecting to a remote target ================================== On the GDB host machine, you will need an unstripped copy of your program, since GDB needs symobl and debugging information. Start up GDB as usual, using the name of the local copy of your program as the first argument. If you're using a serial line, you may want to give GDB the `--baud' option, or use the `set remotebaud' command before the `target' command. After that, use `target remote' to establish communications with the target machine. Its argument specifies how to communicate--either via a devicename attached to a direct serial line, or a TCP or UDP port (possibly to a terminal server which in turn has a serial line to the target). For example, to use a serial line connected to the device named `/dev/ttyb': target remote /dev/ttyb To use a TCP connection, use an argument of the form `HOST:PORT' or `tcp:HOST:PORT'. For example, to connect to port 2828 on a terminal server named `manyfarms': target remote manyfarms:2828 If your remote target is actually running on the same machine as your debugger session (e.g. a simulator of your target running on the same host), you can omit the hostname. For example, to connect to port 1234 on your local machine: target remote :1234 Note that the colon is still required here. To use a UDP connection, use an argument of the form `udp:HOST:PORT'. For example, to connect to UDP port 2828 on a terminal server named `manyfarms': target remote udp:manyfarms:2828 When using a UDP connection for remote debugging, you should keep in mind that the `U' stands for "Unreliable". UDP can silently drop packets on busy or unreliable networks, which will cause havoc with your debugging session. Now you can use all the usual commands to examine and change data and to step and continue the remote program. Whenever GDB is waiting for the remote program, if you type the interrupt character (often ), GDB attempts to stop the program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, GDB displays this prompt: Interrupted while waiting for the program. Give up (and stop debugging it)? (y or n) If you type `y', GDB abandons the remote debugging session. (If you decide you want to try again later, you can use `target remote' again to connect once more.) If you type `n', GDB goes back to waiting. `detach' When you have finished debugging the remote program, you can use the `detach' command to release it from GDB control. Detaching from the target normally resumes its execution, but the results will depend on your particular remote stub. After the `detach' command, GDB is free to connect to another target. `disconnect' The `disconnect' command behaves like `detach', except that the target is generally not resumed. It will wait for GDB (this instance or another one) to connect and continue debugging. After the `disconnect' command, GDB is again free to connect to another target.  File: gdb.info, Node: Server, Next: NetWare, Prev: Connecting, Up: Remote Debugging 17.2 Using the `gdbserver' program ================================== `gdbserver' is a control program for Unix-like systems, which allows you to connect your program with a remote GDB via `target remote'--but without linking in the usual debugging stub. `gdbserver' is not a complete replacement for the debugging stubs, because it requires essentially the same operating-system facilities that GDB itself does. In fact, a system that can run `gdbserver' to connect to a remote GDB could also run GDB locally! `gdbserver' is sometimes useful nevertheless, because it is a much smaller program than GDB itself. It is also easier to port than all of GDB, so you may be able to get started more quickly on a new system by using `gdbserver'. Finally, if you develop code for real-time systems, you may find that the tradeoffs involved in real-time operation make it more convenient to do as much development work as possible on another system, for example by cross-compiling. You can use `gdbserver' to make a similar choice for debugging. GDB and `gdbserver' communicate via either a serial line or a TCP connection, using the standard GDB remote serial protocol. _On the target machine,_ you need to have a copy of the program you want to debug. `gdbserver' does not need your program's symbol table, so you can strip the program if necessary to save space. GDB on the host system does all the symbol handling. To use the server, you must tell it how to communicate with GDB; the name of your program; and the arguments for your program. The usual syntax is: target> gdbserver COMM PROGRAM [ ARGS ... ] COMM is either a device name (to use a serial line) or a TCP hostname and portnumber. For example, to debug Emacs with the argument `foo.txt' and communicate with GDB over the serial port `/dev/com1': target> gdbserver /dev/com1 emacs foo.txt `gdbserver' waits passively for the host GDB to communicate with it. To use a TCP connection instead of a serial line: target> gdbserver host:2345 emacs foo.txt The only difference from the previous example is the first argument, specifying that you are communicating with the host GDB via TCP. The `host:2345' argument means that `gdbserver' is to expect a TCP connection from machine `host' to local TCP port 2345. (Currently, the `host' part is ignored.) You can choose any number you want for the port number as long as it does not conflict with any TCP ports already in use on the target system (for example, `23' is reserved for `telnet').(1) You must use the same port number with the host GDB `target remote' command. On some targets, `gdbserver' can also attach to running programs. This is accomplished via the `--attach' argument. The syntax is: target> gdbserver COMM --attach PID PID is the process ID of a currently running process. It isn't necessary to point `gdbserver' at a binary for the running process. You can debug processes by name instead of process ID if your target has the `pidof' utility: target> gdbserver COMM --attach `pidof PROGRAM` In case more than one copy of PROGRAM is running, or PROGRAM has multiple threads, most versions of `pidof' support the `-s' option to only return the first process ID. _On the host machine,_ connect to your target (*note Connecting to a remote target: Connecting.). For TCP connections, you must start up `gdbserver' prior to using the `target remote' command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like `Connection refused'. You don't need to use the `load' command in GDB when using gdbserver, since the program is already on the target. ---------- Footnotes ---------- (1) If you choose a port number that conflicts with another service, `gdbserver' prints an error message and exits.  File: gdb.info, Node: NetWare, Next: Remote configuration, Prev: Server, Up: Remote Debugging 17.3 Using the `gdbserve.nlm' program ===================================== `gdbserve.nlm' is a control program for NetWare systems, which allows you to connect your program with a remote GDB via `target remote'. GDB and `gdbserve.nlm' communicate via a serial line, using the standard GDB remote serial protocol. _On the target machine,_ you need to have a copy of the program you want to debug. `gdbserve.nlm' does not need your program's symbol table, so you can strip the program if necessary to save space. GDB on the host system does all the symbol handling. To use the server, you must tell it how to communicate with GDB; the name of your program; and the arguments for your program. The syntax is: load gdbserve [ BOARD=BOARD ] [ PORT=PORT ] [ BAUD=BAUD ] PROGRAM [ ARGS ... ] BOARD and PORT specify the serial line; BAUD specifies the baud rate used by the connection. PORT and NODE default to 0, BAUD defaults to 9600bps. For example, to debug Emacs with the argument `foo.txt'and communicate with GDB over serial port number 2 or board 1 using a 19200bps connection: load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt __ On the GDB host machine, connect to your target (*note Connecting to a remote target: Connecting.).  File: gdb.info, Node: Remote configuration, Next: remote stub, Prev: NetWare, Up: Remote Debugging 17.4 Remote configuration ========================= The following configuration options are available when debugging remote programs: `set remote hardware-watchpoint-limit LIMIT' `set remote hardware-breakpoint-limit LIMIT' Restrict GDB to using LIMIT remote hardware breakpoint or watchpoints. A limit of -1, the default, is treated as unlimited.  File: gdb.info, Node: remote stub, Prev: Remote configuration, Up: Remote Debugging 17.5 Implementing a remote stub =============================== The stub files provided with GDB implement the target side of the communication protocol, and the GDB side is implemented in the GDB source file `remote.c'. Normally, you can simply allow these subroutines to communicate, and ignore the details. (If you're implementing your own stub file, you can still ignore the details: start with one of the existing stub files. `sparc-stub.c' is the best organized, and therefore the easiest to read.) To debug a program running on another machine (the debugging "target" machine), you must first arrange for all the usual prerequisites for the program to run by itself. For example, for a C program, you need: 1. A startup routine to set up the C runtime environment; these usually have a name like `crt0'. The startup routine may be supplied by your hardware supplier, or you may have to write your own. 2. A C subroutine library to support your program's subroutine calls, notably managing input and output. 3. A way of getting your program to the other machine--for example, a download program. These are often supplied by the hardware manufacturer, but you may have to write your own from hardware documentation. The next step is to arrange for your program to use a serial port to communicate with the machine where GDB is running (the "host" machine). In general terms, the scheme looks like this: _On the host,_ GDB already understands how to use this protocol; when everything else is set up, you can simply use the `target remote' command (*note Specifying a Debugging Target: Targets.). _On the target,_ you must link with your program a few special-purpose subroutines that implement the GDB remote serial protocol. The file containing these subroutines is called a "debugging stub". On certain remote targets, you can use an auxiliary program `gdbserver' instead of linking a stub into your program. *Note Using the `gdbserver' program: Server, for details. The debugging stub is specific to the architecture of the remote machine; for example, use `sparc-stub.c' to debug programs on SPARC boards. These working remote stubs are distributed with GDB: `i386-stub.c' For Intel 386 and compatible architectures. `m68k-stub.c' For Motorola 680x0 architectures. `sh-stub.c' For Renesas SH architectures. `sparc-stub.c' For SPARC architectures. `sparcl-stub.c' For Fujitsu SPARCLITE architectures. The `README' file in the GDB distribution may list other recently added stubs. * Menu: * Stub Contents:: What the stub can do for you * Bootstrapping:: What you must do for the stub * Debug Session:: Putting it all together  File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: remote stub 17.5.1 What the stub can do for you ----------------------------------- The debugging stub for your architecture supplies these three subroutines: `set_debug_traps' This routine arranges for `handle_exception' to run when your program stops. You must call this subroutine explicitly near the beginning of your program. `handle_exception' This is the central workhorse, but your program never calls it explicitly--the setup code arranges for `handle_exception' to run when a trap is triggered. `handle_exception' takes control when your program stops during execution (for example, on a breakpoint), and mediates communications with GDB on the host machine. This is where the communications protocol is implemented; `handle_exception' acts as the GDB representative on the target machine. It begins by sending summary information on the state of your program, then continues to execute, retrieving and transmitting any information GDB needs, until you execute a GDB command that makes your program resume; at that point, `handle_exception' returns control to your own code on the target machine. `breakpoint' Use this auxiliary subroutine to make your program contain a breakpoint. Depending on the particular situation, this may be the only way for GDB to get control. For instance, if your target machine has some sort of interrupt button, you won't need to call this; pressing the interrupt button transfers control to `handle_exception'--in effect, to GDB. On some machines, simply receiving characters on the serial port may also trigger a trap; again, in that situation, you don't need to call `breakpoint' from your own program--simply running `target remote' from the host GDB session gets control. Call `breakpoint' if none of these is true, or if you simply want to make certain your program stops at a predetermined point for the start of your debugging session.  File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: remote stub 17.5.2 What you must do for the stub ------------------------------------ The debugging stubs that come with GDB are set up for a particular chip architecture, but they have no information about the rest of your debugging target machine. First of all you need to tell the stub how to communicate with the serial port. `int getDebugChar()' Write this subroutine to read a single character from the serial port. It may be identical to `getchar' for your target system; a different name is used to allow you to distinguish the two if you wish. `void putDebugChar(int)' Write this subroutine to write a single character to the serial port. It may be identical to `putchar' for your target system; a different name is used to allow you to distinguish the two if you wish. If you want GDB to be able to stop your program while it is running, you need to use an interrupt-driven serial driver, and arrange for it to stop when it receives a `^C' (`\003', the control-C character). That is the character which GDB uses to tell the remote system to stop. Getting the debugging target to return the proper status to GDB probably requires changes to the standard stub; one quick and dirty way is to just execute a breakpoint instruction (the "dirty" part is that GDB reports a `SIGTRAP' instead of a `SIGINT'). Other routines you need to supply are: `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' Write this function to install EXCEPTION_ADDRESS in the exception handling tables. You need to do this because the stub does not have any way of knowing what the exception handling tables on your target system are like (for example, the processor's table might be in ROM, containing entries which point to a table in RAM). EXCEPTION_NUMBER is the exception number which should be changed; its meaning is architecture-dependent (for example, different numbers might represent divide by zero, misaligned access, etc). When this exception occurs, control should be transferred directly to EXCEPTION_ADDRESS, and the processor state (stack, registers, and so on) should be just as it is when a processor exception occurs. So if you want to use a jump instruction to reach EXCEPTION_ADDRESS, it should be a simple jump, not a jump to subroutine. For the 386, EXCEPTION_ADDRESS should be installed as an interrupt gate so that interrupts are masked while the handler runs. The gate should be at privilege level 0 (the most privileged level). The SPARC and 68k stubs are able to mask interrupts themselves without help from `exceptionHandler'. `void flush_i_cache()' On SPARC and SPARCLITE only, write this subroutine to flush the instruction cache, if any, on your target machine. If there is no instruction cache, this subroutine may be a no-op. On target machines that have instruction caches, GDB requires this function to make certain that the state of your program is stable. You must also make sure this library routine is available: `void *memset(void *, int, int)' This is the standard library function `memset' that sets an area of memory to a known value. If you have one of the free versions of `libc.a', `memset' can be found there; otherwise, you must either obtain it from your hardware manufacturer, or write your own. If you do not use the GNU C compiler, you may need other standard library subroutines as well; this varies from one stub to another, but in general the stubs are likely to use any of the common library subroutines which `gcc' generates as inline code.  File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: remote stub 17.5.3 Putting it all together ------------------------------ In summary, when your program is ready to debug, you must follow these steps. 1. Make sure you have defined the supporting low-level routines (*note What you must do for the stub: Bootstrapping.): `getDebugChar', `putDebugChar', `flush_i_cache', `memset', `exceptionHandler'. 2. Insert these lines near the top of your program: set_debug_traps(); breakpoint(); 3. For the 680x0 stub only, you need to provide a variable called `exceptionHook'. Normally you just use: void (*exceptionHook)() = 0; but if before calling `set_debug_traps', you set it to point to a function in your program, that function is called when `GDB' continues after stopping on a trap (for example, bus error). The function indicated by `exceptionHook' is called with one parameter: an `int' which is the exception number. 4. Compile and link together: your program, the GDB debugging stub for your target architecture, and the supporting subroutines. 5. Make sure you have a serial connection between your target machine and the GDB host, and identify the serial port on the host. 6. Download your program to your target machine (or get it there by whatever means the manufacturer provides), and start it. 7. Start GDB on the host, and connect to the target (*note Connecting to a remote target: Connecting.).  File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top 18 Configuration-Specific Information ************************************* While nearly all GDB commands are available for all native and cross versions of the debugger, there are some exceptions. This chapter describes things that are only available in certain configurations. There are three major categories of configurations: native configurations, where the host and target are the same, embedded operating system configurations, which are usually the same for several different processor architectures, and bare embedded processors, which are quite different from each other. * Menu: * Native:: * Embedded OS:: * Embedded Processors:: * Architectures::  File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations 18.1 Native =========== This section describes details specific to particular native configurations. * Menu: * HP-UX:: HP-UX * BSD libkvm Interface:: Debugging BSD kernel memory images * SVR4 Process Information:: SVR4 process information * DJGPP Native:: Features specific to the DJGPP port * Cygwin Native:: Features specific to the Cygwin port  File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native 18.1.1 HP-UX ------------ On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, GDB searches for a user or system name first, before it searches for a convenience variable.  File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native 18.1.2 BSD libkvm Interface --------------------------- BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory interface that provides a uniform interface for accessing kernel virtual memory images, including live systems and crash dumps. GDB uses this interface to allow you to debug live kernels and kernel crash dumps on many native BSD configurations. This is implemented as a special `kvm' debugging target. For debugging a live system, load the currently running kernel into GDB and connect to the `kvm' target: (gdb) target kvm For debugging crash dumps, provide the file name of the crash dump as an argument: (gdb) target kvm /var/crash/bsd.0 Once connected to the `kvm' target, the following commands are available: `kvm pcb' Set current context from pcb address. `kvm proc' Set current context from proc address. This command isn't available on modern FreeBSD systems.  File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native 18.1.3 SVR4 process information ------------------------------- Many versions of SVR4 provide a facility called `/proc' that can be used to examine the image of a running process using file-system subroutines. If GDB is configured for an operating system with this facility, the command `info proc' is available to report on several kinds of information about the process running your program. `info proc' works only on SVR4 systems that include the `procfs' code. This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not HP-UX or GNU/Linux, for example. `info proc' Summarize available information about the process. `info proc mappings' Report on the address ranges accessible in the program, with information on whether your program may read, write, or execute each range.  File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native 18.1.4 Features for Debugging DJGPP Programs -------------------------------------------- DJGPP is the port of GNU development tools to MS-DOS and MS-Windows. DJGPP programs are 32-bit protected-mode programs that use the "DPMI" (DOS Protected-Mode Interface) API to run on top of real-mode DOS systems and their emulations. GDB supports native debugging of DJGPP programs, and defines a few commands specific to the DJGPP port. This subsection describes those commands. `info dos' This is a prefix of DJGPP-specific commands which print information about the target system and important OS structures. `info dos sysinfo' This command displays assorted information about the underlying platform: the CPU type and features, the OS version and flavor, the DPMI version, and the available conventional and DPMI memory. `info dos gdt' `info dos ldt' `info dos idt' These 3 commands display entries from, respectively, Global, Local, and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor tables are data structures which store a descriptor for each segment that is currently in use. The segment's selector is an index into a descriptor table; the table entry for that index holds the descriptor's base address and limit, and its attributes and access rights. A typical DJGPP program uses 3 segments: a code segment, a data segment (used for both data and the stack), and a DOS segment (which allows access to DOS/BIOS data structures and absolute addresses in conventional memory). However, the DPMI host will usually define additional segments in order to support the DPMI environment. These commands allow to display entries from the descriptor tables. Without an argument, all entries from the specified table are displayed. An argument, which should be an integer expression, means display a single entry whose index is given by the argument. For example, here's a convenient way to display information about the debugged program's data segment: `(gdb) info dos ldt $ds' `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' This comes in handy when you want to see whether a pointer is outside the data segment's limit (i.e. "garbled"). `info dos pde' `info dos pte' These two commands display entries from, respectively, the Page Directory and the Page Tables. Page Directories and Page Tables are data structures which control how virtual memory addresses are mapped into physical addresses. A Page Table includes an entry for every page of memory that is mapped into the program's address space; there may be several Page Tables, each one holding up to 4096 entries. A Page Directory has up to 4096 entries, one each for every Page Table that is currently in use. Without an argument, `info dos pde' displays the entire Page Directory, and `info dos pte' displays all the entries in all of the Page Tables. An argument, an integer expression, given to the `info dos pde' command means display only that entry from the Page Directory table. An argument given to the `info dos pte' command means display entries from a single Page Table, the one pointed to by the specified entry in the Page Directory. These commands are useful when your program uses "DMA" (Direct Memory Access), which needs physical addresses to program the DMA controller. These commands are supported only with some DPMI servers. `info dos address-pte ADDR' This command displays the Page Table entry for a specified linear address. The argument linear address ADDR should already have the appropriate segment's base address added to it, because this command accepts addresses which may belong to _any_ segment. For example, here's how to display the Page Table entry for the page where the variable `i' is stored: `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' `Page Table entry for address 0x11a00d30:' `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' This says that `i' is stored at offset `0xd30' from the page whose physical base address is `0x02698000', and prints all the attributes of that page. Note that you must cast the addresses of variables to a `char *', since otherwise the value of `__djgpp_base_address', the base address of all variables and functions in a DJGPP program, will be added using the rules of C pointer arithmetics: if `i' is declared an `int', GDB will add 4 times the value of `__djgpp_base_address' to the address of `i'. Here's another example, it displays the Page Table entry for the transfer buffer: `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' `Page Table entry for address 0x29110:' `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' (The `+ 3' offset is because the transfer buffer's address is the 3rd member of the `_go32_info_block' structure.) The output of this command clearly shows that addresses in conventional memory are mapped 1:1, i.e. the physical and linear addresses are identical. This command is supported only with some DPMI servers.  File: gdb.info, Node: Cygwin Native, Prev: DJGPP Native, Up: Native 18.1.5 Features for Debugging MS Windows PE executables ------------------------------------------------------- GDB supports native debugging of MS Windows programs, including DLLs with and without symbolic debugging information. There are various additional Cygwin-specific commands, described in this subsection. The subsubsection *note Non-debug DLL symbols:: describes working with DLLs that have no debugging symbols. `info w32' This is a prefix of MS Windows specific commands which print information about the target system and important OS structures. `info w32 selector' This command displays information returned by the Win32 API `GetThreadSelectorEntry' function. It takes an optional argument that is evaluated to a long value to give the information about this given selector. Without argument, this command displays information about the the six segment registers. `info dll' This is a Cygwin specific alias of info shared. `dll-symbols' This command loads symbols from a dll similarly to add-sym command but without the need to specify a base address. `set new-console MODE' If MODE is `on' the debuggee will be started in a new console on next start. If MODE is `off'i, the debuggee will be started in the same console as the debugger. `show new-console' Displays whether a new console is used when the debuggee is started. `set new-group MODE' This boolean value controls whether the debuggee should start a new group or stay in the same group as the debugger. This affects the way the Windows OS handles Ctrl-C. `show new-group' Displays current value of new-group boolean. `set debugevents' This boolean value adds debug output concerning events seen by the debugger. `set debugexec' This boolean value adds debug output concerning execute events seen by the debugger. `set debugexceptions' This boolean value adds debug ouptut concerning exception events seen by the debugger. `set debugmemory' This boolean value adds debug ouptut concerning memory events seen by the debugger. `set shell' This boolean values specifies whether the debuggee is called via a shell or directly (default value is on). `show shell' Displays if the debuggee will be started with a shell. * Menu: * Non-debug DLL symbols:: Support for DLLs without debugging symbols  File: gdb.info, Node: Non-debug DLL symbols, Up: Cygwin Native 18.1.5.1 Support for DLLs without debugging symbols ................................................... Very often on windows, some of the DLLs that your program relies on do not include symbolic debugging information (for example, `kernel32.dll'). When GDB doesn't recognize any debugging symbols in a DLL, it relies on the minimal amount of symbolic information contained in the DLL's export table. This subsubsection describes working with such symbols, known internally to GDB as "minimal symbols". Note that before the debugged program has started execution, no DLLs will have been loaded. The easiest way around this problem is simply to start the program -- either by setting a breakpoint or letting the program run once to completion. It is also possible to force GDB to load a particular DLL before starting the executable -- see the shared library information in *note Files:: or the `dll-symbols' command in *note Cygwin Native::. Currently, explicitly loading symbols from a DLL with no debugging information will cause the symbol names to be duplicated in GDB's lookup table, which may adversely affect symbol lookup performance. 18.1.5.2 DLL name prefixes .......................... In keeping with the naming conventions used by the Microsoft debugging tools, DLL export symbols are made available with a prefix based on the DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also entered into the symbol table, so `CreateFileA' is often sufficient. In some cases there will be name clashes within a program (particularly if the executable itself includes full debugging symbols) necessitating the use of the fully qualified name when referring to the contents of the DLL. Use single-quotes around the name to avoid the exclamation mark ("!") being interpreted as a language operator. Note that the internal name of the DLL may be all upper-case, even though the file name of the DLL is lower-case, or vice-versa. Since symbols within GDB are _case-sensitive_ this may cause some confusion. If in doubt, try the `info functions' and `info variables' commands or even `maint print msymbols' (see *note Symbols::). Here's an example: (gdb) info function CreateFileA All functions matching regular expression "CreateFileA": Non-debugging symbols: 0x77e885f4 CreateFileA 0x77e885f4 KERNEL32!CreateFileA (gdb) info function ! All functions matching regular expression "!": Non-debugging symbols: 0x6100114c cygwin1!__assert 0x61004034 cygwin1!_dll_crt0@0 0x61004240 cygwin1!dll_crt0(per_process *) [etc...] 18.1.5.3 Working with minimal symbols ..................................... Symbols extracted from a DLL's export table do not contain very much type information. All that GDB can do is guess whether a symbol refers to a function or variable depending on the linker section that contains the symbol. Also note that the actual contents of the memory contained in a DLL are not available unless the program is running. This means that you cannot examine the contents of a variable or disassemble a function within a DLL without a running program. Variables are generally treated as pointers and dereferenced automatically. For this reason, it is often necessary to prefix a variable name with the address-of operator ("&") and provide explicit type information in the command. Here's an example of the type of problem: (gdb) print 'cygwin1!__argv' $1 = 268572168 (gdb) x 'cygwin1!__argv' 0x10021610: "\230y\"" And two possible solutions: (gdb) print ((char **)'cygwin1!__argv')[0] $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" (gdb) x/2x &'cygwin1!__argv' 0x610c0aa8 : 0x10021608 0x00000000 (gdb) x/x 0x10021608 0x10021608: 0x0022fd98 (gdb) x/s 0x0022fd98 0x22fd98: "/cygdrive/c/mydirectory/myprogram" Setting a break point within a DLL is possible even before the program starts execution. However, under these circumstances, GDB can't examine the initial instructions of the function in order to skip the function's frame set-up code. You can work around this by using "*&" to set the breakpoint at a raw memory address: (gdb) break *&'python22!PyOS_Readline' Breakpoint 1 at 0x1e04eff0 The author of these extensions is not entirely convinced that setting a break point within a shared DLL like `kernel32.dll' is completely safe.  File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations 18.2 Embedded Operating Systems =============================== This section describes configurations involving the debugging of embedded operating systems that are available for several different architectures. * Menu: * VxWorks:: Using GDB with VxWorks GDB includes the ability to debug programs running on various real-time operating systems.  File: gdb.info, Node: VxWorks, Up: Embedded OS 18.2.1 Using GDB with VxWorks ----------------------------- `target vxworks MACHINENAME' A VxWorks system, attached via TCP/IP. The argument MACHINENAME is the target system's machine name or IP address. On VxWorks, `load' links FILENAME dynamically on the current target system as well as adding its symbols in GDB. GDB enables developers to spawn and debug tasks running on networked VxWorks targets from a Unix host. Already-running tasks spawned from the VxWorks shell can also be debugged. GDB uses code that runs on both the Unix host and on the VxWorks target. The program `gdb' is installed and executed on the Unix host. (It may be installed with the name `vxgdb', to distinguish it from a GDB for debugging programs on the host itself.) `VxWorks-timeout ARGS' All VxWorks-based targets now support the option `vxworks-timeout'. This option is set by the user, and ARGS represents the number of seconds GDB waits for responses to rpc's. You might use this if your VxWorks target is a slow software simulator or is on the far side of a thin network line. The following information on connecting to VxWorks was current when this manual was produced; newer releases of VxWorks may use revised procedures. To use GDB with VxWorks, you must rebuild your VxWorks kernel to include the remote debugging interface routines in the VxWorks library `rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration file `configAll.h' and rebuild your VxWorks kernel. The resulting kernel contains `rdb.a', and spawns the source debugging task `tRdbTask' when VxWorks is booted. For more information on configuring and remaking VxWorks, see the manufacturer's manual. Once you have included `rdb.a' in your VxWorks system image and set your Unix execution search path to find GDB, you are ready to run GDB. From your Unix host, run `gdb' (or `vxgdb', depending on your installation). GDB comes up showing the prompt: (vxgdb) * Menu: * VxWorks Connection:: Connecting to VxWorks * VxWorks Download:: VxWorks download * VxWorks Attach:: Running tasks  File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks 18.2.1.1 Connecting to VxWorks .............................. The GDB command `target' lets you connect to a VxWorks target on the network. To connect to a target whose host name is "`tt'", type: (vxgdb) target vxworks tt GDB displays messages like these: Attaching remote machine across net... Connected to tt. GDB then attempts to read the symbol tables of any object modules loaded into the VxWorks target since it was last booted. GDB locates these files by searching the directories listed in the command search path (*note Your program's environment: Environment.); if it fails to find an object file, it displays a message such as: prog.o: No such file or directory. When this happens, add the appropriate directory to the search path with the GDB command `path', and execute the `target' command again.  File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks 18.2.1.2 VxWorks download ......................... If you have connected to the VxWorks target and you want to debug an object that has not yet been loaded, you can use the GDB `load' command to download a file from Unix to VxWorks incrementally. The object file given as an argument to the `load' command is actually opened twice: first by the VxWorks target in order to download the code, then by GDB in order to read the symbol table. This can lead to problems if the current working directories on the two systems differ. If both systems have NFS mounted the same filesystems, you can avoid these problems by using absolute paths. Otherwise, it is simplest to set the working directory on both systems to the directory in which the object file resides, and then to reference the file by its name, without any path. For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this program, type this on VxWorks: -> cd "VXPATH/vw/demo/rdb" Then, in GDB, type: (vxgdb) cd HOSTPATH/vw/demo/rdb (vxgdb) load prog.o GDB displays a response similar to this: Reading symbol data from wherever/vw/demo/rdb/prog.o... done. You can also use the `load' command to reload an object module after editing and recompiling the corresponding source file. Note that this makes GDB delete all currently-defined breakpoints, auto-displays, and convenience variables, and to clear the value history. (This is necessary in order to preserve the integrity of debugger's data structures that reference the target system's symbol table.)  File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks 18.2.1.3 Running tasks ...................... You can also attach to an existing task using the `attach' command as follows: (vxgdb) attach TASK where TASK is the VxWorks hexadecimal task ID. The task can be running or suspended when you attach to it. Running tasks are suspended at the time of attachment.  File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations 18.3 Embedded Processors ======================== This section goes into details specific to particular embedded configurations. * Menu: * ARM:: ARM * H8/300:: Renesas H8/300 * H8/500:: Renesas H8/500 * M32R/D:: Renesas M32R/D * M68K:: Motorola M68K * MIPS Embedded:: MIPS Embedded * OpenRISC 1000:: OpenRisc 1000 * PA:: HP PA Embedded * PowerPC: PowerPC * SH:: Renesas SH * Sparclet:: Tsqware Sparclet * Sparclite:: Fujitsu Sparclite * ST2000:: Tandem ST2000 * Z8000:: Zilog Z8000  File: gdb.info, Node: ARM, Next: H8/300, Up: Embedded Processors 18.3.1 ARM ---------- `target rdi DEV' ARM Angel monitor, via RDI library interface to ADP protocol. You may use this target to communicate with both boards running the Angel monitor, or with the EmbeddedICE JTAG debug device. `target rdp DEV' ARM Demon monitor.  File: gdb.info, Node: H8/300, Next: H8/500, Prev: ARM, Up: Embedded Processors 18.3.2 Renesas H8/300 --------------------- `target hms DEV' A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host. Use special commands `device' and `speed' to control the serial line and the communications speed used. `target e7000 DEV' E7000 emulator for Renesas H8 and SH. `target sh3 DEV' `target sh3e DEV' Renesas SH-3 and SH-3E target systems. When you select remote debugging to a Renesas SH, H8/300, or H8/500 board, the `load' command downloads your program to the Renesas board and also opens it as the current executable target for GDB on your host (like the `file' command). GDB needs to know these things to talk to your Renesas SH, H8/300, or H8/500: 1. that you want to use `target hms', the remote debugging interface for Renesas microprocessors, or `target e7000', the in-circuit emulator for the Renesas SH and the Renesas 300H. (`target hms' is the default when GDB is configured specifically for the Renesas SH, H8/300, or H8/500.) 2. what serial device connects your host to your Renesas board (the first serial device available on your host is the default). 3. what speed to use over the serial device. * Menu: * Renesas Boards:: Connecting to Renesas boards. * Renesas ICE:: Using the E7000 In-Circuit Emulator. * Renesas Special:: Special GDB commands for Renesas micros.  File: gdb.info, Node: Renesas Boards, Next: Renesas ICE, Up: H8/300 18.3.2.1 Connecting to Renesas boards ..................................... Use the special `GDB' command `device PORT' if you need to explicitly set the serial device. The default PORT is the first available port on your host. This is only necessary on Unix hosts, where it is typically something like `/dev/ttya'. `GDB' has another special command to set the communications speed: `speed BPS'. This command also is only used from Unix hosts; on DOS hosts, set the line speed as usual from outside GDB with the DOS `mode' command (for instance, `mode com2:9600,n,8,1,p' for a 9600bps connection). The `device' and `speed' commands are available only when you use a Unix host to debug your Renesas microprocessor programs. If you use a DOS host, GDB depends on an auxiliary terminate-and-stay-resident program called `asynctsr' to communicate with the development board through a PC serial port. You must also use the DOS `mode' command to set up the serial port on the DOS side. The following sample session illustrates the steps needed to start a program under GDB control on an H8/300. The example uses a sample H8/300 program called `t.x'. The procedure is the same for the Renesas SH and the H8/500. First hook up your development board. In this example, we use a board attached to serial port `COM2'; if you use a different serial port, substitute its name in the argument of the `mode' command. When you call `asynctsr', the auxiliary comms program used by the debugger, you give it just the numeric part of the serial port's name; for example, `asyncstr 2' below runs `asyncstr' on `COM2'. C:\H8300\TEST> asynctsr 2 C:\H8300\TEST> mode com2:9600,n,8,1,p Resident portion of MODE loaded COM2: 9600, n, 8, 1, p _Warning:_ We have noticed a bug in PC-NFS that conflicts with `asynctsr'. If you also run PC-NFS on your DOS host, you may need to disable it, or even boot without it, to use `asynctsr' to control your development board. Now that serial communications are set up, and the development board is connected, you can start up GDB. Call `gdb' with the name of your program as the argument. `GDB' prompts you, as usual, with the prompt `(gdb)'. Use two special commands to begin your debugging session: `target hms' to specify cross-debugging to the Renesas board, and the `load' command to download your program to the board. `load' displays the names of the program's sections, and a `*' for each 2K of data downloaded. (If you want to refresh GDB data on symbols or on the executable file without downloading, use the GDB commands `file' or `symbol-file'. These commands, and `load' itself, are described in *Note Commands to specify files: Files.) (eg-C:\H8300\TEST) gdb t.x GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is absolutely no warranty for GDB; type "show warranty" for details. GDB 6.3, Copyright 1992 Free Software Foundation, Inc... (gdb) target hms Connected to remote H8/300 HMS system. (gdb) load t.x .text : 0x8000 .. 0xabde *********** .data : 0xabde .. 0xad30 * .stack : 0xf000 .. 0xf014 * At this point, you're ready to run or debug your program. From here on, you can use all the usual GDB commands. The `break' command sets breakpoints; the `run' command starts your program; `print' or `x' display data; the `continue' command resumes execution after stopping at a breakpoint. You can use the `help' command at any time to find out more about GDB commands. Remember, however, that _operating system_ facilities aren't available on your development board; for example, if your program hangs, you can't send an interrupt--but you can press the RESET switch! Use the RESET button on the development board * to interrupt your program (don't use `ctl-C' on the DOS host--it has no way to pass an interrupt signal to the development board); and * to return to the GDB command prompt after your program finishes normally. The communications protocol provides no other way for GDB to detect program completion. In either case, GDB sees the effect of a RESET on the development board as a "normal exit" of your program.  File: gdb.info, Node: Renesas ICE, Next: Renesas Special, Prev: Renesas Boards, Up: H8/300 18.3.2.2 Using the E7000 in-circuit emulator ............................................ You can use the E7000 in-circuit emulator to develop code for either the Renesas SH or the H8/300H. Use one of these forms of the `target e7000' command to connect GDB to your E7000: `target e7000 PORT SPEED' Use this form if your E7000 is connected to a serial port. The PORT argument identifies what serial port to use (for example, `com2'). The third argument is the line speed in bits per second (for example, `9600'). `target e7000 HOSTNAME' If your E7000 is installed as a host on a TCP/IP network, you can just specify its hostname; GDB uses `telnet' to connect.  File: gdb.info, Node: Renesas Special, Prev: Renesas ICE, Up: H8/300 18.3.2.3 Special GDB commands for Renesas micros ................................................ Some GDB commands are available only for the H8/300: `set machine h8300' `set machine h8300h' Condition GDB for one of the two variants of the H8/300 architecture with `set machine'. You can use `show machine' to check which variant is currently in effect.  File: gdb.info, Node: H8/500, Next: M32R/D, Prev: H8/300, Up: Embedded Processors 18.3.3 H8/500 ------------- `set memory MOD' `show memory' Specify which H8/500 memory model (MOD) you are using with `set memory'; check which memory model is in effect with `show memory'. The accepted values for MOD are `small', `big', `medium', and `compact'.  File: gdb.info, Node: M32R/D, Next: M68K, Prev: H8/500, Up: Embedded Processors 18.3.4 Renesas M32R/D --------------------- `target m32r DEV' Renesas M32R/D ROM monitor. `target m32rsdi DEV' Renesas M32R SDI server, connected via parallel port to the board.  File: gdb.info, Node: M68K, Next: MIPS Embedded, Prev: M32R/D, Up: Embedded Processors 18.3.5 M68k ----------- The Motorola m68k configuration includes ColdFire support, and target command for the following ROM monitors. `target abug DEV' ABug ROM monitor for M68K. `target cpu32bug DEV' CPU32BUG monitor, running on a CPU32 (M68K) board. `target dbug DEV' dBUG ROM monitor for Motorola ColdFire. `target est DEV' EST-300 ICE monitor, running on a CPU32 (M68K) board. `target rom68k DEV' ROM 68K monitor, running on an M68K IDP board. `target rombug DEV' ROMBUG ROM monitor for OS/9000.  File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: M68K, Up: Embedded Processors 18.3.6 MIPS Embedded -------------------- GDB can use the MIPS remote debugging protocol to talk to a MIPS board attached to a serial line. This is available when you configure GDB with `--target=mips-idt-ecoff'. Use these GDB commands to specify the connection to your target board: `target mips PORT' To run a program on the board, start up `gdb' with the name of your program as the argument. To connect to the board, use the command `target mips PORT', where PORT is the name of the serial port connected to the board. If the program has not already been downloaded to the board, you may use the `load' command to download it. You can then use all the usual GDB commands. For example, this sequence connects to the target board through a serial port, and loads and runs a program called PROG through the debugger: host$ gdb PROG GDB is free software and ... (gdb) target mips /dev/ttyb (gdb) load PROG (gdb) run `target mips HOSTNAME:PORTNUMBER' On some GDB host configurations, you can specify a TCP connection (for instance, to a serial line managed by a terminal concentrator) instead of a serial port, using the syntax `HOSTNAME:PORTNUMBER'. `target pmon PORT' PMON ROM monitor. `target ddb PORT' NEC's DDB variant of PMON for Vr4300. `target lsi PORT' LSI variant of PMON. `target r3900 DEV' Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. `target array DEV' Array Tech LSI33K RAID controller board. GDB also supports these special commands for MIPS targets: `set processor ARGS' `show processor' Use the `set processor' command to set the type of MIPS processor when you want to access processor-type-specific registers. For example, `set processor R3041' tells GDB to use the CPU registers appropriate for the 3041 chip. Use the `show processor' command to see what MIPS processor GDB is using. Use the `info reg' command to see what registers GDB is using. `set mipsfpu double' `set mipsfpu single' `set mipsfpu none' `show mipsfpu' If your target board does not support the MIPS floating point coprocessor, you should use the command `set mipsfpu none' (if you need this, you may wish to put the command in your GDB init file). This tells GDB how to find the return value of functions which return floating point values. It also allows GDB to avoid saving the floating point registers when calling functions on the board. If you are using a floating point coprocessor with only single precision floating point support, as on the R4650 processor, use the command `set mipsfpu single'. The default double precision floating point coprocessor may be selected using `set mipsfpu double'. In previous versions the only choices were double precision or no floating point, so `set mipsfpu on' will select double precision and `set mipsfpu off' will select no floating point. As usual, you can inquire about the `mipsfpu' variable with `show mipsfpu'. `set remotedebug N' `show remotedebug' You can see some debugging information about communications with the board by setting the `remotedebug' variable. If you set it to `1' using `set remotedebug 1', every packet is displayed. If you set it to `2', every character is displayed. You can check the current value at any time with the command `show remotedebug'. `set timeout SECONDS' `set retransmit-timeout SECONDS' `show timeout' `show retransmit-timeout' You can control the timeout used while waiting for a packet, in the MIPS remote protocol, with the `set timeout SECONDS' command. The default is 5 seconds. Similarly, you can control the timeout used while waiting for an acknowledgement of a packet with the `set retransmit-timeout SECONDS' command. The default is 3 seconds. You can inspect both values with `show timeout' and `show retransmit-timeout'. (These commands are _only_ available when GDB is configured for `--target=mips-idt-ecoff'.) The timeout set by `set timeout' does not apply when GDB is waiting for your program to stop. In that case, GDB waits forever because it has no way of knowing how long the program is going to run before stopping.  File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors 18.3.7 OpenRISC 1000 -------------------- See OR1k Architecture document (`www.opencores.org') for more information about platform and commands. `target jtag jtag://HOST:PORT' Connects to remote JTAG server. JTAG remote server can be either an or1ksim or JTAG server, connected via parallel port to the board. Example: `target jtag jtag://localhost:9999' `or1ksim COMMAND' If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, proprietary commands can be executed. `info or1k spr' Displays spr groups. `info or1k spr GROUP' `info or1k spr GROUPNO' Displays register names in selected group. `info or1k spr GROUP REGISTER' `info or1k spr REGISTER' `info or1k spr GROUPNO REGISTERNO' `info or1k spr REGISTERNO' Shows information about specified spr register. `spr GROUP REGISTER VALUE' `spr REGISTER VALUE' `spr GROUPNO REGISTERNO VALUE' `spr REGISTERNO VALUE' Writes VALUE to specified spr register. Some implementations of OpenRISC 1000 Architecture also have hardware trace. It is very similar to GDB trace, except it does not interfere with normal program execution and is thus much faster. Hardware breakpoints/watchpoint triggers can be set using: `$LEA/$LDATA' Load effective address/data `$SEA/$SDATA' Store effective address/data `$AEA/$ADATA' Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) `$FETCH' Fetch data When triggered, it can capture low level data, like: `PC', `LSEA', `LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. `htrace' commands: `hwatch CONDITIONAL' Set hardware watchpoint on combination of Load/Store Effecive Address(es) or Data. For example: `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)' `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)' `htrace info' Display information about current HW trace configuration. `htrace trigger CONDITIONAL' Set starting criteria for HW trace. `htrace qualifier CONDITIONAL' Set acquisition qualifier for HW trace. `htrace stop CONDITIONAL' Set HW trace stopping criteria. `htrace record [DATA]*' Selects the data to be recorded, when qualifier is met and HW trace was triggered. `htrace enable' `htrace disable' Enables/disables the HW trace. `htrace rewind [FILENAME]' Clears currently recorded trace data. If filename is specified, new trace file is made and any newly collected data will be written there. `htrace print [START [LEN]]' Prints trace buffer, using current record configuration. `htrace mode continuous' Set continuous trace mode. `htrace mode suspend' Set suspend trace mode.  File: gdb.info, Node: PowerPC, Next: SH, Prev: PA, Up: Embedded Processors 18.3.8 PowerPC -------------- `target dink32 DEV' DINK32 ROM monitor. `target ppcbug DEV' `target ppcbug1 DEV' PPCBUG ROM monitor for PowerPC. `target sds DEV' SDS monitor, running on a PowerPC board (such as Motorola's ADS).  File: gdb.info, Node: PA, Next: PowerPC, Prev: OpenRISC 1000, Up: Embedded Processors 18.3.9 HP PA Embedded --------------------- `target op50n DEV' OP50N monitor, running on an OKI HPPA board. `target w89k DEV' W89K monitor, running on a Winbond HPPA board.  File: gdb.info, Node: SH, Next: Sparclet, Prev: PowerPC, Up: Embedded Processors 18.3.10 Renesas SH ------------------ `target hms DEV' A Renesas SH board attached via serial line to your host. Use special commands `device' and `speed' to control the serial line and the communications speed used. `target e7000 DEV' E7000 emulator for Renesas SH. `target sh3 DEV' `target sh3e DEV' Renesas SH-3 and SH-3E target systems.  File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: SH, Up: Embedded Processors 18.3.11 Tsqware Sparclet ------------------------ GDB enables developers to debug tasks running on Sparclet targets from a Unix host. GDB uses code that runs on both the Unix host and on the Sparclet target. The program `gdb' is installed and executed on the Unix host. `remotetimeout ARGS' GDB supports the option `remotetimeout'. This option is set by the user, and ARGS represents the number of seconds GDB waits for responses. When compiling for debugging, include the options `-g' to get debug information and `-Ttext' to relocate the program to where you wish to load it on the target. You may also want to add the options `-n' or `-N' in order to reduce the size of the sections. Example: sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N You can use `objdump' to verify that the addresses are what you intended: sparclet-aout-objdump --headers --syms prog Once you have set your Unix execution search path to find GDB, you are ready to run GDB. From your Unix host, run `gdb' (or `sparclet-aout-gdb', depending on your installation). GDB comes up showing the prompt: (gdbslet) * Menu: * Sparclet File:: Setting the file to debug * Sparclet Connection:: Connecting to Sparclet * Sparclet Download:: Sparclet download * Sparclet Execution:: Running and debugging  File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet 18.3.11.1 Setting file to debug ............................... The GDB command `file' lets you choose with program to debug. (gdbslet) file prog GDB then attempts to read the symbol table of `prog'. GDB locates the file by searching the directories listed in the command search path. If the file was compiled with debug information (option "-g"), source files will be searched as well. GDB locates the source files by searching the directories listed in the directory search path (*note Your program's environment: Environment.). If it fails to find a file, it displays a message such as: prog: No such file or directory. When this happens, add the appropriate directories to the search paths with the GDB commands `path' and `dir', and execute the `target' command again.  File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet 18.3.11.2 Connecting to Sparclet ................................ The GDB command `target' lets you connect to a Sparclet target. To connect to a target on serial port "`ttya'", type: (gdbslet) target sparclet /dev/ttya Remote target sparclet connected to /dev/ttya main () at ../prog.c:3 GDB displays messages like these: Connected to ttya.  File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet 18.3.11.3 Sparclet download ........................... Once connected to the Sparclet target, you can use the GDB `load' command to download the file from the host to the target. The file name and load offset should be given as arguments to the `load' command. Since the file format is aout, the program must be loaded to the starting address. You can use `objdump' to find out what this value is. The load offset is an offset which is added to the VMA (virtual memory address) of each of the file's sections. For instance, if the program `prog' was linked to text address 0x1201000, with data at 0x12010160 and bss at 0x12010170, in GDB, type: (gdbslet) load prog 0x12010000 Loading section .text, size 0xdb0 vma 0x12010000 If the code is loaded at a different address then what the program was linked to, you may need to use the `section' and `add-symbol-file' commands to tell GDB where to map the symbol table.  File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet 18.3.11.4 Running and debugging ............................... You can now begin debugging the task using GDB's execution control commands, `b', `step', `run', etc. See the GDB manual for the list of commands. (gdbslet) b main Breakpoint 1 at 0x12010000: file prog.c, line 3. (gdbslet) run Starting program: prog Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 3 char *symarg = 0; (gdbslet) step 4 char *execarg = "hello!"; (gdbslet)  File: gdb.info, Node: Sparclite, Next: ST2000, Prev: Sparclet, Up: Embedded Processors 18.3.12 Fujitsu Sparclite ------------------------- `target sparclite DEV' Fujitsu sparclite boards, used only for the purpose of loading. You must use an additional command to debug the program. For example: target remote DEV using GDB standard remote protocol.  File: gdb.info, Node: ST2000, Next: Z8000, Prev: Sparclite, Up: Embedded Processors 18.3.13 Tandem ST2000 --------------------- GDB may be used with a Tandem ST2000 phone switch, running Tandem's STDBUG protocol. To connect your ST2000 to the host system, see the manufacturer's manual. Once the ST2000 is physically attached, you can run: target st2000 DEV SPEED to establish it as your debugging environment. DEV is normally the name of a serial device, such as `/dev/ttya', connected to the ST2000 via a serial line. You can instead specify DEV as a TCP connection (for example, to a serial line attached via a terminal concentrator) using the syntax `HOSTNAME:PORTNUMBER'. The `load' and `attach' commands are _not_ defined for this target; you must load your program into the ST2000 as you normally would for standalone operation. GDB reads debugging information (such as symbols) from a separate, debugging version of the program available on your host computer. These auxiliary GDB commands are available to help you with the ST2000 environment: `st2000 COMMAND' Send a COMMAND to the STDBUG monitor. See the manufacturer's manual for available commands. `connect' Connect the controlling terminal to the STDBUG command monitor. When you are done interacting with STDBUG, typing either of two character sequences gets you back to the GDB command prompt: `~.' (Return, followed by tilde and period) or `~' (Return, followed by tilde and control-D).  File: gdb.info, Node: Z8000, Prev: ST2000, Up: Embedded Processors 18.3.14 Zilog Z8000 ------------------- When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 simulator. For the Z8000 family, `target sim' simulates either the Z8002 (the unsegmented variant of the Z8000 architecture) or the Z8001 (the segmented variant). The simulator recognizes which architecture is appropriate by inspecting the object code. `target sim ARGS' Debug programs on a simulated CPU. If the simulator supports setup options, specify them via ARGS. After specifying this target, you can debug programs for the simulated CPU in the same style as programs for your host computer; use the `file' command to load a new program image, the `run' command to run your program, and so on. As well as making available all the usual machine registers (*note Registers: Registers.), the Z8000 simulator provides three additional items of information as specially named registers: `cycles' Counts clock-ticks in the simulator. `insts' Counts instructions run in the simulator. `time' Execution time in 60ths of a second. You can refer to these values in GDB expressions with the usual conventions; for example, `b fputc if $cycles>5000' sets a conditional breakpoint that suspends only after at least 5000 simulated clock ticks.  File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations 18.4 Architectures ================== This section describes characteristics of architectures that affect all uses of GDB with the architecture, both native and cross. * Menu: * A29K:: * Alpha:: * MIPS::  File: gdb.info, Node: A29K, Next: Alpha, Up: Architectures 18.4.1 A29K ----------- `set rstack_high_address ADDRESS' On AMD 29000 family processors, registers are saved in a separate "register stack". There is no way for GDB to determine the extent of this stack. Normally, GDB just assumes that the stack is "large enough". This may result in GDB referencing memory locations that do not exist. If necessary, you can get around this problem by specifying the ending address of the register stack with the `set rstack_high_address' command. The argument should be an address, which you probably want to precede with `0x' to specify in hexadecimal. `show rstack_high_address' Display the current limit of the register stack, on AMD 29000 family processors.  File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures 18.4.2 Alpha ------------ See the following section.  File: gdb.info, Node: MIPS, Prev: Alpha, Up: Architectures 18.4.3 MIPS ----------- Alpha- and MIPS-based computers use an unusual stack frame, which sometimes requires GDB to search backward in the object code to find the beginning of a function. To improve response time (especially for embedded applications, where GDB may be restricted to a slow serial line for this search) you may want to limit the size of this search, using one of these commands: `set heuristic-fence-post LIMIT' Restrict GDB to examining at most LIMIT bytes in its search for the beginning of a function. A value of 0 (the default) means there is no limit. However, except for 0, the larger the limit the more bytes `heuristic-fence-post' must search and therefore the longer it takes to run. `show heuristic-fence-post' Display the current limit. These commands are available _only_ when GDB is configured for debugging programs on Alpha or MIPS processors.  File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Configurations, Up: Top 19 Controlling GDB ****************** You can alter the way GDB interacts with you by using the `set' command. For commands controlling how GDB displays data, see *Note Print settings: Print Settings. Other settings are described here. * Menu: * Prompt:: Prompt * Editing:: Command editing * History:: Command history * Screen Size:: Screen size * Numbers:: Numbers * ABI:: Configuring the current ABI * Messages/Warnings:: Optional warnings and messages * Debugging Output:: Optional messages about internal happenings  File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB 19.1 Prompt =========== GDB indicates its readiness to read a command by printing a string called the "prompt". This string is normally `(gdb)'. You can change the prompt string with the `set prompt' command. For instance, when debugging GDB with GDB, it is useful to change the prompt in one of the GDB sessions so that you can always tell which one you are talking to. _Note:_ `set prompt' does not add a space for you after the prompt you set. This allows you to set a prompt which ends in a space or a prompt that does not. `set prompt NEWPROMPT' Directs GDB to use NEWPROMPT as its prompt string henceforth. `show prompt' Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT'  File: gdb.info, Node: Editing, Next: History, Prev: Prompt, Up: Controlling GDB 19.2 Command editing ==================== GDB reads its input commands via the "Readline" interface. This GNU library provides consistent behavior for programs which provide a command line interface to the user. Advantages are GNU Emacs-style or "vi"-style inline editing of commands, `csh'-like history substitution, and a storage and recall of command history across debugging sessions. You may control the behavior of command line editing in GDB with the command `set'. `set editing' `set editing on' Enable command line editing (enabled by default). `set editing off' Disable command line editing. `show editing' Show whether command line editing is enabled. *Note Command Line Editing::, for more details about the Readline interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to read that chapter.  File: gdb.info, Node: History, Next: Screen Size, Prev: Editing, Up: Controlling GDB 19.3 Command history ==================== GDB can keep track of the commands you type during your debugging sessions, so that you can be certain of precisely what happened. Use these commands to manage the GDB command history facility. GDB uses the GNU History library, a part of the Readline package, to provide the history facility. *Note Using History Interactively::, for the detailed description of the History library. Here is the description of GDB commands related to command history. `set history filename FNAME' Set the name of the GDB command history file to FNAME. This is the file where GDB reads an initial command history list, and where it writes the command history from this session when it exits. You can access this list through history expansion or through the history command editing characters listed below. This file defaults to the value of the environment variable `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) if this variable is not set. `set history save' `set history save on' Record command history in a file, whose name may be specified with the `set history filename' command. By default, this option is disabled. `set history save off' Stop recording command history in a file. `set history size SIZE' Set the number of commands which GDB keeps in its history list. This defaults to the value of the environment variable `HISTSIZE', or to 256 if this variable is not set. History expansion assigns special meaning to the character `!'. *Note Event Designators::, for more details. Since `!' is also the logical not operator in C, history expansion is off by default. If you decide to enable history expansion with the `set history expansion on' command, you may sometimes need to follow `!' (when it is used as logical not, in an expression) with a space or a tab to prevent it from being expanded. The readline history facilities do not attempt substitution on the strings `!=' and `!(', even when history expansion is enabled. The commands to control history expansion are: `set history expansion on' `set history expansion' Enable history expansion. History expansion is off by default. `set history expansion off' Disable history expansion. `show history' `show history filename' `show history save' `show history size' `show history expansion' These commands display the state of the GDB history parameters. `show history' by itself displays all four states. `show commands' Display the last ten commands in the command history. `show commands N' Print ten commands centered on command number N. `show commands +' Print ten commands just after the commands last printed.  File: gdb.info, Node: Screen Size, Next: Numbers, Prev: History, Up: Controlling GDB 19.4 Screen size ================ Certain commands to GDB may produce large amounts of information output to the screen. To help you read all of it, GDB pauses and asks you for input at the end of each page of output. Type when you want to continue the output, or `q' to discard the remaining output. Also, the screen width setting determines when to wrap lines of output. Depending on what is being printed, GDB tries to break the line at a readable place, rather than simply letting it overflow onto the following line. Normally GDB knows the size of the screen from the terminal driver software. For example, on Unix GDB uses the termcap data base together with the value of the `TERM' environment variable and the `stty rows' and `stty cols' settings. If this is not correct, you can override it with the `set height' and `set width' commands: `set height LPP' `show height' `set width CPL' `show width' These `set' commands specify a screen height of LPP lines and a screen width of CPL characters. The associated `show' commands display the current settings. If you specify a height of zero lines, GDB does not pause during output no matter how long the output is. This is useful if output is to a file or to an editor buffer. Likewise, you can specify `set width 0' to prevent GDB from wrapping its output.  File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB 19.5 Numbers ============ You can always enter numbers in octal, decimal, or hexadecimal in GDB by the usual conventions: octal numbers begin with `0', decimal numbers end with `.', and hexadecimal numbers begin with `0x'. Numbers that begin with none of these are, by default, entered in base 10; likewise, the default display for numbers--when no particular format is specified--is base 10. You can change the default base for both input and output with the `set radix' command. `set input-radix BASE' Set the default base for numeric input. Supported choices for BASE are decimal 8, 10, or 16. BASE must itself be specified either unambiguously or using the current default radix; for example, any of set radix 012 set radix 10. set radix 0xa sets the base to decimal. On the other hand, `set radix 10' leaves the radix unchanged no matter what it was. `set output-radix BASE' Set the default base for numeric display. Supported choices for BASE are decimal 8, 10, or 16. BASE must itself be specified either unambiguously or using the current default radix. `show input-radix' Display the current default base for numeric input. `show output-radix' Display the current default base for numeric display.  File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB 19.6 Configuring the current ABI ================================ GDB can determine the "ABI" (Application Binary Interface) of your application automatically. However, sometimes you need to override its conclusions. Use these commands to manage GDB's view of the current ABI. One GDB configuration can debug binaries for multiple operating system targets, either via remote debugging or native emulation. GDB will autodetect the "OS ABI" (Operating System ABI) in use, but you can override its conclusion using the `set osabi' command. One example where this is useful is in debugging of binaries which use an alternate C library (e.g. UCLIBC for GNU/Linux) which does not have the same identifying marks that the standard C library for your platform provides. `show osabi' Show the OS ABI currently in use. `set osabi' With no argument, show the list of registered available OS ABI's. `set osabi ABI' Set the current OS ABI to ABI. Generally, the way that an argument of type `float' is passed to a function depends on whether the function is prototyped. For a prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed unchanged, according to the architecture's convention for `float'. For unprototyped (i.e. K&R style) functions, `float' arguments are first promoted to type `double' and then passed. Unfortunately, some forms of debug information do not reliably indicate whether a function is prototyped. If GDB calls a function that is not marked as prototyped, it consults `set coerce-float-to-double'. `set coerce-float-to-double' `set coerce-float-to-double on' Arguments of type `float' will be promoted to `double' when passed to an unprototyped function. This is the default setting. `set coerce-float-to-double off' Arguments of type `float' will be passed directly to unprototyped functions. GDB needs to know the ABI used for your program's C++ objects. The correct C++ ABI depends on which C++ compiler was used to build your application. GDB only fully supports programs with a single C++ ABI; if your program contains code using multiple C++ ABI's or if GDB can not identify your program's ABI correctly, you can tell GDB which ABI to use. Currently supported ABI's include "gnu-v2", for `g++' versions before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or "gnu-v3" ABI's as well. The default setting is "auto". `show cp-abi' Show the C++ ABI currently in use. `set cp-abi' With no argument, show the list of supported C++ ABI's. `set cp-abi ABI' `set cp-abi auto' Set the current C++ ABI to ABI, or return to automatic detection.  File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB 19.7 Optional warnings and messages =================================== By default, GDB is silent about its inner workings. If you are running on a slow machine, you may want to use the `set verbose' command. This makes GDB tell you when it does a lengthy internal operation, so you will not think it has crashed. Currently, the messages controlled by `set verbose' are those which announce that the symbol table for a source file is being read; see `symbol-file' in *Note Commands to specify files: Files. `set verbose on' Enables GDB output of certain informational messages. `set verbose off' Disables GDB output of certain informational messages. `show verbose' Displays whether `set verbose' is on or off. By default, if GDB encounters bugs in the symbol table of an object file, it is silent; but if you are debugging a compiler, you may find this information useful (*note Errors reading symbol files: Symbol Errors.). `set complaints LIMIT' Permits GDB to output LIMIT complaints about each type of unusual symbols before becoming silent about the problem. Set LIMIT to zero to suppress all complaints; set it to a large number to prevent complaints from being suppressed. `show complaints' Displays how many symbol complaints GDB is permitted to produce. By default, GDB is cautious, and asks what sometimes seems to be a lot of stupid questions to confirm certain commands. For example, if you try to run a program which is already running: (gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) If you are willing to unflinchingly face the consequences of your own commands, you can disable this "feature": `set confirm off' Disables confirmation requests. `set confirm on' Enables confirmation requests (the default). `show confirm' Displays state of confirmation requests.  File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB 19.8 Optional messages about internal happenings ================================================ `set debug arch' Turns on or off display of gdbarch debugging info. The default is off `show debug arch' Displays the current state of displaying gdbarch debugging info. `set debug event' Turns on or off display of GDB event debugging info. The default is off. `show debug event' Displays the current state of displaying GDB event debugging info. `set debug expression' Turns on or off display of GDB expression debugging info. The default is off. `show debug expression' Displays the current state of displaying GDB expression debugging info. `set debug frame' Turns on or off display of GDB frame debugging info. The default is off. `show debug frame' Displays the current state of displaying GDB frame debugging info. `set debug observer' Turns on or off display of GDB observer debugging. This includes info such as the notification of observable events. `show debug observer' Displays the current state of observer debugging. `set debug overload' Turns on or off display of GDB C++ overload debugging info. This includes info such as ranking of functions, etc. The default is off. `show debug overload' Displays the current state of displaying GDB C++ overload debugging info. `set debug remote' Turns on or off display of reports on all packets sent back and forth across the serial line to the remote machine. The info is printed on the GDB standard output stream. The default is off. `show debug remote' Displays the state of display of remote packets. `set debug serial' Turns on or off display of GDB serial debugging info. The default is off. `show debug serial' Displays the current state of displaying GDB serial debugging info. `set debug target' Turns on or off display of GDB target debugging info. This info includes what is going on at the target level of GDB, as it happens. The default is 0. Set it to 1 to track events, and to 2 to also track the value of large memory transfers. Changes to this flag do not take effect until the next time you connect to a target or use the `run' command. `show debug target' Displays the current state of displaying GDB target debugging info. `set debug varobj' Turns on or off display of GDB variable object debugging info. The default is off. `show debug varobj' Displays the current state of displaying GDB variable object debugging info.  File: gdb.info, Node: Sequences, Next: TUI, Prev: Controlling GDB, Up: Top 20 Canned Sequences of Commands ******************************* Aside from breakpoint commands (*note Breakpoint command lists: Break Commands.), GDB provides two ways to store sequences of commands for execution as a unit: user-defined commands and command files. * Menu: * Define:: User-defined commands * Hooks:: User-defined command hooks * Command Files:: Command files * Output:: Commands for controlled output  File: gdb.info, Node: Define, Next: Hooks, Up: Sequences 20.1 User-defined commands ========================== A "user-defined command" is a sequence of GDB commands to which you assign a new name as a command. This is done with the `define' command. User commands may accept up to 10 arguments separated by whitespace. Arguments are accessed within the user command via $ARG0...$ARG9. A trivial example: define adder print $arg0 + $arg1 + $arg2 To execute the command use: adder 1 2 3 This defines the command `adder', which prints the sum of its three arguments. Note the arguments are text substitutions, so they may reference variables, use complex expressions, or even perform inferior functions calls. `define COMMANDNAME' Define a command named COMMANDNAME. If there is already a command by that name, you are asked to confirm that you want to redefine it. The definition of the command is made up of other GDB command lines, which are given following the `define' command. The end of these commands is marked by a line containing `end'. `if' Takes a single argument, which is an expression to evaluate. It is followed by a series of commands that are executed only if the expression is true (nonzero). There can then optionally be a line `else', followed by a series of commands that are only executed if the expression was false. The end of the list is marked by a line containing `end'. `while' The syntax is similar to `if': the command takes a single argument, which is an expression to evaluate, and must be followed by the commands to execute, one per line, terminated by an `end'. The commands are executed repeatedly as long as the expression evaluates to true. `document COMMANDNAME' Document the user-defined command COMMANDNAME, so that it can be accessed by `help'. The command COMMANDNAME must already be defined. This command reads lines of documentation just as `define' reads the lines of the command definition, ending with `end'. After the `document' command is finished, `help' on command COMMANDNAME displays the documentation you have written. You may use the `document' command again to change the documentation of a command. Redefining the command with `define' does not change the documentation. `help user-defined' List all user-defined commands, with the first line of the documentation (if any) for each. `show user' `show user COMMANDNAME' Display the GDB commands used to define COMMANDNAME (but not its documentation). If no COMMANDNAME is given, display the definitions for all user-defined commands. `show max-user-call-depth' `set max-user-call-depth' The value of `max-user-call-depth' controls how many recursion levels are allowed in user-defined commands before GDB suspects an infinite recursion and aborts the command. When user-defined commands are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command. If used interactively, commands that would ask for confirmation proceed without asking when used inside a user-defined command. Many GDB commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.  File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences 20.2 User-defined command hooks =============================== You may define "hooks", which are a special kind of user-defined command. Whenever you run the command `foo', if the user-defined command `hook-foo' exists, it is executed (with no arguments) before that command. A hook may also be defined which is run after the command you executed. Whenever you run the command `foo', if the user-defined command `hookpost-foo' exists, it is executed (with no arguments) after that command. Post-execution hooks may exist simultaneously with pre-execution hooks, for the same command. It is valid for a hook to call the command which it hooks. If this occurs, the hook is not re-executed, thereby avoiding infinte recursion. In addition, a pseudo-command, `stop' exists. Defining (`hook-stop') makes the associated commands execute every time execution stops in your program: before breakpoint commands are run, displays are printed, or the stack frame is printed. For example, to ignore `SIGALRM' signals while single-stepping, but treat them normally during normal execution, you could define: define hook-stop handle SIGALRM nopass end define hook-run handle SIGALRM pass end define hook-continue handle SIGLARM pass end As a further example, to hook at the begining and end of the `echo' command, and to add extra text to the beginning and end of the message, you could define: define hook-echo echo <<<--- end define hookpost-echo echo --->>>\n end (gdb) echo Hello World <<<---Hello World--->>> (gdb) You can define a hook for any single-word command in GDB, but not for command aliases; you should define a hook for the basic command name, e.g. `backtrace' rather than `bt'. If an error occurs during the execution of your hook, execution of GDB commands stops and GDB issues a prompt (before the command that you actually typed had a chance to run). If you try to define a hook which does not match any known command, you get a warning from the `define' command.  File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences 20.3 Command files ================== A command file for GDB is a file of lines that are GDB commands. Comments (lines starting with `#') may also be included. An empty line in a command file does nothing; it does not mean to repeat the last command, as it would from the terminal. When you start GDB, it automatically executes commands from its "init files", normally called `.gdbinit'(1). During startup, GDB does the following: 1. Reads the init file (if any) in your home directory(2). 2. Processes command line options and operands. 3. Reads the init file (if any) in the current working directory. 4. Reads command files specified by the `-x' option. The init file in your home directory can set options (such as `set complaints') that affect subsequent processing of command line options and operands. Init files are not executed if you use the `-nx' option (*note Choosing modes: Mode Options.). On some configurations of GDB, the init file is known by a different name (these are typically environments where a specialized form of GDB may need to coexist with other forms, hence a different name for the specialized version's init file). These are the environments with special init file names: * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' You can also request the execution of a command file with the `source' command: `source FILENAME' Execute the command file FILENAME. The lines in a command file are executed sequentially. They are not printed as they are executed. An error in any command terminates execution of the command file and control is returned to the console. Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many GDB commands that normally print messages to say what they are doing omit the messages when called from command files. GDB also accepts command input from standard input. In this mode, normal output goes to standard output and error output goes to standard error. Errors in a command file supplied on standard input do not terminate execution of the command file -- execution continues with the next command. gdb < cmds > log 2>&1 (The syntax above will vary depending on the shell used.) This example will execute commands from the file `cmds'. All output and errors would be directed to `log'. ---------- Footnotes ---------- (1) The DJGPP port of GDB uses the name `gdb.ini' instead, due to the limitations of file names imposed by DOS filesystems. (2) On DOS/Windows systems, the home directory is the one pointed to by the `HOME' environment variable.  File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences 20.4 Commands for controlled output =================================== During the execution of a command file or a user-defined command, normal GDB output is suppressed; the only output that appears is what is explicitly printed by the commands in the definition. This section describes three commands useful for generating exactly the output you want. `echo TEXT' Print TEXT. Nonprinting characters can be included in TEXT using C escape sequences, such as `\n' to print a newline. *No newline is printed unless you specify one.* In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for displaying a string with spaces at the beginning or the end, since leading and trailing spaces are otherwise trimmed from all arguments. To print ` and foo = ', use the command `echo \ and foo = \ '. A backslash at the end of TEXT can be used, as in C, to continue the command onto subsequent lines. For example, echo This is some text\n\ which is continued\n\ onto several lines.\n produces the same output as echo This is some text\n echo which is continued\n echo onto several lines.\n `output EXPRESSION' Print the value of EXPRESSION and nothing but that value: no newlines, no `$NN = '. The value is not entered in the value history either. *Note Expressions: Expressions, for more information on expressions. `output/FMT EXPRESSION' Print the value of EXPRESSION in format FMT. You can use the same formats as for `print'. *Note Output formats: Output Formats, for more information. `printf STRING, EXPRESSIONS...' Print the values of the EXPRESSIONS under the control of STRING. The EXPRESSIONS are separated by commas and may be either numbers or pointers. Their values are printed as specified by STRING, exactly as if your program were to execute the C subroutine printf (STRING, EXPRESSIONS...); For example, you can print two values in hex like this: printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo The only backslash-escape sequences that you can use in the format string are the simple ones that consist of backslash followed by a letter.  File: gdb.info, Node: Interpreters, Next: Emacs, Prev: TUI, Up: Top 21 Command Interpreters *********************** GDB supports multiple command interpreters, and some command infrastructure to allow users or user interface writers to switch between interpreters or run commands in other interpreters. GDB currently supports two command interpreters, the console interpreter (sometimes called the command-line interpreter or CLI) and the machine interface interpreter (or GDB/MI). This manual describes both of these interfaces in great detail. By default, GDB will start with the console interpreter. However, the user may choose to start GDB with another interpreter by specifying the `-i' or `--interpreter' startup options. Defined interpreters include: `console' The traditional console or command-line interpreter. This is the most often used interpreter with GDB. With no interpreter specified at runtime, GDB will use this interpreter. `mi' The newest GDB/MI interface (currently `mi2'). Used primarily by programs wishing to use GDB as a backend for a debugger GUI or an IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. `mi2' The current GDB/MI interface. `mi1' The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. The interpreter being used by GDB may not be dynamically switched at runtime. Although possible, this could lead to a very precarious situation. Consider an IDE using GDB/MI. If a user enters the command "interpreter-set console" in a console view, GDB would switch to using the console interpreter, rendering the IDE inoperable! Although you may only choose a single interpreter at startup, you may execute commands in any interpreter from the current interpreter using the appropriate command. If you are running the console interpreter, simply use the `interpreter-exec' command: interpreter-exec mi "-data-list-register-names" GDB/MI has a similar command, although it is only available in versions of GDB which support GDB/MI version 2 (or greater).  File: gdb.info, Node: TUI, Next: Interpreters, Prev: Sequences, Up: Top 22 GDB Text User Interface ************************** * Menu: * TUI Overview:: TUI overview * TUI Keys:: TUI key bindings * TUI Single Key Mode:: TUI single key mode * TUI Commands:: TUI specific commands * TUI Configuration:: TUI configuration variables The GDB Text User Interface, TUI in short, is a terminal interface which uses the `curses' library to show the source file, the assembly output, the program registers and GDB commands in separate text windows. The TUI is enabled by invoking GDB using either `gdbtui' or `gdb -tui'.  File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI 22.1 TUI overview ================= The TUI has two display modes that can be switched while GDB runs: * A curses (or TUI) mode in which it displays several text windows on the terminal. * A standard mode which corresponds to the GDB configured without the TUI. In the TUI mode, GDB can display several text window on the terminal: _command_ This window is the GDB command window with the GDB prompt and the GDB outputs. The GDB input is still managed using readline but through the TUI. The _command_ window is always visible. _source_ The source window shows the source file of the program. The current line as well as active breakpoints are displayed in this window. _assembly_ The assembly window shows the disassembly output of the program. _register_ This window shows the processor registers. It detects when a register is changed and when this is the case, registers that have changed are highlighted. The source and assembly windows show the current program position by highlighting the current line and marking them with the `>' marker. Breakpoints are also indicated with two markers. A first one indicates the breakpoint type: `B' Breakpoint which was hit at least once. `b' Breakpoint which was never hit. `H' Hardware breakpoint which was hit at least once. `h' Hardware breakpoint which was never hit. The second marker indicates whether the breakpoint is enabled or not: `+' Breakpoint is enabled. `-' Breakpoint is disabled. The source, assembly and register windows are attached to the thread and the frame position. They are updated when the current thread changes, when the frame changes or when the program counter changes. These three windows are arranged by the TUI according to several layouts. The layout defines which of these three windows are visible. The following layouts are available: * source * assembly * source and assembly * source and registers * assembly and registers On top of the command window a status line gives various information concerning the current process begin debugged. The status line is updated when the information it shows changes. The following fields are displayed: _target_ Indicates the current gdb target (*note Specifying a Debugging Target: Targets.). _process_ Gives information about the current process or thread number. When no process is being debugged, this field is set to `No process'. _function_ Gives the current function name for the selected frame. The name is demangled if demangling is turned on (*note Print Settings::). When there is no symbol corresponding to the current program counter the string `??' is displayed. _line_ Indicates the current line number for the selected frame. When the current line number is not known the string `??' is displayed. _pc_ Indicates the current program counter address.  File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI 22.2 TUI Key Bindings ===================== The TUI installs several key bindings in the readline keymaps (*note Command Line Editing::). They allow to leave or enter in the TUI mode or they operate directly on the TUI layout and windows. The TUI also provides a _SingleKey_ keymap which binds several keys directly to GDB commands. The following key bindings are installed for both TUI mode and the GDB standard mode. `C-x C-a' `C-x a' `C-x A' Enter or leave the TUI mode. When the TUI mode is left, the curses window management is left and GDB operates using its standard mode writing on the terminal directly. When the TUI mode is entered, the control is given back to the curses windows. The screen is then refreshed. `C-x 1' Use a TUI layout with only one window. The layout will either be `source' or `assembly'. When the TUI mode is not active, it will switch to the TUI mode. Think of this key binding as the Emacs `C-x 1' binding. `C-x 2' Use a TUI layout with at least two windows. When the current layout shows already two windows, a next layout with two windows is used. When a new layout is chosen, one window will always be common to the previous layout and the new one. Think of it as the Emacs `C-x 2' binding. `C-x o' Change the active window. The TUI associates several key bindings (like scrolling and arrow keys) to the active window. This command gives the focus to the next TUI window. Think of it as the Emacs `C-x o' binding. `C-x s' Use the TUI _SingleKey_ keymap that binds single key to gdb commands (*note TUI Single Key Mode::). The following key bindings are handled only by the TUI mode: Scroll the active window one page up. Scroll the active window one page down. Scroll the active window one line up. Scroll the active window one line down. Scroll the active window one column left. Scroll the active window one column right. Refresh the screen. In the TUI mode, the arrow keys are used by the active window for scrolling. This means they are available for readline when the active window is the command window. When the command window does not have the focus, it is necessary to use other readline key bindings such as , , and .  File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI 22.3 TUI Single Key Mode ======================== The TUI provides a _SingleKey_ mode in which it installs a particular key binding in the readline keymaps to connect single keys to some gdb commands. `c' continue `d' down `f' finish `n' next `q' exit the _SingleKey_ mode. `r' run `s' step `u' up `v' info locals `w' where Other keys temporarily switch to the GDB command prompt. The key that was pressed is inserted in the editing buffer so that it is possible to type most GDB commands without interaction with the TUI _SingleKey_ mode. Once the command is entered the TUI _SingleKey_ mode is restored. The only way to permanently leave this mode is by hitting or ` '.  File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI 22.4 TUI specific commands ========================== The TUI has specific commands to control the text windows. These commands are always available, that is they do not depend on the current terminal mode in which GDB runs. When GDB is in the standard mode, using these commands will automatically switch in the TUI mode. `info win' List and give the size of all displayed windows. `layout next' Display the next layout. `layout prev' Display the previous layout. `layout src' Display the source window only. `layout asm' Display the assembly window only. `layout split' Display the source and assembly window. `layout regs' Display the register window together with the source or assembly window. `focus next | prev | src | asm | regs | split' Set the focus to the named window. This command allows to change the active window so that scrolling keys can be affected to another window. `refresh' Refresh the screen. This is similar to using key. `tui reg float' Show the floating point registers in the register window. `tui reg general' Show the general registers in the register window. `tui reg next' Show the next register group. The list of register groups as well as their order is target specific. The predefined register groups are the following: `general', `float', `system', `vector', `all', `save', `restore'. `tui reg system' Show the system registers in the register window. `update' Update the source window and the current execution point. `winheight NAME +COUNT' `winheight NAME -COUNT' Change the height of the window NAME by COUNT lines. Positive counts increase the height, while negative counts decrease it.  File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI 22.5 TUI configuration variables ================================ The TUI has several configuration variables that control the appearance of windows on the terminal. `set tui border-kind KIND' Select the border appearance for the source, assembly and register windows. The possible values are the following: `space' Use a space character to draw the border. `ascii' Use ascii characters + - and | to draw the border. `acs' Use the Alternate Character Set to draw the border. The border is drawn using character line graphics if the terminal supports them. `set tui active-border-mode MODE' Select the attributes to display the border of the active window. The possible values are `normal', `standout', `reverse', `half', `half-standout', `bold' and `bold-standout'. `set tui border-mode MODE' Select the attributes to display the border of other windows. The MODE can be one of the following: `normal' Use normal attributes to display the border. `standout' Use standout mode. `reverse' Use reverse video mode. `half' Use half bright mode. `half-standout' Use half bright and standout mode. `bold' Use extra bright or bold mode. `bold-standout' Use extra bright or bold and standout mode.  File: gdb.info, Node: Emacs, Next: Annotations, Prev: Interpreters, Up: Top 23 Using GDB under GNU Emacs **************************** A special interface allows you to use GNU Emacs to view (and edit) the source files for the program you are debugging with GDB. To use this interface, use the command `M-x gdb' in Emacs. Give the executable file you want to debug as an argument. This command starts GDB as a subprocess of Emacs, with input and output through a newly created Emacs buffer. Using GDB under Emacs is just like using GDB normally except for two things: * All "terminal" input and output goes through the Emacs buffer. This applies both to GDB commands and their output, and to the input and output done by the program you are debugging. This is useful because it means that you can copy the text of previous commands and input them again; you can even use parts of the output in this way. All the facilities of Emacs' Shell mode are available for interacting with your program. In particular, you can send signals the usual way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop. * GDB displays source code through Emacs. Each time GDB displays a stack frame, Emacs automatically finds the source file for that frame and puts an arrow (`=>') at the left margin of the current line. Emacs uses a separate buffer for source display, and splits the screen to show both your GDB session and the source. Explicit GDB `list' or search commands still produce output as usual, but you probably have no reason to use them from Emacs. If you specify an absolute file name when prompted for the `M-x gdb' argument, then Emacs sets your current working directory to where your program resides. If you only specify the file name, then Emacs sets your current working directory to to the directory associated with the previous buffer. In this case, GDB may find your program by searching your environment's `PATH' variable, but on some operating systems it might not find the source. So, although the GDB input and output session proceeds normally, the auxiliary buffer does not display the current source and line of execution. The initial working directory of GDB is printed on the top line of the GDB I/O buffer and this serves as a default for the commands that specify files for GDB to operate on. *Note Commands to specify files: Files. By default, `M-x gdb' calls the program called `gdb'. If you need to call GDB by a different name (for example, if you keep several configurations around, with different names) you can customize the Emacs variable `gud-gdb-command-name' to run the one you want. In the GDB I/O buffer, you can use these special Emacs commands in addition to the standard Shell mode commands: `C-h m' Describe the features of Emacs' GDB Mode. `C-c C-s' Execute to another source line, like the GDB `step' command; also update the display window to show the current file and location. `C-c C-n' Execute to next source line in this function, skipping all function calls, like the GDB `next' command. Then update the display window to show the current file and location. `C-c C-i' Execute one instruction, like the GDB `stepi' command; update display window accordingly. `C-c C-f' Execute until exit from the selected stack frame, like the GDB `finish' command. `C-c C-r' Continue execution of your program, like the GDB `continue' command. `C-c <' Go up the number of frames indicated by the numeric argument (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' command. `C-c >' Go down the number of frames indicated by the numeric argument, like the GDB `down' command. In any source file, the Emacs command `C-x SPC' (`gud-break') tells GDB to set a breakpoint on the source line point is on. If you type `M-x speedbar', then Emacs displays a separate frame which shows a backtrace when the GDB I/O buffer is current. Move point to any frame in the stack and type to make it become the current frame and display the associated source in the source buffer. Alternatively, click `Mouse-2' to make the selected frame become the current one. If you accidentally delete the source-display buffer, an easy way to get it back is to type the command `f' in the GDB buffer, to request a frame display; when you run under Emacs, this recreates the source buffer if necessary to show you the context of the current frame. The source files displayed in Emacs are in ordinary Emacs buffers which are visiting the source files in the usual way. You can edit the files with these buffers if you wish; but keep in mind that GDB communicates with Emacs in terms of line numbers. If you add or delete lines from the text, the line numbers that GDB knows cease to correspond properly with the code. The description given here is for GNU Emacs version 21.3 and a more detailed description of its interaction with GDB is given in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).  File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top 24 The GDB/MI Interface *********************** Function and Purpose ==================== GDB/MI is a line based machine oriented text interface to GDB. It is specifically intended to support the development of systems which use the debugger as just one small component of a larger system. This chapter is a specification of the GDB/MI interface. It is written in the form of a reference manual. Note that GDB/MI is still under construction, so some of the features described below are incomplete and subject to change. Notation and Terminology ======================== This chapter uses the following notation: * `|' separates two alternatives. * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or may not be given. * `( GROUP )*' means that GROUP inside the parentheses may repeat zero or more times. * `( GROUP )+' means that GROUP inside the parentheses may repeat one or more times. * `"STRING"' means a literal STRING. Acknowledgments =============== In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and Elena Zannoni. * Menu: * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: * GDB/MI Output Records:: * GDB/MI Command Description Format:: * GDB/MI Breakpoint Table Commands:: * GDB/MI Data Manipulation:: * GDB/MI Program Control:: * GDB/MI Miscellaneous Commands:: * GDB/MI Stack Manipulation:: * GDB/MI Symbol Query:: * GDB/MI Target Manipulation:: * GDB/MI Thread Commands:: * GDB/MI Tracepoint Commands:: * GDB/MI Variable Objects::  File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI 24.1 GDB/MI Command Syntax ========================== * Menu: * GDB/MI Input Syntax:: * GDB/MI Output Syntax:: * GDB/MI Simple Examples::  File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax 24.1.1 GDB/MI Input Syntax -------------------------- `COMMAND ==>' `CLI-COMMAND | MI-COMMAND' `CLI-COMMAND ==>' `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB CLI command. `MI-COMMAND ==>' `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " PARAMETER )* NL' `TOKEN ==>' "any sequence of digits" `OPTION ==>' `"-" PARAMETER [ " " PARAMETER ]' `PARAMETER ==>' `NON-BLANK-SEQUENCE | C-STRING' `OPERATION ==>' _any of the operations described in this chapter_ `NON-BLANK-SEQUENCE ==>' _anything, provided it doesn't contain special characters such as "-", NL, """ and of course " "_ `C-STRING ==>' `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' `NL ==>' `CR | CR-LF' Notes: * The CLI commands are still handled by the MI interpreter; their output is described below. * The `TOKEN', when present, is passed back when the command finishes. * Some MI commands accept optional arguments as part of the parameter list. Each option is identified by a leading `-' (dash) and may be followed by an optional argument parameter. Options occur first in the parameter list and can be delimited from normal parameters using `--' (this is useful when some parameters begin with a dash). Pragmatics: * We want easy access to the existing CLI syntax (for debugging). * We want it to be easy to spot a MI operation.  File: gdb.info, Node: GDB/MI Output Syntax, Next: GDB/MI Simple Examples, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax 24.1.2 GDB/MI Output Syntax --------------------------- The output from GDB/MI consists of zero or more out-of-band records followed, optionally, by a single result record. This result record is for the most recent command. The sequence of output records is terminated by `(gdb)'. If an input command was prefixed with a `TOKEN' then the corresponding output for that command will also be prefixed by that same TOKEN. `OUTPUT ==>' `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' `RESULT-RECORD ==>' ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' `OUT-OF-BAND-RECORD ==>' `ASYNC-RECORD | STREAM-RECORD' `ASYNC-RECORD ==>' `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' `EXEC-ASYNC-OUTPUT ==>' `[ TOKEN ] "*" ASYNC-OUTPUT' `STATUS-ASYNC-OUTPUT ==>' `[ TOKEN ] "+" ASYNC-OUTPUT' `NOTIFY-ASYNC-OUTPUT ==>' `[ TOKEN ] "=" ASYNC-OUTPUT' `ASYNC-OUTPUT ==>' `ASYNC-CLASS ( "," RESULT )* NL' `RESULT-CLASS ==>' `"done" | "running" | "connected" | "error" | "exit"' `ASYNC-CLASS ==>' `"stopped" | OTHERS' (where OTHERS will be added depending on the needs--this is still in development). `RESULT ==>' ` VARIABLE "=" VALUE' `VARIABLE ==>' ` STRING ' `VALUE ==>' ` CONST | TUPLE | LIST ' `CONST ==>' `C-STRING' `TUPLE ==>' ` "{}" | "{" RESULT ( "," RESULT )* "}" ' `LIST ==>' ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* "]" ' `STREAM-RECORD ==>' `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' `CONSOLE-STREAM-OUTPUT ==>' `"~" C-STRING' `TARGET-STREAM-OUTPUT ==>' `"@" C-STRING' `LOG-STREAM-OUTPUT ==>' `"&" C-STRING' `NL ==>' `CR | CR-LF' `TOKEN ==>' _any sequence of digits_. Notes: * All output sequences end in a single line containing a period. * The `TOKEN' is from the corresponding request. If an execution command is interrupted by the `-exec-interrupt' command, the TOKEN associated with the `*stopped' message is the one of the original execution command, not the one of the interrupt command. * STATUS-ASYNC-OUTPUT contains on-going status information about the progress of a slow operation. It can be discarded. All status output is prefixed by `+'. * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target (stopped, started, disappeared). All async output is prefixed by `*'. * NOTIFY-ASYNC-OUTPUT contains supplementary information that the client should handle (e.g., a new breakpoint information). All notify output is prefixed by `='. * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in the console. It is the textual response to a CLI command. All the console output is prefixed by `~'. * TARGET-STREAM-OUTPUT is the output produced by the target program. All the target output is prefixed by `@'. * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for instance messages that should be displayed as part of an error log. All the log output is prefixed by `&'. * New GDB/MI commands should only output LISTS containing VALUES. *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details about the various output records.  File: gdb.info, Node: GDB/MI Simple Examples, Prev: GDB/MI Output Syntax, Up: GDB/MI Command Syntax 24.1.3 Simple Examples of GDB/MI Interaction -------------------------------------------- This subsection presents several simple examples of interaction using the GDB/MI interface. In these examples, `->' means that the following line is passed to GDB/MI as input, while `<-' means the output received from GDB/MI. Target Stop ........... Here's an example of stopping the inferior process: -> -stop <- (gdb) and later: <- *stop,reason="stop",address="0x123",source="a.c:123" <- (gdb) Simple CLI Command .................. Here's an example of a simple CLI command being passed through GDB/MI and on to the CLI. -> print 1+2 <- &"print 1+2\n" <- ~"$1 = 3\n" <- ^done <- (gdb) Command With Side Effects ......................... -> -symbol-file xyz.exe <- *breakpoint,nr="3",address="0x123",source="a.c:123" <- (gdb) A Bad Command ............. Here's what happens if you pass a non-existent command: -> -rubbish <- ^error,msg="Undefined MI command: rubbish" <- (gdb)  File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Output Records, Prev: GDB/MI Command Syntax, Up: GDB/MI 24.2 GDB/MI Compatibility with CLI ================================== To help users familiar with GDB's existing CLI interface, GDB/MI accepts existing CLI commands. As specified by the syntax, such commands can be directly entered into the GDB/MI interface and GDB will respond. This mechanism is provided as an aid to developers of GDB/MI clients and not as a reliable interface into the CLI. Since the command is being interpreteted in an environment that assumes GDB/MI behaviour, the exact output of such commands is likely to end up being an un-supported hybrid of GDB/MI and CLI output.  File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Command Description Format, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI 24.3 GDB/MI Output Records ========================== * Menu: * GDB/MI Result Records:: * GDB/MI Stream Records:: * GDB/MI Out-of-band Records::  File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records 24.3.1 GDB/MI Result Records ---------------------------- In addition to a number of out-of-band notifications, the response to a GDB/MI command includes one of the following result indications: `"^done" [ "," RESULTS ]' The synchronous operation was successful, `RESULTS' are the return values. `"^running"' The asynchronous operation was successfully started. The target is running. `"^error" "," C-STRING' The operation failed. The `C-STRING' contains the corresponding error message.  File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records 24.3.2 GDB/MI Stream Records ---------------------------- GDB internally maintains a number of output streams: the console, the target, and the log. The output intended for each of these streams is funneled through the GDB/MI interface using "stream records". Each stream record begins with a unique "prefix character" which identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output Syntax.). In addition to the prefix, each stream record contains a `STRING-OUTPUT'. This is either raw text (with an implicit new line) or a quoted C string (which does not contain an implicit newline). `"~" STRING-OUTPUT' The console output stream contains text that should be displayed in the CLI console window. It contains the textual responses to CLI commands. `"@" STRING-OUTPUT' The target output stream contains any textual output from the running target. `"&" STRING-OUTPUT' The log stream contains debugging messages being produced by GDB's internals.  File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records 24.3.3 GDB/MI Out-of-band Records --------------------------------- "Out-of-band" records are used to notify the GDB/MI client of additional changes that have occurred. Those changes can either be a consequence of GDB/MI (e.g., a breakpoint modified) or a result of target activity (e.g., target stopped). The following is a preliminary list of possible out-of-band records. `"*" "stop"'  File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Table Commands, Prev: GDB/MI Output Records, Up: GDB/MI 24.4 GDB/MI Command Description Format ====================================== The remaining sections describe blocks of commands. Each block of commands is laid out in a fashion similar to this section. Note the the line breaks shown in the examples are here only for readability. They don't appear in the real output. Also note that the commands with a non-available example (N.A.) are not yet implemented. Motivation ---------- The motivation for this collection of commands. Introduction ------------ A brief introduction to this collection of commands as a whole. Commands -------- For each command in the block, the following is described: Synopsis ........ -command ARGS... GDB Command ........... The corresponding GDB CLI command. Result ...... Out-of-band ........... Notes ..... Example .......  File: gdb.info, Node: GDB/MI Breakpoint Table Commands, Next: GDB/MI Data Manipulation, Prev: GDB/MI Command Description Format, Up: GDB/MI 24.5 GDB/MI Breakpoint table commands ===================================== This section documents GDB/MI commands for manipulating breakpoints. The `-break-after' Command -------------------------- Synopsis ........ -break-after NUMBER COUNT The breakpoint number NUMBER is not in effect until it has been hit COUNT times. To see how this is reflected in the output of the `-break-list' command, see the description of the `-break-list' command below. GDB Command ........... The corresponding GDB command is `ignore'. Example ....... (gdb) -break-insert main ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"} (gdb) -break-after 1 3 ~ ^done (gdb) -break-list ^done,BreakpointTable={nr_rows="1",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x000100d0",func="main",file="hello.c",line="5",times="0", ignore="3"}]} (gdb) The `-break-condition' Command ------------------------------ Synopsis ........ -break-condition NUMBER EXPR Breakpoint NUMBER will stop the program only if the condition in EXPR is true. The condition becomes part of the `-break-list' output (see the description of the `-break-list' command below). GDB Command ........... The corresponding GDB command is `condition'. Example ....... (gdb) -break-condition 1 1 ^done (gdb) -break-list ^done,BreakpointTable={nr_rows="1",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", times="0",ignore="3"}]} (gdb) The `-break-delete' Command --------------------------- Synopsis ........ -break-delete ( BREAKPOINT )+ Delete the breakpoint(s) whose number(s) are specified in the argument list. This is obviously reflected in the breakpoint list. GDB command ........... The corresponding GDB command is `delete'. Example ....... (gdb) -break-delete 1 ^done (gdb) -break-list ^done,BreakpointTable={nr_rows="0",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[]} (gdb) The `-break-disable' Command ---------------------------- Synopsis ........ -break-disable ( BREAKPOINT )+ Disable the named BREAKPOINT(s). The field `enabled' in the break list is now set to `n' for the named BREAKPOINT(s). GDB Command ........... The corresponding GDB command is `disable'. Example ....... (gdb) -break-disable 2 ^done (gdb) -break-list ^done,BreakpointTable={nr_rows="1",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]} (gdb) The `-break-enable' Command --------------------------- Synopsis ........ -break-enable ( BREAKPOINT )+ Enable (previously disabled) BREAKPOINT(s). GDB Command ........... The corresponding GDB command is `enable'. Example ....... (gdb) -break-enable 2 ^done (gdb) -break-list ^done,BreakpointTable={nr_rows="1",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]} (gdb) The `-break-info' Command ------------------------- Synopsis ........ -break-info BREAKPOINT Get information about a single breakpoint. GDB command ........... The corresponding GDB command is `info break BREAKPOINT'. Example ....... N.A. The `-break-insert' Command --------------------------- Synopsis ........ -break-insert [ -t ] [ -h ] [ -r ] [ -c CONDITION ] [ -i IGNORE-COUNT ] [ -p THREAD ] [ LINE | ADDR ] If specified, LINE, can be one of: * function * filename:linenum * filename:function * *address The possible optional parameters of this command are: `-t' Insert a tempoary breakpoint. `-h' Insert a hardware breakpoint. `-c CONDITION' Make the breakpoint conditional on CONDITION. `-i IGNORE-COUNT' Initialize the IGNORE-COUNT. `-r' Insert a regular breakpoint in all the functions whose names match the given regular expression. Other flags are not applicable to regular expresson. Result ...... The result is in the form: ^done,bkptno="NUMBER",func="FUNCNAME", file="FILENAME",line="LINENO" where NUMBER is the GDB number for this breakpoint, FUNCNAME is the name of the function where the breakpoint was inserted, FILENAME is the name of the source file which contains this function, and LINENO is the source line number within that file. Note: this format is open to change. GDB Command ........... The corresponding GDB commands are `break', `tbreak', `hbreak', `thbreak', and `rbreak'. Example ....... (gdb) -break-insert main ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} (gdb) -break-insert -t foo ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"} (gdb) -break-list ^done,BreakpointTable={nr_rows="2",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"}, bkpt={number="2",type="breakpoint",disp="del",enabled="y", addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]} (gdb) -break-insert -r foo.* ~int foo(int, int); ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"} (gdb) The `-break-list' Command ------------------------- Synopsis ........ -break-list Displays the list of inserted breakpoints, showing the following fields: `Number' number of the breakpoint `Type' type of the breakpoint: `breakpoint' or `watchpoint' `Disposition' should the breakpoint be deleted or disabled when it is hit: `keep' or `nokeep' `Enabled' is the breakpoint enabled or no: `y' or `n' `Address' memory location at which the breakpoint is set `What' logical location of the breakpoint, expressed by function name, file name, line number `Times' number of times the breakpoint has been hit If there are no breakpoints or watchpoints, the `BreakpointTable' `body' field is an empty list. GDB Command ........... The corresponding GDB command is `info break'. Example ....... (gdb) -break-list ^done,BreakpointTable={nr_rows="2",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, bkpt={number="2",type="breakpoint",disp="keep",enabled="y", addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}]} (gdb) Here's an example of the result when there are no breakpoints: (gdb) -break-list ^done,BreakpointTable={nr_rows="0",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[]} (gdb) The `-break-watch' Command -------------------------- Synopsis ........ -break-watch [ -a | -r ] Create a watchpoint. With the `-a' option it will create an "access" watchpoint, i.e. a watchpoint that triggers either on a read from or on a write to the memory location. With the `-r' option, the watchpoint created is a "read" watchpoint, i.e. it will trigger only when the memory location is accessed for reading. Without either of the options, the watchpoint created is a regular watchpoint, i.e. it will trigger when the memory location is accessed for writing. *Note Setting watchpoints: Set Watchpoints. Note that `-break-list' will report a single list of watchpoints and breakpoints inserted. GDB Command ........... The corresponding GDB commands are `watch', `awatch', and `rwatch'. Example ....... Setting a watchpoint on a variable in the `main' function: (gdb) -break-watch x ^done,wpt={number="2",exp="x"} (gdb) -exec-continue ^running ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"}, value={old="-268439212",new="55"}, frame={func="main",args=[],file="recursive2.c",line="5"} (gdb) Setting a watchpoint on a variable local to a function. GDB will stop the program execution twice: first for the variable changing value, then for the watchpoint going out of scope. (gdb) -break-watch C ^done,wpt={number="5",exp="C"} (gdb) -exec-continue ^running ^done,reason="watchpoint-trigger", wpt={number="5",exp="C"},value={old="-276895068",new="3"}, frame={func="callee4",args=[], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"} (gdb) -exec-continue ^running ^done,reason="watchpoint-scope",wpnum="5", frame={func="callee3",args=[{name="strarg", value="0x11940 \"A string argument.\""}], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} (gdb) Listing breakpoints and watchpoints, at different points in the program execution. Note that once the watchpoint goes out of scope, it is deleted. (gdb) -break-watch C ^done,wpt={number="2",exp="C"} (gdb) -break-list ^done,BreakpointTable={nr_rows="2",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x00010734",func="callee4", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, bkpt={number="2",type="watchpoint",disp="keep", enabled="y",addr="",what="C",times="0"}]} (gdb) -exec-continue ^running ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"}, value={old="-276895068",new="3"}, frame={func="callee4",args=[], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"} (gdb) -break-list ^done,BreakpointTable={nr_rows="2",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x00010734",func="callee4", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, bkpt={number="2",type="watchpoint",disp="keep", enabled="y",addr="",what="C",times="-5"}]} (gdb) -exec-continue ^running ^done,reason="watchpoint-scope",wpnum="2", frame={func="callee3",args=[{name="strarg", value="0x11940 \"A string argument.\""}], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} (gdb) -break-list ^done,BreakpointTable={nr_rows="1",nr_cols="6", hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, {width="14",alignment="-1",col_name="type",colhdr="Type"}, {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, {width="10",alignment="-1",col_name="addr",colhdr="Address"}, {width="40",alignment="2",col_name="what",colhdr="What"}], body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", addr="0x00010734",func="callee4", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}]} (gdb)  File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Program Control, Prev: GDB/MI Breakpoint Table Commands, Up: GDB/MI 24.6 GDB/MI Data Manipulation ============================= This section describes the GDB/MI commands that manipulate data: examine memory and registers, evaluate expressions, etc. The `-data-disassemble' Command ------------------------------- Synopsis ........ -data-disassemble [ -s START-ADDR -e END-ADDR ] | [ -f FILENAME -l LINENUM [ -n LINES ] ] -- MODE Where: `START-ADDR' is the beginning address (or `$pc') `END-ADDR' is the end address `FILENAME' is the name of the file to disassemble `LINENUM' is the line number to disassemble around `LINES' is the the number of disassembly lines to be produced. If it is -1, the whole function will be disassembled, in case no END-ADDR is specified. If END-ADDR is specified as a non-zero value, and LINES is lower than the number of disassembly lines between START-ADDR and END-ADDR, only LINES lines are displayed; if LINES is higher than the number of lines between START-ADDR and END-ADDR, only the lines up to END-ADDR are displayed. `MODE' is either 0 (meaning only disassembly) or 1 (meaning mixed source and disassembly). Result ...... The output for each instruction is composed of four fields: * Address * Func-name * Offset * Instruction Note that whatever included in the instruction field, is not manipulated directely by GDB/MI, i.e. it is not possible to adjust its format. GDB Command ........... There's no direct mapping from this command to the CLI. Example ....... Disassemble from the current value of `$pc' to `$pc + 20': (gdb) -data-disassemble -s $pc -e "$pc + 20" -- 0 ^done, asm_insns=[ {address="0x000107c0",func-name="main",offset="4", inst="mov 2, %o0"}, {address="0x000107c4",func-name="main",offset="8", inst="sethi %hi(0x11800), %o2"}, {address="0x000107c8",func-name="main",offset="12", inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, {address="0x000107cc",func-name="main",offset="16", inst="sethi %hi(0x11800), %o2"}, {address="0x000107d0",func-name="main",offset="20", inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] (gdb) Disassemble the whole `main' function. Line 32 is part of `main'. -data-disassemble -f basics.c -l 32 -- 0 ^done,asm_insns=[ {address="0x000107bc",func-name="main",offset="0", inst="save %sp, -112, %sp"}, {address="0x000107c0",func-name="main",offset="4", inst="mov 2, %o0"}, {address="0x000107c4",func-name="main",offset="8", inst="sethi %hi(0x11800), %o2"}, [...] {address="0x0001081c",func-name="main",offset="96",inst="ret "}, {address="0x00010820",func-name="main",offset="100",inst="restore "}] (gdb) Disassemble 3 instructions from the start of `main': (gdb) -data-disassemble -f basics.c -l 32 -n 3 -- 0 ^done,asm_insns=[ {address="0x000107bc",func-name="main",offset="0", inst="save %sp, -112, %sp"}, {address="0x000107c0",func-name="main",offset="4", inst="mov 2, %o0"}, {address="0x000107c4",func-name="main",offset="8", inst="sethi %hi(0x11800), %o2"}] (gdb) Disassemble 3 instructions from the start of `main' in mixed mode: (gdb) -data-disassemble -f basics.c -l 32 -n 3 -- 1 ^done,asm_insns=[ src_and_asm_line={line="31", file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ testsuite/gdb.mi/basics.c",line_asm_insn=[ {address="0x000107bc",func-name="main",offset="0", inst="save %sp, -112, %sp"}]}, src_and_asm_line={line="32", file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ testsuite/gdb.mi/basics.c",line_asm_insn=[ {address="0x000107c0",func-name="main",offset="4", inst="mov 2, %o0"}, {address="0x000107c4",func-name="main",offset="8", inst="sethi %hi(0x11800), %o2"}]}] (gdb) The `-data-evaluate-expression' Command --------------------------------------- Synopsis ........ -data-evaluate-expression EXPR Evaluate EXPR as an expression. The expression could contain an inferior function call. The function call will execute synchronously. If the expression contains spaces, it must be enclosed in double quotes. GDB Command ........... The corresponding GDB commands are `print', `output', and `call'. In `gdbtk' only, there's a corresponding `gdb_eval' command. Example ....... In the following example, the numbers that precede the commands are the "tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command Syntax. Notice how GDB/MI returns the same tokens in its output. 211-data-evaluate-expression A 211^done,value="1" (gdb) 311-data-evaluate-expression &A 311^done,value="0xefffeb7c" (gdb) 411-data-evaluate-expression A+3 411^done,value="4" (gdb) 511-data-evaluate-expression "A + 3" 511^done,value="4" (gdb) The `-data-list-changed-registers' Command ------------------------------------------ Synopsis ........ -data-list-changed-registers Display a list of the registers that have changed. GDB Command ........... GDB doesn't have a direct analog for this command; `gdbtk' has the corresponding command `gdb_changed_register_list'. Example ....... On a PPC MBX board: (gdb) -exec-continue ^running (gdb) *stopped,reason="breakpoint-hit",bkptno="1",frame={func="main", args=[],file="try.c",line="5"} (gdb) -data-list-changed-registers ^done,changed-registers=["0","1","2","4","5","6","7","8","9", "10","11","13","14","15","16","17","18","19","20","21","22","23", "24","25","26","27","28","30","31","64","65","66","67","69"] (gdb) The `-data-list-register-names' Command --------------------------------------- Synopsis ........ -data-list-register-names [ ( REGNO )+ ] Show a list of register names for the current target. If no arguments are given, it shows a list of the names of all the registers. If integer numbers are given as arguments, it will print a list of the names of the registers corresponding to the arguments. To ensure consistency between a register name and its number, the output list may include empty register names. GDB Command ........... GDB does not have a command which corresponds to `-data-list-register-names'. In `gdbtk' there is a corresponding command `gdb_regnames'. Example ....... For the PPC MBX board: (gdb) -data-list-register-names ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", "", "pc","ps","cr","lr","ctr","xer"] (gdb) -data-list-register-names 1 2 3 ^done,register-names=["r1","r2","r3"] (gdb) The `-data-list-register-values' Command ---------------------------------------- Synopsis ........ -data-list-register-values FMT [ ( REGNO )*] Display the registers' contents. FMT is the format according to which the registers' contents are to be returned, followed by an optional list of numbers specifying the registers to display. A missing list of numbers indicates that the contents of all the registers must be returned. Allowed formats for FMT are: `x' Hexadecimal `o' Octal `t' Binary `d' Decimal `r' Raw `N' Natural GDB Command ........... The corresponding GDB commands are `info reg', `info all-reg', and (in `gdbtk') `gdb_fetch_registers'. Example ....... For a PPC MBX board (note: line breaks are for readability only, they don't appear in the actual output): (gdb) -data-list-register-values r 64 65 ^done,register-values=[{number="64",value="0xfe00a300"}, {number="65",value="0x00029002"}] (gdb) -data-list-register-values x ^done,register-values=[{number="0",value="0xfe0043c8"}, {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, {number="3",value="0x0"},{number="4",value="0xa"}, {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, {number="7",value="0xfe011e98"},{number="8",value="0x2"}, {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, {number="11",value="0x1"},{number="12",value="0x0"}, {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, {number="29",value="0x0"},{number="30",value="0xfe010000"}, {number="31",value="0x0"},{number="32",value="0x0"}, {number="33",value="0x0"},{number="34",value="0x0"}, {number="35",value="0x0"},{number="36",value="0x0"}, {number="37",value="0x0"},{number="38",value="0x0"}, {number="39",value="0x0"},{number="40",value="0x0"}, {number="41",value="0x0"},{number="42",value="0x0"}, {number="43",value="0x0"},{number="44",value="0x0"}, {number="45",value="0x0"},{number="46",value="0x0"}, {number="47",value="0x0"},{number="48",value="0x0"}, {number="49",value="0x0"},{number="50",value="0x0"}, {number="51",value="0x0"},{number="52",value="0x0"}, {number="53",value="0x0"},{number="54",value="0x0"}, {number="55",value="0x0"},{number="56",value="0x0"}, {number="57",value="0x0"},{number="58",value="0x0"}, {number="59",value="0x0"},{number="60",value="0x0"}, {number="61",value="0x0"},{number="62",value="0x0"}, {number="63",value="0x0"},{number="64",value="0xfe00a300"}, {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, {number="69",value="0x20002b03"}] (gdb) The `-data-read-memory' Command ------------------------------- Synopsis ........ -data-read-memory [ -o BYTE-OFFSET ] ADDRESS WORD-FORMAT WORD-SIZE NR-ROWS NR-COLS [ ASCHAR ] where: `ADDRESS' An expression specifying the address of the first memory word to be read. Complex expressions containing embedded white space should be quoted using the C convention. `WORD-FORMAT' The format to be used to print the memory words. The notation is the same as for GDB's `print' command (*note Output formats: Output Formats.). `WORD-SIZE' The size of each memory word in bytes. `NR-ROWS' The number of rows in the output table. `NR-COLS' The number of columns in the output table. `ASCHAR' If present, indicates that each row should include an ASCII dump. The value of ASCHAR is used as a padding character when a byte is not a member of the printable ASCII character set (printable ASCII characters are those whose code is between 32 and 126, inclusively). `BYTE-OFFSET' An offset to add to the ADDRESS before fetching memory. This command displays memory contents as a table of NR-ROWS by NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). Should less than the requested number of bytes be returned by the target, the missing words are identified using `N/A'. The number of bytes read from the target is returned in `nr-bytes' and the starting address used to read memory in `addr'. The address of the next/previous row or page is available in `next-row' and `prev-row', `next-page' and `prev-page'. GDB Command ........... The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory read command. Example ....... Read six bytes of memory starting at `bytes+6' but then offset by `-6' bytes. Format as three rows of two columns. One byte per word. Display each word in hex. (gdb) 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", prev-page="0x0000138a",memory=[ {addr="0x00001390",data=["0x00","0x01"]}, {addr="0x00001392",data=["0x02","0x03"]}, {addr="0x00001394",data=["0x04","0x05"]}] (gdb) Read two bytes of memory starting at address `shorts + 64' and display as a single word formatted in decimal. (gdb) 5-data-read-memory shorts+64 d 2 1 1 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", next-row="0x00001512",prev-row="0x0000150e", next-page="0x00001512",prev-page="0x0000150e",memory=[ {addr="0x00001510",data=["128"]}] (gdb) Read thirty two bytes of memory starting at `bytes+16' and format as eight rows of four columns. Include a string encoding with `x' used as the non-printable character. (gdb) 4-data-read-memory bytes+16 x 1 8 4 x 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", next-row="0x000013c0",prev-row="0x0000139c", next-page="0x000013c0",prev-page="0x00001380",memory=[ {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] (gdb) The `-display-delete' Command ----------------------------- Synopsis ........ -display-delete NUMBER Delete the display NUMBER. GDB Command ........... The corresponding GDB command is `delete display'. Example ....... N.A. The `-display-disable' Command ------------------------------ Synopsis ........ -display-disable NUMBER Disable display NUMBER. GDB Command ........... The corresponding GDB command is `disable display'. Example ....... N.A. The `-display-enable' Command ----------------------------- Synopsis ........ -display-enable NUMBER Enable display NUMBER. GDB Command ........... The corresponding GDB command is `enable display'. Example ....... N.A. The `-display-insert' Command ----------------------------- Synopsis ........ -display-insert EXPRESSION Display EXPRESSION every time the program stops. GDB Command ........... The corresponding GDB command is `display'. Example ....... N.A. The `-display-list' Command --------------------------- Synopsis ........ -display-list List the displays. Do not show the current values. GDB Command ........... The corresponding GDB command is `info display'. Example ....... N.A. The `-environment-cd' Command ----------------------------- Synopsis ........ -environment-cd PATHDIR Set GDB's working directory. GDB Command ........... The corresponding GDB command is `cd'. Example ....... (gdb) -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb ^done (gdb) The `-environment-directory' Command ------------------------------------ Synopsis ........ -environment-directory [ -r ] [ PATHDIR ]+ Add directories PATHDIR to beginning of search path for source files. If the `-r' option is used, the search path is reset to the default search path. If directories PATHDIR are supplied in addition to the `-r' option, the search path is first reset and then addition occurs as normal. Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current search path is displayed. GDB Command ........... The corresponding GDB command is `dir'. Example ....... (gdb) -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" (gdb) -environment-directory "" ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" (gdb) -environment-directory -r /home/jjohnstn/src/gdb /usr/src ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" (gdb) -environment-directory -r ^done,source-path="$cdir:$cwd" (gdb) The `-environment-path' Command ------------------------------- Synopsis ........ -environment-path [ -r ] [ PATHDIR ]+ Add directories PATHDIR to beginning of search path for object files. If the `-r' option is used, the search path is reset to the original search path that existed at gdb start-up. If directories PATHDIR are supplied in addition to the `-r' option, the search path is first reset and then addition occurs as normal. Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current path is displayed. GDB Command ........... The corresponding GDB command is `path'. Example ....... (gdb) -environment-path ^done,path="/usr/bin" (gdb) -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" (gdb) -environment-path -r /usr/local/bin ^done,path="/usr/local/bin:/usr/bin" (gdb) The `-environment-pwd' Command ------------------------------ Synopsis ........ -environment-pwd Show the current working directory. GDB command ........... The corresponding GDB command is `pwd'. Example ....... (gdb) -environment-pwd ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" (gdb)  File: gdb.info, Node: GDB/MI Program Control, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Data Manipulation, Up: GDB/MI 24.7 GDB/MI Program control =========================== Program termination ................... As a result of execution, the inferior program can run to completion, if it doesn't encounter any breakpoints. In this case the output will include an exit code, if the program has exited exceptionally. Examples ........ Program exited normally: (gdb) -exec-run ^running (gdb) x = 55 *stopped,reason="exited-normally" (gdb) Program exited exceptionally: (gdb) -exec-run ^running (gdb) x = 55 *stopped,reason="exited",exit-code="01" (gdb) Another way the program can terminate is if it receives a signal such as `SIGINT'. In this case, GDB/MI displays this: (gdb) *stopped,reason="exited-signalled",signal-name="SIGINT", signal-meaning="Interrupt" The `-exec-abort' Command ------------------------- Synopsis ........ -exec-abort Kill the inferior running program. GDB Command ........... The corresponding GDB command is `kill'. Example ....... N.A. The `-exec-arguments' Command ----------------------------- Synopsis ........ -exec-arguments ARGS Set the inferior program arguments, to be used in the next `-exec-run'. GDB Command ........... The corresponding GDB command is `set args'. Example ....... Don't have one around. The `-exec-continue' Command ---------------------------- Synopsis ........ -exec-continue Asynchronous command. Resumes the execution of the inferior program until a breakpoint is encountered, or until the inferior exits. GDB Command ........... The corresponding GDB corresponding is `continue'. Example ....... -exec-continue ^running (gdb) @Hello world *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[], file="hello.c",line="13"} (gdb) The `-exec-finish' Command -------------------------- Synopsis ........ -exec-finish Asynchronous command. Resumes the execution of the inferior program until the current function is exited. Displays the results returned by the function. GDB Command ........... The corresponding GDB command is `finish'. Example ....... Function returning `void'. -exec-finish ^running (gdb) @hello from foo *stopped,reason="function-finished",frame={func="main",args=[], file="hello.c",line="7"} (gdb) Function returning other than `void'. The name of the internal GDB variable storing the result is printed, together with the value itself. -exec-finish ^running (gdb) *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", args=[{name="a",value="1"],{name="b",value="9"}}, file="recursive2.c",line="14"}, gdb-result-var="$1",return-value="0" (gdb) The `-exec-interrupt' Command ----------------------------- Synopsis ........ -exec-interrupt Asynchronous command. Interrupts the background execution of the target. Note how the token associated with the stop message is the one for the execution command that has been interrupted. The token for the interrupt itself only appears in the `^done' output. If the user is trying to interrupt a non-running program, an error message will be printed. GDB Command ........... The corresponding GDB command is `interrupt'. Example ....... (gdb) 111-exec-continue 111^running (gdb) 222-exec-interrupt 222^done (gdb) 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", frame={addr="0x00010140",func="foo",args=[],file="try.c",line="13"} (gdb) (gdb) -exec-interrupt ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." (gdb) The `-exec-next' Command ------------------------ Synopsis ........ -exec-next Asynchronous command. Resumes execution of the inferior program, stopping when the beginning of the next source line is reached. GDB Command ........... The corresponding GDB command is `next'. Example ....... -exec-next ^running (gdb) *stopped,reason="end-stepping-range",line="8",file="hello.c" (gdb) The `-exec-next-instruction' Command ------------------------------------ Synopsis ........ -exec-next-instruction Asynchronous command. Executes one machine instruction. If the instruction is a function call continues until the function returns. If the program stops at an instruction in the middle of a source line, the address will be printed as well. GDB Command ........... The corresponding GDB command is `nexti'. Example ....... (gdb) -exec-next-instruction ^running (gdb) *stopped,reason="end-stepping-range", addr="0x000100d4",line="5",file="hello.c" (gdb) The `-exec-return' Command -------------------------- Synopsis ........ -exec-return Makes current function return immediately. Doesn't execute the inferior. Displays the new current frame. GDB Command ........... The corresponding GDB command is `return'. Example ....... (gdb) 200-break-insert callee4 200^done,bkpt={number="1",addr="0x00010734", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} (gdb) 000-exec-run 000^running (gdb) 000*stopped,reason="breakpoint-hit",bkptno="1", frame={func="callee4",args=[], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} (gdb) 205-break-delete 205^done (gdb) 111-exec-return 111^done,frame={level="0",func="callee3", args=[{name="strarg", value="0x11940 \"A string argument.\""}], file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} (gdb) The `-exec-run' Command ----------------------- Synopsis ........ -exec-run Asynchronous command. Starts execution of the inferior from the beginning. The inferior executes until either a breakpoint is encountered or the program exits. GDB Command ........... The corresponding GDB command is `run'. Example ....... (gdb) -break-insert main ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} (gdb) -exec-run ^running (gdb) *stopped,reason="breakpoint-hit",bkptno="1", frame={func="main",args=[],file="recursive2.c",line="4"} (gdb) The `-exec-show-arguments' Command ---------------------------------- Synopsis ........ -exec-show-arguments Print the arguments of the program. GDB Command ........... The corresponding GDB command is `show args'. Example ....... N.A. The `-exec-step' Command ------------------------ Synopsis ........ -exec-step Asynchronous command. Resumes execution of the inferior program, stopping when the beginning of the next source line is reached, if the next source line is not a function call. If it is, stop at the first instruction of the called function. GDB Command ........... The corresponding GDB command is `step'. Example ....... Stepping into a function: -exec-step ^running (gdb) *stopped,reason="end-stepping-range", frame={func="foo",args=[{name="a",value="10"}, {name="b",value="0"}],file="recursive2.c",line="11"} (gdb) Regular stepping: -exec-step ^running (gdb) *stopped,reason="end-stepping-range",line="14",file="recursive2.c" (gdb) The `-exec-step-instruction' Command ------------------------------------ Synopsis ........ -exec-step-instruction Asynchronous command. Resumes the inferior which executes one machine instruction. The output, once GDB has stopped, will vary depending on whether we have stopped in the middle of a source line or not. In the former case, the address at which the program stopped will be printed as well. GDB Command ........... The corresponding GDB command is `stepi'. Example ....... (gdb) -exec-step-instruction ^running (gdb) *stopped,reason="end-stepping-range", frame={func="foo",args=[],file="try.c",line="10"} (gdb) -exec-step-instruction ^running (gdb) *stopped,reason="end-stepping-range", frame={addr="0x000100f4",func="foo",args=[],file="try.c",line="10"} (gdb) The `-exec-until' Command ------------------------- Synopsis ........ -exec-until [ LOCATION ] Asynchronous command. Executes the inferior until the LOCATION specified in the argument is reached. If there is no argument, the inferior executes until a source line greater than the current one is reached. The reason for stopping in this case will be `location-reached'. GDB Command ........... The corresponding GDB command is `until'. Example ....... (gdb) -exec-until recursive2.c:6 ^running (gdb) x = 55 *stopped,reason="location-reached",frame={func="main",args=[], file="recursive2.c",line="6"} (gdb) The `-file-exec-and-symbols' Command ------------------------------------ Synopsis ........ -file-exec-and-symbols FILE Specify the executable file to be debugged. This file is the one from which the symbol table is also read. If no file is specified, the command clears the executable and symbol information. If breakpoints are set when using this command with no arguments, GDB will produce error messages. Otherwise, no output is produced, except a completion notification. GDB Command ........... The corresponding GDB command is `file'. Example ....... (gdb) -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx ^done (gdb) The `-file-exec-file' Command ----------------------------- Synopsis ........ -file-exec-file FILE Specify the executable file to be debugged. Unlike `-file-exec-and-symbols', the symbol table is _not_ read from this file. If used without argument, GDB clears the information about the executable file. No output is produced, except a completion notification. GDB Command ........... The corresponding GDB command is `exec-file'. Example ....... (gdb) -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx ^done (gdb) The `-file-list-exec-sections' Command -------------------------------------- Synopsis ........ -file-list-exec-sections List the sections of the current executable file. GDB Command ........... The GDB command `info file' shows, among the rest, the same information as this command. `gdbtk' has a corresponding command `gdb_load_info'. Example ....... N.A. The `-file-list-exec-source-file' Command ----------------------------------------- Synopsis ........ -file-list-exec-source-file List the line number, the current source file, and the absolute path to the current source file for the current executable. GDB Command ........... There's no GDB command which directly corresponds to this one. Example ....... (gdb) 123-file-list-exec-source-file 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" (gdb) The `-file-list-exec-source-files' Command ------------------------------------------ Synopsis ........ -file-list-exec-source-files List the source files for the current executable. It will always output the filename, but only when GDB can find the absolute file name of a source file, will it output the fullname. GDB Command ........... There's no GDB command which directly corresponds to this one. `gdbtk' has an analogous command `gdb_listfiles'. Example ....... (gdb) -file-list-exec-source-files ^done,files=[ {file=foo.c,fullname=/home/foo.c}, {file=/home/bar.c,fullname=/home/bar.c}, {file=gdb_could_not_find_fullpath.c}] (gdb) The `-file-list-shared-libraries' Command ----------------------------------------- Synopsis ........ -file-list-shared-libraries List the shared libraries in the program. GDB Command ........... The corresponding GDB command is `info shared'. Example ....... N.A. The `-file-list-symbol-files' Command ------------------------------------- Synopsis ........ -file-list-symbol-files List symbol files. GDB Command ........... The corresponding GDB command is `info file' (part of it). Example ....... N.A. The `-file-symbol-file' Command ------------------------------- Synopsis ........ -file-symbol-file FILE Read symbol table info from the specified FILE argument. When used without arguments, clears GDB's symbol table info. No output is produced, except for a completion notification. GDB Command ........... The corresponding GDB command is `symbol-file'. Example ....... (gdb) -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx ^done (gdb)  File: gdb.info, Node: GDB/MI Miscellaneous Commands, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Program Control, Up: GDB/MI 24.8 Miscellaneous GDB commands in GDB/MI ========================================= The `-gdb-exit' Command ----------------------- Synopsis ........ -gdb-exit Exit GDB immediately. GDB Command ........... Approximately corresponds to `quit'. Example ....... (gdb) -gdb-exit The `-gdb-set' Command ---------------------- Synopsis ........ -gdb-set Set an internal GDB variable. GDB Command ........... The corresponding GDB command is `set'. Example ....... (gdb) -gdb-set $foo=3 ^done (gdb) The `-gdb-show' Command ----------------------- Synopsis ........ -gdb-show Show the current value of a GDB variable. GDB command ........... The corresponding GDB command is `show'. Example ....... (gdb) -gdb-show annotate ^done,value="0" (gdb) The `-gdb-version' Command -------------------------- Synopsis ........ -gdb-version Show version information for GDB. Used mostly in testing. GDB Command ........... There's no equivalent GDB command. GDB by default shows this information when you start an interactive session. Example ....... (gdb) -gdb-version ~GNU gdb 5.2.1 ~Copyright 2000 Free Software Foundation, Inc. ~GDB is free software, covered by the GNU General Public License, and ~you are welcome to change it and/or distribute copies of it under ~ certain conditions. ~Type "show copying" to see the conditions. ~There is absolutely no warranty for GDB. Type "show warranty" for ~ details. ~This GDB was configured as "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". ^done (gdb) The `-interpreter-exec' Command ------------------------------- Synopsis -------- -interpreter-exec INTERPRETER COMMAND Execute the specified COMMAND in the given INTERPRETER. GDB Command ----------- The corresponding GDB command is `interpreter-exec'. Example ------- (gdb) -interpreter-exec console "break main" &"During symbol reading, couldn't parse type; debugger out of date?.\n" &"During symbol reading, bad structure-type format.\n" ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" ^done (gdb)  File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Symbol Query, Prev: GDB/MI Miscellaneous Commands, Up: GDB/MI 24.9 GDB/MI Stack Manipulation Commands ======================================= The `-stack-info-frame' Command ------------------------------- Synopsis ........ -stack-info-frame Get info on the current frame. GDB Command ........... The corresponding GDB command is `info frame' or `frame' (without arguments). Example ....... N.A. The `-stack-info-depth' Command ------------------------------- Synopsis ........ -stack-info-depth [ MAX-DEPTH ] Return the depth of the stack. If the integer argument MAX-DEPTH is specified, do not count beyond MAX-DEPTH frames. GDB Command ........... There's no equivalent GDB command. Example ....... For a stack with frame levels 0 through 11: (gdb) -stack-info-depth ^done,depth="12" (gdb) -stack-info-depth 4 ^done,depth="4" (gdb) -stack-info-depth 12 ^done,depth="12" (gdb) -stack-info-depth 11 ^done,depth="11" (gdb) -stack-info-depth 13 ^done,depth="12" (gdb) The `-stack-list-arguments' Command ----------------------------------- Synopsis ........ -stack-list-arguments SHOW-VALUES [ LOW-FRAME HIGH-FRAME ] Display a list of the arguments for the frames between LOW-FRAME and HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, list the arguments for the whole call stack. The SHOW-VALUES argument must have a value of 0 or 1. A value of 0 means that only the names of the arguments are listed, a value of 1 means that both names and values of the arguments are printed. GDB Command ........... GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' command which partially overlaps with the functionality of `-stack-list-arguments'. Example ....... (gdb) -stack-list-frames ^done, stack=[ frame={level="0",addr="0x00010734",func="callee4", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, frame={level="1",addr="0x0001076c",func="callee3", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, frame={level="2",addr="0x0001078c",func="callee2", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, frame={level="3",addr="0x000107b4",func="callee1", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, frame={level="4",addr="0x000107e0",func="main", file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] (gdb) -stack-list-arguments 0 ^done, stack-args=[ frame={level="0",args=[]}, frame={level="1",args=[name="strarg"]}, frame={level="2",args=[name="intarg",name="strarg"]}, frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, frame={level="4",args=[]}] (gdb) -stack-list-arguments 1 ^done, stack-args=[ frame={level="0",args=[]}, frame={level="1", args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, frame={level="2",args=[ {name="intarg",value="2"}, {name="strarg",value="0x11940 \"A string argument.\""}]}, {frame={level="3",args=[ {name="intarg",value="2"}, {name="strarg",value="0x11940 \"A string argument.\""}, {name="fltarg",value="3.5"}]}, frame={level="4",args=[]}] (gdb) -stack-list-arguments 0 2 2 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] (gdb) -stack-list-arguments 1 2 2 ^done,stack-args=[frame={level="2", args=[{name="intarg",value="2"}, {name="strarg",value="0x11940 \"A string argument.\""}]}] (gdb) The `-stack-list-frames' Command -------------------------------- Synopsis ........ -stack-list-frames [ LOW-FRAME HIGH-FRAME ] List the frames currently on the stack. For each frame it displays the following info: `LEVEL' The frame number, 0 being the topmost frame, i.e. the innermost function. `ADDR' The `$pc' value for that frame. `FUNC' Function name. `FILE' File name of the source file where the function lives. `LINE' Line number corresponding to the `$pc'. If invoked without arguments, this command prints a backtrace for the whole stack. If given two integer arguments, it shows the frames whose levels are between the two arguments (inclusive). If the two arguments are equal, it shows the single frame at the corresponding level. GDB Command ........... The corresponding GDB commands are `backtrace' and `where'. Example ....... Full stack backtrace: (gdb) -stack-list-frames ^done,stack= [frame={level="0",addr="0x0001076c",func="foo", file="recursive2.c",line="11"}, frame={level="1",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="2",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="3",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="4",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="5",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="6",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="7",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="8",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="9",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="10",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="11",addr="0x00010738",func="main", file="recursive2.c",line="4"}] (gdb) Show frames between LOW_FRAME and HIGH_FRAME: (gdb) -stack-list-frames 3 5 ^done,stack= [frame={level="3",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="4",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}, frame={level="5",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}] (gdb) Show a single frame: (gdb) -stack-list-frames 3 3 ^done,stack= [frame={level="3",addr="0x000107a4",func="foo", file="recursive2.c",line="14"}] (gdb) The `-stack-list-locals' Command -------------------------------- Synopsis ........ -stack-list-locals PRINT-VALUES Display the local variable names for the current frame. With an argument of 0 or `--no-values', prints only the names of the variables. With argument of 1 or `--all-values', prints also their values. With argument of 2 or `--simple-values', prints the name, type and value for simple data types and the name and type for arrays, structures and unions. In this last case, the idea is that the user can see the value of simple data types immediately and he can create variable objects for other data types if he wishes to explore their values in more detail. GDB Command ........... `info locals' in GDB, `gdb_get_locals' in `gdbtk'. Example ....... (gdb) -stack-list-locals 0 ^done,locals=[name="A",name="B",name="C"] (gdb) -stack-list-locals --all-values ^done,locals=[{name="A",value="1"},{name="B",value="2"}, {name="C",value="{1, 2, 3}"}] -stack-list-locals --simple-values ^done,locals=[{name="A",type="int",value="1"}, {name="B",type="int",value="2"},{name="C",type="int [3]"}] (gdb) The `-stack-select-frame' Command --------------------------------- Synopsis ........ -stack-select-frame FRAMENUM Change the current frame. Select a different frame FRAMENUM on the stack. GDB Command ........... The corresponding GDB commands are `frame', `up', `down', `select-frame', `up-silent', and `down-silent'. Example ....... (gdb) -stack-select-frame 2 ^done (gdb)  File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI Target Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI 24.10 GDB/MI Symbol Query Commands ================================== The `-symbol-info-address' Command ---------------------------------- Synopsis ........ -symbol-info-address SYMBOL Describe where SYMBOL is stored. GDB Command ........... The corresponding GDB command is `info address'. Example ....... N.A. The `-symbol-info-file' Command ------------------------------- Synopsis ........ -symbol-info-file Show the file for the symbol. GDB Command ........... There's no equivalent GDB command. `gdbtk' has `gdb_find_file'. Example ....... N.A. The `-symbol-info-function' Command ----------------------------------- Synopsis ........ -symbol-info-function Show which function the symbol lives in. GDB Command ........... `gdb_get_function' in `gdbtk'. Example ....... N.A. The `-symbol-info-line' Command ------------------------------- Synopsis ........ -symbol-info-line Show the core addresses of the code for a source line. GDB Command ........... The corresponding GDB command is `info line'. `gdbtk' has the `gdb_get_line' and `gdb_get_file' commands. Example ....... N.A. The `-symbol-info-symbol' Command --------------------------------- Synopsis ........ -symbol-info-symbol ADDR Describe what symbol is at location ADDR. GDB Command ........... The corresponding GDB command is `info symbol'. Example ....... N.A. The `-symbol-list-functions' Command ------------------------------------ Synopsis ........ -symbol-list-functions List the functions in the executable. GDB Command ........... `info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'. Example ....... N.A. The `-symbol-list-lines' Command -------------------------------- Synopsis ........ -symbol-list-lines FILENAME Print the list of lines that contain code and their associated program addresses for the given source filename. The entries are sorted in ascending PC order. GDB Command ........... There is no corresponding GDB command. Example ....... (gdb) -symbol-list-lines basics.c ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] (gdb) The `-symbol-list-types' Command -------------------------------- Synopsis ........ -symbol-list-types List all the type names. GDB Command ........... The corresponding commands are `info types' in GDB, `gdb_search' in `gdbtk'. Example ....... N.A. The `-symbol-list-variables' Command ------------------------------------ Synopsis ........ -symbol-list-variables List all the global and static variable names. GDB Command ........... `info variables' in GDB, `gdb_search' in `gdbtk'. Example ....... N.A. The `-symbol-locate' Command ---------------------------- Synopsis ........ -symbol-locate GDB Command ........... `gdb_loc' in `gdbtk'. Example ....... N.A. The `-symbol-type' Command -------------------------- Synopsis ........ -symbol-type VARIABLE Show type of VARIABLE. GDB Command ........... The corresponding GDB command is `ptype', `gdbtk' has `gdb_obj_variable'. Example ....... N.A.  File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI Thread Commands, Prev: GDB/MI Symbol Query, Up: GDB/MI 24.11 GDB/MI Target Manipulation Commands ========================================= The `-target-attach' Command ---------------------------- Synopsis ........ -target-attach PID | FILE Attach to a process PID or a file FILE outside of GDB. GDB command ........... The corresponding GDB command is `attach'. Example ....... N.A. The `-target-compare-sections' Command -------------------------------------- Synopsis ........ -target-compare-sections [ SECTION ] Compare data of section SECTION on target to the exec file. Without the argument, all sections are compared. GDB Command ........... The GDB equivalent is `compare-sections'. Example ....... N.A. The `-target-detach' Command ---------------------------- Synopsis ........ -target-detach Disconnect from the remote target. There's no output. GDB command ........... The corresponding GDB command is `detach'. Example ....... (gdb) -target-detach ^done (gdb) The `-target-disconnect' Command -------------------------------- Synopsis ........ -target-disconnect Disconnect from the remote target. There's no output. GDB command ........... The corresponding GDB command is `disconnect'. Example ....... (gdb) -target-disconnect ^done (gdb) The `-target-download' Command ------------------------------ Synopsis ........ -target-download Loads the executable onto the remote target. It prints out an update message every half second, which includes the fields: `section' The name of the section. `section-sent' The size of what has been sent so far for that section. `section-size' The size of the section. `total-sent' The total size of what was sent so far (the current and the previous sections). `total-size' The size of the overall executable to download. Each message is sent as status record (*note GDB/MI Output Syntax: GDB/MI Output Syntax.). In addition, it prints the name and size of the sections, as they are downloaded. These messages include the following fields: `section' The name of the section. `section-size' The size of the section. `total-size' The size of the overall executable to download. At the end, a summary is printed. GDB Command ........... The corresponding GDB command is `load'. Example ....... Note: each status message appears on a single line. Here the messages have been broken down so that they can fit onto a page. (gdb) -target-download +download,{section=".text",section-size="6668",total-size="9880"} +download,{section=".text",section-sent="512",section-size="6668", total-sent="512",total-size="9880"} +download,{section=".text",section-sent="1024",section-size="6668", total-sent="1024",total-size="9880"} +download,{section=".text",section-sent="1536",section-size="6668", total-sent="1536",total-size="9880"} +download,{section=".text",section-sent="2048",section-size="6668", total-sent="2048",total-size="9880"} +download,{section=".text",section-sent="2560",section-size="6668", total-sent="2560",total-size="9880"} +download,{section=".text",section-sent="3072",section-size="6668", total-sent="3072",total-size="9880"} +download,{section=".text",section-sent="3584",section-size="6668", total-sent="3584",total-size="9880"} +download,{section=".text",section-sent="4096",section-size="6668", total-sent="4096",total-size="9880"} +download,{section=".text",section-sent="4608",section-size="6668", total-sent="4608",total-size="9880"} +download,{section=".text",section-sent="5120",section-size="6668", total-sent="5120",total-size="9880"} +download,{section=".text",section-sent="5632",section-size="6668", total-sent="5632",total-size="9880"} +download,{section=".text",section-sent="6144",section-size="6668", total-sent="6144",total-size="9880"} +download,{section=".text",section-sent="6656",section-size="6668", total-sent="6656",total-size="9880"} +download,{section=".init",section-size="28",total-size="9880"} +download,{section=".fini",section-size="28",total-size="9880"} +download,{section=".data",section-size="3156",total-size="9880"} +download,{section=".data",section-sent="512",section-size="3156", total-sent="7236",total-size="9880"} +download,{section=".data",section-sent="1024",section-size="3156", total-sent="7748",total-size="9880"} +download,{section=".data",section-sent="1536",section-size="3156", total-sent="8260",total-size="9880"} +download,{section=".data",section-sent="2048",section-size="3156", total-sent="8772",total-size="9880"} +download,{section=".data",section-sent="2560",section-size="3156", total-sent="9284",total-size="9880"} +download,{section=".data",section-sent="3072",section-size="3156", total-sent="9796",total-size="9880"} ^done,address="0x10004",load-size="9880",transfer-rate="6586", write-rate="429" (gdb) The `-target-exec-status' Command --------------------------------- Synopsis ........ -target-exec-status Provide information on the state of the target (whether it is running or not, for instance). GDB Command ........... There's no equivalent GDB command. Example ....... N.A. The `-target-list-available-targets' Command -------------------------------------------- Synopsis ........ -target-list-available-targets List the possible targets to connect to. GDB Command ........... The corresponding GDB command is `help target'. Example ....... N.A. The `-target-list-current-targets' Command ------------------------------------------ Synopsis ........ -target-list-current-targets Describe the current target. GDB Command ........... The corresponding information is printed by `info file' (among other things). Example ....... N.A. The `-target-list-parameters' Command ------------------------------------- Synopsis ........ -target-list-parameters GDB Command ........... No equivalent. Example ....... N.A. The `-target-select' Command ---------------------------- Synopsis ........ -target-select TYPE PARAMETERS ... Connect GDB to the remote target. This command takes two args: `TYPE' The type of target, for instance `async', `remote', etc. `PARAMETERS' Device names, host names and the like. *Note Commands for managing targets: Target Commands, for more details. The output is a connection notification, followed by the address at which the target program is, in the following form: ^connected,addr="ADDRESS",func="FUNCTION NAME", args=[ARG LIST] GDB Command ........... The corresponding GDB command is `target'. Example ....... (gdb) -target-select async /dev/ttya ^connected,addr="0xfe00a300",func="??",args=[] (gdb)  File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI 24.12 GDB/MI Thread Commands ============================ The `-thread-info' Command -------------------------- Synopsis ........ -thread-info GDB command ........... No equivalent. Example ....... N.A. The `-thread-list-all-threads' Command -------------------------------------- Synopsis ........ -thread-list-all-threads GDB Command ........... The equivalent GDB command is `info threads'. Example ....... N.A. The `-thread-list-ids' Command ------------------------------ Synopsis ........ -thread-list-ids Produces a list of the currently known GDB thread ids. At the end of the list it also prints the total number of such threads. GDB Command ........... Part of `info threads' supplies the same information. Example ....... No threads present, besides the main process: (gdb) -thread-list-ids ^done,thread-ids={},number-of-threads="0" (gdb) Several threads: (gdb) -thread-list-ids ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, number-of-threads="3" (gdb) The `-thread-select' Command ---------------------------- Synopsis ........ -thread-select THREADNUM Make THREADNUM the current thread. It prints the number of the new current thread, and the topmost frame for that thread. GDB Command ........... The corresponding GDB command is `thread'. Example ....... (gdb) -exec-next ^running (gdb) *stopped,reason="end-stepping-range",thread-id="2",line="187", file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" (gdb) -thread-list-ids ^done, thread-ids={thread-id="3",thread-id="2",thread-id="1"}, number-of-threads="3" (gdb) -thread-select 3 ^done,new-thread-id="3", frame={level="0",func="vprintf", args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, {name="arg",value="0x2"}],file="vprintf.c",line="31"} (gdb)  File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Variable Objects, Prev: GDB/MI Thread Commands, Up: GDB/MI 24.13 GDB/MI Tracepoint Commands ================================ The tracepoint commands are not yet implemented.  File: gdb.info, Node: GDB/MI Variable Objects, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI 24.14 GDB/MI Variable Objects ============================= Motivation for Variable Objects in GDB/MI ----------------------------------------- For the implementation of a variable debugger window (locals, watched expressions, etc.), we are proposing the adaptation of the existing code used by `Insight'. The two main reasons for that are: 1. It has been proven in practice (it is already on its second generation). 2. It will shorten development time (needless to say how important it is now). The original interface was designed to be used by Tcl code, so it was slightly changed so it could be used through GDB/MI. This section describes the GDB/MI operations that will be available and gives some hints about their use. _Note_: In addition to the set of operations described here, we expect the GUI implementation of a variable window to require, at least, the following operations: * `-gdb-show' `output-radix' * `-stack-list-arguments' * `-stack-list-locals' * `-stack-select-frame' Introduction to Variable Objects in GDB/MI ------------------------------------------ The basic idea behind variable objects is the creation of a named object to represent a variable, an expression, a memory location or even a CPU register. For each object created, a set of operations is available for examining or changing its properties. Furthermore, complex data types, such as C structures, are represented in a tree format. For instance, the `struct' type variable is the root and the children will represent the struct members. If a child is itself of a complex type, it will also have children of its own. Appropriate language differences are handled for C, C++ and Java. When returning the actual values of the objects, this facility allows for the individual selection of the display format used in the result creation. It can be chosen among: binary, decimal, hexadecimal, octal and natural. Natural refers to a default format automatically chosen based on the variable type (like decimal for an `int', hex for pointers, etc.). The following is the complete set of GDB/MI operations defined to access this functionality: *Operation* *Description* `-var-create' create a variable object `-var-delete' delete the variable object and its children `-var-set-format' set the display format of this variable `-var-show-format' show the display format of this variable `-var-info-num-children' tells how many children this object has `-var-list-children' return a list of the object's children `-var-info-type' show the type of this variable object `-var-info-expression' print what this variable object represents `-var-show-attributes' is this variable editable? does it exist here? `-var-evaluate-expression' get the value of this variable `-var-assign' set the value of this variable `-var-update' update the variable and its children In the next subsection we describe each operation in detail and suggest how it can be used. Description And Use of Operations on Variable Objects ----------------------------------------------------- The `-var-create' Command ------------------------- Synopsis ........ -var-create {NAME | "-"} {FRAME-ADDR | "*"} EXPRESSION This operation creates a variable object, which allows the monitoring of a variable, the result of an expression, a memory cell or a CPU register. The NAME parameter is the string by which the object can be referenced. It must be unique. If `-' is specified, the varobj system will generate a string "varNNNNNN" automatically. It will be unique provided that one does not specify NAME on that format. The command fails if a duplicate name is found. The frame under which the expression should be evaluated can be specified by FRAME-ADDR. A `*' indicates that the current frame should be used. EXPRESSION is any expression valid on the current language set (must not begin with a `*'), or one of the following: * `*ADDR', where ADDR is the address of a memory cell * `*ADDR-ADDR' -- a memory address range (TBD) * `$REGNAME' -- a CPU register name Result ...... This operation returns the name, number of children and the type of the object created. Type is returned as a string as the ones generated by the GDB CLI: name="NAME",numchild="N",type="TYPE" The `-var-delete' Command ------------------------- Synopsis ........ -var-delete NAME Deletes a previously created variable object and all of its children. Returns an error if the object NAME is not found. The `-var-set-format' Command ----------------------------- Synopsis ........ -var-set-format NAME FORMAT-SPEC Sets the output format for the value of the object NAME to be FORMAT-SPEC. The syntax for the FORMAT-SPEC is as follows: FORMAT-SPEC ==> {binary | decimal | hexadecimal | octal | natural} The `-var-show-format' Command ------------------------------ Synopsis ........ -var-show-format NAME Returns the format used to display the value of the object NAME. FORMAT ==> FORMAT-SPEC The `-var-info-num-children' Command ------------------------------------ Synopsis ........ -var-info-num-children NAME Returns the number of children of a variable object NAME: numchild=N The `-var-list-children' Command -------------------------------- Synopsis ........ -var-list-children [PRINT-VALUES] NAME Returns a list of the children of the specified variable object. With just the variable object name as an argument or with an optional preceding argument of 0 or `--no-values', prints only the names of the variables. With an optional preceding argument of 1 or `--all-values', also prints their values. Example ....... (gdb) -var-list-children n numchild=N,children=[{name=NAME, numchild=N,type=TYPE},(repeats N times)] (gdb) -var-list-children --all-values n numchild=N,children=[{name=NAME, numchild=N,value=VALUE,type=TYPE},(repeats N times)] The `-var-info-type' Command ---------------------------- Synopsis ........ -var-info-type NAME Returns the type of the specified variable NAME. The type is returned as a string in the same format as it is output by the GDB CLI: type=TYPENAME The `-var-info-expression' Command ---------------------------------- Synopsis ........ -var-info-expression NAME Returns what is represented by the variable object NAME: lang=LANG-SPEC,exp=EXPRESSION where LANG-SPEC is `{"C" | "C++" | "Java"}'. The `-var-show-attributes' Command ---------------------------------- Synopsis ........ -var-show-attributes NAME List attributes of the specified variable object NAME: status=ATTR [ ( ,ATTR )* ] where ATTR is `{ { editable | noneditable } | TBD }'. The `-var-evaluate-expression' Command -------------------------------------- Synopsis ........ -var-evaluate-expression NAME Evaluates the expression that is represented by the specified variable object and returns its value as a string in the current format specified for the object: value=VALUE Note that one must invoke `-var-list-children' for a variable before the value of a child variable can be evaluated. The `-var-assign' Command ------------------------- Synopsis ........ -var-assign NAME EXPRESSION Assigns the value of EXPRESSION to the variable object specified by NAME. The object must be `editable'. If the variable's value is altered by the assign, the variable will show up in any subsequent `-var-update' list. Example ....... (gdb) -var-assign var1 3 ^done,value="3" (gdb) -var-update * ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] (gdb) The `-var-update' Command ------------------------- Synopsis ........ -var-update {NAME | "*"} Update the value of the variable object NAME by evaluating its expression after fetching all the new values from memory or registers. A `*' causes all existing variable objects to be updated.  File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top 25 GDB Annotations ****************** This chapter describes annotations in GDB. Annotations were designed to interface GDB to graphical user interfaces or other similar programs which want to interact with GDB at a relatively high level. The annotation mechanism has largely been superseeded by GDB/MI (*note GDB/MI::). * Menu: * Annotations Overview:: What annotations are; the general syntax. * Server Prefix:: Issuing a command without affecting user state. * Prompting:: Annotations marking GDB's need for input. * Errors:: Annotations for error messages. * Invalidation:: Some annotations describe things now invalid. * Annotations for Running:: Whether the program is running, how it stopped, etc. * Source Annotations:: Annotations describing source code.  File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations 25.1 What is an Annotation? =========================== Annotations start with a newline character, two `control-z' characters, and the name of the annotation. If there is no additional information associated with this annotation, the name of the annotation is followed immediately by a newline. If there is additional information, the name of the annotation is followed by a space, the additional information, and a newline. The additional information cannot contain newline characters. Any output not beginning with a newline and two `control-z' characters denotes literal output from GDB. Currently there is no need for GDB to output a newline followed by two `control-z' characters, but if there was such a need, the annotations could be extended with an `escape' annotation which means those three characters as output. The annotation LEVEL, which is specified using the `--annotate' command line option (*note Mode Options::), controls how much information GDB prints together with its prompt, values of expressions, source lines, and other types of output. Level 0 is for no anntations, level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3 is the maximum annotation suitable for programs that control GDB, and level 2 annotations have been made obsolete (*note Limitations of the Annotation Interface: (annotate)Limitations.). This chapter describes level 3 annotations. A simple example of starting up GDB with annotations is: $ gdb --annotate=3 GNU gdb 6.0 Copyright 2003 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "i386-pc-linux-gnu" ^Z^Zpre-prompt (gdb) ^Z^Zprompt quit ^Z^Zpost-prompt $ Here `quit' is input to GDB; the rest is output from GDB. The three lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are annotations; the rest is output from GDB.  File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations 25.2 The Server Prefix ====================== To issue a command to GDB without affecting certain aspects of the state which is seen by users, prefix it with `server '. This means that this command will not affect the command history, nor will it affect GDB's notion of which command to repeat if is pressed on a line by itself. The server prefix does not affect the recording of values into the value history; to print a value without recording it into the value history, use the `output' command instead of the `print' command.  File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations 25.3 Annotation for GDB Input ============================= When GDB prompts for input, it annotates this fact so it is possible to know when to send output, when the output from a given command is over, etc. Different kinds of input each have a different "input type". Each input type has three annotations: a `pre-' annotation, which denotes the beginning of any prompt which is being output, a plain annotation, which denotes the end of the prompt, and then a `post-' annotation which denotes the end of any echo which may (or may not) be associated with the input. For example, the `prompt' input type features the following annotations: ^Z^Zpre-prompt ^Z^Zprompt ^Z^Zpost-prompt The input types are `prompt' When GDB is prompting for a command (the main GDB prompt). `commands' When GDB prompts for a set of commands, like in the `commands' command. The annotations are repeated for each command which is input. `overload-choice' When GDB wants the user to select between various overloaded functions. `query' When GDB wants the user to confirm a potentially dangerous operation. `prompt-for-continue' When GDB is asking the user to press return to continue. Note: Don't expect this to work well; instead use `set height 0' to disable prompting. This is because the counting of lines is buggy in the presence of annotations.  File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations 25.4 Errors =========== ^Z^Zquit This annotation occurs right before GDB responds to an interrupt. ^Z^Zerror This annotation occurs right before GDB responds to an error. Quit and error annotations indicate that any annotations which GDB was in the middle of may end abruptly. For example, if a `value-history-begin' annotation is followed by a `error', one cannot expect to receive the matching `value-history-end'. One cannot expect not to receive it either, however; an error annotation does not necessarily mean that GDB is immediately returning all the way to the top level. A quit or error annotation may be preceded by ^Z^Zerror-begin Any output between that and the quit or error annotation is the error message. Warning messages are not yet annotated.  File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations 25.5 Invalidation Notices ========================= The following annotations say that certain pieces of state may have changed. `^Z^Zframes-invalid' The frames (for example, output from the `backtrace' command) may have changed. `^Z^Zbreakpoints-invalid' The breakpoints may have changed. For example, the user just added or deleted a breakpoint.  File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations 25.6 Running the Program ======================== When the program starts executing due to a GDB command such as `step' or `continue', ^Z^Zstarting is output. When the program stops, ^Z^Zstopped is output. Before the `stopped' annotation, a variety of annotations describe how the program stopped. `^Z^Zexited EXIT-STATUS' The program exited, and EXIT-STATUS is the exit status (zero for successful exit, otherwise nonzero). `^Z^Zsignalled' The program exited with a signal. After the `^Z^Zsignalled', the annotation continues: INTRO-TEXT ^Z^Zsignal-name NAME ^Z^Zsignal-name-end MIDDLE-TEXT ^Z^Zsignal-string STRING ^Z^Zsignal-string-end END-TEXT where NAME is the name of the signal, such as `SIGILL' or `SIGSEGV', and STRING is the explanation of the signal, such as `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no particular format. `^Z^Zsignal' The syntax of this annotation is just like `signalled', but GDB is just saying that the program received the signal, not that it was terminated with it. `^Z^Zbreakpoint NUMBER' The program hit breakpoint number NUMBER. `^Z^Zwatchpoint NUMBER' The program hit watchpoint number NUMBER.  File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations 25.7 Displaying Source ====================== The following annotation is used instead of displaying source code: ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR where FILENAME is an absolute file name indicating which source file, LINE is the line number within that file (where 1 is the first line in the file), CHARACTER is the character position within the file (where 0 is the first character in the file) (for most debug formats this will necessarily point to the beginning of a line), MIDDLE is `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at the beginning of the line, and ADDR is the address in the target program associated with the source which is being displayed. ADDR is in the form `0x' followed by one or more lowercase hex digits (note that this does not depend on the language).  File: gdb.info, Node: GDB Bugs, Next: Formatting Documentation, Prev: GDB/MI, Up: Top 26 Reporting Bugs in GDB ************************ Your bug reports play an essential role in making GDB reliable. Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of GDB work better. Bug reports are your contribution to the maintenance of GDB. In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug. * Menu: * Bug Criteria:: Have you found a bug? * Bug Reporting:: How to report bugs