diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 9153272f8a9..7d259a4d5e3 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +Mon Oct 25 03:25:41 1993 Tom Lord (lord@cygnus.com) + + * libgdb.texinfo: total rewrite from a different starting + premise. + Wed Oct 20 18:07:44 1993 Jim Kingdon (kingdon@lioth.cygnus.com) * stabs.texinfo (Local Variable Parameters): Re-write paragraph on diff --git a/gdb/doc/libgdb.texinfo b/gdb/doc/libgdb.texinfo index c67c3a88359..34a531a6dde 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 +@ifinfo @node Top, Overview, (dir), (dir) -@ifinfo - -Libgdb is a library which provides the core functionality of a symbolic -debugger. It is derived from GNU GDB and depends on the BFD library. - -This is an early draft of this document. Subsequent versions will likely -contain revisions, deletions and additions. - -This document applies to version 0.0. - -Text marked `[[[' indicates areas which require expansion. - -Many nodes describe library entry points by giving a prototype and brief -description: - -@deftypefun {const char **} gdb_warranty () -(warranty_info) -Return a pointer to the text of the GDB disclaimer. -@end deftypefun - -The parenthesized symbols (e.g. `(warranty_info)') refer to the -existing GDB source and generally indicate where to find code with -which to implement the library function. -@end ifinfo +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. - -target -inferior +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 -@node Conventions, Targets, Overview, top -@comment node-name, next, previous, up -@chapter Programming Conventions for Libgdb Clients -@cindex Conventions - -@heading Naming Conventions - -Names intentionally exported from libgdb all begin @code{gdb_} -as in @code{gdb_use_file}. +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 Error Returns +@heading Terminology -Libgdb functions that might not succeed generally have a return -type of @code{gdb_error_t}. +In this document, @dfn{libgdb} refers to a library containing the +functions defined herein, @dfn{application} refers to any program built +with that library. -@deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error}) -returns a reasonable error message for @var{error}. + +@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 Blocking I/O +@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: - -@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 - -@deftypefun {char *} gdb_copy_pwd () -Make a copy of the name of gdb's default directory.@* -(pwd_command) -@end deftypefun - - -@subheading controlling the input/output radix -@deftypefun 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 - - -@subheading manipulating environments -@deftp Type {struct environ} @example -struct environ -@{ - int allocated; - char ** vector; -@} +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 -A `struct environ' holds a description of environment -variable bindings. + +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 {struct environ *} gdb_make_environ () -Create a new (empty) environment.@* -(make_environ) -@end deftypefun - -@deftypefun {void} gdb_free_environ (struct environ *) -Free an environment allocated by `gdb_make_environ'.@* -(free_environ) -@end deftypefun - -@deftypefun {void} gdb_init_environ (struct environ * env) -Copy the processes environment into ENV.@* -(init_environ) -@end deftypefun - -@deftypefun {char **} gdb_get_in_environ (const struct environ * @var{env}, const char * @var{var}) -Look up the binding of @var{var} in @var{env}.@* -(get_in_environ) -@end deftypefun - - -@deftypefun {void} gdb_set_in_environ (struct environ * @var{env}, const char * @var{var}, const char * @var{value}) -Lookup/bind variables within an environment. -(set_in_environ) -@end deftypefun - - -@subheading legal notices -@deftypefun {char **} gdb_copying () -@deftypefunx {char **} gdb_warranty () -These return pointers to NULL terminated arrays of strings. -They contain text which describes the conditions under which -libgdb is distributed (`gdb_copying') and which explains to -users that there is no warranty for libgdb (`gdb_warranty').@* -(show_warranty_command, show_copying_command) -@end deftypefun - - -@subheading the inferior's terminal -@deftypefun void gdb_inferiors_io (int @var{std_in}, int @var{std_out}, int @var{std_err}) -Assert that the given descriptors should be copied into -descriptors 0, 1, and 2 of the inferior when it -is next run. -@end deftypefun - - -@heading callbacks - -One idiom used in several places deserves mention. -At times, it makes sense for libgdb functions to -invoke functions provided by the libgdb client. -Where this is the case, callback structures are used -to refer to client functions. For example, here -are the declarations for a callback to which libgdb -will pass an integer and a character pointer. - +@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 -struct a_gdb_cback; -typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *, - int, char *); + 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 -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: + + +@subheading Output + +An output vector is a structure with at least these fields: @example -struct my_cback +struct gdb_output_vector @{ - struct a_gdb_cback gdb_cback; /* must be first */ - float magic_number; -@}; - -void -foo_helper (struct a_gdb_cback * callback, int i, char * cp) -@{ - foo ( ((struct my_cback *)callback)->magic_number, i, c); -@} - -struct my_cback -@{ - foo_helper, - 1079252848.8 -@} the_cback; -@end example - - -@subheading stream callbacks - -A common kind of callback takes just a character pointer, -presumed to point to part or all of an informational -message. - -@example -struct gdb_stream_cback; -typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *, - char *); -@end example - - -@subheading integer callbacks - -Another common kind of callback takes just an integer. - -@example -struct gdb_int_cback; -typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int); -@end example - -@node Targets, Symtabs, Conventions, top -@comment node-name, next, previous, up -@chapter Selecting Targets and Symbol Tables for Debugging -@cindex targets - -@deftypefun gdb_error_t gdb_use_file (char * @var{filename}) -Arrange to read both executable code and symbol table information -from FILENAME. - -This is exactly equivalent to a sequence of two calls: -@example - gdb_use_exec_file (filename); - gdb_use_symbol_file (filename); -@end example -(file_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_use_exec_file (char * @var{filename}) -Read the code to debug from `filename'.@* -(exec_file_command) -@end deftypefun - - -@deftypefun {char *} gdb_get_exec_file () -Return the name of the executable file as a string or 0 -if there is none. -@end deftypefun - - -@deftypefun gdb_error_t gdb_use_core (char * @var{filename}) -Specify the whereabouts of a core dump file to be used as the -"contents of memory". Traditionally, core files contain only some -parts of the address space of the process that generated them; GDB -can access the executable file itself for other parts. - -If @var{filename} is @code{NULL}, no core file is used.@* -(core_file_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_use_symbol_file (char * @var{filename}) -Arrange to read symbol table information from `filename'. - -This is the same as: - - gdb_symbol_file_add (filename, 1, (CORE_ADDR)0, 1, 0, 0); - -See @code{gdb_symbol_file_add} for finer control over the symbol -table.@* -(symbol_file_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_symbol_file_add (@var{name}, @var{verbose}, @var{text_addr}, @var{replace}, @var{eager}) -Arrange to read additional symbol table information from -the file `name'. - -The arguments are: -@itemize @minus -@item struct gdb_stream_cback * @var{info_out} - -Callback to handle informational output. - -@item char * @var{name} - -If not 0, verbose output will occur. - -@item int @var{be_verbose} - -Regulates the amount of informational output produced. - -@item CORE_ADDR @var{text_addr} - -is the address at which the named file is presumed to have -been loaded. - -@item int @var{replace}@* - -If not 0, this will become the only file -in the symbol table -- all previously loaded -symbol table information will be discarded. - -@item int @var{readnow} - -If not 0, eagerly read symbols from this file,otherwise -symbols will only be read lazily (as needed). -@end itemize -@end deftypefun - - -@deftypefun {char *} gdb_copy_exec_path () -Make a copy of the execution path.@* -[[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]@* -(path_info) -@end deftypefun - - -@deftypefun void gdb_mod_exec_path (char * @var{dirnames}) -Add zero or more directories to the front of the execution path. -@var{dirnames} should be a colon separated list of directory names.@* -(path_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_target_device (char * @var{name}) -Connects the libgdb host environment to a target machine -or process.@* -(target foo) -@end deftypefun - - -@deftypefun gdb_error_t gdb_set_baud (int @var{rate}) -If using a remote target connected by a serial port, -use RATE as the communication speed. -@end deftypefun - - -@deftypefun gdb_error_t gdb_set_target_debugging (int @var{level}) -Choose the level of verboseness of with which a remote -target produces debugging output. -@end deftypefun - -@node Symtabs, Source, Targets, top -@comment node-name, next, previous, up -@chapter Accessing symbol tables and debugging information. -@cindex Symtabs -@cindex {Symbol Tables} - -@deftp Type {struct symtab} -Each source file is represented by a struct symtab. -In many contexts, @code{struct symtab *} is used in preference -to a {char *} filename to refer to the source. -@end deftp - - -@deftypefun {char *} gdb_symtab_to_filename (struct symtab *) -@deftypefunx {char *} gdb_symtab_to_dirname (struct symtab *) -Return the location of the file corresponding to this symtab. -@code{gdb_symtab_to_dirname} might return @code{NULL} if no directory -is known. @code{gdb_symtab_to_line_count} might return -1 if line -number information is unavailable. -@end deftypefun - -@deftypefun int gdb_symtab_to_line_count (struct symtab *) -(See also `Source') -@end deftypefun - - -@deftypefun {struct symtab *} gdb_filename_to_symtab (char * @var{filename}) -Lookup the symbol table of a source file named NAME.@* -(lookup_symtab) -@end deftypefun - - -@deftp Type {struct symtab_and_line} -@example -struct symtab_and_line -@{ - struct symtab *symtab; - int line; - CORE_ADDR pc; - CORE_ADDR end; + /* 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. +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. -@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 +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 symtab_and_line} gdb_find_pc_line (CORE_ADDR @var{pc}, int @var{notcurrent}) -Find the source file and line number for a given @var{pc} value. -Return a structure containing a symtab pointer, a line number, -and a pc range for the entire source line. -The value's @code{.pc} field is NOT the specified @var{pc}. -@var{notcurrent} nonzero means, if specified pc is on a line boundary, -use the line that ends there. Otherwise, in that case, the line -that begins there is used.@* -(find_pc_line) -@end deftypefun - - -@deftypefun gdb_error_t gdb_find_line (struct symtab_and_line * @var{out}, struct symtab *, int) -Create a symtab_and_line for a given symtab and line number. -In other words, if you know the source file and line, -this returns a location for the breakpoint.@* -(resolve_sal_pc) -@end deftypefun - - -@deftypefun {struct symtabs_and_lines} gdb_decode_line (@var{argptr}, @var{firstln}, @var{default_symtab}, @var{default_line}, @var{canonical}) @example - char ** argptr; - int funfirstline; - struct symtab * default_symtab; - int default_line; - char *** canonical; +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: +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. - 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. +There are four kinds of input requests explicitly made by libgdb. - FUNCTION may be an undebuggable function found in minimal symbol - table. +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. - If the argument FUNFIRSTLINE is nonzero, we want the first line - of real code inside a function when a function is specified. +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. - DEFAULT_SYMTAB specifies the file to use if none is specified. - It defaults to current_source_symtab. +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. - 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. +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. - 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. +@heading I/O Redirection from the Application Top-Level - The return value of this function includes allocated memory - which the caller is responsible for freeing: - - struct symtabs_and_lines sals; - sals = decode_line_spec (arg, 1); - .... - free (sals.sals);@* -(decode_line_1) -@end deftypefun - - -@deftp Type {struct block *} -Lexical environments in the program are represented by struct block. -These are useful as arguements to expression parsing functions (see -`Expressions'). -@end deftp - - -@deftypefun {struct block *} gdb_block_for_pc (CORE_ADDR) -Return the innermost lexical block containing the -specified pc value, or 0 if there is none.@* -(block_for_pc) -@end deftypefun - - -@deftypefun {struct block *} gdb_get_frame_block (FRAME @var{frame}) -This returns the block being executed by a given -stack frame (see `Stack')@* -(get_frame_block) -@end deftypefun - - -@deftypefun int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out}) +@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) +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}.) -@deftypefun int gdb_find_pc_partial_function (@var{pc}, @var{name}, @var{address}, @var{endaddr}) +@heading I/O Redirection in Debugger Commands + +A libgdb application creates input and output vectors and assigns them names. +Which input and output vectors are used by libgdb is established by +executing these debugger commands: + +@defun {set input-vector} name +@defunx {set error-output-vector} name +@defunx {set info-output-vector} name +@defunx {set value-output-vector} name +Choose an I/O vector by name. +@end defun + + +A few debugger commands are for use only within commands defined using +the debugger command `define' (they have no effect at other times). +These commands exist so that an application can maintain hooks which +redirect output without affecting the global I/O vectors. + +@defun with-input-vector name +@defunx with-error-output-vector name +@defunx with-info-output-vector name +@defunx with-value-output-vector name +Set an I/O vector, but only temporarily. The setting has effect only +within the command definition in which it occurs. +@end defun + + +@heading Initial Conditions + +When libgdb is initialized, a set of default I/O vectors is put in +place. The default vectors are called @code{default-input-vector}, +@code{default-output-vector}, &c. + +The default query function always returns `y'. Other input functions +always abort. The default output functions do nothing. + + +@node Invoking, Defining Commands, I/O, Top +@chapter Invoking the Interpreter, Executing Commands +@cindex {executing commands} +@cindex {invoking the interpreter} + +This section introduces the libgdb functions which invoke the command +interpreter. + +@deftypefun void gdb_execute_command (@var{command}) @example -CORE_ADDR @var{pc}; -char **@var{name}; -CORE_ADDR *@var{address}; -CORE_ADDR *@var{endaddr}; +char * @var{command}; @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) +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_list_symbols (@var{info_out}, @var{regexp}, @var{class}, @var{bpt}) -@example -struct gdb_stream_cback * @var{info_out}; -char * @var{regexp}; -int @var{class}; -int @var{bpt}; -@end example -List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}. - - -If @var{class} is ... -@itemize @bullet -@item -0, list all symbols except functions, type names, and -constants (enums). -@item -1, list only functions. -@item -2, list only type names. -@item -3, list only method names. -@end itemize -BPT is non-zero if set a breakpoint at the functions we find.@* -(variables_info, functions_info, types_info, list_symbols) -@end deftypefun - - -@deftypefun int gdb_locals_info (struct gdb_stream_cback * @var{info_out}, FRAME @var{frame}) -Print all the local variables in the given frame. -including all the blocks active in that frame -at its current pc. - -Returns 1 if the job was done, -or 0 if nothing was printed because we have no info -on the function running in @var{frame}.@* -(locals_info) -@end deftypefun - - -@deftypefun int print_frame_arg_vars (struct gdb_stream_cback *, FRAME) -Similar to `gdb_locals_info'.@* -(args_info) -@end deftypefun - -@node Source, Running, Symtabs, top -@comment node-name, next, previous, up -@chapter Relating Inferiors to Source Files -@cindex source -@cindex {source files} - -How to find the source that corresponds to executable code and the -executable code that corresponds to a line of source. - -@deftypefun {char *} gdb_copy_source_fullname (struct symtab *@var{s}) -Return a copy of the full path name to a source file. -(See `Symtabs' for more information about filenames -and symbol tables.). -@end deftypefun - - -@deftypefun int gdb_open_source_file (struct symtab *@var{s}) -Open a source file corresponding to @var{s}. Returns a file descriptor -or negative number for error. -[[[We may decide not to provide this function.]]]@* -(open_source_file) -@end deftypefun - - -@deftypefun int gdb_source_line_pos (struct symtab * @var{s}, int @var{lineno}) -Return the byte offset of a given line of source -or a negative number if @var{lineno} is out of range.@* -(find_source_lines) -@end deftypefun - - - -- IDIOM: The gdb command `show directories'. -@example - puts_filtered ("Source directories searched: "); - puts_filtered (source_path); - puts_filtered ("\n"); -@end example -(show_directories) - - -@deftypefun {char *} gdb_source_path () -Return the path in which source files are sought.@* -(source_path) -@end deftypefun - - -@deftypefun void gdb_modify_source_path (char * @var{dirnames}) -Change the source path according to dirnames.@* -(directory_command) -@end deftypefun - - -See `Symtabs' for functions relating symbol tables to files. -(source_info) - - -See `Symtabs' for functions relating source lines to PC values. -(line_info) - - -[[[Try to expose sources_info without having to introduce struct object *?]]] -(sources_info) - - -@node Running, Stopping, Source, top -@comment node-name, next, previous, up -@chapter Creating, Continuing, and Stepping Through an Inferior Process -@cindex running - - -@deftypefun gdb_error_t gdb_target_create_inferior (@var{exec}, @var{args}, @var{environ}) -@example -char * @var{exec_file}; -char * @var{inferior_args}; -char ** @var{inferior_environment_vector}; -@end example -Create a running inferior. -[[[I think the exec_file parameter is redundant. Perhaps this will take -only two arguments.]]]@* -(run_command, target_create_inferior) -@end deftypefun - - -@deftypefun int gdb_target_has_execution () -Return non-0 if an inferior is running.@* -(target_has_execution) -@end deftypefun - - -@deftypefun void gdb_target_kill () -Kill the inferior process. Make it go away. -The inferior may become a core file. -If so, gdb_target_has_stack() will return non-0.@* -(target_kill) -@end deftypefun - - -@deftypefun gdb_error_t gdb_step_1 (@var{skip_subs}, @var{single_inst}, @var{repeat_count}) +@deftypefun void gdb_execute_with_io (@var{command}, @var{vecs}) @example -int skip_subs; -int single_inst; -int repeat_count; -@end example -Continue a program a little bit. Roughly: -@example - for (; count > 0; --count) - gdb_clear_proceed_status (); - gdb_proceed (...); -@end example -(next_command, nexti_command, step_command, stepi_command) -@end deftypefun +char * @var{command}; +struct gdb_io_vecs * @var{vecs}; - - -- IDIOM: Continuing a program where it stopped. -@example - gdb_clear_proceed_status (); - gdb_proceed ((CORE_ADDR) -1, -1, 0); -@end example -(continue_command) - - - -- IDIOM: Continuing a program giving it a specified signal. -@example - gdb_clear_proceed_status (); - gdb_proceed ((CORE_ADDR) -1, signum, 0); -@end example -(signal_command) - - -@deftypefun {char *} strtosigno (char * @var{str}) -(Typical use:) -@example - signum = strtosigno (signum_exp); - - if (signum == 0) - /* Not found as a name, try it as an expression. */ - signum = parse_and_eval_address (signum_exp); - - gdb_clear_proceed_status (); - gdb_proceed (); -@end example -@end deftypefun - - - -- IDIOM: Continuing a program at a specified address. -@example - gdb_clear_proceed_status (); - gdb_proceed (addr, 0, 0); -@end example -(jump_command) - - -@deftypefun gdb_error_t gdb_finish () -"finish": Set a temporary breakpoint at the place -the selected frame will return to, then continue. -This is a convenience function but it summarizes a lot -of other stuff.@* -(finish_command) -@end deftypefun - - -@deftypefun void gdb_clear_proceed_status () -Clear out all variables saying what to do when inferior is continued. -First do this, then set the ones you want, then call @code{gdb_proceed}. - - [[[Some of these should be documented, others hidden.]]] -@example - The variables are: - trap_expected = 0; - step_range_start = 0; - step_range_end = 0; - step_frame_address = 0; - step_over_calls = -1; - stop_after_trap = 0; - stop_soon_quietly = 0; - proceed_to_finish = 0; - breakpoint_proceeded = 1; /* We're about to proceed... */ - - /* Discard any remaining commands or status from previous stop. */ - bpstat_clear (&stop_bpstat); -@end example -(clear_proceed_status) -@end deftypefun - - -@deftypefun void gdb_proceed (CORE_ADDR @var{addr}, int @var{signal}, int @var{step}) -Basic routine for continuing the program in various fashions. - -@var{addr} is the address to resume at, or -1 for resume where stopped.@* -@var{signal} is the signal to give it, or 0 for none, -or -1 for act according to how it stopped.@* -@var{step} is nonzero if should trap after one instruction. --1 means return after that and print nothing.@* -You should probably set various step_... variables -before calling here, if you are stepping. - -You should call @code{gdb_clear_proceed_status} before calling proceed. -(See the documentation for @code{gdb_clear_proceed_status} for more -parameters to @code{gdb_proceed}).@* -(proceed) -@end deftypefun - - -@deftypefun gdb_error_t gdb_return (value @var{return_value}, FRAME @var{frame}) -Make @var{frame} return to @var{value} to it's caller. -Unlike the other functions in this section, this doesn't -call proceed. -(return_command) -@end deftypefun - - -@deftypefun int gdb_inferior_pid () -0 or the valid pid of an inferior. -@end deftypefun - - -@deftypefun gdb_error_t gdb_attach (int @var{pid}) -takes a program started up outside of gdb and -`attaches'' to it. This stops it cold in its tracks and allows us -to start debugging it. and wait for the trace-trap that results -from attaching.@* -(attach_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_detach (int @var{signal_num}) -Takes a program previously attached to and detaches it. -The program resumes execution and will no longer stop -on signals, etc. We better not have left any breakpoints -in the program or it'll die when it hits one. For this -to work, it may be necessary for the process to have been -previously attached. It *might* work if the program was -started via the normal ptrace (PTRACE_TRACEME).@* -(detach_command) -@end deftypefun - -@node Stopping, Stack, Running, top -@comment node-name, next, previous, up -@chapter Using Breakpoints, Signaling an Inferior -@cindex stopping -@cindex breakpoints - - -@deftp Type {struct breakpoint} -Breakpoints are typically represented @code{struct breakpoint *}. -@end deftp - - -@deftypefun {struct breakpoint *} gdb_find_breakpoint (int) -Find a breakpoint given it's number (return 0 if it doesn't exist). -@end deftypefun - -@deftypefun gdb_error_t gdb_set_break (struct breakpoint * @var{brk_out}, struct symtab_and_line) -@deftypefunx gdb_error_t gdb_set_tbreak (struct breakpoint *, struct symtab_and_line) -@deftypefunx gdb_error_t gdb_set_until (struct breakpoint *, struct symtab_and_line) -These three are like their command language counterparts. -They are front ends to `gdb_set_raw_breakpoint'. -See `Symtabs' for sources of `struct symtab_and_line'.@* -(break_command, break_command_1, until_command, tbreak_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_set_watchpt (@var{brk_out}, @var{exp_string}, @var{exp}, @var{exp_valid_block}) -@example -struct breakpoint * @var{brk_out}; -char * @var{exp_string}; -struct expression * @var{exp}; -struct block * @var{expression_valid_block}; -@end example -Set a watchpoint for the given expression.@* -(watch_command) -@end deftypefun - - -@deftypefun void gdb_set_ignore_count (int @var{bptnum}, int @var{count}) -Set ignore-count of breakpoint number BPTNUM to COUNT.@* -(set_ignore_count) -@end deftypefun - - -@deftypefun {struct gdb_bp_condition *} gdb_set_condition (@var{bp}, @var{exp_str}, @var{cond}) -@example -int @var{pbtnum}; -char * @var{exp_str}; -struct gdb_bp_condition * @var{cond}; - -typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num); -struct gdb_bp_condition +struct gdb_io_vecs @{ - gdb_bp_fn fn; -@}; + struct gdb_input_vector * input; + struct gdb_output_vector * error; + struct gdb_output_vector * info; + struct gdb_output_vector * value; +@} @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) +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 gdb_error_t gdb_enable_breakpoint (struct breakpoint * @var{bpt}, int @var{once}) -@deftypefunx gdb_error_t gdb_disable_breakpoint (struct breakpoint * @var{bpt}) -Enable/disable a breakpoint. If `once' is not 0, the -breakpoint is only temporarily enabled.@* -(enable_breakpoint, disable_breakpoint, enable_command) -@end deftypefun - - -@deftypefun gdb_error_t gdb_delete_breakpoint (struct breakpoint * @var{bpt}) -Delete a breakpoint and clean up all traces of it in the -data structures.@* -(delete_breakpoint) -@end deftypefun - - -@deftypefun void gdb_clear_breakpoints (struct symtabs_and_lines * @var{sals}) -Clear breakpoints from a list of program locations as -might be returned by `gdb_decode_line' (see `Symtabs').@* -(clear_command) -@end deftypefun - - -@deftypefun {static struct symtabs_and_lines} get_catch_sals (int @var{this_level_only}) -Return the line numbers of all exception handlers currently -active (or `this_level_only'?? [[[?]]]). -[[[The implementation should remember to resolve_sal_pc]]] -@end deftypefun - - -@deftp Type {struct breakpoint_cback} +@deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd}) @example -typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num); -struct breakpoint_cback +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 @{ - breakpoint_cback_fn fn; + char * error; + char * info; + char * value; @}; @end example -Breakpoints can have an associated function which is called -when the program is stopped by that breakpoint.@* -(commands_command) -@end deftp +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. -@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.]]] +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 {struct breakpoint_cback *} gdb_get_breakpoint_cback (int @var{bp_num}) -@end deftypefun - - -@deftypefun void gdb_breakpoints_info (struct gdb_stream_cback, int @var{bp_num}, int @var{watches}) -Print information on breakpoint number @var{bnum}, or -1 if all. -If @var{watches} is zero, process only breakpoints; if @var{watches} -is nonzero, process only watchpoints. -[[[In the long run, expose the information read off by this function.]]]@* -(info breakpoints, info watchpoints, breakpoints_info, breakpoint_1) -@end deftypefun - - -@deftypefun void gdb_catch_info (struct gdb_stream_cback *) -Print a list of all the exception handlers that are active in the -current stack frame at the current point of execution.@* -(catch_info) -@end deftypefun - - -@deftypefun void gdb_handle_command (char * @var{args}) -Takes arguments like the gdb command `handle' and has -the same effect.@* -(handle_command) -@end deftypefun - - -@deftypefun void gdb_signals_info (struct gdb_stream_cback *) -Show how signals are handled.@* -(signals_info) -@end deftypefun - - -@node Stack, Expressions, Stopping, top -@comment node-name, next, previous, up -@chapter Accessing An Inferior's Execution Stack -@cindex stack -@cindex FRAME -@cindex {stack frames} - - - -@deftp Type FRAME -This type representing active stack frames in the inferior. -Consider this type opaque. -@end deftp - - -@deftypefun FRAME gdb_get_innermost_frame () -Returns the innermost frame or the frame most recently designated -as current by a call to gdb_set_current_frame.@* -(get_current_frame) -@end deftypefun - - -@deftypefun FRAME gdb_get_caller_frame (FRAME @var{frame}) -Return the frame that called @var{frame}.@* -If @var{frame} is the original frame (it has no caller), return 0.@* -(get_prev_frame) -@end deftypefun - - -@deftypefun FRAME gdb_get_called_frame (FRAME @var{frame}) -Return the frame that @var{frame} calls (0 if @var{frame} is the innermost -frame).@* -(get_next_frame) -@end deftypefun - - -@deftypefun FRAME gdb_parse_frame_specification (char * @var{frame_exp}) -Read a frame specification in whatever the appropriate format is. -Call @code{error}() If the specification is in any way invalid (i.e. -this function never returns NULL).@* -(parse_frame_specification) -@end deftypefun - - -@deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@* -(Example use: Implementing @code{disassemble_command})@* -(get_frame_pc) -@end deftypefun - - -@deftypefun FRAME gdb_selected_frame () -The "selected" stack frame is used by default for local and -arg access. May be @code{NULL}, for no selected frame.@* -(variable selected_frame) -@end deftypefun - - -@deftypefun int gdb_selected_frame_level () -Level of the selected frame:@* -0 for innermost,@* -1 for its caller,@* -or -1 for frame specified by address with no defined level.@* -(variable selected_frame_level) -@end deftypefun - - -@deftypefun void gdb_select_frame (FRAME @var{frame}, int @var{level}) -Select frame @var{frame}, and note that its stack level is @var{level}. -@var{level} may be -1 if an actual level number is not known. -Calls @code{set_language} to establish the correct language for the -selected frame. -@end deftypefun - - - -- IDIOM: Computing Frame Levels@* +@deftypefun void execute_catching_errors (@var{command}) @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++; -@} +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. -@deftypefun void gdb_print_stack_frame (@var{cback}, @var{frame}, @var{level}, @var{source}) +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 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} + +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 -struct gdb_stream_cback * @var{cback}; -FRAME @var{frame}; -int @var{level}; -int @var{source}; +char * @var{name}; +int (*@var{fn}) (void *); +void * @var{fn_arg}; @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) +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. -@deftypefun void gdb_print_backtrace (cback, @var{count}, @var{from_tty}) + +@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 -struct gdb_stream_cback * @var{cback}; -int @var{count}; -int @var{from_tty}; +void (*@var{fn})(void * fn_arg, int (*gdb_poll)()); +void * @var{fn_arg}; @end example -Print briefly all stack frames or just the innermost @var{count} frames.@* -(backtrace_command) +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 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 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 -@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 +@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. -@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 +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 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 +@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. -@deftp Type {struct expression *} -This represents a parsed expression as might be used for a -breakpoint condition. -@end deftp +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}. -@deftp Type {struct block} -Describes a lexical environment. -@end deftp +An application hook is created for a command XYZZY by using +@code{define-command} to create a command called @code{apphook-XYZZY}. -See also `Values' -See also `Examining' +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 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). +The GDB command language contains many @code{set} and @code{show} +commands. These commands are used to modify or examine parameters to +the debugger. -If @var{comma} is nonzero, stop if a comma is reached. -(See `Stack' for information about the selected frame) -@end deftypefun +One difficulty to get the current state 3f a parameter from the +@code{show} command because @code{show} is very verbose. - -@deftypefun gdb_error_t gdb_evaluate_expression (value * @var{value_out}, struct expression * @var{exp}) -Evaluate an expression. See `values' for more information about -the return type.@* -(evaluate_expression) -@end deftypefun - - -@deftypefun value gdb_evaluate_type (struct expression @var{*exp}) -Evaluate an expression, avoiding all memory references -and getting a value whose type alone is correct.@* -(evaluate_type) -@end deftypefun - - - -@node Values, Examining, Expressions, top -@comment node-name, next, previous, up -@chapter Data from the Inferior, the Values of Expressions -@cindex values -@cindex {expression values} - -Values are allocated by functions such as @code{gdb_evaluate_expression}. -All currently allocated values are on the list @code{all_values} and can be -freed by calling @code{gdb_free_all_values}. - -To preserve a value across calls to @code{gdb_free_all_values}, use -@code{gdb_release_value}. Values added to the history list are automaticly -released. To free a released value use @code{gdb_free_value}. - - -@deftypefun void gdb_free_value (value) -Free the memory associated with a released value. -Do not call this function except on values that have been -passed to @code{gdb_release_value}.@* -(gdb_value_free) -@end deftypefun - - -@deftypefun void gdb_free_all_values (void) -Free all allocated values which haven't been released. -This should be called periodically from outside the dynamic -scope of libgdb functions.@* -(free_all_values) -@end deftypefun - - -@deftypefun void gdb_release_value (value @var{val}) -Remove a value from the list @code{all_values} in order to -protect it from @code{gdb_free_all_values}.@* -(release_value) -@end deftypefun - - -There is a `history list' -- a numbered list of values for -future reference. These can be referred to in expressions, -for example. - -@deftypefun int gdb_record_latest_value (value @var{val}) -Add a value to the history list.@* -(record_latest_value) -@end deftypefun - - -@deftypefun value gdb_access_value_history (int @var{index}) -Retrieve a value from the history list.@* -(access_value_history) -@end deftypefun - - -[[[At the moment, the only libgdb use for values is - string formatting (see `Examining'). So, they are treated - as opaque. It'd be useful to expose more of them in the long run.]]] - - -@node Examining, Types, Values, top -@comment node-name, next, previous, up -@chapter Formatting Values as Strings -@cindex examining -@cindex printing -@cindex formatting -@cindex {pretty printing} - - -Many functions in this section use @code{struct gdb_stream_cback}. -That structure is explained in `Basics'. - - -@deftypefun void gdb_print_formatted (struct gdb_stream_cback * @var{cback}, value @var{val}, int @var{format}, int @var{size}) -Print value @var{val} on a stream according to @var{format}, a letter or 0. -Do not end with a newline. -0 means print @var{val} according to its own type. -@var{size} is the letter for the size of datum being printed. -This is used to pad hex numbers so they line up.@* -(print_formatted) -@end deftypefun - - -@deftypefun static void gdb_printf_command (struct gdb_stream_cback * @var{cback}, char * @var{format}, value * @var{values}, int @var{n_values})@* -(printf_command) -@end deftypefun - - -@deftypefun int gdb_value_print (struct gdb_stream_cback * @var{cback}, @var{value}, int @var{format}, enum @var{val_prettyprint}) -Print the value @var{val} in C-ish syntax on @var{stream}. -@var{format} is a format-letter, or 0 for print in natural format of data type. -If the object printed is a string pointer, returns -the number of string bytes printed. -[[[implementation: watch the change in argument order]]]@* -(value_print) -@end deftypefun - - - -- IDIOM: This prints the values of all convenience variables: @example -for (var = internalvars; var; var = var->next) -@{ -printf_filtered ("$%s = ", var->name); -value_print (var->value, stdout, 0, Val_pretty_default); -printf_filtered ("\n"); -@} +(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 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{} 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"); -@} +(gdb) view check type +auto; currently off +(gdb) view width +80 @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) +(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.) -@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 +@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. -@deftypefun char * gdb_register_name (int @var{i}) -Look up a register name by number. -@end deftypefun +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). -@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 +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). -@deftypefun CORE_ADDR gdb_read_pc () -Return the contents of the inferior's program counter. -@end deftypefun +@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 -@deftypefun int gdb_is_stepping () -If true, the inferior is stopped after being stepped. -@end deftypefun +(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_current_breakpoints (gdb_int_cback) -Call a callback for each of the current breakpoints.@* -(program_info) -@end deftypefun - - -@deftypefun int gdb_stop_signal () -Return the signal that stopped the inferior. -@end deftypefun - - -@deftypefun char * strsigno (int) -Return a symbolic name for a signal. -@end deftypefun - - -@deftypefun void gdb_target_info (struct gdb_stream_cback *) -Print status information about target we're accessing.@* -(target_files_info, e.g. child_files_info) -@end deftypefun - - -float_info -[[[what is appropriate?]]] - - -@deftypefun void gdb_address_info (struct gdb_stream_cback * @var{cback}, char * @var{symbol}); -Like the `info address' command -- show where @var{symbol} -is located.@* -(address_info) -@end deftypefun - - -@node Types, top, Examining, top -@comment node-name, next, previous, up -@chapter Examining the Types of an Inferior's Data -@cindex types - - -@deftp Type {struct type} -@code{struct type *} is used to represent a type. For example, that is -the type returned by the macro @code{VALUE_TYPE(val)} which yields the -type of inferior data recorded in @code{val}. (see `evaluate_type' in -`Expressions'). -@end deftp - - -@deftypefun void type_print (@var{type}, @var{varstring}, @var{stream_cback}, @var{show}) @example -struct type @var{*type}; -char @var{*varstring}; -struct gdb_stream_cback * @var{stream_cback}; -FILE @var{*stream}; -int @var{show}; +(gdb) print foo +$16 = @{v = 0x38ae0, v_length = 40@} @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 +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. -[[[In the long run, we need something to programmaticly read off type - structures in a machine/language independent way.]]] +@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 + := + | (exp-concat *) + | (exp-attribute ) + + := ( * ) + + := ( ) +@end example + +The string-concatenation of all of the @code{} (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 + "$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 + +It is undefined how libgdb will indent these lines of output or +where newlines will be included. @bye