1 \input texinfo @c -*-texinfo-*-
3 @setfilename libgdb.info
9 This file documents libgdb, the GNU symbolic debugger in a library.
11 This is Edition 0.3, Oct 1993, of @cite{Libgdb}.
12 Copyright 1993 Cygnus Support
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with no Front-Cover Texts, and no Back-Cover Texts.
20 @c This title page illustrates only one of the
21 @c two methods of forming a title page.
29 @c The following two commands
30 @c start the copyright page.
32 @vskip 0pt plus 1filll
33 Permission is granted to make and distribute verbatim copies of
34 this manual provided the copyright notice and this permission notice
35 are preserved on all copies.
37 Copyright @copyright{} 1993 Cygnus Support
41 @node Top, Overview, (dir), (dir)
43 This info file documents libgdb: an API for GDB, the GNU symbolic debugger.
46 * Overview:: The basics of libgdb and this document.
47 * Interpreter:: Libgdb is an Interpreter-Based Server.
48 * Top Level:: You Provide the Top Level for the Libgdb
50 * I/O:: How the Server's I/O Can be Used.
51 * Invoking:: Invoking the Interpreter, Executing
53 * Defining Commands:: How New Commands are Created.
54 * Variables:: How Builtin Variables are Defined.
55 * Asynchronous:: Scheduling Asynchronous Computations.
56 * Commands:: Debugger Commands for Libgdb Applications
60 @node Overview, Interpreter, top, top
61 @comment node-name, next, previous, up
66 @heading Function and Purpose
68 Libgdb is a package which provides an API to the functionality of GDB,
69 the GNU symbolic debugger. It is specifically intended to support the
70 development of a symbolic debugger with a graphic interface.
73 @heading This Document
75 This document is a specification of the libgdb API. It is written in
76 the form of a programmer's manual. So the goal of this document is to
77 explain what functions make up the API, and how they can be used in a
83 In this document, @dfn{libgdb} refers to a library containing the
84 functions defined herein, @dfn{application} refers to any program built
90 Programs which are linked with libgdb must be linked with libbfd,
91 libopcodes, libiberty, and libmmalloc.
93 @heading Acknowledgments
95 Essential contributions to this design were made by Stu Grossman, Jim
96 Kingdon, and Rich Pixley.
98 @node Interpreter, Top Level, Overview, Top
99 @comment node-name, next, previous, up
100 @chapter Libgdb is an Interpreter Based Server
104 To understand libgdb, it is necessary to understand how the library is
105 structured. Historically, GDB is written as a small interpreter for a
106 simple command language. The commands of the language perform useful
109 Libgdb is built from GDB by turning the interpreter into a debugging
110 server. The server reads debugging commands from any source and
111 interprets them, directing the output arbitrarily.
113 In addition to changing GDB from a tty-based program to a server, a
114 number of new GDB commands have been added to make the server more
115 useful for a program with a graphic interface.
117 Finally, libgdb includes provisions for asynchronous processing within
120 Most operations that can be carried out with libgdb involve the GDB
121 command interpreter. The usual mode of operation is that the operation
122 is expressed as a string of GDB commands, which the interpreter is then
123 invoked to carry out. The output from commands executed in this manner
124 can be redirected in a variety of useful ways for further processing by
127 The command interpreter provides an extensive system of hooks so an
128 application can monitor any aspect of the debugging library's state. An
129 application can set its own breakpoints and attach commands and
130 conditions to those. It is possible to attach hooks to any debugger
131 command; the hooks are invoked whenever that command is about to be
132 invoked. By means of these, the displays of a graphical interface can
133 be kept fully up to date at all times.
135 We show you how to define new primitives in the command language. By
136 defining new primitives and using them in breakpoint scripts and command
137 hooks, an application can schedule the execution of arbitrary C-code at
138 almost any point of interest in the operation of libgdb.
140 We show you how to define new GDB convenience variables for which your
141 code computes a value on demand. Referring to such variables in a
142 breakpoint condition is a convenient way to conditionalize breakpoints
145 To summarize: in libgdb, the gdb command language is turned into a
146 debugging server. The server takes commands as input, and the server's
147 output is redirectable. An application uses libgdb by formatting
148 debugging commands and invoking the interpreter. The application might
149 maintain breakpoints, watchpoints and many kinds of hooks. An application
150 can define new primitives for the interpreter.
152 @node Top Level, I/O, Interpreter, Top
153 @chapter You Provide the Top Level for the Libgdb Command Interpreter
156 When you use libgdb, your code is providing a @dfn{top level} for the
157 command language interpreter. The top level is significant because it
158 provides commands for the the interpreter to execute. In addition, the
159 top level is responsible for handling some kinds of errors, and
160 performing certain cleanup operations on behalf of the interpreter.
162 @heading Initialization
164 Before calling any other libgdb functions, call this:
166 @deftypefun void gdb_init (void)
167 Perform one-time initialization for libgdb.
170 An application may wish to evaluate specific gdb commands as part of its
171 own initialization. The details of how this can be accomplished are
174 @heading The Top-Level Loop
176 There is a strong presumption in libgdb that the application has
177 the form of a loop. Here is what such a loop might look like:
180 while (gdb_still_going ())
182 if (!GDB_TOP_LEVEL ())
185 gdb_start_top_loop ();
186 command = process_events ();
187 gdb_execute_command (command);
188 gdb_finish_top_loop ();
193 The function @code{gdb_still_going} returns 1 until the gdb command
196 The macro @code{GDB_TOP_LEVEL} invokes setjmp to set the top level error
197 handler. When a command results in an error, the interpreter exits with
198 a longjmp. There is nothing special libgdb requires of the top level
199 error handler other than it be present and that it restart the top level
200 loop. Errors are explained in detail in a later chapter.
202 Each time through the top level loop two important things happen: a
203 debugger command is constructed on the basis of user input, and the
204 interpreter is invoked to execute that command. In the sample code, the
205 call to the imaginary function @code{process_events} represents the
206 point at which a graphical interface should read input events until
207 ready to execute a debugger command. The call to
208 @code{gdb_execute_command} invokes the command interpreter (what happens
209 to the output from the command will be explained later).
211 Libgdb manages some resources using the top-level loop. The primary
212 reason for this is error-handling: even if a command terminates with an
213 error, it may already have allocated resources which need to be freed.
214 The freeing of such resources takes place at the top-level, regardless
215 of how the the command exits. The calls to @code{gdb_start_top_loop}
216 and @code{gdb_finish_top_loop} let libgdb know when it is safe to
217 perform operations associated with these resources.
219 @heading Breakpoint Commands
221 Breakpoint commands are scripts of GDB operations associated with
222 particular breakpoints. When a breakpoint is reached, its associated
223 commands are executed.
225 Breakpoint commands are invoked by the libgdb function
226 @code{gdb_finish_top_loop}.
228 Notice that if control returns to the top-level error handler, the
229 execution of breakpoint commands is bypassed. This can happen as a
230 result of errors during either @code{gdb_execute_command} or
231 @code{gdb_finish_top_loop}.
233 @heading Application Initialization
235 Sometimes it is inconvenient to execute commands via a command loop for
236 example, the commands an application uses to initialize itself. An
237 alternative to @code{execute_command} is @code{execute_catching_errors}.
238 When @code{execute_catching_errors} is used, no top level error handler
239 need be in effect, and it is not necessary to call
240 @code{gdb_start_top_loop} or @code{gdb_finish_top_loop}.
245 The debugger command ``quit'' performs all necessary cleanup for libgdb.
246 After it has done so, it changes the return value of
247 @code{gdb_still_going} to 0 and returns to the top level error handler.
250 @node I/O, Invoking, Top Level, Top
251 @comment node-name, next, previous, up
252 @chapter How the Server's I/O Can be Used
255 In the last chapter it was pointed out that a libgdb application is
256 responsible for providing commands for the interpreter to execute.
257 However some commands require further input (for example, the ``quit''
258 command might ask for confirmation). Almost all commands produce output
259 of some kind. The purpose of this section is to explain how libgdb
260 performs its I/O, and how an application can take advantage of
266 Libgdb has no fixed strategy for I/O. Instead, all operations are
267 performed by functions called via structures of function pointers.
268 Applications supply theses structures and can change them at any
271 @deftp Type {struct gdb_input_vector}
272 @deftpx Type {struct gdb_output_vector}
273 These structures contain a set of function pointers. Each function
274 determines how a particular type of i/o is performed. The details of
275 these strucutres are explained below.
277 The application allocates these structures, initializes them to all bits
278 zero, fills in the function pointers, and then registers names for them
282 @deftypefun void gdb_name_input_vector (@var{name}, @var{vec})
283 @deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
284 @deftypefunx void gdb_name_output_vector (@var{name}, @var{vec})
285 @deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
288 struct gdb_output_vector * @var{vec};
290 These functions are used to give and remove names to i/o vectors. Note
291 that if a name is used twice, the most recent definition applies.
298 An output vector is a structure with at least these fields:
301 struct gdb_output_vector
304 void (*put_string) (struct gdb_output_vector *, char * str);
308 Use the function @code{memset} or something equivalent to initialize an
309 output vector to all bits zero. Then fill in the function pointer with
312 A debugger command can produce three kinds of output: error messages
313 (such as when trying to delete a non-existent breakpoint), informational
314 messages (such as the notification printed when a breakpoint is hit),
315 and the output specifically requested by a command (for example, the
316 value printed by the ``print'' command). At any given time, then,
317 libgdb has three output vectors. These are called the @dfn{error},
318 @dfn{info}, @dfn{value} vector respectively.
323 struct gdb_input_vector
325 int (*query) (struct gdb_input_vector *,
328 int * (*selection) (struct gdb_input_vector *,
331 char * (*read_string) (struct gdb_input_vector *,
333 char ** (*read_strings) (struct gdb_input_vector *,
338 Use the function @code{memset} or something equivalent to initialize an
339 input vector to all bits zero. Then fill in the function pointers with
342 There are four kinds of input requests explicitly made by libgdb.
344 A @dfn{query} is a yes or no question. The user can respond to a query
345 with an affirmative or negative answer, or by telling gdb to abort the
346 command (in some cases an abort is not permitted). Query should return
347 'y' or 'n' or 0 to abort.
349 A @dfn{selection} is a list of options from which the user selects a subset.
350 Selections should return a NULL terminated array of integers, which are
351 indexes into the array of choices. It can return NULL instead to abort
352 the command. The array returned by this function will be passed to
353 @code{free} by libgdb.
355 A @dfn{read_string} asks the user to supply an arbitrary string. It may
356 return NULL to abort the command. The string returned by @code{read_string}
357 should be allocated by @code{malloc}; it will be freed by libgdb.
359 A @dfn{read_strings} asks the user to supply multiple lines of input
360 (for example, the body of a command created using `define'). It, too,
361 may return NULL to abort. The array and the strings returned by this
362 function will be freed by libgdb.
364 @heading I/O Redirection from the Application Top-Level
366 @deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *)
371 struct gdb_input_vector * input;
372 struct gdb_output_vector * error;
373 struct gdb_output_vector * info;
374 struct gdb_output_vector * value;
378 This establishes a new set of i/o vectors, and returns the old setting.
379 Any of the pointers in this structure may be NULL, indicating that the
380 current value should be used.
382 This function is useful for setting up i/o vectors before any libgdb
383 commands have been invoked (hence before any input or output has taken
387 It is explained in a later chapter how to redirect output temporarily.
390 @heading I/O Redirection in Debugger Commands
392 A libgdb application creates input and output vectors and assigns them names.
393 Which input and output vectors are used by libgdb is established by
394 executing these debugger commands:
396 @defun {set input-vector} name
397 @defunx {set error-output-vector} name
398 @defunx {set info-output-vector} name
399 @defunx {set value-output-vector} name
400 Choose an I/O vector by name.
404 A few debugger commands are for use only within commands defined using
405 the debugger command `define' (they have no effect at other times).
406 These commands exist so that an application can maintain hooks which
407 redirect output without affecting the global I/O vectors.
409 @defun with-input-vector name
410 @defunx with-error-output-vector name
411 @defunx with-info-output-vector name
412 @defunx with-value-output-vector name
413 Set an I/O vector, but only temporarily. The setting has effect only
414 within the command definition in which it occurs.
418 @heading Initial Conditions
420 When libgdb is initialized, a set of default I/O vectors is put in
421 place. The default vectors are called @code{default-input-vector},
422 @code{default-output-vector}, &c.
424 The default query function always returns `y'. Other input functions
425 always abort. The default output functions discard output silently.
428 @node Invoking, Defining Commands, I/O, Top
429 @chapter Invoking the Interpreter, Executing Commands
430 @cindex {executing commands}
431 @cindex {invoking the interpreter}
433 This section introduces the libgdb functions which invoke the command
436 @deftypefun void gdb_execute_command (@var{command})
438 char * @var{command};
440 Interpret the argument debugger command. An error handler must be set
441 when this function is called. (@xref{Top Level}.)
444 It is possible to override the current I/O vectors for the duration of a
447 @deftypefun void gdb_execute_with_io (@var{command}, @var{vecs})
449 char * @var{command};
450 struct gdb_io_vecs * @var{vecs};
454 struct gdb_input_vector * input;
455 struct gdb_output_vector * error;
456 struct gdb_output_vector * info;
457 struct gdb_output_vector * value;
461 Execute @var{command}, temporarily using the i/o vectors in @var{vecs}.
463 Any of the vectors may be NULL, indicating that the current value should
464 be used. An error handler must be in place when this function is used.
467 @deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd})
471 @deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input})
474 struct gdb_input_vector * input;
478 struct gdb_str_output
486 Execute @var{cmd}, collecting its output as strings. If no error
487 occurs, all three strings will be present in the structure, the
488 empty-string rather than NULL standing for no output of a particular
491 If the command aborts with an error, then the @code{value} field will be
492 NULL, though the other two strings will be present.
494 In all cases, the strings returned are allocated by malloc and should be
497 The first form listed uses the current input vector, but overrides the
498 current output vector. The second form additionally allows the input
499 vector to be overridden.
501 This function does not require that an error handler be installed.
504 @deftypefun void execute_catching_errors (@var{command})
506 char * @var{command};
508 Like @code{execute_command} except that no error handler is required.
511 @deftypefun void execute_with_text (@var{command}, @var{text})
513 char * @var{command};
516 Like @code{execute_catching_errors}, except that the input vector is
517 overridden. The new input vector handles only calls to @code{query} (by
518 returning 'y') and calls to @code{read_strings} by returning a copy of
519 @var{text} and the strings it points to.
521 This form of execute_command is useful for commands like @code{define},
522 @code{document}, and @code{commands}.
527 @node Defining Commands, Variables, Invoking, Top
528 @comment node-name, next, previous, up
529 @chapter How New Commands are Created
530 @cindex {commands, defining}
532 Applications are, of course, free to take advantage of the existing GDB
533 macro definition capability (the @code{define} and @code{document}
536 In addition, an application can add new primitives to the GDB command
539 @deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc})
545 typedef void (*gdb_cmd_fn) (char * args);
548 Create a new command call @var{name}. The new command is in the
549 @code{application} help class. When invoked, the command-line arguments
550 to the command are passed as a single string.
552 Calling this function twice with the same name replaces an earlier
553 definition, but application commands can not replace builtin commands of
556 The documentation string of the command is set to a copy the string
560 @node Variables, Asynchronous, Defining Commands, Top
561 @comment node-name, next, previous, up
562 @chapter How Builtin Variables are Defined
563 @cindex {variables, defining}
565 Convenience variables provide a way for values maintained by libgdb to
566 be referenced in expressions (e.g. @code{$bpnum}). Libgdb includes a
567 means by which the application can define new, integer valued
568 convenience variables:
570 @deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg})
573 int (*@var{fn}) (void *);
576 This function defines (or undefines) a convenience variable called @var{name}.
577 If @var{fn} is NULL, the variable becomes undefined. Otherwise,
578 @var{fn} is a function which, when passed @var{fn_arg} returns the value
579 of the newly defined variable.
581 No libgdb functions should be called by @var{fn}.
584 One use for this function is to create breakpoint conditions computed in
585 novel ways. This is done by defining a convenience variable and
586 referring to that variable in a breakpoint condition expression.
589 @node Asynchronous, Commands, Variables, Top
590 @chapter Scheduling Asynchronous Computations
594 A running libgdb function can take a long time. Libgdb includes a hook
595 so that an application can run intermittently during long debugger
598 @deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg})
600 void (*@var{fn})(void * fn_arg, int (*gdb_poll)());
603 Arrange to call @var{fn} periodically during lengthy debugger operations.
604 If @var{fn} is NULL, polling is turned off. @var{fn} should take two
605 arguments: an opaque pointer passed as @var{fn_arg} to
606 @code{gdb_set_poll_fn}, and a function pointer. The function pointer
607 passed to @var{fn} is provided by libgdb and points to a function that
608 returns 0 when the poll function should return. That is, when
609 @code{(*gdb_poll)()} returns 0, libgdb is ready to continue @var{fn}
610 should return quickly.
612 It is possible that @code{(*gdb_poll)()} will return 0 the first time it
613 is called, so it is reasonable for an application to do minimal processing
614 before checking whether to return.
616 No libgdb functions should be called from an application's poll function,
617 with one exception: @code{gdb_request_quit}.
621 @deftypefun void gdb_request_quit (void)
622 This function, if called from a poll function, requests that the
623 currently executing libgdb command be interrupted as soon as possible,
624 and that control be returned to the top-level via an error.
626 The quit is not immediate. It will not occur until at least after the
627 application's poll function returns.
630 @node Commands, Top, Asynchronous, Top
631 @comment node-name, next, previous, up
632 @chapter Debugger Commands for Libgdb Applications
634 The debugger commands available to libgdb applications are the same commands
635 available interactively via GDB. This section is an overview of the
636 commands newly created as part of libgdb.
638 This section is not by any means a complete reference to the GDB command
639 language. See the GDB manual for such a reference.
642 * Command Hooks:: Setting Hooks to Execute With Debugger Commands.
643 * View Commands:: View Commands Mirror Show Commands
644 * Breakpoints:: The Application Can Have Its Own Breakpoints
647 @node Command Hooks, View Commands, Commands, Commands
648 @comment node-name, next, previous, up
649 @section Setting Hooks to Execute With Debugger Commands.
651 Debugger commands support hooks. A command hook is executed just before
652 the interpreter invokes the hooked command.
654 There are two hooks allowed for every command. By convention, one hook
655 is for use by users, the other is for use by the application.
657 A user hook is created for a command XYZZY by using
658 @code{define-command} to create a command called @code{hook-XYZZY}.
660 An application hook is created for a command XYZZY by using
661 @code{define-command} to create a command called @code{apphook-XYZZY}.
663 Application hooks are useful for interfaces which wish to continuously
664 monitor certain aspects of debugger state. The application can set a
665 hook on all commands that might modify the watched state. When the hook
666 is executed, it can use i/o redirection to notify parts of the
667 application that previous data may be out of date. After the top-level loop
668 resumes, the application can recompute any values that may have changed.
671 @node View Commands, Breakpoints, Command Hooks, Commands
672 @comment node-name, next, previous, up
673 @section View Commands Mirror Show Commands
675 The GDB command language contains many @code{set} and @code{show}
676 commands. These commands are used to modify or examine parameters to
679 It is difficult to get the current state of a parameter from the
680 @code{show} command because @code{show} is very verbose.
683 (gdb) show check type
684 Type checking is "auto; currently off".
686 Number of characters gdb thinks are in a line is 80.
689 For every @code{show} command, libgdb includes a @code{view} command.
690 @code{view} is like @code{show} without the verbose commentary:
693 (gdb) view check type
699 (The precise format of the ouput from @code{view} is subject to change.
700 In particular, @code{view} may one-day print values which can be used as
701 arguments to the corresponding @code{set} command.)
703 @node Breakpoints, Structured Output, View Commands, Commands
704 @comment node-name, next, previous, up
705 @section The Application Can Have Its Own Breakpoints
707 The GDB breakpoint commands were written with a strong presumption that
708 all breakpoints are managed by a human user. Therefore, the command
709 language contains commands like `delete' which affect all breakpoints
710 without discrimination.
712 In libgdb, there is added support for breakpoints and watchpoints which
713 are set by the application and which should not be affected by ordinary,
714 indiscriminate commands. These are called @dfn{protected} breakpoints.
716 @deffn {Debugger Command} break-protected ...
717 @deffnx {Debugger Command} watch-protected ...
718 These work like @code{break} and @code{watch} except that the resulting
719 breakpoint is given a negative number. Negative numbered breakpoints do
720 not appear in the output of @code{info breakpoints} but do in that of
721 @code{info all-breakpoints}. Negative numbered breakpoints are not
722 affected by commands which ordinarily affect `all' breakpoints (e.g.
723 @code{delete} with no arguments).
725 Note that libgdb itself creates protected breakpoints, so programs
726 should not rely on being able to allocate particular protected
727 breakpoint numbers for themselves.
730 More than one breakpoint may be set at a given location. Libgdb adds
731 the concept of @dfn{priority} to breakpoints. A priority is an integer,
732 assigned to each breakpoint. When a breakpoint is reached, the
733 conditions of all breakpoints at the same location are evaluated in
734 order of ascending priority. When breakpoint commands are executed,
735 they are also executed in ascending priority (until all have been
736 executed, an error occurs, or one set of commands continues the
739 @deffn {Debugger Command} priority n bplist
740 Set the priority for breakpoints @var{bplist} to @var{n}.
741 By default, breakpoints are assigned a priority of zero.
744 @node Structured Output, Commands, Breakpoints, Commands
745 @comment node-name, next, previous, up
746 @section Structured Output, The @code{Explain} Command
748 (This section may be subject to considerable revision.)
750 When GDB prints a the value of an expression, the printed representation
751 contains information that can be usefully fed back into future commands
752 and expressions. For example,
756 $16 = @{v = 0x38ae0, v_length = 40@}
759 On the basis of this output, a user knows, for example, that
760 @code{$16.v} refers to a pointer valued @code{0x38ae0}
762 A new output command helps to make information like this available to
765 @deffn {Debugger Command} explain expression
766 @deffnx {Debugger Command} explain /format expression
767 Print the value of @var{expression} in the manner of the @code{print}
768 command, but embed that output in a list syntax containing information
769 about the structure of the output.
772 As an example, @code{explain argv} might produce this output:
779 (deref-expression "*$19"))
783 The syntax of output from @code{explain} is:
786 <explanation> := <quoted-string>
787 | (exp-concat <explanation> <explanation>*)
788 | (exp-attribute <property-list> <explanation>)
790 <property-list> := ( <property-pair>* )
792 <property-pair> := ( <property-name> <quoted-string> )
795 The string-concatenation of all of the @code{<quoted-string>} (except
796 those in property lists) yields the output generated by the equivalent
797 @code{print} command. Quoted strings may contain quotes and backslashes
798 if they are escaped by backslash. "\n" in a quoted string stands for
799 newline; unescaped newlines do not occur within the strings output by
802 Property names are made up of alphabetic characters, dashes, and
805 The set of properties is open-ended. As GDB acquires support for new
806 source languages and other new capabilities, new property types may be
807 added to the output of this command. Future commands may offer
808 applications some selectivity concerning which properties are reported.
810 The initial set of properties defined includes:
813 @item @code{expression}
815 This is an expression, such as @code{$42} or @code{$42.x}. The
816 expression can be used to refer to the value printed in the attributed
821 This is a user-readable name for the type of the attributed value.
825 If the value is stored in a target register, this is a register number.
826 If the value is stored in a GDB convenience variable, this is an integer
827 that is unique among all the convenience variables. Otherwise, this is
828 the address in the target where the value is stored.
830 @item @code{deref-expression}
832 If the attributed value is a pointer type, this is an expression that
833 refers to the dereferenced value.
836 Here is a larger example, using the same object passed to @code{print}
837 in an earlier example of this section.
843 (type "struct bytecode_vector")
848 ( (expression "$16.v")
851 (deref-expression "*$16.v") )
854 ( (expression "$16.v_length")
861 It is undefined how libgdb will indent these lines of output or
862 where newlines will be included.