Substantial rewrite.

1 files changed, 642 insertions, 1235 deletions

diff --git a/gdb/doc/libgdb.texinfo b/gdb/doc/libgdb.texinfo
index c67c3a8..34a531a 100644
--- a/gdb/doc/libgdb.texinfo
+++ b/gdb/doc/libgdb.texinfo
@@ -2,15 +2,33 @@
 @c %**start of header
 @setfilename libgdb.info
 @settitle Libgdb
-@setchapternewpage odd
+@setchapternewpage off
 @c %**end of header
 
 @ifinfo
-This file documents libgdb, the GNU library for symbolic debuggers.
+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 ...
+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
@@ -18,1454 +36,843 @@ Permission is granted to ...
 
 @titlepage
 @title Libgdb
-@subtitle Version 0.1
-@subtitle 27 Sep 1993
+@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
-Copyright @copyright{} 1993 COPYRIGHT-OWNER
+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.
 
-Published by ...
-
-Permission is granted to ...
+Copyright @copyright{} 1993 Cygnus Support
 @end titlepage
 
-@node Top, Overview, (dir), (dir)
-
 @ifinfo
+@node Top, Overview, (dir), (dir)
 
-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
+This info file documents libgdb: an API for GDB, the GNU symbolic debugger.
 
 @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.
+* 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
 
-
-@node    Copying, Overview, top,      top
-@comment node-name,     next,           previous, up
-@chapter Copying
-@cindex copying
-
-blah blah
-
-@node    Overview, Conventions, Copying,      top
+@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 library which provides the core functionality of a symbolic
-debugger.  It is derived from GNU GDB and depends on the BFD library.
+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.
 
-target
-inferior
 
+@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.
 
-@node    Conventions, Targets, Overview,      top
-@comment node-name,     next,           previous, up
-@chapter Programming Conventions for Libgdb Clients
-@cindex Conventions
 
-@heading Naming Conventions
+@heading Terminology
 
-Names intentionally exported from libgdb all begin @code{gdb_}
-as in @code{gdb_use_file}.
+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 Error Returns
+@heading Dependencies
 
-Libgdb functions that might not succeed generally have a return
-type of @code{gdb_error_t}.
+Programs which are linked with libgdb must be linked with libbfd,
+libopcodes, libiberty, and libmmalloc.
 
-@deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error})
-returns a reasonable error message for @var{error}.
-@end deftypefun
+@heading Acknowledgments
 
+Essential contributions to this design were made by Stu Grossman, Jim
+Kingdon, and Rich Pixley.
 
-@heading Blocking I/O
+@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.
 
-@heading Global Parameters
-@subheading the current directory 
-@deftypefun gdb_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
+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.
 
-@deftypefun {char *} gdb_copy_pwd ()
-Make a copy of the name of gdb's default directory.@*
-(pwd_command)
-@end deftypefun
+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.
 
-@subheading controlling the input/output radix
-@deftypefun gdb_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 gdb_error_t gdb_set_input_radix (int)
-@deftypefunx gdb_error_t gdb_set_output_radix (int)
-@deftypefunx gdb_error_t gdb_set_radix (int)
-Valid output radixes are only 0 (heuristic), 10, and 16.@*
-(set_radix)
-@end deftypefun
+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.
 
-@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
+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.
 
-@deftypefun {struct environ *} gdb_make_environ ()
-Create a new (empty) environment.@*
-(make_environ)
-@end deftypefun
+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.
 
