1470 lines
43 KiB
Text
1470 lines
43 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename libgdb.info
|
|
@settitle Libgdb
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
This file documents libgdb, the GNU library for symbolic debuggers.
|
|
|
|
Copyright 1993 Cygnus Support
|
|
|
|
Permission is granted to ...
|
|
@end ifinfo
|
|
|
|
@c This title page illustrates only one of the
|
|
@c two methods of forming a title page.
|
|
|
|
@titlepage
|
|
@title Libgdb
|
|
@subtitle Version 0.1
|
|
@subtitle 27 Sep 1993
|
|
@author Thomas Lord
|
|
|
|
@c The following two commands
|
|
@c start the copyright page.
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1993 COPYRIGHT-OWNER
|
|
|
|
Published by ...
|
|
|
|
Permission is granted to ...
|
|
@end titlepage
|
|
|
|
@node Top, Overview, (dir), (dir)
|
|
|
|
@ifinfo
|
|
|
|
Libgdb is a library which provides the core functionality of a symbolic
|
|
debugger. It is derived from GNU GDB and depends on the BFD library.
|
|
|
|
This is an early draft of this document. Subsequent versions will likely
|
|
contain revisions, deletions and additions.
|
|
|
|
This document applies to version 0.0.
|
|
|
|
Text marked `[[[' indicates areas which require expansion.
|
|
|
|
Many nodes describe library entry points by giving a prototype and brief
|
|
description:
|
|
|
|
@deftypefun {const char **} gdb_warranty ()
|
|
(warranty_info)
|
|
Return a pointer to the text of the GDB disclaimer.
|
|
@end deftypefun
|
|
|
|
The parenthesized symbols (e.g. `(warranty_info)') refer to the
|
|
existing GDB source and generally indicate where to find code with
|
|
which to implement the library function.
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Copying:: Your rights and freedoms.
|
|
* Overview:: The basics of libgdb and this document.
|
|
* Conventions:: Programming conventions for users of libgdb.
|
|
* Targets:: Selecting debugging targets and symbol tables.
|
|
* Symtabs:: Accessing symbol tables and debugging information.
|
|
* Source:: Relating inferiors to source files.
|
|
* Running:: Creating, continuing, and stepping through an
|
|
inferior process.
|
|
* Stopping:: Using breakpoints, signaling an inferior.
|
|
* Stack:: Accessing an inferior's execution stack.
|
|
* Expressions:: How to parse and evaluate expressions in the
|
|
context of an inferior.
|
|
* Values:: Data from the inferior, the values of expressions.
|
|
* Examining:: Formatting values as strings.
|
|
* Types:: Examining the types of an inferiors data.
|
|
@end menu
|
|
|
|
|
|
@node Copying, Overview, top, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Copying
|
|
@cindex copying
|
|
|
|
blah blah
|
|
|
|
@node Overview, Conventions, Copying, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Overview
|
|
@cindex overview
|
|
@cindex definitions
|
|
|
|
|
|
Libgdb is a library which provides the core functionality of a symbolic
|
|
debugger. It is derived from GNU GDB and depends on the BFD library.
|
|
|
|
target
|
|
inferior
|
|
|
|
|
|
|
|
@node Conventions, Targets, Overview, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Programming Conventions for Libgdb Clients
|
|
@cindex Conventions
|
|
|
|
@heading Naming Conventions
|
|
|
|
Names intentionally exported from libgdb all begin @code{gdb_}
|
|
as in @code{gdb_use_file}.
|
|
|
|
|
|
@heading Error Returns
|
|
|
|
Libgdb functions that might not succeed generally have a return
|
|
type of @code{gdb_error_t}.
|
|
|
|
@deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error})
|
|
returns a reasonable error message for @var{error}.
|
|
@end defun
|
|
|
|
|
|
@heading Blocking I/O
|
|
|
|
[[[....]]]
|
|
|
|
|
|
@heading Global Parameters
|
|
@subheading the current directory
|
|
@deftypefun error_t gdb_cd (char * @var{dir})
|
|
Specify gdb's default directory as well as the working
|
|
directory for the inferior (when first started).@*
|
|
(cd_command)
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} gdb_copy_pwd ()
|
|
Make a copy of the name of gdb's default directory.@*
|
|
(pwd_command)
|
|
@end deftypefun
|
|
|
|
|
|
@subheading controlling the input/output radix
|
|
@deftypefun error_t gdb_set_base (int)
|
|
Change the default output radix to 10 or 16, or set it to 0
|
|
(heuristic). This command is mostly obsolete now that the print
|
|
command allows formats to apply to aggregates, but is still handy
|
|
occasionally.@*
|
|
(set_base_command)
|
|
@end deftypefun
|
|
|
|
@deftypefun error_t gdb_set_input_radix (int)
|
|
@deftypefunx error_t gdb_set_output_radix (int)
|
|
@deftypefunx error_t gdb_set_radix (int)
|
|
Valid output radixes are only 0 (heuristic), 10, and 16.@*
|
|
(set_radix)
|
|
@end deftypefun
|
|
|
|
|
|
@subheading manipulating environments
|
|
@deftp Type {struct environ}
|
|
@example
|
|
struct environ
|
|
@{
|
|
int allocated;
|
|
char ** vector;
|
|
@}
|
|
@end example
|
|
A `struct environ' holds a description of environment
|
|
variable bindings.
|
|
@end deftp
|
|
|
|
@deftypefun {struct environ *} gdb_make_environ ()
|
|
Create a new (empty) environment.@*
|
|
(make_environ)
|
|
@end deftypefun
|
|
|
|
@deftypefun {void} gdb_free_environ (struct environ *)
|
|
Free an environment allocated by `gdb_make_environ'.@*
|
|
(free_environ)
|
|
@end deftypefun
|
|
|
|
@deftypefun {void} gdb_init_environ (struct environ * env)
|
|
Copy the processes environment into ENV.@*
|
|
(init_environ)
|
|
@end deftypefun
|
|
|
|
@deftypefun {char **} gdb_get_in_environ (const struct environ * @var{env}, const char * @var{var})
|
|
Look up the binding of @var{var} in @var{env}.@*
|
|
(get_in_environ)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {void} gdb_set_in_environ (struct environ * @var{env}, const char * @var{var}, const char * @var{value})
|
|
Lookup/bind variables within an environment.
|
|
(set_in_environ)
|
|
@end deftypefun
|
|
|
|
|
|
@subheading legal notices
|
|
@deftypefun {char **} gdb_copying ()
|
|
@deftypefunx {char **} gdb_warranty ()
|
|
These return pointers to NULL terminated arrays of strings.
|
|
They contain text which describes the conditions under which
|
|
libgdb is distributed (`gdb_copying') and which explains to
|
|
users that there is no warranty for libgdb (`gdb_warranty').@*
|
|
(show_warranty_command, show_copying_command)
|
|
@end deftypefun
|
|
|
|
|
|
@subheading the inferior's terminal
|
|
@deftypefun void gdb_inferiors_io (int @var{std_in}, int @var{std_out}, int @var{std_err})
|
|
Assert that the given descriptors should be copied into
|
|
descriptors 0, 1, and 2 of the inferior when it
|
|
is next run.
|
|
@end deftypefun
|
|
|
|
|
|
@heading callbacks
|
|
|
|
One idiom used in several places deserves mention.
|
|
At times, it makes sense for libgdb functions to
|
|
invoke functions provided by the libgdb client.
|
|
Where this is the case, callback structures are used
|
|
to refer to client functions. For example, here
|
|
are the declarations for a callback to which libgdb
|
|
will pass an integer and a character pointer.
|
|
|
|
@example
|
|
struct a_gdb_cback;
|
|
typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *,
|
|
int, char *);
|
|
@end example
|
|
|
|
Suppose the client wants the callback to be implemented
|
|
by @code{foo} which we will assume takes not only the integer
|
|
and character pointer, but also a floating point number.
|
|
The client could use these declarations:
|
|
|
|
@example
|
|
struct my_cback
|
|
{
|
|
struct a_gdb_cback gdb_cback; /* must be first */
|
|
float magic_number;
|
|
};
|
|
|
|
void
|
|
foo_helper (struct a_gdb_cback * callback, int i, char * cp)
|
|
{
|
|
foo ( ((struct my_cback *)callback)->magic_number, i, c);
|
|
}
|
|
|
|
struct my_cback
|
|
{
|
|
foo_helper,
|
|
1079252848.8
|
|
} the_cback;
|
|
@end example
|
|
|
|
|
|
@subheading stream callbacks
|
|
|
|
A common kind of callback takes just a character pointer,
|
|
presumed to point to part or all of an informational
|
|
message.
|
|
|
|
@example
|
|
struct gdb_stream_cback;
|
|
typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *,
|
|
char *);
|
|
@end example
|
|
|
|
|
|
@subheading integer callbacks
|
|
|
|
Another common kind of callback takes just an integer.
|
|
|
|
@example
|
|
struct gdb_int_cback;
|
|
typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int);
|
|
@end example
|
|
|
|
@node Targets, Symtabs, Conventions, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Selecting Targets and Symbol Tables for Debugging
|
|
@cindex targets
|
|
|
|
@deftypefun gdb_error_t gdb_use_file (char * @var{filename})
|
|
Arrange to read both executable code and symbol table information
|
|
from FILENAME.
|
|
|
|
This is exactly equivalent to a sequence of two calls:
|
|
@example
|
|
gdb_use_exec_file (filename);
|
|
gdb_use_symbol_file (filename);
|
|
@end example
|
|
(file_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_use_exec_file (char * @var{filename})
|
|
Read the code to debug from `filename'.@*
|
|
(exec_file_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {char *} gdb_get_exec_file ()
|
|
Return the name of the executable file as a string or 0
|
|
if there is none.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_use_core (char * @var{filename})
|
|
Specify the whereabouts of a core dump file to be used as the
|
|
"contents of memory". Traditionally, core files contain only some
|
|
parts of the address space of the process that generated them; GDB
|
|
can access the executable file itself for other parts.
|
|
|
|
If @var{filename} is @code{NULL}, no core file is used.@*
|
|
(core_file_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_use_symbol_file (char * @var{filename})
|
|
Arrange to read symbol table information from `filename'.
|
|
|
|
This is the same as:
|
|
|
|
gdb_symbol_file_add (filename, 1, (CORE_ADDR)0, 1, 0, 0);
|
|
|
|
See @code{gdb_symbol_file_add} for finer control over the symbol
|
|
table.@*
|
|
(symbol_file_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_symbol_file_add (@var{name}, @var{verbose}, @var{text_addr}, @var{replace}, @var{eager})
|
|
Arrange to read additional symbol table information from
|
|
the file `name'.
|
|
|
|
The arguments are:
|
|
@itemize @minus
|
|
@item struct gdb_stream_cback * @var{info_out}
|
|
|
|
Callback to handle informational output.
|
|
|
|
@item char * @var{name}
|
|
|
|
If not 0, verbose output will occur.
|
|
|
|
@item int @var{be_verbose}
|
|
|
|
Regulates the amount of informational output produced.
|
|
|
|
@item CORE_ADDR @var{text_addr}
|
|
|
|
is the address at which the named file is presumed to have
|
|
been loaded.
|
|
|
|
@item int @var{replace}@*
|
|
|
|
If not 0, this will become the only file
|
|
in the symbol table -- all previously loaded
|
|
symbol table information will be discarded.
|
|
|
|
@item int @var{readnow}
|
|
|
|
If not 0, eagerly read symbols from this file,otherwise
|
|
symbols will only be read lazily (as needed).
|
|
@end itemize
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {char *} gdb_copy_exec_path ()
|
|
Make a copy of the execution path.@*
|
|
[[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]@*
|
|
(path_info)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_mod_exec_path (char * @var{dirnames})
|
|
Add zero or more directories to the front of the execution path.
|
|
@var{dirnames} should be a colon separated list of directory names.@*
|
|
(path_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_target_device (char * @var{name})
|
|
Connects the libgdb host environment to a target machine
|
|
or process.@*
|
|
(target foo)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_set_baud (int @var{rate})
|
|
If using a remote target connected by a serial port,
|
|
use RATE as the communication speed.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_set_target_debugging (int @var{level})
|
|
Choose the level of verboseness of with which a remote
|
|
target produces debugging output.
|
|
@end deftypefun
|
|
|
|
@node Symtabs, Source, Targets, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Accessing symbol tables and debugging information.
|
|
@cindex Symtabs
|
|
@cindex {Symbol Tables}
|
|
|
|
@deftp Type {struct symtab}
|
|
Each source file is represented by a struct symtab.
|
|
In many contexts, @code{struct symtab *} is used in preference
|
|
to a {char *} filename to refer to the source.
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {char *} gdb_symtab_to_filename (struct symtab *)
|
|
@deftypefunx {char *} gdb_symtab_to_dirname (struct symtab *)
|
|
Return the location of the file corresponding to this symtab.
|
|
@code{gdb_symtab_to_dirname} might return @code{NULL} if no directory
|
|
is known. @code{gdb_symtab_to_line_count} might return -1 if line
|
|
number information is unavailable.
|
|
@end deftypefun
|
|
|
|
@deftypefun int gdb_symtab_to_line_count (struct symtab *)
|
|
(See also `Source')
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {struct symtab *} gdb_filename_to_symtab (char * @var{filename})
|
|
Lookup the symbol table of a source file named NAME.@*
|
|
(lookup_symtab)
|
|
@end deftypefun
|
|
|
|
|
|
@deftp Type {struct symtab_and_line}
|
|
@example
|
|
struct symtab_and_line
|
|
@{
|
|
struct symtab *symtab;
|
|
int line;
|
|
CORE_ADDR pc;
|
|
CORE_ADDR end;
|
|
@}
|
|
@end example
|
|
|
|
@code{struct symtab_and_line} is used to refer to a particular line
|
|
of source code. It is used to locate breakpoints in the source
|
|
code and the executable.
|
|
|
|
@code{line} starts at 1 and proceeds through symtab->nlines.
|
|
0 is never a valid line number; it is used to indicate
|
|
that line number information is not available.
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {struct symtab_and_line} gdb_find_pc_line (CORE_ADDR @var{pc}, int @var{notcurrent})
|
|
Find the source file and line number for a given @var{pc} value.
|
|
Return a structure containing a symtab pointer, a line number,
|
|
and a pc range for the entire source line.
|
|
The value's @code{.pc} field is NOT the specified @var{pc}.
|
|
@var{notcurrent} nonzero means, if specified pc is on a line boundary,
|
|
use the line that ends there. Otherwise, in that case, the line
|
|
that begins there is used.@*
|
|
(find_pc_line)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_find_line (struct symtab_and_line * @var{out}, struct symtab *, int)
|
|
Create a symtab_and_line for a given symtab and line number.
|
|
In other words, if you know the source file and line,
|
|
this returns a location for the breakpoint.@*
|
|
(resolve_sal_pc)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {struct symtabs_and_lines} gdb_decode_line (@var{argptr}, @var{firstln}, @var{default_symtab}, @var{default_line}, @var{canonical})
|
|
@example
|
|
char ** argptr;
|
|
int funfirstline;
|
|
struct symtab * default_symtab;
|
|
int default_line;
|
|
char *** canonical;
|
|
@end example
|
|
Parse a string that specifies a line number in GDB syntax.
|
|
@var{argptr} will be advanced over the characters actually parsed.
|
|
|
|
The string can be:
|
|
|
|
LINENUM -- that line number in current file. PC returned is 0.
|
|
FILE:LINENUM -- that line in that file. PC returned is 0.
|
|
FUNCTION -- line number of openbrace of that function.
|
|
PC returned is the start of the function.
|
|
VARIABLE -- line number of definition of that variable.
|
|
PC returned is 0.
|
|
FILE:FUNCTION -- likewise, but prefer functions in that file.
|
|
*EXPR -- line in which address EXPR appears.
|
|
|
|
FUNCTION may be an undebuggable function found in minimal symbol
|
|
table.
|
|
|
|
If the argument FUNFIRSTLINE is nonzero, we want the first line
|
|
of real code inside a function when a function is specified.
|
|
|
|
DEFAULT_SYMTAB specifies the file to use if none is specified.
|
|
It defaults to current_source_symtab.
|
|
|
|
DEFAULT_LINE specifies the line number to use for relative line
|
|
numbers (that start with signs). Defaults to current_source_line.
|
|
If CANONICAL is non-NULL, store an array of strings containing the
|
|
canonical line specs there if necessary. Currently overloaded
|
|
member functions and line numbers or static functions without a
|
|
filename yield a canonical line spec. The array and the line spec
|
|
strings are allocated on the heap, it is the callers responsibility
|
|
to free them.
|
|
|
|
Note that it is possible to return zero for the symtab
|
|
if no file is validly specified. Callers must check that.
|
|
Also, the line number returned may be invalid.
|
|
|
|
The return value of this function includes allocated memory
|
|
which the caller is responsible for freeing:
|
|
|
|
struct symtabs_and_lines sals;
|
|
sals = decode_line_spec (arg, 1);
|
|
....
|
|
free (sals.sals);@*
|
|
(decode_line_1)
|
|
@end deftypefun
|
|
|
|
|
|
@deftp Type {struct block *}
|
|
Lexical environments in the program are represented by struct block.
|
|
These are useful as arguements to expression parsing functions (see
|
|
`Expressions').
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {struct block *} gdb_block_for_pc (CORE_ADDR)
|
|
Return the innermost lexical block containing the
|
|
specified pc value, or 0 if there is none.@*
|
|
(block_for_pc)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {struct block *} gdb_get_frame_block (FRAME @var{frame})
|
|
This returns the block being executed by a given
|
|
stack frame (see `Stack')@*
|
|
(get_frame_block)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out})
|
|
@example
|
|
struct symtab * @var{start_out};
|
|
int @var{line};
|
|
CORE_ADDR * @var{start_out};
|
|
CORE_ADDR * @var{end_out};
|
|
@end example
|
|
Find the range of pc values in a line.@*
|
|
Store the starting pc of the line into @code{*@var{startptr}}.
|
|
and the ending pc (start of next line) into @code{*@var{endptr}}.
|
|
|
|
Returns 1 to indicate success.@*
|
|
Returns 0 if could not find the specified line.@*
|
|
(find_line_pc_range)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_find_pc_partial_function (@var{pc}, @var{name}, @var{address}, @var{endaddr})
|
|
@example
|
|
CORE_ADDR @var{pc};
|
|
char **@var{name};
|
|
CORE_ADDR *@var{address};
|
|
CORE_ADDR *@var{endaddr};
|
|
@end example
|
|
Finds the "function" (text symbol) that is smaller than @var{pc} but
|
|
greatest of all of the potential text symbols. Sets @code{*@var{name}}
|
|
and/or @code{*@var{address}} conditionally if that pointer is non-null. If
|
|
@var{endaddr} is non-null, then set @code{*@var{endaddr}} to be the end of
|
|
the function (exclusive), but passing @var{endaddr} as non-null means that
|
|
the function might cause symbols to be read. This function either succeeds
|
|
or fails (not halfway succeeds). If it succeeds, it sets
|
|
@code{*@var{name}}, @code{*@var{address}}, and @code{*@var{endaddr}} to
|
|
real information and returns 1. If it fails, it sets @code{*@var{name}},
|
|
@code{*@var{address}}, and @code{*@var{endaddr}} to zero and returns 0.
|
|
|
|
@example
|
|
pc = get_frame_pc (selected_frame);
|
|
if (find_pc_partial_function (pc, &name, &low, &high) == 0)
|
|
error ("No function contains program counter for selected frame.\n");
|
|
@end example
|
|
(find_pc_partial_function)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_list_symbols (@var{info_out}, @var{regexp}, @var{class}, @var{bpt})
|
|
@example
|
|
struct gdb_stream_cback * @var{info_out};
|
|
char * @var{regexp};
|
|
int @var{class};
|
|
int @var{bpt};
|
|
@end example
|
|
List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}.
|
|
|
|
|
|
If @var{class} is ...
|
|
@itemize @bullet
|
|
@item
|
|
0, list all symbols except functions, type names, and
|
|
constants (enums).
|
|
@item
|
|
1, list only functions.
|
|
@item
|
|
2, list only type names.
|
|
@item
|
|
3, list only method names.
|
|
@end itemize
|
|
BPT is non-zero if set a breakpoint at the functions we find.@*
|
|
(variables_info, functions_info, types_info, list_symbols)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_locals_info (struct gdb_stream_cback * @var{info_out}, FRAME @var{frame})
|
|
Print all the local variables in the given frame.
|
|
including all the blocks active in that frame
|
|
at its current pc.
|
|
|
|
Returns 1 if the job was done,
|
|
or 0 if nothing was printed because we have no info
|
|
on the function running in @var{frame}.@*
|
|
(locals_info)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int print_frame_arg_vars (struct gdb_stream_cback *, FRAME)
|
|
Similar to `gdb_locals_info'.@*
|
|
(args_info)
|
|
@end deftypefun
|
|
|
|
@node Source, Running, Symtabs, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Relating Inferiors to Source Files
|
|
@cindex source
|
|
@cindex {source files}
|
|
|
|
How to find the source that corresponds to executable code and the
|
|
executable code that corresponds to a line of source.
|
|
|
|
@deftypefun {char *} gdb_copy_source_fullname (struct symtab *@var{s})
|
|
Return a copy of the full path name to a source file.
|
|
(See `Symtabs' for more information about filenames
|
|
and symbol tables.).
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_open_source_file (struct symtab *@var{s})
|
|
Open a source file corresponding to @var{s}. Returns a file descriptor
|
|
or negative number for error.
|
|
[[[We may decide not to provide this function.]]]@*
|
|
(open_source_file)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_source_line_pos (struct symtab * @var{s}, int @var{lineno})
|
|
Return the byte offset of a given line of source
|
|
or a negative number if @var{lineno} is out of range.@*
|
|
(find_source_lines)
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: The gdb command `show directories'.
|
|
@example
|
|
puts_filtered ("Source directories searched: ");
|
|
puts_filtered (source_path);
|
|
puts_filtered ("\n");
|
|
@end example
|
|
(show_directories)
|
|
|
|
|
|
@deftypefun {char *} gdb_source_path ()
|
|
Return the path in which source files are sought.@*
|
|
(source_path)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_modify_source_path (char * @var{dirnames})
|
|
Change the source path according to dirnames.@*
|
|
(directory_command)
|
|
@end deftypefun
|
|
|
|
|
|
See `Symtabs' for functions relating symbol tables to files.
|
|
(source_info)
|
|
|
|
|
|
See `Symtabs' for functions relating source lines to PC values.
|
|
(line_info)
|
|
|
|
|
|
[[[Try to expose sources_info without having to introduce struct object *?]]]
|
|
(sources_info)
|
|
|
|
|
|
@node Running, Stopping, Source, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating, Continuing, and Stepping Through an Inferior Process
|
|
@cindex running
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_target_create_inferior (@var{exec}, @var{args}, @var{environ})
|
|
@example
|
|
char * @var{exec_file};
|
|
char * @var{inferior_args};
|
|
char ** @var{inferior_environment_vector};
|
|
@end example
|
|
Create a running inferior.
|
|
[[[I think the exec_file parameter is redundant. Perhaps this will take
|
|
only two arguments.]]]@*
|
|
(run_command, target_create_inferior)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_target_has_execution ()
|
|
Return non-0 if an inferior is running.@*
|
|
(target_has_execution)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_target_kill ()
|
|
Kill the inferior process. Make it go away.
|
|
The inferior may become a core file.
|
|
If so, gdb_target_has_stack() will return non-0.@*
|
|
(target_kill)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_step_1 (@var{skip_subs}, @var{single_inst}, @var{repeat_count})
|
|
@example
|
|
int skip_subs;
|
|
int single_inst;
|
|
int repeat_count;
|
|
@end example
|
|
Continue a program a little bit. Roughly:
|
|
@example
|
|
for (; count > 0; --count)
|
|
gdb_clear_proceed_status ();
|
|
gdb_proceed (...);
|
|
@end example
|
|
(next_command, nexti_command, step_command, stepi_command)
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: Continuing a program where it stopped.
|
|
@example
|
|
gdb_clear_proceed_status ();
|
|
gdb_proceed ((CORE_ADDR) -1, -1, 0);
|
|
@end example
|
|
(continue_command)
|
|
|
|
|
|
-- IDIOM: Continuing a program giving it a specified signal.
|
|
@example
|
|
gdb_clear_proceed_status ();
|
|
gdb_proceed ((CORE_ADDR) -1, signum, 0);
|
|
@end example
|
|
(signal_command)
|
|
|
|
|
|
@deftypefun {char *} strtosigno (char * @var{str})
|
|
(Typical use:)
|
|
@example
|
|
signum = strtosigno (signum_exp);
|
|
|
|
if (signum == 0)
|
|
/* Not found as a name, try it as an expression. */
|
|
signum = parse_and_eval_address (signum_exp);
|
|
|
|
gdb_clear_proceed_status ();
|
|
gdb_proceed ();
|
|
@end example
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: Continuing a program at a specified address.
|
|
@example
|
|
gdb_clear_proceed_status ();
|
|
gdb_proceed (addr, 0, 0);
|
|
@end example
|
|
(jump_command)
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_finish ()
|
|
"finish": Set a temporary breakpoint at the place
|
|
the selected frame will return to, then continue.
|
|
This is a convenience function but it summarizes a lot
|
|
of other stuff.@*
|
|
(finish_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_clear_proceed_status ()
|
|
Clear out all variables saying what to do when inferior is continued.
|
|
First do this, then set the ones you want, then call @code{gdb_proceed}.
|
|
|
|
[[[Some of these should be documented, others hidden.]]]
|
|
@example
|
|
The variables are:
|
|
trap_expected = 0;
|
|
step_range_start = 0;
|
|
step_range_end = 0;
|
|
step_frame_address = 0;
|
|
step_over_calls = -1;
|
|
stop_after_trap = 0;
|
|
stop_soon_quietly = 0;
|
|
proceed_to_finish = 0;
|
|
breakpoint_proceeded = 1; /* We're about to proceed... */
|
|
|
|
/* Discard any remaining commands or status from previous stop. */
|
|
bpstat_clear (&stop_bpstat);
|
|
@end example
|
|
(clear_proceed_status)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_proceed (CORE_ADDR @var{addr}, int @var{signal}, int @var{step})
|
|
Basic routine for continuing the program in various fashions.
|
|
|
|
@var{addr} is the address to resume at, or -1 for resume where stopped.@*
|
|
@var{signal} is the signal to give it, or 0 for none,
|
|
or -1 for act according to how it stopped.@*
|
|
@var{step} is nonzero if should trap after one instruction.
|
|
-1 means return after that and print nothing.@*
|
|
You should probably set various step_... variables
|
|
before calling here, if you are stepping.
|
|
|
|
You should call @code{gdb_clear_proceed_status} before calling proceed.
|
|
(See the documentation for @code{gdb_clear_proceed_status} for more
|
|
parameters to @code{gdb_proceed}).@*
|
|
(proceed)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_return (value @var{return_value}, FRAME @var{frame})
|
|
Make @var{frame} return to @var{value} to it's caller.
|
|
Unlike the other functions in this section, this doesn't
|
|
call proceed.
|
|
(return_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_inferior_pid ()
|
|
0 or the valid pid of an inferior.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_attach (int @var{pid})
|
|
takes a program started up outside of gdb and
|
|
`attaches'' to it. This stops it cold in its tracks and allows us
|
|
to start debugging it. and wait for the trace-trap that results
|
|
from attaching.@*
|
|
(attach_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_detach (int @var{signal_num})
|
|
Takes a program previously attached to and detaches it.
|
|
The program resumes execution and will no longer stop
|
|
on signals, etc. We better not have left any breakpoints
|
|
in the program or it'll die when it hits one. For this
|
|
to work, it may be necessary for the process to have been
|
|
previously attached. It *might* work if the program was
|
|
started via the normal ptrace (PTRACE_TRACEME).@*
|
|
(detach_command)
|
|
@end deftypefun
|
|
|
|
@node Stopping, Stack, Running, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Using Breakpoints, Signaling an Inferior
|
|
@cindex stopping
|
|
@cindex breakpoints
|
|
|
|
|
|
@deftp Type {struct breakpoint}
|
|
Breakpoints are typically represented @code{struct breakpoint *}.
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {struct breakpoint *} gdb_find_breakpoint (int)
|
|
Find a breakpoint given it's number (return 0 if it doesn't exist).
|
|
@end deftypefun
|
|
|
|
@deftypefun gdb_error_t gdb_set_break (struct breakpoint * @var{brk_out}, struct symtab_and_line)
|
|
@deftypefunx gdb_error_t gdb_set_tbreak (struct breakpoint *, struct symtab_and_line)
|
|
@deftypefunx gdb_error_t gdb_set_until (struct breakpoint *, struct symtab_and_line)
|
|
These three are like their command language counterparts.
|
|
They are front ends to `gdb_set_raw_breakpoint'.
|
|
See `Symtabs' for sources of `struct symtab_and_line'.@*
|
|
(break_command, break_command_1, until_command, tbreak_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_set_watchpt (@var{brk_out}, @var{exp_string}, @var{exp}, @var{exp_valid_block})
|
|
@example
|
|
struct breakpoint * @var{brk_out};
|
|
char * @var{exp_string};
|
|
struct expression * @var{exp};
|
|
struct block * @var{expression_valid_block};
|
|
@end example
|
|
Set a watchpoint for the given expression.@*
|
|
(watch_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_set_ignore_count (int @var{bptnum}, int @var{count})
|
|
Set ignore-count of breakpoint number BPTNUM to COUNT.@*
|
|
(set_ignore_count)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {struct gdb_bp_condition *} gdb_set_condition (@var{bp}, @var{exp_str}, @var{cond})
|
|
@example
|
|
int @var{pbtnum};
|
|
char * @var{exp_str};
|
|
struct gdb_bp_condition * @var{cond};
|
|
|
|
typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num);
|
|
struct gdb_bp_condition
|
|
{
|
|
gdb_bp_fn fn;
|
|
};
|
|
@end example
|
|
Add a condition to a breakpoint.
|
|
The condition is a callback which should return
|
|
0 to skip the breakpoint, and 1 to break at it.
|
|
It is called at times when the break might occur.
|
|
|
|
A useful application of these callbacks to attach
|
|
an expression to breakpoints like the gdb `condition'
|
|
command. See `Expressions' for the parsing and
|
|
evaluation of expressions.@*
|
|
(condition_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_enable_breakpoint (struct breakpoint * @var{bpt}, int @var{once})
|
|
@deftypefunx gdb_error_t gdb_disable_breakpoint (struct breakpoint * @var{bpt})
|
|
Enable/disable a breakpoint. If `once' is not 0, the
|
|
breakpoint is only temporarily enabled.@*
|
|
(enable_breakpoint, disable_breakpoint, enable_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_delete_breakpoint (struct breakpoint * @var{bpt})
|
|
Delete a breakpoint and clean up all traces of it in the
|
|
data structures.@*
|
|
(delete_breakpoint)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_clear_breakpoints (struct symtabs_and_lines * @var{sals})
|
|
Clear breakpoints from a list of program locations as
|
|
might be returned by `gdb_decode_line' (see `Symtabs').@*
|
|
(clear_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {static struct symtabs_and_lines} get_catch_sals (int @var{this_level_only})
|
|
Return the line numbers of all exception handlers currently
|
|
active (or `this_level_only'?? [[[?]]]).
|
|
[[[The implementation should remember to resolve_sal_pc]]]
|
|
@end deftypefun
|
|
|
|
|
|
@deftp Type {struct breakpoint_cback}
|
|
@example
|
|
typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num);
|
|
struct breakpoint_cback
|
|
{
|
|
breakpoint_cback_fn fn;
|
|
};
|
|
@end example
|
|
|
|
Breakpoints can have an associated function which is called
|
|
when the program is stopped by that breakpoint.@*
|
|
(commands_command)
|
|
@end deftp
|
|
|
|
|
|
@deftypefun {struct breakpoint_cback *} gdb_set_breakpoint_cback (int @var{bp_num}, struct breakpoint_cback *)
|
|
This sets a breakpoint callback and returns the previous callback value
|
|
for that breakpoint.
|
|
[[[In the long run, the command interpreter should be available
|
|
for the use of hooks like this one.]]]
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {struct breakpoint_cback *} gdb_get_breakpoint_cback (int @var{bp_num})
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_breakpoints_info (struct gdb_stream_cback, int @var{bp_num}, int @var{watches})
|
|
Print information on breakpoint number @var{bnum}, or -1 if all.
|
|
If @var{watches} is zero, process only breakpoints; if @var{watches}
|
|
is nonzero, process only watchpoints.
|
|
[[[In the long run, expose the information read off by this function.]]]@*
|
|
(info breakpoints, info watchpoints, breakpoints_info, breakpoint_1)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_catch_info (struct gdb_stream_cback *)
|
|
Print a list of all the exception handlers that are active in the
|
|
current stack frame at the current point of execution.@*
|
|
(catch_info)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_handle_command (char * @var{args})
|
|
Takes arguments like the gdb command `handle' and has
|
|
the same effect.@*
|
|
(handle_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_signals_info (struct gdb_stream_cback *)
|
|
Show how signals are handled.@*
|
|
(signals_info)
|
|
@end deftypefun
|
|
|
|
|
|
@node Stack, Expressions, Stopping, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Accessing An Inferior's Execution Stack
|
|
@cindex stack
|
|
@cindex FRAME
|
|
@cindex {stack frames}
|
|
|
|
|
|
|
|
@deftp Type FRAME
|
|
This type representing active stack frames in the inferior.
|
|
Consider this type opaque.
|
|
@end deftp
|
|
|
|
|
|
@deftypefun FRAME gdb_get_innermost_frame ()
|
|
Returns the innermost frame or the frame most recently designated
|
|
as current by a call to gdb_set_current_frame.@*
|
|
(get_current_frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_get_caller_frame (FRAME @var{frame})
|
|
Return the frame that called @var{frame}.@*
|
|
If @var{frame} is the original frame (it has no caller), return 0.@*
|
|
(get_prev_frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_get_called_frame (FRAME @var{frame})
|
|
Return the frame that @var{frame} calls (0 if @var{frame} is the innermost
|
|
frame).@*
|
|
(get_next_frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_parse_frame_specification (char * @var{frame_exp})
|
|
Read a frame specification in whatever the appropriate format is.
|
|
Call @code{error}() If the specification is in any way invalid (i.e.
|
|
this function never returns NULL).@*
|
|
(parse_frame_specification)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@*
|
|
(Example use: Implementing @code{disassemble_command})@*
|
|
(get_frame_pc)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_selected_frame ()
|
|
The "selected" stack frame is used by default for local and
|
|
arg access. May be @code{NULL}, for no selected frame.@*
|
|
(variable selected_frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_selected_frame_level ()
|
|
Level of the selected frame:@*
|
|
0 for innermost,@*
|
|
1 for its caller,@*
|
|
or -1 for frame specified by address with no defined level.@*
|
|
(variable selected_frame_level)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_select_frame (FRAME @var{frame}, int @var{level})
|
|
Select frame @var{frame}, and note that its stack level is @var{level}.
|
|
@var{level} may be -1 if an actual level number is not known.
|
|
Calls @code{set_language} to establish the correct language for the
|
|
selected frame.
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: Computing Frame Levels@*
|
|
@example
|
|
/* Try to figure out what level this frame is as before a
|
|
call to gdb_select_frame. But if there is
|
|
no current stack, don't error out, just pass -1
|
|
instead. */
|
|
frame1 = 0;
|
|
level = -1;
|
|
if (get_current_frame()) {
|
|
for (frame1 = get_prev_frame (0);
|
|
frame1 && frame1 != frame;
|
|
frame1 = get_prev_frame (frame1))
|
|
level++;
|
|
}
|
|
@end example
|
|
|
|
|
|
@deftypefun void gdb_print_stack_frame (@var{cback}, @var{frame}, @var{level}, @var{source})
|
|
@example
|
|
struct gdb_stream_cback * @var{cback};
|
|
FRAME @var{frame};
|
|
int @var{level};
|
|
int @var{source};
|
|
@end example
|
|
Print a stack frame briefly. @var{frame} should be the frame id
|
|
and @var{level} should be its level in the stack (or -1 for level not defined).
|
|
This prints the level, the function executing, the arguments,
|
|
and the file name and line number.@*
|
|
If the pc is not at the beginning of the source line,
|
|
the actual pc is printed at the beginning.@*
|
|
If @var{source} is 1, print the source line as well.@*
|
|
If @var{source} is -1, print ONLY the source line.@*
|
|
(print_stack_frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_print_backtrace (cback, @var{count}, @var{from_tty})
|
|
@example
|
|
struct gdb_stream_cback * @var{cback};
|
|
int @var{count};
|
|
int @var{from_tty};
|
|
@end example
|
|
Print briefly all stack frames or just the innermost @var{count} frames.@*
|
|
(backtrace_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_find_relative_frame (FRAME @var{frame}, int * @var{level_offset_ptr})
|
|
Find a frame a certain number of levels away from @var{frame}.
|
|
@var{level_offset_ptr} points to an int containing the number of levels.
|
|
Positive means go to earlier frames (up); negative, the reverse.
|
|
The int that contains the number of levels is counted toward
|
|
zero as the frames for those levels are found.
|
|
If the top or bottom frame is reached, that frame is returned,
|
|
but the final value of @var{*level_offset_ptr} is nonzero and indicates
|
|
how much farther the original request asked to go.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun FRAME gdb_select_frame_downward (int @var{count})
|
|
@deftypefunx FRAME gdb_select_frame_upward (int @var{count})
|
|
Simply a combination of find_relative_frame and select_frame.
|
|
Returns the newly selected frame.@*
|
|
(down_silently_command, up_silently_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_frame_info (struct gdb_stream_cback * @var{cback}, FRAME @var{frame})
|
|
Print verbosely the selected the argument @var{frame}.
|
|
This means absolutely all information in the frame is printed.@*
|
|
(frame_info)
|
|
@end deftypefun
|
|
|
|
|
|
@node Expressions, Values, Stack, top
|
|
@comment node-name, next, previous, up
|
|
@chapter How to Parse and Evaluate Expressions
|
|
@cindex parsing
|
|
@cindex expressions
|
|
@cindex {expression evaluation}
|
|
@cindex evaluation
|
|
|
|
|
|
@deftp Type {struct expression *}
|
|
This represents a parsed expression as might be used for a
|
|
breakpoint condition.
|
|
@end deftp
|
|
|
|
|
|
@deftp Type {struct block}
|
|
Describes a lexical environment.
|
|
@end deftp
|
|
|
|
See also `Values'
|
|
See also `Examining'
|
|
|
|
|
|
@deftypefun struct expression * parse_exp_1 (char ** @var{stringptr}, struct block * @var{block} int @var{comma})
|
|
Read an expression from the string @code{*@var{stringptr}} points to,
|
|
parse it, and return a pointer to a struct expression that we malloc.
|
|
Use @var{block} as the lexical context for variable names;
|
|
if @var{block} is zero, use the block of the selected stack frame.
|
|
Meanwhile, advance @code{*@var{stringptr}} to point after the expression,
|
|
at the first nonwhite character that is not part of the expression
|
|
(possibly a null character).
|
|
|
|
If @var{comma} is nonzero, stop if a comma is reached.
|
|
(See `Stack' for information about the selected frame)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun gdb_error_t gdb_evaluate_expression (value * @var{value_out}, struct expression * @var{exp})
|
|
Evaluate an expression. See `values' for more information about
|
|
the return type.@*
|
|
(evaluate_expression)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun value gdb_evaluate_type (struct expression @var{*exp})
|
|
Evaluate an expression, avoiding all memory references
|
|
and getting a value whose type alone is correct.@*
|
|
(evaluate_type)
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@node Values, Examining, Expressions, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Data from the Inferior, the Values of Expressions
|
|
@cindex values
|
|
@cindex {expression values}
|
|
|
|
Values are allocated by functions such as @code{gdb_evaluate_expression}.
|
|
All currently allocated values are on the list @code{all_values} and can be
|
|
freed by calling @code{gdb_free_all_values}.
|
|
|
|
To preserve a value across calls to @code{gdb_free_all_values}, use
|
|
@code{gdb_release_value}. Values added to the history list are automaticly
|
|
released. To free a released value use @code{gdb_free_value}.
|
|
|
|
|
|
@deftypefun void gdb_free_value (value)
|
|
Free the memory associated with a released value.
|
|
Do not call this function except on values that have been
|
|
passed to @code{gdb_release_value}.@*
|
|
(gdb_value_free)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_free_all_values (void)
|
|
Free all allocated values which haven't been released.
|
|
This should be called periodically from outside the dynamic
|
|
scope of libgdb functions.@*
|
|
(free_all_values)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_release_value (value @var{val})
|
|
Remove a value from the list @code{all_values} in order to
|
|
protect it from @code{gdb_free_all_values}.@*
|
|
(release_value)
|
|
@end deftypefun
|
|
|
|
|
|
There is a `history list' -- a numbered list of values for
|
|
future reference. These can be referred to in expressions,
|
|
for example.
|
|
|
|
@deftypefun int gdb_record_latest_value (value @var{val})
|
|
Add a value to the history list.@*
|
|
(record_latest_value)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun value gdb_access_value_history (int @var{index})
|
|
Retrieve a value from the history list.@*
|
|
(access_value_history)
|
|
@end deftypefun
|
|
|
|
|
|
[[[At the moment, the only libgdb use for values is
|
|
string formatting (see `Examining'). So, they are treated
|
|
as opaque. It'd be useful to expose more of them in the long run.]]]
|
|
|
|
|
|
@node Examining, Types, Values, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Formatting Values as Strings
|
|
@cindex examining
|
|
@cindex printing
|
|
@cindex formatting
|
|
@cindex {pretty printing}
|
|
|
|
|
|
Many functions in this section use @code{struct gdb_stream_cback}.
|
|
That structure is explained in `Basics'.
|
|
|
|
|
|
@deftypefun void gdb_print_formatted (struct gdb_stream_cback * @var{cback}, value @var{val}, int @var{format}, int @var{size})
|
|
Print value @var{val} on a stream according to @var{format}, a letter or 0.
|
|
Do not end with a newline.
|
|
0 means print @var{val} according to its own type.
|
|
@var{size} is the letter for the size of datum being printed.
|
|
This is used to pad hex numbers so they line up.@*
|
|
(print_formatted)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun static void gdb_printf_command (struct gdb_stream_cback * @var{cback}, char * @var{format}, value * @var{values}, int @var{n_values})@*
|
|
(printf_command)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_value_print (struct gdb_stream_cback * @var{cback}, @var{value}, int @var{format}, enum @var{val_prettyprint})
|
|
Print the value @var{val} in C-ish syntax on @var{stream}.
|
|
@var{format} is a format-letter, or 0 for print in natural format of data type.
|
|
If the object printed is a string pointer, returns
|
|
the number of string bytes printed.
|
|
[[[implementation: watch the change in argument order]]]@*
|
|
(value_print)
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: This prints the values of all convenience variables:
|
|
@example
|
|
for (var = internalvars; var; var = var->next)
|
|
{
|
|
printf_filtered ("$%s = ", var->name);
|
|
value_print (var->value, stdout, 0, Val_pretty_default);
|
|
printf_filtered ("\n");
|
|
}
|
|
@end example
|
|
|
|
|
|
@deftypefun int gdb_print_insn (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{memaddr})
|
|
Print the instruction at @var{memaddr} and return the
|
|
length of the instruction in bytes.@*
|
|
(print_insn)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_print_address (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{addr})
|
|
Print address @var{addr} symbolically on @var{stream}.
|
|
First print it as a number. Then perhaps print
|
|
@code{<SYMBOL + OFFSET>} after the number.@*
|
|
(print_address)
|
|
@end deftypefun
|
|
|
|
|
|
-- IDIOM: This is the core of a dissasemble command:
|
|
@example
|
|
for (pc = low; pc < high; )
|
|
{
|
|
print_address (pc, stdout);
|
|
printf_filtered (":\t");
|
|
pc += print_insn (pc, stdout);
|
|
printf_filtered ("\n");
|
|
}
|
|
@end example
|
|
Advice for computing pc extents like @code{low} and @code{high}
|
|
can be found in `Symtabs' -- for example, @code{gdb_find_line_pc_range}.@*
|
|
(disassemble_command)
|
|
|
|
|
|
@deftypefun void gdb_print_registers (struct gdb_stream_cback * @var{cback}, int @var{regnum}, int @var{fpregs}, int @var{fancy})
|
|
Print the values of registers.
|
|
@var{regnum} can be -1 (print all the registers) or a specific register number.
|
|
If @var{regnum} is -1, @var{fpregs} determines whether floating point registers are
|
|
shown.@*
|
|
(info registers, info all-registers, nofp_registers_info, all_registers_info)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun char * gdb_register_name (int @var{i})
|
|
Look up a register name by number.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_parse_register_name (char ** @var{name})
|
|
Parse a register name and advance a text pointer.
|
|
Return -1 for bogus names.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun CORE_ADDR gdb_read_pc ()
|
|
Return the contents of the inferior's program counter.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_is_stepping ()
|
|
If true, the inferior is stopped after being stepped.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_current_breakpoints (gdb_int_cback)
|
|
Call a callback for each of the current breakpoints.@*
|
|
(program_info)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int gdb_stop_signal ()
|
|
Return the signal that stopped the inferior.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun char * strsigno (int)
|
|
Return a symbolic name for a signal.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_target_info (struct gdb_stream_cback *)
|
|
Print status information about target we're accessing.@*
|
|
(target_files_info, e.g. child_files_info)
|
|
@end deftypefun
|
|
|
|
|
|
float_info
|
|
[[[what is appropriate?]]]
|
|
|
|
|
|
@deftypefun void gdb_address_info (struct gdb_stream_cback * @var{cback}, char * @var{symbol});
|
|
Like the `info address' command -- show where @var{symbol}
|
|
is located.@*
|
|
(address_info)
|
|
@end deftypefun
|
|
|
|
|
|
@node Types, top, Examining, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Examining the Types of an Inferior's Data
|
|
@cindex types
|
|
|
|
|
|
@deftp Type {struct type}
|
|
@code{struct type *} is used to represent a type. For example, that is
|
|
the type returned by the macro @code{VALUE_TYPE(val)} which yields the
|
|
type of inferior data recorded in @code{val}. (see `evaluate_type' in
|
|
`Expressions').
|
|
@end deftp
|
|
|
|
|
|
@deftypefun void type_print (@var{type}, @var{varstring}, @var{stream_cback}, @var{show})
|
|
@example
|
|
struct type @var{*type};
|
|
char @var{*varstring};
|
|
struct gdb_stream_cback * @var{stream_cback};
|
|
FILE @var{*stream};
|
|
int @var{show};
|
|
@end example
|
|
Print a description of a type @var{type} in the form of a declaration of a
|
|
variable named @var{varstring}. (@var{varstring} is demangled if necessary.)
|
|
Output goes to @var{stream_cback}.
|
|
|
|
If @var{show} is positive, we show the contents of the outermost level
|
|
of structure even if there is a type name that could be used instead.
|
|
If @var{show} is negative, we never show the details of elements' types.
|
|
(See `Basics' for an explanation of `struct gdb_stream_cback').
|
|
@end deftypefun
|
|
|
|
|
|
[[[In the long run, we need something to programmaticly read off type
|
|
structures in a machine/language independent way.]]]
|
|
|