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