This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
|
|
INFO-DIR-SECTION Programming & development tools.
|
INFO-DIR-SECTION Programming & development tools.
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb: (gdb). The GNU debugger.
|
* Gdb: (gdb). The GNU debugger.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
|
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
Permission is granted to make and distribute verbatim copies of this
|
manual provided the copyright notice and this permission notice are
|
manual provided the copyright notice and this permission notice are
|
preserved on all copies.
|
preserved on all copies.
|
|
|
Permission is granted to copy and distribute modified versions of
|
Permission is granted to copy and distribute modified versions of
|
this manual under the conditions for verbatim copying, provided also
|
this manual under the conditions for verbatim copying, provided also
|
that the entire resulting derived work is distributed under the terms
|
that the entire resulting derived work is distributed under the terms
|
of a permission notice identical to this one.
|
of a permission notice identical to this one.
|
|
|
Permission is granted to copy and distribute translations of this
|
Permission is granted to copy and distribute translations of this
|
manual into another language, under the above conditions for modified
|
manual into another language, under the above conditions for modified
|
versions.
|
versions.
|
|
|
|
|
File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
|
File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
|
|
|
Examining the Symbol Table
|
Examining the Symbol Table
|
**************************
|
**************************
|
|
|
The commands described in this chapter allow you to inquire about the
|
The commands described in this chapter allow you to inquire about the
|
symbols (names of variables, functions and types) defined in your
|
symbols (names of variables, functions and types) defined in your
|
program. This information is inherent in the text of your program and
|
program. This information is inherent in the text of your program and
|
does not change as your program executes. GDB finds it in your
|
does not change as your program executes. GDB finds it in your
|
program's symbol table, in the file indicated when you started GDB
|
program's symbol table, in the file indicated when you started GDB
|
(*note Choosing files: File Options.), or by one of the file-management
|
(*note Choosing files: File Options.), or by one of the file-management
|
commands (*note Commands to specify files: Files.).
|
commands (*note Commands to specify files: Files.).
|
|
|
Occasionally, you may need to refer to symbols that contain unusual
|
Occasionally, you may need to refer to symbols that contain unusual
|
characters, which GDB ordinarily treats as word delimiters. The most
|
characters, which GDB ordinarily treats as word delimiters. The most
|
frequent case is in referring to static variables in other source files
|
frequent case is in referring to static variables in other source files
|
(*note Program variables: Variables.). File names are recorded in
|
(*note Program variables: Variables.). File names are recorded in
|
object files as debugging symbols, but GDB would ordinarily parse a
|
object files as debugging symbols, but GDB would ordinarily parse a
|
typical file name, like `foo.c', as the three words `foo' `.' `c'. To
|
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
|
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
|
quotes; for example,
|
quotes; for example,
|
|
|
p 'foo.c'::x
|
p 'foo.c'::x
|
|
|
looks up the value of `x' in the scope of the file `foo.c'.
|
looks up the value of `x' in the scope of the file `foo.c'.
|
|
|
`info address SYMBOL'
|
`info address SYMBOL'
|
Describe where the data for SYMBOL is stored. For a register
|
Describe where the data for SYMBOL is stored. For a register
|
variable, this says which register it is kept in. For a
|
variable, this says which register it is kept in. For a
|
non-register local variable, this prints the stack-frame offset at
|
non-register local variable, this prints the stack-frame offset at
|
which the variable is always stored.
|
which the variable is always stored.
|
|
|
Note the contrast with `print &SYMBOL', which does not work at all
|
Note the contrast with `print &SYMBOL', which does not work at all
|
for a register variable, and for a stack local variable prints the
|
for a register variable, and for a stack local variable prints the
|
exact address of the current instantiation of the variable.
|
exact address of the current instantiation of the variable.
|
|
|
`whatis EXPR'
|
`whatis EXPR'
|
Print the data type of expression EXPR. EXPR is not actually
|
Print the data type of expression EXPR. EXPR is not actually
|
evaluated, and any side-effecting operations (such as assignments
|
evaluated, and any side-effecting operations (such as assignments
|
or function calls) inside it do not take place. *Note
|
or function calls) inside it do not take place. *Note
|
Expressions: Expressions.
|
Expressions: Expressions.
|
|
|
`whatis'
|
`whatis'
|
Print the data type of `$', the last value in the value history.
|
Print the data type of `$', the last value in the value history.
|
|
|
`ptype TYPENAME'
|
`ptype TYPENAME'
|
Print a description of data type TYPENAME. TYPENAME may be the
|
Print a description of data type TYPENAME. TYPENAME may be the
|
name of a type, or for C code it may have the form `class
|
name of a type, or for C code it may have the form `class
|
CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
|
CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
|
ENUM-TAG'.
|
ENUM-TAG'.
|
|
|
`ptype EXPR'
|
`ptype EXPR'
|
`ptype'
|
`ptype'
|
Print a description of the type of expression EXPR. `ptype'
|
Print a description of the type of expression EXPR. `ptype'
|
differs from `whatis' by printing a detailed description, instead
|
differs from `whatis' by printing a detailed description, instead
|
of just the name of the type.
|
of just the name of the type.
|
|
|
For example, for this variable declaration:
|
For example, for this variable declaration:
|
|
|
struct complex {double real; double imag;} v;
|
struct complex {double real; double imag;} v;
|
|
|
the two commands give this output:
|
the two commands give this output:
|
|
|
(gdb) whatis v
|
(gdb) whatis v
|
type = struct complex
|
type = struct complex
|
(gdb) ptype v
|
(gdb) ptype v
|
type = struct complex {
|
type = struct complex {
|
double real;
|
double real;
|
double imag;
|
double imag;
|
}
|
}
|
|
|
As with `whatis', using `ptype' without an argument refers to the
|
As with `whatis', using `ptype' without an argument refers to the
|
type of `$', the last value in the value history.
|
type of `$', the last value in the value history.
|
|
|
`info types REGEXP'
|
`info types REGEXP'
|
`info types'
|
`info types'
|
Print a brief description of all types whose names match REGEXP
|
Print a brief description of all types whose names match REGEXP
|
(or all types in your program, if you supply no argument). Each
|
(or all types in your program, if you supply no argument). Each
|
complete typename is matched as though it were a complete line;
|
complete typename is matched as though it were a complete line;
|
thus, `i type value' gives information on all types in your
|
thus, `i type value' gives information on all types in your
|
program whose names include the string `value', but `i type
|
program whose names include the string `value', but `i type
|
^value$' gives information only on types whose complete name is
|
^value$' gives information only on types whose complete name is
|
`value'.
|
`value'.
|
|
|
This command differs from `ptype' in two ways: first, like
|
This command differs from `ptype' in two ways: first, like
|
`whatis', it does not print a detailed description; second, it
|
`whatis', it does not print a detailed description; second, it
|
lists all source files where a type is defined.
|
lists all source files where a type is defined.
|
|
|
`info source'
|
`info source'
|
Show the name of the current source file--that is, the source file
|
Show the name of the current source file--that is, the source file
|
for the function containing the current point of execution--and
|
for the function containing the current point of execution--and
|
the language it was written in.
|
the language it was written in.
|
|
|
`info sources'
|
`info sources'
|
Print the names of all source files in your program for which
|
Print the names of all source files in your program for which
|
there is debugging information, organized into two lists: files
|
there is debugging information, organized into two lists: files
|
whose symbols have already been read, and files whose symbols will
|
whose symbols have already been read, and files whose symbols will
|
be read when needed.
|
be read when needed.
|
|
|
`info functions'
|
`info functions'
|
Print the names and data types of all defined functions.
|
Print the names and data types of all defined functions.
|
|
|
`info functions REGEXP'
|
`info functions REGEXP'
|
Print the names and data types of all defined functions whose
|
Print the names and data types of all defined functions whose
|
names contain a match for regular expression REGEXP. Thus, `info
|
names contain a match for regular expression REGEXP. Thus, `info
|
fun step' finds all functions whose names include `step'; `info
|
fun step' finds all functions whose names include `step'; `info
|
fun ^step' finds those whose names start with `step'.
|
fun ^step' finds those whose names start with `step'.
|
|
|
`info variables'
|
`info variables'
|
Print the names and data types of all variables that are declared
|
Print the names and data types of all variables that are declared
|
outside of functions (i.e., excluding local variables).
|
outside of functions (i.e., excluding local variables).
|
|
|
`info variables REGEXP'
|
`info variables REGEXP'
|
Print the names and data types of all variables (except for local
|
Print the names and data types of all variables (except for local
|
variables) whose names contain a match for regular expression
|
variables) whose names contain a match for regular expression
|
REGEXP.
|
REGEXP.
|
|
|
Some systems allow individual object files that make up your
|
Some systems allow individual object files that make up your
|
program to be replaced without stopping and restarting your
|
program to be replaced without stopping and restarting your
|
program. For example, in VxWorks you can simply recompile a
|
program. For example, in VxWorks you can simply recompile a
|
defective object file and keep on running. If you are running on
|
defective object file and keep on running. If you are running on
|
one of these systems, you can allow GDB to reload the symbols for
|
one of these systems, you can allow GDB to reload the symbols for
|
automatically relinked modules:
|
automatically relinked modules:
|
|
|
`set symbol-reloading on'
|
`set symbol-reloading on'
|
Replace symbol definitions for the corresponding source file
|
Replace symbol definitions for the corresponding source file
|
when an object file with a particular name is seen again.
|
when an object file with a particular name is seen again.
|
|
|
`set symbol-reloading off'
|
`set symbol-reloading off'
|
Do not replace symbol definitions when encountering object
|
Do not replace symbol definitions when encountering object
|
files of the same name more than once. This is the default
|
files of the same name more than once. This is the default
|
state; if you are not running on a system that permits
|
state; if you are not running on a system that permits
|
automatic relinking of modules, you should leave
|
automatic relinking of modules, you should leave
|
`symbol-reloading' off, since otherwise GDB may discard
|
`symbol-reloading' off, since otherwise GDB may discard
|
symbols when linking large programs, that may contain several
|
symbols when linking large programs, that may contain several
|
modules (from different directories or libraries) with the
|
modules (from different directories or libraries) with the
|
same name.
|
same name.
|
|
|
`show symbol-reloading'
|
`show symbol-reloading'
|
Show the current `on' or `off' setting.
|
Show the current `on' or `off' setting.
|
|
|
`set opaque-type-resolution on'
|
`set opaque-type-resolution on'
|
Tell GDB to resolve opaque types. An opaque type is a type
|
Tell GDB to resolve opaque types. An opaque type is a type
|
declared as a pointer to a `struct', `class', or `union'--for
|
declared as a pointer to a `struct', `class', or `union'--for
|
example, `struct MyType *'--that is used in one source file
|
example, `struct MyType *'--that is used in one source file
|
although the full declaration of `struct MyType' is in another
|
although the full declaration of `struct MyType' is in another
|
source file. The default is on.
|
source file. The default is on.
|
|
|
A change in the setting of this subcommand will not take effect
|
A change in the setting of this subcommand will not take effect
|
until the next time symbols for a file are loaded.
|
until the next time symbols for a file are loaded.
|
|
|
`set opaque-type-resolution off'
|
`set opaque-type-resolution off'
|
Tell GDB not to resolve opaque types. In this case, the type is
|
Tell GDB not to resolve opaque types. In this case, the type is
|
printed as follows:
|
printed as follows:
|
{}
|
{}
|
|
|
`show opaque-type-resolution'
|
`show opaque-type-resolution'
|
Show whether opaque types are resolved or not.
|
Show whether opaque types are resolved or not.
|
|
|
`maint print symbols FILENAME'
|
`maint print symbols FILENAME'
|
`maint print psymbols FILENAME'
|
`maint print psymbols FILENAME'
|
`maint print msymbols FILENAME'
|
`maint print msymbols FILENAME'
|
Write a dump of debugging symbol data into the file FILENAME.
|
Write a dump of debugging symbol data into the file FILENAME.
|
These commands are used to debug the GDB symbol-reading code. Only
|
These commands are used to debug the GDB symbol-reading code. Only
|
symbols with debugging data are included. If you use `maint print
|
symbols with debugging data are included. If you use `maint print
|
symbols', GDB includes all the symbols for which it has already
|
symbols', GDB includes all the symbols for which it has already
|
collected full details: that is, FILENAME reflects symbols for
|
collected full details: that is, FILENAME reflects symbols for
|
only those files whose symbols GDB has read. You can use the
|
only those files whose symbols GDB has read. You can use the
|
command `info sources' to find out which files these are. If you
|
command `info sources' to find out which files these are. If you
|
use `maint print psymbols' instead, the dump shows information
|
use `maint print psymbols' instead, the dump shows information
|
about symbols that GDB only knows partially--that is, symbols
|
about symbols that GDB only knows partially--that is, symbols
|
defined in files that GDB has skimmed, but not yet read
|
defined in files that GDB has skimmed, but not yet read
|
completely. Finally, `maint print msymbols' dumps just the
|
completely. Finally, `maint print msymbols' dumps just the
|
minimal symbol information required for each object file from
|
minimal symbol information required for each object file from
|
which GDB has read some symbols. *Note Commands to specify files:
|
which GDB has read some symbols. *Note Commands to specify files:
|
Files, for a discussion of how GDB reads symbols (in the
|
Files, for a discussion of how GDB reads symbols (in the
|
description of `symbol-file').
|
description of `symbol-file').
|
|
|
|
|
File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
|
File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
|
|
|
Altering Execution
|
Altering Execution
|
******************
|
******************
|
|
|
Once you think you have found an error in your program, you might
|
Once you think you have found an error in your program, you might
|
want to find out for certain whether correcting the apparent error
|
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
|
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
|
answer by experiment, using the GDB features for altering execution of
|
the program.
|
the program.
|
|
|
For example, you can store new values into variables or memory
|
For example, you can store new values into variables or memory
|
locations, give your program a signal, restart it at a different
|
locations, give your program a signal, restart it at a different
|
address, or even return prematurely from a function.
|
address, or even return prematurely from a function.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Assignment:: Assignment to variables
|
* Assignment:: Assignment to variables
|
* Jumping:: Continuing at a different address
|
* Jumping:: Continuing at a different address
|
* Signaling:: Giving your program a signal
|
* Signaling:: Giving your program a signal
|
* Returning:: Returning from a function
|
* Returning:: Returning from a function
|
* Calling:: Calling your program's functions
|
* Calling:: Calling your program's functions
|
* Patching:: Patching your program
|
* Patching:: Patching your program
|
|
|
|
|
File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
|
File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
|
|
|
Assignment to variables
|
Assignment to variables
|
=======================
|
=======================
|
|
|
To alter the value of a variable, evaluate an assignment expression.
|
To alter the value of a variable, evaluate an assignment expression.
|
*Note Expressions: Expressions. For example,
|
*Note Expressions: Expressions. For example,
|
|
|
print x=4
|
print x=4
|
|
|
stores the value 4 into the variable `x', and then prints the value of
|
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
|
the assignment expression (which is 4). *Note Using GDB with Different
|
Languages: Languages, for more information on operators in supported
|
Languages: Languages, for more information on operators in supported
|
languages.
|
languages.
|
|
|
If you are not interested in seeing the value of the assignment, use
|
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
|
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
|
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.).
|
is not put in the value history (*note Value history: Value History.).
|
The expression is evaluated only for its effects.
|
The expression is evaluated only for its effects.
|
|
|
If the beginning of the argument string of the `set' command appears
|
If the beginning of the argument string of the `set' command appears
|
identical to a `set' subcommand, use the `set variable' command instead
|
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 just `set'. This command is identical to `set' except for its lack
|
of subcommands. For example, if your program has a variable `width',
|
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
|
you get an error if you try to set a new value with just `set
|
width=13', because GDB has the command `set width':
|
width=13', because GDB has the command `set width':
|
|
|
(gdb) whatis width
|
(gdb) whatis width
|
type = double
|
type = double
|
(gdb) p width
|
(gdb) p width
|
$4 = 13
|
$4 = 13
|
(gdb) set width=47
|
(gdb) set width=47
|
Invalid syntax in expression.
|
Invalid syntax in expression.
|
|
|
The invalid expression, of course, is `=47'. In order to actually set
|
The invalid expression, of course, is `=47'. In order to actually set
|
the program's variable `width', use
|
the program's variable `width', use
|
|
|
(gdb) set var width=47
|
(gdb) set var width=47
|
|
|
Because the `set' command has many subcommands that can conflict
|
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
|
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
|
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
|
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',
|
with just `set g=4', because GDB has the command `set gnutarget',
|
abbreviated `set g':
|
abbreviated `set g':
|
|
|
(gdb) whatis g
|
(gdb) whatis g
|
type = double
|
type = double
|
(gdb) p g
|
(gdb) p g
|
$1 = 1
|
$1 = 1
|
(gdb) set g=4
|
(gdb) set g=4
|
(gdb) p g
|
(gdb) p g
|
$2 = 1
|
$2 = 1
|
(gdb) r
|
(gdb) r
|
The program being debugged has been started already.
|
The program being debugged has been started already.
|
Start it from the beginning? (y or n) y
|
Start it from the beginning? (y or n) y
|
Starting program: /home/smith/cc_progs/a.out
|
Starting program: /home/smith/cc_progs/a.out
|
"/home/smith/cc_progs/a.out": can't open to read symbols:
|
"/home/smith/cc_progs/a.out": can't open to read symbols:
|
Invalid bfd target.
|
Invalid bfd target.
|
(gdb) show g
|
(gdb) show g
|
The current BFD target is "=4".
|
The current BFD target is "=4".
|
|
|
The program variable `g' did not change, and you silently set the
|
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
|
`gnutarget' to an invalid value. In order to set the variable `g', use
|
|
|
(gdb) set var g=4
|
(gdb) set var g=4
|
|
|
GDB allows more implicit conversions in assignments than C; you can
|
GDB allows more implicit conversions in assignments than C; you can
|
freely store an integer value into a pointer variable or vice versa,
|
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
|
and you can convert any structure to any other structure that is the
|
same length or shorter.
|
same length or shorter.
|
|
|
To store values into arbitrary places in memory, use the `{...}'
|
To store values into arbitrary places in memory, use the `{...}'
|
construct to generate a value of specified type at a specified address
|
construct to generate a value of specified type at a specified address
|
(*note Expressions: Expressions.). For example, `{int}0x83040' refers
|
(*note Expressions: Expressions.). For example, `{int}0x83040' refers
|
to memory location `0x83040' as an integer (which implies a certain size
|
to memory location `0x83040' as an integer (which implies a certain size
|
and representation in memory), and
|
and representation in memory), and
|
|
|
set {int}0x83040 = 4
|
set {int}0x83040 = 4
|
|
|
stores the value 4 into that memory location.
|
stores the value 4 into that memory location.
|
|
|
|
|
File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
|
File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
|
|
|
Continuing at a different address
|
Continuing at a different address
|
=================================
|
=================================
|
|
|
Ordinarily, when you continue your program, you do so at the place
|
Ordinarily, when you continue your program, you do so at the place
|
where it stopped, with the `continue' command. You can instead
|
where it stopped, with the `continue' command. You can instead
|
continue at an address of your own choosing, with the following
|
continue at an address of your own choosing, with the following
|
commands:
|
commands:
|
|
|
`jump LINESPEC'
|
`jump LINESPEC'
|
Resume execution at line LINESPEC. Execution stops again
|
Resume execution at line LINESPEC. Execution stops again
|
immediately if there is a breakpoint there. *Note Printing source
|
immediately if there is a breakpoint there. *Note Printing source
|
lines: List, for a description of the different forms of LINESPEC.
|
lines: List, for a description of the different forms of LINESPEC.
|
It is common practice to use the `tbreak' command in conjunction
|
It is common practice to use the `tbreak' command in conjunction
|
with `jump'. *Note Setting breakpoints: Set Breaks.
|
with `jump'. *Note Setting breakpoints: Set Breaks.
|
|
|
The `jump' command does not change the current stack frame, or the
|
The `jump' command does not change the current stack frame, or the
|
stack pointer, or the contents of any memory location or any
|
stack pointer, or the contents of any memory location or any
|
register other than the program counter. If line LINESPEC is in a
|
register other than the program counter. If line LINESPEC is in a
|
different function from the one currently executing, the results
|
different function from the one currently executing, the results
|
may be bizarre if the two functions expect different patterns of
|
may be bizarre if the two functions expect different patterns of
|
arguments or of local variables. For this reason, the `jump'
|
arguments or of local variables. For this reason, the `jump'
|
command requests confirmation if the specified line is not in the
|
command requests confirmation if the specified line is not in the
|
function currently executing. However, even bizarre results are
|
function currently executing. However, even bizarre results are
|
predictable if you are well acquainted with the machine-language
|
predictable if you are well acquainted with the machine-language
|
code of your program.
|
code of your program.
|
|
|
`jump *ADDRESS'
|
`jump *ADDRESS'
|
Resume execution at the instruction at address ADDRESS.
|
Resume execution at the instruction at address ADDRESS.
|
|
|
On many systems, you can get much the same effect as the `jump'
|
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
|
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
|
is that this does not start your program running; it only changes the
|
address of where it _will_ run when you continue. For example,
|
address of where it _will_ run when you continue. For example,
|
|
|
set $pc = 0x485
|
set $pc = 0x485
|
|
|
makes the next `continue' command or stepping command execute at
|
makes the next `continue' command or stepping command execute at
|
address `0x485', rather than at the address where your program stopped.
|
address `0x485', rather than at the address where your program stopped.
|
*Note Continuing and stepping: Continuing and Stepping.
|
*Note Continuing and stepping: Continuing and Stepping.
|
|
|
The most common occasion to use the `jump' command is to back
|
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
|
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.
|
has already executed, in order to examine its execution in more detail.
|
|
|
|
|
File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
|
File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
|
|
|
Giving your program a signal
|
Giving your program a signal
|
============================
|
============================
|
|
|
`signal SIGNAL'
|
`signal SIGNAL'
|
Resume execution where your program stopped, but immediately give
|
Resume execution where your program stopped, but immediately give
|
it the signal SIGNAL. SIGNAL can be the name or the number of a
|
it the signal SIGNAL. SIGNAL can be the name or the number of a
|
signal. For example, on many systems `signal 2' and `signal
|
signal. For example, on many systems `signal 2' and `signal
|
SIGINT' are both ways of sending an interrupt signal.
|
SIGINT' are both ways of sending an interrupt signal.
|
|
|
Alternatively, if SIGNAL is zero, continue execution without
|
Alternatively, if SIGNAL is zero, continue execution without
|
giving a signal. This is useful when your program stopped on
|
giving a signal. This is useful when your program stopped on
|
account of a signal and would ordinary see the signal when resumed
|
account of a signal and would ordinary see the signal when resumed
|
with the `continue' command; `signal 0' causes it to resume
|
with the `continue' command; `signal 0' causes it to resume
|
without a signal.
|
without a signal.
|
|
|
`signal' does not repeat when you press a second time after
|
`signal' does not repeat when you press a second time after
|
executing the command.
|
executing the command.
|
|
|
Invoking the `signal' command is not the same as invoking the `kill'
|
Invoking the `signal' command is not the same as invoking the `kill'
|
utility from the shell. Sending a signal with `kill' causes GDB to
|
utility from the shell. Sending a signal with `kill' causes GDB to
|
decide what to do with the signal depending on the signal handling
|
decide what to do with the signal depending on the signal handling
|
tables (*note Signals::). The `signal' command passes the signal
|
tables (*note Signals::). The `signal' command passes the signal
|
directly to your program.
|
directly to your program.
|
|
|
|
|
File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
|
File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
|
|
|
Returning from a function
|
Returning from a function
|
=========================
|
=========================
|
|
|
`return'
|
`return'
|
`return EXPRESSION'
|
`return EXPRESSION'
|
You can cancel execution of a function call with the `return'
|
You can cancel execution of a function call with the `return'
|
command. If you give an EXPRESSION argument, its value is used as
|
command. If you give an EXPRESSION argument, its value is used as
|
the function's return value.
|
the function's return value.
|
|
|
When you use `return', GDB discards the selected stack frame (and
|
When you use `return', GDB discards the selected stack frame (and
|
all frames within it). You can think of this as making the discarded
|
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
|
frame return prematurely. If you wish to specify a value to be
|
returned, give that value as the argument to `return'.
|
returned, give that value as the argument to `return'.
|
|
|
This pops the selected stack frame (*note Selecting a frame:
|
This pops the selected stack frame (*note Selecting a frame:
|
Selection.), and any other frames inside of it, leaving its caller as
|
Selection.), and any other frames inside of it, leaving its caller as
|
the innermost remaining frame. That frame becomes selected. The
|
the innermost remaining frame. That frame becomes selected. The
|
specified value is stored in the registers used for returning values of
|
specified value is stored in the registers used for returning values of
|
functions.
|
functions.
|
|
|
The `return' command does not resume execution; it leaves the
|
The `return' command does not resume execution; it leaves the
|
program stopped in the state that would exist if the function had just
|
program stopped in the state that would exist if the function had just
|
returned. In contrast, the `finish' command (*note Continuing and
|
returned. In contrast, the `finish' command (*note Continuing and
|
stepping: Continuing and Stepping.) resumes execution until the
|
stepping: Continuing and Stepping.) resumes execution until the
|
selected stack frame returns naturally.
|
selected stack frame returns naturally.
|
|
|
|
|
File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
|
File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
|
|
|
Calling program functions
|
Calling program functions
|
=========================
|
=========================
|
|
|
`call EXPR'
|
`call EXPR'
|
Evaluate the expression EXPR without displaying `void' returned
|
Evaluate the expression EXPR without displaying `void' returned
|
values.
|
values.
|
|
|
You can use this variant of the `print' command if you want to
|
You can use this variant of the `print' command if you want to
|
execute a function from your program, but without cluttering the output
|
execute a function from your program, but without cluttering the output
|
with `void' returned values. If the result is not void, it is printed
|
with `void' returned values. If the result is not void, it is printed
|
and saved in the value history.
|
and saved in the value history.
|
|
|
For the A29K, a user-controlled variable `call_scratch_address',
|
For the A29K, a user-controlled variable `call_scratch_address',
|
specifies the location of a scratch area to be used when GDB calls a
|
specifies the location of a scratch area to be used when GDB calls a
|
function in the target. This is necessary because the usual method of
|
function in the target. This is necessary because the usual method of
|
putting the scratch area on the stack does not work in systems that
|
putting the scratch area on the stack does not work in systems that
|
have separate instruction and data spaces.
|
have separate instruction and data spaces.
|
|
|
|
|
File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
|
File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
|
|
|
Patching programs
|
Patching programs
|
=================
|
=================
|
|
|
By default, GDB opens the file containing your program's executable
|
By default, GDB opens the file containing your program's executable
|
code (or the corefile) read-only. This prevents accidental alterations
|
code (or the corefile) read-only. This prevents accidental alterations
|
to machine code; but it also prevents you from intentionally patching
|
to machine code; but it also prevents you from intentionally patching
|
your program's binary.
|
your program's binary.
|
|
|
If you'd like to be able to patch the binary, you can specify that
|
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
|
explicitly with the `set write' command. For example, you might want
|
to turn on internal debugging flags, or even to make emergency repairs.
|
to turn on internal debugging flags, or even to make emergency repairs.
|
|
|
`set write on'
|
`set write on'
|
`set write off'
|
`set write off'
|
If you specify `set write on', GDB opens executable and core files
|
If you specify `set write on', GDB opens executable and core files
|
for both reading and writing; if you specify `set write off' (the
|
for both reading and writing; if you specify `set write off' (the
|
default), GDB opens them read-only.
|
default), GDB opens them read-only.
|
|
|
If you have already loaded a file, you must load it again (using
|
If you have already loaded a file, you must load it again (using
|
the `exec-file' or `core-file' command) after changing `set
|
the `exec-file' or `core-file' command) after changing `set
|
write', for your new setting to take effect.
|
write', for your new setting to take effect.
|
|
|
`show write'
|
`show write'
|
Display whether executable files and core files are opened for
|
Display whether executable files and core files are opened for
|
writing as well as reading.
|
writing as well as reading.
|
|
|
|
|
File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
|
File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
|
|
|
GDB Files
|
GDB Files
|
*********
|
*********
|
|
|
GDB needs to know the file name of the program to be debugged, both
|
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.
|
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
|
To debug a core dump of a previous run, you must also tell GDB the name
|
of the core dump file.
|
of the core dump file.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Files:: Commands to specify files
|
* Files:: Commands to specify files
|
* Symbol Errors:: Errors reading symbol files
|
* Symbol Errors:: Errors reading symbol files
|
|
|
|
|
File: gdb.info, Node: Files, Next: Symbol Errors, Up: GDB Files
|
File: gdb.info, Node: Files, Next: Symbol Errors, Up: GDB Files
|
|
|
Commands to specify files
|
Commands to specify files
|
=========================
|
=========================
|
|
|
You may want to specify executable and core dump file names. The
|
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
|
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.).
|
start-up commands (*note Getting In and Out of GDB: Invocation.).
|
|
|
Occasionally it is necessary to change to a different file during a
|
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
|
GDB session. Or you may run GDB and forget to specify a file you want
|
to use. In these situations the GDB commands to specify new files are
|
to use. In these situations the GDB commands to specify new files are
|
useful.
|
useful.
|
|
|
`file FILENAME'
|
`file FILENAME'
|
Use FILENAME as the program to be debugged. It is read for its
|
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
|
symbols and for the contents of pure memory. It is also the
|
program executed when you use the `run' command. If you do not
|
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
|
specify a directory and the file is not found in the GDB working
|
directory, GDB uses the environment variable `PATH' as a list of
|
directory, GDB uses the environment variable `PATH' as a list of
|
directories to search, just as the shell does when looking for a
|
directories to search, just as the shell does when looking for a
|
program to run. You can change the value of this variable, for
|
program to run. You can change the value of this variable, for
|
both GDB and your program, using the `path' command.
|
both GDB and your program, using the `path' command.
|
|
|
On systems with memory-mapped files, an auxiliary file named
|
On systems with memory-mapped files, an auxiliary file named
|
`FILENAME.syms' may hold symbol table information for FILENAME.
|
`FILENAME.syms' may hold symbol table information for FILENAME.
|
If so, GDB maps in the symbol table from `FILENAME.syms', starting
|
If so, GDB maps in the symbol table from `FILENAME.syms', starting
|
up more quickly. See the descriptions of the file options
|
up more quickly. See the descriptions of the file options
|
`-mapped' and `-readnow' (available on the command line, and with
|
`-mapped' and `-readnow' (available on the command line, and with
|
the commands `file', `symbol-file', or `add-symbol-file',
|
the commands `file', `symbol-file', or `add-symbol-file',
|
described below), for more information.
|
described below), for more information.
|
|
|
`file'
|
`file'
|
`file' with no argument makes GDB discard any information it has
|
`file' with no argument makes GDB discard any information it has
|
on both executable file and the symbol table.
|
on both executable file and the symbol table.
|
|
|
`exec-file [ FILENAME ]'
|
`exec-file [ FILENAME ]'
|
Specify that the program to be run (but not the symbol table) is
|
Specify that the program to be run (but not the symbol table) is
|
found in FILENAME. GDB searches the environment variable `PATH'
|
found in FILENAME. GDB searches the environment variable `PATH'
|
if necessary to locate your program. Omitting FILENAME means to
|
if necessary to locate your program. Omitting FILENAME means to
|
discard information on the executable file.
|
discard information on the executable file.
|
|
|
`symbol-file [ FILENAME ]'
|
`symbol-file [ FILENAME ]'
|
Read symbol table information from file FILENAME. `PATH' is
|
Read symbol table information from file FILENAME. `PATH' is
|
searched when necessary. Use the `file' command to get both symbol
|
searched when necessary. Use the `file' command to get both symbol
|
table and program to run from the same file.
|
table and program to run from the same file.
|
|
|
`symbol-file' with no argument clears out GDB information on your
|
`symbol-file' with no argument clears out GDB information on your
|
program's symbol table.
|
program's symbol table.
|
|
|
The `symbol-file' command causes GDB to forget the contents of its
|
The `symbol-file' command causes GDB to forget the contents of its
|
convenience variables, the value history, and all breakpoints and
|
convenience variables, the value history, and all breakpoints and
|
auto-display expressions. This is because they may contain
|
auto-display expressions. This is because they may contain
|
pointers to the internal data recording symbols and data types,
|
pointers to the internal data recording symbols and data types,
|
which are part of the old symbol table data being discarded inside
|
which are part of the old symbol table data being discarded inside
|
GDB.
|
GDB.
|
|
|
`symbol-file' does not repeat if you press again after
|
`symbol-file' does not repeat if you press again after
|
executing it once.
|
executing it once.
|
|
|
When GDB is configured for a particular environment, it
|
When GDB is configured for a particular environment, it
|
understands debugging information in whatever format is the
|
understands debugging information in whatever format is the
|
standard generated for that environment; you may use either a GNU
|
standard generated for that environment; you may use either a GNU
|
compiler, or other compilers that adhere to the local conventions.
|
compiler, or other compilers that adhere to the local conventions.
|
Best results are usually obtained from GNU compilers; for example,
|
Best results are usually obtained from GNU compilers; for example,
|
using `gcc' you can generate debugging information for optimized
|
using `gcc' you can generate debugging information for optimized
|
code.
|
code.
|
|
|
For most kinds of object files, with the exception of old SVR3
|
For most kinds of object files, with the exception of old SVR3
|
systems using COFF, the `symbol-file' command does not normally
|
systems using COFF, the `symbol-file' command does not normally
|
read the symbol table in full right away. Instead, it scans the
|
read the symbol table in full right away. Instead, it scans the
|
symbol table quickly to find which source files and which symbols
|
symbol table quickly to find which source files and which symbols
|
are present. The details are read later, one source file at a
|
are present. The details are read later, one source file at a
|
time, as they are needed.
|
time, as they are needed.
|
|
|
The purpose of this two-stage reading strategy is to make GDB
|
The purpose of this two-stage reading strategy is to make GDB
|
start up faster. For the most part, it is invisible except for
|
start up faster. For the most part, it is invisible except for
|
occasional pauses while the symbol table details for a particular
|
occasional pauses while the symbol table details for a particular
|
source file are being read. (The `set verbose' command can turn
|
source file are being read. (The `set verbose' command can turn
|
these pauses into messages if desired. *Note Optional warnings
|
these pauses into messages if desired. *Note Optional warnings
|
and messages: Messages/Warnings.)
|
and messages: Messages/Warnings.)
|
|
|
We have not implemented the two-stage strategy for COFF yet. When
|
We have not implemented the two-stage strategy for COFF yet. When
|
the symbol table is stored in COFF format, `symbol-file' reads the
|
the symbol table is stored in COFF format, `symbol-file' reads the
|
symbol table data in full right away. Note that "stabs-in-COFF"
|
symbol table data in full right away. Note that "stabs-in-COFF"
|
still does the two-stage strategy, since the debug info is actually
|
still does the two-stage strategy, since the debug info is actually
|
in stabs format.
|
in stabs format.
|
|
|
`symbol-file FILENAME [ -readnow ] [ -mapped ]'
|
`symbol-file FILENAME [ -readnow ] [ -mapped ]'
|
`file FILENAME [ -readnow ] [ -mapped ]'
|
`file FILENAME [ -readnow ] [ -mapped ]'
|
You can override the GDB two-stage strategy for reading symbol
|
You can override the GDB two-stage strategy for reading symbol
|
tables by using the `-readnow' option with any of the commands that
|
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
|
load symbol table information, if you want to be sure GDB has the
|
entire symbol table available.
|
entire symbol table available.
|
|
|
If memory-mapped files are available on your system through the
|
If memory-mapped files are available on your system through the
|
`mmap' system call, you can use another option, `-mapped', to
|
`mmap' system call, you can use another option, `-mapped', to
|
cause GDB to write the symbols for your program into a reusable
|
cause GDB to write the symbols for your program into a reusable
|
file. Future GDB debugging sessions map in symbol information
|
file. Future GDB debugging sessions map in symbol information
|
from this auxiliary symbol file (if the program has not changed),
|
from this auxiliary symbol file (if the program has not changed),
|
rather than spending time reading the symbol table from the
|
rather than spending time reading the symbol table from the
|
executable program. Using the `-mapped' option has the same
|
executable program. Using the `-mapped' option has the same
|
effect as starting GDB with the `-mapped' command-line option.
|
effect as starting GDB with the `-mapped' command-line option.
|
|
|
You can use both options together, to make sure the auxiliary
|
You can use both options together, to make sure the auxiliary
|
symbol file has all the symbol information for your program.
|
symbol file has all the symbol information for your program.
|
|
|
The auxiliary symbol file for a program called MYPROG is called
|
The auxiliary symbol file for a program called MYPROG is called
|
`MYPROG.syms'. Once this file exists (so long as it is newer than
|
`MYPROG.syms'. Once this file exists (so long as it is newer than
|
the corresponding executable), GDB always attempts to use it when
|
the corresponding executable), GDB always attempts to use it when
|
you debug MYPROG; no special options or commands are needed.
|
you debug MYPROG; no special options or commands are needed.
|
|
|
The `.syms' file is specific to the host machine where you run
|
The `.syms' file is specific to the host machine where you run
|
GDB. It holds an exact image of the internal GDB symbol table.
|
GDB. It holds an exact image of the internal GDB symbol table.
|
It cannot be shared across multiple host platforms.
|
It cannot be shared across multiple host platforms.
|
|
|
`core-file [ FILENAME ]'
|
`core-file [ FILENAME ]'
|
Specify the whereabouts of a core dump file to be used as the
|
Specify the whereabouts of a core dump file to be used as the
|
"contents of memory". Traditionally, core files contain only some
|
"contents of memory". Traditionally, core files contain only some
|
parts of the address space of the process that generated them; GDB
|
parts of the address space of the process that generated them; GDB
|
can access the executable file itself for other parts.
|
can access the executable file itself for other parts.
|
|
|
`core-file' with no argument specifies that no core file is to be
|
`core-file' with no argument specifies that no core file is to be
|
used.
|
used.
|
|
|
Note that the core file is ignored when your program is actually
|
Note that the core file is ignored when your program is actually
|
running under GDB. So, if you have been running your program and
|
running under GDB. So, if you have been running your program and
|
you wish to debug a core file instead, you must kill the
|
you wish to debug a core file instead, you must kill the
|
subprocess in which the program is running. To do this, use the
|
subprocess in which the program is running. To do this, use the
|
`kill' command (*note Killing the child process: Kill Process.).
|
`kill' command (*note Killing the child process: Kill Process.).
|
|
|
`add-symbol-file FILENAME ADDRESS'
|
`add-symbol-file FILENAME ADDRESS'
|
`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]'
|
`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]'
|
`add-symbol-file FILENAME ADDRESS DATA_ADDRESS BSS_ADDRESS'
|
`add-symbol-file FILENAME ADDRESS DATA_ADDRESS BSS_ADDRESS'
|
`add-symbol-file FILENAME -TSECTION ADDRESS'
|
`add-symbol-file FILENAME -TSECTION ADDRESS'
|
The `add-symbol-file' command reads additional symbol table
|
The `add-symbol-file' command reads additional symbol table
|
information from the file FILENAME. You would use this command
|
information from the file FILENAME. You would use this command
|
when FILENAME has been dynamically loaded (by some other means)
|
when FILENAME has been dynamically loaded (by some other means)
|
into the program that is running. ADDRESS should be the memory
|
into the program that is running. ADDRESS should be the memory
|
address at which the file has been loaded; GDB cannot figure this
|
address at which the file has been loaded; GDB cannot figure this
|
out for itself. You can specify up to three addresses, in which
|
out for itself. You can specify up to three addresses, in which
|
case they are taken to be the addresses of the text, data, and bss
|
case they are taken to be the addresses of the text, data, and bss
|
segments respectively. For complicated cases, you can specify an
|
segments respectively. For complicated cases, you can specify an
|
arbitrary number of `-TSECTION ADDRESS' pairs, to give an explicit
|
arbitrary number of `-TSECTION ADDRESS' pairs, to give an explicit
|
section name and base address for that section. You can specify
|
section name and base address for that section. You can specify
|
any ADDRESS as an expression.
|
any ADDRESS as an expression.
|
|
|
The symbol table of the file FILENAME is added to the symbol table
|
The symbol table of the file FILENAME is added to the symbol table
|
originally read with the `symbol-file' command. You can use the
|
originally read with the `symbol-file' command. You can use the
|
`add-symbol-file' command any number of times; the new symbol data
|
`add-symbol-file' command any number of times; the new symbol data
|
thus read keeps adding to the old. To discard all old symbol data
|
thus read keeps adding to the old. To discard all old symbol data
|
instead, use the `symbol-file' command without any arguments.
|
instead, use the `symbol-file' command without any arguments.
|
|
|
`add-symbol-file' does not repeat if you press after using
|
`add-symbol-file' does not repeat if you press after using
|
it.
|
it.
|
|
|
You can use the `-mapped' and `-readnow' options just as with the
|
You can use the `-mapped' and `-readnow' options just as with the
|
`symbol-file' command, to change how GDB manages the symbol table
|
`symbol-file' command, to change how GDB manages the symbol table
|
information for FILENAME.
|
information for FILENAME.
|
|
|
`add-shared-symbol-file'
|
`add-shared-symbol-file'
|
The `add-shared-symbol-file' command can be used only under
|
The `add-shared-symbol-file' command can be used only under
|
Harris' CXUX operating system for the Motorola 88k. GDB
|
Harris' CXUX operating system for the Motorola 88k. GDB
|
automatically looks for shared libraries, however if GDB does not
|
automatically looks for shared libraries, however if GDB does not
|
find yours, you can run `add-shared-symbol-file'. It takes no
|
find yours, you can run `add-shared-symbol-file'. It takes no
|
arguments.
|
arguments.
|
|
|
`section'
|
`section'
|
The `section' command changes the base address of section SECTION
|
The `section' command changes the base address of section SECTION
|
of the exec file to ADDR. This can be used if the exec file does
|
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
|
not contain section addresses, (such as in the a.out format), or
|
when the addresses specified in the file itself are wrong. Each
|
when the addresses specified in the file itself are wrong. Each
|
section must be changed separately. The `info files' command,
|
section must be changed separately. The `info files' command,
|
described below, lists all the sections and their addresses.
|
described below, lists all the sections and their addresses.
|
|
|
`info files'
|
`info files'
|
`info target'
|
`info target'
|
`info files' and `info target' are synonymous; both print the
|
`info files' and `info target' are synonymous; both print the
|
current target (*note Specifying a Debugging Target: Targets.),
|
current target (*note Specifying a Debugging Target: Targets.),
|
including the names of the executable and core dump files
|
including the names of the executable and core dump files
|
currently in use by GDB, and the files from which symbols were
|
currently in use by GDB, and the files from which symbols were
|
loaded. The command `help target' lists all possible targets
|
loaded. The command `help target' lists all possible targets
|
rather than current ones.
|
rather than current ones.
|
|
|
All file-specifying commands allow both absolute and relative file
|
All file-specifying commands allow both absolute and relative file
|
names as arguments. GDB always converts the file name to an absolute
|
names as arguments. GDB always converts the file name to an absolute
|
file name and remembers it that way.
|
file name and remembers it that way.
|
|
|
GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
|
GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
|
libraries.
|
libraries.
|
|
|
GDB automatically loads symbol definitions from shared libraries
|
GDB automatically loads symbol definitions from shared libraries
|
when you use the `run' command, or when you examine a core file.
|
when you use the `run' command, or when you examine a core file.
|
(Before you issue the `run' command, GDB does not understand references
|
(Before you issue the `run' command, GDB does not understand references
|
to a function in a shared library, however--unless you are debugging a
|
to a function in a shared library, however--unless you are debugging a
|
core file).
|
core file).
|
|
|
On HP-UX, if the program loads a library explicitly, GDB
|
On HP-UX, if the program loads a library explicitly, GDB
|
automatically loads the symbols at the time of the `shl_load' call.
|
automatically loads the symbols at the time of the `shl_load' call.
|
|
|
`info share'
|
`info share'
|
`info sharedlibrary'
|
`info sharedlibrary'
|
Print the names of the shared libraries which are currently loaded.
|
Print the names of the shared libraries which are currently loaded.
|
|
|
`sharedlibrary REGEX'
|
`sharedlibrary REGEX'
|
`share REGEX'
|
`share REGEX'
|
Load shared object library symbols for files matching a Unix
|
Load shared object library symbols for files matching a Unix
|
regular expression. As with files loaded automatically, it only
|
regular expression. As with files loaded automatically, it only
|
loads shared libraries required by your program for a core file or
|
loads shared libraries required by your program for a core file or
|
after typing `run'. If REGEX is omitted all shared libraries
|
after typing `run'. If REGEX is omitted all shared libraries
|
required by your program are loaded.
|
required by your program are loaded.
|
|
|
On HP-UX systems, GDB detects the loading of a shared library and
|
On HP-UX systems, GDB detects the loading of a shared library and
|
automatically reads in symbols from the newly loaded library, up to a
|
automatically reads in symbols from the newly loaded library, up to a
|
threshold that is initially set but that you can modify if you wish.
|
threshold that is initially set but that you can modify if you wish.
|
|
|
Beyond that threshold, symbols from shared libraries must be
|
Beyond that threshold, symbols from shared libraries must be
|
explicitly loaded. To load these symbols, use the command
|
explicitly loaded. To load these symbols, use the command
|
`sharedlibrary FILENAME'. The base address of the shared library is
|
`sharedlibrary FILENAME'. The base address of the shared library is
|
determined automatically by GDB and need not be specified.
|
determined automatically by GDB and need not be specified.
|
|
|
To display or set the threshold, use the commands:
|
To display or set the threshold, use the commands:
|
|
|
`set auto-solib-add THRESHOLD'
|
`set auto-solib-add THRESHOLD'
|
Set the autoloading size threshold, in megabytes. If THRESHOLD is
|
Set the autoloading size threshold, in megabytes. If THRESHOLD is
|
nonzero, symbols from all shared object libraries will be loaded
|
nonzero, symbols from all shared object libraries will be loaded
|
automatically when the inferior begins execution or when the
|
automatically when the inferior begins execution or when the
|
dynamic linker informs GDB that a new library has been loaded,
|
dynamic linker informs GDB that a new library has been loaded,
|
until the symbol table of the program and libraries exceeds this
|
until the symbol table of the program and libraries exceeds this
|
threshold. Otherwise, symbols must be loaded manually, using the
|
threshold. Otherwise, symbols must be loaded manually, using the
|
`sharedlibrary' command. The default threshold is 100 megabytes.
|
`sharedlibrary' command. The default threshold is 100 megabytes.
|
|
|
`show auto-solib-add'
|
`show auto-solib-add'
|
Display the current autoloading size threshold, in megabytes.
|
Display the current autoloading size threshold, in megabytes.
|
|
|
|
|
File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files
|
File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files
|
|
|
Errors reading symbol files
|
Errors reading symbol files
|
===========================
|
===========================
|
|
|
While reading a symbol file, GDB occasionally encounters problems,
|
While reading a symbol file, GDB occasionally encounters problems,
|
such as symbol types it does not recognize, or known bugs in compiler
|
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
|
output. By default, GDB does not notify you of such problems, since
|
they are relatively common and primarily of interest to people
|
they are relatively common and primarily of interest to people
|
debugging compilers. If you are interested in seeing information about
|
debugging compilers. If you are interested in seeing information about
|
ill-constructed symbol tables, you can either ask GDB to print only one
|
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
|
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
|
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
|
many times the problems occur, with the `set complaints' command (*note
|
Optional warnings and messages: Messages/Warnings.).
|
Optional warnings and messages: Messages/Warnings.).
|
|
|
The messages currently printed, and their meanings, include:
|
The messages currently printed, and their meanings, include:
|
|
|
`inner block not inside outer block in SYMBOL'
|
`inner block not inside outer block in SYMBOL'
|
The symbol information shows where symbol scopes begin and end
|
The symbol information shows where symbol scopes begin and end
|
(such as at the start of a function or a block of statements).
|
(such as at the start of a function or a block of statements).
|
This error indicates that an inner scope block is not fully
|
This error indicates that an inner scope block is not fully
|
contained in its outer scope blocks.
|
contained in its outer scope blocks.
|
|
|
GDB circumvents the problem by treating the inner block as if it
|
GDB circumvents the problem by treating the inner block as if it
|
had the same scope as the outer block. In the error message,
|
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
|
SYMBOL may be shown as "`(don't know)'" if the outer block is not a
|
function.
|
function.
|
|
|
`block at ADDRESS out of order'
|
`block at ADDRESS out of order'
|
The symbol information for symbol scope blocks should occur in
|
The symbol information for symbol scope blocks should occur in
|
order of increasing addresses. This error indicates that it does
|
order of increasing addresses. This error indicates that it does
|
not do so.
|
not do so.
|
|
|
GDB does not circumvent this problem, and has trouble locating
|
GDB does not circumvent this problem, and has trouble locating
|
symbols in the source file whose symbols it is reading. (You can
|
symbols in the source file whose symbols it is reading. (You can
|
often determine what source file is affected by specifying `set
|
often determine what source file is affected by specifying `set
|
verbose on'. *Note Optional warnings and messages:
|
verbose on'. *Note Optional warnings and messages:
|
Messages/Warnings.)
|
Messages/Warnings.)
|
|
|
`bad block start address patched'
|
`bad block start address patched'
|
The symbol information for a symbol scope block has a start address
|
The symbol information for a symbol scope block has a start address
|
smaller than the address of the preceding source line. This is
|
smaller than the address of the preceding source line. This is
|
known to occur in the SunOS 4.1.1 (and earlier) C compiler.
|
known to occur in the SunOS 4.1.1 (and earlier) C compiler.
|
|
|
GDB circumvents the problem by treating the symbol scope block as
|
GDB circumvents the problem by treating the symbol scope block as
|
starting on the previous source line.
|
starting on the previous source line.
|
|
|
`bad string table offset in symbol N'
|
`bad string table offset in symbol N'
|
Symbol number N contains a pointer into the string table which is
|
Symbol number N contains a pointer into the string table which is
|
larger than the size of the string table.
|
larger than the size of the string table.
|
|
|
GDB circumvents the problem by considering the symbol to have the
|
GDB circumvents the problem by considering the symbol to have the
|
name `foo', which may cause other problems if many symbols end up
|
name `foo', which may cause other problems if many symbols end up
|
with this name.
|
with this name.
|
|
|
`unknown symbol type `0xNN''
|
`unknown symbol type `0xNN''
|
The symbol information contains new data types that GDB does not
|
The symbol information contains new data types that GDB does not
|
yet know how to read. `0xNN' is the symbol type of the
|
yet know how to read. `0xNN' is the symbol type of the
|
uncomprehended information, in hexadecimal.
|
uncomprehended information, in hexadecimal.
|
|
|
GDB circumvents the error by ignoring this symbol information.
|
GDB circumvents the error by ignoring this symbol information.
|
This usually allows you to debug your program, though certain
|
This usually allows you to debug your program, though certain
|
symbols are not accessible. If you encounter such a problem and
|
symbols are not accessible. If you encounter such a problem and
|
feel like debugging it, you can debug `gdb' with itself, breakpoint
|
feel like debugging it, you can debug `gdb' with itself, breakpoint
|
on `complain', then go up to the function `read_dbx_symtab' and
|
on `complain', then go up to the function `read_dbx_symtab' and
|
examine `*bufp' to see the symbol.
|
examine `*bufp' to see the symbol.
|
|
|
`stub type has NULL name'
|
`stub type has NULL name'
|
GDB could not find the full definition for a struct or class.
|
GDB could not find the full definition for a struct or class.
|
|
|
`const/volatile indicator missing (ok if using g++ v1.x), got...'
|
`const/volatile indicator missing (ok if using g++ v1.x), got...'
|
The symbol information for a C++ member function is missing some
|
The symbol information for a C++ member function is missing some
|
information that recent versions of the compiler should have
|
information that recent versions of the compiler should have
|
output for it.
|
output for it.
|
|
|
`info mismatch between compiler and debugger'
|
`info mismatch between compiler and debugger'
|
GDB could not parse a type specification output by the compiler.
|
GDB could not parse a type specification output by the compiler.
|
|
|
|
|
File: gdb.info, Node: Targets, Next: Configurations, Prev: GDB Files, Up: Top
|
File: gdb.info, Node: Targets, Next: Configurations, Prev: GDB Files, Up: Top
|
|
|
Specifying a Debugging Target
|
Specifying a Debugging Target
|
*****************************
|
*****************************
|
|
|
A "target" is the execution environment occupied by your program.
|
A "target" is the execution environment occupied by your program.
|
|
|
Often, GDB runs in the same host environment as your program; in
|
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
|
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
|
use the `file' or `core' commands. When you need more flexibility--for
|
example, running GDB on a physically separate host, or controlling a
|
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
|
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
|
connection--you can use the `target' command to specify one of the
|
target types configured for GDB (*note Commands for managing targets:
|
target types configured for GDB (*note Commands for managing targets:
|
Target Commands.).
|
Target Commands.).
|
|
|
* Menu:
|
* Menu:
|
|
|
* Active Targets:: Active targets
|
* Active Targets:: Active targets
|
* Target Commands:: Commands for managing targets
|
* Target Commands:: Commands for managing targets
|
* Byte Order:: Choosing target byte order
|
* Byte Order:: Choosing target byte order
|
* Remote:: Remote debugging
|
* Remote:: Remote debugging
|
* KOD:: Kernel Object Display
|
* KOD:: Kernel Object Display
|
|
|
|
|
File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets
|
File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets
|
|
|
Active targets
|
Active targets
|
==============
|
==============
|
|
|
There are three classes of targets: processes, core files, and
|
There are three classes of targets: processes, core files, and
|
executable files. GDB can work concurrently on up to three active
|
executable files. GDB can work concurrently on up to three active
|
targets, one in each class. This allows you to (for example) start a
|
targets, one in each class. This allows you to (for example) start a
|
process and inspect its activity without abandoning your work on a core
|
process and inspect its activity without abandoning your work on a core
|
file.
|
file.
|
|
|
For example, if you execute `gdb a.out', then the executable file
|
For example, if you execute `gdb a.out', then the executable file
|
`a.out' is the only active target. If you designate a core file as
|
`a.out' is the only active target. If you designate a core file as
|
well--presumably from a prior run that crashed and coredumped--then GDB
|
well--presumably from a prior run that crashed and coredumped--then GDB
|
has two active targets and uses them in tandem, looking first in the
|
has two active targets and uses them in tandem, looking first in the
|
corefile target, then in the executable file, to satisfy requests for
|
corefile target, then in the executable file, to satisfy requests for
|
memory addresses. (Typically, these two classes of target are
|
memory addresses. (Typically, these two classes of target are
|
complementary, since core files contain only a program's read-write
|
complementary, since core files contain only a program's read-write
|
memory--variables and so on--plus machine status, while executable
|
memory--variables and so on--plus machine status, while executable
|
files contain only the program text and initialized data.)
|
files contain only the program text and initialized data.)
|
|
|
When you type `run', your executable file becomes an active process
|
When you type `run', your executable file becomes an active process
|
target as well. When a process target is active, all GDB commands
|
target as well. When a process target is active, all GDB commands
|
requesting memory addresses refer to that target; addresses in an
|
requesting memory addresses refer to that target; addresses in an
|
active core file or executable file target are obscured while the
|
active core file or executable file target are obscured while the
|
process target is active.
|
process target is active.
|
|
|
Use the `core-file' and `exec-file' commands to select a new core
|
Use the `core-file' and `exec-file' commands to select a new core
|
file or executable target (*note Commands to specify files: Files.).
|
file or executable target (*note Commands to specify files: Files.).
|
To specify as a target a process that is already running, use the
|
To specify as a target a process that is already running, use the
|
`attach' command (*note Debugging an already-running process: Attach.).
|
`attach' command (*note Debugging an already-running process: Attach.).
|
|
|
|
|
File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
|
File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
|
|
|
Commands for managing targets
|
Commands for managing targets
|
=============================
|
=============================
|
|
|
`target TYPE PARAMETERS'
|
`target TYPE PARAMETERS'
|
Connects the GDB host environment to a target machine or process.
|
Connects the GDB host environment to a target machine or process.
|
A target is typically a protocol for talking to debugging
|
A target is typically a protocol for talking to debugging
|
facilities. You use the argument TYPE to specify the type or
|
facilities. You use the argument TYPE to specify the type or
|
protocol of the target machine.
|
protocol of the target machine.
|
|
|
Further PARAMETERS are interpreted by the target protocol, but
|
Further PARAMETERS are interpreted by the target protocol, but
|
typically include things like device names or host names to connect
|
typically include things like device names or host names to connect
|
with, process numbers, and baud rates.
|
with, process numbers, and baud rates.
|
|
|
The `target' command does not repeat if you press again
|
The `target' command does not repeat if you press again
|
after executing the command.
|
after executing the command.
|
|
|
`help target'
|
`help target'
|
Displays the names of all targets available. To display targets
|
Displays the names of all targets available. To display targets
|
currently selected, use either `info target' or `info files'
|
currently selected, use either `info target' or `info files'
|
(*note Commands to specify files: Files.).
|
(*note Commands to specify files: Files.).
|
|
|
`help target NAME'
|
`help target NAME'
|
Describe a particular target, including any parameters necessary to
|
Describe a particular target, including any parameters necessary to
|
select it.
|
select it.
|
|
|
`set gnutarget ARGS'
|
`set gnutarget ARGS'
|
GDB uses its own library BFD to read your files. GDB knows
|
GDB uses its own library BFD to read your files. GDB knows
|
whether it is reading an "executable", a "core", or a ".o" file;
|
whether it is reading an "executable", a "core", or a ".o" file;
|
however, you can specify the file format with the `set gnutarget'
|
however, you can specify the file format with the `set gnutarget'
|
command. Unlike most `target' commands, with `gnutarget' the
|
command. Unlike most `target' commands, with `gnutarget' the
|
`target' refers to a program, not a machine.
|
`target' refers to a program, not a machine.
|
|
|
_Warning:_ To specify a file format with `set gnutarget', you
|
_Warning:_ To specify a file format with `set gnutarget', you
|
must know the actual BFD name.
|
must know the actual BFD name.
|
|
|
*Note Commands to specify files: Files.
|
*Note Commands to specify files: Files.
|
|
|
`show gnutarget'
|
`show gnutarget'
|
Use the `show gnutarget' command to display what file format
|
Use the `show gnutarget' command to display what file format
|
`gnutarget' is set to read. If you have not set `gnutarget', GDB
|
`gnutarget' is set to read. If you have not set `gnutarget', GDB
|
will determine the file format for each file automatically, and
|
will determine the file format for each file automatically, and
|
`show gnutarget' displays `The current BDF target is "auto"'.
|
`show gnutarget' displays `The current BDF target is "auto"'.
|
|
|
Here are some common targets (available, or not, depending on the GDB
|
Here are some common targets (available, or not, depending on the GDB
|
configuration):
|
configuration):
|
|
|
`target exec PROGRAM'
|
`target exec PROGRAM'
|
An executable file. `target exec PROGRAM' is the same as
|
An executable file. `target exec PROGRAM' is the same as
|
`exec-file PROGRAM'.
|
`exec-file PROGRAM'.
|
|
|
`target core FILENAME'
|
`target core FILENAME'
|
A core dump file. `target core FILENAME' is the same as
|
A core dump file. `target core FILENAME' is the same as
|
`core-file FILENAME'.
|
`core-file FILENAME'.
|
|
|
`target remote DEV'
|
`target remote DEV'
|
Remote serial target in GDB-specific protocol. The argument DEV
|
Remote serial target in GDB-specific protocol. The argument DEV
|
specifies what serial device to use for the connection (e.g.
|
specifies what serial device to use for the connection (e.g.
|
`/dev/ttya'). *Note Remote debugging: Remote. `target remote'
|
`/dev/ttya'). *Note Remote debugging: Remote. `target remote'
|
supports the `load' command. This is only useful if you have some
|
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
|
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
|
it somewhere in memory where it won't get clobbered by the
|
download.
|
download.
|
|
|
`target sim'
|
`target sim'
|
Builtin CPU simulator. GDB includes simulators for most
|
Builtin CPU simulator. GDB includes simulators for most
|
architectures. In general,
|
architectures. In general,
|
target sim
|
target sim
|
load
|
load
|
run
|
run
|
|
|
works; however, you cannot assume that a specific memory map,
|
works; however, you cannot assume that a specific memory map,
|
device drivers, or even basic I/O is available, although some
|
device drivers, or even basic I/O is available, although some
|
simulators do provide these. For info about any
|
simulators do provide these. For info about any
|
processor-specific simulator details, see the appropriate section
|
processor-specific simulator details, see the appropriate section
|
in *Note Embedded Processors: Embedded Processors.
|
in *Note Embedded Processors: Embedded Processors.
|
|
|
Some configurations may include these targets as well:
|
Some configurations may include these targets as well:
|
|
|
`target nrom DEV'
|
`target nrom DEV'
|
NetROM ROM emulator. This target only supports downloading.
|
NetROM ROM emulator. This target only supports downloading.
|
|
|
Different targets are available on different configurations of GDB;
|
Different targets are available on different configurations of GDB;
|
your configuration may have more or fewer targets.
|
your configuration may have more or fewer targets.
|
|
|
Many remote targets require you to download the executable's code
|
Many remote targets require you to download the executable's code
|
once you've successfully established a connection.
|
once you've successfully established a connection.
|
|
|
`load FILENAME'
|
`load FILENAME'
|
Depending on what remote debugging facilities are configured into
|
Depending on what remote debugging facilities are configured into
|
GDB, the `load' command may be available. Where it exists, it is
|
GDB, the `load' command may be available. Where it exists, it is
|
meant to make FILENAME (an executable) available for debugging on
|
meant to make FILENAME (an executable) available for debugging on
|
the remote system--by downloading, or dynamic linking, for example.
|
the remote system--by downloading, or dynamic linking, for example.
|
`load' also records the FILENAME symbol table in GDB, like the
|
`load' also records the FILENAME symbol table in GDB, like the
|
`add-symbol-file' command.
|
`add-symbol-file' command.
|
|
|
If your GDB does not have a `load' command, attempting to execute
|
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
|
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
|
The file is loaded at whatever address is specified in the
|
executable. For some object file formats, you can specify the
|
executable. For some object file formats, you can specify the
|
load address when you link the program; for other formats, like
|
load address when you link the program; for other formats, like
|
a.out, the object file format specifies a fixed address.
|
a.out, the object file format specifies a fixed address.
|
|
|
`load' does not repeat if you press again after using it.
|
`load' does not repeat if you press again after using it.
|
|
|
|
|
File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
|
File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
|
|
|
Choosing target byte order
|
Choosing target byte order
|
==========================
|
==========================
|
|
|
Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
|
Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
|
offer the ability to run either big-endian or little-endian byte
|
offer the ability to run either big-endian or little-endian byte
|
orders. Usually the executable or symbol will include a bit to
|
orders. Usually the executable or symbol will include a bit to
|
designate the endian-ness, and you will not need to worry about which
|
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
|
to use. However, you may still find it useful to adjust GDB's idea of
|
processor endian-ness manually.
|
processor endian-ness manually.
|
|
|
`set endian big'
|
`set endian big'
|
Instruct GDB to assume the target is big-endian.
|
Instruct GDB to assume the target is big-endian.
|
|
|
`set endian little'
|
`set endian little'
|
Instruct GDB to assume the target is little-endian.
|
Instruct GDB to assume the target is little-endian.
|
|
|
`set endian auto'
|
`set endian auto'
|
Instruct GDB to use the byte order associated with the executable.
|
Instruct GDB to use the byte order associated with the executable.
|
|
|
`show endian'
|
`show endian'
|
Display GDB's current idea of the target byte order.
|
Display GDB's current idea of the target byte order.
|
|
|
Note that these commands merely adjust interpretation of symbolic
|
Note that these commands merely adjust interpretation of symbolic
|
data on the host, and that they have absolutely no effect on the target
|
data on the host, and that they have absolutely no effect on the target
|
system.
|
system.
|
|
|
|
|
File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets
|
File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets
|
|
|
Remote debugging
|
Remote debugging
|
================
|
================
|
|
|
If you are trying to debug a program running on a machine that
|
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
|
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
|
debugging. For example, you might use remote debugging on an operating
|
system kernel, or on a small system which does not have a general
|
system kernel, or on a small system which does not have a general
|
purpose operating system powerful enough to run a full-featured
|
purpose operating system powerful enough to run a full-featured
|
debugger.
|
debugger.
|
|
|
Some configurations of GDB have special serial or TCP/IP interfaces
|
Some configurations of GDB have special serial or TCP/IP interfaces
|
to make this work with particular debugging targets. In addition, GDB
|
to make this work with particular debugging targets. In addition, GDB
|
comes with a generic serial protocol (specific to GDB, but not specific
|
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
|
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
|
remote stubs--the code that runs on the remote system to communicate
|
with GDB.
|
with GDB.
|
|
|
Other remote targets may be available in your configuration of GDB;
|
Other remote targets may be available in your configuration of GDB;
|
use `help target' to list them.
|
use `help target' to list them.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Remote Serial:: GDB remote serial protocol
|
* Remote Serial:: GDB remote serial protocol
|
|
|
|
|
File: gdb.info, Node: Remote Serial, Up: Remote
|
File: gdb.info, Node: Remote Serial, Up: Remote
|
|
|
The GDB remote serial protocol
|
The GDB remote serial protocol
|
------------------------------
|
------------------------------
|
|
|
To debug a program running on another machine (the debugging
|
To debug a program running on another machine (the debugging
|
"target" machine), you must first arrange for all the usual
|
"target" machine), you must first arrange for all the usual
|
prerequisites for the program to run by itself. For example, for a C
|
prerequisites for the program to run by itself. For example, for a C
|
program, you need:
|
program, you need:
|
|
|
1. A startup routine to set up the C runtime environment; these
|
1. A startup routine to set up the C runtime environment; these
|
usually have a name like `crt0'. The startup routine may be
|
usually have a name like `crt0'. The startup routine may be
|
supplied by your hardware supplier, or you may have to write your
|
supplied by your hardware supplier, or you may have to write your
|
own.
|
own.
|
|
|
2. A C subroutine library to support your program's subroutine calls,
|
2. A C subroutine library to support your program's subroutine calls,
|
notably managing input and output.
|
notably managing input and output.
|
|
|
3. A way of getting your program to the other machine--for example, a
|
3. A way of getting your program to the other machine--for example, a
|
download program. These are often supplied by the hardware
|
download program. These are often supplied by the hardware
|
manufacturer, but you may have to write your own from hardware
|
manufacturer, but you may have to write your own from hardware
|
documentation.
|
documentation.
|
|
|
The next step is to arrange for your program to use a serial port to
|
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).
|
communicate with the machine where GDB is running (the "host" machine).
|
In general terms, the scheme looks like this:
|
In general terms, the scheme looks like this:
|
|
|
_On the host,_
|
_On the host,_
|
GDB already understands how to use this protocol; when everything
|
GDB already understands how to use this protocol; when everything
|
else is set up, you can simply use the `target remote' command
|
else is set up, you can simply use the `target remote' command
|
(*note Specifying a Debugging Target: Targets.).
|
(*note Specifying a Debugging Target: Targets.).
|
|
|
_On the target,_
|
_On the target,_
|
you must link with your program a few special-purpose subroutines
|
you must link with your program a few special-purpose subroutines
|
that implement the GDB remote serial protocol. The file
|
that implement the GDB remote serial protocol. The file
|
containing these subroutines is called a "debugging stub".
|
containing these subroutines is called a "debugging stub".
|
|
|
On certain remote targets, you can use an auxiliary program
|
On certain remote targets, you can use an auxiliary program
|
`gdbserver' instead of linking a stub into your program. *Note
|
`gdbserver' instead of linking a stub into your program. *Note
|
Using the `gdbserver' program: Server, for details.
|
Using the `gdbserver' program: Server, for details.
|
|
|
The debugging stub is specific to the architecture of the remote
|
The debugging stub is specific to the architecture of the remote
|
machine; for example, use `sparc-stub.c' to debug programs on SPARC
|
machine; for example, use `sparc-stub.c' to debug programs on SPARC
|
boards.
|
boards.
|
|
|
These working remote stubs are distributed with GDB:
|
These working remote stubs are distributed with GDB:
|
|
|
`i386-stub.c'
|
`i386-stub.c'
|
For Intel 386 and compatible architectures.
|
For Intel 386 and compatible architectures.
|
|
|
`m68k-stub.c'
|
`m68k-stub.c'
|
For Motorola 680x0 architectures.
|
For Motorola 680x0 architectures.
|
|
|
`sh-stub.c'
|
`sh-stub.c'
|
For Hitachi SH architectures.
|
For Hitachi SH architectures.
|
|
|
`sparc-stub.c'
|
`sparc-stub.c'
|
For SPARC architectures.
|
For SPARC architectures.
|
|
|
`sparcl-stub.c'
|
`sparcl-stub.c'
|
For Fujitsu SPARCLITE architectures.
|
For Fujitsu SPARCLITE architectures.
|
|
|
The `README' file in the GDB distribution may list other recently
|
The `README' file in the GDB distribution may list other recently
|
added stubs.
|
added stubs.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Stub Contents:: What the stub can do for you
|
* Stub Contents:: What the stub can do for you
|
* Bootstrapping:: What you must do for the stub
|
* Bootstrapping:: What you must do for the stub
|
* Debug Session:: Putting it all together
|
* Debug Session:: Putting it all together
|
* Protocol:: Definition of the communication protocol
|
* Protocol:: Definition of the communication protocol
|
* Server:: Using the `gdbserver' program
|
* Server:: Using the `gdbserver' program
|
* NetWare:: Using the `gdbserve.nlm' program
|
* NetWare:: Using the `gdbserve.nlm' program
|
|
|
|
|
File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial
|
File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial
|
|
|
What the stub can do for you
|
What the stub can do for you
|
............................
|
............................
|
|
|
The debugging stub for your architecture supplies these three
|
The debugging stub for your architecture supplies these three
|
subroutines:
|
subroutines:
|
|
|
`set_debug_traps'
|
`set_debug_traps'
|
This routine arranges for `handle_exception' to run when your
|
This routine arranges for `handle_exception' to run when your
|
program stops. You must call this subroutine explicitly near the
|
program stops. You must call this subroutine explicitly near the
|
beginning of your program.
|
beginning of your program.
|
|
|
`handle_exception'
|
`handle_exception'
|
This is the central workhorse, but your program never calls it
|
This is the central workhorse, but your program never calls it
|
explicitly--the setup code arranges for `handle_exception' to run
|
explicitly--the setup code arranges for `handle_exception' to run
|
when a trap is triggered.
|
when a trap is triggered.
|
|
|
`handle_exception' takes control when your program stops during
|
`handle_exception' takes control when your program stops during
|
execution (for example, on a breakpoint), and mediates
|
execution (for example, on a breakpoint), and mediates
|
communications with GDB on the host machine. This is where the
|
communications with GDB on the host machine. This is where the
|
communications protocol is implemented; `handle_exception' acts as
|
communications protocol is implemented; `handle_exception' acts as
|
the GDB representative on the target machine. It begins by
|
the GDB representative on the target machine. It begins by
|
sending summary information on the state of your program, then
|
sending summary information on the state of your program, then
|
continues to execute, retrieving and transmitting any information
|
continues to execute, retrieving and transmitting any information
|
GDB needs, until you execute a GDB command that makes your program
|
GDB needs, until you execute a GDB command that makes your program
|
resume; at that point, `handle_exception' returns control to your
|
resume; at that point, `handle_exception' returns control to your
|
own code on the target machine.
|
own code on the target machine.
|
|
|
`breakpoint'
|
`breakpoint'
|
Use this auxiliary subroutine to make your program contain a
|
Use this auxiliary subroutine to make your program contain a
|
breakpoint. Depending on the particular situation, this may be
|
breakpoint. Depending on the particular situation, this may be
|
the only way for GDB to get control. For instance, if your target
|
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
|
machine has some sort of interrupt button, you won't need to call
|
this; pressing the interrupt button transfers control to
|
this; pressing the interrupt button transfers control to
|
`handle_exception'--in effect, to GDB. On some machines, simply
|
`handle_exception'--in effect, to GDB. On some machines, simply
|
receiving characters on the serial port may also trigger a trap;
|
receiving characters on the serial port may also trigger a trap;
|
again, in that situation, you don't need to call `breakpoint' from
|
again, in that situation, you don't need to call `breakpoint' from
|
your own program--simply running `target remote' from the host GDB
|
your own program--simply running `target remote' from the host GDB
|
session gets control.
|
session gets control.
|
|
|
Call `breakpoint' if none of these is true, or if you simply want
|
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
|
to make certain your program stops at a predetermined point for the
|
start of your debugging session.
|
start of your debugging session.
|
|
|
|
|