878 lines
30 KiB
Text
878 lines
30 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename libgdb.info
|
|
@settitle Libgdb
|
|
@setchapternewpage off
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
This file documents libgdb, the GNU symbolic debugger in a library.
|
|
|
|
This is Edition 0.3, Oct 1993, of @cite{Libgdb}.
|
|
Copyright 1993 Cygnus Support
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
@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.3
|
|
@subtitle Oct 1993
|
|
@author Thomas Lord
|
|
|
|
@c The following two commands
|
|
@c start the copyright page.
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Copyright @copyright{} 1993 Cygnus Support
|
|
@end titlepage
|
|
|
|
@ifinfo
|
|
@node Top, Overview, (dir), (dir)
|
|
|
|
This info file documents libgdb: an API for GDB, the GNU symbolic debugger.
|
|
|
|
@menu
|
|
* Overview:: The basics of libgdb and this document.
|
|
* Interpreter:: Libgdb is an Interpreter-Based Server.
|
|
* Top Level:: You Provide the Top Level for the Libgdb
|
|
Command Interpreter .
|
|
* I/O:: How the Server's I/O Can be Used.
|
|
* Invoking:: Invoking the Interpreter, Executing
|
|
Commands.
|
|
* Defining Commands:: How New Commands are Created.
|
|
* Variables:: How Builtin Variables are Defined.
|
|
* Asynchronous:: Scheduling Asynchronous Computations.
|
|
* Commands:: Debugger Commands for Libgdb Applications
|
|
@end menu
|
|
|
|
@end ifinfo
|
|
@node Overview, Interpreter, top, top
|
|
@comment node-name, next, previous, up
|
|
@chapter Overview
|
|
@cindex overview
|
|
@cindex definitions
|
|
|
|
@heading Function and Purpose
|
|
|
|
Libgdb is a package which provides an API to the functionality of GDB,
|
|
the GNU symbolic debugger. It is specifically intended to support the
|
|
development of a symbolic debugger with a graphic interface.
|
|
|
|
|
|
@heading This Document
|
|
|
|
This document is a specification of the libgdb API. It is written in
|
|
the form of a programmer's manual. So the goal of this document is to
|
|
explain what functions make up the API, and how they can be used in a
|
|
running application.
|
|
|
|
|
|
@heading Terminology
|
|
|
|
In this document, @dfn{libgdb} refers to a library containing the
|
|
functions defined herein, @dfn{application} refers to any program built
|
|
with that library.
|
|
|
|
|
|
@heading Dependencies
|
|
|
|
Programs which are linked with libgdb must be linked with libbfd,
|
|
libopcodes, libiberty, and libmmalloc.
|
|
|
|
@heading Acknowledgments
|
|
|
|
Essential contributions to this design were made by Stu Grossman, Jim
|
|
Kingdon, and Rich Pixley.
|
|
|
|
@node Interpreter, Top Level, Overview, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Libgdb is an Interpreter Based Server
|
|
@cindex interpreter
|
|
@cindex server
|
|
|
|
To understand libgdb, it is necessary to understand how the library is
|
|
structured. Historically, GDB is written as a small interpreter for a
|
|
simple command language. The commands of the language perform useful
|
|
debugging functions.
|
|
|
|
Libgdb is built from GDB by turning the interpreter into a debugging
|
|
server. The server reads debugging commands from any source and
|
|
interprets them, directing the output arbitrarily.
|
|
|
|
In addition to changing GDB from a tty-based program to a server, a
|
|
number of new GDB commands have been added to make the server more
|
|
useful for a program with a graphic interface.
|
|
|
|
Finally, libgdb includes provisions for asynchronous processing within
|
|
the application.
|
|
|
|
Most operations that can be carried out with libgdb involve the GDB
|
|
command interpreter. The usual mode of operation is that the operation
|
|
is expressed as a string of GDB commands, which the interpreter is then
|
|
invoked to carry out. The output from commands executed in this manner
|
|
can be redirected in a variety of useful ways for further processing by
|
|
the application.
|
|
|
|
The command interpreter provides an extensive system of hooks so an
|
|
application can monitor any aspect of the debugging library's state. An
|
|
application can set its own breakpoints and attach commands and
|
|
conditions to those. It is possible to attach hooks to any debugger
|
|
command; the hooks are invoked whenever that command is about to be
|
|
invoked. By means of these, the displays of a graphical interface can
|
|
be kept fully up to date at all times.
|
|
|
|
We show you how to define new primitives in the command language. By
|
|
defining new primitives and using them in breakpoint scripts and command
|
|
hooks, an application can schedule the execution of arbitrary C-code at
|
|
almost any point of interest in the operation of libgdb.
|
|
|
|
We show you how to define new GDB convenience variables for which your
|
|
code computes a value on demand. Referring to such variables in a
|
|
breakpoint condition is a convenient way to conditionalize breakpoints
|
|
in novel ways.
|
|
|
|
To summarize: in libgdb, the gdb command language is turned into a
|
|
debugging server. The server takes commands as input, and the server's
|
|
output is redirectable. An application uses libgdb by formatting
|
|
debugging commands and invoking the interpreter. The application might
|
|
maintain breakpoints, watchpoints and many kinds of hooks. An application
|
|
can define new primitives for the interpreter.
|
|
|
|
@node Top Level, I/O, Interpreter, Top
|
|
@chapter You Provide the Top Level for the Libgdb Command Interpreter
|
|
@cindex {top level}
|
|
|
|
When you use libgdb, your code is providing a @dfn{top level} for the
|
|
command language interpreter. The top level is significant because it
|
|
provides commands for the the interpreter to execute. In addition, the
|
|
top level is responsible for handling some kinds of errors, and
|
|
performing certain cleanup operations on behalf of the interpreter.
|
|
|
|
@heading Initialization
|
|
|
|
Before calling any other libgdb functions, call this:
|
|
|
|
@deftypefun void gdb_init (void)
|
|
Perform one-time initialization for libgdb.
|
|
@end deftypefun
|
|
|
|
An application may wish to evaluate specific gdb commands as part of its
|
|
own initialization. The details of how this can be accomplished are
|
|
explained below.
|
|
|
|
@heading The Top-Level Loop
|
|
|
|
There is a strong presumption in libgdb that the application has
|
|
the form of a loop. Here is what such a loop might look like:
|
|
|
|
@example
|
|
while (gdb_still_going ())
|
|
@{
|
|
if (!GDB_TOP_LEVEL ())
|
|
@{
|
|
char * command;
|
|
gdb_start_top_loop ();
|
|
command = process_events ();
|
|
gdb_execute_command (command);
|
|
gdb_finish_top_loop ();
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
The function @code{gdb_still_going} returns 1 until the gdb command
|
|
`quit' is run.
|
|
|
|
The macro @code{GDB_TOP_LEVEL} invokes setjmp to set the top level error
|
|
handler. When a command results in an error, the interpreter exits with
|
|
a longjmp. There is nothing special libgdb requires of the top level
|
|
error handler other than it be present and that it restart the top level
|
|
loop. Errors are explained in detail in a later chapter.
|
|
|
|
Each time through the top level loop two important things happen: a
|
|
debugger command is constructed on the basis of user input, and the
|
|
interpreter is invoked to execute that command. In the sample code, the
|
|
call to the imaginary function @code{process_events} represents the
|
|
point at which a graphical interface should read input events until
|
|
ready to execute a debugger command. The call to
|
|
@code{gdb_execute_command} invokes the command interpreter (what happens
|
|
to the output from the command will be explained later).
|
|
|
|
Libgdb manages some resources using the top-level loop. The primary
|
|
reason for this is error-handling: even if a command terminates with an
|
|
error, it may already have allocated resources which need to be freed.
|
|
The freeing of such resources takes place at the top-level, regardless
|
|
of how the the command exits. The calls to @code{gdb_start_top_loop}
|
|
and @code{gdb_finish_top_loop} let libgdb know when it is safe to
|
|
perform operations associated with these resources.
|
|
|
|
@heading Breakpoint Commands
|
|
|
|
Breakpoint commands are scripts of GDB operations associated with
|
|
particular breakpoints. When a breakpoint is reached, its associated
|
|
commands are executed.
|
|
|
|
Breakpoint commands are invoked by the libgdb function
|
|
@code{gdb_finish_top_loop}.
|
|
|
|
Notice that if control returns to the top-level error handler, the
|
|
execution of breakpoint commands is bypassed. This can happen as a
|
|
result of errors during either @code{gdb_execute_command} or
|
|
@code{gdb_finish_top_loop}.
|
|
|
|
@heading Application Initialization
|
|
|
|
Sometimes it is inconvenient to execute commands via a command loop for
|
|
example, the commands an application uses to initialize itself. An
|
|
alternative to @code{execute_command} is @code{execute_catching_errors}.
|
|
When @code{execute_catching_errors} is used, no top level error handler
|
|
need be in effect, and it is not necessary to call
|
|
@code{gdb_start_top_loop} or @code{gdb_finish_top_loop}.
|
|
|
|
|
|
@heading Cleanup
|
|
|
|
The debugger command ``quit'' performs all necessary cleanup for libgdb.
|
|
After it has done so, it changes the return value of
|
|
@code{gdb_still_going} to 0 and returns to the top level error handler.
|
|
|
|
|
|
@node I/O, Invoking, Top Level, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter How the Server's I/O Can be Used
|
|
@cindex I/O
|
|
|
|
In the last chapter it was pointed out that a libgdb application is
|
|
responsible for providing commands for the interpreter to execute.
|
|
However some commands require further input (for example, the ``quit''
|
|
command might ask for confirmation). Almost all commands produce output
|
|
of some kind. The purpose of this section is to explain how libgdb
|
|
performs its I/O, and how an application can take advantage of
|
|
this.
|
|
|
|
|
|
@heading I/O Vectors
|
|
|
|
Libgdb has no fixed strategy for I/O. Instead, all operations are
|
|
performed by functions called via structures of function pointers.
|
|
Applications supply theses structures and can change them at any
|
|
time.
|
|
|
|
@deftp Type {struct gdb_input_vector}
|
|
@deftpx Type {struct gdb_output_vector}
|
|
These structures contain a set of function pointers. Each function
|
|
determines how a particular type of i/o is performed. The details of
|
|
these strucutres are explained below.
|
|
|
|
The application allocates these structures, initializes them to all bits
|
|
zero, fills in the function pointers, and then registers names for them
|
|
them with libgdb.
|
|
@end deftp
|
|
|
|
@deftypefun void gdb_name_input_vector (@var{name}, @var{vec})
|
|
@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
|
|
@deftypefunx void gdb_name_output_vector (@var{name}, @var{vec})
|
|
@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
|
|
@example
|
|
char * @var{name};
|
|
struct gdb_output_vector * @var{vec};
|
|
@end example
|
|
These functions are used to give and remove names to i/o vectors. Note
|
|
that if a name is used twice, the most recent definition applies.
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@subheading Output
|
|
|
|
An output vector is a structure with at least these fields:
|
|
|
|
@example
|
|
struct gdb_output_vector
|
|
@{
|
|
/* output */
|
|
void (*put_string) (struct gdb_output_vector *, char * str);
|
|
@}
|
|
@end example
|
|
|
|
Use the function @code{memset} or something equivalent to initialize an
|
|
output vector to all bits zero. Then fill in the function pointer with
|
|
your function.
|
|
|
|
A debugger command can produce three kinds of output: error messages
|
|
(such as when trying to delete a non-existent breakpoint), informational
|
|
messages (such as the notification printed when a breakpoint is hit),
|
|
and the output specifically requested by a command (for example, the
|
|
value printed by the ``print'' command). At any given time, then,
|
|
libgdb has three output vectors. These are called the @dfn{error},
|
|
@dfn{info}, @dfn{value} vector respectively.
|
|
|
|
@subheading Input
|
|
|
|
@example
|
|
struct gdb_input_vector
|
|
@{
|
|
int (*query) (struct gdb_input_vector *,
|
|
char * prompt,
|
|
int quit_allowed);
|
|
int * (*selection) (struct gdb_input_vector *,
|
|
char * prompt,
|
|
char ** choices);
|
|
char * (*read_string) (struct gdb_input_vector *,
|
|
char * prompt);
|
|
char ** (*read_strings) (struct gdb_input_vector *,
|
|
char * prompt);
|
|
@}
|
|
@end example
|
|
|
|
Use the function @code{memset} or something equivalent to initialize an
|
|
input vector to all bits zero. Then fill in the function pointers with
|
|
your functions.
|
|
|
|
There are four kinds of input requests explicitly made by libgdb.
|
|
|
|
A @dfn{query} is a yes or no question. The user can respond to a query
|
|
with an affirmative or negative answer, or by telling gdb to abort the
|
|
command (in some cases an abort is not permitted). Query should return
|
|
'y' or 'n' or 0 to abort.
|
|
|
|
A @dfn{selection} is a list of options from which the user selects a subset.
|
|
Selections should return a NULL terminated array of integers, which are
|
|
indexes into the array of choices. It can return NULL instead to abort
|
|
the command. The array returned by this function will be passed to
|
|
@code{free} by libgdb.
|
|
|
|
A @dfn{read_string} asks the user to supply an arbitrary string. It may
|
|
return NULL to abort the command. The string returned by @code{read_string}
|
|
should be allocated by @code{malloc}; it will be freed by libgdb.
|
|
|
|
A @dfn{read_strings} asks the user to supply multiple lines of input
|
|
(for example, the body of a command created using `define'). It, too,
|
|
may return NULL to abort. The array and the strings returned by this
|
|
function will be freed by libgdb.
|
|
|
|
@heading I/O Redirection from the Application Top-Level
|
|
|
|
@deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *)
|
|
@example
|
|
|
|
struct gdb_io_vecs
|
|
@{
|
|
struct gdb_input_vector * input;
|
|
struct gdb_output_vector * error;
|
|
struct gdb_output_vector * info;
|
|
struct gdb_output_vector * value;
|
|
@}
|
|
@end example
|
|
|
|
This establishes a new set of i/o vectors, and returns the old setting.
|
|
Any of the pointers in this structure may be NULL, indicating that the
|
|
current value should be used.
|
|
|
|
This function is useful for setting up i/o vectors before any libgdb
|
|
commands have been invoked (hence before any input or output has taken
|
|
place).
|
|
@end deftypefun
|
|
|
|
It is explained in a later chapter how to redirect output temporarily.
|
|
(@xref{Invoking}.)
|
|
|
|
@heading I/O Redirection in Debugger Commands
|
|
|
|
A libgdb application creates input and output vectors and assigns them names.
|
|
Which input and output vectors are used by libgdb is established by
|
|
executing these debugger commands:
|
|
|
|
@defun {set input-vector} name
|
|
@defunx {set error-output-vector} name
|
|
@defunx {set info-output-vector} name
|
|
@defunx {set value-output-vector} name
|
|
Choose an I/O vector by name.
|
|
@end defun
|
|
|
|
|
|
A few debugger commands are for use only within commands defined using
|
|
the debugger command `define' (they have no effect at other times).
|
|
These commands exist so that an application can maintain hooks which
|
|
redirect output without affecting the global I/O vectors.
|
|
|
|
@defun with-input-vector name
|
|
@defunx with-error-output-vector name
|
|
@defunx with-info-output-vector name
|
|
@defunx with-value-output-vector name
|
|
Set an I/O vector, but only temporarily. The setting has effect only
|
|
within the command definition in which it occurs.
|
|
@end defun
|
|
|
|
|
|
@heading Initial Conditions
|
|
|
|
When libgdb is initialized, a set of default I/O vectors is put in
|
|
place. The default vectors are called @code{default-input-vector},
|
|
@code{default-output-vector}, &c.
|
|
|
|
The default query function always returns `y'. Other input functions
|
|
always abort. The default output functions do nothing.
|
|
|
|
|
|
@node Invoking, Defining Commands, I/O, Top
|
|
@chapter Invoking the Interpreter, Executing Commands
|
|
@cindex {executing commands}
|
|
@cindex {invoking the interpreter}
|
|
|
|
This section introduces the libgdb functions which invoke the command
|
|
interpreter.
|
|
|
|
@deftypefun void gdb_execute_command (@var{command})
|
|
@example
|
|
char * @var{command};
|
|
@end example
|
|
Interpret the argument debugger command. An error handler must be set
|
|
when this function is called. (@xref{Top Level}.)
|
|
@end deftypefun
|
|
|
|
It is possible to override the current I/O vectors for the duration of a
|
|
single command:
|
|
|
|
@deftypefun void gdb_execute_with_io (@var{command}, @var{vecs})
|
|
@example
|
|
char * @var{command};
|
|
struct gdb_io_vecs * @var{vecs};
|
|
|
|
struct gdb_io_vecs
|
|
@{
|
|
struct gdb_input_vector * input;
|
|
struct gdb_output_vector * error;
|
|
struct gdb_output_vector * info;
|
|
struct gdb_output_vector * value;
|
|
@}
|
|
@end example
|
|
|
|
Execute @var{command}, temporarily using the i/o vectors in @var{vecs}.
|
|
|
|
Any of the vectors may be NULL, indicating that the current value should
|
|
be used. An error handler must be in place when this function is used.
|
|
@end deftypefun
|
|
|
|
@deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd})
|
|
@example
|
|
char * cmd;
|
|
@end example
|
|
@deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input})
|
|
@example
|
|
char * cmd;
|
|
struct gdb_input_vector * input;
|
|
@end example
|
|
@page
|
|
@example
|
|
struct gdb_str_output
|
|
@{
|
|
char * error;
|
|
char * info;
|
|
char * value;
|
|
@};
|
|
@end example
|
|
|
|
Execute @var{cmd}, collecting its output as strings. If no error
|
|
occurs, all three strings will be present in the structure, the
|
|
empty-string rather than NULL standing for no output of a particular
|
|
kind.
|
|
|
|
If the command aborts with an error, then the @code{value} field will be
|
|
NULL, though the other two strings will be present.
|
|
|
|
In all cases, the strings returned are allocated by malloc and should be
|
|
freed by the caller.
|
|
|
|
The first form listed uses the current input vector, but overrides the
|
|
current output vector. The second form additionally allows the input
|
|
vector to be overridden.
|
|
|
|
This function does not require that an error handler be installed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void execute_catching_errors (@var{command})
|
|
@example
|
|
char * @var{command};
|
|
@end example
|
|
Like @code{execute_command} except that no error handler is required.
|
|
@end deftypefun
|
|
|
|
@deftypefun void execute_with_text (@var{command}, @var{text})
|
|
@example
|
|
char * @var{command};
|
|
char ** @var{text};
|
|
@end example
|
|
Like @code{execute_catching_errors}, except that the input vector is
|
|
overridden. The new input vector handles only calls to @code{query} (by
|
|
returning 'y') and calls to @code{read_strings} by returning a copy of
|
|
@var{text} and the strings it points to.
|
|
|
|
This form of execute_command is useful for commands like @code{define},
|
|
@code{document}, and @code{commands}.
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@node Defining Commands, Variables, Invoking, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter How New Commands are Created
|
|
@cindex {commands, defining}
|
|
|
|
Applications are, of course, free to take advantage of the existing GDB
|
|
macro definition capability (the @code{define} and @code{document}
|
|
functions).
|
|
|
|
In addition, an application can add new primitives to the GDB command
|
|
language.
|
|
|
|
@deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc})
|
|
@example
|
|
char * @var{name};
|
|
gdb_cmd_fn @var{fn};
|
|
char * @var{doc};
|
|
|
|
typedef void (*gdb_cmd_fn) (char * args);
|
|
@end example
|
|
|
|
Create a new command call @var{name}. The new command is in the
|
|
@code{application} help class. When invoked, the command-line arguments
|
|
to the command are passed as a single string.
|
|
|
|
Calling this function twice with the same name replaces an earlier
|
|
definition, but application commands can not replace builtin commands of
|
|
the same name.
|
|
|
|
The documentation string of the command is set to a copy the string
|
|
@var{doc}.
|
|
@end deftypefun
|
|
|
|
@node Variables, Asynchronous, Defining Commands, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter How Builtin Variables are Defined
|
|
@cindex {variables, defining}
|
|
|
|
Convenience variables provide a way for values maintained by libgdb to
|
|
be referenced in expressions (e.g. @code{$bpnum}). Libgdb includes a
|
|
means by which the application can define new, integer valued
|
|
convenience variables:
|
|
@page
|
|
@deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg})
|
|
@example
|
|
char * @var{name};
|
|
int (*@var{fn}) (void *);
|
|
void * @var{fn_arg};
|
|
@end example
|
|
This function defines (or undefines) a convenience variable called @var{name}.
|
|
If @var{fn} is NULL, the variable becomes undefined. Otherwise,
|
|
@var{fn} is a function which, when passed @var{fn_arg} returns the value
|
|
of the newly defined variable.
|
|
|
|
No libgdb functions should be called by @var{fn}.
|
|
@end deftypefun
|
|
|
|
One use for this function is to create breakpoint conditions computed in
|
|
novel ways. This is done by defining a convenience variable and
|
|
referring to that variable in a breakpoint condition expression.
|
|
|
|
|
|
@node Asynchronous, Commands, Variables, Top
|
|
@chapter Scheduling Asynchronous Computations
|
|
@cindex asynchronous
|
|
|
|
|
|
A running libgdb function can take a long time. Libgdb includes a hook
|
|
so that an application can run intermittently during long debugger
|
|
operations.
|
|
|
|
@deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg})
|
|
@example
|
|
void (*@var{fn})(void * fn_arg, int (*gdb_poll)());
|
|
void * @var{fn_arg};
|
|
@end example
|
|
Arrange to call @var{fn} periodically during lengthy debugger operations.
|
|
If @var{fn} is NULL, polling is turned off. @var{fn} should take two
|
|
arguments: an opaque pointer passed as @var{fn_arg} to
|
|
@code{gdb_set_poll_fn}, and a function pointer. The function pointer
|
|
passed to @var{fn} is provided by libgdb and points to a function that
|
|
returns 0 when the poll function should return. That is, when
|
|
@code{(*gdb_poll)()} returns 0, libgdb is ready to continue @var{fn}
|
|
should return quickly.
|
|
|
|
It is possible that @code{(*gdb_poll)()} will return 0 the first time it
|
|
is called, so it is reasonable for an application to do minimal processing
|
|
before checking whether to return.
|
|
|
|
No libgdb functions should be called from an application's poll function,
|
|
with one exception: @code{gdb_request_quit}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void gdb_request_quit (void)
|
|
This function, if called from a poll function, requests that the
|
|
currently executing libgdb command be interrupted as soon as possible,
|
|
and that control be returned to the top-level via an error.
|
|
|
|
The quit is not immediate. It will not occur until at least after the
|
|
application's poll function returns.
|
|
@end deftypefun
|
|
|
|
@node Commands, Top, Asynchronous, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Debugger Commands for Libgdb Applications
|
|
|
|
The debugger commands available to libgdb applications are the same commands
|
|
available interactively via GDB. This section is an overview of the
|
|
commands newly created as part of libgdb.
|
|
|
|
This section is not by any means a complete reference to the GDB command
|
|
language. See the GDB manual for such a reference.
|
|
|
|
@menu
|
|
* Command Hooks:: Setting Hooks to Execute With Debugger Commands.
|
|
* View Commands:: View Commands Mirror Show Commands
|
|
* Breakpoints:: The Application Can Have Its Own Breakpoints
|
|
@end menu
|
|
|
|
@node Command Hooks, View Commands, Commands, Commands
|
|
@comment node-name, next, previous, up
|
|
@section Setting Hooks to Execute With Debugger Commands.
|
|
|
|
Debugger commands support hooks. A command hook is executed just before
|
|
the interpreter invokes the hooked command.
|
|
|
|
There are two hooks allowed for every command. By convention, one hook
|
|
is for use by users, the other is for use by the application.
|
|
|
|
A user hook is created for a command XYZZY by using
|
|
@code{define-command} to create a command called @code{hook-XYZZY}.
|
|
|
|
An application hook is created for a command XYZZY by using
|
|
@code{define-command} to create a command called @code{apphook-XYZZY}.
|
|
|
|
Application hooks are useful for interfaces which wish to continuously
|
|
monitor certain aspects of debugger state. The application can set a
|
|
hook on all commands that might modify the watched state. When the hook
|
|
is executed, it can use i/o redirection to notify parts of the
|
|
application that previous data may be out of date. After the top-level loop
|
|
resumes, the application can recompute any values that may have changed.
|
|
(@xref{I/O}.)
|
|
|
|
@node View Commands, Breakpoints, Command Hooks, Commands
|
|
@comment node-name, next, previous, up
|
|
@section View Commands Mirror Show Commands
|
|
|
|
The GDB command language contains many @code{set} and @code{show}
|
|
commands. These commands are used to modify or examine parameters to
|
|
the debugger.
|
|
|
|
It is difficult to get the current state of a parameter from the
|
|
@code{show} command because @code{show} is very verbose.
|
|
|
|
@example
|
|
(gdb) show check type
|
|
Type checking is "auto; currently off".
|
|
(gdb) show width
|
|
Number of characters gdb thinks are in a line is 80.
|
|
@end example
|
|
|
|
For every @code{show} command, libgdb includes a @code{view} command.
|
|
@code{view} is like @code{show} without the verbose commentary:
|
|
|
|
@example
|
|
(gdb) view check type
|
|
auto; currently off
|
|
(gdb) view width
|
|
80
|
|
@end example
|
|
|
|
(The precise format of the ouput from @code{view} is subject to change.
|
|
In particular, @code{view} may one-day print values which can be used as
|
|
arguments to the corresponding @code{set} command.)
|
|
|
|
@node Breakpoints, Structured Output, View Commands, Commands
|
|
@comment node-name, next, previous, up
|
|
@section The Application Can Have Its Own Breakpoints
|
|
|
|
The GDB breakpoint commands were written with a strong presumption that
|
|
all breakpoints are managed by a human user. Therefore, the command
|
|
language contains commands like `delete' which affect all breakpoints
|
|
without discrimination.
|
|
|
|
In libgdb, there is added support for breakpoints and watchpoints which
|
|
are set by the application and which should not be affected by ordinary,
|
|
indiscriminate commands. These are called @dfn{protected} breakpoints.
|
|
|
|
@deffn {Debugger Command} break-protected ...
|
|
@deffnx {Debugger Command} watch-protected ...
|
|
These work like @code{break} and @code{watch} except that the resulting
|
|
breakpoint is given a negative number. Negative numbered breakpoints do
|
|
not appear in the output of @code{info breakpoints} but do in that of
|
|
@code{info all-breakpoints}. Negative numbered breakpoints are not
|
|
affected by commands which ordinarily affect `all' breakpoints (e.g.
|
|
@code{delete} with no arguments).
|
|
|
|
Note that libgdb itself creates protected breakpoints, so programs
|
|
should not rely on being able to allocate particular protected
|
|
breakpoint numbers for themselves.
|
|
@end deffn
|
|
|
|
More than one breakpoint may be set at a given location. Libgdb adds
|
|
the concept of @dfn{priority} to breakpoints. A priority is an integer,
|
|
assigned to each breakpoint. When a breakpoint is reached, the
|
|
conditions of all breakpoints at the same location are evaluated in
|
|
order of ascending priority. When breakpoint commands are executed,
|
|
they are also executed in ascending priority (until all have been
|
|
executed, an error occurs, or one set of commands continues the
|
|
target).
|
|
|
|
@deffn {Debugger Command} priority n bplist
|
|
Set the priority for breakpoints @var{bplist} to @var{n}.
|
|
By default, breakpoints are assigned a priority of zero.
|
|
@end deffn
|
|
|
|
@node Structured Output, Commands, Breakpoints, Commands
|
|
@comment node-name, next, previous, up
|
|
@section Structured Output, The @code{Explain} Command
|
|
|
|
(This section may be subject to considerable revision.)
|
|
|
|
When GDB prints a the value of an expression, the printed representation
|
|
contains information that can be usefully fed back into future commands
|
|
and expressions. For example,
|
|
|
|
@example
|
|
(gdb) print foo
|
|
$16 = @{v = 0x38ae0, v_length = 40@}
|
|
@end example
|
|
|
|
On the basis of this output, a user knows, for example, that
|
|
@code{$16.v} refers to a pointer valued @code{0x38ae0}
|
|
|
|
A new output command helps to make information like this available to
|
|
the application.
|
|
|
|
@deffn {Debugger Command} explain expression
|
|
@deffnx {Debugger Command} explain /format expression
|
|
Print the value of @var{expression} in the manner of the @code{print}
|
|
command, but embed that output in a list syntax containing information
|
|
about the structure of the output.
|
|
@end deffn
|
|
|
|
As an example, @code{explain argv} might produce this output:
|
|
|
|
@example
|
|
(exp-attribute
|
|
((expression "$19")
|
|
(type "char **")
|
|
(address "48560")
|
|
(deref-expression "*$19"))
|
|
"$19 = 0x3800\n")
|
|
@end example
|
|
|
|
The syntax of output from @code{explain} is:
|
|
|
|
@example
|
|
<explanation> := <quoted-string>
|
|
| (exp-concat <explanation> <explanation>*)
|
|
| (exp-attribute <property-list> <explanation>)
|
|
|
|
<property-list> := ( <property-pair>* )
|
|
|
|
<property-pair> := ( <property-name> <quoted-string> )
|
|
@end example
|
|
|
|
The string-concatenation of all of the @code{<quoted-string>} (except
|
|
those in property lists) yields the output generated by the equivalent
|
|
@code{print} command. Quoted strings may contain quotes and backslashes
|
|
if they are escaped by backslash. "\n" in a quoted string stands for
|
|
newline; unescaped newlines do not occur within the strings output by
|
|
@code{explain}.
|
|
|
|
Property names are made up of alphabetic characters, dashes, and
|
|
underscores.
|
|
|
|
The set of properties is open-ended. As GDB acquires support for new
|
|
source languages and other new capabilities, new property types may be
|
|
added to the output of this command. Future commands may offer
|
|
applications some selectivity concerning which properties are reported.
|
|
|
|
The initial set of properties defined includes:
|
|
|
|
@itemize @bullet
|
|
@item @code{expression}
|
|
|
|
This is an expression, such as @code{$42} or @code{$42.x}. The
|
|
expression can be used to refer to the value printed in the attributed
|
|
part of the string.
|
|
|
|
@item @code{type}
|
|
|
|
This is a user-readable name for the type of the attributed value.
|
|
|
|
@item @code{address}
|
|
|
|
If the value is stored in a target register, this is a register number.
|
|
If the value is stored in a GDB convenience variable, this is an integer
|
|
that is unique among all the convenience variables. Otherwise, this is
|
|
the address in the target where the value is stored.
|
|
|
|
@item @code{deref-expression}
|
|
|
|
If the attributed value is a pointer type, this is an expression that
|
|
refers to the dereferenced value.
|
|
@end itemize
|
|
|
|
Here is a larger example, using the same object passed to @code{print}
|
|
in an earlier example of this section.
|
|
|
|
@example
|
|
(gdb) explain foo
|
|
(exp-attribute
|
|
( (expression "$16")
|
|
(type "struct bytecode_vector")
|
|
(address 14336) )
|
|
(exp-concat
|
|
"$16 = @{"
|
|
(exp-attribute
|
|
( (expression "$16.v")
|
|
(type "char *")
|
|
(address 14336)
|
|
(deref-expression "*$16.v") )
|
|
"v = 0x38ae0")
|
|
(exp-attribute
|
|
( (expression "$16.v_length")
|
|
(type "int")
|
|
(address 14340) )
|
|
", v_length = 40")
|
|
"@}\n"))
|
|
@end example
|
|
|
|
It is undefined how libgdb will indent these lines of output or
|
|
where newlines will be included.
|
|
|
|
@bye
|