| This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo. |
| |
| Copyright (C) 1988-2020 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.3 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 FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Tenth Edition, of 'Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 9.1. |
| |
| Copyright (C) 1988-2020 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.3 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 FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Arithmetic In Guile, Next: Types In Guile, Prev: Values From Inferior In Guile, Up: Guile API |
| |
| 23.3.3.6 Arithmetic In Guile |
| ............................ |
| |
| The '(gdb)' module provides several functions for performing arithmetic |
| on '<gdb:value>' objects. The arithmetic is performed as if it were |
| done by the target, and therefore has target semantics which are not |
| necessarily those of Scheme. For example operations work with a fixed |
| precision, not the arbitrary precision of Scheme. |
| |
| Wherever a function takes an integer or pointer as an operand, GDB |
| will convert appropriate Scheme values to perform the operation. |
| |
| -- Scheme Procedure: value-add a b |
| |
| -- Scheme Procedure: value-sub a b |
| |
| -- Scheme Procedure: value-mul a b |
| |
| -- Scheme Procedure: value-div a b |
| |
| -- Scheme Procedure: value-rem a b |
| |
| -- Scheme Procedure: value-mod a b |
| |
| -- Scheme Procedure: value-pow a b |
| |
| -- Scheme Procedure: value-not a |
| |
| -- Scheme Procedure: value-neg a |
| |
| -- Scheme Procedure: value-pos a |
| |
| -- Scheme Procedure: value-abs a |
| |
| -- Scheme Procedure: value-lsh a b |
| |
| -- Scheme Procedure: value-rsh a b |
| |
| -- Scheme Procedure: value-min a b |
| |
| -- Scheme Procedure: value-max a b |
| |
| -- Scheme Procedure: value-lognot a |
| |
| -- Scheme Procedure: value-logand a b |
| |
| -- Scheme Procedure: value-logior a b |
| |
| -- Scheme Procedure: value-logxor a b |
| |
| -- Scheme Procedure: value=? a b |
| |
| -- Scheme Procedure: value<? a b |
| |
| -- Scheme Procedure: value<=? a b |
| |
| -- Scheme Procedure: value>? a b |
| |
| -- Scheme Procedure: value>=? a b |
| |
| Scheme does not provide a 'not-equal' function, and thus Guile |
| support in GDB does not either. |
| |
| |
| File: gdb.info, Node: Types In Guile, Next: Guile Pretty Printing API, Prev: Arithmetic In Guile, Up: Guile API |
| |
| 23.3.3.7 Types In Guile |
| ....................... |
| |
| GDB represents types from the inferior in objects of type '<gdb:type>'. |
| |
| The following type-related procedures are provided by the '(gdb)' |
| module. |
| |
| -- Scheme Procedure: type? object |
| Return '#t' if OBJECT is an object of type '<gdb:type>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: lookup-type name [#:block block] |
| This function looks up a type by its NAME, which must be a string. |
| |
| If BLOCK is given, it is an object of type '<gdb:block>', and NAME |
| is looked up in that scope. Otherwise, it is searched for |
| globally. |
| |
| Ordinarily, this function will return an instance of '<gdb:type>'. |
| If the named type cannot be found, it will throw an exception. |
| |
| -- Scheme Procedure: type-code type |
| Return the type code of TYPE. The type code will be one of the |
| 'TYPE_CODE_' constants defined below. |
| |
| -- Scheme Procedure: type-tag type |
| Return the tag name of TYPE. The tag name is the name after |
| 'struct', 'union', or 'enum' in C and C++; not all languages have |
| this concept. If this type has no tag name, then '#f' is returned. |
| |
| -- Scheme Procedure: type-name type |
| Return the name of TYPE. If this type has no name, then '#f' is |
| returned. |
| |
| -- Scheme Procedure: type-print-name type |
| Return the print name of TYPE. This returns something even for |
| anonymous types. For example, for an anonymous C struct '"struct |
| {...}"' is returned. |
| |
| -- Scheme Procedure: type-sizeof type |
| Return the size of this type, in target 'char' units. Usually, a |
| target's 'char' type will be an 8-bit byte. However, on some |
| unusual platforms, this type may have a different size. |
| |
| -- Scheme Procedure: type-strip-typedefs type |
| Return a new '<gdb:type>' that represents the real type of TYPE, |
| after removing all layers of typedefs. |
| |
| -- Scheme Procedure: type-array type n1 [n2] |
| Return a new '<gdb:type>' object which represents an array of this |
| type. If one argument is given, it is the inclusive upper bound of |
| the array; in this case the lower bound is zero. If two arguments |
| are given, the first argument is the lower bound of the array, and |
| the second argument is the upper bound of the array. An array's |
| length must not be negative, but the bounds can be. |
| |
| -- Scheme Procedure: type-vector type n1 [n2] |
| Return a new '<gdb:type>' object which represents a vector of this |
| type. If one argument is given, it is the inclusive upper bound of |
| the vector; in this case the lower bound is zero. If two arguments |
| are given, the first argument is the lower bound of the vector, and |
| the second argument is the upper bound of the vector. A vector's |
| length must not be negative, but the bounds can be. |
| |
| The difference between an 'array' and a 'vector' is that arrays |
| behave like in C: when used in expressions they decay to a pointer |
| to the first element whereas vectors are treated as first class |
| values. |
| |
| -- Scheme Procedure: type-pointer type |
| Return a new '<gdb:type>' object which represents a pointer to |
| TYPE. |
| |
| -- Scheme Procedure: type-range type |
| Return a list of two elements: the low bound and high bound of |
| TYPE. If TYPE does not have a range, an exception is thrown. |
| |
| -- Scheme Procedure: type-reference type |
| Return a new '<gdb:type>' object which represents a reference to |
| TYPE. |
| |
| -- Scheme Procedure: type-target type |
| Return a new '<gdb:type>' object which represents the target type |
| of TYPE. |
| |
| For a pointer type, the target type is the type of the pointed-to |
| object. For an array type (meaning C-like arrays), the target type |
| is the type of the elements of the array. For a function or method |
| type, the target type is the type of the return value. For a |
| complex type, the target type is the type of the elements. For a |
| typedef, the target type is the aliased type. |
| |
| If the type does not have a target, this method will throw an |
| exception. |
| |
| -- Scheme Procedure: type-const type |
| Return a new '<gdb:type>' object which represents a |
| 'const'-qualified variant of TYPE. |
| |
| -- Scheme Procedure: type-volatile type |
| Return a new '<gdb:type>' object which represents a |
| 'volatile'-qualified variant of TYPE. |
| |
| -- Scheme Procedure: type-unqualified type |
| Return a new '<gdb:type>' object which represents an unqualified |
| variant of TYPE. That is, the result is neither 'const' nor |
| 'volatile'. |
| |
| -- Scheme Procedure: type-num-fields |
| Return the number of fields of '<gdb:type>' TYPE. |
| |
| -- Scheme Procedure: type-fields type |
| Return the fields of TYPE as a list. For structure and union |
| types, 'fields' has the usual meaning. Range types have two |
| fields, the minimum and maximum values. Enum types have one field |
| per enum constant. Function and method types have one field per |
| parameter. The base types of C++ classes are also represented as |
| fields. If the type has no fields, or does not fit into one of |
| these categories, an empty list will be returned. *Note Fields of |
| a type in Guile::. |
| |
| -- Scheme Procedure: make-field-iterator type |
| Return the fields of TYPE as a <gdb:iterator> object. *Note |
| Iterators In Guile::. |
| |
| -- Scheme Procedure: type-field type field-name |
| Return field named FIELD-NAME in TYPE. The result is an object of |
| type '<gdb:field>'. *Note Fields of a type in Guile::. If the |
| type does not have fields, or FIELD-NAME is not a field of TYPE, an |
| exception is thrown. |
| |
| For example, if 'some-type' is a '<gdb:type>' instance holding a |
| structure type, you can access its 'foo' field with: |
| |
| (define bar (type-field some-type "foo")) |
| |
| 'bar' will be a '<gdb:field>' object. |
| |
| -- Scheme Procedure: type-has-field? type name |
| Return '#t' if '<gdb:type>' TYPE has field named NAME. Otherwise |
| return '#f'. |
| |
| Each type has a code, which indicates what category this type falls |
| into. The available type categories are represented by constants |
| defined in the '(gdb)' module: |
| |
| 'TYPE_CODE_PTR' |
| The type is a pointer. |
| |
| 'TYPE_CODE_ARRAY' |
| The type is an array. |
| |
| 'TYPE_CODE_STRUCT' |
| The type is a structure. |
| |
| 'TYPE_CODE_UNION' |
| The type is a union. |
| |
| 'TYPE_CODE_ENUM' |
| The type is an enum. |
| |
| 'TYPE_CODE_FLAGS' |
| A bit flags type, used for things such as status registers. |
| |
| 'TYPE_CODE_FUNC' |
| The type is a function. |
| |
| 'TYPE_CODE_INT' |
| The type is an integer type. |
| |
| 'TYPE_CODE_FLT' |
| A floating point type. |
| |
| 'TYPE_CODE_VOID' |
| The special type 'void'. |
| |
| 'TYPE_CODE_SET' |
| A Pascal set type. |
| |
| 'TYPE_CODE_RANGE' |
| A range type, that is, an integer type with bounds. |
| |
| 'TYPE_CODE_STRING' |
| A string type. Note that this is only used for certain languages |
| with language-defined string types; C strings are not represented |
| this way. |
| |
| 'TYPE_CODE_BITSTRING' |
| A string of bits. It is deprecated. |
| |
| 'TYPE_CODE_ERROR' |
| An unknown or erroneous type. |
| |
| 'TYPE_CODE_METHOD' |
| A method type, as found in C++. |
| |
| 'TYPE_CODE_METHODPTR' |
| A pointer-to-member-function. |
| |
| 'TYPE_CODE_MEMBERPTR' |
| A pointer-to-member. |
| |
| 'TYPE_CODE_REF' |
| A reference type. |
| |
| 'TYPE_CODE_CHAR' |
| A character type. |
| |
| 'TYPE_CODE_BOOL' |
| A boolean type. |
| |
| 'TYPE_CODE_COMPLEX' |
| A complex float type. |
| |
| 'TYPE_CODE_TYPEDEF' |
| A typedef to some other type. |
| |
| 'TYPE_CODE_NAMESPACE' |
| A C++ namespace. |
| |
| 'TYPE_CODE_DECFLOAT' |
| A decimal floating point type. |
| |
| 'TYPE_CODE_INTERNAL_FUNCTION' |
| A function internal to GDB. This is the type used to represent |
| convenience functions (*note Convenience Funs::). |
| |
| Further support for types is provided in the '(gdb types)' Guile |
| module (*note Guile Types Module::). |
| |
| Each field is represented as an object of type '<gdb:field>'. |
| |
| The following field-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: field? object |
| Return '#t' if OBJECT is an object of type '<gdb:field>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: field-name field |
| Return the name of the field, or '#f' for anonymous fields. |
| |
| -- Scheme Procedure: field-type field |
| Return the type of the field. This is usually an instance of |
| '<gdb:type>', but it can be '#f' in some situations. |
| |
| -- Scheme Procedure: field-enumval field |
| Return the enum value represented by '<gdb:field>' FIELD. |
| |
| -- Scheme Procedure: field-bitpos field |
| Return the bit position of '<gdb:field>' FIELD. This attribute is |
| not available for 'static' fields (as in C++). |
| |
| -- Scheme Procedure: field-bitsize field |
| If the field is packed, or is a bitfield, return the size of |
| '<gdb:field>' FIELD in bits. Otherwise, zero is returned; in which |
| case the field's size is given by its type. |
| |
| -- Scheme Procedure: field-artificial? field |
| Return '#t' if the field is artificial, usually meaning that it was |
| provided by the compiler and not the user. Otherwise return '#f'. |
| |
| -- Scheme Procedure: field-base-class? field |
| Return '#t' if the field represents a base class of a C++ |
| structure. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Guile Pretty Printing API, Next: Selecting Guile Pretty-Printers, Prev: Types In Guile, Up: Guile API |
| |
| 23.3.3.8 Guile Pretty Printing API |
| .................................. |
| |
| An example output is provided (*note Pretty Printing::). |
| |
| A pretty-printer is represented by an object of type |
| <gdb:pretty-printer>. Pretty-printer objects are created with |
| 'make-pretty-printer'. |
| |
| The following pretty-printer-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: make-pretty-printer name lookup-function |
| Return a '<gdb:pretty-printer>' object named NAME. |
| |
| LOOKUP-FUNCTION is a function of one parameter: the value to be |
| printed. If the value is handled by this pretty-printer, then |
| LOOKUP-FUNCTION returns an object of type |
| <gdb:pretty-printer-worker> to perform the actual pretty-printing. |
| Otherwise LOOKUP-FUNCTION returns '#f'. |
| |
| -- Scheme Procedure: pretty-printer? object |
| Return '#t' if OBJECT is a '<gdb:pretty-printer>' object. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: pretty-printer-enabled? pretty-printer |
| Return '#t' if PRETTY-PRINTER is enabled. Otherwise return '#f'. |
| |
| -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag |
| Set the enabled flag of PRETTY-PRINTER to FLAG. The value returned |
| is unspecified. |
| |
| -- Scheme Procedure: pretty-printers |
| Return the list of global pretty-printers. |
| |
| -- Scheme Procedure: set-pretty-printers! pretty-printers |
| Set the list of global pretty-printers to PRETTY-PRINTERS. The |
| value returned is unspecified. |
| |
| -- Scheme Procedure: make-pretty-printer-worker display-hint to-string |
| children |
| Return an object of type '<gdb:pretty-printer-worker>'. |
| |
| This function takes three parameters: |
| |
| 'display-hint' |
| DISPLAY-HINT provides a hint to GDB or GDB front end via MI to |
| change the formatting of the value being printed. The value |
| must be a string or '#f' (meaning there is no hint). Several |
| values for DISPLAY-HINT are predefined by GDB: |
| |
| 'array' |
| Indicate that the object being printed is "array-like". |
| The CLI uses this to respect parameters such as 'set |
| print elements' and 'set print array'. |
| |
| 'map' |
| Indicate that the object being printed is "map-like", and |
| that the children of this value can be assumed to |
| alternate between keys and values. |
| |
| 'string' |
| Indicate that the object being printed is "string-like". |
| If the printer's 'to-string' function returns a Guile |
| string of some kind, then GDB will call its internal |
| language-specific string-printing function to format the |
| string. For the CLI this means adding quotation marks, |
| possibly escaping some characters, respecting 'set print |
| elements', and the like. |
| |
| 'to-string' |
| TO-STRING is either a function of one parameter, the |
| '<gdb:pretty-printer-worker>' object, or '#f'. |
| |
| When printing from the CLI, if the 'to-string' method exists, |
| then GDB will prepend its result to the values returned by |
| 'children'. Exactly how this formatting is done is dependent |
| on the display hint, and may change as more hints are added. |
| Also, depending on the print settings (*note Print |
| Settings::), the CLI may print just the result of 'to-string' |
| in a stack trace, omitting the result of 'children'. |
| |
| If this method returns a string, it is printed verbatim. |
| |
| Otherwise, if this method returns an instance of |
| '<gdb:value>', then GDB prints this value. This may result in |
| a call to another pretty-printer. |
| |
| If instead the method returns a Guile value which is |
| convertible to a '<gdb:value>', then GDB performs the |
| conversion and prints the resulting value. Again, this may |
| result in a call to another pretty-printer. Guile scalars |
| (integers, floats, and booleans) and strings are convertible |
| to '<gdb:value>'; other types are not. |
| |
| Finally, if this method returns '#f' then no further |
| operations are peformed in this method and nothing is printed. |
| |
| If the result is not one of these types, an exception is |
| raised. |
| |
| TO-STRING may also be '#f' in which case it is left to |
| CHILDREN to print the value. |
| |
| 'children' |
| CHILDREN is either a function of one parameter, the |
| '<gdb:pretty-printer-worker>' object, or '#f'. |
| |
| GDB will call this function on a pretty-printer to compute the |
| children of the pretty-printer's value. |
| |
| This function must return a <gdb:iterator> object. Each item |
| returned by the iterator must be a tuple holding two elements. |
| The first element is the "name" of the child; the second |
| element is the child's value. The value can be any Guile |
| object which is convertible to a GDB value. |
| |
| If CHILDREN is '#f', GDB will act as though the value has no |
| children. |
| |
| Children may be hidden from display based on the value of 'set |
| print max-depth' (*note Print Settings::). |
| |
| GDB provides a function which can be used to look up the default |
| pretty-printer for a '<gdb:value>': |
| |
| -- Scheme Procedure: default-visualizer value |
| This function takes a '<gdb:value>' object as an argument. If a |
| pretty-printer for this value exists, then it is returned. If no |
| such printer exists, then this returns '#f'. |
| |
| |
| File: gdb.info, Node: Selecting Guile Pretty-Printers, Next: Writing a Guile Pretty-Printer, Prev: Guile Pretty Printing API, Up: Guile API |
| |
| 23.3.3.9 Selecting Guile Pretty-Printers |
| ........................................ |
| |
| There are three sets of pretty-printers that GDB searches: |
| |
| * Per-objfile list of pretty-printers (*note Objfiles In Guile::). |
| * Per-progspace list of pretty-printers (*note Progspaces In |
| Guile::). |
| * The global list of pretty-printers (*note Guile Pretty Printing |
| API::). These printers are available when debugging any inferior. |
| |
| Pretty-printer lookup is done by passing the value to be printed to |
| the lookup function of each enabled object in turn. Lookup stops when a |
| lookup function returns a non-'#f' value or when the list is exhausted. |
| Lookup functions must return either a '<gdb:pretty-printer-worker>' |
| object or '#f'. Otherwise an exception is thrown. |
| |
| GDB first checks the result of 'objfile-pretty-printers' of each |
| '<gdb:objfile>' in the current program space and iteratively calls each |
| enabled lookup function in the list for that '<gdb:objfile>' until a |
| non-'#f' object is returned. If no pretty-printer is found in the |
| objfile lists, GDB then searches the result of |
| 'progspace-pretty-printers' of the current program space, calling each |
| enabled function until a non-'#f' object is returned. After these lists |
| have been exhausted, it tries the global pretty-printers list, obtained |
| with 'pretty-printers', again calling each enabled function until a |
| non-'#f' object is returned. |
| |
| The order in which the objfiles are searched is not specified. For a |
| given list, functions are always invoked from the head of the list, and |
| iterated over sequentially until the end of the list, or a |
| '<gdb:pretty-printer-worker>' object is returned. |
| |
| For various reasons a pretty-printer may not work. For example, the |
| underlying data structure may have changed and the pretty-printer is out |
| of date. |
| |
| The consequences of a broken pretty-printer are severe enough that |
| GDB provides support for enabling and disabling individual printers. |
| For example, if 'print frame-arguments' is on, a backtrace can become |
| highly illegible if any argument is printed with a broken printer. |
| |
| Pretty-printers are enabled and disabled from Scheme by calling |
| 'set-pretty-printer-enabled!'. *Note Guile Pretty Printing API::. |
| |
| |
| File: gdb.info, Node: Writing a Guile Pretty-Printer, Next: Commands In Guile, Prev: Selecting Guile Pretty-Printers, Up: Guile API |
| |
| 23.3.3.10 Writing a Guile Pretty-Printer |
| ........................................ |
| |
| A pretty-printer consists of two basic parts: a lookup function to |
| determine if the type is supported, and the printer itself. |
| |
| Here is an example showing how a 'std::string' printer might be |
| written. *Note Guile Pretty Printing API::, for details. |
| |
| (define (make-my-string-printer value) |
| "Print a my::string string" |
| (make-pretty-printer-worker |
| "string" |
| (lambda (printer) |
| (value-field value "_data")) |
| #f)) |
| |
| And here is an example showing how a lookup function for the printer |
| example above might be written. |
| |
| (define (str-lookup-function pretty-printer value) |
| (let ((tag (type-tag (value-type value)))) |
| (and tag |
| (string-prefix? "std::string<" tag) |
| (make-my-string-printer value)))) |
| |
| Then to register this printer in the global printer list: |
| |
| (append-pretty-printer! |
| (make-pretty-printer "my-string" str-lookup-function)) |
| |
| The example lookup function extracts the value's type, and attempts |
| to match it to a type that it can pretty-print. If it is a type the |
| printer can pretty-print, it will return a <gdb:pretty-printer-worker> |
| object. If not, it returns '#f'. |
| |
| We recommend that you put your core pretty-printers into a Guile |
| package. If your pretty-printers are for use with a library, we further |
| recommend embedding a version number into the package name. This |
| practice will enable GDB to load multiple versions of your |
| pretty-printers at the same time, because they will have different |
| names. |
| |
| You should write auto-loaded code (*note Guile Auto-loading::) such |
| that it can be evaluated multiple times without changing its meaning. |
| An ideal auto-load file will consist solely of 'import's of your printer |
| modules, followed by a call to a register pretty-printers with the |
| current objfile. |
| |
| Taken as a whole, this approach will scale nicely to multiple |
| inferiors, each potentially using a different library version. |
| Embedding a version number in the Guile package name will ensure that |
| GDB is able to load both sets of printers simultaneously. Then, because |
| the search for pretty-printers is done by objfile, and because your |
| auto-loaded code took care to register your library's printers with a |
| specific objfile, GDB will find the correct printers for the specific |
| version of the library used by each inferior. |
| |
| To continue the 'my::string' example, this code might appear in |
| '(my-project my-library v1)': |
| |
| (use-modules (gdb)) |
| (define (register-printers objfile) |
| (append-objfile-pretty-printer! |
| (make-pretty-printer "my-string" str-lookup-function))) |
| |
| And then the corresponding contents of the auto-load file would be: |
| |
| (use-modules (gdb) (my-project my-library v1)) |
| (register-printers (current-objfile)) |
| |
| The previous example illustrates a basic pretty-printer. There are a |
| few things that can be improved on. The printer only handles one type, |
| whereas a library typically has several types. One could install a |
| lookup function for each desired type in the library, but one could also |
| have a single lookup function recognize several types. The latter is |
| the conventional way this is handled. If a pretty-printer can handle |
| multiple data types, then its "subprinters" are the printers for the |
| individual data types. |
| |
| The '(gdb printing)' module provides a formal way of solving this |
| problem (*note Guile Printing Module::). Here is another example that |
| handles multiple types. |
| |
| These are the types we are going to pretty-print: |
| |
| struct foo { int a, b; }; |
| struct bar { struct foo x, y; }; |
| |
| Here are the printers: |
| |
| (define (make-foo-printer value) |
| "Print a foo object" |
| (make-pretty-printer-worker |
| "foo" |
| (lambda (printer) |
| (format #f "a=<~a> b=<~a>" |
| (value-field value "a") (value-field value "a"))) |
| #f)) |
| |
| (define (make-bar-printer value) |
| "Print a bar object" |
| (make-pretty-printer-worker |
| "foo" |
| (lambda (printer) |
| (format #f "x=<~a> y=<~a>" |
| (value-field value "x") (value-field value "y"))) |
| #f)) |
| |
| This example doesn't need a lookup function, that is handled by the |
| '(gdb printing)' module. Instead a function is provided to build up the |
| object that handles the lookup. |
| |
| (use-modules (gdb printing)) |
| |
| (define (build-pretty-printer) |
| (let ((pp (make-pretty-printer-collection "my-library"))) |
| (pp-collection-add-tag-printer "foo" make-foo-printer) |
| (pp-collection-add-tag-printer "bar" make-bar-printer) |
| pp)) |
| |
| And here is the autoload support: |
| |
| (use-modules (gdb) (my-library)) |
| (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer)) |
| |
| Finally, when this printer is loaded into GDB, here is the |
| corresponding output of 'info pretty-printer': |
| |
| (gdb) info pretty-printer |
| my_library.so: |
| my-library |
| foo |
| bar |
| |
| |
| File: gdb.info, Node: Commands In Guile, Next: Parameters In Guile, Prev: Writing a Guile Pretty-Printer, Up: Guile API |
| |
| 23.3.3.11 Commands In Guile |
| ........................... |
| |
| You can implement new GDB CLI commands in Guile. A CLI command object |
| is created with the 'make-command' Guile function, and added to GDB with |
| the 'register-command!' Guile function. This two-step approach is taken |
| to separate out the side-effect of adding the command to GDB from |
| 'make-command'. |
| |
| There is no support for multi-line commands, that is commands that |
| consist of multiple lines and are terminated with 'end'. |
| |
| -- Scheme Procedure: (make-command name [#:invoke invoke] |
| [#:command-class command-class] [#:completer-class completer] |
| [#:prefix? prefix] [#:doc doc-string]) |
| |
| The argument NAME is the name of the command. If NAME consists of |
| multiple words, then the initial words are looked for as prefix |
| commands. In this case, if one of the prefix commands does not |
| exist, an exception is raised. |
| |
| The result is the '<gdb:command>' object representing the command. |
| The command is not usable until it has been registered with GDB |
| with 'register-command!'. |
| |
| The rest of the arguments are optional. |
| |
| The argument INVOKE is a procedure of three arguments: SELF, ARGS |
| and FROM-TTY. The argument SELF is the '<gdb:command>' object |
| representing the command. The argument ARGS is a string |
| representing the arguments passed to the command, after leading and |
| trailing whitespace has been stripped. The argument FROM-TTY is a |
| boolean flag and specifies whether the command should consider |
| itself to have been originated from the user invoking it |
| interactively. If this function throws an exception, it is turned |
| into a GDB 'error' call. Otherwise, the return value is ignored. |
| |
| The argument COMMAND-CLASS is one of the 'COMMAND_' constants |
| defined below. This argument tells GDB how to categorize the new |
| command in the help system. The default is 'COMMAND_NONE'. |
| |
| The argument COMPLETER is either '#f', one of the 'COMPLETE_' |
| constants defined below, or a procedure, also defined below. This |
| argument tells GDB how to perform completion for this command. If |
| not provided or if the value is '#f', then no completion is |
| performed on the command. |
| |
| The argument PREFIX is a boolean flag indicating whether the new |
| command is a prefix command; sub-commands of this command may be |
| registered. |
| |
| The argument DOC-STRING is help text for the new command. If no |
| documentation string is provided, the default value "This command |
| is not documented." is used. |
| |
| -- Scheme Procedure: register-command! command |
| Add COMMAND, a '<gdb:command>' object, to GDB's list of commands. |
| It is an error to register a command more than once. The result is |
| unspecified. |
| |
| -- Scheme Procedure: command? object |
| Return '#t' if OBJECT is a '<gdb:command>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: dont-repeat |
| By default, a GDB command is repeated when the user enters a blank |
| line at the command prompt. A command can suppress this behavior |
| by invoking the 'dont-repeat' function. This is similar to the |
| user command 'dont-repeat', see *note dont-repeat: Define. |
| |
| -- Scheme Procedure: string->argv string |
| Convert a string to a list of strings split up according to GDB's |
| argv parsing rules. It is recommended to use this for consistency. |
| Arguments are separated by spaces and may be quoted. Example: |
| |
| scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") |
| $1 = ("1" "2 \"3" "4 \"5" "6 '7") |
| |
| -- Scheme Procedure: throw-user-error message . args |
| Throw a 'gdb:user-error' exception. The argument MESSAGE is the |
| error message as a format string, like the FMT argument to the |
| 'format' Scheme function. *Note (guile)Formatted Output::. The |
| argument ARGS is a list of the optional arguments of MESSAGE. |
| |
| This is used when the command detects a user error of some kind, |
| say a bad command argument. |
| |
| (gdb) guile (use-modules (gdb)) |
| (gdb) guile |
| (register-command! (make-command "test-user-error" |
| #:command-class COMMAND_OBSCURE |
| #:invoke (lambda (self arg from-tty) |
| (throw-user-error "Bad argument ~a" arg)))) |
| end |
| (gdb) test-user-error ugh |
| ERROR: Bad argument ugh |
| |
| -- completer: self text word |
| If the COMPLETER option to 'make-command' is a procedure, it takes |
| three arguments: SELF which is the '<gdb:command>' object, and TEXT |
| and WORD which are both strings. The argument TEXT holds the |
| complete command line up to the cursor's location. The argument |
| WORD holds the last word of the command line; this is computed |
| using a word-breaking heuristic. |
| |
| All forms of completion are handled by this function, that is, the |
| <TAB> and <M-?> key bindings (*note Completion::), and the |
| 'complete' command (*note complete: Help.). |
| |
| This procedure can return several kinds of values: |
| |
| * If the return value is a list, the contents of the list are |
| used as the completions. It is up to COMPLETER to ensure that |
| the contents actually do complete the word. An empty list is |
| allowed, it means that there were no completions available. |
| Only string elements of the list are used; other elements in |
| the list are ignored. |
| |
| * If the return value is a '<gdb:iterator>' object, it is |
| iterated over to obtain the completions. It is up to |
| 'completer-procedure' to ensure that the results actually do |
| complete the word. Only string elements of the result are |
| used; other elements in the sequence are ignored. |
| |
| * All other results are treated as though there were no |
| available completions. |
| |
| When a new command is registered, it will have been declared as a |
| member of some general class of commands. This is used to classify |
| top-level commands in the on-line help system; note that prefix commands |
| are not listed under their own category but rather that of their |
| top-level command. The available classifications are represented by |
| constants defined in the 'gdb' module: |
| |
| 'COMMAND_NONE' |
| The command does not belong to any particular class. A command in |
| this category will not be displayed in any of the help categories. |
| This is the default. |
| |
| 'COMMAND_RUNNING' |
| The command is related to running the inferior. For example, |
| 'start', 'step', and 'continue' are in this category. Type 'help |
| running' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_DATA' |
| The command is related to data or variables. For example, 'call', |
| 'find', and 'print' are in this category. Type 'help data' at the |
| GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_STACK' |
| The command has to do with manipulation of the stack. For example, |
| 'backtrace', 'frame', and 'return' are in this category. Type |
| 'help stack' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_FILES' |
| This class is used for file-related commands. For example, 'file', |
| 'list' and 'section' are in this category. Type 'help files' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_SUPPORT' |
| This should be used for "support facilities", generally meaning |
| things that are useful to the user when interacting with GDB, but |
| not related to the state of the inferior. For example, 'help', |
| 'make', and 'shell' are in this category. Type 'help support' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_STATUS' |
| The command is an 'info'-related command, that is, related to the |
| state of GDB itself. For example, 'info', 'macro', and 'show' are |
| in this category. Type 'help status' at the GDB prompt to see a |
| list of commands in this category. |
| |
| 'COMMAND_BREAKPOINTS' |
| The command has to do with breakpoints. For example, 'break', |
| 'clear', and 'delete' are in this category. Type 'help |
| breakpoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_TRACEPOINTS' |
| The command has to do with tracepoints. For example, 'trace', |
| 'actions', and 'tfind' are in this category. Type 'help |
| tracepoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_USER' |
| The command is a general purpose command for the user, and |
| typically does not fit in one of the other categories. Type 'help |
| user-defined' at the GDB prompt to see a list of commands in this |
| category, as well as the list of gdb macros (*note Sequences::). |
| |
| 'COMMAND_OBSCURE' |
| The command is only used in unusual circumstances, or is not of |
| general interest to users. For example, 'checkpoint', 'fork', and |
| 'stop' are in this category. Type 'help obscure' at the GDB prompt |
| to see a list of commands in this category. |
| |
| 'COMMAND_MAINTENANCE' |
| The command is only useful to GDB maintainers. The 'maintenance' |
| and 'flushregs' commands are in this category. Type 'help |
| internals' at the GDB prompt to see a list of commands in this |
| category. |
| |
| A new command can use a predefined completion function, either by |
| specifying it via an argument at initialization, or by returning it from |
| the 'completer' procedure. These predefined completion constants are |
| all defined in the 'gdb' module: |
| |
| 'COMPLETE_NONE' |
| This constant means that no completion should be done. |
| |
| 'COMPLETE_FILENAME' |
| This constant means that filename completion should be performed. |
| |
| 'COMPLETE_LOCATION' |
| This constant means that location completion should be done. *Note |
| Specify Location::. |
| |
| 'COMPLETE_COMMAND' |
| This constant means that completion should examine GDB command |
| names. |
| |
| 'COMPLETE_SYMBOL' |
| This constant means that completion should be done using symbol |
| names as the source. |
| |
| 'COMPLETE_EXPRESSION' |
| This constant means that completion should be done on expressions. |
| Often this means completing on symbol names, but some language |
| parsers also have support for completing on field names. |
| |
| The following code snippet shows how a trivial CLI command can be |
| implemented in Guile: |
| |
| (gdb) guile |
| (register-command! (make-command "hello-world" |
| #:command-class COMMAND_USER |
| #:doc "Greet the whole world." |
| #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) |
| end |
| (gdb) hello-world |
| Hello, World! |
| |
| |
| File: gdb.info, Node: Parameters In Guile, Next: Progspaces In Guile, Prev: Commands In Guile, Up: Guile API |
| |
| 23.3.3.12 Parameters In Guile |
| ............................. |
| |
| You can implement new GDB "parameters" using Guile (1). |
| |
| There are many parameters that already exist and can be set in GDB. |
| Two examples are: 'set follow-fork' and 'set charset'. Setting these |
| parameters influences certain behavior in GDB. Similarly, you can |
| define parameters that can be used to influence behavior in custom Guile |
| scripts and commands. |
| |
| A new parameter is defined with the 'make-parameter' Guile function, |
| and added to GDB with the 'register-parameter!' Guile function. This |
| two-step approach is taken to separate out the side-effect of adding the |
| parameter to GDB from 'make-parameter'. |
| |
| Parameters are exposed to the user via the 'set' and 'show' commands. |
| *Note Help::. |
| |
| -- Scheme Procedure: (make-parameter name [#:command-class |
| command-class] [#:parameter-type parameter-type] [#:enum-list |
| enum-list] [#:set-func set-func] [#:show-func show-func] |
| [#:doc doc] [#:set-doc set-doc] [#:show-doc show-doc] |
| [#:initial-value initial-value]) |
| |
| The argument NAME is the name of the new parameter. If NAME |
| consists of multiple words, then the initial words are looked for |
| as prefix parameters. An example of this can be illustrated with |
| the 'set print' set of parameters. If NAME is 'print foo', then |
| 'print' will be searched as the prefix parameter. In this case the |
| parameter can subsequently be accessed in GDB as 'set print foo'. |
| If NAME consists of multiple words, and no prefix parameter group |
| can be found, an exception is raised. |
| |
| The result is the '<gdb:parameter>' object representing the |
| parameter. The parameter is not usable until it has been |
| registered with GDB with 'register-parameter!'. |
| |
| The rest of the arguments are optional. |
| |
| The argument COMMAND-CLASS should be one of the 'COMMAND_' |
| constants (*note Commands In Guile::). This argument tells GDB how |
| to categorize the new parameter in the help system. The default is |
| 'COMMAND_NONE'. |
| |
| The argument PARAMETER-TYPE should be one of the 'PARAM_' constants |
| defined below. This argument tells GDB the type of the new |
| parameter; this information is used for input validation and |
| completion. The default is 'PARAM_BOOLEAN'. |
| |
| If PARAMETER-TYPE is 'PARAM_ENUM', then ENUM-LIST must be a list of |
| strings. These strings represent the possible values for the |
| parameter. |
| |
| If PARAMETER-TYPE is not 'PARAM_ENUM', then the presence of |
| ENUM-LIST will cause an exception to be thrown. |
| |
| The argument SET-FUNC is a function of one argument: SELF which is |
| the '<gdb:parameter>' object representing the parameter. GDB will |
| call this function when a PARAMETER's value has been changed via |
| the 'set' API (for example, 'set foo off'). The value of the |
| parameter has already been set to the new value. This function |
| must return a string to be displayed to the user. GDB will add a |
| trailing newline if the string is non-empty. GDB generally doesn't |
| print anything when a parameter is set, thus typically this |
| function should return '""'. A non-empty string result should |
| typically be used for displaying warnings and errors. |
| |
| The argument SHOW-FUNC is a function of two arguments: SELF which |
| is the '<gdb:parameter>' object representing the parameter, and |
| SVALUE which is the string representation of the current value. |
| GDB will call this function when a PARAMETER's 'show' API has been |
| invoked (for example, 'show foo'). This function must return a |
| string, and will be displayed to the user. GDB will add a trailing |
| newline. |
| |
| The argument DOC is the help text for the new parameter. If there |
| is no documentation string, a default value is used. |
| |
| The argument SET-DOC is the help text for this parameter's 'set' |
| command. |
| |
| The argument SHOW-DOC is the help text for this parameter's 'show' |
| command. |
| |
| The argument INITIAL-VALUE specifies the initial value of the |
| parameter. If it is a function, it takes one parameter, the |
| '<gdb:parameter>' object and its result is used as the initial |
| value of the parameter. The initial value must be valid for the |
| parameter type, otherwise an exception is thrown. |
| |
| -- Scheme Procedure: register-parameter! parameter |
| Add PARAMETER, a '<gdb:parameter>' object, to GDB's list of |
| parameters. It is an error to register a parameter more than once. |
| The result is unspecified. |
| |
| -- Scheme Procedure: parameter? object |
| Return '#t' if OBJECT is a '<gdb:parameter>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: parameter-value parameter |
| Return the value of PARAMETER which may either be a |
| '<gdb:parameter>' object or a string naming the parameter. |
| |
| -- Scheme Procedure: set-parameter-value! parameter new-value |
| Assign PARAMETER the value of NEW-VALUE. The argument PARAMETER |
| must be an object of type '<gdb:parameter>'. GDB does validation |
| when assignments are made. |
| |
| When a new parameter is defined, its type must be specified. The |
| available types are represented by constants defined in the 'gdb' |
| module: |
| |
| 'PARAM_BOOLEAN' |
| The value is a plain boolean. The Guile boolean values, '#t' and |
| '#f' are the only valid values. |
| |
| 'PARAM_AUTO_BOOLEAN' |
| The value has three possible states: true, false, and 'auto'. In |
| Guile, true and false are represented using boolean constants, and |
| 'auto' is represented using '#:auto'. |
| |
| 'PARAM_UINTEGER' |
| The value is an unsigned integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| 'PARAM_ZINTEGER' |
| The value is an integer. |
| |
| 'PARAM_ZUINTEGER' |
| The value is an unsigned integer. |
| |
| 'PARAM_ZUINTEGER_UNLIMITED' |
| The value is an integer in the range '[0, INT_MAX]'. A value of |
| '-1' means "unlimited", and other negative numbers are not allowed. |
| |
| 'PARAM_STRING' |
| The value is a string. When the user modifies the string, any |
| escape sequences, such as '\t', '\f', and octal escapes, are |
| translated into corresponding characters and encoded into the |
| current host charset. |
| |
| 'PARAM_STRING_NOESCAPE' |
| The value is a string. When the user modifies the string, escapes |
| are passed through untranslated. |
| |
| 'PARAM_OPTIONAL_FILENAME' |
| The value is a either a filename (a string), or '#f'. |
| |
| 'PARAM_FILENAME' |
| The value is a filename. This is just like |
| 'PARAM_STRING_NOESCAPE', but uses file names for completion. |
| |
| 'PARAM_ENUM' |
| The value is a string, which must be one of a collection of string |
| constants provided when the parameter is created. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Note that GDB parameters must not be confused with Guile’s |
| parameter objects (*note (guile)Parameters::). |
| |
| |
| File: gdb.info, Node: Progspaces In Guile, Next: Objfiles In Guile, Prev: Parameters In Guile, Up: Guile API |
| |
| 23.3.3.13 Program Spaces In Guile |
| ................................. |
| |
| A program space, or "progspace", represents a symbolic view of an |
| address space. It consists of all of the objfiles of the program. |
| *Note Objfiles In Guile::. *Note program spaces: Inferiors and |
| Programs, for more details about program spaces. |
| |
| Each progspace is represented by an instance of the '<gdb:progspace>' |
| smob. *Note GDB Scheme Data Types::. |
| |
| The following progspace-related functions are available in the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: progspace? object |
| Return '#t' if OBJECT is a '<gdb:progspace>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: progspace-valid? progspace |
| Return '#t' if PROGSPACE is valid, '#f' if not. A |
| '<gdb:progspace>' object can become invalid if the program it |
| refers to is not loaded in GDB any longer. |
| |
| -- Scheme Procedure: current-progspace |
| This function returns the program space of the currently selected |
| inferior. There is always a current progspace, this never returns |
| '#f'. *Note Inferiors and Programs::. |
| |
| -- Scheme Procedure: progspaces |
| Return a list of all the progspaces currently known to GDB. |
| |
| -- Scheme Procedure: progspace-filename progspace |
| Return the absolute file name of PROGSPACE as a string. This is |
| the name of the file passed as the argument to the 'file' or |
| 'symbol-file' commands. If the program space does not have an |
| associated file name, then '#f' is returned. This occurs, for |
| example, when GDB is started without a program to debug. |
| |
| A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is |
| invalid. |
| |
| -- Scheme Procedure: progspace-objfiles progspace |
| Return the list of objfiles of PROGSPACE. The order of objfiles in |
| the result is arbitrary. Each element is an object of type |
| '<gdb:objfile>'. *Note Objfiles In Guile::. |
| |
| A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is |
| invalid. |
| |
| -- Scheme Procedure: progspace-pretty-printers progspace |
| Return the list of pretty-printers of PROGSPACE. Each element is |
| an object of type '<gdb:pretty-printer>'. *Note Guile Pretty |
| Printing API::, for more information. |
| |
| -- Scheme Procedure: set-progspace-pretty-printers! progspace |
| printer-list |
| Set the list of registered '<gdb:pretty-printer>' objects for |
| PROGSPACE to PRINTER-LIST. *Note Guile Pretty Printing API::, for |
| more information. |
| |
| |
| File: gdb.info, Node: Objfiles In Guile, Next: Frames In Guile, Prev: Progspaces In Guile, Up: Guile API |
| |
| 23.3.3.14 Objfiles In Guile |
| ........................... |
| |
| GDB loads symbols for an inferior from various symbol-containing files |
| (*note Files::). These include the primary executable file, any shared |
| libraries used by the inferior, and any separate debug info files (*note |
| Separate Debug Files::). GDB calls these symbol-containing files |
| "objfiles". |
| |
| Each objfile is represented as an object of type '<gdb:objfile>'. |
| |
| The following objfile-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: objfile? object |
| Return '#t' if OBJECT is a '<gdb:objfile>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: objfile-valid? objfile |
| Return '#t' if OBJFILE is valid, '#f' if not. A '<gdb:objfile>' |
| object can become invalid if the object file it refers to is not |
| loaded in GDB any longer. All other '<gdb:objfile>' procedures |
| will throw an exception if it is invalid at the time the procedure |
| is called. |
| |
| -- Scheme Procedure: objfile-filename objfile |
| Return the file name of OBJFILE as a string, with symbolic links |
| resolved. |
| |
| -- Scheme Procedure: objfile-progspace objfile |
| Return the '<gdb:progspace>' that this object file lives in. *Note |
| Progspaces In Guile::, for more on progspaces. |
| |
| -- Scheme Procedure: objfile-pretty-printers objfile |
| Return the list of registered '<gdb:pretty-printer>' objects for |
| OBJFILE. *Note Guile Pretty Printing API::, for more information. |
| |
| -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list |
| Set the list of registered '<gdb:pretty-printer>' objects for |
| OBJFILE to PRINTER-LIST. The PRINTER-LIST must be a list of |
| '<gdb:pretty-printer>' objects. *Note Guile Pretty Printing API::, |
| for more information. |
| |
| -- Scheme Procedure: current-objfile |
| When auto-loading a Guile script (*note Guile Auto-loading::), GDB |
| sets the "current objfile" to the corresponding objfile. This |
| function returns the current objfile. If there is no current |
| objfile, this function returns '#f'. |
| |
| -- Scheme Procedure: objfiles |
| Return a list of all the objfiles in the current program space. |
| |
| |
| File: gdb.info, Node: Frames In Guile, Next: Blocks In Guile, Prev: Objfiles In Guile, Up: Guile API |
| |
| 23.3.3.15 Accessing inferior stack frames from Guile. |
| ..................................................... |
| |
| When the debugged program stops, GDB is able to analyze its call stack |
| (*note Stack frames: Frames.). The '<gdb:frame>' class represents a |
| frame in the stack. A '<gdb:frame>' object is only valid while its |
| corresponding frame exists in the inferior's stack. If you try to use |
| an invalid frame object, GDB will throw a 'gdb:invalid-object' exception |
| (*note Guile Exception Handling::). |
| |
| Two '<gdb:frame>' objects can be compared for equality with the |
| 'equal?' function, like: |
| |
| (gdb) guile (equal? (newest-frame) (selected-frame)) |
| #t |
| |
| The following frame-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: frame? object |
| Return '#t' if OBJECT is a '<gdb:frame>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: frame-valid? frame |
| Returns '#t' if FRAME is valid, '#f' if not. A frame object can |
| become invalid if the frame it refers to doesn't exist anymore in |
| the inferior. All '<gdb:frame>' procedures will throw an exception |
| if the frame is invalid at the time the procedure is called. |
| |
| -- Scheme Procedure: frame-name frame |
| Return the function name of FRAME, or '#f' if it can't be obtained. |
| |
| -- Scheme Procedure: frame-arch frame |
| Return the '<gdb:architecture>' object corresponding to FRAME's |
| architecture. *Note Architectures In Guile::. |
| |
| -- Scheme Procedure: frame-type frame |
| Return the type of FRAME. The value can be one of: |
| |
| 'NORMAL_FRAME' |
| An ordinary stack frame. |
| |
| 'DUMMY_FRAME' |
| A fake stack frame that was created by GDB when performing an |
| inferior function call. |
| |
| 'INLINE_FRAME' |
| A frame representing an inlined function. The function was |
| inlined into a 'NORMAL_FRAME' that is older than this one. |
| |
| 'TAILCALL_FRAME' |
| A frame representing a tail call. *Note Tail Call Frames::. |
| |
| 'SIGTRAMP_FRAME' |
| A signal trampoline frame. This is the frame created by the |
| OS when it calls into a signal handler. |
| |
| 'ARCH_FRAME' |
| A fake stack frame representing a cross-architecture call. |
| |
| 'SENTINEL_FRAME' |
| This is like 'NORMAL_FRAME', but it is only used for the |
| newest frame. |
| |
| -- Scheme Procedure: frame-unwind-stop-reason frame |
| Return an integer representing the reason why it's not possible to |
| find more frames toward the outermost frame. Use |
| 'unwind-stop-reason-string' to convert the value returned by this |
| function to a string. The value can be one of: |
| |
| 'FRAME_UNWIND_NO_REASON' |
| No particular reason (older frames should be available). |
| |
| 'FRAME_UNWIND_NULL_ID' |
| The previous frame's analyzer returns an invalid result. |
| |
| 'FRAME_UNWIND_OUTERMOST' |
| This frame is the outermost. |
| |
| 'FRAME_UNWIND_UNAVAILABLE' |
| Cannot unwind further, because that would require knowing the |
| values of registers or memory that have not been collected. |
| |
| 'FRAME_UNWIND_INNER_ID' |
| This frame ID looks like it ought to belong to a NEXT frame, |
| but we got it for a PREV frame. Normally, this is a sign of |
| unwinder failure. It could also indicate stack corruption. |
| |
| 'FRAME_UNWIND_SAME_ID' |
| This frame has the same ID as the previous one. That means |
| that unwinding further would almost certainly give us another |
| frame with exactly the same ID, so break the chain. Normally, |
| this is a sign of unwinder failure. It could also indicate |
| stack corruption. |
| |
| 'FRAME_UNWIND_NO_SAVED_PC' |
| The frame unwinder did not find any saved PC, but we needed |
| one to unwind further. |
| |
| 'FRAME_UNWIND_MEMORY_ERROR' |
| The frame unwinder caused an error while trying to access |
| memory. |
| |
| 'FRAME_UNWIND_FIRST_ERROR' |
| Any stop reason greater or equal to this value indicates some |
| kind of error. This special value facilitates writing code |
| that tests for errors in unwinding in a way that will work |
| correctly even if the list of the other values is modified in |
| future GDB versions. Using it, you could write: |
| |
| (define reason (frame-unwind-stop-readon (selected-frame))) |
| (define reason-str (unwind-stop-reason-string reason)) |
| (if (>= reason FRAME_UNWIND_FIRST_ERROR) |
| (format #t "An error occured: ~s\n" reason-str)) |
| |
| -- Scheme Procedure: frame-pc frame |
| Return the frame's resume address. |
| |
| -- Scheme Procedure: frame-block frame |
| Return the frame's code block as a '<gdb:block>' object. *Note |
| Blocks In Guile::. |
| |
| -- Scheme Procedure: frame-function frame |
| Return the symbol for the function corresponding to this frame as a |
| '<gdb:symbol>' object, or '#f' if there isn't one. *Note Symbols |
| In Guile::. |
| |
| -- Scheme Procedure: frame-older frame |
| Return the frame that called FRAME. |
| |
| -- Scheme Procedure: frame-newer frame |
| Return the frame called by FRAME. |
| |
| -- Scheme Procedure: frame-sal frame |
| Return the frame's '<gdb:sal>' (symtab and line) object. *Note |
| Symbol Tables In Guile::. |
| |
| -- Scheme Procedure: frame-read-register frame register |
| Return the value of REGISTER in FRAME. REGISTER should be a |
| string, like 'pc'. |
| |
| -- Scheme Procedure: frame-read-var frame variable [#:block block] |
| Return the value of VARIABLE in FRAME. If the optional argument |
| BLOCK is provided, search for the variable from that block; |
| otherwise start at the frame's current block (which is determined |
| by the frame's current program counter). The VARIABLE must be |
| given as a string or a '<gdb:symbol>' object, and BLOCK must be a |
| '<gdb:block>' object. |
| |
| -- Scheme Procedure: frame-select frame |
| Set FRAME to be the selected frame. *Note Examining the Stack: |
| Stack. |
| |
| -- Scheme Procedure: selected-frame |
| Return the selected frame object. *Note Selecting a Frame: |
| Selection. |
| |
| -- Scheme Procedure: newest-frame |
| Return the newest frame object for the selected thread. |
| |
| -- Scheme Procedure: unwind-stop-reason-string reason |
| Return a string explaining the reason why GDB stopped unwinding |
| frames, as expressed by the given REASON code (an integer, see the |
| 'frame-unwind-stop-reason' procedure above in this section). |
| |
| |
| File: gdb.info, Node: Blocks In Guile, Next: Symbols In Guile, Prev: Frames In Guile, Up: Guile API |
| |
| 23.3.3.16 Accessing blocks from Guile. |
| ...................................... |
| |
| In GDB, symbols are stored in blocks. A block corresponds roughly to a |
| scope in the source code. Blocks are organized hierarchically, and are |
| represented individually in Guile as an object of type '<gdb:block>'. |
| Blocks rely on debugging information being available. |
| |
| A frame has a block. Please see *note Frames In Guile::, for a more |
| in-depth discussion of frames. |
| |
| The outermost block is known as the "global block". The global block |
| typically holds public global variables and functions. |
| |
| The block nested just inside the global block is the "static block". |
| The static block typically holds file-scoped variables and functions. |
| |
| GDB provides a method to get a block's superblock, but there is |
| currently no way to examine the sub-blocks of a block, or to iterate |
| over all the blocks in a symbol table (*note Symbol Tables In Guile::). |
| |
| Here is a short example that should help explain blocks: |
| |
| /* This is in the global block. */ |
| int global; |
| |
| /* This is in the static block. */ |
| static int file_scope; |
| |
| /* 'function' is in the global block, and 'argument' is |
| in a block nested inside of 'function'. */ |
| int function (int argument) |
| { |
| /* 'local' is in a block inside 'function'. It may or may |
| not be in the same block as 'argument'. */ |
| int local; |
| |
| { |
| /* 'inner' is in a block whose superblock is the one holding |
| 'local'. */ |
| int inner; |
| |
| /* If this call is expanded by the compiler, you may see |
| a nested block here whose function is 'inline_function' |
| and whose superblock is the one holding 'inner'. */ |
| inline_function (); |
| } |
| } |
| |
| The following block-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: block? object |
| Return '#t' if OBJECT is a '<gdb:block>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: block-valid? block |
| Returns '#t' if '<gdb:block>' BLOCK is valid, '#f' if not. A block |
| object can become invalid if the block it refers to doesn't exist |
| anymore in the inferior. All other '<gdb:block>' methods will |
| throw an exception if it is invalid at the time the procedure is |
| called. The block's validity is also checked during iteration over |
| symbols of the block. |
| |
| -- Scheme Procedure: block-start block |
| Return the start address of '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-end block |
| Return the end address of '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-function block |
| Return the name of '<gdb:block>' BLOCK represented as a |
| '<gdb:symbol>' object. If the block is not named, then '#f' is |
| returned. |
| |
| For ordinary function blocks, the superblock is the static block. |
| However, you should note that it is possible for a function block |
| to have a superblock that is not the static block - for instance |
| this happens for an inlined function. |
| |
| -- Scheme Procedure: block-superblock block |
| Return the block containing '<gdb:block>' BLOCK. If the parent |
| block does not exist, then '#f' is returned. |
| |
| -- Scheme Procedure: block-global-block block |
| Return the global block associated with '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-static-block block |
| Return the static block associated with '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-global? block |
| Return '#t' if '<gdb:block>' BLOCK is a global block. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: block-static? block |
| Return '#t' if '<gdb:block>' BLOCK is a static block. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: block-symbols |
| Return a list of all symbols (as <gdb:symbol> objects) in |
| '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: make-block-symbols-iterator block |
| Return an object of type '<gdb:iterator>' that will iterate over |
| all symbols of the block. Guile programs should not assume that a |
| specific block object will always contain a given symbol, since |
| changes in GDB features and infrastructure may cause symbols move |
| across blocks in a symbol table. *Note Iterators In Guile::. |
| |
| -- Scheme Procedure: block-symbols-progress? |
| Return #t if the object is a <gdb:block-symbols-progress> object. |
| This object would be obtained from the 'progress' element of the |
| '<gdb:iterator>' object returned by 'make-block-symbols-iterator'. |
| |
| -- Scheme Procedure: lookup-block pc |
| Return the innermost '<gdb:block>' containing the given PC value. |
| If the block cannot be found for the PC value specified, the |
| function will return '#f'. |
| |
| |
| File: gdb.info, Node: Symbols In Guile, Next: Symbol Tables In Guile, Prev: Blocks In Guile, Up: Guile API |
| |
| 23.3.3.17 Guile representation of Symbols. |
| .......................................... |
| |
| GDB represents every variable, function and type as an entry in a symbol |
| table. *Note Examining the Symbol Table: Symbols. Guile represents |
| these symbols in GDB with the '<gdb:symbol>' object. |
| |
| The following symbol-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: symbol? object |
| Return '#t' if OBJECT is an object of type '<gdb:symbol>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-valid? symbol |
| Return '#t' if the '<gdb:symbol>' object is valid, '#f' if not. A |
| '<gdb:symbol>' object can become invalid if the symbol it refers to |
| does not exist in GDB any longer. All other '<gdb:symbol>' |
| procedures will throw an exception if it is invalid at the time the |
| procedure is called. |
| |
| -- Scheme Procedure: symbol-type symbol |
| Return the type of SYMBOL or '#f' if no type is recorded. The |
| result is an object of type '<gdb:type>'. *Note Types In Guile::. |
| |
| -- Scheme Procedure: symbol-symtab symbol |
| Return the symbol table in which SYMBOL appears. The result is an |
| object of type '<gdb:symtab>'. *Note Symbol Tables In Guile::. |
| |
| -- Scheme Procedure: symbol-line symbol |
| Return the line number in the source code at which SYMBOL was |
| defined. This is an integer. |
| |
| -- Scheme Procedure: symbol-name symbol |
| Return the name of SYMBOL as a string. |
| |
| -- Scheme Procedure: symbol-linkage-name symbol |
| Return the name of SYMBOL, as used by the linker (i.e., may be |
| mangled). |
| |
| -- Scheme Procedure: symbol-print-name symbol |
| Return the name of SYMBOL in a form suitable for output. This is |
| either 'name' or 'linkage_name', depending on whether the user |
| asked GDB to display demangled or mangled names. |
| |
| -- Scheme Procedure: symbol-addr-class symbol |
| Return the address class of the symbol. This classifies how to |
| find the value of a symbol. Each address class is a constant |
| defined in the '(gdb)' module and described later in this chapter. |
| |
| -- Scheme Procedure: symbol-needs-frame? symbol |
| Return '#t' if evaluating SYMBOL's value requires a frame (*note |
| Frames In Guile::) and '#f' otherwise. Typically, local variables |
| will require a frame, but other symbols will not. |
| |
| -- Scheme Procedure: symbol-argument? symbol |
| Return '#t' if SYMBOL is an argument of a function. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: symbol-constant? symbol |
| Return '#t' if SYMBOL is a constant. Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-function? symbol |
| Return '#t' if SYMBOL is a function or a method. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: symbol-variable? symbol |
| Return '#t' if SYMBOL is a variable. Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-value symbol [#:frame frame] |
| Compute the value of SYMBOL, as a '<gdb:value>'. For functions, |
| this computes the address of the function, cast to the appropriate |
| type. If the symbol requires a frame in order to compute its |
| value, then FRAME must be given. If FRAME is not given, or if |
| FRAME is invalid, then an exception is thrown. |
| |
| -- Scheme Procedure: lookup-symbol name [#:block block] [#:domain |
| domain] |
| This function searches for a symbol by name. The search scope can |
| be restricted to the parameters defined in the optional domain and |
| block arguments. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| BLOCK argument restricts the search to symbols visible in that |
| BLOCK. The BLOCK argument must be a '<gdb:block>' object. If |
| omitted, the block for the current frame is used. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the '(gdb)' |
| module and described later in this chapter. |
| |
| The result is a list of two elements. The first element is a |
| '<gdb:symbol>' object or '#f' if the symbol is not found. If the |
| symbol is found, the second element is '#t' if the symbol is a |
| field of a method's object (e.g., 'this' in C++), otherwise it is |
| '#f'. If the symbol is not found, the second element is '#f'. |
| |
| -- Scheme Procedure: lookup-global-symbol name [#:domain domain] |
| This function searches for a global symbol by name. The search |
| scope can be restricted by the domain argument. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the '(gdb)' |
| module and described later in this chapter. |
| |
| The result is a '<gdb:symbol>' object or '#f' if the symbol is not |
| found. |
| |
| The available domain categories in '<gdb:symbol>' are represented as |
| constants in the '(gdb)' module: |
| |
| 'SYMBOL_UNDEF_DOMAIN' |
| This is used when a domain has not been discovered or none of the |
| following domains apply. This usually indicates an error either in |
| the symbol information or in GDB's handling of symbols. |
| |
| 'SYMBOL_VAR_DOMAIN' |
| This domain contains variables, function names, typedef names and |
| enum type values. |
| |
| 'SYMBOL_STRUCT_DOMAIN' |
| This domain holds struct, union and enum type names. |
| |
| 'SYMBOL_LABEL_DOMAIN' |
| This domain contains names of labels (for gotos). |
| |
| 'SYMBOL_VARIABLES_DOMAIN' |
| This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains |
| everything minus functions and types. |
| |
| 'SYMBOL_FUNCTIONS_DOMAIN' |
| This domain contains all functions. |
| |
| 'SYMBOL_TYPES_DOMAIN' |
| This domain contains all types. |
| |
| The available address class categories in '<gdb:symbol>' are |
| represented as constants in the 'gdb' module: |
| |
| 'SYMBOL_LOC_UNDEF' |
| If this is returned by address class, it indicates an error either |
| in the symbol information or in GDB's handling of symbols. |
| |
| 'SYMBOL_LOC_CONST' |
| Value is constant int. |
| |
| 'SYMBOL_LOC_STATIC' |
| Value is at a fixed address. |
| |
| 'SYMBOL_LOC_REGISTER' |
| Value is in a register. |
| |
| 'SYMBOL_LOC_ARG' |
| Value is an argument. This value is at the offset stored within |
| the symbol inside the frame's argument list. |
| |
| 'SYMBOL_LOC_REF_ARG' |
| Value address is stored in the frame's argument list. Just like |
| 'LOC_ARG' except that the value's address is stored at the offset, |
| not the value itself. |
| |
| 'SYMBOL_LOC_REGPARM_ADDR' |
| Value is a specified register. Just like 'LOC_REGISTER' except the |
| register holds the address of the argument instead of the argument |
| itself. |
| |
| 'SYMBOL_LOC_LOCAL' |
| Value is a local variable. |
| |
| 'SYMBOL_LOC_TYPEDEF' |
| Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all |
| have this class. |
| |
| 'SYMBOL_LOC_BLOCK' |
| Value is a block. |
| |
| 'SYMBOL_LOC_CONST_BYTES' |
| Value is a byte-sequence. |
| |
| 'SYMBOL_LOC_UNRESOLVED' |
| Value is at a fixed address, but the address of the variable has to |
| be determined from the minimal symbol table whenever the variable |
| is referenced. |
| |
| 'SYMBOL_LOC_OPTIMIZED_OUT' |
| The value does not actually exist in the program. |
| |
| 'SYMBOL_LOC_COMPUTED' |
| The value's address is a computed location. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Guile, Next: Breakpoints In Guile, Prev: Symbols In Guile, Up: Guile API |
| |
| 23.3.3.18 Symbol table representation in Guile. |
| ............................................... |
| |
| Access to symbol table data maintained by GDB on the inferior is exposed |
| to Guile via two objects: '<gdb:sal>' (symtab-and-line) and |
| '<gdb:symtab>'. Symbol table and line data for a frame is returned from |
| the 'frame-find-sal' '<gdb:frame>' procedure. *Note Frames In Guile::. |
| |
| For more information on GDB's symbol table management, see *note |
| Examining the Symbol Table: Symbols. |
| |
| The following symtab-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: symtab? object |
| Return '#t' if OBJECT is an object of type '<gdb:symtab>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: symtab-valid? symtab |
| Return '#t' if the '<gdb:symtab>' object is valid, '#f' if not. A |
| '<gdb:symtab>' object becomes invalid when the symbol table it |
| refers to no longer exists in GDB. All other '<gdb:symtab>' |
| procedures will throw an exception if it is invalid at the time the |
| procedure is called. |
| |
| -- Scheme Procedure: symtab-filename symtab |
| Return the symbol table's source filename. |
| |
| -- Scheme Procedure: symtab-fullname symtab |
| Return the symbol table's source absolute file name. |
| |
| -- Scheme Procedure: symtab-objfile symtab |
| Return the symbol table's backing object file. *Note Objfiles In |
| Guile::. |
| |
| -- Scheme Procedure: symtab-global-block symtab |
| Return the global block of the underlying symbol table. *Note |
| Blocks In Guile::. |
| |
| -- Scheme Procedure: symtab-static-block symtab |
| Return the static block of the underlying symbol table. *Note |
| Blocks In Guile::. |
| |
| The following symtab-and-line-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: sal? object |
| Return '#t' if OBJECT is an object of type '<gdb:sal>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: sal-valid? sal |
| Return '#t' if SAL is valid, '#f' if not. A '<gdb:sal>' object |
| becomes invalid when the Symbol table object it refers to no longer |
| exists in GDB. All other '<gdb:sal>' procedures will throw an |
| exception if it is invalid at the time the procedure is called. |
| |
| -- Scheme Procedure: sal-symtab sal |
| Return the symbol table object ('<gdb:symtab>') for SAL. |
| |
| -- Scheme Procedure: sal-line sal |
| Return the line number for SAL. |
| |
| -- Scheme Procedure: sal-pc sal |
| Return the start of the address range occupied by code for SAL. |
| |
| -- Scheme Procedure: sal-last sal |
| Return the end of the address range occupied by code for SAL. |
| |
| -- Scheme Procedure: find-pc-line pc |
| Return the '<gdb:sal>' object corresponding to the PC value. If an |
| invalid value of PC is passed as an argument, then the 'symtab' and |
| 'line' attributes of the returned '<gdb:sal>' object will be '#f' |
| and 0 respectively. |
| |
| |
| File: gdb.info, Node: Breakpoints In Guile, Next: Lazy Strings In Guile, Prev: Symbol Tables In Guile, Up: Guile API |
| |
| 23.3.3.19 Manipulating breakpoints using Guile |
| .............................................. |
| |
| Breakpoints in Guile are represented by objects of type |
| '<gdb:breakpoint>'. New breakpoints can be created with the |
| 'make-breakpoint' Guile function, and then added to GDB with the |
| 'register-breakpoint!' Guile function. This two-step approach is taken |
| to separate out the side-effect of adding the breakpoint to GDB from |
| 'make-breakpoint'. |
| |
| Support is also provided to view and manipulate breakpoints created |
| outside of Guile. |
| |
| The following breakpoint-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: make-breakpoint location [#:type type] [#:wp-class |
| wp-class] [#:internal internal] |
| Create a new breakpoint at LOCATION, a string naming the location |
| of the breakpoint, or an expression that defines a watchpoint. The |
| contents can be any location recognized by the 'break' command, or |
| in the case of a watchpoint, by the 'watch' command. |
| |
| The breakpoint is initially marked as 'invalid'. The breakpoint is |
| not usable until it has been registered with GDB with |
| 'register-breakpoint!', at which point it becomes 'valid'. The |
| result is the '<gdb:breakpoint>' object representing the |
| breakpoint. |
| |
| The optional TYPE denotes the breakpoint to create. This argument |
| can be either 'BP_BREAKPOINT' or 'BP_WATCHPOINT', and defaults to |
| 'BP_BREAKPOINT'. |
| |
| The optional WP-CLASS argument defines the class of watchpoint to |
| create, if TYPE is 'BP_WATCHPOINT'. If a watchpoint class is not |
| provided, it is assumed to be a 'WP_WRITE' class. |
| |
| The optional INTERNAL argument allows the breakpoint to become |
| invisible to the user. The breakpoint will neither be reported |
| when registered, nor will it be listed in the output from 'info |
| breakpoints' (but will be listed with the 'maint info breakpoints' |
| command). If an internal flag is not provided, the breakpoint is |
| visible (non-internal). |
| |
| When a watchpoint is created, GDB will try to create a hardware |
| assisted watchpoint. If successful, the type of the watchpoint is |
| changed from 'BP_WATCHPOINT' to 'BP_HARDWARE_WATCHPOINT' for |
| 'WP_WRITE', 'BP_READ_WATCHPOINT' for 'WP_READ', and |
| 'BP_ACCESS_WATCHPOINT' for 'WP_ACCESS'. If not successful, the |
| type of the watchpoint is left as 'WP_WATCHPOINT'. |
| |
| The available types are represented by constants defined in the |
| 'gdb' module: |
| |
| 'BP_BREAKPOINT' |
| Normal code breakpoint. |
| |
| 'BP_WATCHPOINT' |
| Watchpoint breakpoint. |
| |
| 'BP_HARDWARE_WATCHPOINT' |
| Hardware assisted watchpoint. This value cannot be specified |
| when creating the breakpoint. |
| |
| 'BP_READ_WATCHPOINT' |
| Hardware assisted read watchpoint. This value cannot be |
| specified when creating the breakpoint. |
| |
| 'BP_ACCESS_WATCHPOINT' |
| Hardware assisted access watchpoint. This value cannot be |
| specified when creating the breakpoint. |
| |
| The available watchpoint types represented by constants are defined |
| in the '(gdb)' module: |
| |
| 'WP_READ' |
| Read only watchpoint. |
| |
| 'WP_WRITE' |
| Write only watchpoint. |
| |
| 'WP_ACCESS' |
| Read/Write watchpoint. |
| |
| -- Scheme Procedure: register-breakpoint! breakpoint |
| Add BREAKPOINT, a '<gdb:breakpoint>' object, to GDB's list of |
| breakpoints. The breakpoint must have been created with |
| 'make-breakpoint'. One cannot register breakpoints that have been |
| created outside of Guile. Once a breakpoint is registered it |
| becomes 'valid'. It is an error to register an already registered |
| breakpoint. The result is unspecified. |
| |
| -- Scheme Procedure: delete-breakpoint! breakpoint |
| Remove BREAKPOINT from GDB's list of breakpoints. This also |
| invalidates the Guile BREAKPOINT object. Any further attempt to |
| access the object will throw an exception. |
| |
| If BREAKPOINT was created from Guile with 'make-breakpoint' it may |
| be re-registered with GDB, in which case the breakpoint becomes |
| valid again. |
| |
| -- Scheme Procedure: breakpoints |
| Return a list of all breakpoints. Each element of the list is a |
| '<gdb:breakpoint>' object. |
| |
| -- Scheme Procedure: breakpoint? object |
| Return '#t' if OBJECT is a '<gdb:breakpoint>' object, and '#f' |
| otherwise. |
| |
| -- Scheme Procedure: breakpoint-valid? breakpoint |
| Return '#t' if BREAKPOINT is valid, '#f' otherwise. Breakpoints |
| created with 'make-breakpoint' are marked as invalid until they are |
| registered with GDB with 'register-breakpoint!'. A |
| '<gdb:breakpoint>' object can become invalid if the user deletes |
| the breakpoint. In this case, the object still exists, but the |
| underlying breakpoint does not. In the cases of watchpoint scope, |
| the watchpoint remains valid even if execution of the inferior |
| leaves the scope of that watchpoint. |
| |
| -- Scheme Procedure: breakpoint-number breakpoint |
| Return the breakpoint's number -- the identifier used by the user |
| to manipulate the breakpoint. |
| |
| -- Scheme Procedure: breakpoint-type breakpoint |
| Return the breakpoint's type -- the identifier used to determine |
| the actual breakpoint type or use-case. |
| |
| -- Scheme Procedure: breakpoint-visible? breakpoint |
| Return '#t' if the breakpoint is visible to the user when hit, or |
| when the 'info breakpoints' command is run. Otherwise return '#f'. |
| |
| -- Scheme Procedure: breakpoint-location breakpoint |
| Return the location of the breakpoint, as specified by the user. |
| It is a string. If the breakpoint does not have a location (that |
| is, it is a watchpoint) return '#f'. |
| |
| -- Scheme Procedure: breakpoint-expression breakpoint |
| Return the breakpoint expression, as specified by the user. It is |
| a string. If the breakpoint does not have an expression (the |
| breakpoint is not a watchpoint) return '#f'. |
| |
| -- Scheme Procedure: breakpoint-enabled? breakpoint |
| Return '#t' if the breakpoint is enabled, and '#f' otherwise. |
| |
| -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag |
| Set the enabled state of BREAKPOINT to FLAG. If flag is '#f' it is |
| disabled, otherwise it is enabled. |
| |
| -- Scheme Procedure: breakpoint-silent? breakpoint |
| Return '#t' if the breakpoint is silent, and '#f' otherwise. |
| |
| Note that a breakpoint can also be silent if it has commands and |
| the first command is 'silent'. This is not reported by the |
| 'silent' attribute. |
| |
| -- Scheme Procedure: set-breakpoint-silent! breakpoint flag |
| Set the silent state of BREAKPOINT to FLAG. If flag is '#f' the |
| breakpoint is made silent, otherwise it is made non-silent (or |
| noisy). |
| |
| -- Scheme Procedure: breakpoint-ignore-count breakpoint |
| Return the ignore count for BREAKPOINT. |
| |
| -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count |
| Set the ignore count for BREAKPOINT to COUNT. |
| |
| -- Scheme Procedure: breakpoint-hit-count breakpoint |
| Return hit count of BREAKPOINT. |
| |
| -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count |
| Set the hit count of BREAKPOINT to COUNT. At present, COUNT must |
| be zero. |
| |
| -- Scheme Procedure: breakpoint-thread breakpoint |
| Return the global-thread-id for thread-specific breakpoint |
| BREAKPOINT. Return #f if BREAKPOINT is not thread-specific. |
| |
| -- Scheme Procedure: set-breakpoint-thread! breakpoint |
| global-thread-id|#f |
| Set the thread-id for BREAKPOINT to GLOBAL-THREAD-ID If set to |
| '#f', the breakpoint is no longer thread-specific. |
| |
| -- Scheme Procedure: breakpoint-task breakpoint |
| If the breakpoint is Ada task-specific, return the Ada task id. If |
| the breakpoint is not task-specific (or the underlying language is |
| not Ada), return '#f'. |
| |
| -- Scheme Procedure: set-breakpoint-task! breakpoint task |
| Set the Ada task of BREAKPOINT to TASK. If set to '#f', the |
| breakpoint is no longer task-specific. |
| |
| -- Scheme Procedure: breakpoint-condition breakpoint |
| Return the condition of BREAKPOINT, as specified by the user. It |
| is a string. If there is no condition, return '#f'. |
| |
| -- Scheme Procedure: set-breakpoint-condition! breakpoint condition |
| Set the condition of BREAKPOINT to CONDITION, which must be a |
| string. If set to '#f' then the breakpoint becomes unconditional. |
| |
| -- Scheme Procedure: breakpoint-stop breakpoint |
| Return the stop predicate of BREAKPOINT. See |
| 'set-breakpoint-stop!' below in this section. |
| |
| -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f |
| Set the stop predicate of BREAKPOINT. The predicate PROCEDURE |
| takes one argument: the <gdb:breakpoint> object. If this predicate |
| is set to a procedure then it is invoked whenever the inferior |
| reaches this breakpoint. If it returns '#t', or any non-'#f' |
| value, then the inferior is stopped, otherwise the inferior will |
| continue. |
| |
| If there are multiple breakpoints at the same location with a |
| 'stop' predicate, each one will be called regardless of the return |
| status of the previous. This ensures that all 'stop' predicates |
| have a chance to execute at that location. In this scenario if one |
| of the methods returns '#t' but the others return '#f', the |
| inferior will still be stopped. |
| |
| You should not alter the execution state of the inferior (i.e., |
| step, next, etc.), alter the current frame context (i.e., change |
| the current active frame), or alter, add or delete any breakpoint. |
| As a general rule, you should not alter any data within GDB or the |
| inferior at this time. |
| |
| Example 'stop' implementation: |
| |
| (define (my-stop? bkpt) |
| (let ((int-val (parse-and-eval "foo"))) |
| (value=? int-val 3))) |
| (define bkpt (make-breakpoint "main.c:42")) |
| (register-breakpoint! bkpt) |
| (set-breakpoint-stop! bkpt my-stop?) |
| |
| -- Scheme Procedure: breakpoint-commands breakpoint |
| Return the commands attached to BREAKPOINT as a string, or '#f' if |
| there are none. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Guile, Next: Architectures In Guile, Prev: Breakpoints In Guile, Up: Guile API |
| |
| 23.3.3.20 Guile representation of lazy strings. |
| ............................................... |
| |
| A "lazy string" is a string whose contents is not retrieved or encoded |
| until it is needed. |
| |
| A '<gdb:lazy-string>' is represented in GDB as an 'address' that |
| points to a region of memory, an 'encoding' that will be used to encode |
| that region of memory, and a 'length' to delimit the region of memory |
| that represents the string. The difference between a |
| '<gdb:lazy-string>' and a string wrapped within a '<gdb:value>' is that |
| a '<gdb:lazy-string>' will be treated differently by GDB when printing. |
| A '<gdb:lazy-string>' is retrieved and encoded during printing, while a |
| '<gdb:value>' wrapping a string is immediately retrieved and encoded on |
| creation. |
| |
| The following lazy-string-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: lazy-string? object |
| Return '#t' if OBJECT is an object of type '<gdb:lazy-string>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: lazy-string-address lazy-sring |
| Return the address of LAZY-STRING. |
| |
| -- Scheme Procedure: lazy-string-length lazy-string |
| Return the length of LAZY-STRING in characters. If the length is |
| -1, then the string will be fetched and encoded up to the first |
| null of appropriate width. |
| |
| -- Scheme Procedure: lazy-string-encoding lazy-string |
| Return the encoding that will be applied to LAZY-STRING when the |
| string is printed by GDB. If the encoding is not set, or contains |
| an empty string, then GDB will select the most appropriate encoding |
| when the string is printed. |
| |
| -- Scheme Procedure: lazy-string-type lazy-string |
| Return the type that is represented by LAZY-STRING's type. For a |
| lazy string this is a pointer or array type. To resolve this to |
| the lazy string's character type, use 'type-target-type'. *Note |
| Types In Guile::. |
| |
| -- Scheme Procedure: lazy-string->value lazy-string |
| Convert the '<gdb:lazy-string>' to a '<gdb:value>'. This value |
| will point to the string in memory, but will lose all the delayed |
| retrieval, encoding and handling that GDB applies to a |
| '<gdb:lazy-string>'. |
| |
| |
| File: gdb.info, Node: Architectures In Guile, Next: Disassembly In Guile, Prev: Lazy Strings In Guile, Up: Guile API |
| |
| 23.3.3.21 Guile representation of architectures |
| ............................................... |
| |
| GDB uses architecture specific parameters and artifacts in a number of |
| its various computations. An architecture is represented by an instance |
| of the '<gdb:arch>' class. |
| |
| The following architecture-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: arch? object |
| Return '#t' if OBJECT is an object of type '<gdb:arch>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: current-arch |
| Return the current architecture as a '<gdb:arch>' object. |
| |
| -- Scheme Procedure: arch-name arch |
| Return the name (string value) of '<gdb:arch>' ARCH. |
| |
| -- Scheme Procedure: arch-charset arch |
| Return name of target character set of '<gdb:arch>' ARCH. |
| |
| -- Scheme Procedure: arch-wide-charset |
| Return name of target wide character set of '<gdb:arch>' ARCH. |
| |
| Each architecture provides a set of predefined types, obtained by the |
| following functions. |
| |
| -- Scheme Procedure: arch-void-type arch |
| Return the '<gdb:type>' object for a 'void' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-char-type arch |
| Return the '<gdb:type>' object for a 'char' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-short-type arch |
| Return the '<gdb:type>' object for a 'short' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int-type arch |
| Return the '<gdb:type>' object for an 'int' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-long-type arch |
| Return the '<gdb:type>' object for a 'long' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-schar-type arch |
| Return the '<gdb:type>' object for a 'signed char' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-uchar-type arch |
| Return the '<gdb:type>' object for an 'unsigned char' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ushort-type arch |
| Return the '<gdb:type>' object for an 'unsigned short' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-uint-type arch |
| Return the '<gdb:type>' object for an 'unsigned int' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ulong-type arch |
| Return the '<gdb:type>' object for an 'unsigned long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-float-type arch |
| Return the '<gdb:type>' object for a 'float' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-double-type arch |
| Return the '<gdb:type>' object for a 'double' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-longdouble-type arch |
| Return the '<gdb:type>' object for a 'long double' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-bool-type arch |
| Return the '<gdb:type>' object for a 'bool' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-longlong-type arch |
| Return the '<gdb:type>' object for a 'long long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ulonglong-type arch |
| Return the '<gdb:type>' object for an 'unsigned long long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-int8-type arch |
| Return the '<gdb:type>' object for an 'int8' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint8-type arch |
| Return the '<gdb:type>' object for a 'uint8' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int16-type arch |
| Return the '<gdb:type>' object for an 'int16' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint16-type arch |
| Return the '<gdb:type>' object for a 'uint16' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int32-type arch |
| Return the '<gdb:type>' object for an 'int32' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint32-type arch |
| Return the '<gdb:type>' object for a 'uint32' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int64-type arch |
| Return the '<gdb:type>' object for an 'int64' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint64-type arch |
| Return the '<gdb:type>' object for a 'uint64' type of architecture |
| ARCH. |
| |
| Example: |
| |
| (gdb) guile (type-name (arch-uchar-type (current-arch))) |
| "unsigned char" |
| |
| |
| File: gdb.info, Node: Disassembly In Guile, Next: I/O Ports in Guile, Prev: Architectures In Guile, Up: Guile API |
| |
| 23.3.3.22 Disassembly In Guile |
| .............................. |
| |
| The disassembler can be invoked from Scheme code. Furthermore, the |
| disassembler can take a Guile port as input, allowing one to disassemble |
| from any source, and not just target memory. |
| |
| -- Scheme Procedure: arch-disassemble arch start-pc [#:port port] |
| [#:offset offset] [#:size size] [#:count count] |
| Return a list of disassembled instructions starting from the memory |
| address START-PC. |
| |
| The optional argument PORT specifies the input port to read bytes |
| from. If PORT is '#f' then bytes are read from target memory. |
| |
| The optional argument OFFSET specifies the address offset of the |
| first byte in PORT. This is useful, for example, when PORT |
| specifies a 'bytevector' and you want the bytevector to be |
| disassembled as if it came from that address. The START-PC passed |
| to the reader for PORT is offset by the same amount. |
| |
| Example: |
| (gdb) guile (use-modules (rnrs io ports)) |
| (gdb) guile (define pc (value->integer (parse-and-eval "$pc"))) |
| (gdb) guile (define mem (open-memory #:start pc)) |
| (gdb) guile (define bv (get-bytevector-n mem 10)) |
| (gdb) guile (define bv-port (open-bytevector-input-port bv)) |
| (gdb) guile (define arch (current-arch)) |
| (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc) |
| (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5))) |
| |
| The optional arguments SIZE and COUNT determine the number of |
| instructions in the returned list. If either SIZE or COUNT is |
| specified as zero, then no instructions are disassembled and an |
| empty list is returned. If both the optional arguments SIZE and |
| COUNT are specified, then a list of at most COUNT disassembled |
| instructions whose start address falls in the closed memory address |
| interval from START-PC to (START-PC + SIZE - 1) are returned. If |
| SIZE is not specified, but COUNT is specified, then COUNT number of |
| instructions starting from the address START-PC are returned. If |
| COUNT is not specified but SIZE is specified, then all instructions |
| whose start address falls in the closed memory address interval |
| from START-PC to (START-PC + SIZE - 1) are returned. If neither |
| SIZE nor COUNT are specified, then a single instruction at START-PC |
| is returned. |
| |
| Each element of the returned list is an alist (associative list) |
| with the following keys: |
| |
| 'address' |
| The value corresponding to this key is a Guile integer of the |
| memory address of the instruction. |
| |
| 'asm' |
| The value corresponding to this key is a string value which |
| represents the instruction with assembly language mnemonics. |
| The assembly language flavor used is the same as that |
| specified by the current CLI variable 'disassembly-flavor'. |
| *Note Machine Code::. |
| |
| 'length' |
| The value corresponding to this key is the length of the |
| instruction in bytes. |
| |
| |
| File: gdb.info, Node: I/O Ports in Guile, Next: Memory Ports in Guile, Prev: Disassembly In Guile, Up: Guile API |
| |
| 23.3.3.23 I/O Ports in Guile |
| ............................ |
| |
| -- Scheme Procedure: input-port |
| Return GDB's input port as a Guile port object. |
| |
| -- Scheme Procedure: output-port |
| Return GDB's output port as a Guile port object. |
| |
| -- Scheme Procedure: error-port |
| Return GDB's error port as a Guile port object. |
| |
| -- Scheme Procedure: stdio-port? object |
| Return '#t' if OBJECT is a GDB stdio port. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Memory Ports in Guile, Next: Iterators In Guile, Prev: I/O Ports in Guile, Up: Guile API |
| |
| 23.3.3.24 Memory Ports in Guile |
| ............................... |
| |
| GDB provides a 'port' interface to target memory. This allows Guile |
| code to read/write target memory using Guile's port and bytevector |
| functionality. The main routine is 'open-memory' which returns a port |
| object. One can then read/write memory using that object. |
| |
| -- Scheme Procedure: open-memory [#:mode mode] [#:start address] |
| [#:size size] |
| Return a port object that can be used for reading and writing |
| memory. The port will be open according to MODE, which is the |
| standard mode argument to Guile port open routines, except that the |
| '"a"' and '"l"' modes are not supported. *Note (guile)File |
| Ports::. The '"b"' (binary) character may be present, but is |
| ignored: memory ports are binary only. If '"0"' is appended then |
| the port is marked as unbuffered. The default is '"r"', read-only |
| and buffered. |
| |
| The chunk of memory that can be accessed can be bounded. If both |
| START and SIZE are unspecified, all of memory can be accessed. If |
| only START is specified, all of memory from that point on can be |
| accessed. If only SIZE if specified, all memory in the range |
| [0,SIZE) can be accessed. If both are specified, all memory in the |
| rane [START,START+SIZE) can be accessed. |
| |
| -- Scheme Procedure: memory-port? |
| Return '#t' if OBJECT is an object of type '<gdb:memory-port>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: memory-port-range memory-port |
| Return the range of '<gdb:memory-port>' MEMORY-PORT as a list of |
| two elements: '(start end)'. The range is START to END inclusive. |
| |
| -- Scheme Procedure: memory-port-read-buffer-size memory-port |
| Return the size of the read buffer of '<gdb:memory-port>' |
| MEMORY-PORT. |
| |
| -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size |
| Set the size of the read buffer of '<gdb:memory-port>' MEMORY-PORT |
| to SIZE. The result is unspecified. |
| |
| -- Scheme Procedure: memory-port-write-buffer-size memory-port |
| Return the size of the write buffer of '<gdb:memory-port>' |
| MEMORY-PORT. |
| |
| -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port |
| size |
| Set the size of the write buffer of '<gdb:memory-port>' MEMORY-PORT |
| to SIZE. The result is unspecified. |
| |
| A memory port is closed like any other port, with 'close-port'. |
| |
| Combined with Guile's 'bytevectors', memory ports provide a lot of |
| utility. For example, to fill a buffer of 10 integers in memory, one |
| can do something like the following. |
| |
| ;; In the program: int buffer[10]; |
| (use-modules (rnrs bytevectors)) |
| (use-modules (rnrs io ports)) |
| (define addr (parse-and-eval "buffer")) |
| (define n 10) |
| (define byte-size (* n 4)) |
| (define mem-port (open-memory #:mode "r+" #:start |
| (value->integer addr) #:size byte-size)) |
| (define byte-vec (make-bytevector byte-size)) |
| (do ((i 0 (+ i 1))) |
| ((>= i n)) |
| (bytevector-s32-native-set! byte-vec (* i 4) (* i 42))) |
| (put-bytevector mem-port byte-vec) |
| (close-port mem-port) |
| |
| |
| File: gdb.info, Node: Iterators In Guile, Prev: Memory Ports in Guile, Up: Guile API |
| |
| 23.3.3.25 Iterators In Guile |
| ............................ |
| |
| A simple iterator facility is provided to allow, for example, iterating |
| over the set of program symbols without having to first construct a list |
| of all of them. A useful contribution would be to add support for SRFI |
| 41 and SRFI 45. |
| |
| -- Scheme Procedure: make-iterator object progress next! |
| A '<gdb:iterator>' object is constructed with the 'make-iterator' |
| procedure. It takes three arguments: the object to be iterated |
| over, an object to record the progress of the iteration, and a |
| procedure to return the next element in the iteration, or an |
| implementation chosen value to denote the end of iteration. |
| |
| By convention, end of iteration is marked with |
| '(end-of-iteration)', and may be tested with the |
| 'end-of-iteration?' predicate. The result of '(end-of-iteration)' |
| is chosen so that it is not otherwise used by the '(gdb)' module. |
| If you are using '<gdb:iterator>' in your own code it is your |
| responsibility to maintain this invariant. |
| |
| A trivial example for illustration's sake: |
| |
| (use-modules (gdb iterator)) |
| (define my-list (list 1 2 3)) |
| (define iter |
| (make-iterator my-list my-list |
| (lambda (iter) |
| (let ((l (iterator-progress iter))) |
| (if (eq? l '()) |
| (end-of-iteration) |
| (begin |
| (set-iterator-progress! iter (cdr l)) |
| (car l))))))) |
| |
| Here is a slightly more realistic example, which computes a list of |
| all the functions in 'my-global-block'. |
| |
| (use-modules (gdb iterator)) |
| (define this-sal (find-pc-line (frame-pc (selected-frame)))) |
| (define this-symtab (sal-symtab this-sal)) |
| (define this-global-block (symtab-global-block this-symtab)) |
| (define syms-iter (make-block-symbols-iterator this-global-block)) |
| (define functions (iterator-filter symbol-function? syms-iter)) |
| |
| -- Scheme Procedure: iterator? object |
| Return '#t' if OBJECT is a '<gdb:iterator>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: iterator-object iterator |
| Return the first argument that was passed to 'make-iterator'. This |
| is the object being iterated over. |
| |
| -- Scheme Procedure: iterator-progress iterator |
| Return the object tracking iteration progress. |
| |
| -- Scheme Procedure: set-iterator-progress! iterator new-value |
| Set the object tracking iteration progress. |
| |
| -- Scheme Procedure: iterator-next! iterator |
| Invoke the procedure that was the third argument to |
| 'make-iterator', passing it one argument, the '<gdb:iterator>' |
| object. The result is either the next element in the iteration, or |
| an end marker as implemented by the 'next!' procedure. By |
| convention the end marker is the result of '(end-of-iteration)'. |
| |
| -- Scheme Procedure: end-of-iteration |
| Return the Scheme object that denotes end of iteration. |
| |
| -- Scheme Procedure: end-of-iteration? object |
| Return '#t' if OBJECT is the end of iteration marker. Otherwise |
| return '#f'. |
| |
| These functions are provided by the '(gdb iterator)' module to assist |
| in using iterators. |
| |
| -- Scheme Procedure: make-list-iterator list |
| Return a '<gdb:iterator>' object that will iterate over LIST. |
| |
| -- Scheme Procedure: iterator->list iterator |
| Return the elements pointed to by ITERATOR as a list. |
| |
| -- Scheme Procedure: iterator-map proc iterator |
| Return the list of objects obtained by applying PROC to the object |
| pointed to by ITERATOR and to each subsequent object. |
| |
| -- Scheme Procedure: iterator-for-each proc iterator |
| Apply PROC to each element pointed to by ITERATOR. The result is |
| unspecified. |
| |
| -- Scheme Procedure: iterator-filter pred iterator |
| Return the list of elements pointed to by ITERATOR that satisfy |
| PRED. |
| |
| -- Scheme Procedure: iterator-until pred iterator |
| Run ITERATOR until the result of '(pred element)' is true and |
| return that as the result. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Guile Auto-loading, Next: Guile Modules, Prev: Guile API, Up: Guile |
| |
| 23.3.4 Guile Auto-loading |
| ------------------------- |
| |
| When a new object file is read (for example, due to the 'file' command, |
| or because the inferior has loaded a shared library), GDB will look for |
| Guile support scripts in two ways: 'OBJFILE-gdb.scm' and the |
| '.debug_gdb_scripts' section. *Note Auto-loading extensions::. |
| |
| The auto-loading feature is useful for supplying application-specific |
| debugging commands and scripts. |
| |
| Auto-loading can be enabled or disabled, and the list of auto-loaded |
| scripts can be printed. |
| |
| 'set auto-load guile-scripts [on|off]' |
| Enable or disable the auto-loading of Guile scripts. |
| |
| 'show auto-load guile-scripts' |
| Show whether auto-loading of Guile scripts is enabled or disabled. |
| |
| 'info auto-load guile-scripts [REGEXP]' |
| Print the list of all Guile scripts that GDB auto-loaded. |
| |
| Also printed is the list of Guile scripts that were mentioned in |
| the '.debug_gdb_scripts' section and were not found. This is |
| useful because their names are not printed when GDB tries to load |
| them and fails. There may be many of them, and printing an error |
| message for each one is problematic. |
| |
| If REGEXP is supplied only Guile scripts with matching names are |
| printed. |
| |
| Example: |
| |
| (gdb) info auto-load guile-scripts |
| Loaded Script |
| Yes scm-section-script.scm |
| full name: /tmp/scm-section-script.scm |
| No my-foo-pretty-printers.scm |
| |
| When reading an auto-loaded file, GDB sets the "current objfile". |
| This is available via the 'current-objfile' procedure (*note Objfiles In |
| Guile::). This can be useful for registering objfile-specific |
| pretty-printers. |
| |
| |
| File: gdb.info, Node: Guile Modules, Prev: Guile Auto-loading, Up: Guile |
| |
| 23.3.5 Guile Modules |
| -------------------- |
| |
| GDB comes with several modules to assist writing Guile code. |
| |
| * Menu: |
| |
| * Guile Printing Module:: Building and registering pretty-printers |
| * Guile Types Module:: Utilities for working with types |
| |
| |
| File: gdb.info, Node: Guile Printing Module, Next: Guile Types Module, Up: Guile Modules |
| |
| 23.3.5.1 Guile Printing Module |
| .............................. |
| |
| This module provides a collection of utilities for working with |
| pretty-printers. |
| |
| Usage: |
| |
| (use-modules (gdb printing)) |
| |
| -- Scheme Procedure: prepend-pretty-printer! object printer |
| Add PRINTER to the front of the list of pretty-printers for OBJECT. |
| The OBJECT must either be a '<gdb:objfile>' object, or '#f' in |
| which case PRINTER is added to the global list of printers. |
| |
| -- Scheme Procecure: append-pretty-printer! object printer |
| Add PRINTER to the end of the list of pretty-printers for OBJECT. |
| The OBJECT must either be a '<gdb:objfile>' object, or '#f' in |
| which case PRINTER is added to the global list of printers. |
| |
| |
| File: gdb.info, Node: Guile Types Module, Prev: Guile Printing Module, Up: Guile Modules |
| |
| 23.3.5.2 Guile Types Module |
| ........................... |
| |
| This module provides a collection of utilities for working with |
| '<gdb:type>' objects. |
| |
| Usage: |
| |
| (use-modules (gdb types)) |
| |
| -- Scheme Procedure: get-basic-type type |
| Return TYPE with const and volatile qualifiers stripped, and with |
| typedefs and C++ references converted to the underlying type. |
| |
| C++ example: |
| |
| typedef const int const_int; |
| const_int foo (3); |
| const_int& foo_ref (foo); |
| int main () { return 0; } |
| |
| Then in gdb: |
| |
| (gdb) start |
| (gdb) guile (use-modules (gdb) (gdb types)) |
| (gdb) guile (define foo-ref (parse-and-eval "foo_ref")) |
| (gdb) guile (get-basic-type (value-type foo-ref)) |
| int |
| |
| -- Scheme Procedure: type-has-field-deep? type field |
| Return '#t' if TYPE, assumed to be a type with fields (e.g., a |
| structure or union), has field FIELD. Otherwise return '#f'. This |
| searches baseclasses, whereas 'type-has-field?' does not. |
| |
| -- Scheme Procedure: make-enum-hashtable enum-type |
| Return a Guile hash table produced from ENUM-TYPE. Elements in the |
| hash table are referenced with 'hashq-ref'. |
| |
| |
| File: gdb.info, Node: Auto-loading extensions, Next: Multiple Extension Languages, Prev: Guile, Up: Extending GDB |
| |
| 23.4 Auto-loading extensions |
| ============================ |
| |
| GDB provides two mechanisms for automatically loading extensions when a |
| new object file is read (for example, due to the 'file' command, or |
| because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' and |
| the '.debug_gdb_scripts' section of modern file formats like ELF. |
| |
| * Menu: |
| |
| * objfile-gdb.ext file: objfile-gdbdotext file. The 'OBJFILE-gdb.EXT' file |
| * .debug_gdb_scripts section: dotdebug_gdb_scripts section. The '.debug_gdb_scripts' section |
| * Which flavor to choose?:: |
| |
| The auto-loading feature is useful for supplying application-specific |
| debugging commands and features. |
| |
| Auto-loading can be enabled or disabled, and the list of auto-loaded |
| scripts can be printed. See the 'auto-loading' section of each |
| extension language for more information. For GDB command files see |
| *note Auto-loading sequences::. For Python files see *note Python |
| Auto-loading::. |
| |
| Note that loading of this script file also requires accordingly |
| configured 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| |
| File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions |
| |
| 23.4.1 The 'OBJFILE-gdb.EXT' file |
| --------------------------------- |
| |
| When a new object file is read, GDB looks for a file named |
| 'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the |
| object file's name and where EXT is the file extension for the extension |
| language: |
| |
| 'OBJFILE-gdb.gdb' |
| GDB's own command language |
| 'OBJFILE-gdb.py' |
| Python |
| 'OBJFILE-gdb.scm' |
| Guile |
| |
| SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is |
| absolute, following all symlinks, and resolving '.' and '..' components, |
| and appending the '-gdb.EXT' suffix. If this file exists and is |
| readable, GDB will evaluate it as a script in the specified extension |
| language. |
| |
| If this file does not exist, then GDB will look for SCRIPT-NAME file |
| in all of the directories as specified below. |
| |
| Note that loading of these files requires an accordingly configured |
| 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| For object files using '.exe' suffix GDB tries to load first the |
| scripts normally according to its '.exe' filename. But if no scripts |
| are found GDB also tries script filenames matching the object file |
| without its '.exe' suffix. This '.exe' stripping is case insensitive |
| and it is attempted on any platform. This makes the script filenames |
| compatible between Unix and MS-Windows hosts. |
| |
| 'set auto-load scripts-directory [DIRECTORIES]' |
| Control GDB auto-loaded scripts location. Multiple directory |
| entries may be delimited by the host platform path separator in use |
| (':' on Unix, ';' on MS-Windows and MS-DOS). |
| |
| Each entry here needs to be covered also by the security setting |
| 'set auto-load safe-path' (*note set auto-load safe-path::). |
| |
| This variable defaults to '$debugdir:$datadir/auto-load'. The |
| default 'set auto-load safe-path' value can be also overriden by |
| GDB configuration option '--with-auto-load-dir'. |
| |
| Any reference to '$debugdir' will get replaced by |
| DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any |
| reference to '$datadir' will get replaced by DATA-DIRECTORY which |
| is determined at GDB startup (*note Data Files::). '$debugdir' and |
| '$datadir' must be placed as a directory component -- either alone |
| or delimited by '/' or '\' directory separators, depending on the |
| host platform. |
| |
| The list of directories uses path separator (':' on GNU and Unix |
| systems, ';' on MS-Windows and MS-DOS) to separate directories, |
| similarly to the 'PATH' environment variable. |
| |
| 'show auto-load scripts-directory' |
| Show GDB auto-loaded scripts location. |
| |
| 'add-auto-load-scripts-directory [DIRECTORIES...]' |
| Add an entry (or list of entries) to the list of auto-loaded |
| scripts locations. Multiple entries may be delimited by the host |
| platform path separator in use. |
| |
| GDB does not track which files it has already auto-loaded this way. |
| GDB will load the associated script every time the corresponding OBJFILE |
| is opened. So your '-gdb.EXT' file should be careful to avoid errors if |
| it is evaluated more than once. |
| |
| |
| File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions |
| |
| 23.4.2 The '.debug_gdb_scripts' section |
| --------------------------------------- |
| |
| For systems using file formats like ELF and COFF, when GDB loads a new |
| object file it will look for a special section named |
| '.debug_gdb_scripts'. If this section exists, its contents is a list of |
| null-terminated entries specifying scripts to load. Each entry begins |
| with a non-null prefix byte that specifies the kind of entry, typically |
| the extension language and whether the script is in a file or inlined in |
| '.debug_gdb_scripts'. |
| |
| The following entries are supported: |
| |
| 'SECTION_SCRIPT_ID_PYTHON_FILE = 1' |
| 'SECTION_SCRIPT_ID_SCHEME_FILE = 3' |
| 'SECTION_SCRIPT_ID_PYTHON_TEXT = 4' |
| 'SECTION_SCRIPT_ID_SCHEME_TEXT = 6' |
| |
| 23.4.2.1 Script File Entries |
| ............................ |
| |
| If the entry specifies a file, GDB will look for the file first in the |
| current directory and then along the source search path (*note |
| Specifying Source Directories: Source Path.), except that '$cdir' is not |
| searched, since the compilation directory is not relevant to scripts. |
| |
| File entries can be placed in section '.debug_gdb_scripts' with, for |
| example, this GCC macro for Python scripts. |
| |
| /* Note: The "MS" section flags are to remove duplicates. */ |
| #define DEFINE_GDB_PY_SCRIPT(script_name) \ |
| asm("\ |
| .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ |
| .byte 1 /* Python */\n\ |
| .asciz \"" script_name "\"\n\ |
| .popsection \n\ |
| "); |
| |
| For Guile scripts, replace '.byte 1' with '.byte 3'. Then one can |
| reference the macro in a header or source file like this: |
| |
| DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") |
| |
| The script name may include directories if desired. |
| |
| Note that loading of this script file also requires accordingly |
| configured 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| If the macro invocation is put in a header, any application or |
| library using this header will get a reference to the specified script, |
| and with the use of '"MS"' attributes on the section, the linker will |
| remove duplicates. |
| |
| 23.4.2.2 Script Text Entries |
| ............................ |
| |
| Script text entries allow to put the executable script in the entry |
| itself instead of loading it from a file. The first line of the entry, |
| everything after the prefix byte and up to the first newline ('0xa') |
| character, is the script name, and must not contain any kind of space |
| character, e.g., spaces or tabs. The rest of the entry, up to the |
| trailing null byte, is the script to execute in the specified language. |
| The name needs to be unique among all script names, as GDB executes each |
| script only once based on its name. |
| |
| Here is an example from file 'py-section-script.c' in the GDB |
| testsuite. |
| |
| #include "symcat.h" |
| #include "gdb/section-scripts.h" |
| asm( |
| ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n" |
| ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" |
| ".ascii \"gdb.inlined-script\\n\"\n" |
| ".ascii \"class test_cmd (gdb.Command):\\n\"\n" |
| ".ascii \" def __init__ (self):\\n\"\n" |
| ".ascii \" super (test_cmd, self).__init__ (" |
| "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" |
| ".ascii \" def invoke (self, arg, from_tty):\\n\"\n" |
| ".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" |
| ".ascii \"test_cmd ()\\n\"\n" |
| ".byte 0\n" |
| ".popsection\n" |
| ); |
| |
| Loading of inlined scripts requires a properly configured 'auto-load |
| safe-path' (*note Auto-loading safe path::). The path to specify in |
| 'auto-load safe-path' is the path of the file containing the |
| '.debug_gdb_scripts' section. |
| |
| |
| File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions |
| |
| 23.4.3 Which flavor to choose? |
| ------------------------------ |
| |
| Given the multiple ways of auto-loading extensions, it might not always |
| be clear which one to choose. This section provides some guidance. |
| |
| Benefits of the '-gdb.EXT' way: |
| |
| * Can be used with file formats that don't support multiple sections. |
| |
| * Ease of finding scripts for public libraries. |
| |
| Scripts specified in the '.debug_gdb_scripts' section are searched |
| for in the source search path. For publicly installed libraries, |
| e.g., 'libstdc++', there typically isn't a source directory in |
| which to find the script. |
| |
| * Doesn't require source code additions. |
| |
| Benefits of the '.debug_gdb_scripts' way: |
| |
| * Works with static linking. |
| |
| Scripts for libraries done the '-gdb.EXT' way require an objfile to |
| trigger their loading. When an application is statically linked |
| the only objfile available is the executable, and it is cumbersome |
| to attach all the scripts from all the input libraries to the |
| executable's '-gdb.EXT' script. |
| |
| * Works with classes that are entirely inlined. |
| |
| Some classes can be entirely inlined, and thus there may not be an |
| associated shared library to attach a '-gdb.EXT' script to. |
| |
| * Scripts needn't be copied out of the source tree. |
| |
| In some circumstances, apps can be built out of large collections |
| of internal libraries, and the build infrastructure necessary to |
| install the '-gdb.EXT' scripts in a place where GDB can find them |
| is cumbersome. It may be easier to specify the scripts in the |
| '.debug_gdb_scripts' section as relative paths, and add a path to |
| the top of the source tree to the source search path. |
| |
| |
| File: gdb.info, Node: Multiple Extension Languages, Next: Aliases, Prev: Auto-loading extensions, Up: Extending GDB |
| |
| 23.5 Multiple Extension Languages |
| ================================= |
| |
| The Guile and Python extension languages do not share any state, and |
| generally do not interfere with each other. There are some things to be |
| aware of, however. |
| |
| 23.5.1 Python comes first |
| ------------------------- |
| |
| Python was GDB's first extension language, and to avoid breaking |
| existing behaviour Python comes first. This is generally solved by the |
| "first one wins" principle. GDB maintains a list of enabled extension |
| languages, and when it makes a call to an extension language, (say to |
| pretty-print a value), it tries each in turn until an extension language |
| indicates it has performed the request (e.g., has returned the |
| pretty-printed form of a value). This extends to errors while |
| performing such requests: If an error happens while, for example, trying |
| to pretty-print an object then the error is reported and any following |
| extension languages are not tried. |
| |
| |
| File: gdb.info, Node: Aliases, Prev: Multiple Extension Languages, Up: Extending GDB |
| |
| 23.6 Creating new spellings of existing commands |
| ================================================ |
| |
| It is often useful to define alternate spellings of existing commands. |
| For example, if a new GDB command defined in Python has a long name to |
| type, it is handy to have an abbreviated version of it that involves |
| less typing. |
| |
| GDB itself uses aliases. For example 's' is an alias of the 'step' |
| command even though it is otherwise an ambiguous abbreviation of other |
| commands like 'set' and 'show'. |
| |
| Aliases are also used to provide shortened or more common versions of |
| multi-word commands. For example, GDB provides the 'tty' alias of the |
| 'set inferior-tty' command. |
| |
| You can define a new alias with the 'alias' command. |
| |
| 'alias [-a] [--] ALIAS = COMMAND' |
| |
| ALIAS specifies the name of the new alias. Each word of ALIAS must |
| consist of letters, numbers, dashes and underscores. |
| |
| COMMAND specifies the name of an existing command that is being |
| aliased. |
| |
| The '-a' option specifies that the new alias is an abbreviation of |
| the command. Abbreviations are not shown in command lists displayed by |
| the 'help' command. |
| |
| The '--' option specifies the end of options, and is useful when |
| ALIAS begins with a dash. |
| |
| Here is a simple example showing how to make an abbreviation of a |
| command so that there is less to type. Suppose you were tired of typing |
| 'disas', the current shortest unambiguous abbreviation of the |
| 'disassemble' command and you wanted an even shorter version named 'di'. |
| The following will accomplish this. |
| |
| (gdb) alias -a di = disas |
| |
| Note that aliases are different from user-defined commands. With a |
| user-defined command, you also need to write documentation for it with |
| the 'document' command. An alias automatically picks up the |
| documentation of the existing command. |
| |
| Here is an example where we make 'elms' an abbreviation of 'elements' |
| in the 'set print elements' command. This is to show that you can make |
| an abbreviation of any part of a command. |
| |
| (gdb) alias -a set print elms = set print elements |
| (gdb) alias -a show print elms = show print elements |
| (gdb) set p elms 20 |
| (gdb) show p elms |
| Limit on string chars or array elements to print is 200. |
| |
| Note that if you are defining an alias of a 'set' command, and you |
| want to have an alias for the corresponding 'show' command, then you |
| need to define the latter separately. |
| |
| Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, |
| just as they are normally. |
| |
| (gdb) alias -a set pr elms = set p ele |
| |
| Finally, here is an example showing the creation of a one word alias |
| for a more complex command. This creates alias 'spe' of the command |
| 'set print elements'. |
| |
| (gdb) alias spe = set print elements |
| (gdb) spe 20 |
| |
| |
| File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top |
| |
| 24 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 'mi3'). 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. |
| |
| 'mi3' |
| The GDB/MI interface introduced in GDB 9.1. |
| |
| 'mi2' |
| The GDB/MI interface introduced in GDB 6.0. |
| |
| 'mi1' |
| The GDB/MI interface introduced in GDB 5.1. |
| |
| 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). |
| |
| Note that 'interpreter-exec' only changes the interpreter for the |
| duration of the specified command. It does not change the interpreter |
| permanently. |
| |
| Although you may only choose a single interpreter at startup, it is |
| possible to run an independent interpreter on a specified input/output |
| device (usually a tty). |
| |
| For example, consider a debugger GUI or IDE that wants to provide a |
| GDB console view. It may do so by embedding a terminal emulator widget |
| in its GUI, starting GDB in the traditional command-line mode with |
| stdin/stdout/stderr redirected to that terminal, and then creating an MI |
| interpreter running on a specified input/output device. The console |
| interpreter created by GDB at startup handles commands the user types in |
| the terminal widget, while the GUI controls and synchronizes state with |
| GDB using the separate MI interpreter. |
| |
| To start a new secondary "user interface" running MI, use the |
| 'new-ui' command: |
| |
| new-ui INTERPRETER TTY |
| |
| The INTERPRETER parameter specifies the interpreter to run. This |
| accepts the same values as the 'interpreter-exec' command. For example, |
| 'console', 'mi', 'mi2', etc. The TTY parameter specifies the name of |
| the bidirectional file the interpreter uses for input/output, usually |
| the name of a pseudoterminal slave on Unix systems. For example: |
| |
| (gdb) new-ui mi /dev/pts/9 |
| |
| runs an MI interpreter on '/dev/pts/9'. |
| |
| |
| File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top |
| |
| 25 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) 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 |
| mode is supported only on platforms where a suitable version of the |
| 'curses' library is available. |
| |
| The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'. |
| You can also switch in and out of TUI mode while GDB runs by using |
| various TUI commands and key bindings, such as 'tui enable' or 'C-x |
| C-a'. *Note TUI Commands: TUI Commands, and *note TUI Key Bindings: TUI |
| Keys. |
| |
| |
| File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI |
| |
| 25.1 TUI Overview |
| ================= |
| |
| In TUI mode, GDB can display several text windows: |
| |
| _command_ |
| This window is the GDB command window with the GDB prompt and the |
| GDB output. The GDB input is still managed using readline. |
| |
| _source_ |
| The source window shows the source file of the program. The |
| current line and 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. Registers are |
| highlighted when their values change. |
| |
| The source and assembly windows show the current program position by |
| highlighting the current line and marking it with a '>' marker. |
| Breakpoints are indicated with two markers. The first marker 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 updated when the |
| current thread changes, when the frame changes, or when the program |
| counter changes. |
| |
| These windows are not all visible at the same time. The command |
| window is always visible. The others can be arranged in several |
| layouts: |
| |
| * source only, |
| |
| * assembly only, |
| |
| * source and assembly, |
| |
| * source and registers, or |
| |
| * assembly and registers. |
| |
| A status line above the command window shows the following |
| information: |
| |
| _target_ |
| Indicates the current GDB target. (*note Specifying a Debugging |
| Target: Targets.). |
| |
| _process_ |
| Gives 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 |
| |
| 25.2 TUI Key Bindings |
| ===================== |
| |
| The TUI installs several key bindings in the readline keymaps (*note |
| Command Line Editing::). 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 leaving the TUI mode, the curses |
| window management stops and GDB operates using its standard mode, |
| writing on the terminal directly. When reentering the TUI mode, |
| control is given back to the curses windows. The screen is then |
| refreshed. |
| |
| This key binding uses the bindable Readline function |
| 'tui-switch-mode'. |
| |
| '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. |
| |
| This key binding uses the bindable Readline function |
| 'tui-delete-other-windows'. |
| |
| 'C-x 2' |
| Use a TUI layout with at least two windows. When the current |
| layout already has two windows, the 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. |
| |
| This key binding uses the bindable Readline function |
| 'tui-change-windows'. |
| |
| 'C-x o' |
| Change the active window. The TUI associates several key bindings |
| (like scrolling and arrow keys) with the active window. This |
| command gives the focus to the next TUI window. |
| |
| Think of it as the Emacs 'C-x o' binding. |
| |
| This key binding uses the bindable Readline function |
| 'tui-other-window'. |
| |
| 'C-x s' |
| Switch in and out of the TUI SingleKey mode that binds single keys |
| to GDB commands (*note TUI Single Key Mode::). |
| |
| This key binding uses the bindable Readline function 'next-keymap'. |
| |
| The following key bindings only work in 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. |
| |
| Because the arrow keys scroll the active window in the TUI mode, they |
| are not available for their normal use by readline unless the command |
| window has the focus. When another window is active, you must use other |
| readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control |
| the command window. |
| |
| |
| File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI |
| |
| 25.3 TUI Single Key Mode |
| ======================== |
| |
| The TUI also provides a "SingleKey" mode, which binds several frequently |
| used GDB commands to single keys. Type 'C-x s' to switch into this |
| mode, where the following key bindings are used: |
| |
| 'c' |
| continue |
| |
| 'd' |
| down |
| |
| 'f' |
| finish |
| |
| 'n' |
| next |
| |
| 'o' |
| nexti. The shortcut letter 'o' stands for "step Over". |
| |
| 'q' |
| exit the SingleKey mode. |
| |
| 'r' |
| run |
| |
| 's' |
| step |
| |
| 'i' |
| stepi. The shortcut letter 'i' stands for "step Into". |
| |
| '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'. |
| |
| If GDB was built with Readline 8.0 or later, the TUI SingleKey keymap |
| will be named 'SingleKey'. This can be used in '.inputrc' to add |
| additional bindings to this keymap. |
| |
| |
| File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI |
| |
| 25.4 TUI-specific Commands |
| ========================== |
| |
| The TUI has specific commands to control the text windows. These |
| commands are always available, even when GDB is not in the TUI mode. |
| When GDB is in the standard mode, most of these commands will |
| automatically switch to the TUI mode. |
| |
| Note that if GDB's 'stdout' is not connected to a terminal, or GDB |
| has been started with the machine interface interpreter (*note The |
| GDB/MI Interface: GDB/MI.), most of these commands will fail with an |
| error, because it would not be possible or desirable to enable curses |
| window management. |
| |
| 'tui enable' |
| Activate TUI mode. The last active TUI window layout will be used |
| if TUI mode has previously been used in the current debugging |
| session, otherwise a default layout is used. |
| |
| 'tui disable' |
| Disable TUI mode, returning to the console interpreter. |
| |
| 'info win' |
| List and give the size of all displayed windows. |
| |
| 'layout NAME' |
| Changes which TUI windows are displayed. In each layout the |
| command window is always displayed, the NAME parameter controls |
| which additional windows are displayed, and can be any of the |
| following: |
| |
| 'next' |
| Display the next layout. |
| |
| 'prev' |
| Display the previous layout. |
| |
| 'src' |
| Display the source and command windows. |
| |
| 'asm' |
| Display the assembly and command windows. |
| |
| 'split' |
| Display the source, assembly, and command windows. |
| |
| 'regs' |
| When in 'src' layout display the register, source, and command |
| windows. When in 'asm' or 'split' layout display the |
| register, assembler, and command windows. |
| |
| 'focus NAME' |
| Changes which TUI window is currently active for scrolling. The |
| NAME parameter can be any of the following: |
| |
| 'next' |
| Make the next window active for scrolling. |
| |
| 'prev' |
| Make the previous window active for scrolling. |
| |
| 'src' |
| Make the source window active for scrolling. |
| |
| 'asm' |
| Make the assembly window active for scrolling. |
| |
| 'regs' |
| Make the register window active for scrolling. |
| |
| 'cmd' |
| Make the command window active for scrolling. |
| |
| 'refresh' |
| Refresh the screen. This is similar to typing 'C-L'. |
| |
| 'tui reg GROUP' |
| Changes the register group displayed in the tui register window to |
| GROUP. If the register window is not currently displayed this |
| command will cause the register window to be displayed. The list |
| of register groups, as well as their order is target specific. The |
| following groups are available on most targets: |
| 'next' |
| Repeatedly selecting this group will cause the display to |
| cycle through all of the available register groups. |
| |
| 'prev' |
| Repeatedly selecting this group will cause the display to |
| cycle through all of the available register groups in the |
| reverse order to NEXT. |
| |
| 'general' |
| Display the general registers. |
| 'float' |
| Display the floating point registers. |
| 'system' |
| Display the system registers. |
| 'vector' |
| Display the vector registers. |
| 'all' |
| Display all registers. |
| |
| '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. The |
| NAME parameter can be one of 'src' (the source window), 'cmd' (the |
| command window), 'asm' (the disassembly window), or 'regs' (the |
| register display window). |
| |
| |
| File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI |
| |
| 25.5 TUI Configuration Variables |
| ================================ |
| |
| Several configuration variables control the appearance of TUI windows. |
| |
| '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 border-mode MODE' |
| 'set tui active-border-mode MODE' |
| Select the display attributes for the borders of the inactive |
| windows or the active window. 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. |
| |
| 'set tui tab-width NCHARS' |
| Set the width of tab stops to be NCHARS characters. This setting |
| affects the display of TAB characters in the source and assembly |
| windows. |
| |
| 'set tui compact-source [on|off]' |
| Set whether the TUI source window is displayed in "compact" form. |
| The default display uses more space for line numbers and starts the |
| source text at the next tab stop; the compact display uses only as |
| much space as is needed for the line numbers in the current file, |
| and only a single space to separate the line numbers from the |
| source. |
| |
| Note that the colors of the TUI borders can be controlled using the |
| appropriate 'set style' commands. *Note Output Styling::. |
| |
| |
| File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top |
| |
| 26 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. |
| |
| Running GDB under Emacs can be just like running GDB normally except |
| for two things: |
| |
| * All "terminal" input and output goes through an Emacs buffer, |
| called the GUD 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. |
| |
| We call this "text command mode". Emacs 22.1, and later, also uses a |
| graphical mode, enabled by default, which provides further buffers that |
| can control the execution and describe the state of your program. *Note |
| (Emacs)GDB Graphical Interface::. |
| |
| 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 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 GUD 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 GUD buffer, you can use these special Emacs commands in |
| addition to the standard Shell mode commands: |
| |
| 'C-h m' |
| Describe the features of Emacs' GUD 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. |
| |
| In text command mode, if you type 'M-x speedbar', Emacs displays a |
| separate frame which shows a backtrace when the GUD 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. In graphical mode, the speedbar displays watch |
| expressions. |
| |
| 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. |
| |
| A more detailed description of Emacs' interaction with GDB is given |
| in the Emacs manual (*note (Emacs)Debuggers::). |
| |
| |
| File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top |
| |
| 27 The GDB/MI Interface |
| *********************** |
| |
| * Menu: |
| |
| * GDB/MI General Design:: |
| * 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 Catchpoint Commands:: |
| * GDB/MI Program Context:: |
| * GDB/MI Thread Commands:: |
| * GDB/MI Ada Tasking 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 File Transfer Commands:: |
| * GDB/MI Ada Exceptions Commands:: |
| * GDB/MI Support Commands:: |
| * GDB/MI Miscellaneous Commands:: |
| |
| 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 General Design:: |
| * 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 Catchpoint Commands:: |
| * GDB/MI Program Context:: |
| * GDB/MI Thread Commands:: |
| * GDB/MI Ada Tasking 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 File Transfer Commands:: |
| * GDB/MI Ada Exceptions Commands:: |
| * GDB/MI Support Commands:: |
| * GDB/MI Miscellaneous Commands:: |
| |
| |
| File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI |
| |
| 27.1 GDB/MI General Design |
| ========================== |
| |
| Interaction of a GDB/MI frontend with GDB involves three parts--commands |
| sent to GDB, responses to those commands and notifications. Each |
| command results in exactly one response, indicating either successful |
| completion of the command, or an error. For the commands that do not |
| resume the target, the response contains the requested information. For |
| the commands that resume the target, the response only indicates whether |
| the target was successfully resumed. Notifications is the mechanism for |
| reporting changes in the state of the target, or in GDB state, that |
| cannot conveniently be associated with a command and reported as part of |
| that command response. |
| |
| The important examples of notifications are: |
| |
| * Exec notifications. These are used to report changes in target |
| state--when a target is resumed, or stopped. It would not be |
| feasible to include this information in response of resuming |
| commands, because one resume commands can result in multiple events |
| in different threads. Also, quite some time may pass before any |
| event happens in the target, while a frontend needs to know whether |
| the resuming command itself was successfully executed. |
| |
| * Console output, and status notifications. Console output |
| notifications are used to report output of CLI commands, as well as |
| diagnostics for other commands. Status notifications are used to |
| report the progress of a long-running operation. Naturally, |
| including this information in command response would mean no output |
| is produced until the command is finished, which is undesirable. |
| |
| * General notifications. Commands may have various side effects on |
| the GDB or target state beyond their official purpose. For |
| example, a command may change the selected thread. Although such |
| changes can be included in command response, using notification |
| allows for more orthogonal frontend design. |
| |
| There's no guarantee that whenever an MI command reports an error, |
| GDB or the target are in any specific state, and especially, the state |
| is not reverted to the state before the MI command was processed. |
| Therefore, whenever an MI command results in an error, we recommend that |
| the frontend refreshes all the information shown in the user interface. |
| |
| * Menu: |
| |
| * Context management:: |
| * Asynchronous and non-stop modes:: |
| * Thread groups:: |
| |
| |
| File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design |
| |
| 27.1.1 Context management |
| ------------------------- |
| |
| 27.1.1.1 Threads and Frames |
| ........................... |
| |
| In most cases when GDB accesses the target, this access is done in |
| context of a specific thread and frame (*note Frames::). Often, even |
| when accessing global data, the target requires that a thread be |
| specified. The CLI interface maintains the selected thread and frame, |
| and supplies them to target on each command. This is convenient, |
| because a command line user would not want to specify that information |
| explicitly on each command, and because user interacts with GDB via a |
| single terminal, so no confusion is possible as to what thread and frame |
| are the current ones. |
| |
| In the case of MI, the concept of selected thread and frame is less |
| useful. First, a frontend can easily remember this information itself. |
| Second, a graphical frontend can have more than one window, each one |
| used for debugging a different thread, and the frontend might want to |
| access additional threads for internal purposes. This increases the |
| risk that by relying on implicitly selected thread, the frontend may be |
| operating on a wrong one. Therefore, each MI command should explicitly |
| specify which thread and frame to operate on. To make it possible, each |
| MI command accepts the '--thread' and '--frame' options, the value to |
| each is GDB global identifier for thread and frame to operate on. |
| |
| Usually, each top-level window in a frontend allows the user to |
| select a thread and a frame, and remembers the user selection for |
| further operations. However, in some cases GDB may suggest that the |
| current thread or frame be changed. For example, when stopping on a |
| breakpoint it is reasonable to switch to the thread where breakpoint is |
| hit. For another example, if the user issues the CLI 'thread' or |
| 'frame' commands via the frontend, it is desirable to change the |
| frontend's selection to the one specified by user. GDB communicates the |
| suggestion to change current thread and frame using the |
| '=thread-selected' notification. |
| |
| Note that historically, MI shares the selected thread with CLI, so |
| frontends used the '-thread-select' to execute commands in the right |
| context. However, getting this to work right is cumbersome. The |
| simplest way is for frontend to emit '-thread-select' command before |
| every command. This doubles the number of commands that need to be |
| sent. The alternative approach is to suppress '-thread-select' if the |
| selected thread in GDB is supposed to be identical to the thread the |
| frontend wants to operate on. However, getting this optimization right |
| can be tricky. In particular, if the frontend sends several commands to |
| GDB, and one of the commands changes the selected thread, then the |
| behaviour of subsequent commands will change. So, a frontend should |
| either wait for response from such problematic commands, or explicitly |
| add '-thread-select' for all subsequent commands. No frontend is known |
| to do this exactly right, so it is suggested to just always pass the |
| '--thread' and '--frame' options. |
| |
| 27.1.1.2 Language |
| ................. |
| |
| The execution of several commands depends on which language is selected. |
| By default, the current language (*note show language::) is used. But |
| for commands known to be language-sensitive, it is recommended to use |
| the '--language' option. This option takes one argument, which is the |
| name of the language to use while executing the command. For instance: |
| |
| -data-evaluate-expression --language c "sizeof (void*)" |
| ^done,value="4" |
| (gdb) |
| |
| The valid language names are the same names accepted by the 'set |
| language' command (*note Manually::), excluding 'auto', 'local' or |
| 'unknown'. |
| |
| |
| File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design |
| |
| 27.1.2 Asynchronous command execution and non-stop mode |
| ------------------------------------------------------- |
| |
| On some targets, GDB is capable of processing MI commands even while the |
| target is running. This is called "asynchronous command execution" |
| (*note Background Execution::). The frontend may specify a preference |
| for asynchronous execution using the '-gdb-set mi-async 1' command, |
| which should be emitted before either running the executable or |
| attaching to the target. After the frontend has started the executable |
| or attached to the target, it can find if asynchronous execution is |
| enabled using the '-list-target-features' command. |
| |
| '-gdb-set mi-async on' |
| '-gdb-set mi-async off' |
| Set whether MI is in asynchronous mode. |
| |
| When 'off', which is the default, MI execution commands (e.g., |
| '-exec-continue') are foreground commands, and GDB waits for the |
| program to stop before processing further commands. |
| |
| When 'on', MI execution commands are background execution commands |
| (e.g., '-exec-continue' becomes the equivalent of the 'c&' CLI |
| command), and so GDB is capable of processing MI commands even |
| while the target is running. |
| |
| '-gdb-show mi-async' |
| Show whether MI asynchronous mode is enabled. |
| |
| Note: In GDB version 7.7 and earlier, this option was called |
| 'target-async' instead of 'mi-async', and it had the effect of both |
| putting MI in asynchronous mode and making CLI background commands |
| possible. CLI background commands are now always possible "out of the |
| box" if the target supports them. The old spelling is kept as a |
| deprecated alias for backwards compatibility. |
| |
| Even if GDB can accept a command while target is running, many |
| commands that access the target do not work when the target is running. |
| Therefore, asynchronous command execution is most useful when combined |
| with non-stop mode (*note Non-Stop Mode::). Then, it is possible to |
| examine the state of one thread, while other threads are running. |
| |
| When a given thread is running, MI commands that try to access the |
| target in the context of that thread may not work, or may work only on |
| some targets. In particular, commands that try to operate on thread's |
| stack will not work, on any target. Commands that read memory, or |
| modify breakpoints, may work or not work, depending on the target. Note |
| that even commands that operate on global state, such as 'print', 'set', |
| and breakpoint commands, still access the target in the context of a |
| specific thread, so frontend should try to find a stopped thread and |
| perform the operation on that thread (using the '--thread' option). |
| |
| Which commands will work in the context of a running thread is highly |
| target dependent. However, the two commands '-exec-interrupt', to stop |
| a thread, and '-thread-info', to find the state of a thread, will always |
| work. |
| |
| |
| File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design |
| |
| 27.1.3 Thread groups |
| -------------------- |
| |
| GDB may be used to debug several processes at the same time. On some |
| platforms, GDB may support debugging of several hardware systems, each |
| one having several cores with several different processes running on |
| each core. This section describes the MI mechanism to support such |
| debugging scenarios. |
| |
| The key observation is that regardless of the structure of the |
| target, MI can have a global list of threads, because most commands that |
| accept the '--thread' option do not need to know what process that |
| thread belongs to. Therefore, it is not necessary to introduce neither |
| additional '--process' option, nor an notion of the current process in |
| the MI interface. The only strictly new feature that is required is the |
| ability to find how the threads are grouped into processes. |
| |
| To allow the user to discover such grouping, and to support arbitrary |
| hierarchy of machines/cores/processes, MI introduces the concept of a |
| "thread group". Thread group is a collection of threads and other |
| thread groups. A thread group always has a string identifier, a type, |
| and may have additional attributes specific to the type. A new command, |
| '-list-thread-groups', returns the list of top-level thread groups, |
| which correspond to processes that GDB is debugging at the moment. By |
| passing an identifier of a thread group to the '-list-thread-groups' |
| command, it is possible to obtain the members of specific thread group. |
| |
| To allow the user to easily discover processes, and other objects, he |
| wishes to debug, a concept of "available thread group" is introduced. |
| Available thread group is an thread group that GDB is not debugging, but |
| that can be attached to, using the '-target-attach' command. The list |
| of available top-level thread groups can be obtained using |
| '-list-thread-groups --available'. In general, the content of a thread |
| group may be only retrieved only after attaching to that thread group. |
| |
| Thread groups are related to inferiors (*note Inferiors and |
| Programs::). Each inferior corresponds to a thread group of a special |
| type 'process', and some additional operations are permitted on such |
| thread groups. |
| |
| |
| File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI |
| |
| 27.2 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 |
| |
| 27.2.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 |
| |
| 27.2.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 NL' |
| |
| 'STATUS-ASYNC-OUTPUT ==>' |
| '[ TOKEN ] "+" ASYNC-OUTPUT NL' |
| |
| 'NOTIFY-ASYNC-OUTPUT ==>' |
| '[ TOKEN ] "=" ASYNC-OUTPUT NL' |
| |
| 'ASYNC-OUTPUT ==>' |
| 'ASYNC-CLASS ( "," RESULT )*' |
| |
| '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 NL' |
| |
| 'TARGET-STREAM-OUTPUT ==>' |
| '"@" C-STRING NL' |
| |
| 'LOG-STREAM-OUTPUT ==>' |
| '"&" C-STRING NL' |
| |
| '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. Note that for all |
| async output, while the token is allowed by the grammar and may be |
| output by future versions of GDB for select async output messages, |
| it is generally omitted. Frontends should treat all async output |
| as reporting general changes in the state of the target and there |
| should be no need to associate async output to any prior 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 |
| |
| 27.3 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 |
| |
| 27.4 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". |
| |
| Since GDB/MI is used by a variety of front ends to GDB, changes to |
| the MI interface may break existing usage. This section describes how |
| the protocol changes and how to request previous version of the protocol |
| when it does. |
| |
| 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. |
| |
| * The range of values for fields with specified values, e.g., |
| 'in_scope' (*note -var-update::) may be extended. |
| |
| If the changes are likely to break front ends, the MI version level |
| will be increased by one. The new versions of the MI protocol are not |
| compatible with the old versions. Old versions of MI remain available, |
| allowing front ends to keep using them until they are modified to use |
| the latest MI version. |
| |
| Since '--interpreter=mi' always points to the latest MI version, it |
| is recommended that front ends request a specific version of MI when |
| launching GDB (e.g. '--interpreter=mi2') to make sure they get an |
| interpreter with the MI version they expect. |
| |
| The following table gives a summary of the the released versions of |
| the MI interface: the version number, the version of GDB in which it |
| first appeared and the breaking changes compared to the previous |
| version. |
| |
| MI GDB Breaking changes |
| versionversion |
| ---------------------------------------------------------------------------- |
| 1 5.1 None |
| |
| 2 6.0 |
| * The '-environment-pwd', '-environment-directory' and |
| '-environment-path' commands now returns values using the |
| MI output syntax, rather than CLI output syntax. |
| |
| * '-var-list-children''s 'children' result field is now a |
| list, rather than a tuple. |
| |
| * '-var-update''s 'changelist' result field is now a list, |
| rather than a tuple. |
| |
| 3 9.1 |
| * The output of information about multi-location breakpoints |
| has changed in the responses to the '-break-insert' and |
| '-break-info' commands, as well as in the |
| '=breakpoint-created' and '=breakpoint-modified' events. |
| The multiple locations are now placed in a 'locations' |
| field, whose value is a list. |
| |
| |
| If your front end cannot yet migrate to a more recent version of the |
| MI protocol, you can nevertheless selectively enable specific features |
| available in those recent MI versions, using the following commands: |
| |
| '-fix-multi-location-breakpoint-output' |
| Use the output for multi-location breakpoints which was introduced |
| by MI 3, even when using MI versions 2 or 1. This command has no |
| effect when using MI version 3 or later. |
| |
| 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>. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI |
| |
| 27.5 GDB/MI Output Records |
| ========================== |
| |
| * Menu: |
| |
| * GDB/MI Result Records:: |
| * GDB/MI Stream Records:: |
| * GDB/MI Async Records:: |
| * GDB/MI Breakpoint Information:: |
| * GDB/MI Frame Information:: |
| * GDB/MI Thread Information:: |
| * GDB/MI Ada Exception Information:: |
| |
| |
| File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.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"' |
| This result record is equivalent to '^done'. Historically, it was |
| output instead of '^done' if the command has resumed the target. |
| This behaviour is maintained for backward compatibility, but all |
| frontends should treat '^done' and '^running' identically and rely |
| on the '*running' output record to determine which threads are |
| resumed. |
| |
| '"^connected"' |
| GDB has connected to a remote target. |
| |
| '"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]' |
| The operation failed. The 'msg=C-STRING' variable contains the |
| corresponding error message. |
| |
| If present, the 'code=C-STRING' variable provides an error code on |
| which consumers can rely on to detect the corresponding error |
| condition. At present, only one error code is defined: |
| |
| '"undefined-command"' |
| Indicates that the command causing the error does not exist. |
| |
| '"^exit"' |
| GDB has terminated. |
| |
| |
| File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records |
| |
| 27.5.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 Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.3 GDB/MI Async Records |
| --------------------------- |
| |
| "Async" 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 commands (e.g., a breakpoint modified) or a result of target |
| activity (e.g., target stopped). |
| |
| The following is the list of possible async records: |
| |
| '*running,thread-id="THREAD"' |
| The target is now running. The THREAD field can be the global |
| thread ID of the the thread that is now running, and it can be |
| 'all' if all threads are running. The frontend should assume that |
| no interaction with a running thread is possible after this |
| notification is produced. The frontend should not assume that this |
| notification is output only once for any command. GDB may emit |
| this notification several times, either for different threads, |
| because it cannot resume all threads together, or even for a single |
| thread, if the thread must be stepped though some code before |
| letting it run freely. |
| |
| '*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' |
| The target has stopped. The REASON field can have one of the |
| following values: |
| |
| '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. |
| 'solib-event' |
| The inferior has stopped due to a library being loaded or |
| unloaded. This can happen when 'stop-on-solib-events' (*note |
| Files::) is set or when a 'catch load' or 'catch unload' |
| catchpoint is in use (*note Set Catchpoints::). |
| 'fork' |
| The inferior has forked. This is reported when 'catch fork' |
| (*note Set Catchpoints::) has been used. |
| 'vfork' |
| The inferior has vforked. This is reported in when 'catch |
| vfork' (*note Set Catchpoints::) has been used. |
| 'syscall-entry' |
| The inferior entered a system call. This is reported when |
| 'catch syscall' (*note Set Catchpoints::) has been used. |
| 'syscall-return' |
| The inferior returned from a system call. This is reported |
| when 'catch syscall' (*note Set Catchpoints::) has been used. |
| 'exec' |
| The inferior called 'exec'. This is reported when 'catch |
| exec' (*note Set Catchpoints::) has been used. |
| |
| The ID field identifies the global thread ID of the thread that |
| directly caused the stop - for example by hitting a breakpoint. |
| Depending on whether all-stop mode is in effect (*note All-Stop |
| Mode::), GDB may either stop all threads, or only the thread that |
| directly triggered the stop. If all threads are stopped, the |
| STOPPED field will have the value of '"all"'. Otherwise, the value |
| of the STOPPED field will be a list of thread identifiers. |
| Presently, this list will always include a single thread, but |
| frontend should be prepared to see several threads in the list. |
| The CORE field reports the processor core on which the stop event |
| has happened. This field may be absent if such information is not |
| available. |
| |
| '=thread-group-added,id="ID"' |
| '=thread-group-removed,id="ID"' |
| A thread group was either added or removed. The ID field contains |
| the GDB identifier of the thread group. When a thread group is |
| added, it generally might not be associated with a running process. |
| When a thread group is removed, its id becomes invalid and cannot |
| be used in any way. |
| |
| '=thread-group-started,id="ID",pid="PID"' |
| A thread group became associated with a running program, either |
| because the program was just started or the thread group was |
| attached to a program. The ID field contains the GDB identifier of |
| the thread group. The PID field contains process identifier, |
| specific to the operating system. |
| |
| '=thread-group-exited,id="ID"[,exit-code="CODE"]' |
| A thread group is no longer associated with a running program, |
| either because the program has exited, or because it was detached |
| from. The ID field contains the GDB identifier of the thread |
| group. The CODE field is the exit code of the inferior; it exists |
| only when the inferior exited with some code. |
| |
| '=thread-created,id="ID",group-id="GID"' |
| '=thread-exited,id="ID",group-id="GID"' |
| A thread either was created, or has exited. The ID field contains |
| the global GDB identifier of the thread. The GID field identifies |
| the thread group this thread belongs to. |
| |
| '=thread-selected,id="ID"[,frame="FRAME"]' |
| Informs that the selected thread or frame were changed. This |
| notification is not emitted as result of the '-thread-select' or |
| '-stack-select-frame' commands, but is emitted whenever an MI |
| command that is not documented to change the selected thread and |
| frame actually changes them. In particular, invoking, directly or |
| indirectly (via user-defined command), the CLI 'thread' or 'frame' |
| commands, will generate this notification. Changing the thread or |
| frame from another user interface (see *note Interpreters::) will |
| also generate this notification. |
| |
| The FRAME field is only present if the newly selected thread is |
| stopped. See *note GDB/MI Frame Information:: for the format of |
| its value. |
| |
| We suggest that in response to this notification, front ends |
| highlight the selected thread and cause subsequent commands to |
| apply to that thread. |
| |
| '=library-loaded,...' |
| Reports that a new library file was loaded by the program. This |
| notification has 5 fields--ID, TARGET-NAME, HOST-NAME, |
| SYMBOLS-LOADED and RANGES. The ID field is an opaque identifier of |
| the library. For remote debugging case, TARGET-NAME and HOST-NAME |
| fields give the name of the library file on the target, and on the |
| host respectively. For native debugging, both those fields have |
| the same value. The SYMBOLS-LOADED field is emitted only for |
| backward compatibility and should not be relied on to convey any |
| useful information. The THREAD-GROUP field, if present, specifies |
| the id of the thread group in whose context the library was loaded. |
| If the field is absent, it means the library was loaded in the |
| context of all present thread groups. The RANGES field specifies |
| the ranges of addresses belonging to this library. |
| |
| '=library-unloaded,...' |
| Reports that a library was unloaded by the program. This |
| notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the |
| same meaning as for the '=library-loaded' notification. The |
| THREAD-GROUP field, if present, specifies the id of the thread |
| group in whose context the library was unloaded. If the field is |
| absent, it means the library was unloaded in the context of all |
| present thread groups. |
| |
| '=traceframe-changed,num=TFNUM,tracepoint=TPNUM' |
| '=traceframe-changed,end' |
| Reports that the trace frame was changed and its new number is |
| TFNUM. The number of the tracepoint associated with this trace |
| frame is TPNUM. |
| |
| '=tsv-created,name=NAME,initial=INITIAL' |
| Reports that the new trace state variable NAME is created with |
| initial value INITIAL. |
| |
| '=tsv-deleted,name=NAME' |
| '=tsv-deleted' |
| Reports that the trace state variable NAME is deleted or all trace |
| state variables are deleted. |
| |
| '=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]' |
| Reports that the trace state variable NAME is modified with the |
| initial value INITIAL. The current value CURRENT of trace state |
| variable is optional and is reported if the current value of trace |
| state variable is known. |
| |
| '=breakpoint-created,bkpt={...}' |
| '=breakpoint-modified,bkpt={...}' |
| '=breakpoint-deleted,id=NUMBER' |
| Reports that a breakpoint was created, modified, or deleted, |
| respectively. Only user-visible breakpoints are reported to the MI |
| user. |
| |
| The BKPT argument is of the same form as returned by the various |
| breakpoint commands; *Note GDB/MI Breakpoint Commands::. The |
| NUMBER is the ordinal number of the breakpoint. |
| |
| Note that if a breakpoint is emitted in the result record of a |
| command, then it will not also be emitted in an async record. |
| |
| '=record-started,thread-group="ID",method="METHOD"[,format="FORMAT"]' |
| '=record-stopped,thread-group="ID"' |
| Execution log recording was either started or stopped on an |
| inferior. The ID is the GDB identifier of the thread group |
| corresponding to the affected inferior. |
| |
| The METHOD field indicates the method used to record execution. If |
| the method in use supports multiple recording formats, FORMAT will |
| be present and contain the currently used format. *Note Process |
| Record and Replay::, for existing method and format values. |
| |
| '=cmd-param-changed,param=PARAM,value=VALUE' |
| Reports that a parameter of the command 'set PARAM' is changed to |
| VALUE. In the multi-word 'set' command, the PARAM is the whole |
| parameter list to 'set' command. For example, In command 'set |
| check type on', PARAM is 'check type' and VALUE is 'on'. |
| |
| '=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]' |
| Reports that bytes from ADDR to DATA + LEN were written in an |
| inferior. The ID is the identifier of the thread group |
| corresponding to the affected inferior. The optional 'type="code"' |
| part is reported if the memory written to holds executable code. |
| |
| |
| File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records |
| |
| 27.5.4 GDB/MI Breakpoint Information |
| ------------------------------------ |
| |
| When GDB reports information about a breakpoint, a tracepoint, a |
| watchpoint, or a catchpoint, it uses a tuple with the following fields: |
| |
| 'number' |
| The breakpoint number. |
| |
| 'type' |
| The type of the breakpoint. For ordinary breakpoints this will be |
| 'breakpoint', but many values are possible. |
| |
| 'catch-type' |
| If the type of the breakpoint is 'catchpoint', then this indicates |
| the exact type of catchpoint. |
| |
| 'disp' |
| This is the breakpoint disposition--either 'del', meaning that the |
| breakpoint will be deleted at the next stop, or 'keep', meaning |
| that the breakpoint will not be deleted. |
| |
| 'enabled' |
| This indicates whether the breakpoint is enabled, in which case the |
| value is 'y', or disabled, in which case the value is 'n'. Note |
| that this is not the same as the field 'enable'. |
| |
| 'addr' |
| The address of the breakpoint. This may be a hexidecimal number, |
| giving the address; or the string '<PENDING>', for a pending |
| breakpoint; or the string '<MULTIPLE>', for a breakpoint with |
| multiple locations. This field will not be present if no address |
| can be determined. For example, a watchpoint does not have an |
| address. |
| |
| 'addr_flags' |
| Optional field containing any flags related to the address. These |
| flags are architecture-dependent; see *note Architectures:: for |
| their meaning for a particular CPU. |
| |
| 'func' |
| If known, the function in which the breakpoint appears. If not |
| known, this field is not present. |
| |
| 'filename' |
| The name of the source file which contains this function, if known. |
| If not known, this field is not present. |
| |
| 'fullname' |
| The full file name of the source file which contains this function, |
| if known. If not known, this field is not present. |
| |
| 'line' |
| The line number at which this breakpoint appears, if known. If not |
| known, this field is not present. |
| |
| 'at' |
| If the source file is not known, this field may be provided. If |
| provided, this holds the address of the breakpoint, possibly |
| followed by a symbol name. |
| |
| 'pending' |
| If this breakpoint is pending, this field is present and holds the |
| text used to set the breakpoint, as entered by the user. |
| |
| 'evaluated-by' |
| Where this breakpoint's condition is evaluated, either 'host' or |
| 'target'. |
| |
| 'thread' |
| If this is a thread-specific breakpoint, then this identifies the |
| thread in which the breakpoint can trigger. |
| |
| 'task' |
| If this breakpoint is restricted to a particular Ada task, then |
| this field will hold the task identifier. |
| |
| 'cond' |
| If the breakpoint is conditional, this is the condition expression. |
| |
| 'ignore' |
| The ignore count of the breakpoint. |
| |
| 'enable' |
| The enable count of the breakpoint. |
| |
| 'traceframe-usage' |
| FIXME. |
| |
| 'static-tracepoint-marker-string-id' |
| For a static tracepoint, the name of the static tracepoint marker. |
| |
| 'mask' |
| For a masked watchpoint, this is the mask. |
| |
| 'pass' |
| A tracepoint's pass count. |
| |
| 'original-location' |
| The location of the breakpoint as originally specified by the user. |
| This field is optional. |
| |
| 'times' |
| The number of times the breakpoint has been hit. |
| |
| 'installed' |
| This field is only given for tracepoints. This is either 'y', |
| meaning that the tracepoint is installed, or 'n', meaning that it |
| is not. |
| |
| 'what' |
| Some extra data, the exact contents of which are type-dependent. |
| |
| 'locations' |
| This field is present if the breakpoint has multiple locations. It |
| is also exceptionally present if the breakpoint is enabled and has |
| a single, disabled location. |
| |
| The value is a list of locations. The format of a location is |
| described below. |
| |
| A location in a multi-location breakpoint is represented as a tuple |
| with the following fields: |
| |
| 'number' |
| The location number as a dotted pair, like '1.2'. The first digit |
| is the number of the parent breakpoint. The second digit is the |
| number of the location within that breakpoint. |
| |
| 'enabled' |
| This indicates whether the location is enabled, in which case the |
| value is 'y', or disabled, in which case the value is 'n'. Note |
| that this is not the same as the field 'enable'. |
| |
| 'addr' |
| The address of this location as an hexidecimal number. |
| |
| 'addr_flags' |
| Optional field containing any flags related to the address. These |
| flags are architecture-dependent; see *note Architectures:: for |
| their meaning for a particular CPU. |
| |
| 'func' |
| If known, the function in which the location appears. If not |
| known, this field is not present. |
| |
| 'file' |
| The name of the source file which contains this location, if known. |
| If not known, this field is not present. |
| |
| 'fullname' |
| The full file name of the source file which contains this location, |
| if known. If not known, this field is not present. |
| |
| 'line' |
| The line number at which this location appears, if known. If not |
| known, this field is not present. |
| |
| 'thread-groups' |
| The thread groups this location is in. |
| |
| For example, here is what the output of '-break-insert' (*note GDB/MI |
| Breakpoint Commands::) might be: |
| |
| -> -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",thread-groups=["i1"], |
| times="0"} |
| <- (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records |
| |
| 27.5.5 GDB/MI Frame Information |
| ------------------------------- |
| |
| Response from many MI commands includes an information about stack |
| frame. This information is a tuple that may have the following fields: |
| |
| 'level' |
| The level of the stack frame. The innermost frame has the level of |
| zero. This field is always present. |
| |
| 'func' |
| The name of the function corresponding to the frame. This field |
| may be absent if GDB is unable to determine the function name. |
| |
| 'addr' |
| The code address for the frame. This field is always present. |
| |
| 'addr_flags' |
| Optional field containing any flags related to the address. These |
| flags are architecture-dependent; see *note Architectures:: for |
| their meaning for a particular CPU. |
| |
| 'file' |
| The name of the source files that correspond to the frame's code |
| address. This field may be absent. |
| |
| 'line' |
| The source line corresponding to the frames' code address. This |
| field may be absent. |
| |
| 'from' |
| The name of the binary file (either executable or shared library) |
| the corresponds to the frame's code address. This field may be |
| absent. |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records |
| |
| 27.5.6 GDB/MI Thread Information |
| -------------------------------- |
| |
| Whenever GDB has to report an information about a thread, it uses a |
| tuple with the following fields. The fields are always present unless |
| stated otherwise. |
| |
| 'id' |
| The global numeric id assigned to the thread by GDB. |
| |
| 'target-id' |
| The target-specific string identifying the thread. |
| |
| 'details' |
| Additional information about the thread provided by the target. It |
| is supposed to be human-readable and not interpreted by the |
| frontend. This field is optional. |
| |
| 'name' |
| The name of the thread. If the user specified a name using the |
| 'thread name' command, then this name is given. Otherwise, if GDB |
| can extract the thread name from the target, then that name is |
| given. If GDB cannot find the thread name, then this field is |
| omitted. |
| |
| 'state' |
| The execution state of the thread, either 'stopped' or 'running', |
| depending on whether the thread is presently running. |
| |
| 'frame' |
| The stack frame currently executing in the thread. This field is |
| only present if the thread is stopped. Its format is documented in |
| *note GDB/MI Frame Information::. |
| |
| 'core' |
| The value of this field is an integer number of the processor core |
| the thread was last seen on. This field is optional. |
| |
| |
| File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records |
| |
| 27.5.7 GDB/MI Ada Exception Information |
| --------------------------------------- |
| |
| Whenever a '*stopped' record is emitted because the program stopped |
| after hitting an exception catchpoint (*note Set Catchpoints::), GDB |
| provides the name of the exception that was raised via the |
| 'exception-name' field. Also, for exceptions that were raised with an |
| exception message, GDB provides that message via the 'exception-message' |
| field. |
| |
| |
| File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI |
| |
| 27.6 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 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",thread-groups=["i1"], |
| 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",disp="keep",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", |
| arch="i386:x86_64"} |
| <- (gdb) |
| -> -exec-continue |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="exited-normally" |
| <- (gdb) |
| |
| Quitting GDB |
| ------------ |
| |
| Quitting GDB just prints the result class '^exit'. |
| |
| -> (gdb) |
| <- -gdb-exit |
| <- ^exit |
| |
| Please note that '^exit' is printed immediately, but it might take |
| some time for GDB to actually exit. During that time, GDB performs |
| necessary cleanups, including killing programs being debugged or |
| disconnecting from debug hardware, so the frontend should wait till GDB |
| exits and should only forcibly kill GDB if it fails to exit in |
| reasonable time. |
| |
| 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 |
| |
| 27.7 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). |
| |
| |
| File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI |
| |
| 27.8 GDB/MI Breakpoint Commands |
| =============================== |
| |
| This section documents GDB/MI commands for manipulating breakpoints. |
| |
| The '-break-after' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-after NUMBER COUNT |
| |
| The breakpoint number NUMBER is not in effect until it has been hit |
| COUNT times. To see how this is reflected in the output of the |
| '-break-list' command, see the description of the '-break-list' command |
| below. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'ignore'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], |
| times="0"} |
| (gdb) |
| -break-after 1 3 |
| ~ |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",thread-groups=["i1"],times="0",ignore="3"}]} |
| (gdb) |
| |
| The '-break-commands' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-commands NUMBER [ COMMAND1 ... COMMANDN ] |
| |
| Specifies the CLI commands that should be executed when breakpoint |
| NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. |
| If no command is specified, any previously-set commands are cleared. |
| *Note Break Commands::. Typical use of this functionality is tracing a |
| program, that is, printing of values of some variables whenever |
| breakpoint is hit and then continuing. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'commands'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], |
| times="0"} |
| (gdb) |
| -break-commands 1 "print v" "continue" |
| ^done |
| (gdb) |
| |
| The '-break-condition' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-condition NUMBER EXPR |
| |
| Breakpoint NUMBER will stop the program only if the condition in EXPR |
| is true. The condition becomes part of the '-break-list' output (see |
| the description of the '-break-list' command below). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'condition'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-condition 1 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]} |
| (gdb) |
| |
| The '-break-delete' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-delete ( BREAKPOINT )+ |
| |
| Delete the breakpoint(s) whose number(s) are specified in the |
| argument list. This is obviously reflected in the breakpoint list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-delete 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The '-break-disable' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-disable ( BREAKPOINT )+ |
| |
| Disable the named BREAKPOINT(s). The field 'enabled' in the break |
| list is now set to 'n' for the named BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'disable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-disable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",thread-groups=["i1"],times="0"}]} |
| (gdb) |
| |
| The '-break-enable' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-enable ( BREAKPOINT )+ |
| |
| Enable (previously disabled) BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'enable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-enable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",thread-groups=["i1"],times="0"}]} |
| (gdb) |
| |
| The '-break-info' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-info BREAKPOINT |
| |
| Get information about a single breakpoint. |
| |
| The result is a table of breakpoints. *Note GDB/MI Breakpoint |
| Information::, for details on the format of each breakpoint in the |
| table. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info break BREAKPOINT'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The '-break-insert' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] |
| [ -c CONDITION ] [ -i IGNORE-COUNT ] |
| [ -p THREAD-ID ] [ LOCATION ] |
| |
| If specified, LOCATION, can be one of: |
| |
| LINESPEC LOCATION |
| A linespec location. *Note Linespec Locations::. |
| |
| EXPLICIT LOCATION |
| An explicit location. GDB/MI explicit locations are analogous to |
| the CLI's explicit locations using the option names listed below. |
| *Note Explicit Locations::. |
| |
| '--source FILENAME' |
| The source file name of the location. This option requires |
| the use of either '--function' or '--line'. |
| |
| '--function FUNCTION' |
| The name of a function or method. |
| |
| '--label LABEL' |
| The name of a label. |
| |
| '--line LINEOFFSET' |
| An absolute or relative line offset from the start of the |
| location. |
| |
| ADDRESS LOCATION |
| An address location, *ADDRESS. *Note Address Locations::. |
| |
| The possible optional parameters of this command are: |
| |
| '-t' |
| Insert a temporary breakpoint. |
| '-h' |
| Insert a hardware breakpoint. |
| '-f' |
| If LOCATION cannot be parsed (for example if it refers to unknown |
| files or functions), create a pending breakpoint. Without this |
| flag, GDB will report an error, and won't create a breakpoint, if |
| LOCATION cannot be parsed. |
| '-d' |
| Create a disabled breakpoint. |
| '-a' |
| Create a tracepoint. *Note Tracepoints::. When this parameter is |
| used together with '-h', a fast tracepoint is created. |
| '-c CONDITION' |
| Make the breakpoint conditional on CONDITION. |
| '-i IGNORE-COUNT' |
| Initialize the IGNORE-COUNT. |
| '-p THREAD-ID' |
| Restrict the breakpoint to the thread with the specified global |
| THREAD-ID. |
| |
| Result |
| ...... |
| |
| *Note GDB/MI Breakpoint Information::, for details on the format of the |
| resulting breakpoint. |
| |
| Note: this format is open to change. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and |
| 'thbreak'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], |
| times="0"} |
| (gdb) |
| -break-insert -t foo |
| ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], |
| times="0"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x0001072c", func="main",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], |
| times="0"}, |
| bkpt={number="2",type="breakpoint",disp="del",enabled="y", |
| addr="0x00010774",func="foo",file="recursive2.c", |
| fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], |
| times="0"}]} |
| (gdb) |
| |
| The '-dprintf-insert' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -dprintf-insert [ -t ] [ -f ] [ -d ] |
| [ -c CONDITION ] [ -i IGNORE-COUNT ] |
| [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ] |
| [ ARGUMENT ] |
| |
| If supplied, LOCATION may be specified the same way as for the |
| '-break-insert' command. *Note -break-insert::. |
| |
| The possible optional parameters of this command are: |
| |
| '-t' |
| Insert a temporary breakpoint. |
| '-f' |
| If LOCATION cannot be parsed (for example, if it refers to unknown |
| files or functions), create a pending breakpoint. Without this |
| flag, GDB will report an error, and won't create a breakpoint, if |
| LOCATION cannot be parsed. |
| '-d' |
| Create a disabled breakpoint. |
| '-c CONDITION' |
| Make the breakpoint conditional on CONDITION. |
| '-i IGNORE-COUNT' |
| Set the ignore count of the breakpoint (*note ignore count: |
| Conditions.) to IGNORE-COUNT. |
| '-p THREAD-ID' |
| Restrict the breakpoint to the thread with the specified global |
| THREAD-ID. |
| |
| Result |
| ...... |
| |
| *Note GDB/MI Breakpoint Information::, for details on the format of the |
| resulting breakpoint. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'dprintf'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 4-dprintf-insert foo "At foo entry\n" |
| 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y", |
| addr="0x000000000040061b",func="foo",file="mi-dprintf.c", |
| fullname="mi-dprintf.c",line="25",thread-groups=["i1"], |
| times="0",script={"printf \"At foo entry\\n\"","continue"}, |
| original-location="foo"} |
| (gdb) |
| 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g |
| 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y", |
| addr="0x000000000040062a",func="foo",file="mi-dprintf.c", |
| fullname="mi-dprintf.c",line="26",thread-groups=["i1"], |
| times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"}, |
| original-location="mi-dprintf.c:26"} |
| (gdb) |
| |
| The '-break-list' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-list |
| |
| Displays the list of inserted breakpoints, showing the following |
| fields: |
| |
| 'Number' |
| number of the breakpoint |
| 'Type' |
| type of the breakpoint: 'breakpoint' or 'watchpoint' |
| 'Disposition' |
| should the breakpoint be deleted or disabled when it is hit: 'keep' |
| or 'nokeep' |
| 'Enabled' |
| is the breakpoint enabled or no: 'y' or 'n' |
| 'Address' |
| memory location at which the breakpoint is set |
| 'What' |
| logical location of the breakpoint, expressed by function name, |
| file name, line number |
| 'Thread-groups' |
| list of thread groups to which this breakpoint applies |
| 'Times' |
| number of times the breakpoint has been hit |
| |
| If there are no breakpoints or watchpoints, the 'BreakpointTable' |
| 'body' field is an empty list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info break'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], |
| times="0"}, |
| bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", |
| line="13",thread-groups=["i1"],times="0"}]} |
| (gdb) |
| |
| Here's an example of the result when there are no breakpoints: |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The '-break-passcount' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-passcount TRACEPOINT-NUMBER PASSCOUNT |
| |
| Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If |
| the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, |
| error is emitted. This corresponds to CLI command 'passcount'. |
| |
| The '-break-watch' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-watch [ -a | -r ] |
| |
| Create a watchpoint. With the '-a' option it will create an "access" |
| watchpoint, i.e., a watchpoint that triggers either on a read from or on |
| a write to the memory location. With the '-r' option, the watchpoint |
| created is a "read" watchpoint, i.e., it will trigger only when the |
| memory location is accessed for reading. Without either of the options, |
| the watchpoint created is a regular watchpoint, i.e., it will trigger |
| when the memory location is accessed for writing. *Note Setting |
| Watchpoints: Set Watchpoints. |
| |
| Note that '-break-list' will report a single list of watchpoints and |
| breakpoints inserted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'. |
| |
| Example |
| ....... |
| |
| Setting a watchpoint on a variable in the 'main' function: |
| |
| (gdb) |
| -break-watch x |
| ^done,wpt={number="2",exp="x"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, |
| value={old="-268439212",new="55"}, |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"} |
| (gdb) |
| |
| Setting a watchpoint on a variable local to a function. GDB will |
| stop the program execution twice: first for the variable changing value, |
| then for the watchpoint going out of scope. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="5",exp="C"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger", |
| wpt={number="5",exp="C"},value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", |
| arch="i386:x86_64"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-scope",wpnum="5", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", |
| arch="i386:x86_64"} |
| (gdb) |
| |
| Listing breakpoints and watchpoints, at different points in the |
| program execution. Note that once the watchpoint goes out of scope, it |
| is deleted. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="2",exp="C"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], |
| times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, |
| value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", |
| arch="i386:x86_64"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], |
| times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-scope",wpnum="2", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", |
| arch="i386:x86_64"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| thread-groups=["i1"],times="1"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI |
| |
| 27.9 GDB/MI Catchpoint Commands |
| =============================== |
| |
| This section documents GDB/MI commands for manipulating catchpoints. |
| |
| * Menu: |
| |
| * Shared Library GDB/MI Catchpoint Commands:: |
| * Ada Exception GDB/MI Catchpoint Commands:: |
| * C++ Exception GDB/MI Catchpoint Commands:: |
| |
| |
| File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands |
| |
| 27.9.1 Shared Library GDB/MI Catchpoints |
| ---------------------------------------- |
| |
| The '-catch-load' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-load [ -t ] [ -d ] REGEXP |
| |
| Add a catchpoint for library load events. If the '-t' option is |
| used, the catchpoint is a temporary one (*note Setting Breakpoints: Set |
| Breaks.). If the '-d' option is used, the catchpoint is created in a |
| disabled state. The 'regexp' argument is a regular expression used to |
| match the name of the loaded library. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'catch load'. |
| |
| Example |
| ....... |
| |
| -catch-load -t foo.so |
| ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y", |
| what="load of library matching foo.so",catch-type="load",times="0"} |
| (gdb) |
| |
| The '-catch-unload' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-unload [ -t ] [ -d ] REGEXP |
| |
| Add a catchpoint for library unload events. If the '-t' option is |
| used, the catchpoint is a temporary one (*note Setting Breakpoints: Set |
| Breaks.). If the '-d' option is used, the catchpoint is created in a |
| disabled state. The 'regexp' argument is a regular expression used to |
| match the name of the unloaded library. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'catch unload'. |
| |
| Example |
| ....... |
| |
| -catch-unload -d bar.so |
| ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n", |
| what="load of library matching bar.so",catch-type="unload",times="0"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Next: C++ Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands |
| |
| 27.9.2 Ada Exception GDB/MI Catchpoints |
| --------------------------------------- |
| |
| The following GDB/MI commands can be used to create catchpoints that |
| stop the execution when Ada exceptions are being raised. |
| |
| The '-catch-assert' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-assert [ -c CONDITION] [ -d ] [ -t ] |
| |
| Add a catchpoint for failed Ada assertions. |
| |
| The possible optional parameters for this command are: |
| |
| '-c CONDITION' |
| Make the catchpoint conditional on CONDITION. |
| '-d' |
| Create a disabled catchpoint. |
| '-t' |
| Create a temporary catchpoint. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'catch assert'. |
| |
| Example |
| ....... |
| |
| -catch-assert |
| ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep", |
| enabled="y",addr="0x0000000000404888",what="failed Ada assertions", |
| thread-groups=["i1"],times="0", |
| original-location="__gnat_debug_raise_assert_failure"} |
| (gdb) |
| |
| The '-catch-exception' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] |
| [ -t ] [ -u ] |
| |
| Add a catchpoint stopping when Ada exceptions are raised. By |
| default, the command stops the program when any Ada exception gets |
| raised. But it is also possible, by using some of the optional |
| parameters described below, to create more selective catchpoints. |
| |
| The possible optional parameters for this command are: |
| |
| '-c CONDITION' |
| Make the catchpoint conditional on CONDITION. |
| '-d' |
| Create a disabled catchpoint. |
| '-e EXCEPTION-NAME' |
| Only stop when EXCEPTION-NAME is raised. This option cannot be |
| used combined with '-u'. |
| '-t' |
| Create a temporary catchpoint. |
| '-u' |
| Stop only when an unhandled exception gets raised. This option |
| cannot be used combined with '-e'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'catch exception' and 'catch |
| exception unhandled'. |
| |
| Example |
| ....... |
| |
| -catch-exception -e Program_Error |
| ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", |
| enabled="y",addr="0x0000000000404874", |
| what="`Program_Error' Ada exception", thread-groups=["i1"], |
| times="0",original-location="__gnat_debug_raise_exception"} |
| (gdb) |
| |
| The '-catch-handlers' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-handlers [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] |
| [ -t ] |
| |
| Add a catchpoint stopping when Ada exceptions are handled. By |
| default, the command stops the program when any Ada exception gets |
| handled. But it is also possible, by using some of the optional |
| parameters described below, to create more selective catchpoints. |
| |
| The possible optional parameters for this command are: |
| |
| '-c CONDITION' |
| Make the catchpoint conditional on CONDITION. |
| '-d' |
| Create a disabled catchpoint. |
| '-e EXCEPTION-NAME' |
| Only stop when EXCEPTION-NAME is handled. |
| '-t' |
| Create a temporary catchpoint. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'catch handlers'. |
| |
| Example |
| ....... |
| |
| -catch-handlers -e Constraint_Error |
| ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", |
| enabled="y",addr="0x0000000000402f68", |
| what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"], |
| times="0",original-location="__gnat_begin_handler"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: C++ Exception GDB/MI Catchpoint Commands, Prev: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands |
| |
| 27.9.3 C++ Exception GDB/MI Catchpoints |
| --------------------------------------- |
| |
| The following GDB/MI commands can be used to create catchpoints that |
| stop the execution when C++ exceptions are being throw, rethrown, or |
| caught. |
| |
| The '-catch-throw' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-throw [ -t ] [ -r REGEXP] |
| |
| Stop when the debuggee throws a C++ exception. If REGEXP is given, |
| then only exceptions whose type matches the regular expression will be |
| caught. |
| |
| If '-t' is given, then the catchpoint is enabled only for one stop, |
| the catchpoint is automatically deleted after stopping once for the |
| event. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'catch throw' and 'tcatch throw' |
| (*note Set Catchpoints::). |
| |
| Example |
| ....... |
| |
| -catch-throw -r exception_type |
| ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", |
| what="exception throw",catch-type="throw", |
| thread-groups=["i1"], |
| regexp="exception_type",times="0"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| ~"\n" |
| ~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed |
| in __cxa_throw () from /lib64/libstdc++.so.6\n" |
| *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", |
| frame={addr="0x00007ffff7ae00ed",func="__cxa_throw", |
| args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, |
| thread-id="1",stopped-threads="all",core="6" |
| (gdb) |
| |
| The '-catch-rethrow' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-rethrow [ -t ] [ -r REGEXP] |
| |
| Stop when a C++ exception is re-thrown. If REGEXP is given, then |
| only exceptions whose type matches the regular expression will be |
| caught. |
| |
| If '-t' is given, then the catchpoint is enabled only for one stop, |
| the catchpoint is automatically deleted after the first event is caught. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'catch rethrow' and 'tcatch rethrow' |
| (*note Set Catchpoints::). |
| |
| Example |
| ....... |
| |
| -catch-rethrow -r exception_type |
| ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", |
| what="exception rethrow",catch-type="rethrow", |
| thread-groups=["i1"], |
| regexp="exception_type",times="0"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| ~"\n" |
| ~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed |
| in __cxa_rethrow () from /lib64/libstdc++.so.6\n" |
| *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", |
| frame={addr="0x00007ffff7ae00ed",func="__cxa_rethrow", |
| args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, |
| thread-id="1",stopped-threads="all",core="6" |
| (gdb) |
| |
| The '-catch-catch' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -catch-catch [ -t ] [ -r REGEXP] |
| |
| Stop when the debuggee catches a C++ exception. If REGEXP is given, |
| then only exceptions whose type matches the regular expression will be |
| caught. |
| |
| If '-t' is given, then the catchpoint is enabled only for one stop, |
| the catchpoint is automatically deleted after the first event is caught. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'catch catch' and 'tcatch catch' |
| (*note Set Catchpoints::). |
| |
| Example |
| ....... |
| |
| -catch-catch -r exception_type |
| ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", |
| what="exception catch",catch-type="catch", |
| thread-groups=["i1"], |
| regexp="exception_type",times="0"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| ~"\n" |
| ~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed |
| in __cxa_begin_catch () from /lib64/libstdc++.so.6\n" |
| *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", |
| frame={addr="0x00007ffff7ae00ed",func="__cxa_begin_catch", |
| args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, |
| thread-id="1",stopped-threads="all",core="6" |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI |
| |
| 27.10 GDB/MI Program Context |
| ============================ |
| |
| The '-exec-arguments' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-arguments ARGS |
| |
| Set the inferior program arguments, to be used in the next |
| '-exec-run'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'set args'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-arguments -v word |
| ^done |
| (gdb) |
| |
| The '-environment-cd' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-cd PATHDIR |
| |
| Set GDB's working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'cd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| |
| The '-environment-directory' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-directory [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for source files. |
| If the '-r' option is used, the search path is reset to the default |
| search path. If directories PATHDIR are supplied in addition to the |
| '-r' option, the search path is first reset and then addition occurs as |
| normal. Multiple directories may be specified, separated by blanks. |
| Specifying multiple directories in a single command results in the |
| directories added to the beginning of the search path in the same order |
| they were presented in the command. If blanks are needed as part of a |
| directory name, double-quotes should be used around the name. In the |
| command output, the path will show up separated by the system |
| directory-separator character. The directory-separator character must |
| not be used in any directory name. If no directories are specified, the |
| current search path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'dir'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory "" |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r /home/jjohnstn/src/gdb /usr/src |
| ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r |
| ^done,source-path="$cdir:$cwd" |
| (gdb) |
| |
| The '-environment-path' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-path [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for object files. |
| If the '-r' option is used, the search path is reset to the original |
| search path that existed at gdb start-up. If directories PATHDIR are |
| supplied in addition to the '-r' option, the search path is first reset |
| and then addition occurs as normal. Multiple directories may be |
| specified, separated by blanks. Specifying multiple directories in a |
| single command results in the directories added to the beginning of the |
| search path in the same order they were presented in the command. If |
| blanks are needed as part of a directory name, double-quotes should be |
| used around the name. In the command output, the path will show up |
| separated by the system directory-separator character. The |
| directory-separator character must not be used in any directory name. |
| If no directories are specified, the current path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'path'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-path |
| ^done,path="/usr/bin" |
| (gdb) |
| -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin |
| ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" |
| (gdb) |
| -environment-path -r /usr/local/bin |
| ^done,path="/usr/local/bin:/usr/bin" |
| (gdb) |
| |
| The '-environment-pwd' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-pwd |
| |
| Show the current working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'pwd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-pwd |
| ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI |
| |
| 27.11 GDB/MI Thread Commands |
| ============================ |
| |
| The '-thread-info' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-info [ THREAD-ID ] |
| |
| Reports information about either a specific thread, if the THREAD-ID |
| parameter is present, or about all threads. THREAD-ID is the thread's |
| global thread ID. When printing information about all threads, also |
| reports the global ID of the current thread. |
| |
| GDB Command |
| ........... |
| |
| The 'info thread' command prints the same information about all threads. |
| |
| Result |
| ...... |
| |
| The result contains the following attributes: |
| |
| 'threads' |
| A list of threads. The format of the elements of the list is |
| described in *note GDB/MI Thread Information::. |
| |
| 'current-thread-id' |
| The global id of the currently selected thread. This field is |
| omitted if there is no selected thread (for example, when the |
| selected inferior is not running, and therefore has no threads) or |
| if a THREAD-ID argument was passed to the command. |
| |
| Example |
| ....... |
| |
| -thread-info |
| ^done,threads=[ |
| {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", |
| frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", |
| args=[]},state="running"}, |
| {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", |
| frame={level="0",addr="0x0804891f",func="foo", |
| args=[{name="i",value="10"}], |
| file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"}, |
| state="running"}], |
| current-thread-id="1" |
| (gdb) |
| |
| The '-thread-list-ids' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -thread-list-ids |
| |
| Produces a list of the currently known global GDB thread ids. At the |
| end of the list it also prints the total number of such threads. |
| |
| This command is retained for historical reasons, the '-thread-info' |
| command should be used instead. |
| |
| GDB Command |
| ........... |
| |
| Part of 'info threads' supplies the same information. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| current-thread-id="1",number-of-threads="3" |
| (gdb) |
| |
| The '-thread-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-select THREAD-ID |
| |
| Make thread with global thread number THREAD-ID the current thread. |
| It prints the number of the new current thread, and the topmost frame |
| for that thread. |
| |
| This command is deprecated in favor of explicitly using the |
| '--thread' option to each command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'thread'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",thread-id="2",line="187", |
| file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" |
| (gdb) |
| -thread-list-ids |
| ^done, |
| thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| -thread-select 3 |
| ^done,new-thread-id="3", |
| frame={level="0",func="vprintf", |
| args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, |
| {name="arg",value="0x2"}],file="vprintf.c",line="31",arch="i386:x86_64"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI |
| |
| 27.12 GDB/MI Ada Tasking Commands |
| ================================= |
| |
| The '-ada-task-info' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -ada-task-info [ TASK-ID ] |
| |
| Reports information about either a specific Ada task, if the TASK-ID |
| parameter is present, or about all Ada tasks. |
| |
| GDB Command |
| ........... |
| |
| The 'info tasks' command prints the same information about all Ada tasks |
| (*note Ada Tasks::). |
| |
| Result |
| ...... |
| |
| The result is a table of Ada tasks. The following columns are defined |
| for each Ada task: |
| |
| 'current' |
| This field exists only for the current thread. It has the value |
| '*'. |
| |
| 'id' |
| The identifier that GDB uses to refer to the Ada task. |
| |
| 'task-id' |
| The identifier that the target uses to refer to the Ada task. |
| |
| 'thread-id' |
| The global thread identifier of the thread corresponding to the Ada |
| task. |
| |
| This field should always exist, as Ada tasks are always implemented |
| on top of a thread. But if GDB cannot find this corresponding |
| thread for any reason, the field is omitted. |
| |
| 'parent-id' |
| This field exists only when the task was created by another task. |
| In this case, it provides the ID of the parent task. |
| |
| 'priority' |
| The base priority of the task. |
| |
| 'state' |
| The current state of the task. For a detailed description of the |
| possible states, see *note Ada Tasks::. |
| |
| 'name' |
| The name of the task. |
| |
| Example |
| ....... |
| |
| -ada-task-info |
| ^done,tasks={nr_rows="3",nr_cols="8", |
| hdr=[{width="1",alignment="-1",col_name="current",colhdr=""}, |
| {width="3",alignment="1",col_name="id",colhdr="ID"}, |
| {width="9",alignment="1",col_name="task-id",colhdr="TID"}, |
| {width="4",alignment="1",col_name="thread-id",colhdr=""}, |
| {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"}, |
| {width="3",alignment="1",col_name="priority",colhdr="Pri"}, |
| {width="22",alignment="-1",col_name="state",colhdr="State"}, |
| {width="1",alignment="2",col_name="name",colhdr="Name"}], |
| body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", |
| state="Child Termination Wait",name="main_task"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI |
| |
| 27.13 GDB/MI Program Execution |
| ============================== |
| |
| These are the asynchronous commands which generate the out-of-band |
| record '*stopped'. Currently GDB only really executes asynchronously |
| with remote targets and this interaction is mimicked in other cases. |
| |
| The '-exec-continue' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-continue [--reverse] [--all|--thread-group N] |
| |
| Resumes the execution of the inferior program, which will continue to |
| execute until it reaches a debugger stop event. If the '--reverse' |
| option is specified, execution resumes in reverse until it reaches a |
| stop event. Stop events may include |
| * breakpoints or watchpoints |
| * signals or exceptions |
| * the end of the process (or its beginning under '--reverse') |
| * the end or beginning of a replay log if one is being used. |
| In all-stop mode (*note All-Stop Mode::), may resume only one thread, |
| or all threads, depending on the value of the 'scheduler-locking' |
| variable. If '--all' is specified, all threads (in all inferiors) will |
| be resumed. The '--all' option is ignored in all-stop mode. If the |
| '--thread-group' options is specified, then all threads in that thread |
| group are resumed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB corresponding is 'continue'. |
| |
| Example |
| ....... |
| |
| -exec-continue |
| ^running |
| (gdb) |
| @Hello world |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ |
| func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", |
| line="13",arch="i386:x86_64"} |
| (gdb) |
| |
| The '-exec-finish' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-finish [--reverse] |
| |
| Resumes the execution of the inferior program until the current |
| function is exited. Displays the results returned by the function. If |
| the '--reverse' option is specified, resumes the reverse execution of |
| the inferior program until the point where current function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'finish'. |
| |
| Example |
| ....... |
| |
| Function returning 'void'. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| @hello from foo |
| *stopped,reason="function-finished",frame={func="main",args=[], |
| file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"} |
| (gdb) |
| |
| Function returning other than 'void'. The name of the internal GDB |
| variable storing the result is printed, together with the value itself. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", |
| args=[{name="a",value="1"],{name="b",value="9"}}, |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| gdb-result-var="$1",return-value="0" |
| (gdb) |
| |
| The '-exec-interrupt' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-interrupt [--all|--thread-group N] |
| |
| Interrupts the background execution of the target. Note how the |
| token associated with the stop message is the one for the execution |
| command that has been interrupted. The token for the interrupt itself |
| only appears in the '^done' output. If the user is trying to interrupt |
| a non-running program, an error message will be printed. |
| |
| Note that when asynchronous execution is enabled, this command is |
| asynchronous just like other execution commands. That is, first the |
| '^done' response will be printed, and the target stop will be reported |
| after that using the '*stopped' notification. |
| |
| In non-stop mode, only the context thread is interrupted by default. |
| All threads (in all inferiors) will be interrupted if the '--all' option |
| is specified. If the '--thread-group' option is specified, all threads |
| in that group will be interrupted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'interrupt'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 111-exec-continue |
| 111^running |
| |
| (gdb) |
| 222-exec-interrupt |
| 222^done |
| (gdb) |
| 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", |
| frame={addr="0x00010140",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"} |
| (gdb) |
| |
| (gdb) |
| -exec-interrupt |
| ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." |
| (gdb) |
| |
| The '-exec-jump' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-jump LOCATION |
| |
| Resumes execution of the inferior program at the location specified |
| by parameter. *Note Specify Location::, for a description of the |
| different forms of LOCATION. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'jump'. |
| |
| Example |
| ....... |
| |
| -exec-jump foo.c:10 |
| *running,thread-id="all" |
| ^running |
| |
| The '-exec-next' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached. |
| |
| If the '--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the beginning of the previous source |
| line. If you issue this command on the first line of a function, it |
| will take you back to the caller of that function, to the source line |
| where the function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'next'. |
| |
| Example |
| ....... |
| |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="8",file="hello.c" |
| (gdb) |
| |
| The '-exec-next-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next-instruction [--reverse] |
| |
| Executes one machine instruction. If the instruction is a function |
| call, continues until the function returns. If the program stops at an |
| instruction in the middle of a source line, the address will be printed |
| as well. |
| |
| If the '--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the previous instruction. If the |
| previously executed instruction was a return from another function, it |
| will continue to execute in reverse until the call to that function |
| (from the current stack frame) is reached. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'nexti'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| addr="0x000100d4",line="5",file="hello.c" |
| (gdb) |
| |
| The '-exec-return' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-return |
| |
| Makes current function return immediately. Doesn't execute the |
| inferior. Displays the new current frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'return'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 200-break-insert callee4 |
| 200^done,bkpt={number="1",addr="0x00010734", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 000-exec-run |
| 000^running |
| (gdb) |
| 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| arch="i386:x86_64"} |
| (gdb) |
| 205-break-delete |
| 205^done |
| (gdb) |
| 111-exec-return |
| 111^done,frame={level="0",func="callee3", |
| args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", |
| arch="i386:x86_64"} |
| (gdb) |
| |
| The '-exec-run' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-run [ --all | --thread-group N ] [ --start ] |
| |
| Starts execution of the inferior from the beginning. The inferior |
| executes until either a breakpoint is encountered or the program exits. |
| In the latter case the output will include an exit code, if the program |
| has exited exceptionally. |
| |
| When neither the '--all' nor the '--thread-group' option is |
| specified, the current inferior is started. If the '--thread-group' |
| option is specified, it should refer to a thread group of type |
| 'process', and that thread group will be started. If the '--all' option |
| is specified, then all inferiors will be started. |
| |
| Using the '--start' option instructs the debugger to stop the |
| execution at the start of the inferior's main subprogram, following the |
| same behavior as the 'start' command (*note Starting::). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'run'. |
| |
| Examples |
| ........ |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"} |
| (gdb) |
| |
| Program exited normally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited-normally" |
| (gdb) |
| |
| Program exited exceptionally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited",exit-code="01" |
| (gdb) |
| |
| Another way the program can terminate is if it receives a signal such |
| as 'SIGINT'. In this case, GDB/MI displays this: |
| |
| (gdb) |
| *stopped,reason="exited-signalled",signal-name="SIGINT", |
| signal-meaning="Interrupt" |
| |
| The '-exec-step' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached, if the next source line is |
| not a function call. If it is, stop at the first instruction of the |
| called function. If the '--reverse' option is specified, resumes |
| reverse execution of the inferior program, stopping at the beginning of |
| the previously executed source line. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'step'. |
| |
| Example |
| ....... |
| |
| Stepping into a function: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[{name="a",value="10"}, |
| {name="b",value="0"}],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"} |
| (gdb) |
| |
| Regular stepping: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="14",file="recursive2.c" |
| (gdb) |
| |
| The '-exec-step-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step-instruction [--reverse] |
| |
| Resumes the inferior which executes one machine instruction. If the |
| '--reverse' option is specified, resumes reverse execution of the |
| inferior program, stopping at the previously executed instruction. The |
| output, once GDB has stopped, will vary depending on whether we have |
| stopped in the middle of a source line or not. In the former case, the |
| address at which the program stopped will be printed as well. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'stepi'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"} |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={addr="0x000100f4",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"} |
| (gdb) |
| |
| The '-exec-until' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-until [ LOCATION ] |
| |
| Executes the inferior until the LOCATION specified in the argument is |
| reached. If there is no argument, the inferior executes until a source |
| line greater than the current one is reached. The reason for stopping |
| in this case will be 'location-reached'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'until'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-until recursive2.c:6 |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="location-reached",frame={func="main",args=[], |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6", |
| arch="i386:x86_64"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI |
| |
| 27.14 GDB/MI Stack Manipulation Commands |
| ======================================== |
| |
| The '-enable-frame-filters' Command |
| ----------------------------------- |
| |
| -enable-frame-filters |
| |
| GDB allows Python-based frame filters to affect the output of the MI |
| commands relating to stack traces. As there is no way to implement this |
| in a fully backward-compatible way, a front end must request that this |
| functionality be enabled. |
| |
| Once enabled, this feature cannot be disabled. |
| |
| Note that if Python support has not been compiled into GDB, this |
| command will still succeed (and do nothing). |
| |
| The '-stack-info-frame' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-frame |
| |
| Get info on the selected frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'info frame' or 'frame' (without |
| arguments). |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-info-frame |
| ^done,frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", |
| arch="i386:x86_64"} |
| (gdb) |
| |
| The '-stack-info-depth' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-depth [ MAX-DEPTH ] |
| |
| Return the depth of the stack. If the integer argument MAX-DEPTH is |
| specified, do not count beyond MAX-DEPTH frames. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| For a stack with frame levels 0 through 11: |
| |
| (gdb) |
| -stack-info-depth |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 4 |
| ^done,depth="4" |
| (gdb) |
| -stack-info-depth 12 |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 11 |
| ^done,depth="11" |
| (gdb) |
| -stack-info-depth 13 |
| ^done,depth="12" |
| (gdb) |
| |
| The '-stack-list-arguments' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES |
| [ LOW-FRAME HIGH-FRAME ] |
| |
| Display a list of the arguments for the frames between LOW-FRAME and |
| HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, |
| list the arguments for the whole call stack. If the two arguments are |
| equal, show the single frame at the corresponding level. It is an error |
| if LOW-FRAME is larger than the actual number of frames. On the other |
| hand, HIGH-FRAME may be larger than the actual number of frames, in |
| which case only existing frames will be returned. |
| |
| If PRINT-VALUES is 0 or '--no-values', print only the names of the |
| variables; if it is 1 or '--all-values', print also their values; and if |
| it is 2 or '--simple-values', print the name, type and value for simple |
| data types, and the name and type for arrays, structures and unions. If |
| the option '--no-frame-filters' is supplied, then Python frame filters |
| will not be executed. |
| |
| If the '--skip-unavailable' option is specified, arguments that are |
| not available are not listed. Partially available arguments are still |
| displayed, however. |
| |
| Use of this command to obtain arguments in a single frame is |
| deprecated in favor of the '-stack-list-variables' command. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args' |
| command which partially overlaps with the functionality of |
| '-stack-list-arguments'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-frames |
| ^done, |
| stack=[ |
| frame={level="0",addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| arch="i386:x86_64"}, |
| frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", |
| arch="i386:x86_64"}, |
| frame={level="2",addr="0x0001078c",func="callee2", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22", |
| arch="i386:x86_64"}, |
| frame={level="3",addr="0x000107b4",func="callee1", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27", |
| arch="i386:x86_64"}, |
| frame={level="4",addr="0x000107e0",func="main", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32", |
| arch="i386:x86_64"}] |
| (gdb) |
| -stack-list-arguments 0 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1",args=[name="strarg"]}, |
| frame={level="2",args=[name="intarg",name="strarg"]}, |
| frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 1 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1", |
| args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, |
| frame={level="2",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}, |
| {frame={level="3",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}, |
| {name="fltarg",value="3.5"}]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 0 2 2 |
| ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] |
| (gdb) |
| -stack-list-arguments 1 2 2 |
| ^done,stack-args=[frame={level="2", |
| args=[{name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}] |
| (gdb) |
| |
| The '-stack-list-frames' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ] |
| |
| List the frames currently on the stack. For each frame it displays |
| the following info: |
| |
| 'LEVEL' |
| The frame number, 0 being the topmost frame, i.e., the innermost |
| function. |
| 'ADDR' |
| The '$pc' value for that frame. |
| 'FUNC' |
| Function name. |
| 'FILE' |
| File name of the source file where the function lives. |
| 'FULLNAME' |
| The full file name of the source file where the function lives. |
| 'LINE' |
| Line number corresponding to the '$pc'. |
| 'FROM' |
| The shared library where this function is defined. This is only |
| given if the frame's function is not known. |
| 'ARCH' |
| Frame's architecture. |
| |
| If invoked without arguments, this command prints a backtrace for the |
| whole stack. If given two integer arguments, it shows the frames whose |
| levels are between the two arguments (inclusive). If the two arguments |
| are equal, it shows the single frame at the corresponding level. It is |
| an error if LOW-FRAME is larger than the actual number of frames. On |
| the other hand, HIGH-FRAME may be larger than the actual number of |
| frames, in which case only existing frames will be returned. If the |
| option '--no-frame-filters' is supplied, then Python frame filters will |
| not be executed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'backtrace' and 'where'. |
| |
| Example |
| ....... |
| |
| Full stack backtrace: |
| |
| (gdb) |
| -stack-list-frames |
| ^done,stack= |
| [frame={level="0",addr="0x0001076c",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11", |
| arch="i386:x86_64"}, |
| frame={level="1",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="2",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="6",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="7",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="8",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="9",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="10",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="11",addr="0x00010738",func="main", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4", |
| arch="i386:x86_64"}] |
| (gdb) |
| |
| Show frames between LOW_FRAME and HIGH_FRAME: |
| |
| (gdb) |
| -stack-list-frames 3 5 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}] |
| (gdb) |
| |
| Show a single frame: |
| |
| (gdb) |
| -stack-list-frames 3 3 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", |
| arch="i386:x86_64"}] |
| (gdb) |
| |
| The '-stack-list-locals' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES |
| |
| Display the local variable names for the selected frame. If |
| PRINT-VALUES is 0 or '--no-values', print only the names of the |
| variables; if it is 1 or '--all-values', print also their values; and if |
| it is 2 or '--simple-values', print the name, type and value for simple |
| data types, and the name and type for arrays, structures and unions. In |
| this last case, a frontend can immediately display the value of simple |
| data types and create variable objects for other data types when the |
| user wishes to explore their values in more detail. If the option |
| '--no-frame-filters' is supplied, then Python frame filters will not be |
| executed. |
| |
| If the '--skip-unavailable' option is specified, local variables that |
| are not available are not listed. Partially available local variables |
| are still displayed, however. |
| |
| This command is deprecated in favor of the '-stack-list-variables' |
| command. |
| |
| GDB Command |
| ........... |
| |
| 'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-locals 0 |
| ^done,locals=[name="A",name="B",name="C"] |
| (gdb) |
| -stack-list-locals --all-values |
| ^done,locals=[{name="A",value="1"},{name="B",value="2"}, |
| {name="C",value="{1, 2, 3}"}] |
| -stack-list-locals --simple-values |
| ^done,locals=[{name="A",type="int",value="1"}, |
| {name="B",type="int",value="2"},{name="C",type="int [3]"}] |
| (gdb) |
| |
| The '-stack-list-variables' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES |
| |
| Display the names of local variables and function arguments for the |
| selected frame. If PRINT-VALUES is 0 or '--no-values', print only the |
| names of the variables; if it is 1 or '--all-values', print also their |
| values; and if it is 2 or '--simple-values', print the name, type and |
| value for simple data types, and the name and type for arrays, |
| structures and unions. If the option '--no-frame-filters' is supplied, |
| then Python frame filters will not be executed. |
| |
| If the '--skip-unavailable' option is specified, local variables and |
| arguments that are not available are not listed. Partially available |
| arguments and local variables are still displayed, however. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-variables --thread 1 --frame 0 --all-values |
| ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] |
| (gdb) |
| |
| The '-stack-select-frame' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-select-frame FRAMENUM |
| |
| Change the selected frame. Select a different frame FRAMENUM on the |
| stack. |
| |
| This command in deprecated in favor of passing the '--frame' option |
| to every command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'frame', 'up', 'down', |
| 'select-frame', 'up-silent', and 'down-silent'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-select-frame 2 |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI |
| |
| 27.15 GDB/MI Variable Objects |
| ============================= |
| |
| Introduction to Variable Objects |
| -------------------------------- |
| |
| Variable objects are "object-oriented" MI interface for examining and |
| changing values of expressions. Unlike some other MI interfaces that |
| work with expressions, variable objects are specifically designed for |
| simple and efficient presentation in the frontend. A variable object is |
| identified by string name. When a variable object is created, the |
| frontend specifies the expression for that variable object. The |
| expression can be a simple variable, or it can be an arbitrary complex |
| expression, and can even involve CPU registers. After creating a |
| variable object, the frontend can invoke other variable object |
| operations--for example to obtain or change the value of a variable |
| object, or to change display format. |
| |
| Variable objects have hierarchical tree structure. Any variable |
| object that corresponds to a composite type, such as structure in C, has |
| a number of child variable objects, for example corresponding to each |
| element of a structure. A child variable object can itself have |
| children, recursively. Recursion ends when we reach leaf variable |
| objects, which always have built-in types. Child variable objects are |
| created only by explicit request, so if a frontend is not interested in |
| the children of a particular variable object, no child will be created. |
| |
| For a leaf variable object it is possible to obtain its value as a |
| string, or set the value from a string. String value can be also |
| obtained for a non-leaf variable object, but it's generally a string |
| that only indicates the type of the object, and does not list its |
| contents. Assignment to a non-leaf variable object is not allowed. |
| |
| A frontend does not need to read the values of all variable objects |
| each time the program stops. Instead, MI provides an update command |
| that lists all variable objects whose values has changed since the last |
| update operation. This considerably reduces the amount of data that |
| must be transferred to the frontend. As noted above, children variable |
| objects are created on demand, and only leaf variable objects have a |
| real value. As result, gdb will read target memory only for leaf |
| variables that frontend has created. |
| |
| The automatic update is not always desirable. For example, a |
| frontend might want to keep a value of some expression for future |
| reference, and never update it. For another example, fetching memory is |
| relatively slow for embedded targets, so a frontend might want to |
| disable automatic update for the variables that are either not visible |
| on the screen, or "closed". This is possible using so called "frozen |
| variable objects". Such variable objects are never implicitly updated. |
| |
| Variable objects can be either "fixed" or "floating". For the fixed |
| variable object, the expression is parsed when the variable object is |
| created, including associating identifiers to specific variables. The |
| meaning of expression never changes. For a floating variable object the |
| values of variables whose names appear in the expressions are |
| re-evaluated every time in the context of the current frame. Consider |
| this example: |
| |
| void do_work(...) |
| { |
| struct work_state state; |
| |
| if (...) |
| do_work(...); |
| } |
| |
| If a fixed variable object for the 'state' variable is created in |
| this function, and we enter the recursive call, the variable object will |
| report the value of 'state' in the top-level 'do_work' invocation. On |
| the other hand, a floating variable object will report the value of |
| 'state' in the current frame. |
| |
| If an expression specified when creating a fixed variable object |
| refers to a local variable, the variable object becomes bound to the |
| thread and frame in which the variable object is created. When such |
| variable object is updated, GDB makes sure that the thread/frame |
| combination the variable object is bound to still exists, and |
| re-evaluates the variable object in context of that thread/frame. |
| |
| The following is the complete set of GDB/MI operations defined to |
| access this functionality: |
| |
| *Operation* *Description* |
| |
| '-enable-pretty-printing' enable Python-based pretty-printing |
| '-var-create' create a variable object |
| '-var-delete' delete the variable object and/or its |
| children |
| '-var-set-format' set the display format of this variable |
| '-var-show-format' show the display format of this variable |
| '-var-info-num-children' tells how many children this object has |
| '-var-list-children' return a list of the object's children |
| '-var-info-type' show the type of this variable object |
| '-var-info-expression' print parent-relative expression that |
| this variable object represents |
| '-var-info-path-expression' print full expression that this variable |
| object represents |
| '-var-show-attributes' is this variable editable? does it exist |
| here? |
| '-var-evaluate-expression' get the value of this variable |
| '-var-assign' set the value of this variable |
| '-var-update' update the variable and its children |
| '-var-set-frozen' set frozenness attribute |
| '-var-set-update-range' set range of children to display on |
| update |
| |
| In the next subsection we describe each operation in detail and |
| suggest how it can be used. |
| |
| Description And Use of Operations on Variable Objects |
| ----------------------------------------------------- |
| |
| The '-enable-pretty-printing' Command |
| ------------------------------------- |
| |
| -enable-pretty-printing |
| |
| GDB allows Python-based visualizers to affect the output of the MI |
| variable object commands. However, because there was no way to |
| implement this in a fully backward-compatible way, a front end must |
| request that this functionality be enabled. |
| |
| Once enabled, this feature cannot be disabled. |
| |
| Note that if Python support has not been compiled into GDB, this |
| command will still succeed (and do nothing). |
| |
| This feature is currently (as of GDB 7.0) experimental, and may work |
| differently in future versions of GDB. |
| |
| The '-var-create' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-create {NAME | "-"} |
| {FRAME-ADDR | "*" | "@"} EXPRESSION |
| |
| This operation creates a variable object, which allows the monitoring |
| of a variable, the result of an expression, a memory cell or a CPU |
| register. |
| |
| The NAME parameter is the string by which the object can be |
| referenced. It must be unique. If '-' is specified, the varobj system |
| will generate a string "varNNNNNN" automatically. It will be unique |
| provided that one does not specify NAME of that format. The command |
| fails if a duplicate name is found. |
| |
| The frame under which the expression should be evaluated can be |
| specified by FRAME-ADDR. A '*' indicates that the current frame should |
| be used. A '@' indicates that a floating variable object must be |
| created. |
| |
| EXPRESSION is any expression valid on the current language set (must |
| not begin with a '*'), or one of the following: |
| |
| * '*ADDR', where ADDR is the address of a memory cell |
| |
| * '*ADDR-ADDR' -- a memory address range (TBD) |
| |
| * '$REGNAME' -- a CPU register name |
| |
| A varobj's contents may be provided by a Python-based pretty-printer. |
| In this case the varobj is known as a "dynamic varobj". Dynamic varobjs |
| have slightly different semantics in some cases. If the |
| '-enable-pretty-printing' command is not sent, then GDB will never |
| create a dynamic varobj. This ensures backward compatibility for |
| existing clients. |
| |
| Result |
| ...... |
| |
| This operation returns attributes of the newly-created varobj. These |
| are: |
| |
| 'name' |
| The name of the varobj. |
| |
| 'numchild' |
| The number of children of the varobj. This number is not |
| necessarily reliable for a dynamic varobj. Instead, you must |
| examine the 'has_more' attribute. |
| |
| 'value' |
| The varobj's scalar value. For a varobj whose type is some sort of |
| aggregate (e.g., a 'struct'), or for a dynamic varobj, this value |
| will not be interesting. |
| |
| 'type' |
| The varobj's type. This is a string representation of the type, as |
| would be printed by the GDB CLI. If 'print object' (*note set print |
| object: Print Settings.) is set to 'on', the _actual_ (derived) |
| type of the object is shown rather than the _declared_ one. |
| |
| 'thread-id' |
| If a variable object is bound to a specific thread, then this is |
| the thread's global identifier. |
| |
| 'has_more' |
| For a dynamic varobj, this indicates whether there appear to be any |
| children available. For a non-dynamic varobj, this will be 0. |
| |
| 'dynamic' |
| This attribute will be present and have the value '1' if the varobj |
| is a dynamic varobj. If the varobj is not a dynamic varobj, then |
| this attribute will not be present. |
| |
| 'displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| 'display_hint' method. *Note Pretty Printing API::. |
| |
| Typical output will look like this: |
| |
| name="NAME",numchild="N",type="TYPE",thread-id="M", |
| has_more="HAS_MORE" |
| |
| The '-var-delete' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-delete [ -c ] NAME |
| |
| Deletes a previously created variable object and all of its children. |
| With the '-c' option, just deletes the children. |
| |
| Returns an error if the object NAME is not found. |
| |
| The '-var-set-format' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-format NAME FORMAT-SPEC |
| |
| Sets the output format for the value of the object NAME to be |
| FORMAT-SPEC. |
| |
| The syntax for the FORMAT-SPEC is as follows: |
| |
| FORMAT-SPEC ==> |
| {binary | decimal | hexadecimal | octal | natural | zero-hexadecimal} |
| |
| The natural format is the default format choosen automatically based |
| on the variable type (like decimal for an 'int', hex for pointers, |
| etc.). |
| |
| The zero-hexadecimal format has a representation similar to |
| hexadecimal but with padding zeroes to the left of the value. For |
| example, a 32-bit hexadecimal value of 0x1234 would be represented as |
| 0x00001234 in the zero-hexadecimal format. |
| |
| For a variable with children, the format is set only on the variable |
| itself, and the children are not affected. |
| |
| The '-var-show-format' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-show-format NAME |
| |
| Returns the format used to display the value of the object NAME. |
| |
| FORMAT ==> |
| FORMAT-SPEC |
| |
| The '-var-info-num-children' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-info-num-children NAME |
| |
| Returns the number of children of a variable object NAME: |
| |
| numchild=N |
| |
| Note that this number is not completely reliable for a dynamic |
| varobj. It will return the current number of children, but more |
| children may be available. |
| |
| The '-var-list-children' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-list-children [PRINT-VALUES] NAME [FROM TO] |
| |
| Return a list of the children of the specified variable object and |
| create variable objects for them, if they do not already exist. With a |
| single argument or if PRINT-VALUES has a value of 0 or '--no-values', |
| print only the names of the variables; if PRINT-VALUES is 1 or |
| '--all-values', also print their values; and if it is 2 or |
| '--simple-values' print the name and value for simple data types and |
| just the name for arrays, structures and unions. |
| |
| FROM and TO, if specified, indicate the range of children to report. |
| If FROM or TO is less than zero, the range is reset and all children |
| will be reported. Otherwise, children starting at FROM (zero-based) and |
| up to and excluding TO will be reported. |
| |
| If a child range is requested, it will only affect the current call |
| to '-var-list-children', but not future calls to '-var-update'. For |
| this, you must instead use '-var-set-update-range'. The intent of this |
| approach is to enable a front end to implement any update approach it |
| likes; for example, scrolling a view may cause the front end to request |
| more children with '-var-list-children', and then the front end could |
| call '-var-set-update-range' with a different range to ensure that |
| future updates are restricted to just the visible items. |
| |
| For each child the following results are returned: |
| |
| NAME |
| Name of the variable object created for this child. |
| |
| EXP |
| The expression to be shown to the user by the front end to |
| designate this child. For example this may be the name of a |
| structure member. |
| |
| For a dynamic varobj, this value cannot be used to form an |
| expression. There is no way to do this at all with a dynamic |
| varobj. |
| |
| For C/C++ structures there are several pseudo children returned to |
| designate access qualifiers. For these pseudo children EXP is |
| 'public', 'private', or 'protected'. In this case the type and |
| value are not present. |
| |
| A dynamic varobj will not report the access qualifying |
| pseudo-children, regardless of the language. This information is |
| not available at all with a dynamic varobj. |
| |
| NUMCHILD |
| Number of children this child has. For a dynamic varobj, this will |
| be 0. |
| |
| TYPE |
| The type of the child. If 'print object' (*note set print object: |
| Print Settings.) is set to 'on', the _actual_ (derived) type of the |
| object is shown rather than the _declared_ one. |
| |
| VALUE |
| If values were requested, this is the value. |
| |
| THREAD-ID |
| If this variable object is associated with a thread, this is the |
| thread's global thread id. Otherwise this result is not present. |
| |
| FROZEN |
| If the variable object is frozen, this variable will be present |
| with a value of 1. |
| |
| DISPLAYHINT |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| 'display_hint' method. *Note Pretty Printing API::. |
| |
| DYNAMIC |
| This attribute will be present and have the value '1' if the varobj |
| is a dynamic varobj. If the varobj is not a dynamic varobj, then |
| this attribute will not be present. |
| |
| The result may have its own attributes: |
| |
| 'displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| 'display_hint' method. *Note Pretty Printing API::. |
| |
| 'has_more' |
| This is an integer attribute which is nonzero if there are children |
| remaining after the end of the selected range. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-list-children n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,type=TYPE},(repeats N times)] |
| (gdb) |
| -var-list-children --all-values n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,value=VALUE,type=TYPE},(repeats N times)] |
| |
| The '-var-info-type' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-type NAME |
| |
| Returns the type of the specified variable NAME. The type is |
| returned as a string in the same format as it is output by the GDB CLI: |
| |
| type=TYPENAME |
| |
| The '-var-info-expression' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-expression NAME |
| |
| Returns a string that is suitable for presenting this variable object |
| in user interface. The string is generally not valid expression in the |
| current language, and cannot be evaluated. |
| |
| For example, if 'a' is an array, and variable object 'A' was created |
| for 'a', then we'll get this output: |
| |
| (gdb) -var-info-expression A.1 |
| ^done,lang="C",exp="1" |
| |
| Here, the value of 'lang' is the language name, which can be found in |
| *note Supported Languages::. |
| |
| Note that the output of the '-var-list-children' command also |
| includes those expressions, so the '-var-info-expression' command is of |
| limited use. |
| |
| The '-var-info-path-expression' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-path-expression NAME |
| |
| Returns an expression that can be evaluated in the current context |
| and will yield the same value that a variable object has. Compare this |
| with the '-var-info-expression' command, which result can be used only |
| for UI presentation. Typical use of the '-var-info-path-expression' |
| command is creating a watchpoint from a variable object. |
| |
| This command is currently not valid for children of a dynamic varobj, |
| and will give an error when invoked on one. |
| |
| For example, suppose 'C' is a C++ class, derived from class 'Base', |
| and that the 'Base' class has a member called 'm_size'. Assume a |
| variable 'c' is has the type of 'C' and a variable object 'C' was |
| created for variable 'c'. Then, we'll get this output: |
| (gdb) -var-info-path-expression C.Base.public.m_size |
| ^done,path_expr=((Base)c).m_size) |
| |
| The '-var-show-attributes' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-show-attributes NAME |
| |
| List attributes of the specified variable object NAME: |
| |
| status=ATTR [ ( ,ATTR )* ] |
| |
| where ATTR is '{ { editable | noneditable } | TBD }'. |
| |
| The '-var-evaluate-expression' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-evaluate-expression [-f FORMAT-SPEC] NAME |
| |
| Evaluates the expression that is represented by the specified |
| variable object and returns its value as a string. The format of the |
| string can be specified with the '-f' option. The possible values of |
| this option are the same as for '-var-set-format' (*note |
| -var-set-format::). If the '-f' option is not specified, the current |
| display format will be used. The current display format can be changed |
| using the '-var-set-format' command. |
| |
| value=VALUE |
| |
| Note that one must invoke '-var-list-children' for a variable before |
| the value of a child variable can be evaluated. |
| |
| The '-var-assign' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-assign NAME EXPRESSION |
| |
| Assigns the value of EXPRESSION to the variable object specified by |
| NAME. The object must be 'editable'. If the variable's value is |
| altered by the assign, the variable will show up in any subsequent |
| '-var-update' list. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update * |
| ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] |
| (gdb) |
| |
| The '-var-update' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-update [PRINT-VALUES] {NAME | "*"} |
| |
| Reevaluate the expressions corresponding to the variable object NAME |
| and all its direct and indirect children, and return the list of |
| variable objects whose values have changed; NAME must be a root variable |
| object. Here, "changed" means that the result of |
| '-var-evaluate-expression' before and after the '-var-update' is |
| different. If '*' is used as the variable object names, all existing |
| variable objects are updated, except for frozen ones (*note |
| -var-set-frozen::). The option PRINT-VALUES determines whether both |
| names and values, or just names are printed. The possible values of |
| this option are the same as for '-var-list-children' (*note |
| -var-list-children::). It is recommended to use the '--all-values' |
| option, to reduce the number of MI commands needed on each program stop. |
| |
| With the '*' parameter, if a variable object is bound to a currently |
| running thread, it will not be updated, without any diagnostic. |
| |
| If '-var-set-update-range' was previously used on a varobj, then only |
| the selected range of children will be reported. |
| |
| '-var-update' reports all the changed varobjs in a tuple named |
| 'changelist'. |
| |
| Each item in the change list is itself a tuple holding: |
| |
| 'name' |
| The name of the varobj. |
| |
| 'value' |
| If values were requested for this update, then this field will be |
| present and will hold the value of the varobj. |
| |
| 'in_scope' |
| This field is a string which may take one of three values: |
| |
| '"true"' |
| The variable object's current value is valid. |
| |
| '"false"' |
| The variable object does not currently hold a valid value but |
| it may hold one in the future if its associated expression |
| comes back into scope. |
| |
| '"invalid"' |
| The variable object no longer holds a valid value. This can |
| occur when the executable file being debugged has changed, |
| either through recompilation or by using the GDB 'file' |
| command. The front end should normally choose to delete these |
| variable objects. |
| |
| In the future new values may be added to this list so the front |
| should be prepared for this possibility. *Note GDB/MI Development |
| and Front Ends: GDB/MI Development and Front Ends. |
| |
| 'type_changed' |
| This is only present if the varobj is still valid. If the type |
| changed, then this will be the string 'true'; otherwise it will be |
| 'false'. |
| |
| When a varobj's type changes, its children are also likely to have |
| become incorrect. Therefore, the varobj's children are |
| automatically deleted when this attribute is 'true'. Also, the |
| varobj's update range, when set using the '-var-set-update-range' |
| command, is unset. |
| |
| 'new_type' |
| If the varobj's type changed, then this field will be present and |
| will hold the new type. |
| |
| 'new_num_children' |
| For a dynamic varobj, if the number of children changed, or if the |
| type changed, this will be the new number of children. |
| |
| The 'numchild' field in other varobj responses is generally not |
| valid for a dynamic varobj - it will show the number of children |
| that GDB knows about, but because dynamic varobjs lazily |
| instantiate their children, this will not reflect the number of |
| children which may be available. |
| |
| The 'new_num_children' attribute only reports changes to the number |
| of children known by GDB. This is the only way to detect whether |
| an update has removed children (which necessarily can only happen |
| at the end of the update range). |
| |
| 'displayhint' |
| The display hint, if any. |
| |
| 'has_more' |
| This is an integer value, which will be 1 if there are more |
| children available outside the varobj's update range. |
| |
| 'dynamic' |
| This attribute will be present and have the value '1' if the varobj |
| is a dynamic varobj. If the varobj is not a dynamic varobj, then |
| this attribute will not be present. |
| |
| 'new_children' |
| If new children were added to a dynamic varobj within the selected |
| update range (as set by '-var-set-update-range'), then they will be |
| listed in this attribute. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update --all-values var1 |
| ^done,changelist=[{name="var1",value="3",in_scope="true", |
| type_changed="false"}] |
| (gdb) |
| |
| The '-var-set-frozen' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-frozen NAME FLAG |
| |
| Set the frozenness flag on the variable object NAME. The FLAG |
| parameter should be either '1' to make the variable frozen or '0' to |
| make it unfrozen. If a variable object is frozen, then neither itself, |
| nor any of its children, are implicitly updated by '-var-update' of a |
| parent variable or by '-var-update *'. Only '-var-update' of the |
| variable itself will update its value and values of its children. After |
| a variable object is unfrozen, it is implicitly updated by all |
| subsequent '-var-update' operations. Unfreezing a variable does not |
| update it, only subsequent '-var-update' does. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-frozen V 1 |
| ^done |
| (gdb) |
| |
| The '-var-set-update-range' command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-update-range NAME FROM TO |
| |
| Set the range of children to be returned by future invocations of |
| '-var-update'. |
| |
| FROM and TO indicate the range of children to report. If FROM or TO |
| is less than zero, the range is reset and all children will be reported. |
| Otherwise, children starting at FROM (zero-based) and up to and |
| excluding TO will be reported. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-update-range V 1 2 |
| ^done |
| |
| The '-var-set-visualizer' command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-visualizer NAME VISUALIZER |
| |
| Set a visualizer for the variable object NAME. |
| |
| VISUALIZER is the visualizer to use. The special value 'None' means |
| to disable any visualizer in use. |
| |
| If not 'None', VISUALIZER must be a Python expression. This |
| expression must evaluate to a callable object which accepts a single |
| argument. GDB will call this object with the value of the varobj NAME |
| as an argument (this is done so that the same Python pretty-printing |
| code can be used for both the CLI and MI). When called, this object must |
| return an object which conforms to the pretty-printing interface (*note |
| Pretty Printing API::). |
| |
| The pre-defined function 'gdb.default_visualizer' may be used to |
| select a visualizer by following the built-in process (*note Selecting |
| Pretty-Printers::). This is done automatically when a varobj is |
| created, and so ordinarily is not needed. |
| |
| This feature is only available if Python support is enabled. The MI |
| command '-list-features' (*note GDB/MI Support Commands::) can be used |
| to check this. |
| |
| Example |
| ....... |
| |
| Resetting the visualizer: |
| |
| (gdb) |
| -var-set-visualizer V None |
| ^done |
| |
| Reselecting the default (type-based) visualizer: |
| |
| (gdb) |
| -var-set-visualizer V gdb.default_visualizer |
| ^done |
| |
| Suppose 'SomeClass' is a visualizer class. A lambda expression can |
| be used to instantiate this class for a varobj: |
| |
| (gdb) |
| -var-set-visualizer V "lambda val: SomeClass()" |
| ^done |
| |
| |
| File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI |
| |
| 27.16 GDB/MI Data Manipulation |
| ============================== |
| |
| This section describes the GDB/MI commands that manipulate data: examine |
| memory and registers, evaluate expressions, etc. |
| |
| For details about what an addressable memory unit is, *note |
| addressable memory unit::. |
| |
| The '-data-disassemble' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-disassemble |
| [ -s START-ADDR -e END-ADDR ] |
| | [ -a ADDR ] |
| | [ -f FILENAME -l LINENUM [ -n LINES ] ] |
| -- MODE |
| |
| Where: |
| |
| 'START-ADDR' |
| is the beginning address (or '$pc') |
| 'END-ADDR' |
| is the end address |
| 'ADDR' |
| is an address anywhere within (or the name of) the function to |
| disassemble. If an address is specified, the whole function |
| surrounding that address will be disassembled. If a name is |
| specified, the whole function with that name will be disassembled. |
| 'FILENAME' |
| is the name of the file to disassemble |
| 'LINENUM' |
| is the line number to disassemble around |
| 'LINES' |
| is the number of disassembly lines to be produced. If it is -1, |
| the whole function will be disassembled, in case no END-ADDR is |
| specified. If END-ADDR is specified as a non-zero value, and LINES |
| is lower than the number of disassembly lines between START-ADDR |
| and END-ADDR, only LINES lines are displayed; if LINES is higher |
| than the number of lines between START-ADDR and END-ADDR, only the |
| lines up to END-ADDR are displayed. |
| 'MODE' |
| is one of: |
| * 0 disassembly only |
| * 1 mixed source and disassembly (deprecated) |
| * 2 disassembly with raw opcodes |
| * 3 mixed source and disassembly with raw opcodes (deprecated) |
| * 4 mixed source and disassembly |
| * 5 mixed source and disassembly with raw opcodes |
| |
| Modes 1 and 3 are deprecated. The output is "source centric" which |
| hasn't proved useful in practice. *Note Machine Code::, for a |
| discussion of the difference between '/m' and '/s' output of the |
| 'disassemble' command. |
| |
| Result |
| ...... |
| |
| The result of the '-data-disassemble' command will be a list named |
| 'asm_insns', the contents of this list depend on the MODE used with the |
| '-data-disassemble' command. |
| |
| For modes 0 and 2 the 'asm_insns' list contains tuples with the |
| following fields: |
| |
| 'address' |
| The address at which this instruction was disassembled. |
| |
| 'func-name' |
| The name of the function this instruction is within. |
| |
| 'offset' |
| The decimal offset in bytes from the start of 'func-name'. |
| |
| 'inst' |
| The text disassembly for this 'address'. |
| |
| 'opcodes' |
| This field is only present for modes 2, 3 and 5. This contains the |
| raw opcode bytes for the 'inst' field. |
| |
| For modes 1, 3, 4 and 5 the 'asm_insns' list contains tuples named |
| 'src_and_asm_line', each of which has the following fields: |
| |
| 'line' |
| The line number within 'file'. |
| |
| 'file' |
| The file name from the compilation unit. This might be an absolute |
| file name or a relative file name depending on the compile command |
| used. |
| |
| 'fullname' |
| Absolute file name of 'file'. It is converted to a canonical form |
| using the source file search path (*note Specifying Source |
| Directories: Source Path.) and after resolving all the symbolic |
| links. |
| |
| If the source file is not found this field will contain the path as |
| present in the debug information. |
| |
| 'line_asm_insn' |
| This is a list of tuples containing the disassembly for 'line' in |
| 'file'. The fields of each tuple are the same as for |
| '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name', |
| 'offset', 'inst', and optionally 'opcodes'. |
| |
| Note that whatever included in the 'inst' field, is not manipulated |
| directly by GDB/MI, i.e., it is not possible to adjust its format. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'disassemble'. |
| |
| Example |
| ....... |
| |
| Disassemble from the current value of '$pc' to '$pc + 20': |
| |
| (gdb) |
| -data-disassemble -s $pc -e "$pc + 20" -- 0 |
| ^done, |
| asm_insns=[ |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}, |
| {address="0x000107c8",func-name="main",offset="12", |
| inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, |
| {address="0x000107cc",func-name="main",offset="16", |
| inst="sethi %hi(0x11800), %o2"}, |
| {address="0x000107d0",func-name="main",offset="20", |
| inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] |
| (gdb) |
| |
| Disassemble the whole 'main' function. Line 32 is part of 'main'. |
| |
| -data-disassemble -f basics.c -l 32 -- 0 |
| ^done,asm_insns=[ |
| {address="0x000107bc",func-name="main",offset="0", |
| inst="save %sp, -112, %sp"}, |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}, |
| [...] |
| {address="0x0001081c",func-name="main",offset="96",inst="ret "}, |
| {address="0x00010820",func-name="main",offset="100",inst="restore "}] |
| (gdb) |
| |
| Disassemble 3 instructions from the start of 'main': |
| |
| (gdb) |
| -data-disassemble -f basics.c -l 32 -n 3 -- 0 |
| ^done,asm_insns=[ |
| {address="0x000107bc",func-name="main",offset="0", |
| inst="save %sp, -112, %sp"}, |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}] |
| (gdb) |
| |
| Disassemble 3 instructions from the start of 'main' in mixed mode: |
| |
| (gdb) |
| -data-disassemble -f basics.c -l 32 -n 3 -- 1 |
| ^done,asm_insns=[ |
| src_and_asm_line={line="31", |
| file="../../../src/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", |
| line_asm_insn=[{address="0x000107bc", |
| func-name="main",offset="0",inst="save %sp, -112, %sp"}]}, |
| src_and_asm_line={line="32", |
| file="../../../src/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", |
| line_asm_insn=[{address="0x000107c0", |
| func-name="main",offset="4",inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}]}] |
| (gdb) |
| |
| The '-data-evaluate-expression' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-evaluate-expression EXPR |
| |
| Evaluate EXPR as an expression. The expression could contain an |
| inferior function call. The function call will execute synchronously. |
| If the expression contains spaces, it must be enclosed in double quotes. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'print', 'output', and 'call'. In |
| 'gdbtk' only, there's a corresponding 'gdb_eval' command. |
| |
| Example |
| ....... |
| |
| In the following example, the numbers that precede the commands are the |
| "tokens" described in *note GDB/MI Command Syntax: GDB/MI Command |
| Syntax. Notice how GDB/MI returns the same tokens in its output. |
| |
| 211-data-evaluate-expression A |
| 211^done,value="1" |
| (gdb) |
| 311-data-evaluate-expression &A |
| 311^done,value="0xefffeb7c" |
| (gdb) |
| 411-data-evaluate-expression A+3 |
| 411^done,value="4" |
| (gdb) |
| 511-data-evaluate-expression "A + 3" |
| 511^done,value="4" |
| (gdb) |
| |
| The '-data-list-changed-registers' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -data-list-changed-registers |
| |
| Display a list of the registers that have changed. |
| |
| GDB Command |
| ........... |
| |
| GDB doesn't have a direct analog for this command; 'gdbtk' has the |
| corresponding command 'gdb_changed_register_list'. |
| |
| Example |
| ....... |
| |
| On a PPC MBX board: |
| |
| (gdb) |
| -exec-continue |
| ^running |
| |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ |
| func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", |
| line="5",arch="powerpc"} |
| (gdb) |
| -data-list-changed-registers |
| ^done,changed-registers=["0","1","2","4","5","6","7","8","9", |
| "10","11","13","14","15","16","17","18","19","20","21","22","23", |
| "24","25","26","27","28","30","31","64","65","66","67","69"] |
| (gdb) |
| |
| The '-data-list-register-names' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-list-register-names [ ( REGNO )+ ] |
| |
| Show a list of register names for the current target. If no |
| arguments are given, it shows a list of the names of all the registers. |
| If integer numbers are given as arguments, it will print a list of the |
| names of the registers corresponding to the arguments. To ensure |
| consistency between a register name and its number, the output list may |
| include empty register names. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have a command which corresponds to |
| '-data-list-register-names'. In 'gdbtk' there is a corresponding |
| command 'gdb_regnames'. |
| |
| Example |
| ....... |
| |
| For the PPC MBX board: |
| (gdb) |
| -data-list-register-names |
| ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", |
| "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", |
| "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", |
| "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", |
| "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", |
| "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", |
| "", "pc","ps","cr","lr","ctr","xer"] |
| (gdb) |
| -data-list-register-names 1 2 3 |
| ^done,register-names=["r1","r2","r3"] |
| (gdb) |
| |
| The '-data-list-register-values' Command |
| ---------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-list-register-values |
| [ --skip-unavailable ] FMT [ ( REGNO )*] |
| |
| Display the registers' contents. The format according to which the |
| registers' contents are to be returned is given by FMT, followed by an |
| optional list of numbers specifying the registers to display. A missing |
| list of numbers indicates that the contents of all the registers must be |
| returned. The '--skip-unavailable' option indicates that only the |
| available registers are to be returned. |
| |
| Allowed formats for FMT are: |
| |
| 'x' |
| Hexadecimal |
| 'o' |
| Octal |
| 't' |
| Binary |
| 'd' |
| Decimal |
| 'r' |
| Raw |
| 'N' |
| Natural |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are 'info reg', 'info all-reg', and (in |
| 'gdbtk') 'gdb_fetch_registers'. |
| |
| Example |
| ....... |
| |
| For a PPC MBX board (note: line breaks are for readability only, they |
| don't appear in the actual output): |
| |
| (gdb) |
| -data-list-register-values r 64 65 |
| ^done,register-values=[{number="64",value="0xfe00a300"}, |
| {number="65",value="0x00029002"}] |
| (gdb) |
| -data-list-register-values x |
| ^done,register-values=[{number="0",value="0xfe0043c8"}, |
| {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, |
| {number="3",value="0x0"},{number="4",value="0xa"}, |
| {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, |
| {number="7",value="0xfe011e98"},{number="8",value="0x2"}, |
| {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, |
| {number="11",value="0x1"},{number="12",value="0x0"}, |
| {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, |
| {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, |
| {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, |
| {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, |
| {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, |
| {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, |
| {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, |
| {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, |
| {number="29",value="0x0"},{number="30",value="0xfe010000"}, |
| {number="31",value="0x0"},{number="32",value="0x0"}, |
| {number="33",value="0x0"},{number="34",value="0x0"}, |
| {number="35",value="0x0"},{number="36",value="0x0"}, |
| {number="37",value="0x0"},{number="38",value="0x0"}, |
| {number="39",value="0x0"},{number="40",value="0x0"}, |
| {number="41",value="0x0"},{number="42",value="0x0"}, |
| {number="43",value="0x0"},{number="44",value="0x0"}, |
| {number="45",value="0x0"},{number="46",value="0x0"}, |
| {number="47",value="0x0"},{number="48",value="0x0"}, |
| {number="49",value="0x0"},{number="50",value="0x0"}, |
| {number="51",value="0x0"},{number="52",value="0x0"}, |
| {number="53",value="0x0"},{number="54",value="0x0"}, |
| {number="55",value="0x0"},{number="56",value="0x0"}, |
| {number="57",value="0x0"},{number="58",value="0x0"}, |
| {number="59",value="0x0"},{number="60",value="0x0"}, |
| {number="61",value="0x0"},{number="62",value="0x0"}, |
| {number="63",value="0x0"},{number="64",value="0xfe00a300"}, |
| {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, |
| {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, |
| {number="69",value="0x20002b03"}] |
| (gdb) |
| |
| The '-data-read-memory' Command |
| ------------------------------- |
| |
| This command is deprecated, use '-data-read-memory-bytes' instead. |
| |
| Synopsis |
| ........ |
| |
| -data-read-memory [ -o BYTE-OFFSET ] |
| ADDRESS WORD-FORMAT WORD-SIZE |
| NR-ROWS NR-COLS [ ASCHAR ] |
| |
| where: |
| |
| 'ADDRESS' |
| An expression specifying the address of the first memory word to be |
| read. Complex expressions containing embedded white space should |
| be quoted using the C convention. |
| |
| 'WORD-FORMAT' |
| The format to be used to print the memory words. The notation is |
| the same as for GDB's 'print' command (*note Output Formats: Output |
| Formats.). |
| |
| 'WORD-SIZE' |
| The size of each memory word in bytes. |
| |
| 'NR-ROWS' |
| The number of rows in the output table. |
| |
| 'NR-COLS' |
| The number of columns in the output table. |
| |
| 'ASCHAR' |
| If present, indicates that each row should include an ASCII dump. |
| The value of ASCHAR is used as a padding character when a byte is |
| not a member of the printable ASCII character set (printable ASCII |
| characters are those whose code is between 32 and 126, |
| inclusively). |
| |
| 'BYTE-OFFSET' |
| An offset to add to the ADDRESS before fetching memory. |
| |
| This command displays memory contents as a table of NR-ROWS by |
| NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS * |
| NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should |
| less than the requested number of bytes be returned by the target, the |
| missing words are identified using 'N/A'. The number of bytes read from |
| the target is returned in 'nr-bytes' and the starting address used to |
| read memory in 'addr'. |
| |
| The address of the next/previous row or page is available in |
| 'next-row' and 'prev-row', 'next-page' and 'prev-page'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory |
| read command. |
| |
| Example |
| ....... |
| |
| Read six bytes of memory starting at 'bytes+6' but then offset by '-6' |
| bytes. Format as three rows of two columns. One byte per word. |
| Display each word in hex. |
| |
| (gdb) |
| 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 |
| 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", |
| next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", |
| prev-page="0x0000138a",memory=[ |
| {addr="0x00001390",data=["0x00","0x01"]}, |
| {addr="0x00001392",data=["0x02","0x03"]}, |
| {addr="0x00001394",data=["0x04","0x05"]}] |
| (gdb) |
| |
| Read two bytes of memory starting at address 'shorts + 64' and |
| display as a single word formatted in decimal. |
| |
| (gdb) |
| 5-data-read-memory shorts+64 d 2 1 1 |
| 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", |
| next-row="0x00001512",prev-row="0x0000150e", |
| next-page="0x00001512",prev-page="0x0000150e",memory=[ |
| {addr="0x00001510",data=["128"]}] |
| (gdb) |
| |
| Read thirty two bytes of memory starting at 'bytes+16' and format as |
| eight rows of four columns. Include a string encoding with 'x' used as |
| the non-printable character. |
| |
| (gdb) |
| 4-data-read-memory bytes+16 x 1 8 4 x |
| 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", |
| next-row="0x000013c0",prev-row="0x0000139c", |
| next-page="0x000013c0",prev-page="0x00001380",memory=[ |
| {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, |
| {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, |
| {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, |
| {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, |
| {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, |
| {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, |
| {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, |
| {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] |
| (gdb) |
| |
| The '-data-read-memory-bytes' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-read-memory-bytes [ -o OFFSET ] |
| ADDRESS COUNT |
| |
| where: |
| |
| 'ADDRESS' |
| An expression specifying the address of the first addressable |
| memory unit to be read. Complex expressions containing embedded |
| white space should be quoted using the C convention. |
| |
| 'COUNT' |
| The number of addressable memory units to read. This should be an |
| integer literal. |
| |
| 'OFFSET' |
| The offset relative to ADDRESS at which to start reading. This |
| should be an integer literal. This option is provided so that a |
| frontend is not required to first evaluate address and then perform |
| address arithmetics itself. |
| |
| This command attempts to read all accessible memory regions in the |
| specified range. First, all regions marked as unreadable in the memory |
| map (if one is defined) will be skipped. *Note Memory Region |
| Attributes::. Second, GDB will attempt to read the remaining regions. |
| For each one, if reading full region results in an errors, GDB will try |
| to read a subset of the region. |
| |
| In general, every single memory unit in the region may be readable or |
| not, and the only way to read every readable unit is to try a read at |
| every address, which is not practical. Therefore, GDB will attempt to |
| read all accessible memory units at either beginning or the end of the |
| region, using a binary division scheme. This heuristic works well for |
| reading across a memory map boundary. Note that if a region has a |
| readable range that is neither at the beginning or the end, GDB will not |
| read it. |
| |
| The result record (*note GDB/MI Result Records::) that is output of |
| the command includes a field named 'memory' whose content is a list of |
| tuples. Each tuple represent a successfully read memory block and has |
| the following fields: |
| |
| 'begin' |
| The start address of the memory block, as hexadecimal literal. |
| |
| 'end' |
| The end address of the memory block, as hexadecimal literal. |
| |
| 'offset' |
| The offset of the memory block, as hexadecimal literal, relative to |
| the start address passed to '-data-read-memory-bytes'. |
| |
| 'contents' |
| The contents of the memory block, in hex. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is 'x'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -data-read-memory-bytes &a 10 |
| ^done,memory=[{begin="0xbffff154",offset="0x00000000", |
| end="0xbffff15e", |
| contents="01000000020000000300"}] |
| (gdb) |
| |
| The '-data-write-memory-bytes' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-write-memory-bytes ADDRESS CONTENTS |
| -data-write-memory-bytes ADDRESS CONTENTS [COUNT] |
| |
| where: |
| |
| 'ADDRESS' |
| An expression specifying the address of the first addressable |
| memory unit to be written. Complex expressions containing embedded |
| white space should be quoted using the C convention. |
| |
| 'CONTENTS' |
| The hex-encoded data to write. It is an error if CONTENTS does not |
| represent an integral number of addressable memory units. |
| |
| 'COUNT' |
| Optional argument indicating the number of addressable memory units |
| to be written. If COUNT is greater than CONTENTS' length, GDB will |
| repeatedly write CONTENTS until it fills COUNT memory units. |
| |
| GDB Command |
| ........... |
| |
| There's no corresponding GDB command. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -data-write-memory-bytes &a "aabbccdd" |
| ^done |
| (gdb) |
| |
| (gdb) |
| -data-write-memory-bytes &a "aabbccdd" 16e |
| ^done |
| (gdb) |
| |