| \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 |