+++ /dev/null
-\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 copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and no Back-Cover Texts.
-@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 discard output silently.
-
-
-@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
projects / binutils-gdb.git / commitdiff