| This is gdb.info, produced by makeinfo version 4.8 from |
| ../.././gdb/doc/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.6. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, |
| 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 |
| 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: Checks, Next: Supported languages, Prev: Show, Up: Languages |
| |
| 12.3 Type and range checking |
| ============================ |
| |
| _Warning:_ In this release, the GDB commands for type and range |
| checking are included, but they do not yet have any effect. This |
| section documents the intended facilities. |
| |
| Some languages are designed to guard you against making seemingly |
| common errors through a series of compile- and run-time checks. These |
| include checking the type of arguments to functions and operators, and |
| making sure mathematical overflows are caught at run time. Checks such |
| as these help to ensure a program's correctness once it has been |
| compiled by eliminating type mismatches, and providing active checks |
| for range errors when your program is running. |
| |
| GDB can check for conditions like the above if you wish. Although |
| GDB does not check the statements in your program, it can check |
| expressions entered directly into GDB for evaluation via the `print' |
| command, for example. As with the working language, GDB can also |
| decide whether or not to check automatically based on your program's |
| source language. *Note Supported languages: Supported languages, for |
| the default settings of supported languages. |
| |
| * Menu: |
| |
| * Type Checking:: An overview of type checking |
| * Range Checking:: An overview of range checking |
| |
| |
| File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks |
| |
| 12.3.1 An overview of type checking |
| ----------------------------------- |
| |
| Some languages, such as Modula-2, are strongly typed, meaning that the |
| arguments to operators and functions have to be of the correct type, |
| otherwise an error occurs. These checks prevent type mismatch errors |
| from ever causing any run-time problems. For example, |
| |
| 1 + 2 => 3 |
| but |
| error--> 1 + 2.3 |
| |
| The second example fails because the `CARDINAL' 1 is not |
| type-compatible with the `REAL' 2.3. |
| |
| For the expressions you use in GDB commands, you can tell the GDB |
| type checker to skip checking; to treat any mismatches as errors and |
| abandon the expression; or to only issue warnings when type mismatches |
| occur, but evaluate the expression anyway. When you choose the last of |
| these, GDB evaluates expressions like the second example above, but |
| also issues a warning. |
| |
| Even if you turn type checking off, there may be other reasons |
| related to type that prevent GDB from evaluating an expression. For |
| instance, GDB does not know how to add an `int' and a `struct foo'. |
| These particular type errors have nothing to do with the language in |
| use, and usually arise from expressions, such as the one described |
| above, which make little sense to evaluate anyway. |
| |
| Each language defines to what degree it is strict about type. For |
| instance, both Modula-2 and C require the arguments to arithmetical |
| operators to be numbers. In C, enumerated types and pointers can be |
| represented as numbers, so that they are valid arguments to mathematical |
| operators. *Note Supported languages: Supported languages, for further |
| details on specific languages. |
| |
| GDB provides some additional commands for controlling the type |
| checker: |
| |
| `set check type auto' |
| Set type checking on or off based on the current working language. |
| *Note Supported languages: Supported languages, for the default |
| settings for each language. |
| |
| `set check type on' |
| `set check type off' |
| Set type checking on or off, overriding the default setting for the |
| current working language. Issue a warning if the setting does not |
| match the language default. If any type mismatches occur in |
| evaluating an expression while type checking is on, GDB prints a |
| message and aborts evaluation of the expression. |
| |
| `set check type warn' |
| Cause the type checker to issue warnings, but to always attempt to |
| evaluate the expression. Evaluating the expression may still be |
| impossible for other reasons. For example, GDB cannot add numbers |
| and structures. |
| |
| `show type' |
| Show the current setting of the type checker, and whether or not |
| GDB is setting it automatically. |
| |
| |
| File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks |
| |
| 12.3.2 An overview of range checking |
| ------------------------------------ |
| |
| In some languages (such as Modula-2), it is an error to exceed the |
| bounds of a type; this is enforced with run-time checks. Such range |
| checking is meant to ensure program correctness by making sure |
| computations do not overflow, or indices on an array element access do |
| not exceed the bounds of the array. |
| |
| For expressions you use in GDB commands, you can tell GDB to treat |
| range errors in one of three ways: ignore them, always treat them as |
| errors and abandon the expression, or issue warnings but evaluate the |
| expression anyway. |
| |
| A range error can result from numerical overflow, from exceeding an |
| array index bound, or when you type a constant that is not a member of |
| any type. Some languages, however, do not treat overflows as an error. |
| In many implementations of C, mathematical overflow causes the result |
| to "wrap around" to lower values--for example, if M is the largest |
| integer value, and S is the smallest, then |
| |
| M + 1 => S |
| |
| This, too, is specific to individual languages, and in some cases |
| specific to individual compilers or machines. *Note Supported |
| languages: Supported languages, for further details on specific |
| languages. |
| |
| GDB provides some additional commands for controlling the range |
| checker: |
| |
| `set check range auto' |
| Set range checking on or off based on the current working language. |
| *Note Supported languages: Supported languages, for the default |
| settings for each language. |
| |
| `set check range on' |
| `set check range off' |
| Set range checking on or off, overriding the default setting for |
| the current working language. A warning is issued if the setting |
| does not match the language default. If a range error occurs and |
| range checking is on, then a message is printed and evaluation of |
| the expression is aborted. |
| |
| `set check range warn' |
| Output messages when the GDB range checker detects a range error, |
| but attempt to evaluate the expression anyway. Evaluating the |
| expression may still be impossible for other reasons, such as |
| accessing memory that the process does not own (a typical example |
| from many Unix systems). |
| |
| `show range' |
| Show the current setting of the range checker, and whether or not |
| it is being set automatically by GDB. |
| |
| |
| File: gdb.info, Node: Supported languages, Next: Unsupported languages, Prev: Checks, Up: Languages |
| |
| 12.4 Supported languages |
| ======================== |
| |
| GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly, |
| Modula-2, and Ada. Some GDB features may be used in expressions |
| regardless of the language you use: the GDB `@' and `::' operators, and |
| the `{type}addr' construct (*note Expressions: Expressions.) can be |
| used with the constructs of any supported language. |
| |
| The following sections detail to what degree each source language is |
| supported by GDB. These sections are not meant to be language |
| tutorials or references, but serve only as a reference guide to what the |
| GDB expression parser accepts, and what input and output formats should |
| look like for different languages. There are many good books written |
| on each of these languages; please look to these for a language |
| reference or tutorial. |
| |
| * Menu: |
| |
| * C:: C and C++ |
| * Objective-C:: Objective-C |
| * Fortran:: Fortran |
| * Pascal:: Pascal |
| * Modula-2:: Modula-2 |
| * Ada:: Ada |
| |
| |
| File: gdb.info, Node: C, Next: Objective-C, Up: Supported languages |
| |
| 12.4.1 C and C++ |
| ---------------- |
| |
| Since C and C++ are so closely related, many features of GDB apply to |
| both languages. Whenever this is the case, we discuss those languages |
| together. |
| |
| The C++ debugging facilities are jointly implemented by the C++ |
| compiler and GDB. Therefore, to debug your C++ code effectively, you |
| must compile your C++ programs with a supported C++ compiler, such as |
| GNU `g++', or the HP ANSI C++ compiler (`aCC'). |
| |
| For best results when using GNU C++, use the DWARF 2 debugging |
| format; if it doesn't work on your system, try the stabs+ debugging |
| format. You can select those formats explicitly with the `g++' |
| command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for |
| Debugging Your Program or GNU CC: (gcc.info)Debugging Options. |
| |
| * Menu: |
| |
| * C Operators:: C and C++ operators |
| * C Constants:: C and C++ constants |
| * C plus plus expressions:: C++ expressions |
| * C Defaults:: Default settings for C and C++ |
| * C Checks:: C and C++ type and range checks |
| * Debugging C:: GDB and C |
| * Debugging C plus plus:: GDB features for C++ |
| |
| |
| File: gdb.info, Node: C Operators, Next: C Constants, Up: C |
| |
| 12.4.1.1 C and C++ operators |
| ............................ |
| |
| Operators must be defined on values of specific types. For instance, |
| `+' is defined on numbers, but not on structures. Operators are often |
| defined on groups of types. |
| |
| For the purposes of C and C++, the following definitions hold: |
| |
| * _Integral types_ include `int' with any of its storage-class |
| specifiers; `char'; `enum'; and, for C++, `bool'. |
| |
| * _Floating-point types_ include `float', `double', and `long |
| double' (if supported by the target platform). |
| |
| * _Pointer types_ include all types defined as `(TYPE *)'. |
| |
| * _Scalar types_ include all of the above. |
| |
| |
| The following operators are supported. They are listed here in order |
| of increasing precedence: |
| |
| `,' |
| The comma or sequencing operator. Expressions in a |
| comma-separated list are evaluated from left to right, with the |
| result of the entire expression being the last expression |
| evaluated. |
| |
| `=' |
| Assignment. The value of an assignment expression is the value |
| assigned. Defined on scalar types. |
| |
| `OP=' |
| Used in an expression of the form `A OP= B', and translated to |
| `A = A OP B'. `OP=' and `=' have the same precedence. OP is any |
| one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', |
| `/', `%'. |
| |
| `?:' |
| The ternary operator. `A ? B : C' can be thought of as: if A |
| then B else C. A should be of an integral type. |
| |
| `||' |
| Logical OR. Defined on integral types. |
| |
| `&&' |
| Logical AND. Defined on integral types. |
| |
| `|' |
| Bitwise OR. Defined on integral types. |
| |
| `^' |
| Bitwise exclusive-OR. Defined on integral types. |
| |
| `&' |
| Bitwise AND. Defined on integral types. |
| |
| `==, !=' |
| Equality and inequality. Defined on scalar types. The value of |
| these expressions is 0 for false and non-zero for true. |
| |
| `<, >, <=, >=' |
| Less than, greater than, less than or equal, greater than or equal. |
| Defined on scalar types. The value of these expressions is 0 for |
| false and non-zero for true. |
| |
| `<<, >>' |
| left shift, and right shift. Defined on integral types. |
| |
| `@' |
| The GDB "artificial array" operator (*note Expressions: |
| Expressions.). |
| |
| `+, -' |
| Addition and subtraction. Defined on integral types, |
| floating-point types and pointer types. |
| |
| `*, /, %' |
| Multiplication, division, and modulus. Multiplication and |
| division are defined on integral and floating-point types. |
| Modulus is defined on integral types. |
| |
| `++, --' |
| Increment and decrement. When appearing before a variable, the |
| operation is performed before the variable is used in an |
| expression; when appearing after it, the variable's value is used |
| before the operation takes place. |
| |
| `*' |
| Pointer dereferencing. Defined on pointer types. Same precedence |
| as `++'. |
| |
| `&' |
| Address operator. Defined on variables. Same precedence as `++'. |
| |
| For debugging C++, GDB implements a use of `&' beyond what is |
| allowed in the C++ language itself: you can use `&(&REF)' (or, if |
| you prefer, simply `&&REF') to examine the address where a C++ |
| reference variable (declared with `&REF') is stored. |
| |
| `-' |
| Negative. Defined on integral and floating-point types. Same |
| precedence as `++'. |
| |
| `!' |
| Logical negation. Defined on integral types. Same precedence as |
| `++'. |
| |
| `~' |
| Bitwise complement operator. Defined on integral types. Same |
| precedence as `++'. |
| |
| `., ->' |
| Structure member, and pointer-to-structure member. For |
| convenience, GDB regards the two as equivalent, choosing whether |
| to dereference a pointer based on the stored type information. |
| Defined on `struct' and `union' data. |
| |
| `.*, ->*' |
| Dereferences of pointers to members. |
| |
| `[]' |
| Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence |
| as `->'. |
| |
| `()' |
| Function parameter list. Same precedence as `->'. |
| |
| `::' |
| C++ scope resolution operator. Defined on `struct', `union', and |
| `class' types. |
| |
| `::' |
| Doubled colons also represent the GDB scope operator (*note |
| Expressions: Expressions.). Same precedence as `::', above. |
| |
| If an operator is redefined in the user code, GDB usually attempts |
| to invoke the redefined version instead of using the operator's |
| predefined meaning. |
| |
| * Menu: |
| |
| * C Constants:: |
| |
| |
| File: gdb.info, Node: C Constants, Next: C plus plus expressions, Prev: C Operators, Up: C |
| |
| 12.4.1.2 C and C++ constants |
| ............................ |
| |
| GDB allows you to express the constants of C and C++ in the following |
| ways: |
| |
| * Integer constants are a sequence of digits. Octal constants are |
| specified by a leading `0' (i.e. zero), and hexadecimal constants |
| by a leading `0x' or `0X'. Constants may also end with a letter |
| `l', specifying that the constant should be treated as a `long' |
| value. |
| |
| * Floating point constants are a sequence of digits, followed by a |
| decimal point, followed by a sequence of digits, and optionally |
| followed by an exponent. An exponent is of the form: |
| `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' |
| is optional for positive exponents. A floating-point constant may |
| also end with a letter `f' or `F', specifying that the constant |
| should be treated as being of the `float' (as opposed to the |
| default `double') type; or with a letter `l' or `L', which |
| specifies a `long double' constant. |
| |
| * Enumerated constants consist of enumerated identifiers, or their |
| integral equivalents. |
| |
| * Character constants are a single character surrounded by single |
| quotes (`''), or a number--the ordinal value of the corresponding |
| character (usually its ASCII value). Within quotes, the single |
| character may be represented by a letter or by "escape sequences", |
| which are of the form `\NNN', where NNN is the octal representation |
| of the character's ordinal value; or of the form `\X', where `X' |
| is a predefined special character--for example, `\n' for newline. |
| |
| * String constants are a sequence of character constants surrounded |
| by double quotes (`"'). Any valid character constant (as described |
| above) may appear. Double quotes within the string must be |
| preceded by a backslash, so for instance `"a\"b'c"' is a string of |
| five characters. |
| |
| * Pointer constants are an integral value. You can also write |
| pointers to constants using the C operator `&'. |
| |
| * Array constants are comma-separated lists surrounded by braces `{' |
| and `}'; for example, `{1,2,3}' is a three-element array of |
| integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and |
| `{&"hi", &"there", &"fred"}' is a three-element array of pointers. |
| |
| * Menu: |
| |
| * C plus plus expressions:: |
| * C Defaults:: |
| * C Checks:: |
| |
| * Debugging C:: |
| |
| |
| File: gdb.info, Node: C plus plus expressions, Next: C Defaults, Prev: C Constants, Up: C |
| |
| 12.4.1.3 C++ expressions |
| ........................ |
| |
| GDB expression handling can interpret most C++ expressions. |
| |
| _Warning:_ GDB can only debug C++ code if you use the proper |
| compiler and the proper debug format. Currently, GDB works best |
| when debugging C++ code that is compiled with GCC 2.95.3 or with |
| GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. |
| DWARF 2 is preferred over stabs+. Most configurations of GCC emit |
| either DWARF 2 or stabs+ as their default debug format, so you |
| usually don't need to specify a debug format explicitly. Other |
| compilers and/or debug formats are likely to work badly or not at |
| all when using GDB to debug C++ code. |
| |
| 1. Member function calls are allowed; you can use expressions like |
| |
| count = aml->GetOriginal(x, y) |
| |
| 2. While a member function is active (in the selected stack frame), |
| your expressions have the same namespace available as the member |
| function; that is, GDB allows implicit references to the class |
| instance pointer `this' following the same rules as C++. |
| |
| 3. You can call overloaded functions; GDB resolves the function call |
| to the right definition, with some restrictions. GDB does not |
| perform overload resolution involving user-defined type |
| conversions, calls to constructors, or instantiations of templates |
| that do not exist in the program. It also cannot handle ellipsis |
| argument lists or default arguments. |
| |
| It does perform integral conversions and promotions, floating-point |
| promotions, arithmetic conversions, pointer conversions, |
| conversions of class objects to base classes, and standard |
| conversions such as those of functions or arrays to pointers; it |
| requires an exact match on the number of function arguments. |
| |
| Overload resolution is always performed, unless you have specified |
| `set overload-resolution off'. *Note GDB features for C++: |
| Debugging C plus plus. |
| |
| You must specify `set overload-resolution off' in order to use an |
| explicit function signature to call an overloaded function, as in |
| p 'foo(char,int)'('x', 13) |
| |
| The GDB command-completion facility can simplify this; see *Note |
| Command completion: Completion. |
| |
| 4. GDB understands variables declared as C++ references; you can use |
| them in expressions just as you do in C++ source--they are |
| automatically dereferenced. |
| |
| In the parameter list shown when GDB displays a frame, the values |
| of reference variables are not displayed (unlike other variables); |
| this avoids clutter, since references are often used for large |
| structures. The _address_ of a reference variable is always |
| shown, unless you have specified `set print address off'. |
| |
| 5. GDB supports the C++ name resolution operator `::'--your |
| expressions can use it just as expressions in your program do. |
| Since one scope may be defined in another, you can use `::' |
| repeatedly if necessary, for example in an expression like |
| `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by |
| reference to source files, in both C and C++ debugging (*note |
| Program variables: Variables.). |
| |
| In addition, when used with HP's C++ compiler, GDB supports calling |
| virtual functions correctly, printing out virtual bases of objects, |
| calling functions in a base subobject, casting objects, and invoking |
| user-defined operators. |
| |
| |
| File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C plus plus expressions, Up: C |
| |
| 12.4.1.4 C and C++ defaults |
| ........................... |
| |
| If you allow GDB to set type and range checking automatically, they |
| both default to `off' whenever the working language changes to C or |
| C++. This happens regardless of whether you or GDB selects the working |
| language. |
| |
| If you allow GDB to set the language automatically, it recognizes |
| source files whose names end with `.c', `.C', or `.cc', etc, and when |
| GDB enters code compiled from one of these files, it sets the working |
| language to C or C++. *Note Having GDB infer the source language: |
| Automatically, for further details. |
| |
| |
| File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C |
| |
| 12.4.1.5 C and C++ type and range checks |
| ........................................ |
| |
| By default, when GDB parses C or C++ expressions, type checking is not |
| used. However, if you turn type checking on, GDB considers two |
| variables type equivalent if: |
| |
| * The two variables are structured and have the same structure, |
| union, or enumerated tag. |
| |
| * The two variables have the same type name, or types that have been |
| declared equivalent through `typedef'. |
| |
| |
| Range checking, if turned on, is done on mathematical operations. |
| Array indices are not checked, since they are often used to index a |
| pointer that is not itself an array. |
| |
| |
| File: gdb.info, Node: Debugging C, Next: Debugging C plus plus, Prev: C Checks, Up: C |
| |
| 12.4.1.6 GDB and C |
| .................. |
| |
| The `set print union' and `show print union' commands apply to the |
| `union' type. When set to `on', any `union' that is inside a `struct' |
| or `class' is also printed. Otherwise, it appears as `{...}'. |
| |
| The `@' operator aids in the debugging of dynamic arrays, formed |
| with pointers and a memory allocation function. *Note Expressions: |
| Expressions. |
| |
| * Menu: |
| |
| * Debugging C plus plus:: |
| |
| |
| File: gdb.info, Node: Debugging C plus plus, Prev: Debugging C, Up: C |
| |
| 12.4.1.7 GDB features for C++ |
| ............................. |
| |
| Some GDB commands are particularly useful with C++, and some are |
| designed specifically for use with C++. Here is a summary: |
| |
| `breakpoint menus' |
| When you want a breakpoint in a function whose name is overloaded, |
| GDB breakpoint menus help you specify which function definition |
| you want. *Note Breakpoint menus: Breakpoint Menus. |
| |
| `rbreak REGEX' |
| Setting breakpoints using regular expressions is helpful for |
| setting breakpoints on overloaded functions that are not members |
| of any special classes. *Note Setting breakpoints: Set Breaks. |
| |
| `catch throw' |
| `catch catch' |
| Debug C++ exception handling using these commands. *Note Setting |
| catchpoints: Set Catchpoints. |
| |
| `ptype TYPENAME' |
| Print inheritance relationships as well as other information for |
| type TYPENAME. *Note Examining the Symbol Table: Symbols. |
| |
| `set print demangle' |
| `show print demangle' |
| `set print asm-demangle' |
| `show print asm-demangle' |
| Control whether C++ symbols display in their source form, both when |
| displaying code as C++ source and when displaying disassemblies. |
| *Note Print settings: Print Settings. |
| |
| `set print object' |
| `show print object' |
| Choose whether to print derived (actual) or declared types of |
| objects. *Note Print settings: Print Settings. |
| |
| `set print vtbl' |
| `show print vtbl' |
| Control the format for printing virtual function tables. *Note |
| Print settings: Print Settings. (The `vtbl' commands do not work |
| on programs compiled with the HP ANSI C++ compiler (`aCC').) |
| |
| `set overload-resolution on' |
| Enable overload resolution for C++ expression evaluation. The |
| default is on. For overloaded functions, GDB evaluates the |
| arguments and searches for a function whose signature matches the |
| argument types, using the standard C++ conversion rules (see *Note |
| C++ expressions: C plus plus expressions, for details). If it |
| cannot find a match, it emits a message. |
| |
| `set overload-resolution off' |
| Disable overload resolution for C++ expression evaluation. For |
| overloaded functions that are not class member functions, GDB |
| chooses the first function of the specified name that it finds in |
| the symbol table, whether or not its arguments are of the correct |
| type. For overloaded functions that are class member functions, |
| GDB searches for a function whose signature _exactly_ matches the |
| argument types. |
| |
| `show overload-resolution' |
| Show the current setting of overload resolution. |
| |
| `Overloaded symbol names' |
| You can specify a particular definition of an overloaded symbol, |
| using the same notation that is used to declare such symbols in |
| C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also |
| use the GDB command-line word completion facilities to list the |
| available choices, or to finish the type list for you. *Note |
| Command completion: Completion, for details on how to do this. |
| |
| |
| File: gdb.info, Node: Objective-C, Next: Fortran, Prev: C, Up: Supported languages |
| |
| 12.4.2 Objective-C |
| ------------------ |
| |
| This section provides information about some commands and command |
| options that are useful for debugging Objective-C code. See also *Note |
| info classes: Symbols, and *Note info selectors: Symbols, for a few |
| more commands specific to Objective-C support. |
| |
| * Menu: |
| |
| * Method Names in Commands:: |
| * The Print Command with Objective-C:: |
| |
| |
| File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Prev: Objective-C, Up: Objective-C |
| |
| 12.4.2.1 Method Names in Commands |
| ................................. |
| |
| The following commands have been extended to accept Objective-C method |
| names as line specifications: |
| |
| * `clear' |
| |
| * `break' |
| |
| * `info line' |
| |
| * `jump' |
| |
| * `list' |
| |
| A fully qualified Objective-C method name is specified as |
| |
| -[CLASS METHODNAME] |
| |
| where the minus sign is used to indicate an instance method and a |
| plus sign (not shown) is used to indicate a class method. The class |
| name CLASS and method name METHODNAME are enclosed in brackets, similar |
| to the way messages are specified in Objective-C source code. For |
| example, to set a breakpoint at the `create' instance method of class |
| `Fruit' in the program currently being debugged, enter: |
| |
| break -[Fruit create] |
| |
| To list ten program lines around the `initialize' class method, |
| enter: |
| |
| list +[NSText initialize] |
| |
| In the current version of GDB, the plus or minus sign is required. |
| In future versions of GDB, the plus or minus sign will be optional, but |
| you can use it to narrow the search. It is also possible to specify |
| just a method name: |
| |
| break create |
| |
| You must specify the complete method name, including any colons. If |
| your program's source files contain more than one `create' method, |
| you'll be presented with a numbered list of classes that implement that |
| method. Indicate your choice by number, or type `0' to exit if none |
| apply. |
| |
| As another example, to clear a breakpoint established at the |
| `makeKeyAndOrderFront:' method of the `NSWindow' class, enter: |
| |
| clear -[NSWindow makeKeyAndOrderFront:] |
| |
| |
| File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C |
| |
| 12.4.2.2 The Print Command With Objective-C |
| ........................................... |
| |
| The print command has also been extended to accept methods. For |
| example: |
| |
| print -[OBJECT hash] |
| |
| will tell GDB to send the `hash' message to OBJECT and print the |
| result. Also, an additional command has been added, `print-object' or |
| `po' for short, which is meant to print the description of an object. |
| However, this command may only work with certain Objective-C libraries |
| that have a particular hook function, `_NSPrintForDebugger', defined. |
| |
| |
| File: gdb.info, Node: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported languages |
| |
| 12.4.3 Fortran |
| -------------- |
| |
| GDB can be used to debug programs written in Fortran, but it currently |
| supports only the features of Fortran 77 language. |
| |
| Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers |
| among them) append an underscore to the names of variables and |
| functions. When you debug programs compiled by those compilers, you |
| will need to refer to variables and functions with a trailing |
| underscore. |
| |
| * Menu: |
| |
| * Fortran Operators:: Fortran operators and expressions |
| * Fortran Defaults:: Default settings for Fortran |
| * Special Fortran commands:: Special GDB commands for Fortran |
| |
| |
| File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran |
| |
| 12.4.3.1 Fortran operators and expressions |
| .......................................... |
| |
| Operators must be defined on values of specific types. For instance, |
| `+' is defined on numbers, but not on characters or other non- |
| arithmetic types. Operators are often defined on groups of types. |
| |
| `**' |
| The exponentiation operator. It raises the first operand to the |
| power of the second one. |
| |
| `:' |
| The range operator. Normally used in the form of array(low:high) |
| to represent a section of array. |
| |
| |
| File: gdb.info, Node: Fortran Defaults, Next: Special Fortran commands, Prev: Fortran Operators, Up: Fortran |
| |
| 12.4.3.2 Fortran Defaults |
| ......................... |
| |
| Fortran symbols are usually case-insensitive, so GDB by default uses |
| case-insensitive matches for Fortran symbols. You can change that with |
| the `set case-insensitive' command, see *Note Symbols::, for the |
| details. |
| |
| |
| File: gdb.info, Node: Special Fortran commands, Prev: Fortran Defaults, Up: Fortran |
| |
| 12.4.3.3 Special Fortran commands |
| ................................. |
| |
| GDB had some commands to support Fortran specific feature, such as |
| common block displaying. |
| |
| `info common [COMMON-NAME]' |
| This command prints the values contained in the Fortran `COMMON' |
| block whose name is COMMON-NAME. With no argument, the names of |
| all `COMMON' blocks visible at current program location are |
| printed. |
| |
| |
| File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported languages |
| |
| 12.4.4 Pascal |
| ------------- |
| |
| Debugging Pascal programs which use sets, subranges, file variables, or |
| nested functions does not currently work. GDB does not support |
| entering expressions, printing values, or similar features using Pascal |
| syntax. |
| |
| The Pascal-specific command `set print pascal_static-members' |
| controls whether static members of Pascal objects are displayed. *Note |
| pascal_static-members: Print Settings. |
| |
| |
| File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported languages |
| |
| 12.4.5 Modula-2 |
| --------------- |
| |
| The extensions made to GDB to support Modula-2 only support output from |
| the GNU Modula-2 compiler (which is currently being developed). Other |
| Modula-2 compilers are not currently supported, and attempting to debug |
| executables produced by them is most likely to give an error as GDB |
| reads in the executable's symbol table. |
| |
| * Menu: |
| |
| * M2 Operators:: Built-in operators |
| * Built-In Func/Proc:: Built-in functions and procedures |
| * M2 Constants:: Modula-2 constants |
| * M2 Types:: Modula-2 types |
| * M2 Defaults:: Default settings for Modula-2 |
| * Deviations:: Deviations from standard Modula-2 |
| * M2 Checks:: Modula-2 type and range checks |
| * M2 Scope:: The scope operators `::' and `.' |
| * GDB/M2:: GDB and Modula-2 |
| |
| |
| File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 |
| |
| 12.4.5.1 Operators |
| .................. |
| |
| Operators must be defined on values of specific types. For instance, |
| `+' is defined on numbers, but not on structures. Operators are often |
| defined on groups of types. For the purposes of Modula-2, the |
| following definitions hold: |
| |
| * _Integral types_ consist of `INTEGER', `CARDINAL', and their |
| subranges. |
| |
| * _Character types_ consist of `CHAR' and its subranges. |
| |
| * _Floating-point types_ consist of `REAL'. |
| |
| * _Pointer types_ consist of anything declared as `POINTER TO TYPE'. |
| |
| * _Scalar types_ consist of all of the above. |
| |
| * _Set types_ consist of `SET' and `BITSET' types. |
| |
| * _Boolean types_ consist of `BOOLEAN'. |
| |
| The following operators are supported, and appear in order of |
| increasing precedence: |
| |
| `,' |
| Function argument or array index separator. |
| |
| `:=' |
| Assignment. The value of VAR `:=' VALUE is VALUE. |
| |
| `<, >' |
| Less than, greater than on integral, floating-point, or enumerated |
| types. |
| |
| `<=, >=' |
| Less than or equal to, greater than or equal to on integral, |
| floating-point and enumerated types, or set inclusion on set |
| types. Same precedence as `<'. |
| |
| `=, <>, #' |
| Equality and two ways of expressing inequality, valid on scalar |
| types. Same precedence as `<'. In GDB scripts, only `<>' is |
| available for inequality, since `#' conflicts with the script |
| comment character. |
| |
| `IN' |
| Set membership. Defined on set types and the types of their |
| members. Same precedence as `<'. |
| |
| `OR' |
| Boolean disjunction. Defined on boolean types. |
| |
| `AND, &' |
| Boolean conjunction. Defined on boolean types. |
| |
| `@' |
| The GDB "artificial array" operator (*note Expressions: |
| Expressions.). |
| |
| `+, -' |
| Addition and subtraction on integral and floating-point types, or |
| union and difference on set types. |
| |
| `*' |
| Multiplication on integral and floating-point types, or set |
| intersection on set types. |
| |
| `/' |
| Division on floating-point types, or symmetric set difference on |
| set types. Same precedence as `*'. |
| |
| `DIV, MOD' |
| Integer division and remainder. Defined on integral types. Same |
| precedence as `*'. |
| |
| `-' |
| Negative. Defined on `INTEGER' and `REAL' data. |
| |
| `^' |
| Pointer dereferencing. Defined on pointer types. |
| |
| `NOT' |
| Boolean negation. Defined on boolean types. Same precedence as |
| `^'. |
| |
| `.' |
| `RECORD' field selector. Defined on `RECORD' data. Same |
| precedence as `^'. |
| |
| `[]' |
| Array indexing. Defined on `ARRAY' data. Same precedence as `^'. |
| |
| `()' |
| Procedure argument list. Defined on `PROCEDURE' objects. Same |
| precedence as `^'. |
| |
| `::, .' |
| GDB and Modula-2 scope operators. |
| |
| _Warning:_ Set expressions and their operations are not yet |
| supported, so GDB treats the use of the operator `IN', or the use |
| of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' |
| on sets as an error. |
| |
| |
| File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 |
| |
| 12.4.5.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 Types, Prev: Built-In Func/Proc, Up: Modula-2 |
| |
| 12.4.5.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 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 |
| |
| 12.4.5.4 Modula-2 Types |
| ....................... |
| |
| Currently GDB can print the following data types in Modula-2 syntax: |
| array types, record types, set types, pointer types, procedure types, |
| enumerated types, subrange types and base types. You can also print |
| the contents of variables declared using these type. This section |
| gives a number of simple source code examples together with sample GDB |
| sessions. |
| |
| The first example contains the following section of code: |
| |
| VAR |
| s: SET OF CHAR ; |
| r: [20..40] ; |
| |
| and you can request GDB to interrogate the type and value of `r' and |
| `s'. |
| |
| (gdb) print s |
| {'A'..'C', 'Z'} |
| (gdb) ptype s |
| SET OF CHAR |
| (gdb) print r |
| 21 |
| (gdb) ptype r |
| [20..40] |
| |
| Likewise if your source code declares `s' as: |
| |
| VAR |
| s: SET ['A'..'Z'] ; |
| |
| then you may query the type of `s' by: |
| |
| (gdb) ptype s |
| type = SET ['A'..'Z'] |
| |
| Note that at present you cannot interactively manipulate set |
| expressions using the debugger. |
| |
| The following example shows how you might declare an array in |
| Modula-2 and how you can interact with GDB to print its type and |
| contents: |
| |
| VAR |
| s: ARRAY [-10..10] OF CHAR ; |
| |
| (gdb) ptype s |
| ARRAY [-10..10] OF CHAR |
| |
| Note that the array handling is not yet complete and although the |
| type is printed correctly, expression handling still assumes that all |
| arrays have a lower bound of zero and not `-10' as in the example |
| above. Unbounded arrays are also not yet recognized in GDB. |
| |
| Here are some more type related Modula-2 examples: |
| |
| TYPE |
| colour = (blue, red, yellow, green) ; |
| t = [blue..yellow] ; |
| VAR |
| s: t ; |
| BEGIN |
| s := blue ; |
| |
| The GDB interaction shows how you can query the data type and value of |
| a variable. |
| |
| (gdb) print s |
| $1 = blue |
| (gdb) ptype t |
| type = [blue..yellow] |
| |
| In this example a Modula-2 array is declared and its contents |
| displayed. Observe that the contents are written in the same way as |
| their `C' counterparts. |
| |
| VAR |
| s: ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| s[1] := 1 ; |
| |
| (gdb) print s |
| $1 = {1, 0, 0, 0, 0} |
| (gdb) ptype s |
| type = ARRAY [1..5] OF CARDINAL |
| |
| The Modula-2 language interface to GDB also understands pointer |
| types as shown in this example: |
| |
| VAR |
| s: POINTER TO ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| NEW(s) ; |
| s^[1] := 1 ; |
| |
| and you can request that GDB describes the type of `s'. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [1..5] OF CARDINAL |
| |
| GDB handles compound types as we can see in this example. Here we |
| combine array types, record types, pointer types and subrange types: |
| |
| TYPE |
| foo = RECORD |
| f1: CARDINAL ; |
| f2: CHAR ; |
| f3: myarray ; |
| END ; |
| |
| myarray = ARRAY myrange OF CARDINAL ; |
| myrange = [-2..2] ; |
| VAR |
| s: POINTER TO ARRAY myrange OF foo ; |
| |
| and you can ask GDB to describe the type of `s' as shown below. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [-2..2] OF foo = RECORD |
| f1 : CARDINAL; |
| f2 : CHAR; |
| f3 : ARRAY [-2..2] OF CARDINAL; |
| END |
| |
| |
| File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 |
| |
| 12.4.5.5 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.5.6 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.5.7 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.5.8 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.5.9 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: Supported languages |
| |
| 12.4.6 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.6.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.6.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 is limited support for array and record aggregates. They are |
| permitted only on the right sides of assignments, as in these |
| examples: |
| |
| set An_Array := (1, 2, 3, 4, 5, 6) |
| set An_Array := (1, others => 0) |
| set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) |
| set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) |
| set A_Record := (1, "Peter", True); |
| set A_Record := (Name => "Peter", Id => 1, Alive => True) |
| |
| Changing a discriminant's value by assigning an aggregate has an |
| undefined effect if that discriminant is used within the record. |
| However, you can first modify discriminants by directly assigning |
| to them (which normally would not be allowed in Ada), and then |
| performing an aggregate assignment. For example, given a variable |
| `A_Rec' declared to have a type such as: |
| |
| type Rec (Len : Small_Integer := 0) is record |
| Id : Integer; |
| Vals : IntArray (1 .. Len); |
| end record; |
| |
| you can assign a value with a different size of `Vals' with two |
| assignments: |
| |
| set A_Rec.Len := 4 |
| set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) |
| |
| As this example also illustrates, GDB is very loose about the usual |
| rules concerning aggregates. You may leave out some of the |
| components of an array or record aggregate (such as the `Len' |
| component in the assignment to `A_Rec' above); they will retain |
| their original values upon assignment. You may freely use dynamic |
| values as indices in component associations. You may even use |
| overlapping or redundant component associations, although which |
| component values are assigned in such cases is not defined. |
| |
| * 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.6.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 <JMPBUF_SAVE>[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.6.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.6.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: Supported languages, 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'. |
| |
| `set case-sensitive on' |
| `set case-sensitive off' |
| `set case-sensitive auto' |
| Normally, when GDB looks up symbols, it matches their names with |
| case sensitivity determined by the current source language. |
| Occasionally, you may wish to control that. The command `set |
| case-sensitive' lets you do that by specifying `on' for |
| case-sensitive matches or `off' for case-insensitive ones. If you |
| specify `auto', case sensitivity is reset to the default suitable |
| for the source language. The default is case-sensitive matches |
| for all languages except for Fortran, for which the default is |
| case-insensitive matches. |
| |
| `show case-sensitive' |
| This command shows the current setting of case sensitivity for |
| symbols lookups. |
| |
| `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 [ARG]' |
| Print the data type of ARG, which can be either an expression or a |
| data type. With no argument, print the data type of `$', the last |
| value in the value history. If ARG is an expression, it is not |
| actually evaluated, and any side-effecting operations (such as |
| assignments or function calls) inside it do not take place. If |
| ARG is a type name, it may be the name of a type or typedef, or |
| for C code it may have the form `class CLASS-NAME', `struct |
| STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note |
| Expressions: Expressions. |
| |
| `ptype [ARG]' |
| `ptype' accepts the same arguments as `whatis', but prints a |
| detailed description of the type, instead of just the name of the |
| type. *Note Expressions: Expressions. |
| |
| 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. |
| |
| Sometimes, programs use opaque data types or incomplete |
| specifications of complex data structure. If the debug |
| information included in the program does not allow GDB to display |
| a full declaration of the data type, it will say `<incomplete |
| type>'. For example, given these declarations: |
| |
| struct foo; |
| struct foo *fooptr; |
| |
| but no definition for `struct foo' itself, GDB will say: |
| |
| (gdb) ptype foo |
| $1 = <incomplete type> |
| |
| "Incomplete type" is C terminology for data types that are not |
| completely specified. |
| |
| `info types REGEXP' |
| `info types' |
| Print a brief description of all types whose names match the |
| regular expression 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 LOCATION' |
| List all the variables local to a particular scope. This command |
| accepts a LOCATION argument--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 (e.g. `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: |
| {<no data fields>} |
| |
| `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 <RET> 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 |
| ============================== |
| |
| `print EXPR' |
| Evaluate the expression EXPR and display the resuling value. EXPR |
| may include calls to functions in the program being debugged. |
| |
| `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 that does not return anything |
| (a.k.a. "a void function"), but without cluttering the output with |
| `void' returned values that GDB will otherwise print. If the |
| result is not void, it is printed and saved in the value history. |
| |
| It is possible for the function you call via the `print' or `call' |
| command to generate a signal (e.g., if there's a bug in the function, |
| or if you passed it incorrect arguments). What happens in that case is |
| controlled by the `set unwindonsignal' command. |
| |
| `set unwindonsignal' |
| Set unwinding of the stack if a signal is received while in a |
| function that GDB called in the program being debugged. If set to |
| on, GDB unwinds the stack it created for the call and restores the |
| context to what it was before the call. If set to off (the |
| default), GDB stops in the frame where the signal was received. |
| |
| `show unwindonsignal' |
| Show the current setting of stack unwinding in the functions |
| called by GDB. |
| |
| Sometimes, a function you wish to call is actually a "weak alias" |
| for another function. In such case, GDB might not pick up the type |
| information, including the types of the function arguments, which |
| causes GDB to call the inferior function incorrectly. As a result, the |
| called function will function erroneously and may even crash. A |
| solution to that is to use the name of the aliased function instead. |
| |
| |
| 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. Or you are debugging a remote target via `gdbserver' (*note |
| file: Server.). 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. |
| |
| You can load unlinked object `.o' files into GDB using the `file' |
| command. You will not be able to "run" an object file, but you |
| can disassemble functions and inspect variables. Also, if the |
| underlying BFD functionality supports it, you could use `gdb |
| -write' to patch object files using this technique. Note that GDB |
| can neither interpret nor modify relocations in this case, so |
| branches and some initialized variables will appear to go to the |
| wrong place. But this feature is still handy from time to time. |
| |
| `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 |
| some 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 <RET> 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 ]' |
| `file FILENAME [ -readnow ]' |
| 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. |
| |
| `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 ]' |
| `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 <RET> after using |
| it. |
| |
| `add-symbol-file-from-memory ADDRESS' |
| Load symbols from the given ADDRESS in a dynamically loaded object |
| file whose image is mapped directly into the inferior's memory. |
| For example, the Linux kernel maps a `syscall DSO' into each |
| process's address space; this DSO provides kernel-specific code for |
| some system calls. The argument can be any expression whose |
| evaluation yields the address of the file's shared object file |
| header. For this command to work, you must have used |
| `symbol-file' or `exec-file' commands in advance. |
| |
| `add-shared-symbol-files LIBRARY-FILE' |
| `assf LIBRARY-FILE' |
| The `add-shared-symbol-files' command can currently be used only |
| in the Cygwin build of GDB on MS-Windows OS, where it is an alias |
| for the `dll-symbols' command (*note Cygwin Native::). GDB |
| automatically looks for shared libraries, however if GDB does not |
| find yours, you can invoke `add-shared-symbol-files'. It takes |
| one argument: the shared library's file name. `assf' is a |
| shorthand alias for `add-shared-symbol-files'. |
| |
| `section SECTION ADDR' |
| The `section' command changes the base address of the named |
| 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. |
| |
| `show trust-readonly-sections' |
| Show the current setting of trusting readonly sections. |
| |
| 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 GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and |
| IBM RS/6000 AIX 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'. |
| |
| If your program uses lots of shared libraries with debug info that |
| takes large amounts of memory, you can decrease the GDB memory |
| footprint by preventing it from automatically loading the symbols |
| from shared libraries. To that end, type `set auto-solib-add off' |
| before running the inferior, then load each library whose debug |
| symbols you do need with `sharedlibrary REGEXP', where REGEXP is a |
| regular expresion that matches the libraries whose symbols you |
| want to be loaded. |
| |
| `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. |
| |
| `nosharedlibrary' |
| Unload all shared object library symbols. This discards all |
| symbols that have been loaded from all shared libraries. Symbols |
| from shared libraries that were loaded by explicit user requests |
| are not discarded. |
| |
| Sometimes you may wish that GDB stops and gives you control when any |
| of shared library events happen. Use the `set stop-on-solib-events' |
| command for this: |
| |
| `set stop-on-solib-events' |
| This command controls whether GDB should give you control when the |
| dynamic linker notifies it about some shared library event. The |
| most common event of interest is loading or unloading of a new |
| shared library. |
| |
| `show stop-on-solib-events' |
| Show whether GDB stops and gives you control when shared library |
| events happen. |
| |
| 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. |
| |
| For remote debugging, 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.). |
| |
| It is possible to build GDB for several different "target |
| architectures". When GDB is built like that, you can choose one of the |
| available architectures with the `set architecture' command. |
| |
| `set architecture ARCH' |
| This command sets the current target architecture to ARCH. The |
| value of ARCH can be `"auto"', in addition to one of the supported |
| architectures. |
| |
| `show architecture' |
| Show the current target architecture. |
| |
| `set processor' |
| `processor' |
| These are alias commands for, respectively, `set architecture' and |
| `show architecture'. |
| |
| * Menu: |
| |
| * Active Targets:: Active targets |
| * Target Commands:: Commands for managing targets |
| * Byte Order:: Choosing target byte order |
| * Remote:: Remote debugging |
| |
| |
| 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 <RET> 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 MEDIUM' |
| A remote system connected to GDB via a serial line or network |
| connection. This command tells GDB to use its own remote protocol |
| over MEDIUM for debugging. *Note Remote Debugging::. |
| |
| For example, if you have a board connected to `/dev/ttya' on the |
| machine running GDB, you could say: |
| |
| target remote /dev/ttya |
| |
| `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. You may wish to |
| control various aspects of this process. |
| |
| `set hash' |
| This command controls whether a hash mark `#' is displayed while |
| downloading a file to the remote monitor. If on, a hash mark is |
| displayed after each S-record is successfully downloaded to the |
| monitor. |
| |
| `show hash' |
| Show the current status of displaying the hash mark. |
| |
| `set debug monitor' |
| Enable or disable display of communications messages between GDB |
| and the remote monitor. |
| |
| `show debug monitor' |
| Show the current status of displaying communications between GDB |
| and the remote monitor. |
| |
| `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. |
| |
| Depending on the remote side capabilities, GDB may be able to load |
| programs into flash memory. |
| |
| `load' does not repeat if you press <RET> 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, 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. |
| |
| Once you've connected to the remote target, GDB allows you to send |
| arbitrary commands to the remote monitor: |
| |
| `remote COMMAND' |
| Send an arbitrary COMMAND string to the remote monitor. |
| |
| |
| 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 |
| * 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. |
| |
| GDB can communicate with the target over a serial line, or over an |
| IP network using TCP or UDP. In each case, GDB uses the same protocol |
| for debugging your program; only the medium carrying the debugging |
| packets varies. The `target remote' command establishes a connection |
| to the target. Its arguments indicate which medium to use: |
| |
| `target remote SERIAL-DEVICE' |
| Use SERIAL-DEVICE to communicate with the target. For example, to |
| use a serial line connected to the device named `/dev/ttyb': |
| |
| target remote /dev/ttyb |
| |
| If you're using a serial line, you may want to give GDB the |
| `--baud' option, or use the `set remotebaud' command (*note set |
| remotebaud: Remote configuration.) before the `target' command. |
| |
| `target remote `HOST:PORT'' |
| `target remote `tcp:HOST:PORT'' |
| Debug using a TCP connection to PORT on HOST. The HOST may be |
| either a host name or a numeric IP address; PORT must be a decimal |
| number. The HOST could be the target machine itself, if it is |
| directly connected to the net, or it might be a terminal server |
| which in turn has a serial line to the target. |
| |
| 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 for 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. |
| |
| `target remote `udp:HOST:PORT'' |
| Debug using UDP packets to PORT on HOST. 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. |
| |
| `target remote | COMMAND' |
| Run COMMAND in the background and communicate with it using a |
| pipe. The COMMAND is a shell command, to be parsed and expanded |
| by the system's command shell, `/bin/sh'; it should expect remote |
| protocol packets on its standard input, and send replies on its |
| standard output. You could use this to run a stand-alone simulator |
| that speaks the remote debugging protocol, to make net connections |
| using programs like `ssh', or for other similar tricks. |
| |
| If COMMAND closes its standard output (perhaps by exiting), GDB |
| will try to send it a `SIGTERM' signal. (If the program has |
| already exited, this will have no effect.) |
| |
| |
| Once the connection has been established, 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 `Ctrl-c'), 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. |
| |
| `monitor CMD' |
| This command allows you to send arbitrary commands directly to the |
| remote monitor. Since GDB doesn't care about the commands it |
| sends like this, this command is the way to extend GDB--you can |
| add new commands that only the external monitor will understand |
| and implement. |
| |
| |
| File: gdb.info, Node: Server, Next: Remote configuration, 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. However, if you want to load |
| the symbols (as you normally would), do that with the `file' |
| command, and issue it _before_ connecting to the server; |
| otherwise, you will get an error message saying `"Program is |
| already running"', since the program is considered running after |
| the connection. |
| |
| |
| ---------- Footnotes ---------- |
| |
| (1) If you choose a port number that conflicts with another service, |
| `gdbserver' prints an error message and exits. |
| |
| |
| File: gdb.info, Node: Remote configuration, Next: remote stub, Prev: Server, Up: Remote Debugging |
| |
| 17.3 Remote configuration |
| ========================= |
| |
| This section documents the configuration options available when |
| debugging remote programs. For the options related to the File I/O |
| extensions of the remote protocol, see *Note system-call-allowed: |
| system. |
| |
| `set remoteaddresssize BITS' |
| Set the maximum size of address in a memory packet to the specified |
| number of bits. GDB will mask off the address bits above that |
| number, when it passes addresses to the remote target. The |
| default value is the number of bits in the target's address. |
| |
| `show remoteaddresssize' |
| Show the current value of remote address size in bits. |
| |
| `set remotebaud N' |
| Set the baud rate for the remote serial I/O to N baud. The value |
| is used to set the speed of the serial port used for debugging |
| remote targets. |
| |
| `show remotebaud' |
| Show the current speed of the remote connection. |
| |
| `set remotebreak' |
| If set to on, GDB sends a `BREAK' signal to the remote when you |
| type `Ctrl-c' to interrupt the program running on the remote. If |
| set to off, GDB sends the `Ctrl-C' character instead. The default |
| is off, since most remote systems expect to see `Ctrl-C' as the |
| interrupt signal. |
| |
| `show remotebreak' |
| Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote |
| program. |
| |
| `set remotedevice DEVICE' |
| Set the name of the serial port through which to communicate to the |
| remote target to DEVICE. This is the device used by GDB to open |
| the serial communications line to the remote target. There's no |
| default, so you must set a valid port name for the remote serial |
| communications to work. (Some varieties of the `target' command |
| accept the port name as part of their arguments.) |
| |
| `show remotedevice' |
| Show the current name of the serial port. |
| |
| `set remotelogbase BASE' |
| Set the base (a.k.a. radix) of logging serial protocol |
| communications to BASE. Supported values of BASE are: `ascii', |
| `octal', and `hex'. The default is `ascii'. |
| |
| `show remotelogbase' |
| Show the current setting of the radix for logging remote serial |
| protocol. |
| |
| `set remotelogfile FILE' |
| Record remote serial communications on the named FILE. The |
| default is not to record at all. |
| |
| `show remotelogfile.' |
| Show the current setting of the file name on which to record the |
| serial communications. |
| |
| `set remotetimeout NUM' |
| Set the timeout limit to wait for the remote target to respond to |
| NUM seconds. The default is 2 seconds. |
| |
| `show remotetimeout' |
| Show the current number of seconds to wait for the remote target |
| responses. |
| |
| `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. |
| |
| The GDB remote protocol autodetects the packets supported by your |
| debugging stub. If you need to override the autodetection, you can use |
| these commands to enable or disable individual packets. Each packet |
| can be set to `on' (the remote target supports this packet), `off' (the |
| remote target does not support this packet), or `auto' (detect remote |
| target support for this packet). They all default to `auto'. For more |
| information about each packet, see *Note Remote Protocol::. |
| |
| During normal use, you should not have to use any of these commands. |
| If you do, that may be a bug in your remote debugging stub, or a bug in |
| GDB. You may want to report the problem to the GDB developers. |
| |
| The available settings are: |
| |
| Command Name Remote Packet Related Features |
| `fetch-register-packet'`p' `info registers' |
| `set-register-packet' `P' `set' |
| `binary-download-packet'`X' `load', `set' |
| `read-aux-vector-packet'`qXfer:auxv:read'`info auxv' |
| `symbol-lookup-packet' `qSymbol' Detecting multiple |
| threads |
| `verbose-resume-packet'`vCont' Stepping or resuming |
| multiple threads |
| `software-breakpoint-packet'`Z0' `break' |
| `hardware-breakpoint-packet'`Z1' `hbreak' |
| `write-watchpoint-packet'`Z2' `watch' |
| `read-watchpoint-packet'`Z3' `rwatch' |
| `access-watchpoint-packet'`Z4' `awatch' |
| `get-thread-local-storage-address-packet'`qGetTLSAddr' Displaying `__thread' |
| variables |
| `supported-packets' `qSupported' Remote communications |
| parameters |
| |
| |
| File: gdb.info, Node: remote stub, Prev: Remote configuration, Up: Remote Debugging |
| |
| 17.4 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.4.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.4.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.4.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 |
| * Hurd Native:: Features specific to GNU Hurd |
| * Neutrino:: Features specific to QNX Neutrino |
| |
| |
| 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 the "Process Control Block" (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 and compatible systems 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 information about the process running your program, or about any |
| process running on your system. `info proc' works only on SVR4 systems |
| that include the `procfs' code. This includes, as of this writing, |
| GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not |
| HP-UX, for example. |
| |
| `info proc' |
| `info proc PROCESS-ID' |
| Summarize available information about any running process. If a |
| process ID is specified by PROCESS-ID, display information about |
| that process; otherwise display information about the program being |
| debugged. The summary includes the debugged process ID, the |
| command line used to invoke it, its current working directory, and |
| its executable file's absolute file name. |
| |
| On some systems, PROCESS-ID can be of the form `[PID]/TID' which |
| specifies a certain thread ID within a process. If the optional |
| PID part is missing, it means a thread from the process being |
| debugged (the leading `/' still needs to be present, or else GDB |
| will interpret the number as a process ID rather than a thread ID). |
| |
| `info proc mappings' |
| Report the memory address space ranges accessible in the program, |
| with information on whether the process has read, write, or |
| execute access rights to each range. On GNU/Linux systems, each |
| memory range includes the object file which is mapped to that |
| range, instead of the memory access rights to that range. |
| |
| `info proc stat' |
| `info proc status' |
| These subcommands are specific to GNU/Linux systems. They show |
| the process-related information, including the user ID and group |
| ID; how many threads are there in the process; its virtual memory |
| usage; the signals that are pending, blocked, and ignored; its |
| TTY; its consumption of system and user time; its stack size; its |
| `nice' value; etc. For more information, see the `proc' man page |
| (type `man 5 proc' from your shell prompt). |
| |
| `info proc all' |
| Show all the information about the process described under all of |
| the above `info proc' subcommands. |
| |
| `set procfs-trace' |
| This command enables and disables tracing of `procfs' API calls. |
| |
| `show procfs-trace' |
| Show the current state of `procfs' API call tracing. |
| |
| `set procfs-file FILE' |
| Tell GDB to write `procfs' API trace to the named FILE. GDB |
| appends the trace info to the previous contents of the file. The |
| default is to display the trace on the standard output. |
| |
| `show procfs-file' |
| Show the file to which `procfs' API trace is written. |
| |
| `proc-trace-entry' |
| `proc-trace-exit' |
| `proc-untrace-entry' |
| `proc-untrace-exit' |
| These commands enable and disable tracing of entries into and exits |
| from the `syscall' interface. |
| |
| `info pidlist' |
| For QNX Neutrino only, this command displays the list of all the |
| processes and all the threads within each process. |
| |
| `info meminfo' |
| For QNX Neutrino only, this command displays the list of all |
| mapinfos. |
| |
| |
| 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 a port of the 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 ADDR is a linear address which 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 a 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 shows 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 |
| clearly shows that this DPMI server maps the addresses in |
| conventional memory 1:1, i.e. the physical (`0x00029000' + |
| `0x110') and linear (`0x29110') addresses are identical. |
| |
| This command is supported only with some DPMI servers. |
| |
| In addition to native debugging, the DJGPP port supports remote |
| debugging via a serial data link. The following commands are specific |
| to remote serial debugging in the DJGPP port of GDB. |
| |
| `set com1base ADDR' |
| This command sets the base I/O port address of the `COM1' serial |
| port. |
| |
| `set com1irq IRQ' |
| This command sets the "Interrupt Request" (`IRQ') line to use for |
| the `COM1' serial port. |
| |
| There are similar commands `set com2base', `set com3irq', etc. for |
| setting the port address and the `IRQ' lines for the other 3 COM |
| ports. |
| |
| The related commands `show com1base', `show com1irq' etc. display |
| the current settings of the base address and the `IRQ' lines used |
| by the COM ports. |
| |
| `info serial' |
| This command prints the status of the 4 DOS serial ports. For each |
| port, it prints whether it's active or not, its I/O base address |
| and IRQ number, whether it uses a 16550-style FIFO, its baudrate, |
| and the counts of various errors encountered so far. |
| |
| |
| File: gdb.info, Node: Cygwin Native, Next: Hurd 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 cygwin-exceptions MODE' |
| If MODE is `on', GDB will break on exceptions that happen inside |
| the Cygwin DLL. If MODE is `off', GDB will delay recognition of |
| exceptions, and may ignore some exceptions which seem to be caused |
| by internal Cygwin DLL "bookkeeping". This option is meant |
| primarily for debugging the Cygwin DLL itself; the default value |
| is `off' to avoid annoying GDB users with false `SIGSEGV' signals. |
| |
| `show cygwin-exceptions' |
| Displays whether GDB will break on exceptions that happen inside |
| the Cygwin DLL itself. |
| |
| `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 kernel events |
| related to the debuggee seen by the debugger. This includes |
| events that signal thread and process creation and exit, DLL |
| loading and unloading, console interrupts, and debugging messages |
| produced by the Windows `OutputDebugString' API call. |
| |
| `set debugexec' |
| This boolean value adds debug output concerning execute events |
| (such as resume thread) seen by the debugger. |
| |
| `set debugexceptions' |
| This boolean value adds debug output concerning exceptions in the |
| debuggee seen by the debugger. |
| |
| `set debugmemory' |
| This boolean value adds debug output concerning debuggee memory |
| reads and writes 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 <cygwin1!__argv>: 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: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native |
| |
| 18.1.6 Commands specific to GNU Hurd systems |
| -------------------------------------------- |
| |
| This subsection describes GDB commands specific to the GNU Hurd native |
| debugging. |
| |
| `set signals' |
| `set sigs' |
| This command toggles the state of inferior signal interception by |
| GDB. Mach exceptions, such as breakpoint traps, are not affected |
| by this command. `sigs' is a shorthand alias for `signals'. |
| |
| `show signals' |
| `show sigs' |
| Show the current state of intercepting inferior's signals. |
| |
| `set signal-thread' |
| `set sigthread' |
| This command tells GDB which thread is the `libc' signal thread. |
| That thread is run when a signal is delivered to a running |
| process. `set sigthread' is the shorthand alias of `set |
| signal-thread'. |
| |
| `show signal-thread' |
| `show sigthread' |
| These two commands show which thread will run when the inferior is |
| delivered a signal. |
| |
| `set stopped' |
| This commands tells GDB that the inferior process is stopped, as |
| with the `SIGSTOP' signal. The stopped process can be continued |
| by delivering a signal to it. |
| |
| `show stopped' |
| This command shows whether GDB thinks the debuggee is stopped. |
| |
| `set exceptions' |
| Use this command to turn off trapping of exceptions in the |
| inferior. When exception trapping is off, neither breakpoints nor |
| single-stepping will work. To restore the default, set exception |
| trapping on. |
| |
| `show exceptions' |
| Show the current state of trapping exceptions in the inferior. |
| |
| `set task pause' |
| This command toggles task suspension when GDB has control. |
| Setting it to on takes effect immediately, and the task is |
| suspended whenever GDB gets control. Setting it to off will take |
| effect the next time the inferior is continued. If this option is |
| set to off, you can use `set thread default pause on' or `set |
| thread pause on' (see below) to pause individual threads. |
| |
| `show task pause' |
| Show the current state of task suspension. |
| |
| `set task detach-suspend-count' |
| This command sets the suspend count the task will be left with when |
| GDB detaches from it. |
| |
| `show task detach-suspend-count' |
| Show the suspend count the task will be left with when detaching. |
| |
| `set task exception-port' |
| `set task excp' |
| This command sets the task exception port to which GDB will |
| forward exceptions. The argument should be the value of the "send |
| rights" of the task. `set task excp' is a shorthand alias. |
| |
| `set noninvasive' |
| This command switches GDB to a mode that is the least invasive as |
| far as interfering with the inferior is concerned. This is the |
| same as using `set task pause', `set exceptions', and `set |
| signals' to values opposite to the defaults. |
| |
| `info send-rights' |
| `info receive-rights' |
| `info port-rights' |
| `info port-sets' |
| `info dead-names' |
| `info ports' |
| `info psets' |
| These commands display information about, respectively, send |
| rights, receive rights, port rights, port sets, and dead names of |
| a task. There are also shorthand aliases: `info ports' for `info |
| port-rights' and `info psets' for `info port-sets'. |
| |
| `set thread pause' |
| This command toggles current thread suspension when GDB has |
| control. Setting it to on takes effect immediately, and the |
| current thread is suspended whenever GDB gets control. Setting it |
| to off will take effect the next time the inferior is continued. |
| Normally, this command has no effect, since when GDB has control, |
| the whole task is suspended. However, if you used `set task pause |
| off' (see above), this command comes in handy to suspend only the |
| current thread. |
| |
| `show thread pause' |
| This command shows the state of current thread suspension. |
| |
| `set thread run' |
| This comamnd sets whether the current thread is allowed to run. |
| |
| `show thread run' |
| Show whether the current thread is allowed to run. |
| |
| `set thread detach-suspend-count' |
| This command sets the suspend count GDB will leave on a thread |
| when detaching. This number is relative to the suspend count |
| found by GDB when it notices the thread; use `set thread |
| takeover-suspend-count' to force it to an absolute value. |
| |
| `show thread detach-suspend-count' |
| Show the suspend count GDB will leave on the thread when detaching. |
| |
| `set thread exception-port' |
| `set thread excp' |
| Set the thread exception port to which to forward exceptions. This |
| overrides the port set by `set task exception-port' (see above). |
| `set thread excp' is the shorthand alias. |
| |
| `set thread takeover-suspend-count' |
| Normally, GDB's thread suspend counts are relative to the value |
| GDB finds when it notices each thread. This command changes the |
| suspend counts to be absolute instead. |
| |
| `set thread default' |
| `show thread default' |
| Each of the above `set thread' commands has a `set thread default' |
| counterpart (e.g., `set thread default pause', `set thread default |
| exception-port', etc.). The `thread default' variety of commands |
| sets the default thread properties for all threads; you can then |
| change the properties of individual threads with the non-default |
| commands. |
| |
| |
| File: gdb.info, Node: Neutrino, Prev: Hurd Native, Up: Native |
| |
| 18.1.7 QNX Neutrino |
| ------------------- |
| |
| GDB provides the following commands specific to the QNX Neutrino target: |
| |
| `set debug nto-debug' |
| When set to on, enables debugging messages specific to the QNX |
| Neutrino support. |
| |
| `show debug nto-debug' |
| Show the current state of QNX Neutrino messages. |
| |
| |
| 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. |
| |
| Whenever a specific embedded processor has a simulator, GDB allows |
| to send an arbitrary command to the simulator. |
| |
| `sim COMMAND' |
| Send an arbitrary COMMAND string to the simulator. Consult the |
| documentation for the specific simulator in use for information |
| about acceptable commands. |
| |
| * Menu: |
| |
| * ARM:: ARM RDI |
| * 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 |
| * AVR:: Atmel AVR |
| * CRIS:: CRIS |
| * Super-H:: Renesas Super-H |
| * WinCE:: Windows CE child processes |
| |
| |
| 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. |
| |
| |
| GDB provides the following ARM-specific commands: |
| |
| `set arm disassembler' |
| This commands selects from a list of disassembly styles. The |
| `"std"' style is the standard style. |
| |
| `show arm disassembler' |
| Show the current disassembly style. |
| |
| `set arm apcs32' |
| This command toggles ARM operation mode between 32-bit and 26-bit. |
| |
| `show arm apcs32' |
| Display the current usage of the ARM 32-bit mode. |
| |
| `set arm fpu FPUTYPE' |
| This command sets the ARM floating-point unit (FPU) type. The |
| argument FPUTYPE can be one of these: |
| |
| `auto' |
| Determine the FPU type by querying the OS ABI. |
| |
| `softfpa' |
| Software FPU, with mixed-endian doubles on little-endian ARM |
| processors. |
| |
| `fpa' |
| GCC-compiled FPA co-processor. |
| |
| `softvfp' |
| Software FPU with pure-endian doubles. |
| |
| `vfp' |
| VFP co-processor. |
| |
| `show arm fpu' |
| Show the current type of the FPU. |
| |
| `set arm abi' |
| This command forces GDB to use the specified ABI. |
| |
| `show arm abi' |
| Show the currently used ABI. |
| |
| `set debug arm' |
| Toggle whether to display ARM-specific debugging messages from the |
| ARM target support subsystem. |
| |
| `show debug arm' |
| Show whether ARM-specific debugging messages are enabled. |
| |
| The following commands are available when an ARM target is debugged |
| using the RDI interface: |
| |
| `rdilogfile [FILE]' |
| Set the filename for the ADP (Angel Debugger Protocol) packet log. |
| With an argument, sets the log file to the specified FILE. With |
| no argument, show the current log file name. The default log file |
| is `rdi.log'. |
| |
| `rdilogenable [ARG]' |
| Control logging of ADP packets. With an argument of 1 or `"yes"' |
| enables logging, with an argument 0 or `"no"' disables it. With |
| no arguments displays the current setting. When logging is |
| enabled, ADP packets exchanged between GDB and the RDI target |
| device are logged to a file. |
| |
| `set rdiromatzero' |
| Tell GDB whether the target has ROM at address 0. If on, vector |
| catching is disabled, so that zero address can be used. If off |
| (the default), vector catching is enabled. For this command to |
| take effect, it needs to be invoked prior to the `target rdi' |
| command. |
| |
| `show rdiromatzero' |
| Show the current setting of ROM at zero address. |
| |
| `set rdiheartbeat' |
| Enable or disable RDI heartbeat packets. It is not recommended to |
| turn on this option, since it confuses ARM and EPI JTAG interface, |
| as well as the Angel monitor. |
| |
| `show rdiheartbeat' |
| Show the setting of RDI heartbeat packets. |
| |
| |
| 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.6, 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 `Ctrl-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. |
| |
| The following special commands are available when debugging with the |
| Renesas E7000 ICE: |
| |
| `e7000 COMMAND' |
| This sends the specified COMMAND to the E7000 monitor. |
| |
| `ftplogin MACHINE USERNAME PASSWORD DIR' |
| This command records information for subsequent interface with the |
| E7000 monitor via the FTP protocol: GDB will log into the named |
| MACHINE using specified USERNAME and PASSWORD, and then chdir to |
| the named directory DIR. |
| |
| `ftpload FILE' |
| This command uses credentials recorded by `ftplogin' to fetch and |
| load the named FILE from the E7000 monitor. |
| |
| `drain' |
| This command drains any pending text buffers stored on the E7000. |
| |
| `set usehardbreakpoints' |
| `show usehardbreakpoints' |
| These commands set and show the use of hardware breakpoints for all |
| breakpoints. *Note hardware-assisted breakpoint: Set Breaks, for |
| more information about using hardware breakpoints selectively. |
| |
| |
| 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 and M32R/SDI |
| ---------------------------------- |
| |
| `target m32r DEV' |
| Renesas M32R/D ROM monitor. |
| |
| `target m32rsdi DEV' |
| Renesas M32R SDI server, connected via parallel port to the board. |
| |
| The following GDB commands are specific to the M32R monitor: |
| |
| `set download-path PATH' |
| Set the default path for finding donwloadable SREC files. |
| |
| `show download-path' |
| Show the default path for downloadable SREC files. |
| |
| `set board-address ADDR' |
| Set the IP address for the M32R-EVA target board. |
| |
| `show board-address' |
| Show the current IP address of the target board. |
| |
| `set server-address ADDR' |
| Set the IP address for the download server, which is the GDB's |
| host machine. |
| |
| `show server-address' |
| Display the IP address of the download server. |
| |
| `upload [FILE]' |
| Upload the specified SREC FILE via the monitor's Ethernet upload |
| capability. If no FILE argument is given, the current executable |
| file is uploaded. |
| |
| `tload [FILE]' |
| Test the `upload' command. |
| |
| The following commands are available for M32R/SDI: |
| |
| `sdireset' |
| This command resets the SDI connection. |
| |
| `sdistatus' |
| This command shows the SDI connection status. |
| |
| `debug_chaos' |
| Instructs the remote that M32R/Chaos debugging is to be used. |
| |
| `use_debug_dma' |
| Instructs the remote to use the DEBUG_DMA method of accessing |
| memory. |
| |
| `use_mon_code' |
| Instructs the remote to use the MON_CODE method of accessing |
| memory. |
| |
| `use_ib_break' |
| Instructs the remote to set breakpoints by IB break. |
| |
| `use_dbt_break' |
| Instructs the remote to set breakpoints by DBT. |
| |
| |
| 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 mipsfpu double' |
| `set mipsfpu single' |
| `set mipsfpu none' |
| `set mipsfpu auto' |
| `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 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. |
| |
| `set syn-garbage-limit NUM' |
| Limit the maximum number of characters GDB should ignore when it |
| tries to synchronize with the remote target. The default is 10 |
| characters. Setting the limit to -1 means there's no limit. |
| |
| `show syn-garbage-limit' |
| Show the current limit on the number of characters to ignore when |
| trying to synchronize with the remote system. |
| |
| `set monitor-prompt PROMPT' |
| Tell GDB to expect the specified PROMPT string from the remote |
| monitor. The default depends on the target: |
| pmon target |
| `PMON' |
| |
| ddb target |
| `NEC010' |
| |
| lsi target |
| `PMON>' |
| |
| `show monitor-prompt' |
| Show the current strings GDB expects as the prompt from the remote |
| monitor. |
| |
| `set monitor-warnings' |
| Enable or disable monitor warnings about hardware breakpoints. |
| This has effect only for the `lsi' target. When on, GDB will |
| display warning messages whose codes are returned by the `lsi' |
| PMON monitor for breakpoint commands. |
| |
| `show monitor-warnings' |
| Show the current setting of printing monitor warnings. |
| |
| `pmon COMMAND' |
| This command allows sending an arbitrary COMMAND string to the |
| monitor. The monitor must be in debug mode for this to work. |
| |
| |
| 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). |
| |
| The following commands specifi to the SDS protocol are supported |
| byGDB: |
| |
| `set sdstimeout NSEC' |
| Set the timeout for SDS protocol reads to be NSEC seconds. The |
| default is 2 seconds. |
| |
| `show sdstimeout' |
| Show the current value of the SDS timeout. |
| |
| `sds COMMAND' |
| Send the specified COMMAND string to the SDS monitor. |
| |
| |
| 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: |
| `<RET> ~ .' (Return, followed by tilde and period) or `<RET> ~ |
| Ctrl-d' (Return, followed by tilde and control-D). |
| |
| |
| File: gdb.info, Node: Z8000, Next: AVR, 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: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors |
| |
| 18.3.15 Atmel AVR |
| ----------------- |
| |
| When configured for debugging the Atmel AVR, GDB supports the following |
| AVR-specific commands: |
| |
| `info io_registers' |
| This command displays information about the AVR I/O registers. For |
| each register, GDB prints its number and value. |
| |
| |
| File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors |
| |
| 18.3.16 CRIS |
| ------------ |
| |
| When configured for debugging CRIS, GDB provides the following |
| CRIS-specific commands: |
| |
| `set cris-version VER' |
| Set the current CRIS version to VER, either `10' or `32'. The |
| CRIS version affects register names and sizes. This command is |
| useful in case autodetection of the CRIS version fails. |
| |
| `show cris-version' |
| Show the current CRIS version. |
| |
| `set cris-dwarf2-cfi' |
| Set the usage of DWARF-2 CFI for CRIS debugging. The default is |
| `on'. Change to `off' when using `gcc-cris' whose version is below |
| `R59'. |
| |
| `show cris-dwarf2-cfi' |
| Show the current state of using DWARF-2 CFI. |
| |
| `set cris-mode MODE' |
| Set the current CRIS mode to MODE. It should only be changed when |
| debugging in guru mode, in which case it should be set to `guru' |
| (the default is `normal'). |
| |
| `show cris-mode' |
| Show the current CRIS mode. |
| |
| |
| File: gdb.info, Node: Super-H, Next: WinCE, Prev: CRIS, Up: Embedded Processors |
| |
| 18.3.17 Renesas Super-H |
| ----------------------- |
| |
| For the Renesas Super-H processor, GDB provides these commands: |
| |
| `regs' |
| Show the values of all Super-H registers. |
| |
| |
| File: gdb.info, Node: WinCE, Prev: Super-H, Up: Embedded Processors |
| |
| 18.3.18 Windows CE |
| ------------------ |
| |
| The following commands are available for Windows CE: |
| |
| `set remotedirectory DIR' |
| Tell GDB to upload files from the named directory DIR. The |
| default is `/gdb', i.e. the root directory on the current drive. |
| |
| `show remotedirectory' |
| Show the current value of the upload directory. |
| |
| `set remoteupload METHOD' |
| Set the method used to upload files to remote device. Valid values |
| for METHOD are `always', `newer', and `never'. The default is |
| `newer'. |
| |
| `show remoteupload' |
| Show the current setting of the upload method. |
| |
| `set remoteaddhost' |
| Tell GDB whether to add this host to the remote stub's arguments |
| when you debug over a network. |
| |
| `show remoteaddhost' |
| Show whether to add this host to remote stub's arguments when |
| debugging over a network. |
| |
| |
| 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: |
| |
| * i386:: |
| * A29K:: |
| * Alpha:: |
| * MIPS:: |
| * HPPA:: HP PA architecture |
| |
| |
| File: gdb.info, Node: i386, Next: A29K, Up: Architectures |
| |
| 18.4.1 x86 Architecture-specific issues. |
| ---------------------------------------- |
| |
| `set struct-convention MODE' |
| Set the convention used by the inferior to return `struct's and |
| `union's from functions to MODE. Possible values of MODE are |
| `"pcc"', `"reg"', and `"default"' (the default). `"default"' or |
| `"pcc"' means that `struct's are returned on the stack, while |
| `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, |
| or 8 bytes will be returned in a register. |
| |
| `show struct-convention' |
| Show the current setting of the convention to return `struct's |
| from functions. |
| |
| |
| File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures |
| |
| 18.4.2 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.3 Alpha |
| ------------ |
| |
| See the following section. |
| |
| |
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
| |
| 18.4.4 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. You should only need to use this |
| command when debugging a stripped executable. |
| |
| `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. |
| |
| Several MIPS-specific commands are available when debugging MIPS |
| programs: |
| |
| `set mips saved-gpreg-size SIZE' |
| Set the size of MIPS general-purpose registers saved on the stack. |
| The argument SIZE can be one of the following: |
| |
| `32' |
| 32-bit GP registers |
| |
| `64' |
| 64-bit GP registers |
| |
| `auto' |
| Use the target's default setting or autodetect the saved size |
| from the information contained in the executable. This is |
| the default |
| |
| `show mips saved-gpreg-size' |
| Show the current size of MIPS GP registers on the stack. |
| |
| `set mips stack-arg-size SIZE' |
| Set the amount of stack space reserved for arguments to functions. |
| The argument can be one of `"32"', `"64"' or `"auto"' (the |
| default). |
| |
| `set mips abi ARG' |
| Tell GDB which MIPS ABI is used by the inferior. Possible values |
| of ARG are: |
| |
| `auto' |
| The default ABI associated with the current binary (this is |
| the default). |
| |
| `o32' |
| |
| `o64' |
| |
| `n32' |
| |
| `n64' |
| |
| `eabi32' |
| |
| `eabi64' |
| |
| `auto' |
| |
| `show mips abi' |
| Show the MIPS ABI used by GDB to debug the inferior. |
| |
| `set mipsfpu' |
| `show mipsfpu' |
| *Note set mipsfpu: MIPS Embedded. |
| |
| `set mips mask-address ARG' |
| This command determines whether the most-significant 32 bits of |
| 64-bit MIPS addresses are masked off. The argument ARG can be |
| `on', `off', or `auto'. The latter is the default setting, which |
| lets GDB determine the correct value. |
| |
| `show mips mask-address' |
| Show whether the upper 32 bits of MIPS addresses are masked off or |
| not. |
| |
| `set remote-mips64-transfers-32bit-regs' |
| This command controls compatibility with 64-bit MIPS targets that |
| transfer data in 32-bit quantities. If you have an old MIPS 64 |
| target that transfers 32 bits for some registers, like SR and FSR, |
| and 64 bits for other registers, set this option to `on'. |
| |
| `show remote-mips64-transfers-32bit-regs' |
| Show the current setting of compatibility with older MIPS 64 |
| targets. |
| |
| `set debug mips' |
| This command turns on and off debugging messages for the |
| MIPS-specific target code in GDB. |
| |
| `show debug mips' |
| Show the current setting of MIPS debugging messages. |
| |
| |
| File: gdb.info, Node: HPPA, Prev: MIPS, Up: Architectures |
| |
| 18.4.5 HPPA |
| ----------- |
| |
| When GDB is debugging te HP PA architecture, it provides the following |
| special commands: |
| |
| `set debug hppa' |
| THis command determines whether HPPA architecture specific |
| debugging messages are to be displayed. |
| |
| `show debug hppa' |
| Show whether HPPA debugging messages are displayed. |
| |
| `maint print unwind ADDRESS' |
| This command displays the contents of the unwind table entry at the |
| given ADDRESS. |
| |
| |
| |
| 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 |
| * Command 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: Command 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: Command 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. |
| |
| 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 <RET> 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. |
| |
| 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: Command 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 <RET> 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. |
| |
| `set pagination on' |
| `set pagination off' |
| Turn the output pagination on or off; the default is on. Turning |
| pagination off is the alternative to `set height 0'. |
| |
| `show pagination' |
| Show the current pagination mode. |
| |
| |
| 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 |
| neither begin with `0' or `0x', nor end with a `.' 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 commands described below. |
| |
| `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 input radix; for |
| example, any of |
| |
| set input-radix 012 |
| set input-radix 10. |
| set input-radix 0xa |
| |
| sets the input base to decimal. On the other hand, `set |
| input-radix 10' leaves the input radix unchanged, no matter what |
| it was, since `10', being without any leading or trailing signs of |
| its base, is interpreted in the current radix. Thus, if the |
| current radix is 16, `10' is interpreted in hex, i.e. as 16 |
| decimal, which doesn't change the radix. |
| |
| `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 input radix. |
| |
| `show input-radix' |
| Display the current default base for numeric input. |
| |
| `show output-radix' |
| Display the current default base for numeric display. |
| |
| `set radix [BASE]' |
| `show radix' |
| These commands set and show the default base for both input and |
| output of numbers. `set radix' sets the radix of input and output |
| to the same base; without an argument, it resets the radix back to |
| its default value of 10. |
| |
| |
| |
| 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. |
| |
| `show coerce-float-to-double' |
| Show the current setting of promoting `float' to `double'. |
| |
| 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. |
| |
| |
| If you need to debug user-defined commands or sourced files you may |
| find it useful to enable "command tracing". In this mode each command |
| will be printed as it is executed, prefixed with one or more `+' |
| symbols, the quantity denoting the call depth of each command. |
| |
| `set trace-commands on' |
| Enable command tracing. |
| |
| `set trace-commands off' |
| Disable command tracing. |
| |
| `show trace-commands' |
| Display the current state of command tracing. |
| |
| |
| File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB |
| |
| 19.8 Optional messages about internal happenings |
| ================================================ |
| |
| GDB has commands that enable optional debugging messages from various |
| GDB subsystems; normally these commands are of interest to GDB |
| maintainers, or when reporting a bug. This section documents those |
| commands. |
| |
| `set exec-done-display' |
| Turns on or off the notification of asynchronous commands' |
| completion. When on, GDB will print a message when an |
| asynchronous command finishes its execution. The default is off. |
| |
| `show exec-done-display' |
| Displays the current setting of asynchronous command completion |
| notification. |
| |
| `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 aix-thread' |
| Display debugging messages about inner workings of the AIX thread |
| module. |
| |
| `show debug aix-thread' |
| Show the current state of AIX thread debugging info display. |
| |
| `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 debugging info about GDB expression |
| parsing. The default is off. |
| |
| `show debug expression' |
| Displays the current state of displaying debugging info about GDB |
| expression parsing. |
| |
| `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 infrun' |
| Turns on or off display of GDB debugging info for running the |
| inferior. The default is off. `infrun.c' contains GDB's runtime |
| state machine used for implementing operations such as |
| single-stepping the inferior. |
| |
| `show debug infrun' |
| Displays the current state of GDB inferior debugging. |
| |
| `set debug lin-lwp' |
| Turns on or off debugging messages from the Linux LWP debug |
| support. |
| |
| `show debug lin-lwp' |
| Show the current state of Linux LWP debugging messages. |
| |
| `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 solib-frv' |
| Turns on or off debugging messages for FR-V shared-library code. |
| |
| `show debug solib-frv' |
| Display the current state of FR-V shared-library code debugging |
| messages. |
| |
| `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 debugvarobj' |
| Turns on or off display of GDB variable object debugging info. The |
| default is off. |
| |
| `show debugvarobj' |
| 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:: How to define your own commands |
| * Hooks:: Hooks for user-defined commands |
| * Command Files:: How to write scripts of commands to be stored in a file |
| * 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 |
| end |
| |
| 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. |
| |
| In addition, `$argc' may be used to find out how many arguments have |
| been passed. This expands to a number in the range 0...10. |
| |
| define adder |
| if $argc == 2 |
| print $arg0 + $arg1 |
| end |
| if $argc == 3 |
| print $arg0 + $arg1 + $arg2 |
| end |
| end |
| |
| `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'. |
| |
| `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. |
| |
| `dont-repeat' |
| Used inside a user-defined command, this tells GDB that this |
| command should not be repeated when the user hits <RET> (*note |
| repeat last command: Command Syntax.). |
| |
| `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. |
| |
| In addition to the above commands, user-defined commands frequently |
| use control flow commands, described in *Note Command Files::. |
| |
| 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 infinite |
| 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 text file made 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. |
| |
| You can request the execution of a command file with the `source' |
| command: |
| |
| `source [`-v'] FILENAME' |
| Execute the command file FILENAME. |
| |
| The lines in a command file are generally executed sequentially, |
| unless the order of execution is changed by one of the _flow-control |
| commands_ described below. The commands 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. |
| |
| GDB searches for FILENAME in the current directory and then on the |
| search path (specified with the `directory' command). |
| |
| If `-v', for verbose mode, is given then GDB displays each command |
| as it is executed. The option must be given before FILENAME, and is |
| interpreted as part of the filename anywhere else. |
| |
| 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'. |
| |
| Since commands stored on command files tend to be more general than |
| commands typed interactively, they frequently need to deal with |
| complicated situations, such as different or unexpected values of |
| variables and symbols, changes in how the program being debugged is |
| built, etc. GDB provides a set of flow-control commands to deal with |
| these complexities. Using these commands, you can write complex |
| scripts that loop over data structures, execute commands conditionally, |
| etc. |
| |
| `if' |
| `else' |
| This command allows to include in your script conditionally |
| executed commands. The `if' command 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 (its |
| value is nonzero). There can then optionally be an `else' line, |
| 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' |
| This command allows to write loops. Its 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'. These commands are called the |
| "body" of the loop. The commands in the body of `while' are |
| executed repeatedly as long as the expression evaluates to true. |
| |
| `loop_break' |
| This command exits the `while' loop in whose body it is included. |
| Execution of the script continues after that `while's `end' line. |
| |
| `loop_continue' |
| This command skips the execution of the rest of the body of |
| commands in the `while' loop in whose body it is included. |
| Execution branches to the beginning of the `while' loop, where it |
| evaluates the controlling expression. |
| |
| `end' |
| Terminate the block of commands that are the body of `if', `else', |
| or `while' flow-control commands. |
| |
| |
| 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: |
| |
| <PgUp> |
| Scroll the active window one page up. |
| |
| <PgDn> |
| Scroll the active window one page down. |
| |
| <Up> |
| Scroll the active window one line up. |
| |
| <Down> |
| Scroll the active window one line down. |
| |
| <Left> |
| Scroll the active window one column left. |
| |
| <Right> |
| Scroll the active window one column right. |
| |
| <C-L> |
| 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 |
| `C-p', `C-n', `C-b' and `C-f'. |
| |
| |
| 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 typing |
| `q' or `C-x s'. |
| |
| |
| 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 typing `C-L'. |
| |
| `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. |
| |
| `tabset' |
| Set the width of tab stops to be NCHARS characters. |
| |
| |
| |
| 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 <RET> 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 and is |
| activated by specifying using the `--interpreter' command line option |
| (*note Mode Options::). 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 (*note |
| GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). |
| |
| 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. |
| |
| * Menu: |
| |
| * GDB/MI Command Syntax:: |
| * GDB/MI Compatibility with CLI:: |
| * GDB/MI Development and Front Ends:: |
| * GDB/MI Output Records:: |
| * GDB/MI Simple Examples:: |
| * GDB/MI Command Description Format:: |
| * GDB/MI Breakpoint Commands:: |
| * GDB/MI Program Context:: |
| * GDB/MI Thread Commands:: |
| * GDB/MI Program Execution:: |
| * GDB/MI Stack Manipulation:: |
| * GDB/MI Variable Objects:: |
| * GDB/MI Data Manipulation:: |
| * GDB/MI Tracepoint Commands:: |
| * GDB/MI Symbol Query:: |
| * GDB/MI File Commands:: |
| * GDB/MI Target Manipulation:: |
| * GDB/MI Miscellaneous Commands:: |
| |
| |
| 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:: |
| |
| |
| 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, 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 Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI |
| |
| 24.2 GDB/MI Compatibility with CLI |
| ================================== |
| |
| For the developers convenience CLI commands can be entered directly, |
| but there may be some unexpected behaviour. For example, commands that |
| query the user will behave as if the user replied yes, breakpoint |
| command lists are not executed and some CLI commands, such as `if', |
| `when' and `define', prompt for further input with `>', which is not |
| valid MI output. |
| |
| This feature may be removed at some stage in the future and it is |
| recommended that front ends use the `-interpreter-exec' command (*note |
| -interpreter-exec::). |
| |
| |
| File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI |
| |
| 24.3 GDB/MI Development and Front Ends |
| ====================================== |
| |
| The application which takes the MI output and presents the state of the |
| program being debugged to the user is called a "front end". |
| |
| Although GDB/MI is still incomplete, it is currently being used by a |
| variety of front ends to GDB. This makes it difficult to introduce new |
| functionality without breaking existing usage. This section tries to |
| minimize the problems by describing how the protocol might change. |
| |
| Some changes in MI need not break a carefully designed front end, and |
| for these the MI version will remain unchanged. The following is a |
| list of changes that may occur within one level, so front ends should |
| parse MI output in a way that can handle them: |
| |
| * New MI commands may be added. |
| |
| * New fields may be added to the output of any MI command. |
| |
| |
| If the changes are likely to break front ends, the MI version level |
| will be increased by one. This will allow the front end to parse the |
| output according to the MI version. Apart from mi0, new versions of |
| GDB will not support old versions of MI and it will be the |
| responsibility of the front end to work with the new one. |
| |
| The best way to avoid unexpected changes in MI that might break your |
| front end is to make your project known to GDB developers and follow |
| development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. |
| There is also the mailing list <dmi-discuss@lists.freestandards.org>, |
| hosted by the Free Standards Group, which has the aim of creating a a |
| more general MI protocol called Debugger Machine Interface (DMI) that |
| will become a standard for all debuggers, not just GDB. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI |
| |
| 24.4 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.4.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. |
| |
| `"^connected"' |
| GDB has connected to a remote target. |
| |
| `"^error" "," C-STRING' |
| The operation failed. The `C-STRING' contains the corresponding |
| error message. |
| |
| `"^exit"' |
| GDB has terminated. |
| |
| |
| |
| 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.4.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. This is only present when GDB's event loop is |
| truly asynchronous, which is currently only the case for remote |
| targets. |
| |
| `"&" 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.4.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. |
| In particular, the EXEC-ASYNC-OUTPUT records. |
| |
| `*stopped,reason="REASON"' |
| |
| REASON can be one of the following: |
| |
| `breakpoint-hit' |
| A breakpoint was reached. |
| |
| `watchpoint-trigger' |
| A watchpoint was triggered. |
| |
| `read-watchpoint-trigger' |
| A read watchpoint was triggered. |
| |
| `access-watchpoint-trigger' |
| An access watchpoint was triggered. |
| |
| `function-finished' |
| An -exec-finish or similar CLI command was accomplished. |
| |
| `location-reached' |
| An -exec-until or similar CLI command was accomplished. |
| |
| `watchpoint-scope' |
| A watchpoint has gone out of scope. |
| |
| `end-stepping-range' |
| An -exec-next, -exec-next-instruction, -exec-step, |
| -exec-step-instruction or similar CLI command was accomplished. |
| |
| `exited-signalled' |
| The inferior exited because of a signal. |
| |
| `exited' |
| The inferior exited. |
| |
| `exited-normally' |
| The inferior exited normally. |
| |
| `signal-received' |
| A signal was received by the inferior. |
| |
| |
| File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI |
| |
| 24.5 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. |
| |
| Note the the line breaks shown in the examples are here only for |
| readability, they don't appear in the real output. |
| |
| Setting a breakpoint |
| -------------------- |
| |
| Setting a breakpoint generates synchronous output which contains |
| detailed information of the breakpoint. |
| |
| -> -break-insert main |
| <- ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x08048564",func="main",file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="68",times="0"} |
| <- (gdb) |
| |
| Program Execution |
| ----------------- |
| |
| Program execution generates asynchronous records and MI gives the |
| reason that execution stopped. |
| |
| -> -exec-run |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0", |
| frame={addr="0x08048564",func="main", |
| args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], |
| file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} |
| <- (gdb) |
| -> -exec-continue |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="exited-normally" |
| <- (gdb) |
| |
| Quitting GDB |
| ------------ |
| |
| Quitting GDB just prints the result class `^exit'. |
| |
| -> (gdb) |
| <- -gdb-exit |
| <- ^exit |
| |
| 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 Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI |
| |
| 24.6 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. |
| |
| 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... |
| |
| Result |
| ...... |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB CLI command(s), if any. |
| |
| Example |
| ....... |
| |
| Example(s) formatted for readability. Some of the described commands |
| have not been implemented yet and these are labeled N.A. (not |
| available). |
| |