-@deftypefun {void} gdb_free_environ (struct environ *)
-Free an environment allocated by `gdb_make_environ'.@*
-(free_environ)
-@end deftypefun
+@node Top Level, I/O, Interpreter, Top
+@chapter You Provide the Top Level for the Libgdb Command Interpreter
+@cindex {top level}
 
-@deftypefun {void} gdb_init_environ (struct environ * env)
-Copy the processes environment into ENV.@*
-(init_environ)
-@end deftypefun
+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.
 
-@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
+@heading Initialization
 
+Before calling any other libgdb functions, call this:
 
-@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)
+@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.
 
-@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
+@heading The Top-Level Loop
 
-
-@subheading integer callbacks
-
-Another common kind of callback takes just an integer.
+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
-struct gdb_int_cback;
-typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int);
+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
 
-@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.
+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
 
-This is exactly equivalent to a sequence of two calls:
+@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
-  gdb_use_exec_file (filename);
-  gdb_use_symbol_file (filename);
+  char * @var{name};
+  struct gdb_output_vector * @var{vec};
 @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.
+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
 
-@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
+@subheading Output
 
+An output vector is a structure with at least these fields: 
 
-@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 gdb_output_vector
 @{
-  struct symtab *symtab;
-  int line;
-  CORE_ADDR pc;
-  CORE_ADDR end;
+  /* output */
+  void (*put_string) (struct gdb_output_vector *, char * str);
 @}
 @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
-
+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.
 
-@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
+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
 
-@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;
+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
-  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
 
+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.
 
-@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
+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.
 
-@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
+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.
 
-@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
+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 int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out})
+@deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *)
 @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};
+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
-List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}.
 
+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.
 
-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)
+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}.)
 
-@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.
+@heading I/O Redirection in Debugger Commands
 
-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
+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
 
-@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}
+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.
 
-How to find the source that corresponds to executable code and the
-executable code that corresponds to a line of source.
+@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
 
-@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
 
+@heading Initial Conditions
 
-@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
+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.
 
-@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
 
+@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. 
 
- -- IDIOM: The gdb command `show directories'.
+@deftypefun void gdb_execute_command (@var{command})
 @example
-  puts_filtered ("Source directories searched: ");
-  puts_filtered (source_path);
-  puts_filtered ("\n");
+char * @var{command};
 @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)
+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:
 
-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 void gdb_execute_with_io (@var{command}, @var{vecs})
+@example 
+char * @var{command};
+struct gdb_io_vecs * @var{vecs};
 
-@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};
+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
-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
 
+Execute @var{command}, temporarily using the i/o vectors in @var{vecs}.
 
-@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)
+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 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:
+@deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd})
 @example
-    for (; count > 0; --count)
-      gdb_clear_proceed_status ();
-      gdb_proceed (...);
+char * cmd;
 @end example
-(next_command, nexti_command, step_command, stepi_command)
-@end deftypefun
-
-
- -- IDIOM: Continuing a program where it stopped.
+@deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input})
 @example
-  gdb_clear_proceed_status ();
-  gdb_proceed ((CORE_ADDR) -1, -1, 0);
+char * cmd;
+struct gdb_input_vector * input;
 @end example
-(continue_command)
-
-
- -- IDIOM: Continuing a program giving it a specified signal.
+@page
 @example
-  gdb_clear_proceed_status ();
-  gdb_proceed ((CORE_ADDR) -1, signum, 0);
+struct gdb_str_output
+@{
+  char * error;
+  char * info;
+  char * value;
+@};
 @end example
-(signal_command)
 
+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. 
 
-@deftypefun {char *} strtosigno (char * @var{str})
-(Typical use:)
-@example
-  signum = strtosigno (signum_exp);
+If the command aborts with an error, then the @code{value} field will be
+NULL, though the other two strings will be present.
 
-  if (signum == 0)
-    /* Not found as a name, try it as an expression.  */
-    signum = parse_and_eval_address (signum_exp);
+In all cases, the strings returned are allocated by malloc and should be
+freed by the caller.
 
-  gdb_clear_proceed_status ();
-  gdb_proceed ();
-@end example
-@end deftypefun
+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
 
- -- IDIOM: Continuing a program at a specified address.
+@deftypefun void execute_catching_errors (@var{command})
 @example
-  gdb_clear_proceed_status ();
-  gdb_proceed (addr, 0, 0);
+char * @var{command};
 @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)
+Like @code{execute_command} except that no error handler is required.
 @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.]]]
+@deftypefun void execute_with_text (@var{command}, @var{text})
 @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);
+char * @var{command};
+char ** @var{text};
 @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.
+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.
 
-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)
+This form of execute_command is useful for commands like @code{define},
+@code{document}, and @code{commands}.
 @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
+@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).  
 
