| 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: Pascal, Next: Rust, Prev: Fortran, Up: Supported Languages |
| |
| 15.4.7 Pascal |
| ------------- |
| |
| Debugging Pascal programs which use sets, subranges, file variables, or |
| nested functions does not currently work. GDB does not support entering |
| expressions, printing values, or similar features using Pascal syntax. |
| |
| The Pascal-specific command 'set print pascal_static-members' |
| controls whether static members of Pascal objects are displayed. *Note |
| pascal_static-members: Print Settings. |
| |
| |
| File: gdb.info, Node: Rust, Next: Modula-2, Prev: Pascal, Up: Supported Languages |
| |
| 15.4.8 Rust |
| ----------- |
| |
| GDB supports the Rust Programming Language (https://www.rust-lang.org/). |
| Type- and value-printing, and expression parsing, are reasonably |
| complete. However, there are a few peculiarities and holes to be aware |
| of. |
| |
| * Linespecs (*note Specify Location::) are never relative to the |
| current crate. Instead, they act as if there were a global |
| namespace of crates, somewhat similar to the way 'extern crate' |
| behaves. |
| |
| That is, if GDB is stopped at a breakpoint in a function in crate |
| 'A', module 'B', then 'break B::f' will attempt to set a breakpoint |
| in a function named 'f' in a crate named 'B'. |
| |
| As a consequence of this approach, linespecs also cannot refer to |
| items using 'self::' or 'super::'. |
| |
| * Because GDB implements Rust name-lookup semantics in expressions, |
| it will sometimes prepend the current crate to a name. For |
| example, if GDB is stopped at a breakpoint in the crate 'K', then |
| 'print ::x::y' will try to find the symbol 'K::x::y'. |
| |
| However, since it is useful to be able to refer to other crates |
| when debugging, GDB provides the 'extern' extension to circumvent |
| this. To use the extension, just put 'extern' before a path |
| expression to refer to the otherwise unavailable "global" scope. |
| |
| In the above example, if you wanted to refer to the symbol 'y' in |
| the crate 'x', you would use 'print extern x::y'. |
| |
| * The Rust expression evaluator does not support "statement-like" |
| expressions such as 'if' or 'match', or lambda expressions. |
| |
| * Tuple expressions are not implemented. |
| |
| * The Rust expression evaluator does not currently implement the |
| 'Drop' trait. Objects that may be created by the evaluator will |
| never be destroyed. |
| |
| * GDB does not implement type inference for generics. In order to |
| call generic functions or otherwise refer to generic items, you |
| will have to specify the type parameters manually. |
| |
| * GDB currently uses the C++ demangler for Rust. In most cases this |
| does not cause any problems. However, in an expression context, |
| completing a generic function name will give syntactically invalid |
| results. This happens because Rust requires the '::' operator |
| between the function name and its generic arguments. For example, |
| GDB might provide a completion like 'crate::f<u32>', where the |
| parser would require 'crate::f::<u32>'. |
| |
| * As of this writing, the Rust compiler (version 1.8) has a few holes |
| in the debugging information it generates. These holes prevent |
| certain features from being implemented by GDB: |
| |
| * Method calls cannot be made via traits. |
| |
| * Operator overloading is not implemented. |
| |
| * When debugging in a monomorphized function, you cannot use the |
| generic type names. |
| |
| * The type 'Self' is not available. |
| |
| * 'use' statements are not available, so some names may not be |
| available in the crate. |
| |
| |
| File: gdb.info, Node: Modula-2, Next: Ada, Prev: Rust, Up: Supported Languages |
| |
| 15.4.9 Modula-2 |
| --------------- |
| |
| The extensions made to GDB to support Modula-2 only support output from |
| the GNU Modula-2 compiler (which is currently being developed). Other |
| Modula-2 compilers are not currently supported, and attempting to debug |
| executables produced by them is most likely to give an error as GDB |
| reads in the executable's symbol table. |
| |
| * Menu: |
| |
| * M2 Operators:: Built-in operators |
| * Built-In Func/Proc:: Built-in functions and procedures |
| * M2 Constants:: Modula-2 constants |
| * M2 Types:: Modula-2 types |
| * M2 Defaults:: Default settings for Modula-2 |
| * Deviations:: Deviations from standard Modula-2 |
| * M2 Checks:: Modula-2 type and range checks |
| * M2 Scope:: The scope operators '::' and '.' |
| * GDB/M2:: GDB and Modula-2 |
| |
| |
| File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 |
| |
| 15.4.9.1 Operators |
| .................. |
| |
| Operators must be defined on values of specific types. For instance, |
| '+' is defined on numbers, but not on structures. Operators are often |
| defined on groups of types. For the purposes of Modula-2, the following |
| definitions hold: |
| |
| * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their |
| subranges. |
| |
| * _Character types_ consist of 'CHAR' and its subranges. |
| |
| * _Floating-point types_ consist of 'REAL'. |
| |
| * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'. |
| |
| * _Scalar types_ consist of all of the above. |
| |
| * _Set types_ consist of 'SET' and 'BITSET' types. |
| |
| * _Boolean types_ consist of 'BOOLEAN'. |
| |
| The following operators are supported, and appear in order of increasing |
| precedence: |
| |
| ',' |
| Function argument or array index separator. |
| |
| ':=' |
| Assignment. The value of VAR ':=' VALUE is VALUE. |
| |
| '<, >' |
| Less than, greater than on integral, floating-point, or enumerated |
| types. |
| |
| '<=, >=' |
| Less than or equal to, greater than or equal to on integral, |
| floating-point and enumerated types, or set inclusion on set types. |
| Same precedence as '<'. |
| |
| '=, <>, #' |
| Equality and two ways of expressing inequality, valid on scalar |
| types. Same precedence as '<'. In GDB scripts, only '<>' is |
| available for inequality, since '#' conflicts with the script |
| comment character. |
| |
| 'IN' |
| Set membership. Defined on set types and the types of their |
| members. Same precedence as '<'. |
| |
| 'OR' |
| Boolean disjunction. Defined on boolean types. |
| |
| 'AND, &' |
| Boolean conjunction. Defined on boolean types. |
| |
| '@' |
| The GDB "artificial array" operator (*note Expressions: |
| Expressions.). |
| |
| '+, -' |
| Addition and subtraction on integral and floating-point types, or |
| union and difference on set types. |
| |
| '*' |
| Multiplication on integral and floating-point types, or set |
| intersection on set types. |
| |
| '/' |
| Division on floating-point types, or symmetric set difference on |
| set types. Same precedence as '*'. |
| |
| 'DIV, MOD' |
| Integer division and remainder. Defined on integral types. Same |
| precedence as '*'. |
| |
| '-' |
| Negative. Defined on 'INTEGER' and 'REAL' data. |
| |
| '^' |
| Pointer dereferencing. Defined on pointer types. |
| |
| 'NOT' |
| Boolean negation. Defined on boolean types. Same precedence as |
| '^'. |
| |
| '.' |
| 'RECORD' field selector. Defined on 'RECORD' data. Same |
| precedence as '^'. |
| |
| '[]' |
| Array indexing. Defined on 'ARRAY' data. Same precedence as '^'. |
| |
| '()' |
| Procedure argument list. Defined on 'PROCEDURE' objects. Same |
| precedence as '^'. |
| |
| '::, .' |
| GDB and Modula-2 scope operators. |
| |
| _Warning:_ Set expressions and their operations are not yet |
| supported, so GDB treats the use of the operator 'IN', or the use |
| of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>=' |
| on sets as an error. |
| |
| |
| File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 |
| |
| 15.4.9.2 Built-in Functions and Procedures |
| .......................................... |
| |
| Modula-2 also makes available several built-in procedures and functions. |
| In describing these, the following metavariables are used: |
| |
| A |
| represents an 'ARRAY' variable. |
| |
| C |
| represents a 'CHAR' constant or variable. |
| |
| I |
| represents a variable or constant of integral type. |
| |
| M |
| represents an identifier that belongs to a set. Generally used in |
| the same function with the metavariable S. The type of S should be |
| 'SET OF MTYPE' (where MTYPE is the type of M). |
| |
| N |
| represents a variable or constant of integral or floating-point |
| type. |
| |
| R |
| represents a variable or constant of floating-point type. |
| |
| T |
| represents a type. |
| |
| V |
| represents a variable. |
| |
| X |
| represents a variable or constant of one of many types. See the |
| explanation of the function for details. |
| |
| All Modula-2 built-in procedures also return a result, described |
| below. |
| |
| 'ABS(N)' |
| Returns the absolute value of N. |
| |
| 'CAP(C)' |
| If C is a lower case letter, it returns its upper case equivalent, |
| otherwise it returns its argument. |
| |
| 'CHR(I)' |
| Returns the character whose ordinal value is I. |
| |
| 'DEC(V)' |
| Decrements the value in the variable V by one. Returns the new |
| value. |
| |
| 'DEC(V,I)' |
| Decrements the value in the variable V by I. Returns the new |
| value. |
| |
| 'EXCL(M,S)' |
| Removes the element M from the set S. Returns the new set. |
| |
| 'FLOAT(I)' |
| Returns the floating point equivalent of the integer I. |
| |
| 'HIGH(A)' |
| Returns the index of the last member of A. |
| |
| 'INC(V)' |
| Increments the value in the variable V by one. Returns the new |
| value. |
| |
| 'INC(V,I)' |
| Increments the value in the variable V by I. Returns the new |
| value. |
| |
| 'INCL(M,S)' |
| Adds the element M to the set S if it is not already there. |
| Returns the new set. |
| |
| 'MAX(T)' |
| Returns the maximum value of the type T. |
| |
| 'MIN(T)' |
| Returns the minimum value of the type T. |
| |
| 'ODD(I)' |
| Returns boolean TRUE if I is an odd number. |
| |
| 'ORD(X)' |
| Returns the ordinal value of its argument. For example, the |
| ordinal value of a character is its ASCII value (on machines |
| supporting the ASCII character set). The argument X must be of an |
| ordered type, which include integral, character and enumerated |
| types. |
| |
| 'SIZE(X)' |
| Returns the size of its argument. The argument X can be a variable |
| or a type. |
| |
| 'TRUNC(R)' |
| Returns the integral part of R. |
| |
| 'TSIZE(X)' |
| Returns the size of its argument. The argument X can be a variable |
| or a type. |
| |
| 'VAL(T,I)' |
| Returns the member of the type T whose ordinal value is I. |
| |
| _Warning:_ Sets and their operations are not yet supported, so GDB |
| treats the use of procedures 'INCL' and 'EXCL' as an error. |
| |
| |
| File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 |
| |
| 15.4.9.3 Constants |
| .................. |
| |
| GDB allows you to express the constants of Modula-2 in the following |
| ways: |
| |
| * Integer constants are simply a sequence of digits. When used in an |
| expression, a constant is interpreted to be type-compatible with |
| the rest of the expression. Hexadecimal integers are specified by |
| a trailing 'H', and octal integers by a trailing 'B'. |
| |
| * Floating point constants appear as a sequence of digits, followed |
| by a decimal point and another sequence of digits. An optional |
| exponent can then be specified, in the form 'E[+|-]NNN', where |
| '[+|-]NNN' is the desired exponent. All of the digits of the |
| floating point constant must be valid decimal (base 10) digits. |
| |
| * Character constants consist of a single character enclosed by a |
| pair of like quotes, either single (''') or double ('"'). They may |
| also be expressed by their ordinal value (their ASCII value, |
| usually) followed by a 'C'. |
| |
| * String constants consist of a sequence of characters enclosed by a |
| pair of like quotes, either single (''') or double ('"'). Escape |
| sequences in the style of C are also allowed. *Note C and C++ |
| Constants: C Constants, for a brief explanation of escape |
| sequences. |
| |
| * Enumerated constants consist of an enumerated identifier. |
| |
| * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'. |
| |
| * Pointer constants consist of integral values only. |
| |
| * Set constants are not yet supported. |
| |
| |
| File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 |
| |
| 15.4.9.4 Modula-2 Types |
| ....................... |
| |
| Currently GDB can print the following data types in Modula-2 syntax: |
| array types, record types, set types, pointer types, procedure types, |
| enumerated types, subrange types and base types. You can also print the |
| contents of variables declared using these type. This section gives a |
| number of simple source code examples together with sample GDB sessions. |
| |
| The first example contains the following section of code: |
| |
| VAR |
| s: SET OF CHAR ; |
| r: [20..40] ; |
| |
| and you can request GDB to interrogate the type and value of 'r' and |
| 's'. |
| |
| (gdb) print s |
| {'A'..'C', 'Z'} |
| (gdb) ptype s |
| SET OF CHAR |
| (gdb) print r |
| 21 |
| (gdb) ptype r |
| [20..40] |
| |
| Likewise if your source code declares 's' as: |
| |
| VAR |
| s: SET ['A'..'Z'] ; |
| |
| then you may query the type of 's' by: |
| |
| (gdb) ptype s |
| type = SET ['A'..'Z'] |
| |
| Note that at present you cannot interactively manipulate set expressions |
| using the debugger. |
| |
| The following example shows how you might declare an array in |
| Modula-2 and how you can interact with GDB to print its type and |
| contents: |
| |
| VAR |
| s: ARRAY [-10..10] OF CHAR ; |
| |
| (gdb) ptype s |
| ARRAY [-10..10] OF CHAR |
| |
| Note that the array handling is not yet complete and although the |
| type is printed correctly, expression handling still assumes that all |
| arrays have a lower bound of zero and not '-10' as in the example above. |
| |
| Here are some more type related Modula-2 examples: |
| |
| TYPE |
| colour = (blue, red, yellow, green) ; |
| t = [blue..yellow] ; |
| VAR |
| s: t ; |
| BEGIN |
| s := blue ; |
| |
| The GDB interaction shows how you can query the data type and value of a |
| variable. |
| |
| (gdb) print s |
| $1 = blue |
| (gdb) ptype t |
| type = [blue..yellow] |
| |
| In this example a Modula-2 array is declared and its contents displayed. |
| Observe that the contents are written in the same way as their 'C' |
| counterparts. |
| |
| VAR |
| s: ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| s[1] := 1 ; |
| |
| (gdb) print s |
| $1 = {1, 0, 0, 0, 0} |
| (gdb) ptype s |
| type = ARRAY [1..5] OF CARDINAL |
| |
| The Modula-2 language interface to GDB also understands pointer types |
| as shown in this example: |
| |
| VAR |
| s: POINTER TO ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| NEW(s) ; |
| s^[1] := 1 ; |
| |
| and you can request that GDB describes the type of 's'. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [1..5] OF CARDINAL |
| |
| GDB handles compound types as we can see in this example. Here we |
| combine array types, record types, pointer types and subrange types: |
| |
| TYPE |
| foo = RECORD |
| f1: CARDINAL ; |
| f2: CHAR ; |
| f3: myarray ; |
| END ; |
| |
| myarray = ARRAY myrange OF CARDINAL ; |
| myrange = [-2..2] ; |
| VAR |
| s: POINTER TO ARRAY myrange OF foo ; |
| |
| and you can ask GDB to describe the type of 's' as shown below. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [-2..2] OF foo = RECORD |
| f1 : CARDINAL; |
| f2 : CHAR; |
| f3 : ARRAY [-2..2] OF CARDINAL; |
| END |
| |
| |
| File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 |
| |
| 15.4.9.5 Modula-2 Defaults |
| .......................... |
| |
| If type and range checking are set automatically by GDB, they both |
| default to 'on' whenever the working language changes to Modula-2. This |
| happens regardless of whether you or GDB selected the working language. |
| |
| If you allow GDB to set the language automatically, then entering |
| code compiled from a file whose name ends with '.mod' sets the working |
| language to Modula-2. *Note Having GDB Infer the Source Language: |
| Automatically, for further details. |
| |
| |
| File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 |
| |
| 15.4.9.6 Deviations from Standard Modula-2 |
| .......................................... |
| |
| A few changes have been made to make Modula-2 programs easier to debug. |
| This is done primarily via loosening its type strictness: |
| |
| * Unlike in standard Modula-2, pointer constants can be formed by |
| integers. This allows you to modify pointer variables during |
| debugging. (In standard Modula-2, the actual address contained in |
| a pointer variable is hidden from you; it can only be modified |
| through direct assignment to another pointer variable or expression |
| that returned a pointer.) |
| |
| * C escape sequences can be used in strings and characters to |
| represent non-printable characters. GDB prints out strings with |
| these escape sequences embedded. Single non-printable characters |
| are printed using the 'CHR(NNN)' format. |
| |
| * The assignment operator (':=') returns the value of its right-hand |
| argument. |
| |
| * All built-in procedures both modify _and_ return their argument. |
| |
| |
| File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 |
| |
| 15.4.9.7 Modula-2 Type and Range Checks |
| ....................................... |
| |
| _Warning:_ in this release, GDB does not yet perform type or range |
| checking. |
| |
| GDB considers two Modula-2 variables type equivalent if: |
| |
| * They are of types that have been declared equivalent via a 'TYPE T1 |
| = T2' statement |
| |
| * They have been declared on the same line. (Note: This is true of |
| the GNU Modula-2 compiler, but it may not be true of other |
| compilers.) |
| |
| As long as type checking is enabled, any attempt to combine variables |
| whose types are not equivalent is an error. |
| |
| Range checking is done on all mathematical operations, assignment, |
| array index bounds, and all built-in functions and procedures. |
| |
| |
| File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 |
| |
| 15.4.9.8 The Scope Operators '::' and '.' |
| ......................................... |
| |
| There are a few subtle differences between the Modula-2 scope operator |
| ('.') and the GDB scope operator ('::'). The two have similar syntax: |
| |
| |
| MODULE . ID |
| SCOPE :: ID |
| |
| where SCOPE is the name of a module or a procedure, MODULE the name of a |
| module, and ID is any declared identifier within your program, except |
| another module. |
| |
| Using the '::' operator makes GDB search the scope specified by SCOPE |
| for the identifier ID. If it is not found in the specified scope, then |
| GDB searches all scopes enclosing the one specified by SCOPE. |
| |
| Using the '.' operator makes GDB search the current scope for the |
| identifier specified by ID that was imported from the definition module |
| specified by MODULE. With this operator, it is an error if the |
| identifier ID was not imported from definition module MODULE, or if ID |
| is not an identifier in MODULE. |
| |
| |
| File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 |
| |
| 15.4.9.9 GDB and Modula-2 |
| ......................... |
| |
| Some GDB commands have little use when debugging Modula-2 programs. |
| Five subcommands of 'set print' and 'show print' apply specifically to C |
| and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The |
| first four apply to C++, and the last to the C 'union' type, which has |
| no direct analogue in Modula-2. |
| |
| The '@' operator (*note Expressions: Expressions.), while available |
| with any language, is not useful with Modula-2. Its intent is to aid |
| the debugging of "dynamic arrays", which cannot be created in Modula-2 |
| as they can in C or C++. However, because an address can be specified |
| by an integral constant, the construct '{TYPE}ADREXP' is still useful. |
| |
| In GDB scripts, the Modula-2 inequality operator '#' is interpreted |
| as the beginning of a comment. Use '<>' instead. |
| |
| |
| File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages |
| |
| 15.4.10 Ada |
| ----------- |
| |
| The extensions made to GDB for Ada only support output from the GNU Ada |
| (GNAT) compiler. Other Ada compilers are not currently supported, and |
| attempting to debug executables produced by them is most likely to be |
| difficult. |
| |
| * Menu: |
| |
| * Ada Mode Intro:: General remarks on the Ada syntax |
| and semantics supported by Ada mode |
| in GDB. |
| * Omissions from Ada:: Restrictions on the Ada expression syntax. |
| * Additions to Ada:: Extensions of the Ada expression syntax. |
| * Overloading support for Ada:: Support for expressions involving overloaded |
| subprograms. |
| * Stopping Before Main Program:: Debugging the program during elaboration. |
| * Ada Exceptions:: Ada Exceptions |
| * Ada Tasks:: Listing and setting breakpoints in tasks. |
| * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files |
| * Ravenscar Profile:: Tasking Support when using the Ravenscar |
| Profile |
| * Ada Settings:: New settable GDB parameters for Ada. |
| * Ada Glitches:: Known peculiarities of Ada mode. |
| |
| |
| File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada |
| |
| 15.4.10.1 Introduction |
| ...................... |
| |
| The Ada mode of GDB supports a fairly large subset of Ada expression |
| syntax, with some extensions. The philosophy behind the design of this |
| subset is |
| |
| * That GDB should provide basic literals and access to operations for |
| arithmetic, dereferencing, field selection, indexing, and |
| subprogram calls, leaving more sophisticated computations to |
| subprograms written into the program (which therefore may be called |
| from GDB). |
| |
| * That type safety and strict adherence to Ada language restrictions |
| are not particularly important to the GDB user. |
| |
| * That brevity is important to the GDB user. |
| |
| Thus, for brevity, the debugger acts as if all names declared in |
| user-written packages are directly visible, even if they are not visible |
| according to Ada rules, thus making it unnecessary to fully qualify most |
| names with their packages, regardless of context. Where this causes |
| ambiguity, GDB asks the user's intent. |
| |
| The debugger will start in Ada mode if it detects an Ada main |
| program. As for other languages, it will enter Ada mode when stopped in |
| a program that was translated from an Ada source file. |
| |
| While in Ada mode, you may use '--' for comments. This is useful |
| mostly for documenting command files. The standard GDB comment ('#') |
| still works at the beginning of a line in Ada mode, but not in the |
| middle (to allow based literals). |
| |
| |
| File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada |
| |
| 15.4.10.2 Omissions from Ada |
| ............................ |
| |
| Here are the notable omissions from the subset: |
| |
| * Only a subset of the attributes are supported: |
| |
| - 'First, 'Last, and 'Length on array objects (not on types and |
| subtypes). |
| |
| - 'Min and 'Max. |
| |
| - 'Pos and 'Val. |
| |
| - 'Tag. |
| |
| - 'Range on array objects (not subtypes), but only as the right |
| operand of the membership ('in') operator. |
| |
| - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT |
| extension). |
| |
| - 'Address. |
| |
| * The names in 'Characters.Latin_1' are not available and |
| concatenation is not implemented. Thus, escape characters in |
| strings are not currently available. |
| |
| * Equality tests ('=' and '/=') on arrays test for bitwise equality |
| of representations. They will generally work correctly for strings |
| and arrays whose elements have integer or enumeration types. They |
| may not work correctly for arrays whose element types have |
| user-defined equality, for arrays of real values (in particular, |
| IEEE-conformant floating point, because of negative zeroes and |
| NaNs), and for arrays whose elements contain unused bits with |
| indeterminate values. |
| |
| * The other component-by-component array operations ('and', 'or', |
| 'xor', 'not', and relational tests other than equality) are not |
| implemented. |
| |
| * There is limited support for array and record aggregates. They are |
| permitted only on the right sides of assignments, as in these |
| examples: |
| |
| (gdb) set An_Array := (1, 2, 3, 4, 5, 6) |
| (gdb) set An_Array := (1, others => 0) |
| (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) |
| (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) |
| (gdb) set A_Record := (1, "Peter", True); |
| (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) |
| |
| Changing a discriminant's value by assigning an aggregate has an |
| undefined effect if that discriminant is used within the record. |
| However, you can first modify discriminants by directly assigning |
| to them (which normally would not be allowed in Ada), and then |
| performing an aggregate assignment. For example, given a variable |
| 'A_Rec' declared to have a type such as: |
| |
| type Rec (Len : Small_Integer := 0) is record |
| Id : Integer; |
| Vals : IntArray (1 .. Len); |
| end record; |
| |
| you can assign a value with a different size of 'Vals' with two |
| assignments: |
| |
| (gdb) set A_Rec.Len := 4 |
| (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) |
| |
| As this example also illustrates, GDB is very loose about the usual |
| rules concerning aggregates. You may leave out some of the |
| components of an array or record aggregate (such as the 'Len' |
| component in the assignment to 'A_Rec' above); they will retain |
| their original values upon assignment. You may freely use dynamic |
| values as indices in component associations. You may even use |
| overlapping or redundant component associations, although which |
| component values are assigned in such cases is not defined. |
| |
| * Calls to dispatching subprograms are not implemented. |
| |
| * The overloading algorithm is much more limited (i.e., less |
| selective) than that of real Ada. It makes only limited use of the |
| context in which a subexpression appears to resolve its meaning, |
| and it is much looser in its rules for allowing type matches. As a |
| result, some function calls will be ambiguous, and the user will be |
| asked to choose the proper resolution. |
| |
| * The 'new' operator is not implemented. |
| |
| * Entry calls are not implemented. |
| |
| * Aside from printing, arithmetic operations on the native VAX |
| floating-point formats are not supported. |
| |
| * It is not possible to slice a packed array. |
| |
| * The names 'True' and 'False', when not part of a qualified name, |
| are interpreted as if implicitly prefixed by 'Standard', regardless |
| of context. Should your program redefine these names in a package |
| or procedure (at best a dubious practice), you will have to use |
| fully qualified names to access their new definitions. |
| |
| |
| File: gdb.info, Node: Additions to Ada, Next: Overloading support for Ada, Prev: Omissions from Ada, Up: Ada |
| |
| 15.4.10.3 Additions to Ada |
| .......................... |
| |
| As it does for other languages, GDB makes certain generic extensions to |
| Ada (*note Expressions::): |
| |
| * If the expression E is a variable residing in memory (typically a |
| local variable or array element) and N is a positive integer, then |
| 'E@N' displays the values of E and the N-1 adjacent variables |
| following it in memory as an array. In Ada, this operator is |
| generally not necessary, since its prime use is in displaying parts |
| of an array, and slicing will usually do this in Ada. However, |
| there are occasional uses when debugging programs in which certain |
| debugging information has been optimized away. |
| |
| * 'B::VAR' means "the variable named VAR that appears in function or |
| file B." When B is a file name, you must typically surround it in |
| single quotes. |
| |
| * The expression '{TYPE} ADDR' means "the variable of type TYPE that |
| appears at address ADDR." |
| |
| * A name starting with '$' is a convenience variable (*note |
| Convenience Vars::) or a machine register (*note Registers::). |
| |
| In addition, GDB provides a few other shortcuts and outright |
| additions specific to Ada: |
| |
| * The assignment statement is allowed as an expression, returning its |
| right-hand operand as its value. Thus, you may enter |
| |
| (gdb) set x := y + 3 |
| (gdb) print A(tmp := y + 1) |
| |
| * The semicolon is allowed as an "operator," returning as its value |
| the value of its right-hand operand. This allows, for example, |
| complex conditional breaks: |
| |
| (gdb) break f |
| (gdb) condition 1 (report(i); k += 1; A(k) > 100) |
| |
| * Rather than use catenation and symbolic character names to |
| introduce special characters into strings, one may instead use a |
| special bracket notation, which is also used to print strings. A |
| sequence of characters of the form '["XX"]' within a string or |
| character literal denotes the (single) character whose numeric |
| encoding is XX in hexadecimal. The sequence of characters '["""]' |
| also denotes a single quotation mark in strings. For example, |
| "One line.["0a"]Next line.["0a"]" |
| contains an ASCII newline character ('Ada.Characters.Latin_1.LF') |
| after each period. |
| |
| * The subtype used as a prefix for the attributes 'Pos, 'Min, and |
| 'Max is optional (and is ignored in any case). For example, it is |
| valid to write |
| |
| (gdb) print 'max(x, y) |
| |
| * When printing arrays, GDB uses positional notation when the array |
| has a lower bound of 1, and uses a modified named notation |
| otherwise. For example, a one-dimensional array of three integers |
| with a lower bound of 3 might print as |
| |
| (3 => 10, 17, 1) |
| |
| That is, in contrast to valid Ada, only the first component has a |
| '=>' clause. |
| |
| * You may abbreviate attributes in expressions with any unique, |
| multi-character subsequence of their names (an exact match gets |
| preference). For example, you may use a'len, a'gth, or a'lh in |
| place of a'length. |
| |
| * Since Ada is case-insensitive, the debugger normally maps |
| identifiers you type to lower case. The GNAT compiler uses |
| upper-case characters for some of its internal identifiers, which |
| are normally of no interest to users. For the rare occasions when |
| you actually have to look at them, enclose them in angle brackets |
| to avoid the lower-case mapping. For example, |
| (gdb) print <JMPBUF_SAVE>[0] |
| |
| * Printing an object of class-wide type or dereferencing an |
| access-to-class-wide value will display all the components of the |
| object's specific type (as indicated by its run-time tag). |
| Likewise, component selection on such a value will operate on the |
| specific type of the object. |
| |
| |
| File: gdb.info, Node: Overloading support for Ada, Next: Stopping Before Main Program, Prev: Additions to Ada, Up: Ada |
| |
| 15.4.10.4 Overloading support for Ada |
| ..................................... |
| |
| The debugger supports limited overloading. Given a subprogram call in |
| which the function symbol has multiple definitions, it will use the |
| number of actual parameters and some information about their types to |
| attempt to narrow the set of definitions. It also makes very limited |
| use of context, preferring procedures to functions in the context of the |
| 'call' command, and functions to procedures elsewhere. |
| |
| If, after narrowing, the set of matching definitions still contains |
| more than one definition, GDB will display a menu to query which one it |
| should use, for instance: |
| |
| (gdb) print f(1) |
| Multiple matches for f |
| [0] cancel |
| [1] foo.f (integer) return boolean at foo.adb:23 |
| [2] foo.f (foo.new_integer) return boolean at foo.adb:28 |
| > |
| |
| In this case, just select one menu entry either to cancel expression |
| evaluation (type '0' and press <RET>) or to continue evaluation with a |
| specific instance (type the corresponding number and press <RET>). |
| |
| Here are a couple of commands to customize GDB's behavior in this |
| case: |
| |
| 'set ada print-signatures' |
| Control whether parameter types and return types are displayed in |
| overloads selection menus. It is 'on' by default. *Note |
| Overloading support for Ada::. |
| |
| 'show ada print-signatures' |
| Show the current setting for displaying parameter types and return |
| types in overloads selection menu. *Note Overloading support for |
| Ada::. |
| |
| |
| File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Overloading support for Ada, Up: Ada |
| |
| 15.4.10.5 Stopping at the Very Beginning |
| ........................................ |
| |
| It is sometimes necessary to debug the program during elaboration, and |
| before reaching the main procedure. As defined in the Ada Reference |
| Manual, the elaboration code is invoked from a procedure called |
| 'adainit'. To run your program up to the beginning of elaboration, |
| simply use the following two commands: 'tbreak adainit' and 'run'. |
| |
| |
| File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada |
| |
| 15.4.10.6 Ada Exceptions |
| ........................ |
| |
| A command is provided to list all Ada exceptions: |
| |
| 'info exceptions' |
| 'info exceptions REGEXP' |
| The 'info exceptions' command allows you to list all Ada exceptions |
| defined within the program being debugged, as well as their |
| addresses. With a regular expression, REGEXP, as argument, only |
| those exceptions whose names match REGEXP are listed. |
| |
| Below is a small example, showing how the command can be used, first |
| without argument, and next with a regular expression passed as an |
| argument. |
| |
| (gdb) info exceptions |
| All defined Ada exceptions: |
| constraint_error: 0x613da0 |
| program_error: 0x613d20 |
| storage_error: 0x613ce0 |
| tasking_error: 0x613ca0 |
| const.aint_global_e: 0x613b00 |
| (gdb) info exceptions const.aint |
| All Ada exceptions matching regular expression "const.aint": |
| constraint_error: 0x613da0 |
| const.aint_global_e: 0x613b00 |
| |
| It is also possible to ask GDB to stop your program's execution when |
| an exception is raised. For more details, see *note Set Catchpoints::. |
| |
| |
| File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada |
| |
| 15.4.10.7 Extensions for Ada Tasks |
| .................................. |
| |
| Support for Ada tasks is analogous to that for threads (*note |
| Threads::). GDB provides the following task-related commands: |
| |
| 'info tasks' |
| This command shows a list of current Ada tasks, as in the following |
| example: |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8088000 0 15 Child Activation Wait main_task |
| 2 80a4000 1 15 Accept Statement b |
| 3 809a800 1 15 Child Activation Wait a |
| * 4 80ae800 3 15 Runnable c |
| |
| |
| In this listing, the asterisk before the last task indicates it to |
| be the task currently being inspected. |
| |
| ID |
| Represents GDB's internal task number. |
| |
| TID |
| The Ada task ID. |
| |
| P-ID |
| The parent's task ID (GDB's internal task number). |
| |
| Pri |
| The base priority of the task. |
| |
| State |
| Current state of the task. |
| |
| 'Unactivated' |
| The task has been created but has not been activated. It |
| cannot be executing. |
| |
| 'Runnable' |
| The task is not blocked for any reason known to Ada. (It |
| may be waiting for a mutex, though.) It is conceptually |
| "executing" in normal mode. |
| |
| 'Terminated' |
| The task is terminated, in the sense of ARM 9.3 (5). Any |
| dependents that were waiting on terminate alternatives |
| have been awakened and have terminated themselves. |
| |
| 'Child Activation Wait' |
| The task is waiting for created tasks to complete |
| activation. |
| |
| 'Accept Statement' |
| The task is waiting on an accept or selective wait |
| statement. |
| |
| 'Waiting on entry call' |
| The task is waiting on an entry call. |
| |
| 'Async Select Wait' |
| The task is waiting to start the abortable part of an |
| asynchronous select statement. |
| |
| 'Delay Sleep' |
| The task is waiting on a select statement with only a |
| delay alternative open. |
| |
| 'Child Termination Wait' |
| The task is sleeping having completed a master within |
| itself, and is waiting for the tasks dependent on that |
| master to become terminated or waiting on a terminate |
| Phase. |
| |
| 'Wait Child in Term Alt' |
| The task is sleeping waiting for tasks on terminate |
| alternatives to finish terminating. |
| |
| 'Accepting RV with TASKNO' |
| The task is accepting a rendez-vous with the task TASKNO. |
| |
| Name |
| Name of the task in the program. |
| |
| 'info task TASKNO' |
| This command shows detailed informations on the specified task, as |
| in the following example: |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077880 0 15 Child Activation Wait main_task |
| * 2 807c468 1 15 Runnable task_1 |
| (gdb) info task 2 |
| Ada Task: 0x807c468 |
| Name: "task_1" |
| Thread: 0 |
| LWP: 0x1fac |
| Parent: 1 ("main_task") |
| Base Priority: 15 |
| State: Runnable |
| |
| 'task' |
| This command prints the ID and name of the current task. |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077870 0 15 Child Activation Wait main_task |
| * 2 807c458 1 15 Runnable some_task |
| (gdb) task |
| [Current task is 2 "some_task"] |
| |
| 'task TASKNO' |
| This command is like the 'thread THREAD-ID' command (*note |
| Threads::). It switches the context of debugging from the current |
| task to the given task. |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077870 0 15 Child Activation Wait main_task |
| * 2 807c458 1 15 Runnable some_task |
| (gdb) task 1 |
| [Switching to task 1 "main_task"] |
| #0 0x8067726 in pthread_cond_wait () |
| (gdb) bt |
| #0 0x8067726 in pthread_cond_wait () |
| #1 0x8056714 in system.os_interface.pthread_cond_wait () |
| #2 0x805cb63 in system.task_primitives.operations.sleep () |
| #3 0x806153e in system.tasking.stages.activate_tasks () |
| #4 0x804aacc in un () at un.adb:5 |
| |
| 'break LOCATION task TASKNO' |
| 'break LOCATION task TASKNO if ...' |
| These commands are like the 'break ... thread ...' command (*note |
| Thread Stops::). The LOCATION argument specifies source lines, as |
| described in *note Specify Location::. |
| |
| Use the qualifier 'task TASKNO' with a breakpoint command to |
| specify that you only want GDB to stop the program when a |
| particular Ada task reaches this breakpoint. The TASKNO is one of |
| the numeric task identifiers assigned by GDB, shown in the first |
| column of the 'info tasks' display. |
| |
| If you do not specify 'task TASKNO' when you set a breakpoint, the |
| breakpoint applies to _all_ tasks of your program. |
| |
| You can use the 'task' qualifier on conditional breakpoints as |
| well; in this case, place 'task TASKNO' before the breakpoint |
| condition (before the 'if'). |
| |
| For example, |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 140022020 0 15 Child Activation Wait main_task |
| 2 140045060 1 15 Accept/Select Wait t2 |
| 3 140044840 1 15 Runnable t1 |
| * 4 140056040 1 15 Runnable t3 |
| (gdb) b 15 task 2 |
| Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. |
| (gdb) cont |
| Continuing. |
| task # 1 running |
| task # 2 running |
| |
| Breakpoint 5, test_task_debug () at test_task_debug.adb:15 |
| 15 flush; |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 140022020 0 15 Child Activation Wait main_task |
| * 2 140045060 1 15 Runnable t2 |
| 3 140044840 1 15 Runnable t1 |
| 4 140056040 1 15 Delay Sleep t3 |
| |
| |
| File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada |
| |
| 15.4.10.8 Tasking Support when Debugging Core Files |
| ................................................... |
| |
| When inspecting a core file, as opposed to debugging a live program, |
| tasking support may be limited or even unavailable, depending on the |
| platform being used. For instance, on x86-linux, the list of tasks is |
| available, but task switching is not supported. |
| |
| On certain platforms, the debugger needs to perform some memory |
| writes in order to provide Ada tasking support. When inspecting a core |
| file, this means that the core file must be opened with read-write |
| privileges, using the command '"set write on"' (*note Patching::). |
| Under these circumstances, you should make a backup copy of the core |
| file before inspecting it with GDB. |
| |
| |
| File: gdb.info, Node: Ravenscar Profile, Next: Ada Settings, Prev: Ada Tasks and Core Files, Up: Ada |
| |
| 15.4.10.9 Tasking Support when using the Ravenscar Profile |
| .......................................................... |
| |
| The "Ravenscar Profile" is a subset of the Ada tasking features, |
| specifically designed for systems with safety-critical real-time |
| requirements. |
| |
| 'set ravenscar task-switching on' |
| Allows task switching when debugging a program that uses the |
| Ravenscar Profile. This is the default. |
| |
| 'set ravenscar task-switching off' |
| Turn off task switching when debugging a program that uses the |
| Ravenscar Profile. This is mostly intended to disable the code |
| that adds support for the Ravenscar Profile, in case a bug in |
| either GDB or in the Ravenscar runtime is preventing GDB from |
| working properly. To be effective, this command should be run |
| before the program is started. |
| |
| 'show ravenscar task-switching' |
| Show whether it is possible to switch from task to task in a |
| program using the Ravenscar Profile. |
| |
| |
| File: gdb.info, Node: Ada Settings, Next: Ada Glitches, Prev: Ravenscar Profile, Up: Ada |
| |
| 15.4.10.10 Ada Settings |
| ....................... |
| |
| 'set varsize-limit SIZE' |
| Prevent GDB from attempting to evaluate objects whose size is above |
| the given limit (SIZE) when those sizes are computed from run-time |
| quantities. This is typically the case when the object has a |
| variable size, such as an array whose bounds are not known at |
| compile time for example. Setting SIZE to 'unlimited' removes the |
| size limitation. By default, the limit is about 65KB. |
| |
| The purpose of having such a limit is to prevent GDB from trying to |
| grab enormous chunks of virtual memory when asked to evaluate a |
| quantity whose bounds have been corrupted or have not yet been |
| fully initialized. The limit applies to the results of some |
| subexpressions as well as to complete expressions. For example, an |
| expression denoting a simple integer component, such as 'x.y.z', |
| may fail if the size of 'x.y' is variable and exceeds 'size'. On |
| the other hand, GDB is sometimes clever; the expression 'A(i)', |
| where 'A' is an array variable with non-constant size, will |
| generally succeed regardless of the bounds on 'A', as long as the |
| component size is less than SIZE. |
| |
| 'show varsize-limit' |
| Show the limit on types whose size is determined by run-time |
| quantities. |
| |
| |
| File: gdb.info, Node: Ada Glitches, Prev: Ada Settings, Up: Ada |
| |
| 15.4.10.11 Known Peculiarities of Ada Mode |
| .......................................... |
| |
| Besides the omissions listed previously (*note Omissions from Ada::), we |
| know of several problems with and limitations of Ada mode in GDB, some |
| of which will be fixed with planned future releases of the debugger and |
| the GNU Ada compiler. |
| |
| * Static constants that the compiler chooses not to materialize as |
| objects in storage are invisible to the debugger. |
| |
| * Named parameter associations in function argument lists are ignored |
| (the argument lists are treated as positional). |
| |
| * Many useful library packages are currently invisible to the |
| debugger. |
| |
| * Fixed-point arithmetic, conversions, input, and output is carried |
| out using floating-point arithmetic, and may give results that only |
| approximate those on the host machine. |
| |
| * The GNAT compiler never generates the prefix 'Standard' for any of |
| the standard symbols defined by the Ada language. GDB knows about |
| this: it will strip the prefix from names when you use it, and will |
| never look for a name you have so qualified among local symbols, |
| nor match against symbols in other packages or subprograms. If you |
| have defined entities anywhere in your program other than |
| parameters and local variables whose simple names match names in |
| 'Standard', GNAT's lack of qualification here can cause confusion. |
| When this happens, you can usually resolve the confusion by |
| qualifying the problematic names with package 'Standard' |
| explicitly. |
| |
| Older versions of the compiler sometimes generate erroneous debugging |
| information, resulting in the debugger incorrectly printing the value of |
| affected entities. In some cases, the debugger is able to work around |
| an issue automatically. In other cases, the debugger is able to work |
| around the issue, but the work-around has to be specifically enabled. |
| |
| 'set ada trust-PAD-over-XVS on' |
| Configure GDB to strictly follow the GNAT encoding when computing |
| the value of Ada entities, particularly when 'PAD' and 'PAD___XVS' |
| types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a |
| complete description of the encoding used by the GNAT compiler). |
| This is the default. |
| |
| 'set ada trust-PAD-over-XVS off' |
| This is related to the encoding using by the GNAT compiler. If GDB |
| sometimes prints the wrong value for certain entities, changing |
| 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may |
| fix the issue. It is always safe to set 'ada trust-PAD-over-XVS' |
| to 'off', but this incurs a slight performance penalty, so it is |
| recommended to leave this setting to 'on' unless necessary. |
| |
| Internally, the debugger also relies on the compiler following a |
| number of conventions known as the 'GNAT Encoding', all documented in |
| 'gcc/ada/exp_dbug.ads' in the GCC sources. This encoding describes how |
| the debugging information should be generated for certain types. In |
| particular, this convention makes use of "descriptive types", which are |
| artificial types generated purely to help the debugger. |
| |
| These encodings were defined at a time when the debugging information |
| format used was not powerful enough to describe some of the more complex |
| types available in Ada. Since DWARF allows us to express nearly all Ada |
| features, the long-term goal is to slowly replace these descriptive |
| types by their pure DWARF equivalent. To facilitate that transition, a |
| new maintenance option is available to force the debugger to ignore |
| those descriptive types. It allows the user to quickly evaluate how |
| well GDB works without them. |
| |
| 'maintenance ada set ignore-descriptive-types [on|off]' |
| Control whether the debugger should ignore descriptive types. The |
| default is not to ignore descriptives types ('off'). |
| |
| 'maintenance ada show ignore-descriptive-types' |
| Show if descriptive types are ignored by GDB. |
| |
| |
| File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages |
| |
| 15.5 Unsupported Languages |
| ========================== |
| |
| In addition to the other fully-supported programming languages, GDB also |
| provides a pseudo-language, called 'minimal'. It does not represent a |
| real programming language, but provides a set of capabilities close to |
| what the C or assembly languages provide. This should allow most simple |
| operations to be performed while debugging an application that uses a |
| language currently not supported by GDB. |
| |
| If the language is set to 'auto', GDB will automatically select this |
| language if the current frame corresponds to an unsupported language. |
| |
| |
| File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top |
| |
| 16 Examining the Symbol Table |
| ***************************** |
| |
| The commands described in this chapter allow you to inquire about the |
| symbols (names of variables, functions and types) defined in your |
| program. This information is inherent in the text of your program and |
| does not change as your program executes. GDB finds it in your |
| program's symbol table, in the file indicated when you started GDB |
| (*note Choosing Files: File Options.), or by one of the file-management |
| commands (*note Commands to Specify Files: Files.). |
| |
| Occasionally, you may need to refer to symbols that contain unusual |
| characters, which GDB ordinarily treats as word delimiters. The most |
| frequent case is in referring to static variables in other source files |
| (*note Program Variables: Variables.). File names are recorded in |
| object files as debugging symbols, but GDB would ordinarily parse a |
| typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To |
| allow GDB to recognize 'foo.c' as a single symbol, enclose it in single |
| quotes; for example, |
| |
| p 'foo.c'::x |
| |
| looks up the value of 'x' in the scope of the file 'foo.c'. |
| |
| 'set case-sensitive on' |
| 'set case-sensitive off' |
| 'set case-sensitive auto' |
| Normally, when GDB looks up symbols, it matches their names with |
| case sensitivity determined by the current source language. |
| Occasionally, you may wish to control that. The command 'set |
| case-sensitive' lets you do that by specifying 'on' for |
| case-sensitive matches or 'off' for case-insensitive ones. If you |
| specify 'auto', case sensitivity is reset to the default suitable |
| for the source language. The default is case-sensitive matches for |
| all languages except for Fortran, for which the default is |
| case-insensitive matches. |
| |
| 'show case-sensitive' |
| This command shows the current setting of case sensitivity for |
| symbols lookups. |
| |
| 'set print type methods' |
| 'set print type methods on' |
| 'set print type methods off' |
| Normally, when GDB prints a class, it displays any methods declared |
| in that class. You can control this behavior either by passing the |
| appropriate flag to 'ptype', or using 'set print type methods'. |
| Specifying 'on' will cause GDB to display the methods; this is the |
| default. Specifying 'off' will cause GDB to omit the methods. |
| |
| 'show print type methods' |
| This command shows the current setting of method display when |
| printing classes. |
| |
| 'set print type nested-type-limit LIMIT' |
| 'set print type nested-type-limit unlimited' |
| Set the limit of displayed nested types that the type printer will |
| show. A LIMIT of 'unlimited' or '-1' will show all nested |
| definitions. By default, the type printer will not show any nested |
| types defined in classes. |
| |
| 'show print type nested-type-limit' |
| This command shows the current display limit of nested types when |
| printing classes. |
| |
| 'set print type typedefs' |
| 'set print type typedefs on' |
| 'set print type typedefs off' |
| |
| Normally, when GDB prints a class, it displays any typedefs defined |
| in that class. You can control this behavior either by passing the |
| appropriate flag to 'ptype', or using 'set print type typedefs'. |
| Specifying 'on' will cause GDB to display the typedef definitions; |
| this is the default. Specifying 'off' will cause GDB to omit the |
| typedef definitions. Note that this controls whether the typedef |
| definition itself is printed, not whether typedef names are |
| substituted when printing other types. |
| |
| 'show print type typedefs' |
| This command shows the current setting of typedef display when |
| printing classes. |
| |
| 'info address SYMBOL' |
| Describe where the data for SYMBOL is stored. For a register |
| variable, this says which register it is kept in. For a |
| non-register local variable, this prints the stack-frame offset at |
| which the variable is always stored. |
| |
| Note the contrast with 'print &SYMBOL', which does not work at all |
| for a register variable, and for a stack local variable prints the |
| exact address of the current instantiation of the variable. |
| |
| 'info symbol ADDR' |
| Print the name of a symbol which is stored at the address ADDR. If |
| no symbol is stored exactly at ADDR, GDB prints the nearest symbol |
| and an offset from it: |
| |
| (gdb) info symbol 0x54320 |
| _initialize_vx + 396 in section .text |
| |
| This is the opposite of the 'info address' command. You can use it |
| to find out the name of a variable or a function given its address. |
| |
| For dynamically linked executables, the name of executable or |
| shared library containing the symbol is also printed: |
| |
| (gdb) info symbol 0x400225 |
| _start + 5 in section .text of /tmp/a.out |
| (gdb) info symbol 0x2aaaac2811cf |
| __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 |
| |
| 'demangle [-l LANGUAGE] [--] NAME' |
| Demangle NAME. If LANGUAGE is provided it is the name of the |
| language to demangle NAME in. Otherwise NAME is demangled in the |
| current language. |
| |
| The '--' option specifies the end of options, and is useful when |
| NAME begins with a dash. |
| |
| The parameter 'demangle-style' specifies how to interpret the kind |
| of mangling used. *Note Print Settings::. |
| |
| 'whatis[/FLAGS] [ARG]' |
| Print the data type of ARG, which can be either an expression or a |
| name of a data type. With no argument, print the data type of '$', |
| the last value in the value history. |
| |
| If ARG is an expression (*note Expressions: Expressions.), it is |
| not actually evaluated, and any side-effecting operations (such as |
| assignments or function calls) inside it do not take place. |
| |
| If ARG is a variable or an expression, 'whatis' prints its literal |
| type as it is used in the source code. If the type was defined |
| using a 'typedef', 'whatis' will _not_ print the data type |
| underlying the 'typedef'. If the type of the variable or the |
| expression is a compound data type, such as 'struct' or 'class', |
| 'whatis' never prints their fields or methods. It just prints the |
| 'struct'/'class' name (a.k.a. its "tag"). If you want to see the |
| members of such a compound data type, use 'ptype'. |
| |
| If ARG is a type name that was defined using 'typedef', 'whatis' |
| "unrolls" only one level of that 'typedef'. Unrolling means that |
| 'whatis' will show the underlying type used in the 'typedef' |
| declaration of ARG. However, if that underlying type is also a |
| 'typedef', 'whatis' will not unroll it. |
| |
| For C code, the type names may also have the form 'class |
| CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum |
| ENUM-TAG'. |
| |
| FLAGS can be used to modify how the type is displayed. Available |
| flags are: |
| |
| 'r' |
| Display in "raw" form. Normally, GDB substitutes template |
| parameters and typedefs defined in a class when printing the |
| class' members. The '/r' flag disables this. |
| |
| 'm' |
| Do not print methods defined in the class. |
| |
| 'M' |
| Print methods defined in the class. This is the default, but |
| the flag exists in case you change the default with 'set print |
| type methods'. |
| |
| 't' |
| Do not print typedefs defined in the class. Note that this |
| controls whether the typedef definition itself is printed, not |
| whether typedef names are substituted when printing other |
| types. |
| |
| 'T' |
| Print typedefs defined in the class. This is the default, but |
| the flag exists in case you change the default with 'set print |
| type typedefs'. |
| |
| 'o' |
| Print the offsets and sizes of fields in a struct, similar to |
| what the 'pahole' tool does. This option implies the '/tm' |
| flags. |
| |
| For example, given the following declarations: |
| |
| struct tuv |
| { |
| int a1; |
| char *a2; |
| int a3; |
| }; |
| |
| struct xyz |
| { |
| int f1; |
| char f2; |
| void *f3; |
| struct tuv f4; |
| }; |
| |
| union qwe |
| { |
| struct tuv fff1; |
| struct xyz fff2; |
| }; |
| |
| struct tyu |
| { |
| int a1 : 1; |
| int a2 : 3; |
| int a3 : 23; |
| char a4 : 2; |
| int64_t a5; |
| int a6 : 5; |
| int64_t a7 : 3; |
| }; |
| |
| Issuing a 'ptype /o struct tuv' command would print: |
| |
| (gdb) ptype /o struct tuv |
| /* offset | size */ type = struct tuv { |
| /* 0 | 4 */ int a1; |
| /* XXX 4-byte hole */ |
| /* 8 | 8 */ char *a2; |
| /* 16 | 4 */ int a3; |
| |
| /* total size (bytes): 24 */ |
| } |
| |
| Notice the format of the first column of comments. There, you |
| can find two parts separated by the '|' character: the |
| _offset_, which indicates where the field is located inside |
| the struct, in bytes, and the _size_ of the field. Another |
| interesting line is the marker of a _hole_ in the struct, |
| indicating that it may be possible to pack the struct and make |
| it use less space by reorganizing its fields. |
| |
| It is also possible to print offsets inside an union: |
| |
| (gdb) ptype /o union qwe |
| /* offset | size */ type = union qwe { |
| /* 24 */ struct tuv { |
| /* 0 | 4 */ int a1; |
| /* XXX 4-byte hole */ |
| /* 8 | 8 */ char *a2; |
| /* 16 | 4 */ int a3; |
| |
| /* total size (bytes): 24 */ |
| } fff1; |
| /* 40 */ struct xyz { |
| /* 0 | 4 */ int f1; |
| /* 4 | 1 */ char f2; |
| /* XXX 3-byte hole */ |
| /* 8 | 8 */ void *f3; |
| /* 16 | 24 */ struct tuv { |
| /* 16 | 4 */ int a1; |
| /* XXX 4-byte hole */ |
| /* 24 | 8 */ char *a2; |
| /* 32 | 4 */ int a3; |
| |
| /* total size (bytes): 24 */ |
| } f4; |
| |
| /* total size (bytes): 40 */ |
| } fff2; |
| |
| /* total size (bytes): 40 */ |
| } |
| |
| In this case, since 'struct tuv' and 'struct xyz' occupy the |
| same space (because we are dealing with an union), the offset |
| is not printed for them. However, you can still examine the |
| offset of each of these structures' fields. |
| |
| Another useful scenario is printing the offsets of a struct |
| containing bitfields: |
| |
| (gdb) ptype /o struct tyu |
| /* offset | size */ type = struct tyu { |
| /* 0:31 | 4 */ int a1 : 1; |
| /* 0:28 | 4 */ int a2 : 3; |
| /* 0: 5 | 4 */ int a3 : 23; |
| /* 3: 3 | 1 */ signed char a4 : 2; |
| /* XXX 3-bit hole */ |
| /* XXX 4-byte hole */ |
| /* 8 | 8 */ int64_t a5; |
| /* 16: 0 | 4 */ int a6 : 5; |
| /* 16: 5 | 8 */ int64_t a7 : 3; |
| "/* XXX 7-byte padding */ |
| |
| /* total size (bytes): 24 */ |
| } |
| |
| Note how the offset information is now extended to also |
| include the first bit of the bitfield. |
| |
| 'ptype[/FLAGS] [ARG]' |
| 'ptype' accepts the same arguments as 'whatis', but prints a |
| detailed description of the type, instead of just the name of the |
| type. *Note Expressions: Expressions. |
| |
| Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its |
| argument declaration, whether the argument is a variable, |
| expression, or a data type. This means that 'ptype' of a variable |
| or an expression will not print literally its type as present in |
| the source code--use 'whatis' for that. 'typedef's at the pointer |
| or reference targets are also unrolled. Only 'typedef's of fields, |
| methods and inner 'class typedef's of 'struct's, 'class'es and |
| 'union's are not unrolled even with 'ptype'. |
| |
| For example, for this variable declaration: |
| |
| typedef double real_t; |
| struct complex { real_t real; double imag; }; |
| typedef struct complex complex_t; |
| complex_t var; |
| real_t *real_pointer_var; |
| |
| the two commands give this output: |
| |
| (gdb) whatis var |
| type = complex_t |
| (gdb) ptype var |
| type = struct complex { |
| real_t real; |
| double imag; |
| } |
| (gdb) whatis complex_t |
| type = struct complex |
| (gdb) whatis struct complex |
| type = struct complex |
| (gdb) ptype struct complex |
| type = struct complex { |
| real_t real; |
| double imag; |
| } |
| (gdb) whatis real_pointer_var |
| type = real_t * |
| (gdb) ptype real_pointer_var |
| type = double * |
| |
| As with 'whatis', using 'ptype' without an argument refers to the |
| type of '$', the last value in the value history. |
| |
| Sometimes, programs use opaque data types or incomplete |
| specifications of complex data structure. If the debug information |
| included in the program does not allow GDB to display a full |
| declaration of the data type, it will say '<incomplete type>'. For |
| example, given these declarations: |
| |
| struct foo; |
| struct foo *fooptr; |
| |
| but no definition for 'struct foo' itself, GDB will say: |
| |
| (gdb) ptype foo |
| $1 = <incomplete type> |
| |
| "Incomplete type" is C terminology for data types that are not |
| completely specified. |
| |
| Othertimes, information about a variable's type is completely |
| absent from the debug information included in the program. This |
| most often happens when the program or library where the variable |
| is defined includes no debug information at all. GDB knows the |
| variable exists from inspecting the linker/loader symbol table |
| (e.g., the ELF dynamic symbol table), but such symbols do not |
| contain type information. Inspecting the type of a (global) |
| variable for which GDB has no type information shows: |
| |
| (gdb) ptype var |
| type = <data variable, no debug info> |
| |
| *Note no debug info variables: Variables, for how to print the |
| values of such variables. |
| |
| 'info types [-q] [REGEXP]' |
| Print a brief description of all types whose names match the |
| regular expression REGEXP (or all types in your program, if you |
| supply no argument). Each complete typename is matched as though |
| it were a complete line; thus, 'i type value' gives information on |
| all types in your program whose names include the string 'value', |
| but 'i type ^value$' gives information only on types whose complete |
| name is 'value'. |
| |
| In programs using different languages, GDB chooses the syntax to |
| print the type description according to the 'set language' value: |
| using 'set language auto' (see *note Set Language Automatically: |
| Automatically.) means to use the language of the type, other values |
| mean to use the manually specified language (see *note Set Language |
| Manually: Manually.). |
| |
| This command differs from 'ptype' in two ways: first, like |
| 'whatis', it does not print a detailed description; second, it |
| lists all source files and line numbers where a type is defined. |
| |
| The output from 'into types' is proceeded with a header line |
| describing what types are being listed. The optional flag '-q', |
| which stands for 'quiet', disables printing this header |
| information. |
| |
| 'info type-printers' |
| Versions of GDB that ship with Python scripting enabled may have |
| "type printers" available. When using 'ptype' or 'whatis', these |
| printers are consulted when the name of a type is needed. *Note |
| Type Printing API::, for more information on writing type printers. |
| |
| 'info type-printers' displays all the available type printers. |
| |
| 'enable type-printer NAME...' |
| 'disable type-printer NAME...' |
| These commands can be used to enable or disable type printers. |
| |
| 'info scope LOCATION' |
| List all the variables local to a particular scope. This command |
| accepts a LOCATION argument--a function name, a source line, or an |
| address preceded by a '*', and prints all the variables local to |
| the scope defined by that location. (*Note Specify Location::, for |
| details about supported forms of LOCATION.) For example: |
| |
| (gdb) info scope command_line_handler |
| Scope for command_line_handler: |
| Symbol rl is an argument at stack/frame offset 8, length 4. |
| Symbol linebuffer is in static storage at address 0x150a18, length 4. |
| Symbol linelength is in static storage at address 0x150a1c, length 4. |
| Symbol p is a local variable in register $esi, length 4. |
| Symbol p1 is a local variable in register $ebx, length 4. |
| Symbol nline is a local variable in register $edx, length 4. |
| Symbol repeat is a local variable at frame offset -8, length 4. |
| |
| This command is especially useful for determining what data to |
| collect during a "trace experiment", see *note collect: Tracepoint |
| Actions. |
| |
| 'info source' |
| Show information about the current source file--that is, the source |
| file for the function containing the current point of execution: |
| * the name of the source file, and the directory containing it, |
| * the directory it was compiled in, |
| * its length, in lines, |
| * which programming language it is written in, |
| * if the debug information provides it, the program that |
| compiled the file (which may include, e.g., the compiler |
| version and command line arguments), |
| * whether the executable includes debugging information for that |
| file, and if so, what format the information is in (e.g., |
| STABS, Dwarf 2, etc.), and |
| * whether the debugging information includes information about |
| preprocessor macros. |
| |
| 'info sources' |
| Print the names of all source files in your program for which there |
| is debugging information, organized into two lists: files whose |
| symbols have already been read, and files whose symbols will be |
| read when needed. |
| |
| 'info sources [-dirname | -basename] [--] [REGEXP]' |
| Like 'info sources', but only print the names of the files matching |
| the provided REGEXP. By default, the REGEXP is used to match |
| anywhere in the filename. If '-dirname', only files having a |
| dirname matching REGEXP are shown. If '-basename', only files |
| having a basename matching REGEXP are shown. The matching is |
| case-sensitive, except on operating systems that have |
| case-insensitive filesystem (e.g., MS-Windows). |
| |
| 'info functions [-q] [-n]' |
| Print the names and data types of all defined functions. Similarly |
| to 'info types', this command groups its output by source files and |
| annotates each function definition with its source line number. |
| |
| In programs using different languages, GDB chooses the syntax to |
| print the function name and type according to the 'set language' |
| value: using 'set language auto' (see *note Set Language |
| Automatically: Automatically.) means to use the language of the |
| function, other values mean to use the manually specified language |
| (see *note Set Language Manually: Manually.). |
| |
| The '-n' flag excludes "non-debugging symbols" from the results. A |
| non-debugging symbol is a symbol that comes from the executable's |
| symbol table, not from the debug information (for example, DWARF) |
| associated with the executable. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no functions have |
| been printed. |
| |
| 'info functions [-q] [-n] [-t TYPE_REGEXP] [REGEXP]' |
| Like 'info functions', but only print the names and data types of |
| the functions selected with the provided regexp(s). |
| |
| If REGEXP is provided, print only the functions whose names match |
| the regular expression REGEXP. Thus, 'info fun step' finds all |
| functions whose names include 'step'; 'info fun ^step' finds those |
| whose names start with 'step'. If a function name contains |
| characters that conflict with the regular expression language (e.g. |
| 'operator*()'), they may be quoted with a backslash. |
| |
| If TYPE_REGEXP is provided, print only the functions whose types, |
| as printed by the 'whatis' command, match the regular expression |
| TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be |
| enclosed in quote characters. If needed, use backslash to escape |
| the meaning of special characters or quotes. Thus, 'info fun -t |
| '^int ('' finds the functions that return an integer; 'info fun -t |
| '(.*int.*'' finds the functions that have an argument type |
| containing int; 'info fun -t '^int (' ^step' finds the functions |
| whose names start with 'step' and that return int. |
| |
| If both REGEXP and TYPE_REGEXP are provided, a function is printed |
| only if its name matches REGEXP and its type matches TYPE_REGEXP. |
| |
| 'info variables [-q] [-n]' |
| Print the names and data types of all variables that are defined |
| outside of functions (i.e. excluding local variables). The printed |
| variables are grouped by source files and annotated with their |
| respective source line numbers. |
| |
| In programs using different languages, GDB chooses the syntax to |
| print the variable name and type according to the 'set language' |
| value: using 'set language auto' (see *note Set Language |
| Automatically: Automatically.) means to use the language of the |
| variable, other values mean to use the manually specified language |
| (see *note Set Language Manually: Manually.). |
| |
| The '-n' flag excludes non-debugging symbols from the results. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no variables have |
| been printed. |
| |
| 'info variables [-q] [-n] [-t TYPE_REGEXP] [REGEXP]' |
| Like 'info variables', but only print the variables selected with |
| the provided regexp(s). |
| |
| If REGEXP is provided, print only the variables whose names match |
| the regular expression REGEXP. |
| |
| If TYPE_REGEXP is provided, print only the variables whose types, |
| as printed by the 'whatis' command, match the regular expression |
| TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be |
| enclosed in quote characters. If needed, use backslash to escape |
| the meaning of special characters or quotes. |
| |
| If both REGEXP and TYPE_REGEXP are provided, an argument is printed |
| only if its name matches REGEXP and its type matches TYPE_REGEXP. |
| |
| 'info modules [-q] [REGEXP]' |
| List all Fortran modules in the program, or all modules matching |
| the optional regular expression REGEXP. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no modules have been |
| printed. |
| |
| 'info module functions [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]' |
| 'info module variables [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]' |
| List all functions or variables within all Fortran modules. The |
| set of functions or variables listed can be limited by providing |
| some or all of the optional regular expressions. If MODULE-REGEXP |
| is provided, then only Fortran modules matching MODULE-REGEXP will |
| be searched. Only functions or variables whose type matches the |
| optional regular expression TYPE-REGEXP will be listed. And only |
| functions or variables whose name matches the optional regular |
| expression REGEXP will be listed. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no functions or |
| variables have been printed. |
| |
| 'info classes' |
| 'info classes REGEXP' |
| Display all Objective-C classes in your program, or (with the |
| REGEXP argument) all those matching a particular regular |
| expression. |
| |
| 'info selectors' |
| 'info selectors REGEXP' |
| Display all Objective-C selectors in your program, or (with the |
| REGEXP argument) all those matching a particular regular |
| expression. |
| |
| 'set opaque-type-resolution on' |
| Tell GDB to resolve opaque types. An opaque type is a type |
| declared as a pointer to a 'struct', 'class', or 'union'--for |
| example, 'struct MyType *'--that is used in one source file |
| although the full declaration of 'struct MyType' is in another |
| source file. The default is on. |
| |
| A change in the setting of this subcommand will not take effect |
| until the next time symbols for a file are loaded. |
| |
| 'set opaque-type-resolution off' |
| Tell GDB not to resolve opaque types. In this case, the type is |
| printed as follows: |
| {<no data fields>} |
| |
| 'show opaque-type-resolution' |
| Show whether opaque types are resolved or not. |
| |
| 'set print symbol-loading' |
| 'set print symbol-loading full' |
| 'set print symbol-loading brief' |
| 'set print symbol-loading off' |
| The 'set print symbol-loading' command allows you to control the |
| printing of messages when GDB loads symbol information. By default |
| a message is printed for the executable and one for each shared |
| library, and normally this is what you want. However, when |
| debugging apps with large numbers of shared libraries these |
| messages can be annoying. When set to 'brief' a message is printed |
| for each executable, and when GDB loads a collection of shared |
| libraries at once it will only print one message regardless of the |
| number of shared libraries. When set to 'off' no messages are |
| printed. |
| |
| 'show print symbol-loading' |
| Show whether messages will be printed when a GDB command entered |
| from the keyboard causes symbol information to be loaded. |
| |
| 'maint print symbols [-pc ADDRESS] [FILENAME]' |
| 'maint print symbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]' |
| 'maint print psymbols [-objfile OBJFILE] [-pc ADDRESS] [--] [FILENAME]' |
| 'maint print psymbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]' |
| 'maint print msymbols [-objfile OBJFILE] [--] [FILENAME]' |
| Write a dump of debugging symbol data into the file FILENAME or the |
| terminal if FILENAME is unspecified. If '-objfile OBJFILE' is |
| specified, only dump symbols for that objfile. If '-pc ADDRESS' is |
| specified, only dump symbols for the file with code at that |
| address. Note that ADDRESS may be a symbol like 'main'. If |
| '-source SOURCE' is specified, only dump symbols for that source |
| file. |
| |
| These commands are used to debug the GDB symbol-reading code. |
| These commands do not modify internal GDB state, therefore 'maint |
| print symbols' will only print symbols for already expanded symbol |
| tables. You can use the command 'info sources' to find out which |
| files these are. If you use 'maint print psymbols' instead, the |
| dump shows information about symbols that GDB only knows |
| partially--that is, symbols defined in files that GDB has skimmed, |
| but not yet read completely. Finally, 'maint print msymbols' just |
| dumps "minimal symbols", e.g., "ELF symbols". |
| |
| *Note Commands to Specify Files: Files, for a discussion of how GDB |
| reads symbols (in the description of 'symbol-file'). |
| |
| 'maint info symtabs [ REGEXP ]' |
| 'maint info psymtabs [ REGEXP ]' |
| |
| List the 'struct symtab' or 'struct partial_symtab' structures |
| whose names match REGEXP. If REGEXP is not given, list them all. |
| The output includes expressions which you can copy into a GDB |
| debugging this one to examine a particular structure in more |
| detail. For example: |
| |
| (gdb) maint info psymtabs dwarf2read |
| { objfile /home/gnu/build/gdb/gdb |
| ((struct objfile *) 0x82e69d0) |
| { psymtab /home/gnu/src/gdb/dwarf2read.c |
| ((struct partial_symtab *) 0x8474b10) |
| readin no |
| fullname (null) |
| text addresses 0x814d3c8 -- 0x8158074 |
| globals (* (struct partial_symbol **) 0x8507a08 @ 9) |
| statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) |
| dependencies (none) |
| } |
| } |
| (gdb) maint info symtabs |
| (gdb) |
| We see that there is one partial symbol table whose filename |
| contains the string 'dwarf2read', belonging to the 'gdb' |
| executable; and we see that GDB has not read in any symtabs yet at |
| all. If we set a breakpoint on a function, that will cause GDB to |
| read the symtab for the compilation unit containing that function: |
| |
| (gdb) break dwarf2_psymtab_to_symtab |
| Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, |
| line 1574. |
| (gdb) maint info symtabs |
| { objfile /home/gnu/build/gdb/gdb |
| ((struct objfile *) 0x82e69d0) |
| { symtab /home/gnu/src/gdb/dwarf2read.c |
| ((struct symtab *) 0x86c1f38) |
| dirname (null) |
| fullname (null) |
| blockvector ((struct blockvector *) 0x86c1bd0) (primary) |
| linetable ((struct linetable *) 0x8370fa0) |
| debugformat DWARF 2 |
| } |
| } |
| (gdb) |
| |
| 'maint info line-table [ REGEXP ]' |
| |
| List the 'struct linetable' from all 'struct symtab' instances |
| whose name matches REGEXP. If REGEXP is not given, list the |
| 'struct linetable' from all 'struct symtab'. |
| |
| 'maint set symbol-cache-size SIZE' |
| Set the size of the symbol cache to SIZE. The default size is |
| intended to be good enough for debugging most applications. This |
| option exists to allow for experimenting with different sizes. |
| |
| 'maint show symbol-cache-size' |
| Show the size of the symbol cache. |
| |
| 'maint print symbol-cache' |
| Print the contents of the symbol cache. This is useful when |
| debugging symbol cache issues. |
| |
| 'maint print symbol-cache-statistics' |
| Print symbol cache usage statistics. This helps determine how well |
| the cache is being utilized. |
| |
| 'maint flush-symbol-cache' |
| Flush the contents of the symbol cache, all entries are removed. |
| This command is useful when debugging the symbol cache. It is also |
| useful when collecting performance data. |
| |
| |
| File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top |
| |
| 17 Altering Execution |
| ********************* |
| |
| Once you think you have found an error in your program, you might want |
| to find out for certain whether correcting the apparent error would lead |
| to correct results in the rest of the run. You can find the answer by |
| experiment, using the GDB features for altering execution of the |
| program. |
| |
| For example, you can store new values into variables or memory |
| locations, give your program a signal, restart it at a different |
| address, or even return prematurely from a function. |
| |
| * Menu: |
| |
| * Assignment:: Assignment to variables |
| * Jumping:: Continuing at a different address |
| * Signaling:: Giving your program a signal |
| * Returning:: Returning from a function |
| * Calling:: Calling your program's functions |
| * Patching:: Patching your program |
| * Compiling and Injecting Code:: Compiling and injecting code in GDB |
| |
| |
| File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering |
| |
| 17.1 Assignment to Variables |
| ============================ |
| |
| To alter the value of a variable, evaluate an assignment expression. |
| *Note Expressions: Expressions. For example, |
| |
| print x=4 |
| |
| stores the value 4 into the variable 'x', and then prints the value of |
| the assignment expression (which is 4). *Note Using GDB with Different |
| Languages: Languages, for more information on operators in supported |
| languages. |
| |
| If you are not interested in seeing the value of the assignment, use |
| the 'set' command instead of the 'print' command. 'set' is really the |
| same as 'print' except that the expression's value is not printed and is |
| not put in the value history (*note Value History: Value History.). The |
| expression is evaluated only for its effects. |
| |
| If the beginning of the argument string of the 'set' command appears |
| identical to a 'set' subcommand, use the 'set variable' command instead |
| of just 'set'. This command is identical to 'set' except for its lack |
| of subcommands. For example, if your program has a variable 'width', |
| you get an error if you try to set a new value with just 'set width=13', |
| because GDB has the command 'set width': |
| |
| (gdb) whatis width |
| type = double |
| (gdb) p width |
| $4 = 13 |
| (gdb) set width=47 |
| Invalid syntax in expression. |
| |
| The invalid expression, of course, is '=47'. In order to actually set |
| the program's variable 'width', use |
| |
| (gdb) set var width=47 |
| |
| Because the 'set' command has many subcommands that can conflict with |
| the names of program variables, it is a good idea to use the 'set |
| variable' command instead of just 'set'. For example, if your program |
| has a variable 'g', you run into problems if you try to set a new value |
| with just 'set g=4', because GDB has the command 'set gnutarget', |
| abbreviated 'set g': |
| |
| (gdb) whatis g |
| type = double |
| (gdb) p g |
| $1 = 1 |
| (gdb) set g=4 |
| (gdb) p g |
| $2 = 1 |
| (gdb) r |
| The program being debugged has been started already. |
| Start it from the beginning? (y or n) y |
| Starting program: /home/smith/cc_progs/a.out |
| "/home/smith/cc_progs/a.out": can't open to read symbols: |
| Invalid bfd target. |
| (gdb) show g |
| The current BFD target is "=4". |
| |
| The program variable 'g' did not change, and you silently set the |
| 'gnutarget' to an invalid value. In order to set the variable 'g', use |
| |
| (gdb) set var g=4 |
| |
| GDB allows more implicit conversions in assignments than C; you can |
| freely store an integer value into a pointer variable or vice versa, and |
| you can convert any structure to any other structure that is the same |
| length or shorter. |
| |
| To store values into arbitrary places in memory, use the '{...}' |
| construct to generate a value of specified type at a specified address |
| (*note Expressions: Expressions.). For example, '{int}0x83040' refers |
| to memory location '0x83040' as an integer (which implies a certain size |
| and representation in memory), and |
| |
| set {int}0x83040 = 4 |
| |
| stores the value 4 into that memory location. |
| |
| |
| File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering |
| |
| 17.2 Continuing at a Different Address |
| ====================================== |
| |
| Ordinarily, when you continue your program, you do so at the place where |
| it stopped, with the 'continue' command. You can instead continue at an |
| address of your own choosing, with the following commands: |
| |
| 'jump LOCATION' |
| 'j LOCATION' |
| Resume execution at LOCATION. Execution stops again immediately if |
| there is a breakpoint there. *Note Specify Location::, for a |
| description of the different forms of LOCATION. It is common |
| practice to use the 'tbreak' command in conjunction with 'jump'. |
| *Note Setting Breakpoints: Set Breaks. |
| |
| The 'jump' command does not change the current stack frame, or the |
| stack pointer, or the contents of any memory location or any |
| register other than the program counter. If LOCATION is in a |
| different function from the one currently executing, the results |
| may be bizarre if the two functions expect different patterns of |
| arguments or of local variables. For this reason, the 'jump' |
| command requests confirmation if the specified line is not in the |
| function currently executing. However, even bizarre results are |
| predictable if you are well acquainted with the machine-language |
| code of your program. |
| |
| On many systems, you can get much the same effect as the 'jump' |
| command by storing a new value into the register '$pc'. The difference |
| is that this does not start your program running; it only changes the |
| address of where it _will_ run when you continue. For example, |
| |
| set $pc = 0x485 |
| |
| makes the next 'continue' command or stepping command execute at address |
| '0x485', rather than at the address where your program stopped. *Note |
| Continuing and Stepping: Continuing and Stepping. |
| |
| The most common occasion to use the 'jump' command is to back |
| up--perhaps with more breakpoints set--over a portion of a program that |
| has already executed, in order to examine its execution in more detail. |
| |
| |
| File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering |
| |
| 17.3 Giving your Program a Signal |
| ================================= |
| |
| 'signal SIGNAL' |
| Resume execution where your program is stopped, but immediately |
| give it the signal SIGNAL. The SIGNAL can be the name or the |
| number of a signal. For example, on many systems 'signal 2' and |
| 'signal SIGINT' are both ways of sending an interrupt signal. |
| |
| Alternatively, if SIGNAL is zero, continue execution without giving |
| a signal. This is useful when your program stopped on account of a |
| signal and would ordinarily see the signal when resumed with the |
| 'continue' command; 'signal 0' causes it to resume without a |
| signal. |
| |
| _Note:_ When resuming a multi-threaded program, SIGNAL is delivered |
| to the currently selected thread, not the thread that last reported |
| a stop. This includes the situation where a thread was stopped due |
| to a signal. So if you want to continue execution suppressing the |
| signal that stopped a thread, you should select that same thread |
| before issuing the 'signal 0' command. If you issue the 'signal 0' |
| command with another thread as the selected one, GDB detects that |
| and asks for confirmation. |
| |
| Invoking the 'signal' command is not the same as invoking the |
| 'kill' utility from the shell. Sending a signal with 'kill' causes |
| GDB to decide what to do with the signal depending on the signal |
| handling tables (*note Signals::). The 'signal' command passes the |
| signal directly to your program. |
| |
| 'signal' does not repeat when you press <RET> a second time after |
| executing the command. |
| |
| 'queue-signal SIGNAL' |
| Queue SIGNAL to be delivered immediately to the current thread when |
| execution of the thread resumes. The SIGNAL can be the name or the |
| number of a signal. For example, on many systems 'signal 2' and |
| 'signal SIGINT' are both ways of sending an interrupt signal. The |
| handling of the signal must be set to pass the signal to the |
| program, otherwise GDB will report an error. You can control the |
| handling of signals from GDB with the 'handle' command (*note |
| Signals::). |
| |
| Alternatively, if SIGNAL is zero, any currently queued signal for |
| the current thread is discarded and when execution resumes no |
| signal will be delivered. This is useful when your program stopped |
| on account of a signal and would ordinarily see the signal when |
| resumed with the 'continue' command. |
| |
| This command differs from the 'signal' command in that the signal |
| is just queued, execution is not resumed. And 'queue-signal' |
| cannot be used to pass a signal whose handling state has been set |
| to 'nopass' (*note Signals::). |
| |
| *Note stepping into signal handlers::, for information on how |
| stepping commands behave when the thread has a signal queued. |
| |
| |
| File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering |
| |
| 17.4 Returning from a Function |
| ============================== |
| |
| 'return' |
| 'return EXPRESSION' |
| You can cancel execution of a function call with the 'return' |
| command. If you give an EXPRESSION argument, its value is used as |
| the function's return value. |
| |
| When you use 'return', GDB discards the selected stack frame (and all |
| frames within it). You can think of this as making the discarded frame |
| return prematurely. If you wish to specify a value to be returned, give |
| that value as the argument to 'return'. |
| |
| This pops the selected stack frame (*note Selecting a Frame: |
| Selection.), and any other frames inside of it, leaving its caller as |
| the innermost remaining frame. That frame becomes selected. The |
| specified value is stored in the registers used for returning values of |
| functions. |
| |
| The 'return' command does not resume execution; it leaves the program |
| stopped in the state that would exist if the function had just returned. |
| In contrast, the 'finish' command (*note Continuing and Stepping: |
| Continuing and Stepping.) resumes execution until the selected stack |
| frame returns naturally. |
| |
| GDB needs to know how the EXPRESSION argument should be set for the |
| inferior. The concrete registers assignment depends on the OS ABI and |
| the type being returned by the selected stack frame. For example it is |
| common for OS ABI to return floating point values in FPU registers while |
| integer values in CPU registers. Still some ABIs return even floating |
| point values in CPU registers. Larger integer widths (such as 'long |
| long int') also have specific placement rules. GDB already knows the OS |
| ABI from its current target so it needs to find out also the type being |
| returned to make the assignment into the right register(s). |
| |
| Normally, the selected stack frame has debug info. GDB will always |
| use the debug info instead of the implicit type of EXPRESSION when the |
| debug info is available. For example, if you type 'return -1', and the |
| function in the current stack frame is declared to return a 'long long |
| int', GDB transparently converts the implicit 'int' value of -1 into a |
| 'long long int': |
| |
| Breakpoint 1, func () at gdb.base/return-nodebug.c:29 |
| 29 return 31; |
| (gdb) return -1 |
| Make func return now? (y or n) y |
| #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 |
| 43 printf ("result=%lld\n", func ()); |
| (gdb) |
| |
| However, if the selected stack frame does not have a debug info, |
| e.g., if the function was compiled without debug info, GDB has to find |
| out the type to return from user. Specifying a different type by |
| mistake may set the value in different inferior registers than the |
| caller code expects. For example, typing 'return -1' with its implicit |
| type 'int' would set only a part of a 'long long int' result for a debug |
| info less function (on 32-bit architectures). Therefore the user is |
| required to specify the return type by an appropriate cast explicitly: |
| |
| Breakpoint 2, 0x0040050b in func () |
| (gdb) return -1 |
| Return value type not available for selected stack frame. |
| Please use an explicit cast of the value to return. |
| (gdb) return (long long int) -1 |
| Make selected stack frame return now? (y or n) y |
| #0 0x00400526 in main () |
| (gdb) |
| |
| |
| File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering |
| |
| 17.5 Calling Program Functions |
| ============================== |
| |
| 'print EXPR' |
| Evaluate the expression EXPR and display the resulting value. The |
| expression may include calls to functions in the program being |
| debugged. |
| |
| 'call EXPR' |
| Evaluate the expression EXPR without displaying 'void' returned |
| values. |
| |
| You can use this variant of the 'print' command if you want to |
| execute a function from your program that does not return anything |
| (a.k.a. "a void function"), but without cluttering the output with |
| 'void' returned values that GDB will otherwise print. If the |
| result is not void, it is printed and saved in the value history. |
| |
| It is possible for the function you call via the 'print' or 'call' |
| command to generate a signal (e.g., if there's a bug in the function, or |
| if you passed it incorrect arguments). What happens in that case is |
| controlled by the 'set unwindonsignal' command. |
| |
| Similarly, with a C++ program it is possible for the function you |
| call via the 'print' or 'call' command to generate an exception that is |
| not handled due to the constraints of the dummy frame. In this case, |
| any exception that is raised in the frame, but has an out-of-frame |
| exception handler will not be found. GDB builds a dummy-frame for the |
| inferior function call, and the unwinder cannot seek for exception |
| handlers outside of this dummy-frame. What happens in that case is |
| controlled by the 'set unwind-on-terminating-exception' command. |
| |
| 'set unwindonsignal' |
| Set unwinding of the stack if a signal is received while in a |
| function that GDB called in the program being debugged. If set to |
| on, GDB unwinds the stack it created for the call and restores the |
| context to what it was before the call. If set to off (the |
| default), GDB stops in the frame where the signal was received. |
| |
| 'show unwindonsignal' |
| Show the current setting of stack unwinding in the functions called |
| by GDB. |
| |
| 'set unwind-on-terminating-exception' |
| Set unwinding of the stack if a C++ exception is raised, but left |
| unhandled while in a function that GDB called in the program being |
| debugged. If set to on (the default), GDB unwinds the stack it |
| created for the call and restores the context to what it was before |
| the call. If set to off, GDB the exception is delivered to the |
| default C++ exception handler and the inferior terminated. |
| |
| 'show unwind-on-terminating-exception' |
| Show the current setting of stack unwinding in the functions called |
| by GDB. |
| |
| 'set may-call-functions' |
| Set permission to call functions in the program. This controls |
| whether GDB will attempt to call functions in the program, such as |
| with expressions in the 'print' command. It defaults to 'on'. |
| |
| To call a function in the program, GDB has to temporarily modify |
| the state of the inferior. This has potentially undesired side |
| effects. Also, having GDB call nested functions is likely to be |
| erroneous and may even crash the program being debugged. You can |
| avoid such hazards by forbidding GDB from calling functions in the |
| program being debugged. If calling functions in the program is |
| forbidden, GDB will throw an error when a command (such as printing |
| an expression) starts a function call in the program. |
| |
| 'show may-call-functions' |
| Show permission to call functions in the program. |
| |
| 17.5.1 Calling functions with no debug info |
| ------------------------------------------- |
| |
| Sometimes, a function you wish to call is missing debug information. In |
| such case, GDB does not know the type of the function, including the |
| types of the function's parameters. To avoid calling the inferior |
| function incorrectly, which could result in the called function |
| functioning erroneously and even crash, GDB refuses to call the function |
| unless you tell it the type of the function. |
| |
| For prototyped (i.e. ANSI/ISO style) functions, there are two ways to |
| do that. The simplest is to cast the call to the function's declared |
| return type. For example: |
| |
| (gdb) p getenv ("PATH") |
| 'getenv' has unknown return type; cast the call to its declared return type |
| (gdb) p (char *) getenv ("PATH") |
| $1 = 0x7fffffffe7ba "/usr/local/bin:/"... |
| |
| Casting the return type of a no-debug function is equivalent to |
| casting the function to a pointer to a prototyped function that has a |
| prototype that matches the types of the passed-in arguments, and calling |
| that. I.e., the call above is equivalent to: |
| |
| (gdb) p ((char * (*) (const char *)) getenv) ("PATH") |
| |
| and given this prototyped C or C++ function with float parameters: |
| |
| float multiply (float v1, float v2) { return v1 * v2; } |
| |
| these calls are equivalent: |
| |
| (gdb) p (float) multiply (2.0f, 3.0f) |
| (gdb) p ((float (*) (float, float)) multiply) (2.0f, 3.0f) |
| |
| If the function you wish to call is declared as unprototyped (i.e. |
| old K&R style), you must use the cast-to-function-pointer syntax, so |
| that GDB knows that it needs to apply default argument promotions |
| (promote float arguments to double). *Note float promotion: ABI. For |
| example, given this unprototyped C function with float parameters, and |
| no debug info: |
| |
| float |
| multiply_noproto (v1, v2) |
| float v1, v2; |
| { |
| return v1 * v2; |
| } |
| |
| you call it like this: |
| |
| (gdb) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f) |
| |
| |
| File: gdb.info, Node: Patching, Next: Compiling and Injecting Code, Prev: Calling, Up: Altering |
| |
| 17.6 Patching Programs |
| ====================== |
| |
| By default, GDB opens the file containing your program's executable code |
| (or the corefile) read-only. This prevents accidental alterations to |
| machine code; but it also prevents you from intentionally patching your |
| program's binary. |
| |
| If you'd like to be able to patch the binary, you can specify that |
| explicitly with the 'set write' command. For example, you might want to |
| turn on internal debugging flags, or even to make emergency repairs. |
| |
| 'set write on' |
| 'set write off' |
| If you specify 'set write on', GDB opens executable and core files |
| for both reading and writing; if you specify 'set write off' (the |
| default), GDB opens them read-only. |
| |
| If you have already loaded a file, you must load it again (using |
| the 'exec-file' or 'core-file' command) after changing 'set write', |
| for your new setting to take effect. |
| |
| 'show write' |
| Display whether executable files and core files are opened for |
| writing as well as reading. |
| |
| |
| File: gdb.info, Node: Compiling and Injecting Code, Prev: Patching, Up: Altering |
| |
| 17.7 Compiling and injecting code in GDB |
| ======================================== |
| |
| GDB supports on-demand compilation and code injection into programs |
| running under GDB. GCC 5.0 or higher built with 'libcc1.so' must be |
| installed for this functionality to be enabled. This functionality is |
| implemented with the following commands. |
| |
| 'compile code SOURCE-CODE' |
| 'compile code -raw -- SOURCE-CODE' |
| Compile SOURCE-CODE with the compiler language found as the current |
| language in GDB (*note Languages::). If compilation and injection |
| is not supported with the current language specified in GDB, or the |
| compiler does not support this feature, an error message will be |
| printed. If SOURCE-CODE compiles and links successfully, GDB will |
| load the object-code emitted, and execute it within the context of |
| the currently selected inferior. It is important to note that the |
| compiled code is executed immediately. After execution, the |
| compiled code is removed from GDB and any new types or variables |
| you have defined will be deleted. |
| |
| The command allows you to specify SOURCE-CODE in two ways. The |
| simplest method is to provide a single line of code to the command. |
| E.g.: |
| |
| compile code printf ("hello world\n"); |
| |
| If you specify options on the command line as well as source code, |
| they may conflict. The '--' delimiter can be used to separate |
| options from actual source code. E.g.: |
| |
| compile code -r -- printf ("hello world\n"); |
| |
| Alternatively you can enter source code as multiple lines of text. |
| To enter this mode, invoke the 'compile code' command without any |
| text following the command. This will start the multiple-line |
| editor and allow you to type as many lines of source code as |
| required. When you have completed typing, enter 'end' on its own |
| line to exit the editor. |
| |
| compile code |
| >printf ("hello\n"); |
| >printf ("world\n"); |
| >end |
| |
| Specifying '-raw', prohibits GDB from wrapping the provided |
| SOURCE-CODE in a callable scope. In this case, you must specify |
| the entry point of the code by defining a function named |
| '_gdb_expr_'. The '-raw' code cannot access variables of the |
| inferior. Using '-raw' option may be needed for example when |
| SOURCE-CODE requires '#include' lines which may conflict with |
| inferior symbols otherwise. |
| |
| 'compile file FILENAME' |
| 'compile file -raw FILENAME' |
| Like 'compile code', but take the source code from FILENAME. |
| |
| compile file /home/user/example.c |
| |
| 'compile print [[OPTIONS] --] EXPR' |
| 'compile print [[OPTIONS] --] /F EXPR' |
| Compile and execute EXPR with the compiler language found as the |
| current language in GDB (*note Languages::). By default the value |
| of EXPR is printed in a format appropriate to its data type; you |
| can choose a different format by specifying '/F', where F is a |
| letter specifying the format; see *note Output Formats: Output |
| Formats. The 'compile print' command accepts the same options as |
| the 'print' command; see *note print options::. |
| |
| 'compile print [[OPTIONS] --]' |
| 'compile print [[OPTIONS] --] /F' |
| Alternatively you can enter the expression (source code producing |
| it) as multiple lines of text. To enter this mode, invoke the |
| 'compile print' command without any text following the command. |
| This will start the multiple-line editor. |
| |
| The process of compiling and injecting the code can be inspected using: |
| |
| 'set debug compile' |
| Turns on or off display of GDB process of compiling and injecting |
| the code. The default is off. |
| |
| 'show debug compile' |
| Displays the current state of displaying GDB process of compiling |
| and injecting the code. |
| |
| 'set debug compile-cplus-types' |
| Turns on or off the display of C++ type conversion debugging |
| information. The default is off. |
| |
| 'show debug compile-cplus-types' |
| Displays the current state of displaying debugging information for |
| C++ type conversion. |
| |
| 17.7.1 Compilation options for the 'compile' command |
| ---------------------------------------------------- |
| |
| GDB needs to specify the right compilation options for the code to be |
| injected, in part to make its ABI compatible with the inferior and in |
| part to make the injected code compatible with GDB's injecting process. |
| |
| The options used, in increasing precedence: |
| |
| target architecture and OS options ('gdbarch') |
| These options depend on target processor type and target operating |
| system, usually they specify at least 32-bit ('-m32') or 64-bit |
| ('-m64') compilation option. |
| |
| compilation options recorded in the target |
| GCC (since version 4.7) stores the options used for compilation |
| into 'DW_AT_producer' part of DWARF debugging information according |
| to the GCC option '-grecord-gcc-switches'. One has to explicitly |
| specify '-g' during inferior compilation otherwise GCC produces no |
| DWARF. This feature is only relevant for platforms where '-g' |
| produces DWARF by default, otherwise one may try to enforce DWARF |
| by using '-gdwarf-4'. |
| |
| compilation options set by 'set compile-args' |
| |
| You can override compilation options using the following command: |
| |
| 'set compile-args' |
| Set compilation options used for compiling and injecting code with |
| the 'compile' commands. These options override any conflicting |
| ones from the target architecture and/or options stored during |
| inferior compilation. |
| |
| 'show compile-args' |
| Displays the current state of compilation options override. This |
| does not show all the options actually used during compilation, use |
| *note set debug compile:: for that. |
| |
| 17.7.2 Caveats when using the 'compile' command |
| ----------------------------------------------- |
| |
| There are a few caveats to keep in mind when using the 'compile' |
| command. As the caveats are different per language, the table below |
| highlights specific issues on a per language basis. |
| |
| C code examples and caveats |
| When the language in GDB is set to 'C', the compiler will attempt |
| to compile the source code with a 'C' compiler. The source code |
| provided to the 'compile' command will have much the same access to |
| variables and types as it normally would if it were part of the |
| program currently being debugged in GDB. |
| |
| Below is a sample program that forms the basis of the examples that |
| follow. This program has been compiled and loaded into GDB, much |
| like any other normal debugging session. |
| |
| void function1 (void) |
| { |
| int i = 42; |
| printf ("function 1\n"); |
| } |
| |
| void function2 (void) |
| { |
| int j = 12; |
| function1 (); |
| } |
| |
| int main(void) |
| { |
| int k = 6; |
| int *p; |
| function2 (); |
| return 0; |
| } |
| |
| For the purposes of the examples in this section, the program above |
| has been compiled, loaded into GDB, stopped at the function 'main', |
| and GDB is awaiting input from the user. |
| |
| To access variables and types for any program in GDB, the program |
| must be compiled and packaged with debug information. The |
| 'compile' command is not an exception to this rule. Without debug |
| information, you can still use the 'compile' command, but you will |
| be very limited in what variables and types you can access. |
| |
| So with that in mind, the example above has been compiled with |
| debug information enabled. The 'compile' command will have access |
| to all variables and types (except those that may have been |
| optimized out). Currently, as GDB has stopped the program in the |
| 'main' function, the 'compile' command would have access to the |
| variable 'k'. You could invoke the 'compile' command and type some |
| source code to set the value of 'k'. You can also read it, or do |
| anything with that variable you would normally do in 'C'. Be aware |
| that changes to inferior variables in the 'compile' command are |
| persistent. In the following example: |
| |
| compile code k = 3; |
| |
| the variable 'k' is now 3. It will retain that value until |
| something else in the example program changes it, or another |
| 'compile' command changes it. |
| |
| Normal scope and access rules apply to source code compiled and |
| injected by the 'compile' command. In the example, the variables |
| 'j' and 'k' are not accessible yet, because the program is |
| currently stopped in the 'main' function, where these variables are |
| not in scope. Therefore, the following command |
| |
| compile code j = 3; |
| |
| will result in a compilation error message. |
| |
| Once the program is continued, execution will bring these variables |
| in scope, and they will become accessible; then the code you |
| specify via the 'compile' command will be able to access them. |
| |
| You can create variables and types with the 'compile' command as |
| part of your source code. Variables and types that are created as |
| part of the 'compile' command are not visible to the rest of the |
| program for the duration of its run. This example is valid: |
| |
| compile code int ff = 5; printf ("ff is %d\n", ff); |
| |
| However, if you were to type the following into GDB after that |
| command has completed: |
| |
| compile code printf ("ff is %d\n'', ff); |
| |
| a compiler error would be raised as the variable 'ff' no longer |
| exists. Object code generated and injected by the 'compile' |
| command is removed when its execution ends. Caution is advised |
| when assigning to program variables values of variables created by |
| the code submitted to the 'compile' command. This example is |
| valid: |
| |
| compile code int ff = 5; k = ff; |
| |
| The value of the variable 'ff' is assigned to 'k'. The variable |
| 'k' does not require the existence of 'ff' to maintain the value it |
| has been assigned. However, pointers require particular care in |
| assignment. If the source code compiled with the 'compile' command |
| changed the address of a pointer in the example program, perhaps to |
| a variable created in the 'compile' command, that pointer would |
| point to an invalid location when the command exits. The following |
| example would likely cause issues with your debugged program: |
| |
| compile code int ff = 5; p = &ff; |
| |
| In this example, 'p' would point to 'ff' when the 'compile' command |
| is executing the source code provided to it. However, as variables |
| in the (example) program persist with their assigned values, the |
| variable 'p' would point to an invalid location when the command |
| exists. A general rule should be followed in that you should |
| either assign 'NULL' to any assigned pointers, or restore a valid |
| location to the pointer before the command exits. |
| |
| Similar caution must be exercised with any structs, unions, and |
| typedefs defined in 'compile' command. Types defined in the |
| 'compile' command will no longer be available in the next 'compile' |
| command. Therefore, if you cast a variable to a type defined in |
| the 'compile' command, care must be taken to ensure that any future |
| need to resolve the type can be achieved. |
| |
| (gdb) compile code static struct a { int a; } v = { 42 }; argv = &v; |
| (gdb) compile code printf ("%d\n", ((struct a *) argv)->a); |
| gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ |
| Compilation failed. |
| (gdb) compile code struct a { int a; }; printf ("%d\n", ((struct a *) argv)->a); |
| 42 |
| |
| Variables that have been optimized away by the compiler are not |
| accessible to the code submitted to the 'compile' command. Access |
| to those variables will generate a compiler error which GDB will |
| print to the console. |
| |
| 17.7.3 Compiler search for the 'compile' command |
| ------------------------------------------------ |
| |
| GDB needs to find GCC for the inferior being debugged which may not be |
| obvious for remote targets of different architecture than where GDB is |
| running. Environment variable 'PATH' on GDB host is searched for GCC |
| binary matching the target architecture and operating system. This |
| search can be overriden by 'set compile-gcc' GDB command below. 'PATH' |
| is taken from shell that executed GDB, it is not the value set by GDB |
| command 'set environment'). *Note Environment::. |
| |
| Specifically 'PATH' is searched for binaries matching regular |
| expression 'ARCH(-[^-]*)?-OS-gcc' according to the inferior target being |
| debugged. ARCH is processor name -- multiarch is supported, so for |
| example both 'i386' and 'x86_64' targets look for pattern |
| '(x86_64|i.86)' and both 's390' and 's390x' targets look for pattern |
| 's390x?'. OS is currently supported only for pattern 'linux(-gnu)?'. |
| |
| On Posix hosts the compiler driver GDB needs to find also shared |
| library 'libcc1.so' from the compiler. It is searched in default shared |
| library search path (overridable with usual environment variable |
| 'LD_LIBRARY_PATH'), unrelated to 'PATH' or 'set compile-gcc' settings. |
| Contrary to it 'libcc1plugin.so' is found according to the installation |
| of the found compiler -- as possibly specified by the 'set compile-gcc' |
| command. |
| |
| 'set compile-gcc' |
| Set compilation command used for compiling and injecting code with |
| the 'compile' commands. If this option is not set (it is set to an |
| empty string), the search described above will occur -- that is the |
| default. |
| |
| 'show compile-gcc' |
| Displays the current compile command GCC driver filename. If set, |
| it is the main command 'gcc', found usually for example under name |
| 'x86_64-linux-gnu-gcc'. |
| |
| |
| File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top |
| |
| 18 GDB Files |
| ************ |
| |
| GDB needs to know the file name of the program to be debugged, both in |
| order to read its symbol table and in order to start your program. To |
| debug a core dump of a previous run, you must also tell GDB the name of |
| the core dump file. |
| |
| * Menu: |
| |
| * Files:: Commands to specify files |
| * File Caching:: Information about GDB's file caching |
| * Separate Debug Files:: Debugging information in separate files |
| * MiniDebugInfo:: Debugging information in a special section |
| * Index Files:: Index files speed up GDB |
| * Symbol Errors:: Errors reading symbol files |
| * Data Files:: GDB data files |
| |
| |
| File: gdb.info, Node: Files, Next: File Caching, Up: GDB Files |
| |
| 18.1 Commands to Specify Files |
| ============================== |
| |
| You may want to specify executable and core dump file names. The usual |
| way to do this is at start-up time, using the arguments to GDB's |
| start-up commands (*note Getting In and Out of GDB: Invocation.). |
| |
| Occasionally it is necessary to change to a different file during a |
| GDB session. Or you may run GDB and forget to specify a file you want |
| to use. Or you are debugging a remote target via 'gdbserver' (*note |
| file: Server.). In these situations the GDB commands to specify new |
| files are useful. |
| |
| 'file FILENAME' |
| Use FILENAME as the program to be debugged. It is read for its |
| symbols and for the contents of pure memory. It is also the |
| program executed when you use the 'run' command. If you do not |
| specify a directory and the file is not found in the GDB working |
| directory, GDB uses the environment variable 'PATH' as a list of |
| directories to search, just as the shell does when looking for a |
| program to run. You can change the value of this variable, for |
| both GDB and your program, using the 'path' command. |
| |
| You can load unlinked object '.o' files into GDB using the 'file' |
| command. You will not be able to "run" an object file, but you can |
| disassemble functions and inspect variables. Also, if the |
| underlying BFD functionality supports it, you could use 'gdb |
| -write' to patch object files using this technique. Note that GDB |
| can neither interpret nor modify relocations in this case, so |
| branches and some initialized variables will appear to go to the |
| wrong place. But this feature is still handy from time to time. |
| |
| 'file' |
| 'file' with no argument makes GDB discard any information it has on |
| both executable file and the symbol table. |
| |
| 'exec-file [ FILENAME ]' |
| Specify that the program to be run (but not the symbol table) is |
| found in FILENAME. GDB searches the environment variable 'PATH' if |
| necessary to locate your program. Omitting FILENAME means to |
| discard information on the executable file. |
| |
| 'symbol-file [ FILENAME [ -o OFFSET ]]' |
| Read symbol table information from file FILENAME. 'PATH' is |
| searched when necessary. Use the 'file' command to get both symbol |
| table and program to run from the same file. |
| |
| If an optional OFFSET is specified, it is added to the start |
| address of each section in the symbol file. This is useful if the |
| program is relocated at runtime, such as the Linux kernel with |
| kASLR enabled. |
| |
| 'symbol-file' with no argument clears out GDB information on your |
| program's symbol table. |
| |
| The 'symbol-file' command causes GDB to forget the contents of some |
| breakpoints and auto-display expressions. This is because they may |
| contain pointers to the internal data recording symbols and data |
| types, which are part of the old symbol table data being discarded |
| inside GDB. |
| |
| 'symbol-file' does not repeat if you press <RET> again after |
| executing it once. |
| |
| When GDB is configured for a particular environment, it understands |
| debugging information in whatever format is the standard generated |
| for that environment; you may use either a GNU compiler, or other |
| compilers that adhere to the local conventions. Best results are |
| usually obtained from GNU compilers; for example, using 'GCC' you |
| can generate debugging information for optimized code. |
| |
| For most kinds of object files, with the exception of old SVR3 |
| systems using COFF, the 'symbol-file' command does not normally |
| read the symbol table in full right away. Instead, it scans the |
| symbol table quickly to find which source files and which symbols |
| are present. The details are read later, one source file at a |
| time, as they are needed. |
| |
| The purpose of this two-stage reading strategy is to make GDB start |
| up faster. For the most part, it is invisible except for |
| occasional pauses while the symbol table details for a particular |
| source file are being read. (The 'set verbose' command can turn |
| these pauses into messages if desired. *Note Optional Warnings and |
| Messages: Messages/Warnings.) |
| |
| We have not implemented the two-stage strategy for COFF yet. When |
| the symbol table is stored in COFF format, 'symbol-file' reads the |
| symbol table data in full right away. Note that "stabs-in-COFF" |
| still does the two-stage strategy, since the debug info is actually |
| in stabs format. |
| |
| 'symbol-file [ -readnow ] FILENAME' |
| 'file [ -readnow ] FILENAME' |
| You can override the GDB two-stage strategy for reading symbol |
| tables by using the '-readnow' option with any of the commands that |
| load symbol table information, if you want to be sure GDB has the |
| entire symbol table available. |
| |
| 'symbol-file [ -readnever ] FILENAME' |
| 'file [ -readnever ] FILENAME' |
| You can instruct GDB to never read the symbolic information |
| contained in FILENAME by using the '-readnever' option. *Note |
| --readnever::. |
| |
| 'core-file [FILENAME]' |
| 'core' |
| Specify the whereabouts of a core dump file to be used as the |
| "contents of memory". Traditionally, core files contain only some |
| parts of the address space of the process that generated them; GDB |
| can access the executable file itself for other parts. |
| |
| 'core-file' with no argument specifies that no core file is to be |
| used. |
| |
| Note that the core file is ignored when your program is actually |
| running under GDB. So, if you have been running your program and |
| you wish to debug a core file instead, you must kill the subprocess |
| in which the program is running. To do this, use the 'kill' |
| command (*note Killing the Child Process: Kill Process.). |
| |
| 'add-symbol-file FILENAME [ -readnow | -readnever ] [ -o OFFSET ] [ TEXTADDRESS ] [ -s SECTION ADDRESS ... ]' |
| The 'add-symbol-file' command reads additional symbol table |
| information from the file FILENAME. You would use this command |
| when FILENAME has been dynamically loaded (by some other means) |
| into the program that is running. The TEXTADDRESS parameter gives |
| the memory address at which the file's text section has been |
| loaded. You can additionally specify the base address of other |
| sections using an arbitrary number of '-s SECTION ADDRESS' pairs. |
| If a section is omitted, GDB will use its default addresses as |
| found in FILENAME. Any ADDRESS or TEXTADDRESS can be given as an |
| expression. |
| |
| If an optional OFFSET is specified, it is added to the start |
| address of each section, except those for which the address was |
| specified explicitly. |
| |
| The symbol table of the file FILENAME is added to the symbol table |
| originally read with the 'symbol-file' command. You can use the |
| 'add-symbol-file' command any number of times; the new symbol data |
| thus read is kept in addition to the old. |
| |
| Changes can be reverted using the command 'remove-symbol-file'. |
| |
| Although FILENAME is typically a shared library file, an executable |
| file, or some other object file which has been fully relocated for |
| loading into a process, you can also load symbolic information from |
| relocatable '.o' files, as long as: |
| |
| * the file's symbolic information refers only to linker symbols |
| defined in that file, not to symbols defined by other object |
| files, |
| * every section the file's symbolic information refers to has |
| actually been loaded into the inferior, as it appears in the |
| file, and |
| * you can determine the address at which every section was |
| loaded, and provide these to the 'add-symbol-file' command. |
| |
| Some embedded operating systems, like Sun Chorus and VxWorks, can |
| load relocatable files into an already running program; such |
| systems typically make the requirements above easy to meet. |
| However, it's important to recognize that many native systems use |
| complex link procedures ('.linkonce' section factoring and C++ |
| constructor table assembly, for example) that make the requirements |
| difficult to meet. In general, one cannot assume that using |
| 'add-symbol-file' to read a relocatable object file's symbolic |
| information will have the same effect as linking the relocatable |
| object file into the program in the normal way. |
| |
| 'add-symbol-file' does not repeat if you press <RET> after using |
| it. |
| |
| 'remove-symbol-file FILENAME' |
| 'remove-symbol-file -a ADDRESS' |
| Remove a symbol file added via the 'add-symbol-file' command. The |
| file to remove can be identified by its FILENAME or by an ADDRESS |
| that lies within the boundaries of this symbol file in memory. |
| Example: |
| |
| (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 |
| add symbol table from file "/home/user/gdb/mylib.so" at |
| .text_addr = 0x7ffff7ff9480 |
| (y or n) y |
| Reading symbols from /home/user/gdb/mylib.so...done. |
| (gdb) remove-symbol-file -a 0x7ffff7ff9480 |
| Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y |
| (gdb) |
| |
| 'remove-symbol-file' does not repeat if you press <RET> after using |
| it. |
| |
| 'add-symbol-file-from-memory ADDRESS' |
| Load symbols from the given ADDRESS in a dynamically loaded object |
| file whose image is mapped directly into the inferior's memory. |
| For example, the Linux kernel maps a 'syscall DSO' into each |
| process's address space; this DSO provides kernel-specific code for |
| some system calls. The argument can be any expression whose |
| evaluation yields the address of the file's shared object file |
| header. For this command to work, you must have used 'symbol-file' |
| or 'exec-file' commands in advance. |
| |
| 'section SECTION ADDR' |
| The 'section' command changes the base address of the named SECTION |
| of the exec file to ADDR. This can be used if the exec file does |
| not contain section addresses, (such as in the 'a.out' format), or |
| when the addresses specified in the file itself are wrong. Each |
| section must be changed separately. The 'info files' command, |
| described below, lists all the sections and their addresses. |
| |
| 'info files' |
| 'info target' |
| 'info files' and 'info target' are synonymous; both print the |
| current target (*note Specifying a Debugging Target: Targets.), |
| including the names of the executable and core dump files currently |
| in use by GDB, and the files from which symbols were loaded. The |
| command 'help target' lists all possible targets rather than |
| current ones. |
| |
| 'maint info sections' |
| Another command that can give you extra information about program |
| sections is 'maint info sections'. In addition to the section |
| information displayed by 'info files', this command displays the |
| flags and file offset of each section in the executable and core |
| dump files. In addition, 'maint info sections' provides the |
| following command options (which may be arbitrarily combined): |
| |
| 'ALLOBJ' |
| Display sections for all loaded object files, including shared |
| libraries. |
| 'SECTIONS' |
| Display info only for named SECTIONS. |
| 'SECTION-FLAGS' |
| Display info only for sections for which SECTION-FLAGS are |
| true. The section flags that GDB currently knows about are: |
| 'ALLOC' |
| Section will have space allocated in the process when |
| loaded. Set for all sections except those containing |
| debug information. |
| 'LOAD' |
| Section will be loaded from the file into the child |
| process memory. Set for pre-initialized code and data, |
| clear for '.bss' sections. |
| 'RELOC' |
| Section needs to be relocated before loading. |
| 'READONLY' |
| Section cannot be modified by the child process. |
| 'CODE' |
| Section contains executable code only. |
| 'DATA' |
| Section contains data only (no executable code). |
| 'ROM' |
| Section will reside in ROM. |
| 'CONSTRUCTOR' |
| Section contains data for constructor/destructor lists. |
| 'HAS_CONTENTS' |
| Section is not empty. |
| 'NEVER_LOAD' |
| An instruction to the linker to not output the section. |
| 'COFF_SHARED_LIBRARY' |
| A notification to the linker that the section contains |
| COFF shared library information. |
| 'IS_COMMON' |
| Section contains common symbols. |
| 'set trust-readonly-sections on' |
| Tell GDB that readonly sections in your object file really are |
| read-only (i.e. that their contents will not change). In that |
| case, GDB can fetch values from these sections out of the object |
| file, rather than from the target program. For some targets |
| (notably embedded ones), this can be a significant enhancement to |
| debugging performance. |
| |
| The default is off. |
| |
| 'set trust-readonly-sections off' |
| Tell GDB not to trust readonly sections. This means that the |
| contents of the section might change while the program is running, |
| and must therefore be fetched from the target when needed. |
| |
| 'show trust-readonly-sections' |
| Show the current setting of trusting readonly sections. |
| |
| All file-specifying commands allow both absolute and relative file |
| names as arguments. GDB always converts the file name to an absolute |
| file name and remembers it that way. |
| |
| GDB supports GNU/Linux, MS-Windows, SunOS, Darwin/Mach-O, SVr4, IBM |
| RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and DSBT (TIC6X) shared |
| libraries. |
| |
| On MS-Windows GDB must be linked with the Expat library to support |
| shared libraries. *Note Expat::. |
| |
| GDB automatically loads symbol definitions from shared libraries when |
| you use the 'run' command, or when you examine a core file. (Before you |
| issue the 'run' command, GDB does not understand references to a |
| function in a shared library, however--unless you are debugging a core |
| file). |
| |
| There are times, however, when you may wish to not automatically load |
| symbol definitions from shared libraries, such as when they are |
| particularly large or there are many of them. |
| |
| To control the automatic loading of shared library symbols, use the |
| commands: |
| |
| 'set auto-solib-add MODE' |
| If MODE is 'on', symbols from all shared object libraries will be |
| loaded automatically when the inferior begins execution, you attach |
| to an independently started inferior, or when the dynamic linker |
| informs GDB that a new library has been loaded. If MODE is 'off', |
| symbols must be loaded manually, using the 'sharedlibrary' command. |
| The default value is 'on'. |
| |
| If your program uses lots of shared libraries with debug info that |
| takes large amounts of memory, you can decrease the GDB memory |
| footprint by preventing it from automatically loading the symbols |
| from shared libraries. To that end, type 'set auto-solib-add off' |
| before running the inferior, then load each library whose debug |
| symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a |
| regular expression that matches the libraries whose symbols you |
| want to be loaded. |
| |
| 'show auto-solib-add' |
| Display the current autoloading mode. |
| |
| To explicitly load shared library symbols, use the 'sharedlibrary' |
| command: |
| |
| 'info share REGEX' |
| 'info sharedlibrary REGEX' |
| Print the names of the shared libraries which are currently loaded |
| that match REGEX. If REGEX is omitted then print all shared |
| libraries that are loaded. |
| |
| 'info dll REGEX' |
| This is an alias of 'info sharedlibrary'. |
| |
| 'sharedlibrary REGEX' |
| 'share REGEX' |
| Load shared object library symbols for files matching a Unix |
| regular expression. As with files loaded automatically, it only |
| loads shared libraries required by your program for a core file or |
| after typing 'run'. If REGEX is omitted all shared libraries |
| required by your program are loaded. |
| |
| 'nosharedlibrary' |
| Unload all shared object library symbols. This discards all |
| symbols that have been loaded from all shared libraries. Symbols |
| from shared libraries that were loaded by explicit user requests |
| are not discarded. |
| |
| Sometimes you may wish that GDB stops and gives you control when any |
| of shared library events happen. The best way to do this is to use |
| 'catch load' and 'catch unload' (*note Set Catchpoints::). |
| |
| GDB also supports the the 'set stop-on-solib-events' command for |
| this. This command exists for historical reasons. It is less useful |
| than setting a catchpoint, because it does not allow for conditions or |
| commands as a catchpoint does. |
| |
| 'set stop-on-solib-events' |
| This command controls whether GDB should give you control when the |
| dynamic linker notifies it about some shared library event. The |
| most common event of interest is loading or unloading of a new |
| shared library. |
| |
| 'show stop-on-solib-events' |
| Show whether GDB stops and gives you control when shared library |
| events happen. |
| |
| Shared libraries are also supported in many cross or remote debugging |
| configurations. GDB needs to have access to the target's libraries; |
| this can be accomplished either by providing copies of the libraries on |
| the host system, or by asking GDB to automatically retrieve the |
| libraries from the target. If copies of the target libraries are |
| provided, they need to be the same as the target libraries, although the |
| copies on the target can be stripped as long as the copies on the host |
| are not. |
| |
| For remote debugging, you need to tell GDB where the target libraries |
| are, so that it can load the correct copies--otherwise, it may try to |
| load the host's libraries. GDB has two variables to specify the search |
| directories for target libraries. |
| |
| 'set sysroot PATH' |
| Use PATH as the system root for the program being debugged. Any |
| absolute shared library paths will be prefixed with PATH; many |
| runtime loaders store the absolute paths to the shared library in |
| the target program's memory. When starting processes remotely, and |
| when attaching to already-running processes (local or remote), |
| their executable filenames will be prefixed with PATH if reported |
| to GDB as absolute by the operating system. If you use 'set |
| sysroot' to find executables and shared libraries, they need to be |
| laid out in the same way that they are on the target, with e.g. a |
| '/bin', '/lib' and '/usr/lib' hierarchy under PATH. |
| |
| If PATH starts with the sequence 'target:' and the target system is |
| remote then GDB will retrieve the target binaries from the remote |
| system. This is only supported when using a remote target that |
| supports the 'remote get' command (*note Sending files to a remote |
| system: File Transfer.). The part of PATH following the initial |
| 'target:' (if present) is used as system root prefix on the remote |
| file system. If PATH starts with the sequence 'remote:' this is |
| converted to the sequence 'target:' by 'set sysroot'(1). If you |
| want to specify a local system root using a directory that happens |
| to be named 'target:' or 'remote:', you need to use some equivalent |
| variant of the name like './target:'. |
| |
| For targets with an MS-DOS based filesystem, such as MS-Windows and |
| SymbianOS, GDB tries prefixing a few variants of the target |
| absolute file name with PATH. But first, on Unix hosts, GDB |
| converts all backslash directory separators into forward slashes, |
| because the backslash is not a directory separator on Unix: |
| |
| c:\foo\bar.dll => c:/foo/bar.dll |
| |
| Then, GDB attempts prefixing the target file name with PATH, and |
| looks for the resulting file name in the host file system: |
| |
| c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll |
| |
| If that does not find the binary, GDB tries removing the ':' |
| character from the drive spec, both for convenience, and, for the |
| case of the host file system not supporting file names with colons: |
| |
| c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll |
| |
| This makes it possible to have a system root that mirrors a target |
| with more than one drive. E.g., you may want to setup your local |
| copies of the target system shared libraries like so (note 'c' vs |
| 'z'): |
| |
| /path/to/sysroot/c/sys/bin/foo.dll |
| /path/to/sysroot/c/sys/bin/bar.dll |
| /path/to/sysroot/z/sys/bin/bar.dll |
| |
| and point the system root at '/path/to/sysroot', so that GDB can |
| find the correct copies of both 'c:\sys\bin\foo.dll', and |
| 'z:\sys\bin\bar.dll'. |
| |
| If that still does not find the binary, GDB tries removing the |
| whole drive spec from the target file name: |
| |
| c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll |
| |
| This last lookup makes it possible to not care about the drive |
| name, if you don't want or need to. |
| |
| The 'set solib-absolute-prefix' command is an alias for 'set |
| sysroot'. |
| |
| You can set the default system root by using the configure-time |
| '--with-sysroot' option. If the system root is inside GDB's |
| configured binary prefix (set with '--prefix' or '--exec-prefix'), |
| then the default system root will be updated automatically if the |
| installed GDB is moved to a new location. |
| |
| 'show sysroot' |
| Display the current executable and shared library prefix. |
| |
| 'set solib-search-path PATH' |
| If this variable is set, PATH is a colon-separated list of |
| directories to search for shared libraries. 'solib-search-path' is |
| used after 'sysroot' fails to locate the library, or if the path to |
| the library is relative instead of absolute. If you want to use |
| 'solib-search-path' instead of 'sysroot', be sure to set 'sysroot' |
| to a nonexistent directory to prevent GDB from finding your host's |
| libraries. 'sysroot' is preferred; setting it to a nonexistent |
| directory may interfere with automatic loading of shared library |
| symbols. |
| |
| 'show solib-search-path' |
| Display the current shared library search path. |
| |
| 'set target-file-system-kind KIND' |
| Set assumed file system kind for target reported file names. |
| |
| Shared library file names as reported by the target system may not |
| make sense as is on the system GDB is running on. For example, |
| when remote debugging a target that has MS-DOS based file system |
| semantics, from a Unix host, the target may be reporting to GDB a |
| list of loaded shared libraries with file names such as |
| 'c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of |
| drive letters, so the 'c:\' prefix is not normally understood as |
| indicating an absolute file name, and neither is the backslash |
| normally considered a directory separator character. In that case, |
| the native file system would interpret this whole absolute file |
| name as a relative file name with no directory components. This |
| would make it impossible to point GDB at a copy of the remote |
| target's shared libraries on the host using 'set sysroot', and |
| impractical with 'set solib-search-path'. Setting |
| 'target-file-system-kind' to 'dos-based' tells GDB to interpret |
| such file names similarly to how the target would, and to map them |
| to file names valid on GDB's native file system semantics. The |
| value of KIND can be '"auto"', in addition to one of the supported |
| file system kinds. In that case, GDB tries to determine the |
| appropriate file system variant based on the current target's |
| operating system (*note Configuring the Current ABI: ABI.). The |
| supported file system settings are: |
| |
| 'unix' |
| Instruct GDB to assume the target file system is of Unix kind. |
| Only file names starting the forward slash ('/') character are |
| considered absolute, and the directory separator character is |
| also the forward slash. |
| |
| 'dos-based' |
| Instruct GDB to assume the target file system is DOS based. |
| File names starting with either a forward slash, or a drive |
| letter followed by a colon (e.g., 'c:'), are considered |
| absolute, and both the slash ('/') and the backslash ('\\') |
| characters are considered directory separators. |
| |
| 'auto' |
| Instruct GDB to use the file system kind associated with the |
| target operating system (*note Configuring the Current ABI: |
| ABI.). This is the default. |
| |
| When processing file names provided by the user, GDB frequently needs |
| to compare them to the file names recorded in the program's debug info. |
| Normally, GDB compares just the "base names" of the files as strings, |
| which is reasonably fast even for very large programs. (The base name |
| of a file is the last portion of its name, after stripping all the |
| leading directories.) This shortcut in comparison is based upon the |
| assumption that files cannot have more than one base name. This is |
| usually true, but references to files that use symlinks or similar |
| filesystem facilities violate that assumption. If your program records |
| files using such facilities, or if you provide file names to GDB using |
| symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct |
| GDB to completely canonicalize each pair of file names it needs to |
| compare. This will make file-name comparisons accurate, but at a price |
| of a significant slowdown. |
| |
| 'set basenames-may-differ' |
| Set whether a source file may have multiple base names. |
| |
| 'show basenames-may-differ' |
| Show whether a source file may have multiple base names. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Historically the functionality to retrieve binaries from the |
| remote system was provided by prefixing PATH with 'remote:' |
| |
| |
| File: gdb.info, Node: File Caching, Next: Separate Debug Files, Prev: Files, Up: GDB Files |
| |
| 18.2 File Caching |
| ================= |
| |
| To speed up file loading, and reduce memory usage, GDB will reuse the |
| 'bfd' objects used to track open files. *Note BFD: (bfd)Top. The |
| following commands allow visibility and control of the caching behavior. |
| |
| 'maint info bfds' |
| This prints information about each 'bfd' object that is known to |
| GDB. |
| |
| 'maint set bfd-sharing' |
| 'maint show bfd-sharing' |
| Control whether 'bfd' objects can be shared. When sharing is |
| enabled GDB reuses already open 'bfd' objects rather than reopening |
| the same file. Turning sharing off does not cause already shared |
| 'bfd' objects to be unshared, but all future files that are opened |
| will create a new 'bfd' object. Similarly, re-enabling sharing |
| does not cause multiple existing 'bfd' objects to be collapsed into |
| a single shared 'bfd' object. |
| |
| 'set debug bfd-cache LEVEL' |
| Turns on debugging of the bfd cache, setting the level to LEVEL. |
| |
| 'show debug bfd-cache' |
| Show the current debugging level of the bfd cache. |
| |
| |
| File: gdb.info, Node: Separate Debug Files, Next: MiniDebugInfo, Prev: File Caching, Up: GDB Files |
| |
| 18.3 Debugging Information in Separate Files |
| ============================================ |
| |
| GDB allows you to put a program's debugging information in a file |
| separate from the executable itself, in a way that allows GDB to find |
| and load the debugging information automatically. Since debugging |
| information can be very large--sometimes larger than the executable code |
| itself--some systems distribute debugging information for their |
| executables in separate files, which users can install only when they |
| need to debug a problem. |
| |
| GDB supports two ways of specifying the separate debug info file: |
| |
| * The executable contains a "debug link" that specifies the name of |
| the separate debug info file. The separate debug file's name is |
| usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the |
| corresponding executable file without leading directories (e.g., |
| 'ls.debug' for '/usr/bin/ls'). In addition, the debug link |
| specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the |
| debug file, which GDB uses to validate that the executable and the |
| debug file came from the same build. |
| |
| * The executable contains a "build ID", a unique bit string that is |
| also present in the corresponding debug info file. (This is |
| supported only on some operating systems, when using the ELF or PE |
| file formats for binary files and the GNU Binutils.) For more |
| details about this feature, see the description of the '--build-id' |
| command-line option in *note Command Line Options: (ld)Options. |
| The debug info file's name is not specified explicitly by the build |
| ID, but can be computed from the build ID, see below. |
| |
| Depending on the way the debug info file is specified, GDB uses two |
| different methods of looking for the debug file: |
| |
| * For the "debug link" method, GDB looks up the named file in the |
| directory of the executable file, then in a subdirectory of that |
| directory named '.debug', and finally under each one of the global |
| debug directories, in a subdirectory whose name is identical to the |
| leading directories of the executable's absolute file name. (On |
| MS-Windows/MS-DOS, the drive letter of the executable's leading |
| directories is converted to a one-letter subdirectory, i.e. |
| 'd:/usr/bin/' is converted to '/d/usr/bin/', because Windows |
| filesystems disallow colons in file names.) |
| |
| * For the "build ID" method, GDB looks in the '.build-id' |
| subdirectory of each one of the global debug directories for a file |
| named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters |
| of the build ID bit string, and NNNNNNNN are the rest of the bit |
| string. (Real build ID strings are 32 or more hex characters, not |
| 10.) |
| |
| So, for example, suppose you ask GDB to debug '/usr/bin/ls', which |
| has a debug link that specifies the file 'ls.debug', and a build ID |
| whose value in hex is 'abcdef1234'. If the list of the global debug |
| directories includes '/usr/lib/debug', then GDB will look for the |
| following debug information files, in the indicated order: |
| |
| - '/usr/lib/debug/.build-id/ab/cdef1234.debug' |
| - '/usr/bin/ls.debug' |
| - '/usr/bin/.debug/ls.debug' |
| - '/usr/lib/debug/usr/bin/ls.debug'. |
| |
| Global debugging info directories default to what is set by GDB |
| configure option '--with-separate-debug-dir'. During GDB run you can |
| also set the global debugging info directories, and view the list GDB is |
| currently using. |
| |
| 'set debug-file-directory DIRECTORIES' |
| Set the directories which GDB searches for separate debugging |
| information files to DIRECTORY. Multiple path components can be |
| set concatenating them by a path separator. |
| |
| 'show debug-file-directory' |
| Show the directories GDB searches for separate debugging |
| information files. |
| |
| A debug link is a special section of the executable file named |
| '.gnu_debuglink'. The section must contain: |
| |
| * A filename, with any leading directory components removed, followed |
| by a zero byte, |
| * zero to three bytes of padding, as needed to reach the next |
| four-byte boundary within the section, and |
| * a four-byte CRC checksum, stored in the same endianness used for |
| the executable file itself. The checksum is computed on the |
| debugging information file's full contents by the function given |
| below, passing zero as the CRC argument. |
| |
| Any executable file format can carry a debug link, as long as it can |
| contain a section named '.gnu_debuglink' with the contents described |
| above. |
| |
| The build ID is a special section in the executable file (and in |
| other ELF binary files that GDB may consider). This section is often |
| named '.note.gnu.build-id', but that name is not mandatory. It contains |
| unique identification for the built files--the ID remains the same |
| across multiple builds of the same build tree. The default algorithm |
| SHA1 produces 160 bits (40 hexadecimal characters) of the content for |
| the build ID string. The same section with an identical value is |
| present in the original built binary with symbols, in its stripped |
| variant, and in the separate debugging information file. |
| |
| The debugging information file itself should be an ordinary |
| executable, containing a full set of linker symbols, sections, and |
| debugging information. The sections of the debugging information file |
| should have the same names, addresses, and sizes as the original file, |
| but they need not contain any data--much like a '.bss' section in an |
| ordinary executable. |
| |
| The GNU binary utilities (Binutils) package includes the 'objcopy' |
| utility that can produce the separated executable / debugging |
| information file pairs using the following commands: |
| |
| objcopy --only-keep-debug foo foo.debug |
| strip -g foo |
| |
| These commands remove the debugging information from the executable file |
| 'foo' and place it in the file 'foo.debug'. You can use the first, |
| second or both methods to link the two files: |
| |
| * The debug link method needs the following additional command to |
| also leave behind a debug link in 'foo': |
| |
| objcopy --add-gnu-debuglink=foo.debug foo |
| |
| Ulrich Drepper's 'elfutils' package, starting with version 0.53, |
| contains a version of the 'strip' command such that the command |
| 'strip foo -f foo.debug' has the same functionality as the two |
| 'objcopy' commands and the 'ln -s' command above, together. |
| |
| * Build ID gets embedded into the main executable using 'ld |
| --build-id' or the GCC counterpart 'gcc -Wl,--build-id'. Build ID |
| support plus compatibility fixes for debug files separation are |
| present in GNU binary utilities (Binutils) package since version |
| 2.18. |
| |
| |
| The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 |
| using the polynomial: |
| |
| x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11} |
| + x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 |
| |
| The function is computed byte at a time, taking the least significant |
| bit of each byte first. The initial pattern '0xffffffff' is used, to |
| ensure leading zeros affect the CRC and the final result is inverted to |
| ensure trailing zeros also affect the CRC. |
| |
| _Note:_ This is the same CRC polynomial as used in handling the |
| "Remote Serial Protocol" 'qCRC' packet (*note qCRC packet::). However |
| in the case of the Remote Serial Protocol, the CRC is computed _most_ |
| significant bit first, and the result is not inverted, so trailing zeros |
| have no effect on the CRC value. |
| |
| To complete the description, we show below the code of the function |
| which produces the CRC used in '.gnu_debuglink'. Inverting the |
| initially supplied 'crc' argument means that an initial call to this |
| function passing in zero will start computing the CRC using |
| '0xffffffff'. |
| |
| unsigned long |
| gnu_debuglink_crc32 (unsigned long crc, |
| unsigned char *buf, size_t len) |
| { |
| static const unsigned long crc32_table[256] = |
| { |
| 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, |
| 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, |
| 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, |
| 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, |
| 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, |
| 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, |
| 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, |
| 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, |
| 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, |
| 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, |
| 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, |
| 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, |
| 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, |
| 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, |
| 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, |
| 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, |
| 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, |
| 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, |
| 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, |
| 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, |
| 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, |
| 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, |
| 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, |
| 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, |
| 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, |
| 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, |
| 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, |
| 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, |
| 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, |
| 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, |
| 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, |
| 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, |
| 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, |
| 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, |
| 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, |
| 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, |
| 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, |
| 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, |
| 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, |
| 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, |
| 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, |
| 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, |
| 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, |
| 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, |
| 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, |
| 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, |
| 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, |
| 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, |
| 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, |
| 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, |
| 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, |
| 0x2d02ef8d |
| }; |
| unsigned char *end; |
| |
| crc = ~crc & 0xffffffff; |
| for (end = buf + len; buf < end; ++buf) |
| crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); |
| return ~crc & 0xffffffff; |
| } |
| |
| This computation does not apply to the "build ID" method. |
| |
| |
| File: gdb.info, Node: MiniDebugInfo, Next: Index Files, Prev: Separate Debug Files, Up: GDB Files |
| |
| 18.4 Debugging information in a special section |
| =============================================== |
| |
| Some systems ship pre-built executables and libraries that have a |
| special '.gnu_debugdata' section. This feature is called |
| "MiniDebugInfo". This section holds an LZMA-compressed object and is |
| used to supply extra symbols for backtraces. |
| |
| The intent of this section is to provide extra minimal debugging |
| information for use in simple backtraces. It is not intended to be a |
| replacement for full separate debugging information (*note Separate |
| Debug Files::). The example below shows the intended use; however, GDB |
| does not currently put restrictions on what sort of debugging |
| information might be included in the section. |
| |
| GDB has support for this extension. If the section exists, then it |
| is used provided that no other source of debugging information can be |
| found, and that GDB was configured with LZMA support. |
| |
| This section can be easily created using 'objcopy' and other standard |
| utilities: |
| |
| # Extract the dynamic symbols from the main binary, there is no need |
| # to also have these in the normal symbol table. |
| nm -D BINARY --format=posix --defined-only \ |
| | awk '{ print $1 }' | sort > dynsyms |
| |
| # Extract all the text (i.e. function) symbols from the debuginfo. |
| # (Note that we actually also accept "D" symbols, for the benefit |
| # of platforms like PowerPC64 that use function descriptors.) |
| nm BINARY --format=posix --defined-only \ |
| | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \ |
| | sort > funcsyms |
| |
| # Keep all the function symbols not already in the dynamic symbol |
| # table. |
| comm -13 dynsyms funcsyms > keep_symbols |
| |
| # Separate full debug info into debug binary. |
| objcopy --only-keep-debug BINARY debug |
| |
| # Copy the full debuginfo, keeping only a minimal set of symbols and |
| # removing some unnecessary sections. |
| objcopy -S --remove-section .gdb_index --remove-section .comment \ |
| --keep-symbols=keep_symbols debug mini_debuginfo |
| |
| # Drop the full debug info from the original binary. |
| strip --strip-all -R .comment BINARY |
| |
| # Inject the compressed data into the .gnu_debugdata section of the |
| # original binary. |
| xz mini_debuginfo |
| objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY |
| |
| |
| File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: MiniDebugInfo, Up: GDB Files |
| |
| 18.5 Index Files Speed Up GDB |
| ============================= |
| |
| When GDB finds a symbol file, it scans the symbols in the file in order |
| to construct an internal symbol table. This lets most GDB operations |
| work quickly--at the cost of a delay early on. For large programs, this |
| delay can be quite lengthy, so GDB provides a way to build an index, |
| which speeds up startup. |
| |
| For convenience, GDB comes with a program, 'gdb-add-index', which can |
| be used to add the index to a symbol file. It takes the symbol file as |
| its only argument: |
| |
| $ gdb-add-index symfile |
| |
| *Note gdb-add-index::. |
| |
| It is also possible to do the work manually. Here is what |
| 'gdb-add-index' does behind the curtains. |
| |
| The index is stored as a section in the symbol file. GDB can write |
| the index to a file, then you can put it into the symbol file using |
| 'objcopy'. |
| |
| To create an index file, use the 'save gdb-index' command: |
| |
| 'save gdb-index [-dwarf-5] DIRECTORY' |
| Create index files for all symbol files currently known by GDB. |
| For each known SYMBOL-FILE, this command by default creates it |
| produces a single file 'SYMBOL-FILE.gdb-index'. If you invoke this |
| command with the '-dwarf-5' option, it produces 2 files: |
| 'SYMBOL-FILE.debug_names' and 'SYMBOL-FILE.debug_str'. The files |
| are created in the given DIRECTORY. |
| |
| Once you have created an index file you can merge it into your symbol |
| file, here named 'symfile', using 'objcopy': |
| |
| $ objcopy --add-section .gdb_index=symfile.gdb-index \ |
| --set-section-flags .gdb_index=readonly symfile symfile |
| |
| Or for '-dwarf-5': |
| |
| $ objcopy --dump-section .debug_str=symfile.debug_str.new symfile |
| $ cat symfile.debug_str >>symfile.debug_str.new |
| $ objcopy --add-section .debug_names=symfile.gdb-index \ |
| --set-section-flags .debug_names=readonly \ |
| --update-section .debug_str=symfile.debug_str.new symfile symfile |
| |
| GDB will normally ignore older versions of '.gdb_index' sections that |
| have been deprecated. Usually they are deprecated because they are |
| missing a new feature or have performance issues. To tell GDB to use a |
| deprecated index section anyway specify 'set |
| use-deprecated-index-sections on'. The default is 'off'. This can |
| speed up startup, but may result in some functionality being lost. |
| *Note Index Section Format::. |
| |
| _Warning:_ Setting 'use-deprecated-index-sections' to 'on' must be |
| done before gdb reads the file. The following will not work: |
| |
| $ gdb -ex "set use-deprecated-index-sections on" <program> |
| |
| Instead you must do, for example, |
| |
| $ gdb -iex "set use-deprecated-index-sections on" <program> |
| |
| There are currently some limitation on indices. They only work when |
| using DWARF debugging information, not stabs. And, only the '-dwarf-5' |
| index works for programs using Ada. |
| |
| 18.5.1 Automatic symbol index cache |
| ----------------------------------- |
| |
| It is possible for GDB to automatically save a copy of this index in a |
| cache on disk and retrieve it from there when loading the same binary in |
| the future. This feature can be turned on with 'set index-cache on'. |
| The following commands can be used to tweak the behavior of the index |
| cache. |
| |
| 'set index-cache on' |
| 'set index-cache off' |
| Enable or disable the use of the symbol index cache. |
| |
| 'set index-cache directory DIRECTORY' |
| 'show index-cache directory' |
| Set/show the directory where index files will be saved. |
| |
| The default value for this directory depends on the host platform. |
| On most systems, the index is cached in the 'gdb' subdirectory of |
| the directory pointed to by the 'XDG_CACHE_HOME' environment |
| variable, if it is defined, else in the '.cache/gdb' subdirectory |
| of your home directory. However, on some systems, the default may |
| differ according to local convention. |
| |
| There is no limit on the disk space used by index cache. It is |
| perfectly safe to delete the content of that directory to free up |
| disk space. |
| |
| 'show index-cache stats' |
| Print the number of cache hits and misses since the launch of GDB. |
| |
| |
| File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files |
| |
| 18.6 Errors Reading Symbol Files |
| ================================ |
| |
| While reading a symbol file, GDB occasionally encounters problems, such |
| as symbol types it does not recognize, or known bugs in compiler output. |
| By default, GDB does not notify you of such problems, since they are |
| relatively common and primarily of interest to people debugging |
| compilers. If you are interested in seeing information about |
| ill-constructed symbol tables, you can either ask GDB to print only one |
| message about each such type of problem, no matter how many times the |
| problem occurs; or you can ask GDB to print more messages, to see how |
| many times the problems occur, with the 'set complaints' command (*note |
| Optional Warnings and Messages: Messages/Warnings.). |
| |
| The messages currently printed, and their meanings, include: |
| |
| 'inner block not inside outer block in SYMBOL' |
| |
| The symbol information shows where symbol scopes begin and end |
| (such as at the start of a function or a block of statements). |
| This error indicates that an inner scope block is not fully |
| contained in its outer scope blocks. |
| |
| GDB circumvents the problem by treating the inner block as if it |
| had the same scope as the outer block. In the error message, |
| SYMBOL may be shown as "'(don't know)'" if the outer block is not a |
| function. |
| |
| 'block at ADDRESS out of order' |
| |
| The symbol information for symbol scope blocks should occur in |
| order of increasing addresses. This error indicates that it does |
| not do so. |
| |
| GDB does not circumvent this problem, and has trouble locating |
| symbols in the source file whose symbols it is reading. (You can |
| often determine what source file is affected by specifying 'set |
| verbose on'. *Note Optional Warnings and Messages: |
| Messages/Warnings.) |
| |
| 'bad block start address patched' |
| |
| The symbol information for a symbol scope block has a start address |
| smaller than the address of the preceding source line. This is |
| known to occur in the SunOS 4.1.1 (and earlier) C compiler. |
| |
| GDB circumvents the problem by treating the symbol scope block as |
| starting on the previous source line. |
| |
| 'bad string table offset in symbol N' |
| |
| Symbol number N contains a pointer into the string table which is |
| larger than the size of the string table. |
| |
| GDB circumvents the problem by considering the symbol to have the |
| name 'foo', which may cause other problems if many symbols end up |
| with this name. |
| |
| 'unknown symbol type 0xNN' |
| |
| The symbol information contains new data types that GDB does not |
| yet know how to read. '0xNN' is the symbol type of the |
| uncomprehended information, in hexadecimal. |
| |
| GDB circumvents the error by ignoring this symbol information. |
| This usually allows you to debug your program, though certain |
| symbols are not accessible. If you encounter such a problem and |
| feel like debugging it, you can debug 'gdb' with itself, breakpoint |
| on 'complain', then go up to the function 'read_dbx_symtab' and |
| examine '*bufp' to see the symbol. |
| |
| 'stub type has NULL name' |
| |
| GDB could not find the full definition for a struct or class. |
| |
| 'const/volatile indicator missing (ok if using g++ v1.x), got...' |
| The symbol information for a C++ member function is missing some |
| information that recent versions of the compiler should have output |
| for it. |
| |
| 'info mismatch between compiler and debugger' |
| |
| GDB could not parse a type specification output by the compiler. |
| |
| |
| File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files |
| |
| 18.7 GDB Data Files |
| =================== |
| |
| GDB will sometimes read an auxiliary data file. These files are kept in |
| a directory known as the "data directory". |
| |
| You can set the data directory's name, and view the name GDB is |
| currently using. |
| |
| 'set data-directory DIRECTORY' |
| Set the directory which GDB searches for auxiliary data files to |
| DIRECTORY. |
| |
| 'show data-directory' |
| Show the directory GDB searches for auxiliary data files. |
| |
| You can set the default data directory by using the configure-time |
| '--with-gdb-datadir' option. If the data directory is inside GDB's |
| configured binary prefix (set with '--prefix' or '--exec-prefix'), then |
| the default data directory will be updated automatically if the |
| installed GDB is moved to a new location. |
| |
| The data directory may also be specified with the '--data-directory' |
| command line option. *Note Mode Options::. |
| |
| |
| File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top |
| |
| 19 Specifying a Debugging Target |
| ******************************** |
| |
| A "target" is the execution environment occupied by your program. |
| |
| Often, GDB runs in the same host environment as your program; in that |
| case, the debugging target is specified as a side effect when you use |
| the 'file' or 'core' commands. When you need more flexibility--for |
| example, running GDB on a physically separate host, or controlling a |
| standalone system over a serial port or a realtime system over a TCP/IP |
| connection--you can use the 'target' command to specify one of the |
| target types configured for GDB (*note Commands for Managing Targets: |
| Target Commands.). |
| |
| It is possible to build GDB for several different "target |
| architectures". When GDB is built like that, you can choose one of the |
| available architectures with the 'set architecture' command. |
| |
| 'set architecture ARCH' |
| This command sets the current target architecture to ARCH. The |
| value of ARCH can be '"auto"', in addition to one of the supported |
| architectures. |
| |
| 'show architecture' |
| Show the current target architecture. |
| |
| 'set processor' |
| 'processor' |
| These are alias commands for, respectively, 'set architecture' and |
| 'show architecture'. |
| |
| * Menu: |
| |
| * Active Targets:: Active targets |
| * Target Commands:: Commands for managing targets |
| * Byte Order:: Choosing target byte order |
| |
| |
| File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets |
| |
| 19.1 Active Targets |
| =================== |
| |
| There are multiple classes of targets such as: processes, executable |
| files or recording sessions. Core files belong to the process class, |
| making core file and process mutually exclusive. Otherwise, GDB can |
| work concurrently on multiple active targets, one in each class. This |
| allows you to (for example) start a process and inspect its activity, |
| while still having access to the executable file after the process |
| finishes. Or if you start process recording (*note Reverse Execution::) |
| and 'reverse-step' there, you are presented a virtual layer of the |
| recording target, while the process target remains stopped at the |
| chronologically last point of the process execution. |
| |
| Use the 'core-file' and 'exec-file' commands to select a new core |
| file or executable target (*note Commands to Specify Files: Files.). To |
| specify as a target a process that is already running, use the 'attach' |
| command (*note Debugging an Already-running Process: Attach.). |
| |
| |
| File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets |
| |
| 19.2 Commands for Managing Targets |
| ================================== |
| |
| 'target TYPE PARAMETERS' |
| Connects the GDB host environment to a target machine or process. |
| A target is typically a protocol for talking to debugging |
| facilities. You use the argument TYPE to specify the type or |
| protocol of the target machine. |
| |
| Further PARAMETERS are interpreted by the target protocol, but |
| typically include things like device names or host names to connect |
| with, process numbers, and baud rates. |
| |
| The 'target' command does not repeat if you press <RET> again after |
| executing the command. |
| |
| 'help target' |
| Displays the names of all targets available. To display targets |
| currently selected, use either 'info target' or 'info files' (*note |
| Commands to Specify Files: Files.). |
| |
| 'help target NAME' |
| Describe a particular target, including any parameters necessary to |
| select it. |
| |
| 'set gnutarget ARGS' |
| GDB uses its own library BFD to read your files. GDB knows whether |
| it is reading an "executable", a "core", or a ".o" file; however, |
| you can specify the file format with the 'set gnutarget' command. |
| Unlike most 'target' commands, with 'gnutarget' the 'target' refers |
| to a program, not a machine. |
| |
| _Warning:_ To specify a file format with 'set gnutarget', you |
| must know the actual BFD name. |
| |
| *Note Commands to Specify Files: Files. |
| |
| 'show gnutarget' |
| Use the 'show gnutarget' command to display what file format |
| 'gnutarget' is set to read. If you have not set 'gnutarget', GDB |
| will determine the file format for each file automatically, and |
| 'show gnutarget' displays 'The current BFD target is "auto"'. |
| |
| Here are some common targets (available, or not, depending on the GDB |
| configuration): |
| |
| 'target exec PROGRAM' |
| An executable file. 'target exec PROGRAM' is the same as |
| 'exec-file PROGRAM'. |
| |
| 'target core FILENAME' |
| A core dump file. 'target core FILENAME' is the same as 'core-file |
| FILENAME'. |
| |
| 'target remote MEDIUM' |
| A remote system connected to GDB via a serial line or network |
| connection. This command tells GDB to use its own remote protocol |
| over MEDIUM for debugging. *Note Remote Debugging::. |
| |
| For example, if you have a board connected to '/dev/ttya' on the |
| machine running GDB, you could say: |
| |
| target remote /dev/ttya |
| |
| 'target remote' supports the 'load' command. This is only useful |
| if you have some other way of getting the stub to the target |
| system, and you can put it somewhere in memory where it won't get |
| clobbered by the download. |
| |
| 'target sim [SIMARGS] ...' |
| Builtin CPU simulator. GDB includes simulators for most |
| architectures. In general, |
| target sim |
| load |
| run |
| works; however, you cannot assume that a specific memory map, |
| device drivers, or even basic I/O is available, although some |
| simulators do provide these. For info about any processor-specific |
| simulator details, see the appropriate section in *note Embedded |
| Processors: Embedded Processors. |
| |
| 'target native' |
| Setup for local/native process debugging. Useful to make the 'run' |
| command spawn native processes (likewise 'attach', etc.) even when |
| 'set auto-connect-native-target' is 'off' (*note set |
| auto-connect-native-target::). |
| |
| Different targets are available on different configurations of GDB; |
| your configuration may have more or fewer targets. |
| |
| Many remote targets require you to download the executable's code |
| once you've successfully established a connection. You may wish to |
| control various aspects of this process. |
| |
| 'set hash' |
| This command controls whether a hash mark '#' is displayed while |
| downloading a file to the remote monitor. If on, a hash mark is |
| displayed after each S-record is successfully downloaded to the |
| monitor. |
| |
| 'show hash' |
| Show the current status of displaying the hash mark. |
| |
| 'set debug monitor' |
| Enable or disable display of communications messages between GDB |
| and the remote monitor. |
| |
| 'show debug monitor' |
| Show the current status of displaying communications between GDB |
| and the remote monitor. |
| |
| 'load FILENAME OFFSET' |
| Depending on what remote debugging facilities are configured into |
| GDB, the 'load' command may be available. Where it exists, it is |
| meant to make FILENAME (an executable) available for debugging on |
| the remote system--by downloading, or dynamic linking, for example. |
| 'load' also records the FILENAME symbol table in GDB, like the |
| 'add-symbol-file' command. |
| |
| If your GDB does not have a 'load' command, attempting to execute |
| it gets the error message "'You can't do that when your target is |
| ...'" |
| |
| The file is loaded at whatever address is specified in the |
| executable. For some object file formats, you can specify the load |
| address when you link the program; for other formats, like a.out, |
| the object file format specifies a fixed address. |
| |
| It is also possible to tell GDB to load the executable file at a |
| specific offset described by the optional argument OFFSET. When |
| OFFSET is provided, FILENAME must also be provided. |
| |
| Depending on the remote side capabilities, GDB may be able to load |
| programs into flash memory. |
| |
| 'load' does not repeat if you press <RET> again after using it. |
| |
| 'flash-erase' |
| |
| Erases all known flash memory regions on the target. |
| |
| |
| File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets |
| |
| 19.3 Choosing Target Byte Order |
| =============================== |
| |
| Some types of processors, such as the MIPS, PowerPC, and Renesas SH, |
| offer the ability to run either big-endian or little-endian byte orders. |
| Usually the executable or symbol will include a bit to designate the |
| endian-ness, and you will not need to worry about which to use. |
| However, you may still find it useful to adjust GDB's idea of processor |
| endian-ness manually. |
| |
| 'set endian big' |
| Instruct GDB to assume the target is big-endian. |
| |
| 'set endian little' |
| Instruct GDB to assume the target is little-endian. |
| |
| 'set endian auto' |
| Instruct GDB to use the byte order associated with the executable. |
| |
| 'show endian' |
| Display GDB's current idea of the target byte order. |
| |
| If the 'set endian auto' mode is in effect and no executable has been |
| selected, then the endianness used is the last one chosen either by one |
| of the 'set endian big' and 'set endian little' commands or by inferring |
| from the last executable used. If no endianness has been previously |
| chosen, then the default for this mode is inferred from the target GDB |
| has been built for, and is 'little' if the name of the target CPU has an |
| 'el' suffix and 'big' otherwise. |
| |
| Note that these commands merely adjust interpretation of symbolic |
| data on the host, and that they have absolutely no effect on the target |
| system. |
| |
| |
| File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top |
| |
| 20 Debugging Remote Programs |
| **************************** |
| |
| If you are trying to debug a program running on a machine that cannot |
| run GDB in the usual way, it is often useful to use remote debugging. |
| For example, you might use remote debugging on an operating system |
| kernel, or on a small system which does not have a general purpose |
| operating system powerful enough to run a full-featured debugger. |
| |
| Some configurations of GDB have special serial or TCP/IP interfaces |
| to make this work with particular debugging targets. In addition, GDB |
| comes with a generic serial protocol (specific to GDB, but not specific |
| to any particular target system) which you can use if you write the |
| remote stubs--the code that runs on the remote system to communicate |
| with GDB. |
| |
| Other remote targets may be available in your configuration of GDB; |
| use 'help target' to list them. |
| |
| * Menu: |
| |
| * Connecting:: Connecting to a remote target |
| * File Transfer:: Sending files to a remote system |
| * Server:: Using the gdbserver program |
| * Remote Configuration:: Remote configuration |
| * Remote Stub:: Implementing a remote stub |
| |
| |
| File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging |
| |
| 20.1 Connecting to a Remote Target |
| ================================== |
| |
| This section describes how to connect to a remote target, including the |
| types of connections and their differences, how to set up executable and |
| symbol files on the host and target, and the commands used for |
| connecting to and disconnecting from the remote target. |
| |
| 20.1.1 Types of Remote Connections |
| ---------------------------------- |
| |
| GDB supports two types of remote connections, 'target remote' mode and |
| 'target extended-remote' mode. Note that many remote targets support |
| only 'target remote' mode. There are several major differences between |
| the two types of connections, enumerated here: |
| |
| Result of detach or program exit |
| *With target remote mode:* When the debugged program exits or you |
| detach from it, GDB disconnects from the target. When using |
| 'gdbserver', 'gdbserver' will exit. |
| |
| *With target extended-remote mode:* When the debugged program exits |
| or you detach from it, GDB remains connected to the target, even |
| though no program is running. You can rerun the program, attach to |
| a running program, or use 'monitor' commands specific to the |
| target. |
| |
| When using 'gdbserver' in this case, it does not exit unless it was |
| invoked using the '--once' option. If the '--once' option was not |
| used, you can ask 'gdbserver' to exit using the 'monitor exit' |
| command (*note Monitor Commands for gdbserver::). |
| |
| Specifying the program to debug |
| For both connection types you use the 'file' command to specify the |
| program on the host system. If you are using 'gdbserver' there are |
| some differences in how to specify the location of the program on |
| the target. |
| |
| *With target remote mode:* You must either specify the program to |
| debug on the 'gdbserver' command line or use the '--attach' option |
| (*note Attaching to a Running Program: Attaching to a program.). |
| |
| *With target extended-remote mode:* You may specify the program to |
| debug on the 'gdbserver' command line, or you can load the program |
| or attach to it using GDB commands after connecting to 'gdbserver'. |
| |
| You can start 'gdbserver' without supplying an initial command to |
| run or process ID to attach. To do this, use the '--multi' command |
| line option. Then you can connect using 'target extended-remote' |
| and start the program you want to debug (see below for details on |
| using the 'run' command in this scenario). Note that the |
| conditions under which 'gdbserver' terminates depend on how GDB |
| connects to it ('target remote' or 'target extended-remote'). The |
| '--multi' option to 'gdbserver' has no influence on that. |
| |
| The 'run' command |
| *With target remote mode:* The 'run' command is not supported. |
| Once a connection has been established, you can use all the usual |
| GDB commands to examine and change data. The remote program is |
| already running, so you can use commands like 'step' and |
| 'continue'. |
| |
| *With target extended-remote mode:* The 'run' command is supported. |
| The 'run' command uses the value set by 'set remote exec-file' |
| (*note set remote exec-file::) to select the program to run. |
| Command line arguments are supported, except for wildcard expansion |
| and I/O redirection (*note Arguments::). |
| |
| If you specify the program to debug on the command line, then the |
| 'run' command is not required to start execution, and you can |
| resume using commands like 'step' and 'continue' as with 'target |
| remote' mode. |
| |
| Attaching |
| *With target remote mode:* The GDB command 'attach' is not |
| supported. To attach to a running program using 'gdbserver', you |
| must use the '--attach' option (*note Running gdbserver::). |
| |
| *With target extended-remote mode:* To attach to a running program, |
| you may use the 'attach' command after the connection has been |
| established. If you are using 'gdbserver', you may also invoke |
| 'gdbserver' using the '--attach' option (*note Running |
| gdbserver::). |
| |
| 20.1.2 Host and Target Files |
| ---------------------------- |
| |
| GDB, running on the host, needs access to symbol and debugging |
| information for your program running on the target. This requires |
| access to an unstripped copy of your program, and possibly any |
| associated symbol files. Note that this section applies equally to both |
| 'target remote' mode and 'target extended-remote' mode. |
| |
| Some remote targets (*note qXfer executable filename read::, and |
| *note Host I/O Packets::) allow GDB to access program files over the |
| same connection used to communicate with GDB. With such a target, if |
| the remote program is unstripped, the only command you need is 'target |
| remote' (or 'target extended-remote'). |
| |
| If the remote program is stripped, or the target does not support |
| remote program file access, start up GDB using the name of the local |
| unstripped copy of your program as the first argument, or use the 'file' |
| command. Use 'set sysroot' to specify the location (on the host) of |
| target libraries (unless your GDB was compiled with the correct sysroot |
| using '--with-sysroot'). Alternatively, you may use 'set |
| solib-search-path' to specify how GDB locates target libraries. |
| |
| The symbol file and target libraries must exactly match the |
| executable and libraries on the target, with one exception: the files on |
| the host system should not be stripped, even if the files on the target |
| system are. Mismatched or missing files will lead to confusing results |
| during debugging. On GNU/Linux targets, mismatched or missing files may |
| also prevent 'gdbserver' from debugging multi-threaded programs. |
| |
| 20.1.3 Remote Connection Commands |
| --------------------------------- |
| |
| GDB can communicate with the target over a serial line, a local Unix |
| domain socket, or over an IP network using TCP or UDP. In each case, |
| GDB uses the same protocol for debugging your program; only the medium |
| carrying the debugging packets varies. The 'target remote' and 'target |
| extended-remote' commands establish a connection to the target. Both |
| commands accept the same arguments, which indicate the medium to use: |
| |
| 'target remote SERIAL-DEVICE' |
| 'target extended-remote SERIAL-DEVICE' |
| Use SERIAL-DEVICE to communicate with the target. For example, to |
| use a serial line connected to the device named '/dev/ttyb': |
| |
| target remote /dev/ttyb |
| |
| If you're using a serial line, you may want to give GDB the |
| '--baud' option, or use the 'set serial baud' command (*note set |
| serial baud: Remote Configuration.) before the 'target' command. |
| |
| 'target remote LOCAL-SOCKET' |
| 'target extended-remote LOCAL-SOCKET' |
| Use LOCAL-SOCKET to communicate with the target. For example, to |
| use a local Unix domain socket bound to the file system entry |
| '/tmp/gdb-socket0': |
| |
| target remote /tmp/gdb-socket0 |
| |
| Note that this command has the same form as the command to connect |
| to a serial line. GDB will automatically determine which kind of |
| file you have specified and will make the appropriate kind of |
| connection. This feature is not available if the host system does |
| not support Unix domain sockets. |
| |
| 'target remote HOST:PORT' |
| 'target remote [HOST]:PORT' |
| 'target remote tcp:HOST:PORT' |
| 'target remote tcp:[HOST]:PORT' |
| 'target remote tcp4:HOST:PORT' |
| 'target remote tcp6:HOST:PORT' |
| 'target remote tcp6:[HOST]:PORT' |
| 'target extended-remote HOST:PORT' |
| 'target extended-remote [HOST]:PORT' |
| 'target extended-remote tcp:HOST:PORT' |
| 'target extended-remote tcp:[HOST]:PORT' |
| 'target extended-remote tcp4:HOST:PORT' |
| 'target extended-remote tcp6:HOST:PORT' |
| 'target extended-remote tcp6:[HOST]:PORT' |
| Debug using a TCP connection to PORT on HOST. The HOST may be |
| either a host name, a numeric IPv4 address, or a numeric IPv6 |
| address (with or without the square brackets to separate the |
| address from the port); PORT must be a decimal number. The HOST |
| could be the target machine itself, if it is directly connected to |
| the net, or it might be a terminal server which in turn has a |
| serial line to the target. |
| |
| For example, to connect to port 2828 on a terminal server named |
| 'manyfarms': |
| |
| target remote manyfarms:2828 |
| |
| To connect to port 2828 on a terminal server whose address is |
| '2001:0db8:85a3:0000:0000:8a2e:0370:7334', you can either use the |
| square bracket syntax: |
| |
| target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 |
| |
| or explicitly specify the IPv6 protocol: |
| |
| target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 |
| |
| This last example may be confusing to the reader, because there is |
| no visible separation between the hostname and the port number. |
| Therefore, we recommend the user to provide IPv6 addresses using |
| square brackets for clarity. However, it is important to mention |
| that for GDB there is no ambiguity: the number after the last colon |
| is considered to be the port number. |
| |
| If your remote target is actually running on the same machine as |
| your debugger session (e.g. a simulator for your target running on |
| the same host), you can omit the hostname. For example, to connect |
| to port 1234 on your local machine: |
| |
| target remote :1234 |
| |
| Note that the colon is still required here. |
| |
| 'target remote udp:HOST:PORT' |
| 'target remote udp:[HOST]:PORT' |
| 'target remote udp4:HOST:PORT' |
| 'target remote udp6:[HOST]:PORT' |
| 'target extended-remote udp:HOST:PORT' |
| 'target extended-remote udp:HOST:PORT' |
| 'target extended-remote udp:[HOST]:PORT' |
| 'target extended-remote udp4:HOST:PORT' |
| 'target extended-remote udp6:HOST:PORT' |
| 'target extended-remote udp6:[HOST]:PORT' |
| Debug using UDP packets to PORT on HOST. For example, to connect |
| to UDP port 2828 on a terminal server named 'manyfarms': |
| |
| target remote udp:manyfarms:2828 |
| |
| When using a UDP connection for remote debugging, you should keep |
| in mind that the 'U' stands for "Unreliable". UDP can silently |
| drop packets on busy or unreliable networks, which will cause havoc |
| with your debugging session. |
| |
| 'target remote | COMMAND' |
| 'target extended-remote | COMMAND' |
| Run COMMAND in the background and communicate with it using a pipe. |
| The COMMAND is a shell command, to be parsed and expanded by the |
| system's command shell, '/bin/sh'; it should expect remote protocol |
| packets on its standard input, and send replies on its standard |
| output. You could use this to run a stand-alone simulator that |
| speaks the remote debugging protocol, to make net connections using |
| programs like 'ssh', or for other similar tricks. |
| |
| If COMMAND closes its standard output (perhaps by exiting), GDB |
| will try to send it a 'SIGTERM' signal. (If the program has |
| already exited, this will have no effect.) |
| |
| Whenever GDB is waiting for the remote program, if you type the |
| interrupt character (often 'Ctrl-c'), GDB attempts to stop the program. |
| This may or may not succeed, depending in part on the hardware and the |
| serial drivers the remote system uses. If you type the interrupt |
| character once again, GDB displays this prompt: |
| |
| Interrupted while waiting for the program. |
| Give up (and stop debugging it)? (y or n) |
| |
| In 'target remote' mode, if you type 'y', GDB abandons the remote |
| debugging session. (If you decide you want to try again later, you can |
| use 'target remote' again to connect once more.) If you type 'n', GDB |
| goes back to waiting. |
| |
| In 'target extended-remote' mode, typing 'n' will leave GDB connected |
| to the target. |
| |
| 'detach' |
| When you have finished debugging the remote program, you can use |
| the 'detach' command to release it from GDB control. Detaching |
| from the target normally resumes its execution, but the results |
| will depend on your particular remote stub. After the 'detach' |
| command in 'target remote' mode, GDB is free to connect to another |
| target. In 'target extended-remote' mode, GDB is still connected |
| to the target. |
| |
| 'disconnect' |
| The 'disconnect' command closes the connection to the target, and |
| the target is generally not resumed. It will wait for GDB (this |
| instance or another one) to connect and continue debugging. After |
| the 'disconnect' command, GDB is again free to connect to another |
| target. |
| |
| 'monitor CMD' |
| This command allows you to send arbitrary commands directly to the |
| remote monitor. Since GDB doesn't care about the commands it sends |
| like this, this command is the way to extend GDB--you can add new |
| commands that only the external monitor will understand and |
| implement. |
| |
| |
| File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging |
| |
| 20.2 Sending files to a remote system |
| ===================================== |
| |
| Some remote targets offer the ability to transfer files over the same |
| connection used to communicate with GDB. This is convenient for targets |
| accessible through other means, e.g. GNU/Linux systems running |
| 'gdbserver' over a network interface. For other targets, e.g. embedded |
| devices with only a single serial port, this may be the only way to |
| upload or download files. |
| |
| Not all remote targets support these commands. |
| |
| 'remote put HOSTFILE TARGETFILE' |
| Copy file HOSTFILE from the host system (the machine running GDB) |
| to TARGETFILE on the target system. |
| |
| 'remote get TARGETFILE HOSTFILE' |
| Copy file TARGETFILE from the target system to HOSTFILE on the host |
| system. |
| |
| 'remote delete TARGETFILE' |
| Delete TARGETFILE from the target system. |
| |
| |
| File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging |
| |
| 20.3 Using the 'gdbserver' Program |
| ================================== |
| |
| 'gdbserver' is a control program for Unix-like systems, which allows you |
| to connect your program with a remote GDB via 'target remote' or 'target |
| extended-remote'--but without linking in the usual debugging stub. |
| |
| 'gdbserver' is not a complete replacement for the debugging stubs, |
| because it requires essentially the same operating-system facilities |
| that GDB itself does. In fact, a system that can run 'gdbserver' to |
| connect to a remote GDB could also run GDB locally! 'gdbserver' is |
| sometimes useful nevertheless, because it is a much smaller program than |
| GDB itself. It is also easier to port than all of GDB, so you may be |
| able to get started more quickly on a new system by using 'gdbserver'. |
| Finally, if you develop code for real-time systems, you may find that |
| the tradeoffs involved in real-time operation make it more convenient to |
| do as much development work as possible on another system, for example |
| by cross-compiling. You can use 'gdbserver' to make a similar choice |
| for debugging. |
| |
| GDB and 'gdbserver' communicate via either a serial line or a TCP |
| connection, using the standard GDB remote serial protocol. |
| |
| _Warning:_ 'gdbserver' does not have any built-in security. Do not |
| run 'gdbserver' connected to any public network; a GDB connection |
| to 'gdbserver' provides access to the target system with the same |
| privileges as the user running 'gdbserver'. |
| |
| 20.3.1 Running 'gdbserver' |
| -------------------------- |
| |
| Run 'gdbserver' on the target system. You need a copy of the program |
| you want to debug, including any libraries it requires. 'gdbserver' |
| does not need your program's symbol table, so you can strip the program |
| if necessary to save space. GDB on the host system does all the symbol |
| handling. |
| |
| To use the server, you must tell it how to communicate with GDB; the |
| name of your program; and the arguments for your program. The usual |
| syntax is: |
| |
| target> gdbserver COMM PROGRAM [ ARGS ... ] |
| |
| COMM is either a device name (to use a serial line), or a TCP |
| hostname and portnumber, or '-' or 'stdio' to use stdin/stdout of |
| 'gdbserver'. For example, to debug Emacs with the argument 'foo.txt' |
| and communicate with GDB over the serial port '/dev/com1': |
| |
| target> gdbserver /dev/com1 emacs foo.txt |
| |
| 'gdbserver' waits passively for the host GDB to communicate with it. |
| |
| To use a TCP connection instead of a serial line: |
| |
| target> gdbserver host:2345 emacs foo.txt |
| |
| The only difference from the previous example is the first argument, |
| specifying that you are communicating with the host GDB via TCP. The |
| 'host:2345' argument means that 'gdbserver' is to expect a TCP |
| connection from machine 'host' to local TCP port 2345. (Currently, the |
| 'host' part is ignored.) You can choose any number you want for the |
| port number as long as it does not conflict with any TCP ports already |
| in use on the target system (for example, '23' is reserved for |
| 'telnet').(1) You must use the same port number with the host GDB |
| 'target remote' command. |
| |
| The 'stdio' connection is useful when starting 'gdbserver' with ssh: |
| |
| (gdb) target remote | ssh -T hostname gdbserver - hello |
| |
| The '-T' option to ssh is provided because we don't need a remote |
| pty, and we don't want escape-character handling. Ssh does this by |
| default when a command is provided, the flag is provided to make it |
| explicit. You could elide it if you want to. |
| |
| Programs started with stdio-connected gdbserver have '/dev/null' for |
| 'stdin', and 'stdout','stderr' are sent back to gdb for display through |
| a pipe connected to gdbserver. Both 'stdout' and 'stderr' use the same |
| pipe. |
| |
| 20.3.1.1 Attaching to a Running Program |
| ....................................... |
| |
| On some targets, 'gdbserver' can also attach to running programs. This |
| is accomplished via the '--attach' argument. The syntax is: |
| |
| target> gdbserver --attach COMM PID |
| |
| PID is the process ID of a currently running process. It isn't |
| necessary to point 'gdbserver' at a binary for the running process. |
| |
| In 'target extended-remote' mode, you can also attach using the GDB |
| attach command (*note Attaching in Types of Remote Connections::). |
| |
| You can debug processes by name instead of process ID if your target |
| has the 'pidof' utility: |
| |
| target> gdbserver --attach COMM `pidof PROGRAM` |
| |
| In case more than one copy of PROGRAM is running, or PROGRAM has |
| multiple threads, most versions of 'pidof' support the '-s' option to |
| only return the first process ID. |
| |
| 20.3.1.2 TCP port allocation lifecycle of 'gdbserver' |
| ..................................................... |
| |
| This section applies only when 'gdbserver' is run to listen on a TCP |
| port. |
| |
| 'gdbserver' normally terminates after all of its debugged processes |
| have terminated in 'target remote' mode. On the other hand, for 'target |
| extended-remote', 'gdbserver' stays running even with no processes left. |
| GDB normally terminates the spawned debugged process on its exit, which |
| normally also terminates 'gdbserver' in the 'target remote' mode. |
| Therefore, when the connection drops unexpectedly, and GDB cannot ask |
| 'gdbserver' to kill its debugged processes, 'gdbserver' stays running |
| even in the 'target remote' mode. |
| |
| When 'gdbserver' stays running, GDB can connect to it again later. |
| Such reconnecting is useful for features like *note disconnected |
| tracing::. For completeness, at most one GDB can be connected at a |
| time. |
| |
| By default, 'gdbserver' keeps the listening TCP port open, so that |
| subsequent connections are possible. However, if you start 'gdbserver' |
| with the '--once' option, it will stop listening for any further |
| connection attempts after connecting to the first GDB session. This |
| means no further connections to 'gdbserver' will be possible after the |
| first one. It also means 'gdbserver' will terminate after the first |
| connection with remote GDB has closed, even for unexpectedly closed |
| connections and even in the 'target extended-remote' mode. The '--once' |
| option allows reusing the same port number for connecting to multiple |
| instances of 'gdbserver' running on the same host, since each instance |
| closes its port after the first connection. |
| |
| 20.3.1.3 Other Command-Line Arguments for 'gdbserver' |
| ..................................................... |
| |
| You can use the '--multi' option to start 'gdbserver' without specifying |
| a program to debug or a process to attach to. Then you can attach in |
| 'target extended-remote' mode and run or attach to a program. For more |
| information, *note --multi Option in Types of Remote Connnections::. |
| |
| The '--debug' option tells 'gdbserver' to display extra status |
| information about the debugging process. The '--remote-debug' option |
| tells 'gdbserver' to display remote protocol debug output. The |
| '--debug-file=FILENAME' option tells 'gdbserver' to write any debug |
| output to the given FILENAME. These options are intended for |
| 'gdbserver' development and for bug reports to the developers. |
| |
| The '--debug-format=option1[,option2,...]' option tells 'gdbserver' |
| to include additional information in each output. Possible options are: |
| |
| 'none' |
| Turn off all extra information in debugging output. |
| 'all' |
| Turn on all extra information in debugging output. |
| 'timestamps' |
| Include a timestamp in each line of debugging output. |
| |
| Options are processed in order. Thus, for example, if 'none' appears |
| last then no additional information is added to debugging output. |
| |
| The '--wrapper' option specifies a wrapper to launch programs for |
| debugging. The option should be followed by the name of the wrapper, |
| then any command-line arguments to pass to the wrapper, then '--' |
| indicating the end of the wrapper arguments. |
| |
| 'gdbserver' runs the specified wrapper program with a combined |
| command line including the wrapper arguments, then the name of the |
| program to debug, then any arguments to the program. The wrapper runs |
| until it executes your program, and then GDB gains control. |
| |
| You can use any program that eventually calls 'execve' with its |
| arguments as a wrapper. Several standard Unix utilities do this, e.g. |
| 'env' and 'nohup'. Any Unix shell script ending with 'exec "$@"' will |
| also work. |
| |
| For example, you can use 'env' to pass an environment variable to the |
| debugged program, without setting the variable in 'gdbserver''s |
| environment: |
| |
| $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog |
| |
| The '--selftest' option runs the self tests in 'gdbserver': |
| |
| $ gdbserver --selftest |
| Ran 2 unit tests, 0 failed |
| |
| These tests are disabled in release. |
| |
| 20.3.2 Connecting to 'gdbserver' |
| -------------------------------- |
| |
| The basic procedure for connecting to the remote target is: |
| |
| * Run GDB on the host system. |
| |
| * Make sure you have the necessary symbol files (*note Host and |
| target files::). Load symbols for your application using the |
| 'file' command before you connect. Use 'set sysroot' to locate |
| target libraries (unless your GDB was compiled with the correct |
| sysroot using '--with-sysroot'). |
| |
| * Connect to your target (*note Connecting to a Remote Target: |
| Connecting.). For TCP connections, you must start up 'gdbserver' |
| prior to using the 'target' command. Otherwise you may get an |
| error whose text depends on the host system, but which usually |
| looks something like 'Connection refused'. Don't use the 'load' |
| command in GDB when using 'target remote' mode, since the program |
| is already on the target. |
| |
| 20.3.3 Monitor Commands for 'gdbserver' |
| --------------------------------------- |
| |
| During a GDB session using 'gdbserver', you can use the 'monitor' |
| command to send special requests to 'gdbserver'. Here are the available |
| commands. |
| |
| 'monitor help' |
| List the available monitor commands. |
| |
| 'monitor set debug 0' |
| 'monitor set debug 1' |
| Disable or enable general debugging messages. |
| |
| 'monitor set remote-debug 0' |
| 'monitor set remote-debug 1' |
| Disable or enable specific debugging messages associated with the |
| remote protocol (*note Remote Protocol::). |
| |
| 'monitor set debug-file filename' |
| 'monitor set debug-file' |
| Send any debug output to the given file, or to stderr. |
| |
| 'monitor set debug-format option1[,option2,...]' |
| Specify additional text to add to debugging messages. Possible |
| options are: |
| |
| 'none' |
| Turn off all extra information in debugging output. |
| 'all' |
| Turn on all extra information in debugging output. |
| 'timestamps' |
| Include a timestamp in each line of debugging output. |
| |
| Options are processed in order. Thus, for example, if 'none' |
| appears last then no additional information is added to debugging |
| output. |
| |
| 'monitor set libthread-db-search-path [PATH]' |
| When this command is issued, PATH is a colon-separated list of |
| directories to search for 'libthread_db' (*note set |
| libthread-db-search-path: Threads.). If you omit PATH, |
| 'libthread-db-search-path' will be reset to its default value. |
| |
| The special entry '$pdir' for 'libthread-db-search-path' is not |
| supported in 'gdbserver'. |
| |
| 'monitor exit' |
| Tell gdbserver to exit immediately. This command should be |
| followed by 'disconnect' to close the debugging session. |
| 'gdbserver' will detach from any attached processes and kill any |
| processes it created. Use 'monitor exit' to terminate 'gdbserver' |
| at the end of a multi-process mode debug session. |
| |
| 20.3.4 Tracepoints support in 'gdbserver' |
| ----------------------------------------- |
| |
| On some targets, 'gdbserver' supports tracepoints, fast tracepoints and |
| static tracepoints. |
| |
| For fast or static tracepoints to work, a special library called the |
| "in-process agent" (IPA), must be loaded in the inferior process. This |
| library is built and distributed as an integral part of 'gdbserver'. In |
| addition, support for static tracepoints requires building the |
| in-process agent library with static tracepoints support. At present, |
| the UST (LTTng Userspace Tracer, <http://lttng.org/ust>) tracing engine |
| is supported. This support is automatically available if UST |
| development headers are found in the standard include path when |
| 'gdbserver' is built, or if 'gdbserver' was explicitly configured using |
| '--with-ust' to point at such headers. You can explicitly disable the |
| support using '--with-ust=no'. |
| |
| There are several ways to load the in-process agent in your program: |
| |
| 'Specifying it as dependency at link time' |
| |
| You can link your program dynamically with the in-process agent |
| library. On most systems, this is accomplished by adding |
| '-linproctrace' to the link command. |
| |
| 'Using the system's preloading mechanisms' |
| |
| You can force loading the in-process agent at startup time by using |
| your system's support for preloading shared libraries. Many Unixes |
| support the concept of preloading user defined libraries. In most |
| cases, you do that by specifying 'LD_PRELOAD=libinproctrace.so' in |
| the environment. See also the description of 'gdbserver''s |
| '--wrapper' command line option. |
| |
| 'Using GDB to force loading the agent at run time' |
| |
| On some systems, you can force the inferior to load a shared |
| library, by calling a dynamic loader function in the inferior that |
| takes care of dynamically looking up and loading a shared library. |
| On most Unix systems, the function is 'dlopen'. You'll use the |
| 'call' command for that. For example: |
| |
| (gdb) call dlopen ("libinproctrace.so", ...) |
| |
| Note that on most Unix systems, for the 'dlopen' function to be |
| available, the program needs to be linked with '-ldl'. |
| |
| On systems that have a userspace dynamic loader, like most Unix |
| systems, when you connect to 'gdbserver' using 'target remote', you'll |
| find that the program is stopped at the dynamic loader's entry point, |
| and no shared library has been loaded in the program's address space |
| yet, including the in-process agent. In that case, before being able to |
| use any of the fast or static tracepoints features, you need to let the |
| loader run and load the shared libraries. The simplest way to do that |
| is to run the program to the main procedure. E.g., if debugging a C or |
| C++ program, start 'gdbserver' like so: |
| |
| $ gdbserver :9999 myprogram |
| |
| Start GDB and connect to 'gdbserver' like so, and run to main: |
| |
| $ gdb myprogram |
| (gdb) target remote myhost:9999 |
| 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 |
| (gdb) b main |
| (gdb) continue |
| |
| The in-process tracing agent library should now be loaded into the |
| process; you can confirm it with the 'info sharedlibrary' command, which |
| will list 'libinproctrace.so' as loaded in the process. You are now |
| ready to install fast tracepoints, list static tracepoint markers, probe |
| static tracepoints markers, and start tracing. |
| |
| ---------- Footnotes ---------- |
| |
| (1) If you choose a port number that conflicts with another service, |
| 'gdbserver' prints an error message and exits. |
| |
| |
| File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging |
| |
| 20.4 Remote Configuration |
| ========================= |
| |
| This section documents the configuration options available when |
| debugging remote programs. For the options related to the File I/O |
| extensions of the remote protocol, see *note system-call-allowed: |
| system. |
| |
| 'set remoteaddresssize BITS' |
| Set the maximum size of address in a memory packet to the specified |
| number of bits. GDB will mask off the address bits above that |
| number, when it passes addresses to the remote target. The default |
| value is the number of bits in the target's address. |
| |
| 'show remoteaddresssize' |
| Show the current value of remote address size in bits. |
| |
| 'set serial baud N' |
| Set the baud rate for the remote serial I/O to N baud. The value |
| is used to set the speed of the serial port used for debugging |
| remote targets. |
| |
| 'show serial baud' |
| Show the current speed of the remote connection. |
| |
| 'set serial parity PARITY' |
| Set the parity for the remote serial I/O. Supported values of |
| PARITY are: 'even', 'none', and 'odd'. The default is 'none'. |
| |
| 'show serial parity' |
| Show the current parity of the serial port. |
| |
| 'set remotebreak' |
| If set to on, GDB sends a 'BREAK' signal to the remote when you |
| type 'Ctrl-c' to interrupt the program running on the remote. If |
| set to off, GDB sends the 'Ctrl-C' character instead. The default |
| is off, since most remote systems expect to see 'Ctrl-C' as the |
| interrupt signal. |
| |
| 'show remotebreak' |
| Show whether GDB sends 'BREAK' or 'Ctrl-C' to interrupt the remote |
| program. |
| |
| 'set remoteflow on' |
| 'set remoteflow off' |
| Enable or disable hardware flow control ('RTS'/'CTS') on the serial |
| port used to communicate to the remote target. |
| |
| 'show remoteflow' |
| Show the current setting of hardware flow control. |
| |
| 'set remotelogbase BASE' |
| Set the base (a.k.a. radix) of logging serial protocol |
| communications to BASE. Supported values of BASE are: 'ascii', |
| 'octal', and 'hex'. The default is 'ascii'. |
| |
| 'show remotelogbase' |
| Show the current setting of the radix for logging remote serial |
| protocol. |
| |
| 'set remotelogfile FILE' |
| Record remote serial communications on the named FILE. The default |
| is not to record at all. |
| |
| 'show remotelogfile' |
| Show the current setting of the file name on which to record the |
| serial communications. |
| |
| 'set remotetimeout NUM' |
| Set the timeout limit to wait for the remote target to respond to |
| NUM seconds. The default is 2 seconds. |
| |
| 'show remotetimeout' |
| Show the current number of seconds to wait for the remote target |
| responses. |
| |
| 'set remote hardware-watchpoint-limit LIMIT' |
| 'set remote hardware-breakpoint-limit LIMIT' |
| Restrict GDB to using LIMIT remote hardware watchpoints or |
| breakpoints. The LIMIT can be set to 0 to disable hardware |
| watchpoints or breakpoints, and 'unlimited' for unlimited |
| watchpoints or breakpoints. |
| |
| 'show remote hardware-watchpoint-limit' |
| 'show remote hardware-breakpoint-limit' |
| Show the current limit for the number of hardware watchpoints or |
| breakpoints that GDB can use. |
| |
| 'set remote hardware-watchpoint-length-limit LIMIT' |
| Restrict GDB to using LIMIT bytes for the maximum length of a |
| remote hardware watchpoint. A LIMIT of 0 disables hardware |
| watchpoints and 'unlimited' allows watchpoints of any length. |
| |
| 'show remote hardware-watchpoint-length-limit' |
| Show the current limit (in bytes) of the maximum length of a remote |
| hardware watchpoint. |
| |
| 'set remote exec-file FILENAME' |
| 'show remote exec-file' |
| Select the file used for 'run' with 'target extended-remote'. This |
| should be set to a filename valid on the target system. If it is |
| not set, the target will use a default filename (e.g. the last |
| program run). |
| |
| 'set remote interrupt-sequence' |
| Allow the user to select one of 'Ctrl-C', a 'BREAK' or 'BREAK-g' as |
| the sequence to the remote target in order to interrupt the |
| execution. 'Ctrl-C' is a default. Some system prefers 'BREAK' |
| which is high level of serial line for some certain time. Linux |
| kernel prefers 'BREAK-g', a.k.a Magic SysRq g. It is 'BREAK' |
| signal followed by character 'g'. |
| |
| 'show interrupt-sequence' |
| Show which of 'Ctrl-C', 'BREAK' or 'BREAK-g' is sent by GDB to |
| interrupt the remote program. 'BREAK-g' is BREAK signal followed |
| by 'g' and also known as Magic SysRq g. |
| |
| 'set remote interrupt-on-connect' |
| Specify whether interrupt-sequence is sent to remote target when |
| GDB connects to it. This is mostly needed when you debug Linux |
| kernel. Linux kernel expects 'BREAK' followed by 'g' which is |
| known as Magic SysRq g in order to connect GDB. |
| |
| 'show interrupt-on-connect' |
| Show whether interrupt-sequence is sent to remote target when GDB |
| connects to it. |
| |
| 'set tcp auto-retry on' |
| Enable auto-retry for remote TCP connections. This is useful if |
| the remote debugging agent is launched in parallel with GDB; there |
| is a race condition because the agent may not become ready to |
| accept the connection before GDB attempts to connect. When |
| auto-retry is enabled, if the initial attempt to connect fails, GDB |
| reattempts to establish the connection using the timeout specified |
| by 'set tcp connect-timeout'. |
| |
| 'set tcp auto-retry off' |
| Do not auto-retry failed TCP connections. |
| |
| 'show tcp auto-retry' |
| Show the current auto-retry setting. |
| |
| 'set tcp connect-timeout SECONDS' |
| 'set tcp connect-timeout unlimited' |
| Set the timeout for establishing a TCP connection to the remote |
| target to SECONDS. The timeout affects both polling to retry |
| failed connections (enabled by 'set tcp auto-retry on') and waiting |
| for connections that are merely slow to complete, and represents an |
| approximate cumulative value. If SECONDS is 'unlimited', there is |
| no timeout and GDB will keep attempting to establish a connection |
| forever, unless interrupted with 'Ctrl-c'. The default is 15 |
| seconds. |
| |
| 'show tcp connect-timeout' |
| Show the current connection timeout setting. |
| |
| The GDB remote protocol autodetects the packets supported by your |
| debugging stub. If you need to override the autodetection, you can use |
| these commands to enable or disable individual packets. Each packet can |
| be set to 'on' (the remote target supports this packet), 'off' (the |
| remote target does not support this packet), or 'auto' (detect remote |
| target support for this packet). They all default to 'auto'. For more |
| information about each packet, see *note Remote Protocol::. |
| |
| During normal use, you should not have to use any of these commands. |
| If you do, that may be a bug in your remote debugging stub, or a bug in |
| GDB. You may want to report the problem to the GDB developers. |
| |
| For each packet NAME, the command to enable or disable the packet is |
| 'set remote NAME-packet'. The available settings are: |
| |
| Command Name Remote Packet Related Features |
| |
| 'fetch-register' 'p' 'info registers' |
| |
| 'set-register' 'P' 'set' |
| |
| 'binary-download' 'X' 'load', 'set' |
| |
| 'read-aux-vector' 'qXfer:auxv:read' 'info auxv' |
| |
| 'symbol-lookup' 'qSymbol' Detecting |
| multiple threads |
| |
| 'attach' 'vAttach' 'attach' |
| |
| 'verbose-resume' 'vCont' Stepping or |
| resuming |
| multiple threads |
| |
| 'run' 'vRun' 'run' |
| |
| 'software-breakpoint''Z0' 'break' |
| |
| 'hardware-breakpoint''Z1' 'hbreak' |
| |
| 'write-watchpoint' 'Z2' 'watch' |
| |
| 'read-watchpoint' 'Z3' 'rwatch' |
| |
| 'access-watchpoint' 'Z4' 'awatch' |
| |
| 'pid-to-exec-file' 'qXfer:exec-file:read' 'attach', 'run' |
| |
| 'target-features' 'qXfer:features:read' 'set |
| architecture' |
| |
| 'library-info' 'qXfer:libraries:read' 'info |
| sharedlibrary' |
| |
| 'memory-map' 'qXfer:memory-map:read' 'info mem' |
| |
| 'read-sdata-object' 'qXfer:sdata:read' 'print $_sdata' |
| |
| 'read-siginfo-object''qXfer:siginfo:read' 'print |
| $_siginfo' |
| |
| 'write-siginfo-object''qXfer:siginfo:write' 'set $_siginfo' |
| |
| 'threads' 'qXfer:threads:read' 'info threads' |
| |
| 'get-thread-local- 'qGetTLSAddr' Displaying |
| storage-address' '__thread' |
| variables |
| |
| 'get-thread-information-block-address''qGetTIBAddr'Display |
| MS-Windows |
| Thread |
| Information |
| Block. |
| |
| 'search-memory' 'qSearch:memory' 'find' |
| |
| 'supported-packets' 'qSupported' Remote |
| communications |
| parameters |
| |
| 'catch-syscalls' 'QCatchSyscalls' 'catch syscall' |
| |
| 'pass-signals' 'QPassSignals' 'handle SIGNAL' |
| |
| 'program-signals' 'QProgramSignals' 'handle SIGNAL' |
| |
| 'hostio-close-packet''vFile:close' 'remote get', |
| 'remote put' |
| |
| 'hostio-open-packet' 'vFile:open' 'remote get', |
| 'remote put' |
| |
| 'hostio-pread-packet''vFile:pread' 'remote get', |
| 'remote put' |
| |
| 'hostio-pwrite-packet''vFile:pwrite' 'remote get', |
| 'remote put' |
| |
| 'hostio-unlink-packet''vFile:unlink' 'remote delete' |
| |
| 'hostio-readlink-packet''vFile:readlink' Host I/O |
| |
| 'hostio-fstat-packet''vFile:fstat' Host I/O |
| |
| 'hostio-setfs-packet''vFile:setfs' Host I/O |
| |
| 'noack-packet' 'QStartNoAckMode' Packet |
| acknowledgment |
| |
| 'osdata' 'qXfer:osdata:read' 'info os' |
| |
| 'query-attached' 'qAttached' Querying remote |
| process attach |
| state. |
| |
| 'trace-buffer-size' 'QTBuffer:size' 'set |
| trace-buffer-size' |
| |
| 'trace-status' 'qTStatus' 'tstatus' |
| |
| 'traceframe-info' 'qXfer:traceframe-info:read'Traceframe info |
| |
| 'install-in-trace' 'InstallInTrace' Install |
| tracepoint in |
| tracing |
| |
| 'disable-randomization''QDisableRandomization''set |
| disable-randomization' |
| |
| 'startup-with-shell' 'QStartupWithShell' 'set |
| startup-with-shell' |
| |
| 'environment-hex-encoded''QEnvironmentHexEncoded''set |
| environment' |
| |
| 'environment-unset' 'QEnvironmentUnset' 'unset |
| environment' |
| |
| 'environment-reset' 'QEnvironmentReset' 'Reset the |
| inferior |
| environment |
| (i.e., unset |
| user-set |
| variables)' |
| |
| 'set-working-dir' 'QSetWorkingDir' 'set cwd' |
| |
| 'conditional-breakpoints-packet''Z0 and Z1' 'Support for |
| target-side |
| breakpoint |
| condition |
| evaluation' |
| |
| 'multiprocess-extensions''multiprocess Debug multiple |
| extensions' processes and |
| remote process |
| PID awareness |
| |
| 'swbreak-feature' 'swbreak stop reason' 'break' |
| |
| 'hwbreak-feature' 'hwbreak stop reason' 'hbreak' |
| |
| 'fork-event-feature' 'fork stop reason' 'fork' |
| |
| 'vfork-event-feature''vfork stop reason' 'vfork' |
| |
| 'exec-event-feature' 'exec stop reason' 'exec' |
| |
| 'thread-events' 'QThreadEvents' Tracking thread |
| lifetime. |
| |
| 'no-resumed-stop-reply''no resumed thread Tracking thread |
| left stop reply' lifetime. |
| |
| |
| |
| File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging |
| |
| 20.5 Implementing a Remote Stub |
| =============================== |
| |
| The stub files provided with GDB implement the target side of the |
| communication protocol, and the GDB side is implemented in the GDB |
| source file 'remote.c'. Normally, you can simply allow these |
| subroutines to communicate, and ignore the details. (If you're |
| implementing your own stub file, you can still ignore the details: start |
| with one of the existing stub files. 'sparc-stub.c' is the best |
| organized, and therefore the easiest to read.) |
| |
| To debug a program running on another machine (the debugging "target" |
| machine), you must first arrange for all the usual prerequisites for the |
| program to run by itself. For example, for a C program, you need: |
| |
| 1. A startup routine to set up the C runtime environment; these |
| usually have a name like 'crt0'. The startup routine may be |
| supplied by your hardware supplier, or you may have to write your |
| own. |
| |
| 2. A C subroutine library to support your program's subroutine calls, |
| notably managing input and output. |
| |
| 3. A way of getting your program to the other machine--for example, a |
| download program. These are often supplied by the hardware |
| manufacturer, but you may have to write your own from hardware |
| documentation. |
| |
| The next step is to arrange for your program to use a serial port to |
| communicate with the machine where GDB is running (the "host" machine). |
| In general terms, the scheme looks like this: |
| |
| _On the host,_ |
| GDB already understands how to use this protocol; when everything |
| else is set up, you can simply use the 'target remote' command |
| (*note Specifying a Debugging Target: Targets.). |
| |
| _On the target,_ |
| you must link with your program a few special-purpose subroutines |
| that implement the GDB remote serial protocol. The file containing |
| these subroutines is called a "debugging stub". |
| |
| On certain remote targets, you can use an auxiliary program |
| 'gdbserver' instead of linking a stub into your program. *Note |
| Using the 'gdbserver' Program: Server, for details. |
| |
| The debugging stub is specific to the architecture of the remote |
| machine; for example, use 'sparc-stub.c' to debug programs on SPARC |
| boards. |
| |
| These working remote stubs are distributed with GDB: |
| |
| 'i386-stub.c' |
| For Intel 386 and compatible architectures. |
| |
| 'm68k-stub.c' |
| For Motorola 680x0 architectures. |
| |
| 'sh-stub.c' |
| For Renesas SH architectures. |
| |
| 'sparc-stub.c' |
| For SPARC architectures. |
| |
| 'sparcl-stub.c' |
| For Fujitsu SPARCLITE architectures. |
| |
| The 'README' file in the GDB distribution may list other recently |
| added stubs. |
| |
| * Menu: |
| |
| * Stub Contents:: What the stub can do for you |
| * Bootstrapping:: What you must do for the stub |
| * Debug Session:: Putting it all together |
| |
| |
| File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub |
| |
| 20.5.1 What the Stub Can Do for You |
| ----------------------------------- |
| |
| The debugging stub for your architecture supplies these three |
| subroutines: |
| |
| 'set_debug_traps' |
| This routine arranges for 'handle_exception' to run when your |
| program stops. You must call this subroutine explicitly in your |
| program's startup code. |
| |
| 'handle_exception' |
| This is the central workhorse, but your program never calls it |
| explicitly--the setup code arranges for 'handle_exception' to run |
| when a trap is triggered. |
| |
| 'handle_exception' takes control when your program stops during |
| execution (for example, on a breakpoint), and mediates |
| communications with GDB on the host machine. This is where the |
| communications protocol is implemented; 'handle_exception' acts as |
| the GDB representative on the target machine. It begins by sending |
| summary information on the state of your program, then continues to |
| execute, retrieving and transmitting any information GDB needs, |
| until you execute a GDB command that makes your program resume; at |
| that point, 'handle_exception' returns control to your own code on |
| the target machine. |
| |
| 'breakpoint' |
| Use this auxiliary subroutine to make your program contain a |
| breakpoint. Depending on the particular situation, this may be the |
| only way for GDB to get control. For instance, if your target |
| machine has some sort of interrupt button, you won't need to call |
| this; pressing the interrupt button transfers control to |
| 'handle_exception'--in effect, to GDB. On some machines, simply |
| receiving characters on the serial port may also trigger a trap; |
| again, in that situation, you don't need to call 'breakpoint' from |
| your own program--simply running 'target remote' from the host GDB |
| session gets control. |
| |
| Call 'breakpoint' if none of these is true, or if you simply want |
| to make certain your program stops at a predetermined point for the |
| start of your debugging session. |
| |
| |
| File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub |
| |
| 20.5.2 What You Must Do for the Stub |
| ------------------------------------ |
| |
| The debugging stubs that come with GDB are set up for a particular chip |
| architecture, but they have no information about the rest of your |
| debugging target machine. |
| |
| First of all you need to tell the stub how to communicate with the |
| serial port. |
| |
| 'int getDebugChar()' |
| Write this subroutine to read a single character from the serial |
| port. It may be identical to 'getchar' for your target system; a |
| different name is used to allow you to distinguish the two if you |
| wish. |
| |
| 'void putDebugChar(int)' |
| Write this subroutine to write a single character to the serial |
| port. It may be identical to 'putchar' for your target system; a |
| different name is used to allow you to distinguish the two if you |
| wish. |
| |
| If you want GDB to be able to stop your program while it is running, |
| you need to use an interrupt-driven serial driver, and arrange for it to |
| stop when it receives a '^C' ('\003', the control-C character). That is |
| the character which GDB uses to tell the remote system to stop. |
| |
| Getting the debugging target to return the proper status to GDB |
| probably requires changes to the standard stub; one quick and dirty way |
| is to just execute a breakpoint instruction (the "dirty" part is that |
| GDB reports a 'SIGTRAP' instead of a 'SIGINT'). |
| |
| Other routines you need to supply are: |
| |
| 'void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' |
| Write this function to install EXCEPTION_ADDRESS in the exception |
| handling tables. You need to do this because the stub does not |
| have any way of knowing what the exception handling tables on your |
| target system are like (for example, the processor's table might be |
| in ROM, containing entries which point to a table in RAM). The |
| EXCEPTION_NUMBER specifies the exception which should be changed; |
| its meaning is architecture-dependent (for example, different |
| numbers might represent divide by zero, misaligned access, etc). |
| When this exception occurs, control should be transferred directly |
| to EXCEPTION_ADDRESS, and the processor state (stack, registers, |
| and so on) should be just as it is when a processor exception |
| occurs. So if you want to use a jump instruction to reach |
| EXCEPTION_ADDRESS, it should be a simple jump, not a jump to |
| subroutine. |
| |
| For the 386, EXCEPTION_ADDRESS should be installed as an interrupt |
| gate so that interrupts are masked while the handler runs. The |
| gate should be at privilege level 0 (the most privileged level). |
| The SPARC and 68k stubs are able to mask interrupts themselves |
| without help from 'exceptionHandler'. |
| |
| 'void flush_i_cache()' |
| On SPARC and SPARCLITE only, write this subroutine to flush the |
| instruction cache, if any, on your target machine. If there is no |
| instruction cache, this subroutine may be a no-op. |
| |
| On target machines that have instruction caches, GDB requires this |
| function to make certain that the state of your program is stable. |
| |
| You must also make sure this library routine is available: |
| |
| 'void *memset(void *, int, int)' |
| This is the standard library function 'memset' that sets an area of |
| memory to a known value. If you have one of the free versions of |
| 'libc.a', 'memset' can be found there; otherwise, you must either |
| obtain it from your hardware manufacturer, or write your own. |
| |
| If you do not use the GNU C compiler, you may need other standard |
| library subroutines as well; this varies from one stub to another, but |
| in general the stubs are likely to use any of the common library |
| subroutines which 'GCC' generates as inline code. |
| |
| |
| File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub |
| |
| 20.5.3 Putting it All Together |
| ------------------------------ |
| |
| In summary, when your program is ready to debug, you must follow these |
| steps. |
| |
| 1. Make sure you have defined the supporting low-level routines (*note |
| What You Must Do for the Stub: Bootstrapping.): |
| 'getDebugChar', 'putDebugChar', |
| 'flush_i_cache', 'memset', 'exceptionHandler'. |
| |
| 2. Insert these lines in your program's startup code, before the main |
| procedure is called: |
| |
| set_debug_traps(); |
| breakpoint(); |
| |
| On some machines, when a breakpoint trap is raised, the hardware |
| automatically makes the PC point to the instruction after the |
| breakpoint. If your machine doesn't do that, you may need to |
| adjust 'handle_exception' to arrange for it to return to the |
| instruction after the breakpoint on this first invocation, so that |
| your program doesn't keep hitting the initial breakpoint instead of |
| making progress. |
| |
| 3. For the 680x0 stub only, you need to provide a variable called |
| 'exceptionHook'. Normally you just use: |
| |
| void (*exceptionHook)() = 0; |
| |
| but if before calling 'set_debug_traps', you set it to point to a |
| function in your program, that function is called when 'GDB' |
| continues after stopping on a trap (for example, bus error). The |
| function indicated by 'exceptionHook' is called with one parameter: |
| an 'int' which is the exception number. |
| |
| 4. Compile and link together: your program, the GDB debugging stub for |
| your target architecture, and the supporting subroutines. |
| |
| 5. Make sure you have a serial connection between your target machine |
| and the GDB host, and identify the serial port on the host. |
| |
| 6. Download your program to your target machine (or get it there by |
| whatever means the manufacturer provides), and start it. |
| |
| 7. Start GDB on the host, and connect to the target (*note Connecting |
| to a Remote Target: Connecting.). |
| |
| |
| File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top |
| |
| 21 Configuration-Specific Information |
| ************************************* |
| |
| While nearly all GDB commands are available for all native and cross |
| versions of the debugger, there are some exceptions. This chapter |
| describes things that are only available in certain configurations. |
| |
| There are three major categories of configurations: native |
| configurations, where the host and target are the same, embedded |
| operating system configurations, which are usually the same for several |
| different processor architectures, and bare embedded processors, which |
| are quite different from each other. |
| |
| * Menu: |
| |
| * Native:: |
| * Embedded OS:: |
| * Embedded Processors:: |
| * Architectures:: |
| |
| |
| File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations |
| |
| 21.1 Native |
| =========== |
| |
| This section describes details specific to particular native |
| configurations. |
| |
| * Menu: |
| |
| * BSD libkvm Interface:: Debugging BSD kernel memory images |
| * Process Information:: Process information |
| * DJGPP Native:: Features specific to the DJGPP port |
| * Cygwin Native:: Features specific to the Cygwin port |
| * Hurd Native:: Features specific to GNU Hurd |
| * Darwin:: Features specific to Darwin |
| * FreeBSD:: Features specific to FreeBSD |
| |
| |
| File: gdb.info, Node: BSD libkvm Interface, Next: Process Information, Up: Native |
| |
| 21.1.1 BSD libkvm Interface |
| --------------------------- |
| |
| BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory |
| interface that provides a uniform interface for accessing kernel virtual |
| memory images, including live systems and crash dumps. GDB uses this |
| interface to allow you to debug live kernels and kernel crash dumps on |
| many native BSD configurations. This is implemented as a special 'kvm' |
| debugging target. For debugging a live system, load the currently |
| running kernel into GDB and connect to the 'kvm' target: |
| |
| (gdb) target kvm |
| |
| For debugging crash dumps, provide the file name of the crash dump as |
| an argument: |
| |
| (gdb) target kvm /var/crash/bsd.0 |
| |
| Once connected to the 'kvm' target, the following commands are |
| available: |
| |
| 'kvm pcb' |
| Set current context from the "Process Control Block" (PCB) address. |
| |
| 'kvm proc' |
| Set current context from proc address. This command isn't |
| available on modern FreeBSD systems. |
| |
| |
| File: gdb.info, Node: Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native |
| |
| 21.1.2 Process Information |
| -------------------------- |
| |
| Some operating systems provide interfaces to fetch additional |
| information about running processes beyond memory and per-thread |
| register state. If GDB is configured for an operating system with a |
| supported interface, the command 'info proc' is available to report |
| information about the process running your program, or about any process |
| running on your system. |
| |
| One supported interface is a facility called '/proc' that can be used |
| to examine the image of a running process using file-system subroutines. |
| This facility is supported on GNU/Linux and Solaris systems. |
| |
| On FreeBSD systems, system control nodes are used to query process |
| information. |
| |
| In addition, some systems may provide additional process information |
| in core files. Note that a core file may include a subset of the |
| information available from a live process. Process information is |
| currently available from cores created on GNU/Linux and FreeBSD systems. |
| |
| 'info proc' |
| 'info proc PROCESS-ID' |
| Summarize available information about a process. If a process ID |
| is specified by PROCESS-ID, display information about that process; |
| otherwise display information about the program being debugged. |
| The summary includes the debugged process ID, the command line used |
| to invoke it, its current working directory, and its executable |
| file's absolute file name. |
| |
| On some systems, PROCESS-ID can be of the form '[PID]/TID' which |
| specifies a certain thread ID within a process. If the optional |
| PID part is missing, it means a thread from the process being |
| debugged (the leading '/' still needs to be present, or else GDB |
| will interpret the number as a process ID rather than a thread ID). |
| |
| 'info proc cmdline' |
| Show the original command line of the process. This command is |
| supported on GNU/Linux and FreeBSD. |
| |
| 'info proc cwd' |
| Show the current working directory of the process. This command is |
| supported on GNU/Linux and FreeBSD. |
| |
| 'info proc exe' |
| Show the name of executable of the process. This command is |
| supported on GNU/Linux and FreeBSD. |
| |
| 'info proc files' |
| Show the file descriptors open by the process. For each open file |
| descriptor, GDB shows its number, type (file, directory, character |
| device, socket), file pointer offset, and the name of the resource |
| open on the descriptor. The resource name can be a file name (for |
| files, directories, and devices) or a protocol followed by socket |
| address (for network connections). This command is supported on |
| FreeBSD. |
| |
| This example shows the open file descriptors for a process using a |
| tty for standard input and output as well as two network sockets: |
| |
| (gdb) info proc files 22136 |
| process 22136 |
| Open files: |
| |
| FD Type Offset Flags Name |
| text file - r-------- /usr/bin/ssh |
| ctty chr - rw------- /dev/pts/20 |
| cwd dir - r-------- /usr/home/john |
| root dir - r-------- / |
| 0 chr 0x32933a4 rw------- /dev/pts/20 |
| 1 chr 0x32933a4 rw------- /dev/pts/20 |
| 2 chr 0x32933a4 rw------- /dev/pts/20 |
| 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22 |
| 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456 |
| |
| 'info proc mappings' |
| Report the memory address space ranges accessible in a process. On |
| Solaris and FreeBSD systems, each memory range includes information |
| on whether the process has read, write, or execute access rights to |
| each range. On GNU/Linux and FreeBSD systems, each memory range |
| includes the object file which is mapped to that range. |
| |
| 'info proc stat' |
| 'info proc status' |
| Show additional process-related information, including the user ID |
| and group ID; virtual memory usage; the signals that are pending, |
| blocked, and ignored; its TTY; its consumption of system and user |
| time; its stack size; its 'nice' value; etc. These commands are |
| supported on GNU/Linux and FreeBSD. |
| |
| For GNU/Linux systems, see the 'proc' man page for more information |
| (type 'man 5 proc' from your shell prompt). |
| |
| For FreeBSD systems, 'info proc stat' is an alias for 'info proc |
| status'. |
| |
| 'info proc all' |
| Show all the information about the process described under all of |
| the above 'info proc' subcommands. |
| |
| 'set procfs-trace' |
| This command enables and disables tracing of 'procfs' API calls. |
| |
| 'show procfs-trace' |
| Show the current state of 'procfs' API call tracing. |
| |
| 'set procfs-file FILE' |
| Tell GDB to write 'procfs' API trace to the named FILE. GDB |
| appends the trace info to the previous contents of the file. The |
| default is to display the trace on the standard output. |
| |
| 'show procfs-file' |
| Show the file to which 'procfs' API trace is written. |
| |
| 'proc-trace-entry' |
| 'proc-trace-exit' |
| 'proc-untrace-entry' |
| 'proc-untrace-exit' |
| These commands enable and disable tracing of entries into and exits |
| from the 'syscall' interface. |
| |
| 'info pidlist' |
| For QNX Neutrino only, this command displays the list of all the |
| processes and all the threads within each process. |
| |
| 'info meminfo' |
| For QNX Neutrino only, this command displays the list of all |
| mapinfos. |
| |
| |
| File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: Process Information, Up: Native |
| |
| 21.1.3 Features for Debugging DJGPP Programs |
| -------------------------------------------- |
| |
| DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. |
| DJGPP programs are 32-bit protected-mode programs that use the "DPMI" |
| (DOS Protected-Mode Interface) API to run on top of real-mode DOS |
| systems and their emulations. |
| |
| GDB supports native debugging of DJGPP programs, and defines a few |
| commands specific to the DJGPP port. This subsection describes those |
| commands. |
| |
| 'info dos' |
| This is a prefix of DJGPP-specific commands which print information |
| about the target system and important OS structures. |
| |
| 'info dos sysinfo' |
| This command displays assorted information about the underlying |
| platform: the CPU type and features, the OS version and flavor, the |
| DPMI version, and the available conventional and DPMI memory. |
| |
| 'info dos gdt' |
| 'info dos ldt' |
| 'info dos idt' |
| These 3 commands display entries from, respectively, Global, Local, |
| and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor |
| tables are data structures which store a descriptor for each |
| segment that is currently in use. The segment's selector is an |
| index into a descriptor table; the table entry for that index holds |
| the descriptor's base address and limit, and its attributes and |
| access rights. |
| |
| A typical DJGPP program uses 3 segments: a code segment, a data |
| segment (used for both data and the stack), and a DOS segment |
| (which allows access to DOS/BIOS data structures and absolute |
| addresses in conventional memory). However, the DPMI host will |
| usually define additional segments in order to support the DPMI |
| environment. |
| |
| These commands allow to display entries from the descriptor tables. |
| Without an argument, all entries from the specified table are |
| displayed. An argument, which should be an integer expression, |
| means display a single entry whose index is given by the argument. |
| For example, here's a convenient way to display information about |
| the debugged program's data segment: |
| |
| (gdb) info dos ldt $ds |
| 0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up) |
| |
| This comes in handy when you want to see whether a pointer is |
| outside the data segment's limit (i.e. "garbled"). |
| |
| 'info dos pde' |
| 'info dos pte' |
| These two commands display entries from, respectively, the Page |
| Directory and the Page Tables. Page Directories and Page Tables |
| are data structures which control how virtual memory addresses are |
| mapped into physical addresses. A Page Table includes an entry for |
| every page of memory that is mapped into the program's address |
| space; there may be several Page Tables, each one holding up to |
| 4096 entries. A Page Directory has up to 4096 entries, one each |
| for every Page Table that is currently in use. |
| |
| Without an argument, 'info dos pde' displays the entire Page |
| Directory, and 'info dos pte' displays all the entries in all of |
| the Page Tables. An argument, an integer expression, given to the |
| 'info dos pde' command means display only that entry from the Page |
| Directory table. An argument given to the 'info dos pte' command |
| means display entries from a single Page Table, the one pointed to |
| by the specified entry in the Page Directory. |
| |
| These commands are useful when your program uses "DMA" (Direct |
| Memory Access), which needs physical addresses to program the DMA |
| controller. |
| |
| These commands are supported only with some DPMI servers. |
| |
| 'info dos address-pte ADDR' |
| This command displays the Page Table entry for a specified linear |
| address. The argument ADDR is a linear address which should |
| already have the appropriate segment's base address added to it, |
| because this command accepts addresses which may belong to _any_ |
| segment. For example, here's how to display the Page Table entry |
| for the page where a variable 'i' is stored: |
| |
| (gdb) info dos address-pte __djgpp_base_address + (char *)&i |
| Page Table entry for address 0x11a00d30: |
| Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30 |
| |
| This says that 'i' is stored at offset '0xd30' from the page whose |
| physical base address is '0x02698000', and shows all the attributes |
| of that page. |
| |
| Note that you must cast the addresses of variables to a 'char *', |
| since otherwise the value of '__djgpp_base_address', the base |
| address of all variables and functions in a DJGPP program, will be |
| added using the rules of C pointer arithmetics: if 'i' is declared |
| an 'int', GDB will add 4 times the value of '__djgpp_base_address' |
| to the address of 'i'. |
| |
| Here's another example, it displays the Page Table entry for the |
| transfer buffer: |
| |
| (gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3) |
| Page Table entry for address 0x29110: |
| Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110 |
| |
| (The '+ 3' offset is because the transfer buffer's address is the |
| 3rd member of the '_go32_info_block' structure.) The output |
| clearly shows that this DPMI server maps the addresses in |
| conventional memory 1:1, i.e. the physical ('0x00029000' + '0x110') |
| and linear ('0x29110') addresses are identical. |
| |
| This command is supported only with some DPMI servers. |
| |
| In addition to native debugging, the DJGPP port supports remote |
| debugging via a serial data link. The following commands are specific |
| to remote serial debugging in the DJGPP port of GDB. |
| |
| 'set com1base ADDR' |
| This command sets the base I/O port address of the 'COM1' serial |
| port. |
| |
| 'set com1irq IRQ' |
| This command sets the "Interrupt Request" ('IRQ') line to use for |
| the 'COM1' serial port. |
| |
| There are similar commands 'set com2base', 'set com3irq', etc. for |
| setting the port address and the 'IRQ' lines for the other 3 COM |
| ports. |
| |
| The related commands 'show com1base', 'show com1irq' etc. display |
| the current settings of the base address and the 'IRQ' lines used |
| by the COM ports. |
| |
| 'info serial' |
| This command prints the status of the 4 DOS serial ports. For each |
| port, it prints whether it's active or not, its I/O base address |
| and IRQ number, whether it uses a 16550-style FIFO, its baudrate, |
| and the counts of various errors encountered so far. |
| |
| |
| File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native |
| |
| 21.1.4 Features for Debugging MS Windows PE Executables |
| ------------------------------------------------------- |
| |
| GDB supports native debugging of MS Windows programs, including DLLs |
| with and without symbolic debugging information. |
| |
| MS-Windows programs that call 'SetConsoleMode' to switch off the |
| special meaning of the 'Ctrl-C' keystroke cannot be interrupted by |
| typing 'C-c'. For this reason, GDB on MS-Windows supports 'C-<BREAK>' |
| as an alternative interrupt key sequence, which can be used to interrupt |
| the debuggee even if it ignores 'C-c'. |
| |
| There are various additional Cygwin-specific commands, described in |
| this section. Working with DLLs that have no debugging symbols is |
| described in *note Non-debug DLL Symbols::. |
| |
| 'info w32' |
| This is a prefix of MS Windows-specific commands which print |
| information about the target system and important OS structures. |
| |
| 'info w32 selector' |
| This command displays information returned by the Win32 API |
| 'GetThreadSelectorEntry' function. It takes an optional argument |
| that is evaluated to a long value to give the information about |
| this given selector. Without argument, this command displays |
| information about the six segment registers. |
| |
| 'info w32 thread-information-block' |
| This command displays thread specific information stored in the |
| Thread Information Block (readable on the X86 CPU family using |
| '$fs' selector for 32-bit programs and '$gs' for 64-bit programs). |
| |
| 'signal-event ID' |
| This command signals an event with user-provided ID. Used to |
| resume crashing process when attached to it using MS-Windows JIT |
| debugging (AeDebug). |
| |
| To use it, create or edit the following keys in |
| 'HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug' and/or |
| 'HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows |
| NT\CurrentVersion\AeDebug' (for x86_64 versions): |
| |
| - 'Debugger' (REG_SZ) -- a command to launch the debugger. |
| Suggested command is: 'FULLY-QUALIFIED-PATH-TO-GDB.EXE -ex |
| "attach %ld" -ex "signal-event %ld" -ex "continue"'. |
| |
| The first '%ld' will be replaced by the process ID of the |
| crashing process, the second '%ld' will be replaced by the ID |
| of the event that blocks the crashing process, waiting for GDB |
| to attach. |
| |
| - 'Auto' (REG_SZ) -- either '1' or '0'. '1' will make the |
| system run debugger specified by the Debugger key |
| automatically, '0' will cause a dialog box with "OK" and |
| "Cancel" buttons to appear, which allows the user to either |
| terminate the crashing process (OK) or debug it (Cancel). |
| |
| 'set cygwin-exceptions MODE' |
| If MODE is 'on', GDB will break on exceptions that happen inside |
| the Cygwin DLL. If MODE is 'off', GDB will delay recognition of |
| exceptions, and may ignore some exceptions which seem to be caused |
| by internal Cygwin DLL "bookkeeping". This option is meant |
| primarily for debugging the Cygwin DLL itself; the default value is |
| 'off' to avoid annoying GDB users with false 'SIGSEGV' signals. |
| |
| 'show cygwin-exceptions' |
| Displays whether GDB will break on exceptions that happen inside |
| the Cygwin DLL itself. |
| |
| 'set new-console MODE' |
| If MODE is 'on' the debuggee will be started in a new console on |
| next start. If MODE is 'off', the debuggee will be started in the |
| same console as the debugger. |
| |
| 'show new-console' |
| Displays whether a new console is used when the debuggee is |
| started. |
| |
| 'set new-group MODE' |
| This boolean value controls whether the debuggee should start a new |
| group or stay in the same group as the debugger. This affects the |
| way the Windows OS handles 'Ctrl-C'. |
| |
| 'show new-group' |
| Displays current value of new-group boolean. |
| |
| 'set debugevents' |
| This boolean value adds debug output concerning kernel events |
| related to the debuggee seen by the debugger. This includes events |
| that signal thread and process creation and exit, DLL loading and |
| unloading, console interrupts, and debugging messages produced by |
| the Windows 'OutputDebugString' API call. |
| |
| 'set debugexec' |
| This boolean value adds debug output concerning execute events |
| (such as resume thread) seen by the debugger. |
| |
| 'set debugexceptions' |
| This boolean value adds debug output concerning exceptions in the |
| debuggee seen by the debugger. |
| |
| 'set debugmemory' |
| This boolean value adds debug output concerning debuggee memory |
| reads and writes by the debugger. |
| |
| 'set shell' |
| This boolean values specifies whether the debuggee is called via a |
| shell or directly (default value is on). |
| |
| 'show shell' |
| Displays if the debuggee will be started with a shell. |
| |
| * Menu: |
| |
| * Non-debug DLL Symbols:: Support for DLLs without debugging symbols |
| |
| |
| File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native |
| |
| 21.1.4.1 Support for DLLs without Debugging Symbols |
| ................................................... |
| |
| Very often on windows, some of the DLLs that your program relies on do |
| not include symbolic debugging information (for example, |
| 'kernel32.dll'). When GDB doesn't recognize any debugging symbols in a |
| DLL, it relies on the minimal amount of symbolic information contained |
| in the DLL's export table. This section describes working with such |
| symbols, known internally to GDB as "minimal symbols". |
| |
| Note that before the debugged program has started execution, no DLLs |
| will have been loaded. The easiest way around this problem is simply to |
| start the program -- either by setting a breakpoint or letting the |
| program run once to completion. |
| |
| 21.1.4.2 DLL Name Prefixes |
| .......................... |
| |
| In keeping with the naming conventions used by the Microsoft debugging |
| tools, DLL export symbols are made available with a prefix based on the |
| DLL name, for instance 'KERNEL32!CreateFileA'. The plain name is also |
| entered into the symbol table, so 'CreateFileA' is often sufficient. In |
| some cases there will be name clashes within a program (particularly if |
| the executable itself includes full debugging symbols) necessitating the |
| use of the fully qualified name when referring to the contents of the |
| DLL. Use single-quotes around the name to avoid the exclamation mark |
| ("!") being interpreted as a language operator. |
| |
| Note that the internal name of the DLL may be all upper-case, even |
| though the file name of the DLL is lower-case, or vice-versa. Since |
| symbols within GDB are _case-sensitive_ this may cause some confusion. |
| If in doubt, try the 'info functions' and 'info variables' commands or |
| even 'maint print msymbols' (*note Symbols::). Here's an example: |
| |
| (gdb) info function CreateFileA |
| All functions matching regular expression "CreateFileA": |
| |
| Non-debugging symbols: |
| 0x77e885f4 CreateFileA |
| 0x77e885f4 KERNEL32!CreateFileA |
| |
| (gdb) info function ! |
| All functions matching regular expression "!": |
| |
| Non-debugging symbols: |
| 0x6100114c cygwin1!__assert |
| 0x61004034 cygwin1!_dll_crt0@0 |
| 0x61004240 cygwin1!dll_crt0(per_process *) |
| [etc...] |
| |
| 21.1.4.3 Working with Minimal Symbols |
| ..................................... |
| |
| Symbols extracted from a DLL's export table do not contain very much |
| type information. All that GDB can do is guess whether a symbol refers |
| to a function or variable depending on the linker section that contains |
| the symbol. Also note that the actual contents of the memory contained |
| in a DLL are not available unless the program is running. This means |
| that you cannot examine the contents of a variable or disassemble a |
| function within a DLL without a running program. |
| |
| Variables are generally treated as pointers and dereferenced |
| automatically. For this reason, it is often necessary to prefix a |
| variable name with the address-of operator ("&") and provide explicit |
| type information in the command. Here's an example of the type of |
| problem: |
| |
| (gdb) print 'cygwin1!__argv' |
| 'cygwin1!__argv' has unknown type; cast it to its declared type |
| |
| (gdb) x 'cygwin1!__argv' |
| 'cygwin1!__argv' has unknown type; cast it to its declared type |
| |
| And two possible solutions: |
| |
| (gdb) print ((char **)'cygwin1!__argv')[0] |
| $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" |
| |
| (gdb) x/2x &'cygwin1!__argv' |
| 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 |
| (gdb) x/x 0x10021608 |
| 0x10021608: 0x0022fd98 |
| (gdb) x/s 0x0022fd98 |
| 0x22fd98: "/cygdrive/c/mydirectory/myprogram" |
| |
| Setting a break point within a DLL is possible even before the |
| program starts execution. However, under these circumstances, GDB can't |
| examine the initial instructions of the function in order to skip the |
| function's frame set-up code. You can work around this by using "*&" to |
| set the breakpoint at a raw memory address: |
| |
| (gdb) break *&'python22!PyOS_Readline' |
| Breakpoint 1 at 0x1e04eff0 |
| |
| The author of these extensions is not entirely convinced that setting |
| a break point within a shared DLL like 'kernel32.dll' is completely |
| safe. |
| |
| |
| File: gdb.info, Node: Hurd Native, Next: Darwin, Prev: Cygwin Native, Up: Native |
| |
| 21.1.5 Commands Specific to GNU Hurd Systems |
| -------------------------------------------- |
| |
| This subsection describes GDB commands specific to the GNU Hurd native |
| debugging. |
| |
| 'set signals' |
| 'set sigs' |
| This command toggles the state of inferior signal interception by |
| GDB. Mach exceptions, such as breakpoint traps, are not affected |
| by this command. 'sigs' is a shorthand alias for 'signals'. |
| |
| 'show signals' |
| 'show sigs' |
| Show the current state of intercepting inferior's signals. |
| |
| 'set signal-thread' |
| 'set sigthread' |
| This command tells GDB which thread is the 'libc' signal thread. |
| That thread is run when a signal is delivered to a running process. |
| 'set sigthread' is the shorthand alias of 'set signal-thread'. |
| |
| 'show signal-thread' |
| 'show sigthread' |
| These two commands show which thread will run when the inferior is |
| delivered a signal. |
| |
| 'set stopped' |
| This commands tells GDB that the inferior process is stopped, as |
| with the 'SIGSTOP' signal. The stopped process can be continued by |
| delivering a signal to it. |
| |
| 'show stopped' |
| This command shows whether GDB thinks the debuggee is stopped. |
| |
| 'set exceptions' |
| Use this command to turn off trapping of exceptions in the |
| inferior. When exception trapping is off, neither breakpoints nor |
| single-stepping will work. To restore the default, set exception |
| trapping on. |
| |
| 'show exceptions' |
| Show the current state of trapping exceptions in the inferior. |
| |
| 'set task pause' |
| This command toggles task suspension when GDB has control. Setting |
| it to on takes effect immediately, and the task is suspended |
| whenever GDB gets control. Setting it to off will take effect the |
| next time the inferior is continued. If this option is set to off, |
| you can use 'set thread default pause on' or 'set thread pause on' |
| (see below) to pause individual threads. |
| |
| 'show task pause' |
| Show the current state of task suspension. |
| |
| 'set task detach-suspend-count' |
| This command sets the suspend count the task will be left with when |
| GDB detaches from it. |
| |
| 'show task detach-suspend-count' |
| Show the suspend count the task will be left with when detaching. |
| |
| 'set task exception-port' |
| 'set task excp' |
| This command sets the task exception port to which GDB will forward |
| exceptions. The argument should be the value of the "send rights" |
| of the task. 'set task excp' is a shorthand alias. |
| |
| 'set noninvasive' |
| This command switches GDB to a mode that is the least invasive as |
| far as interfering with the inferior is concerned. This is the |
| same as using 'set task pause', 'set exceptions', and 'set signals' |
| to values opposite to the defaults. |
| |
| 'info send-rights' |
| 'info receive-rights' |
| 'info port-rights' |
| 'info port-sets' |
| 'info dead-names' |
| 'info ports' |
| 'info psets' |
| These commands display information about, respectively, send |
| rights, receive rights, port rights, port sets, and dead names of a |
| task. There are also shorthand aliases: 'info ports' for 'info |
| port-rights' and 'info psets' for 'info port-sets'. |
| |
| 'set thread pause' |
| This command toggles current thread suspension when GDB has |
| control. Setting it to on takes effect immediately, and the |
| current thread is suspended whenever GDB gets control. Setting it |
| to off will take effect the next time the inferior is continued. |
| Normally, this command has no effect, since when GDB has control, |
| the whole task is suspended. However, if you used 'set task pause |
| off' (see above), this command comes in handy to suspend only the |
| current thread. |
| |
| 'show thread pause' |
| This command shows the state of current thread suspension. |
| |
| 'set thread run' |
| This command sets whether the current thread is allowed to run. |
| |
| 'show thread run' |
| Show whether the current thread is allowed to run. |
| |
| 'set thread detach-suspend-count' |
| This command sets the suspend count GDB will leave on a thread when |
| detaching. This number is relative to the suspend count found by |
| GDB when it notices the thread; use 'set thread |
| takeover-suspend-count' to force it to an absolute value. |
| |
| 'show thread detach-suspend-count' |
| Show the suspend count GDB will leave on the thread when detaching. |
| |
| 'set thread exception-port' |
| 'set thread excp' |
| Set the thread exception port to which to forward exceptions. This |
| overrides the port set by 'set task exception-port' (see above). |
| 'set thread excp' is the shorthand alias. |
| |
| 'set thread takeover-suspend-count' |
| Normally, GDB's thread suspend counts are relative to the value GDB |
| finds when it notices each thread. This command changes the |
| suspend counts to be absolute instead. |
| |
| 'set thread default' |
| 'show thread default' |
| Each of the above 'set thread' commands has a 'set thread default' |
| counterpart (e.g., 'set thread default pause', 'set thread default |
| exception-port', etc.). The 'thread default' variety of commands |
| sets the default thread properties for all threads; you can then |
| change the properties of individual threads with the non-default |
| commands. |
| |
| |
| File: gdb.info, Node: Darwin, Next: FreeBSD, Prev: Hurd Native, Up: Native |
| |
| 21.1.6 Darwin |
| ------------- |
| |
| GDB provides the following commands specific to the Darwin target: |
| |
| 'set debug darwin NUM' |
| When set to a non zero value, enables debugging messages specific |
| to the Darwin support. Higher values produce more verbose output. |
| |
| 'show debug darwin' |
| Show the current state of Darwin messages. |
| |
| 'set debug mach-o NUM' |
| When set to a non zero value, enables debugging messages while GDB |
| is reading Darwin object files. ("Mach-O" is the file format used |
| on Darwin for object and executable files.) Higher values produce |
| more verbose output. This is a command to diagnose problems |
| internal to GDB and should not be needed in normal usage. |
| |
| 'show debug mach-o' |
| Show the current state of Mach-O file messages. |
| |
| 'set mach-exceptions on' |
| 'set mach-exceptions off' |
| On Darwin, faults are first reported as a Mach exception and are |
| then mapped to a Posix signal. Use this command to turn on |
| trapping of Mach exceptions in the inferior. This might be |
| sometimes useful to better understand the cause of a fault. The |
| default is off. |
| |
| 'show mach-exceptions' |
| Show the current state of exceptions trapping. |
| |
| |
| File: gdb.info, Node: FreeBSD, Prev: Darwin, Up: Native |
| |
| 21.1.7 FreeBSD |
| -------------- |
| |
| When the ABI of a system call is changed in the FreeBSD kernel, this is |
| implemented by leaving a compatibility system call using the old ABI at |
| the existing number and allocating a new system call number for the |
| version using the new ABI. As a convenience, when a system call is |
| caught by name (*note catch syscall::), compatibility system calls are |
| also caught. |
| |
| For example, FreeBSD 12 introduced a new variant of the 'kevent' |
| system call and catching the 'kevent' system call by name catches both |
| variants: |
| |
| (gdb) catch syscall kevent |
| Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560]) |
| (gdb) |
| |
| |
| File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations |
| |
| 21.2 Embedded Operating Systems |
| =============================== |
| |
| This section describes configurations involving the debugging of |
| embedded operating systems that are available for several different |
| architectures. |
| |
| GDB includes the ability to debug programs running on various |
| real-time operating systems. |
| |
| |
| File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations |
| |
| 21.3 Embedded Processors |
| ======================== |
| |
| This section goes into details specific to particular embedded |
| configurations. |
| |
| Whenever a specific embedded processor has a simulator, GDB allows to |
| send an arbitrary command to the simulator. |
| |
| 'sim COMMAND' |
| Send an arbitrary COMMAND string to the simulator. Consult the |
| documentation for the specific simulator in use for information |
| about acceptable commands. |
| |
| * Menu: |
| |
| * ARC:: Synopsys ARC |
| * ARM:: ARM |
| * M68K:: Motorola M68K |
| * MicroBlaze:: Xilinx MicroBlaze |
| * MIPS Embedded:: MIPS Embedded |
| * OpenRISC 1000:: OpenRISC 1000 (or1k) |
| * PowerPC Embedded:: PowerPC Embedded |
| * AVR:: Atmel AVR |
| * CRIS:: CRIS |
| * Super-H:: Renesas Super-H |
| |
| |
| File: gdb.info, Node: ARC, Next: ARM, Up: Embedded Processors |
| |
| 21.3.1 Synopsys ARC |
| ------------------- |
| |
| GDB provides the following ARC-specific commands: |
| |
| 'set debug arc' |
| Control the level of ARC specific debug messages. Use 0 for no |
| messages (the default), 1 for debug messages, and 2 for even more |
| debug messages. |
| |
| 'show debug arc' |
| Show the level of ARC specific debugging in operation. |
| |
| 'maint print arc arc-instruction ADDRESS' |
| Print internal disassembler information about instruction at a |
| given address. |
| |
| |
| File: gdb.info, Node: ARM, Next: M68K, Prev: ARC, Up: Embedded Processors |
| |
| 21.3.2 ARM |
| ---------- |
| |
| GDB provides the following ARM-specific commands: |
| |
| 'set arm disassembler' |
| This commands selects from a list of disassembly styles. The |
| '"std"' style is the standard style. |
| |
| 'show arm disassembler' |
| Show the current disassembly style. |
| |
| 'set arm apcs32' |
| This command toggles ARM operation mode between 32-bit and 26-bit. |
| |
| 'show arm apcs32' |
| Display the current usage of the ARM 32-bit mode. |
| |
| 'set arm fpu FPUTYPE' |
| This command sets the ARM floating-point unit (FPU) type. The |
| argument FPUTYPE can be one of these: |
| |
| 'auto' |
| Determine the FPU type by querying the OS ABI. |
| 'softfpa' |
| Software FPU, with mixed-endian doubles on little-endian ARM |
| processors. |
| 'fpa' |
| GCC-compiled FPA co-processor. |
| 'softvfp' |
| Software FPU with pure-endian doubles. |
| 'vfp' |
| VFP co-processor. |
| |
| 'show arm fpu' |
| Show the current type of the FPU. |
| |
| 'set arm abi' |
| This command forces GDB to use the specified ABI. |
| |
| 'show arm abi' |
| Show the currently used ABI. |
| |
| 'set arm fallback-mode (arm|thumb|auto)' |
| GDB uses the symbol table, when available, to determine whether |
| instructions are ARM or Thumb. This command controls GDB's default |
| behavior when the symbol table is not available. The default is |
| 'auto', which causes GDB to use the current execution mode (from |
| the 'T' bit in the 'CPSR' register). |
| |
| 'show arm fallback-mode' |
| Show the current fallback instruction mode. |
| |
| 'set arm force-mode (arm|thumb|auto)' |
| This command overrides use of the symbol table to determine whether |
| instructions are ARM or Thumb. The default is 'auto', which causes |
| GDB to use the symbol table and then the setting of 'set arm |
| fallback-mode'. |
| |
| 'show arm force-mode' |
| Show the current forced instruction mode. |
| |
| 'set debug arm' |
| Toggle whether to display ARM-specific debugging messages from the |
| ARM target support subsystem. |
| |
| 'show debug arm' |
| Show whether ARM-specific debugging messages are enabled. |
| |
| 'target sim [SIMARGS] ...' |
| The GDB ARM simulator accepts the following optional arguments. |
| |
| '--swi-support=TYPE' |
| Tell the simulator which SWI interfaces to support. The |
| argument TYPE may be a comma separated list of the following |
| values. The default value is 'all'. |
| |
| 'none' |
| 'demon' |
| 'angel' |
| 'redboot' |
| 'all' |
| |
| |
| File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: ARM, Up: Embedded Processors |
| |
| 21.3.3 M68k |
| ----------- |
| |
| The Motorola m68k configuration includes ColdFire support. |
| |
| |
| File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors |
| |
| 21.3.4 MicroBlaze |
| ----------------- |
| |
| The MicroBlaze is a soft-core processor supported on various Xilinx |
| FPGAs, such as Spartan or Virtex series. Boards with these processors |
| usually have JTAG ports which connect to a host system running the |
| Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). |
| This host system is used to download the configuration bitstream to the |
| target FPGA. The Xilinx Microprocessor Debugger (XMD) program |
| communicates with the target board using the JTAG interface and presents |
| a 'gdbserver' interface to the board. By default 'xmd' uses port |
| '1234'. (While it is possible to change this default port, it requires |
| the use of undocumented 'xmd' commands. Contact Xilinx support if you |
| need to do this.) |
| |
| Use these GDB commands to connect to the MicroBlaze target processor. |
| |
| 'target remote :1234' |
| Use this command to connect to the target if you are running GDB on |
| the same system as 'xmd'. |
| |
| 'target remote XMD-HOST:1234' |
| Use this command to connect to the target if it is connected to |
| 'xmd' running on a different system named XMD-HOST. |
| |
| 'load' |
| Use this command to download a program to the MicroBlaze target. |
| |
| 'set debug microblaze N' |
| Enable MicroBlaze-specific debugging messages if non-zero. |
| |
| 'show debug microblaze N' |
| Show MicroBlaze-specific debugging level. |
| |
| |
| File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors |
| |
| 21.3.5 MIPS Embedded |
| -------------------- |
| |
| GDB supports these special commands for MIPS targets: |
| |
| 'set mipsfpu double' |
| 'set mipsfpu single' |
| 'set mipsfpu none' |
| 'set mipsfpu auto' |
| 'show mipsfpu' |
| If your target board does not support the MIPS floating point |
| coprocessor, you should use the command 'set mipsfpu none' (if you |
| need this, you may wish to put the command in your GDB init file). |
| This tells GDB how to find the return value of functions which |
| return floating point values. It also allows GDB to avoid saving |
| the floating point registers when calling functions on the board. |
| If you are using a floating point coprocessor with only single |
| precision floating point support, as on the R4650 processor, use |
| the command 'set mipsfpu single'. The default double precision |
| floating point coprocessor may be selected using 'set mipsfpu |
| double'. |
| |
| In previous versions the only choices were double precision or no |
| floating point, so 'set mipsfpu on' will select double precision |
| and 'set mipsfpu off' will select no floating point. |
| |
| As usual, you can inquire about the 'mipsfpu' variable with 'show |
| mipsfpu'. |
| |
| |
| File: gdb.info, Node: OpenRISC 1000, Next: PowerPC Embedded, Prev: MIPS Embedded, Up: Embedded Processors |
| |
| 21.3.6 OpenRISC 1000 |
| -------------------- |
| |
| The OpenRISC 1000 provides a free RISC instruction set architecture. It |
| is mainly provided as a soft-core which can run on Xilinx, Altera and |
| other FPGA's. |
| |
| GDB for OpenRISC supports the below commands when connecting to a |
| target: |
| |
| 'target sim' |
| |
| Runs the builtin CPU simulator which can run very basic programs |
| but does not support most hardware functions like MMU. For more |
| complex use cases the user is advised to run an external target, |
| and connect using 'target remote'. |
| |
| Example: 'target sim' |
| |
| 'set debug or1k' |
| Toggle whether to display OpenRISC-specific debugging messages from |
| the OpenRISC target support subsystem. |
| |
| 'show debug or1k' |
| Show whether OpenRISC-specific debugging messages are enabled. |
| |
| |
| File: gdb.info, Node: PowerPC Embedded, Next: AVR, Prev: OpenRISC 1000, Up: Embedded Processors |
| |
| 21.3.7 PowerPC Embedded |
| ----------------------- |
| |
| GDB supports using the DVC (Data Value Compare) register to implement in |
| hardware simple hardware watchpoint conditions of the form: |
| |
| (gdb) watch ADDRESS|VARIABLE \ |
| if ADDRESS|VARIABLE == CONSTANT EXPRESSION |
| |
| The DVC register will be automatically used when GDB detects such |
| pattern in a condition expression, and the created watchpoint uses one |
| debug register (either the 'exact-watchpoints' option is on and the |
| variable is scalar, or the variable has a length of one byte). This |
| feature is available in native GDB running on a Linux kernel version |
| 2.6.34 or newer. |
| |
| When running on PowerPC embedded processors, GDB automatically uses |
| ranged hardware watchpoints, unless the 'exact-watchpoints' option is |
| on, in which case watchpoints using only one debug register are created |
| when watching variables of scalar types. |
| |
| You can create an artificial array to watch an arbitrary memory |
| region using one of the following commands (*note Expressions::): |
| |
| (gdb) watch *((char *) ADDRESS)@LENGTH |
| (gdb) watch {char[LENGTH]} ADDRESS |
| |
| PowerPC embedded processors support masked watchpoints. See the |
| discussion about the 'mask' argument in *note Set Watchpoints::. |
| |
| PowerPC embedded processors support hardware accelerated "ranged |
| breakpoints". A ranged breakpoint stops execution of the inferior |
| whenever it executes an instruction at any address within the range it |
| specifies. To set a ranged breakpoint in GDB, use the 'break-range' |
| command. |
| |
| GDB provides the following PowerPC-specific commands: |
| |
| 'break-range START-LOCATION, END-LOCATION' |
| Set a breakpoint for an address range given by START-LOCATION and |
| END-LOCATION, which can specify a function name, a line number, an |
| offset of lines from the current line or from the start location, |
| or an address of an instruction (see *note Specify Location::, for |
| a list of all the possible ways to specify a LOCATION.) The |
| breakpoint will stop execution of the inferior whenever it executes |
| an instruction at any address within the specified range, |
| (including START-LOCATION and END-LOCATION.) |
| |
| 'set powerpc soft-float' |
| 'show powerpc soft-float' |
| Force GDB to use (or not use) a software floating point calling |
| convention. By default, GDB selects the calling convention based |
| on the selected architecture and the provided executable file. |
| |
| 'set powerpc vector-abi' |
| 'show powerpc vector-abi' |
| Force GDB to use the specified calling convention for vector |
| arguments and return values. The valid options are 'auto'; |
| 'generic', to avoid vector registers even if they are present; |
| 'altivec', to use AltiVec registers; and 'spe' to use SPE |
| registers. By default, GDB selects the calling convention based on |
| the selected architecture and the provided executable file. |
| |
| 'set powerpc exact-watchpoints' |
| 'show powerpc exact-watchpoints' |
| Allow GDB to use only one debug register when watching a variable |
| of scalar type, thus assuming that the variable is accessed through |
| the address of its first byte. |
| |
| |
| File: gdb.info, Node: AVR, Next: CRIS, Prev: PowerPC Embedded, Up: Embedded Processors |
| |
| 21.3.8 Atmel AVR |
| ---------------- |
| |
| When configured for debugging the Atmel AVR, GDB supports the following |
| AVR-specific commands: |
| |
| 'info io_registers' |
| This command displays information about the AVR I/O registers. For |
| each register, GDB prints its number and value. |
| |
| |
| File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors |
| |
| 21.3.9 CRIS |
| ----------- |
| |
| When configured for debugging CRIS, GDB provides the following |
| CRIS-specific commands: |
| |
| 'set cris-version VER' |
| Set the current CRIS version to VER, either '10' or '32'. The CRIS |
| version affects register names and sizes. This command is useful |
| in case autodetection of the CRIS version fails. |
| |
| 'show cris-version' |
| Show the current CRIS version. |
| |
| 'set cris-dwarf2-cfi' |
| Set the usage of DWARF-2 CFI for CRIS debugging. The default is |
| 'on'. Change to 'off' when using 'gcc-cris' whose version is below |
| 'R59'. |
| |
| 'show cris-dwarf2-cfi' |
| Show the current state of using DWARF-2 CFI. |
| |
| 'set cris-mode MODE' |
| Set the current CRIS mode to MODE. It should only be changed when |
| debugging in guru mode, in which case it should be set to 'guru' |
| (the default is 'normal'). |
| |
| 'show cris-mode' |
| Show the current CRIS mode. |
| |
| |
| File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors |
| |
| 21.3.10 Renesas Super-H |
| ----------------------- |
| |
| For the Renesas Super-H processor, GDB provides these commands: |
| |
| 'set sh calling-convention CONVENTION' |
| Set the calling-convention used when calling functions from GDB. |
| Allowed values are 'gcc', which is the default setting, and |
| 'renesas'. With the 'gcc' setting, functions are called using the |
| GCC calling convention. If the DWARF-2 information of the called |
| function specifies that the function follows the Renesas calling |
| convention, the function is called using the Renesas calling |
| convention. If the calling convention is set to 'renesas', the |
| Renesas calling convention is always used, regardless of the |
| DWARF-2 information. This can be used to override the default of |
| 'gcc' if debug information is missing, or the compiler does not |
| emit the DWARF-2 calling convention entry for a function. |
| |
| 'show sh calling-convention' |
| Show the current calling convention setting. |
| |
| |
| File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations |
| |
| 21.4 Architectures |
| ================== |
| |
| This section describes characteristics of architectures that affect all |
| uses of GDB with the architecture, both native and cross. |
| |
| * Menu: |
| |
| * AArch64:: |
| * i386:: |
| * Alpha:: |
| * MIPS:: |
| * HPPA:: HP PA architecture |
| * PowerPC:: |
| * Nios II:: |
| * Sparc64:: |
| * S12Z:: |
| |
| |
| File: gdb.info, Node: AArch64, Next: i386, Up: Architectures |
| |
| 21.4.1 AArch64 |
| -------------- |
| |
| When GDB is debugging the AArch64 architecture, it provides the |
| following special commands: |
| |
| 'set debug aarch64' |
| This command determines whether AArch64 architecture-specific |
| debugging messages are to be displayed. |
| |
| 'show debug aarch64' |
| Show whether AArch64 debugging messages are displayed. |
| |
| 21.4.1.1 AArch64 SVE. |
| ..................... |
| |
| When GDB is debugging the AArch64 architecture, if the Scalable Vector |
| Extension (SVE) is present, then GDB will provide the vector registers |
| '$z0' through '$z31', vector predicate registers '$p0' through '$p15', |
| and the '$ffr' register. In addition, the pseudo register '$vg' will be |
| provided. This is the vector granule for the current thread and |
| represents the number of 64-bit chunks in an SVE 'z' register. |
| |
| If the vector length changes, then the '$vg' register will be |
| updated, but the lengths of the 'z' and 'p' registers will not change. |
| This is a known limitation of GDB and does not affect the execution of |
| the target process. |
| |
| 21.4.1.2 AArch64 Pointer Authentication. |
| ........................................ |
| |
| When GDB is debugging the AArch64 architecture, and the program is using |
| the v8.3-A feature Pointer Authentication (PAC), then whenever the link |
| register '$lr' is pointing to an PAC function its value will be masked. |
| When GDB prints a backtrace, any addresses that required unmasking will |
| be postfixed with the marker [PAC]. When using the MI, this is printed |
| as part of the 'addr_flags' field. |
| |
| |
| File: gdb.info, Node: i386, Next: Alpha, Prev: AArch64, Up: Architectures |
| |
| 21.4.2 x86 Architecture-specific Issues |
| --------------------------------------- |
| |
| 'set struct-convention MODE' |
| Set the convention used by the inferior to return 'struct's and |
| 'union's from functions to MODE. Possible values of MODE are |
| '"pcc"', '"reg"', and '"default"' (the default). '"default"' or |
| '"pcc"' means that 'struct's are returned on the stack, while |
| '"reg"' means that a 'struct' or a 'union' whose size is 1, 2, 4, |
| or 8 bytes will be returned in a register. |
| |
| 'show struct-convention' |
| Show the current setting of the convention to return 'struct's from |
| functions. |
| |
| 21.4.2.1 Intel "Memory Protection Extensions" (MPX). |
| .................................................... |
| |
| Memory Protection Extension (MPX) adds the bound registers 'BND0' (1) |
| through 'BND3'. Bound registers store a pair of 64-bit values which are |
| the lower bound and upper bound. Bounds are effective addresses or |
| memory locations. The upper bounds are architecturally represented in |
| 1's complement form. A bound having lower bound = 0, and upper bound = |
| 0 (1's complement of all bits set) will allow access to the entire |
| address space. |
| |
| 'BND0' through 'BND3' are represented in GDB as 'bnd0raw' through |
| 'bnd3raw'. Pseudo registers 'bnd0' through 'bnd3' display the upper |
| bound performing the complement of one operation on the upper bound |
| value, i.e. when upper bound in 'bnd0raw' is 0 in the GDB 'bnd0' it will |
| be '0xfff...'. In this sense it can also be noted that the upper bounds |
| are inclusive. |
| |
| As an example, assume that the register BND0 holds bounds for a |
| pointer having access allowed for the range between 0x32 and 0x71. The |
| values present on bnd0raw and bnd registers are presented as follows: |
| |
| bnd0raw = {0x32, 0xffffffff8e} |
| bnd0 = {lbound = 0x32, ubound = 0x71} : size 64 |
| |
| This way the raw value can be accessed via bnd0raw...bnd3raw. Any |
| change on bnd0...bnd3 or bnd0raw...bnd3raw is reflect on its |
| counterpart. When the bnd0...bnd3 registers are displayed via Python, |
| the display includes the memory size, in bits, accessible to the |
| pointer. |
| |
| Bounds can also be stored in bounds tables, which are stored in |
| application memory. These tables store bounds for pointers by |
| specifying the bounds pointer's value along with its bounds. Evaluating |
| and changing bounds located in bound tables is therefore interesting |
| while investigating bugs on MPX context. GDB provides commands for this |
| purpose: |
| |
| 'show mpx bound POINTER' |
| Display bounds of the given POINTER. |
| |
| 'set mpx bound POINTER, LBOUND, UBOUND' |
| Set the bounds of a pointer in the bound table. This command takes |
| three parameters: POINTER is the pointers whose bounds are to be |
| changed, LBOUND and UBOUND are new values for lower and upper |
| bounds respectively. |
| |
| When you call an inferior function on an Intel MPX enabled program, |
| GDB sets the inferior's bound registers to the init (disabled) state |
| before calling the function. As a consequence, bounds checks for the |
| pointer arguments passed to the function will always pass. |
| |
| This is necessary because when you call an inferior function, the |
| program is usually in the middle of the execution of other function. |
| Since at that point bound registers are in an arbitrary state, not |
| clearing them would lead to random bound violations in the called |
| function. |
| |
| You can still examine the influence of the bound registers on the |
| execution of the called function by stopping the execution of the called |
| function at its prologue, setting bound registers, and continuing the |
| execution. For example: |
| |
| $ break *upper |
| Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47. |
| $ print upper (a, b, c, d, 1) |
| Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48).... |
| $ print $bnd0 |
| {lbound = 0x0, ubound = ffffffff} : size -1 |
| |
| At this last step the value of bnd0 can be changed for investigation |
| of bound violations caused along the execution of the call. In order to |
| know how to set the bound registers or bound table for the call consult |
| the ABI. |
| |
| ---------- Footnotes ---------- |
| |
| (1) The register named with capital letters represent the |
| architecture registers. |
| |
| |
| File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures |
| |
| 21.4.3 Alpha |
| ------------ |
| |
| See the following section. |
| |
| |
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
| |
| 21.4.4 MIPS |
| ----------- |
| |
| Alpha- and MIPS-based computers use an unusual stack frame, which |
| sometimes requires GDB to search backward in the object code to find the |
| beginning of a function. |
| |
| To improve response time (especially for embedded applications, where |
| GDB may be restricted to a slow serial line for this search) you may |
| want to limit the size of this search, using one of these commands: |
| |
| 'set heuristic-fence-post LIMIT' |
| Restrict GDB to examining at most LIMIT bytes in its search for the |
| beginning of a function. A value of 0 (the default) means there is |
| no limit. However, except for 0, the larger the limit the more |
| bytes 'heuristic-fence-post' must search and therefore the longer |
| it takes to run. You should only need to use this command when |
| debugging a stripped executable. |
| |
| 'show heuristic-fence-post' |
| Display the current limit. |
| |
| These commands are available _only_ when GDB is configured for debugging |
| programs on Alpha or MIPS processors. |
| |
| Several MIPS-specific commands are available when debugging MIPS |
| programs: |
| |
| 'set mips abi ARG' |
| Tell GDB which MIPS ABI is used by the inferior. Possible values |
| of ARG are: |
| |
| 'auto' |
| The default ABI associated with the current binary (this is |
| the default). |
| 'o32' |
| 'o64' |
| 'n32' |
| 'n64' |
| 'eabi32' |
| 'eabi64' |
| |
| 'show mips abi' |
| Show the MIPS ABI used by GDB to debug the inferior. |
| |
| 'set mips compression ARG' |
| Tell GDB which MIPS compressed ISA (Instruction Set Architecture) |
| encoding is used by the inferior. GDB uses this for code |
| disassembly and other internal interpretation purposes. This |
| setting is only referred to when no executable has been associated |
| with the debugging session or the executable does not provide |
| information about the encoding it uses. Otherwise this setting is |
| automatically updated from information provided by the executable. |
| |
| Possible values of ARG are 'mips16' and 'micromips'. The default |
| compressed ISA encoding is 'mips16', as executables containing |
| MIPS16 code frequently are not identified as such. |
| |
| This setting is "sticky"; that is, it retains its value across |
| debugging sessions until reset either explicitly with this command |
| or implicitly from an executable. |
| |
| The compiler and/or assembler typically add symbol table |
| annotations to identify functions compiled for the MIPS16 or |
| microMIPS ISAs. If these function-scope annotations are present, |
| GDB uses them in preference to the global compressed ISA encoding |
| setting. |
| |
| 'show mips compression' |
| Show the MIPS compressed ISA encoding used by GDB to debug the |
| inferior. |
| |
| 'set mipsfpu' |
| 'show mipsfpu' |
| *Note set mipsfpu: MIPS Embedded. |
| |
| 'set mips mask-address ARG' |
| This command determines whether the most-significant 32 bits of |
| 64-bit MIPS addresses are masked off. The argument ARG can be |
| 'on', 'off', or 'auto'. The latter is the default setting, which |
| lets GDB determine the correct value. |
| |
| 'show mips mask-address' |
| Show whether the upper 32 bits of MIPS addresses are masked off or |
| not. |
| |
| 'set remote-mips64-transfers-32bit-regs' |
| This command controls compatibility with 64-bit MIPS targets that |
| transfer data in 32-bit quantities. If you have an old MIPS 64 |
| target that transfers 32 bits for some registers, like SR and FSR, |
| and 64 bits for other registers, set this option to 'on'. |
| |
| 'show remote-mips64-transfers-32bit-regs' |
| Show the current setting of compatibility with older MIPS 64 |
| targets. |
| |
| 'set debug mips' |
| This command turns on and off debugging messages for the |
| MIPS-specific target code in GDB. |
| |
| 'show debug mips' |
| Show the current setting of MIPS debugging messages. |
| |
| |
| File: gdb.info, Node: HPPA, Next: PowerPC, Prev: MIPS, Up: Architectures |
| |
| 21.4.5 HPPA |
| ----------- |
| |
| When GDB is debugging the HP PA architecture, it provides the following |
| special commands: |
| |
| 'set debug hppa' |
| This command determines whether HPPA architecture-specific |
| debugging messages are to be displayed. |
| |
| 'show debug hppa' |
| Show whether HPPA debugging messages are displayed. |
| |
| 'maint print unwind ADDRESS' |
| This command displays the contents of the unwind table entry at the |
| given ADDRESS. |
| |
| |
| File: gdb.info, Node: PowerPC, Next: Nios II, Prev: HPPA, Up: Architectures |
| |
| 21.4.6 PowerPC |
| -------------- |
| |
| When GDB is debugging the PowerPC architecture, it provides a set of |
| pseudo-registers to enable inspection of 128-bit wide Decimal Floating |
| Point numbers stored in the floating point registers. These values must |
| be stored in two consecutive registers, always starting at an even |
| register like 'f0' or 'f2'. |
| |
| The pseudo-registers go from '$dl0' through '$dl15', and are formed |
| by joining the even/odd register pairs 'f0' and 'f1' for '$dl0', 'f2' |
| and 'f3' for '$dl1' and so on. |
| |
| For POWER7 processors, GDB provides a set of pseudo-registers, the |
| 64-bit wide Extended Floating Point Registers ('f32' through 'f63'). |
| |
| |
| File: gdb.info, Node: Nios II, Next: Sparc64, Prev: PowerPC, Up: Architectures |
| |
| 21.4.7 Nios II |
| -------------- |
| |
| When GDB is debugging the Nios II architecture, it provides the |
| following special commands: |
| |
| 'set debug nios2' |
| This command turns on and off debugging messages for the Nios II |
| target code in GDB. |
| |
| 'show debug nios2' |
| Show the current setting of Nios II debugging messages. |
| |
| |
| File: gdb.info, Node: Sparc64, Next: S12Z, Prev: Nios II, Up: Architectures |
| |
| 21.4.8 Sparc64 |
| -------------- |
| |
| 21.4.8.1 ADI Support |
| .................... |
| |
| The M7 processor supports an Application Data Integrity (ADI) feature |
| that detects invalid data accesses. When software allocates memory and |
| enables ADI on the allocated memory, it chooses a 4-bit version number, |
| sets the version in the upper 4 bits of the 64-bit pointer to that data, |
| and stores the 4-bit version in every cacheline of that data. Hardware |
| saves the latter in spare bits in the cache and memory hierarchy. On |
| each load and store, the processor compares the upper 4 VA (virtual |
| address) bits to the cacheline's version. If there is a mismatch, the |
| processor generates a version mismatch trap which can be either precise |
| or disrupting. The trap is an error condition which the kernel delivers |
| to the process as a SIGSEGV signal. |
| |
| Note that only 64-bit applications can use ADI and need to be built |
| with ADI-enabled. |
| |
| Values of the ADI version tags, which are in granularity of a |
| cacheline (64 bytes), can be viewed or modified. |
| |
| 'adi (examine | x) [ / N ] ADDR' |
| |
| The 'adi examine' command displays the value of one ADI version tag |
| per cacheline. |
| |
| N is a decimal integer specifying the number in bytes; the default |
| is 1. It specifies how much ADI version information, at the ratio |
| of 1:ADI block size, to display. |
| |
| ADDR is the address in user address space where you want GDB to |
| begin displaying the ADI version tags. |
| |
| Below is an example of displaying ADI versions of variable |
| "shmaddr". |
| |
| (gdb) adi x/100 shmaddr |
| 0xfff800010002c000: 0 0 |
| |
| 'adi (assign | a) [ / N ] ADDR = TAG' |
| |
| The 'adi assign' command is used to assign new ADI version tag to |
| an address. |
| |
| N is a decimal integer specifying the number in bytes; the default |
| is 1. It specifies how much ADI version information, at the ratio |
| of 1:ADI block size, to modify. |
| |
| ADDR is the address in user address space where you want GDB to |
| begin modifying the ADI version tags. |
| |
| TAG is the new ADI version tag. |
| |
| For example, do the following to modify then verify ADI versions of |
| variable "shmaddr": |
| |
| (gdb) adi a/100 shmaddr = 7 |
| (gdb) adi x/100 shmaddr |
| 0xfff800010002c000: 7 7 |
| |
| |
| File: gdb.info, Node: S12Z, Prev: Sparc64, Up: Architectures |
| |
| 21.4.9 S12Z |
| ----------- |
| |
| When GDB is debugging the S12Z architecture, it provides the following |
| special command: |
| |
| 'maint info bdccsr' |
| This command displays the current value of the microprocessor's |
| BDCCSR register. |
| |
| |
| File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top |
| |
| 22 Controlling GDB |
| ****************** |
| |
| You can alter the way GDB interacts with you by using the 'set' command. |
| For commands controlling how GDB displays data, see *note Print |
| Settings: Print Settings. Other settings are described here. |
| |
| * Menu: |
| |
| * Prompt:: Prompt |
| * Editing:: Command editing |
| * Command History:: Command history |
| * Screen Size:: Screen size |
| * Output Styling:: Output styling |
| * Numbers:: Numbers |
| * ABI:: Configuring the current ABI |
| * Auto-loading:: Automatically loading associated files |
| * Messages/Warnings:: Optional warnings and messages |
| * Debugging Output:: Optional messages about internal happenings |
| * Other Misc Settings:: Other Miscellaneous Settings |
| |
| |
| File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB |
| |
| 22.1 Prompt |
| =========== |
| |
| GDB indicates its readiness to read a command by printing a string |
| called the "prompt". This string is normally '(gdb)'. You can change |
| the prompt string with the 'set prompt' command. For instance, when |
| debugging GDB with GDB, it is useful to change the prompt in one of the |
| GDB sessions so that you can always tell which one you are talking to. |
| |
| _Note:_ 'set prompt' does not add a space for you after the prompt |
| you set. This allows you to set a prompt which ends in a space or a |
| prompt that does not. |
| |
| 'set prompt NEWPROMPT' |
| Directs GDB to use NEWPROMPT as its prompt string henceforth. |
| |
| 'show prompt' |
| Prints a line of the form: 'Gdb's prompt is: YOUR-PROMPT' |
| |
| Versions of GDB that ship with Python scripting enabled have prompt |
| extensions. The commands for interacting with these extensions are: |
| |
| 'set extended-prompt PROMPT' |
| Set an extended prompt that allows for substitutions. *Note |
| gdb.prompt::, for a list of escape sequences that can be used for |
| substitution. Any escape sequences specified as part of the prompt |
| string are replaced with the corresponding strings each time the |
| prompt is displayed. |
| |
| For example: |
| |
| set extended-prompt Current working directory: \w (gdb) |
| |
| Note that when an extended-prompt is set, it takes control of the |
| PROMPT_HOOK hook. *Note prompt_hook::, for further information. |
| |
| 'show extended-prompt' |
| Prints the extended prompt. Any escape sequences specified as part |
| of the prompt string with 'set extended-prompt', are replaced with |
| the corresponding strings each time the prompt is displayed. |
| |
| |
| File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB |
| |
| 22.2 Command Editing |
| ==================== |
| |
| GDB reads its input commands via the "Readline" interface. This GNU |
| library provides consistent behavior for programs which provide a |
| command line interface to the user. Advantages are GNU Emacs-style or |
| "vi"-style inline editing of commands, 'csh'-like history substitution, |
| and a storage and recall of command history across debugging sessions. |
| |
| You may control the behavior of command line editing in GDB with the |
| command 'set'. |
| |
| 'set editing' |
| 'set editing on' |
| Enable command line editing (enabled by default). |
| |
| 'set editing off' |
| Disable command line editing. |
| |
| 'show editing' |
| Show whether command line editing is enabled. |
| |
| *Note Command Line Editing::, for more details about the Readline |
| interface. Users unfamiliar with GNU Emacs or 'vi' are encouraged to |
| read that chapter. |
| |
| GDB sets the Readline application name to 'gdb'. This is useful for |
| conditions in '.inputrc'. |
| |
| GDB defines a bindable Readline command, 'operate-and-get-next'. |
| This is bound to 'C-o' by default. This command accepts the current |
| line for execution and fetches the next line relative to the current |
| line from the history for editing. Any argument is ignored. |
| |
| |
| File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB |
| |
| 22.3 Command History |
| ==================== |
| |
| GDB can keep track of the commands you type during your debugging |
| sessions, so that you can be certain of precisely what happened. Use |
| these commands to manage the GDB command history facility. |
| |
| GDB uses the GNU History library, a part of the Readline package, to |
| provide the history facility. *Note Using History Interactively::, for |
| the detailed description of the History library. |
| |
| To issue a command to GDB without affecting certain aspects of the |
| state which is seen by users, prefix it with 'server ' (*note Server |
| Prefix::). This means that this command will not affect the command |
| history, nor will it affect GDB's notion of which command to repeat if |
| <RET> is pressed on a line by itself. |
| |
| The server prefix does not affect the recording of values into the |
| value history; to print a value without recording it into the value |
| history, use the 'output' command instead of the 'print' command. |
| |
| Here is the description of GDB commands related to command history. |
| |
| 'set history filename FNAME' |
| Set the name of the GDB command history file to FNAME. This is the |
| file where GDB reads an initial command history list, and where it |
| writes the command history from this session when it exits. You |
| can access this list through history expansion or through the |
| history command editing characters listed below. This file |
| defaults to the value of the environment variable 'GDBHISTFILE', or |
| to './.gdb_history' ('./_gdb_history' on MS-DOS) if this variable |
| is not set. |
| |
| 'set history save' |
| 'set history save on' |
| Record command history in a file, whose name may be specified with |
| the 'set history filename' command. By default, this option is |
| disabled. |
| |
| 'set history save off' |
| Stop recording command history in a file. |
| |
| 'set history size SIZE' |
| 'set history size unlimited' |
| Set the number of commands which GDB keeps in its history list. |
| This defaults to the value of the environment variable |
| 'GDBHISTSIZE', or to 256 if this variable is not set. Non-numeric |
| values of 'GDBHISTSIZE' are ignored. If SIZE is 'unlimited' or if |
| 'GDBHISTSIZE' is either a negative number or the empty string, then |
| the number of commands GDB keeps in the history list is unlimited. |
| |
| 'set history remove-duplicates COUNT' |
| 'set history remove-duplicates unlimited' |
| Control the removal of duplicate history entries in the command |
| history list. If COUNT is non-zero, GDB will look back at the last |
| COUNT history entries and remove the first entry that is a |
| duplicate of the current entry being added to the command history |
| list. If COUNT is 'unlimited' then this lookbehind is unbounded. |
| If COUNT is 0, then removal of duplicate history entries is |
| disabled. |
| |
| Only history entries added during the current session are |
| considered for removal. This option is set to 0 by default. |
| |
| History expansion assigns special meaning to the character '!'. |
| *Note Event Designators::, for more details. |
| |
| Since '!' is also the logical not operator in C, history expansion is |
| off by default. If you decide to enable history expansion with the 'set |
| history expansion on' command, you may sometimes need to follow '!' |
| (when it is used as logical not, in an expression) with a space or a tab |
| to prevent it from being expanded. The readline history facilities do |
| not attempt substitution on the strings '!=' and '!(', even when history |
| expansion is enabled. |
| |
| The commands to control history expansion are: |
| |
| 'set history expansion on' |
| 'set history expansion' |
| Enable history expansion. History expansion is off by default. |
| |
| 'set history expansion off' |
| Disable history expansion. |
| |
| 'show history' |
| 'show history filename' |
| 'show history save' |
| 'show history size' |
| 'show history expansion' |
| These commands display the state of the GDB history parameters. |
| 'show history' by itself displays all four states. |
| |
| 'show commands' |
| Display the last ten commands in the command history. |
| |
| 'show commands N' |
| Print ten commands centered on command number N. |
| |
| 'show commands +' |
| Print ten commands just after the commands last printed. |
| |