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