-@deftp Type {struct breakpoint}
-Breakpoints are typically represented @code{struct breakpoint *}.
-@end deftp
+In addition, an application can add new primitives to the GDB command
+language.
 
-
-@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})
+@deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc})
 @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
-
+char * @var{name};
+gdb_cmd_fn @var{fn};
+char ** @var{doc};
 
-@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;
-@};
+typedef void (*gdb_cmd_fn) (char * args);
 @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
 
+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.
 
-@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
-
+Calling this function twice with the same name replaces an earlier
+definition, but application commands can not replace builtin commands of
+the same name.
 
-@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]]]
+The documentation string of the command is set to a copy of the NULL
+terminated array of strings @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}
 
-@deftp Type {struct breakpoint_cback} 
+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
-typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num);
-struct breakpoint_cback
-@{
-  breakpoint_cback_fn fn;
-@};
+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.
 
-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})
+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.
 
-@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
 
+@node Asynchronous, Commands, Variables, Top
+@chapter Scheduling Asynchronous Computations
+@cindex asynchronous
 
-@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
 
+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_handle_command (char * @var{args})
-Takes arguments like the gdb command `handle' and has
-the same effect.@*
-(handle_command)
-@end deftypefun
+@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.
 
-@deftypefun void gdb_signals_info (struct gdb_stream_cback *)
-Show how signals are handled.@*
-(signals_info)
+No libgdb functions should be called from an application's poll function,
+with one exception: @code{gdb_request_quit}.
 @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 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.
 
-@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
+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
 
-@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
+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.
 
-@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
+@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.
 
-@deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@*
-(Example use: Implementing @code{disassemble_command})@*
-(get_frame_pc)
-@end deftypefun
+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.
 
-@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
+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}.
 
-@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
+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
 
-@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
+The GDB command language contains many @code{set} and @code{show}
+commands.  These commands are used to modify or examine parameters to
+the debugger.
 
+One difficulty to get the current state 3f a parameter from the
+@code{show} command because @code{show} is very verbose.
 
- -- 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++;
-@}
+(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:
 
-@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};
+(gdb) view check type
+auto; currently off
+(gdb) view width
+80
 @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
 
+(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, 
 
-@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};
+(gdb) print foo
+$16 = @{v = 0x38ae0, v_length = 40@}
 @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'.
+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.
 
-@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
+@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:
 
- -- 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");
-@}
+(exp-attribute
+   ((expression "$19")
+    (type "char **")
+    (address "48560")
+    (deref-expression "*$19"))
+   "$19 = 0x3800\n")
 @end example
 
+The syntax of output from @code{explain} is:
 
-@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
+<explanation> :=    <quoted-string>
+                  | (exp-concat <explanation> <explanation>*)
+                  | (exp-attribute <property-list> <explanation>)
 
+<property-list> := ( <property-pair>* )
 
-@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
+<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}.
 
-@deftypefun char * strsigno (int)
-Return a symbolic name for a signal.
-@end deftypefun
+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.
 
-@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
+The initial set of properties defined includes: 
 
+@itemize @bullet
+@item @code{expression}
 
-float_info
-[[[what is appropriate?]]]
+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}
 
-@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
+This is a user-readable name for the type of the attributed value.
 
+@item @code{address}
 
-@node    Types, top,       Examining, top
-@comment node-name,     next,           previous, up
-@chapter Examining the Types of an Inferior's Data
-@cindex types
+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}
 
-@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
+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.
 
-@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};
+(gdb) explain foo
+(exp-attribute
+  ( (expression "$16")
+    (type "struct bytecode_vector")
+    (address 14336) )
+  (exp-concat
+    "$17 = @{"
+    (exp-attribute
+      ( (expression "$17.v")
+        (type "char *")
+        (address 14336)
+        (deref-expression "*$17.v") )
+      "v = 0x38ae0")
+    (exp-attribute
+      ( (expression "$17.v_length")
+        (type "int")
+        (address 14340) )
+      ", v_length = 40")
+     "@}\n"))
 @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.]]]
+It is undefined how libgdb will indent these lines of output or 
+where newlines will be included.
 
 @bye