7218 lines
293 KiB
Plaintext
7218 lines
293 KiB
Plaintext
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.2.
|
||
|
||
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.
|
||
|