Commit | Line | Data |
---|---|---|
c906108c SS |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename libgdb.info | |
4 | @settitle Libgdb | |
5 | @setchapternewpage off | |
6 | @c %**end of header | |
7 | ||
8 | @ifinfo | |
9 | This file documents libgdb, the GNU symbolic debugger in a library. | |
10 | ||
11 | This is Edition 0.3, Oct 1993, of @cite{Libgdb}. | |
12 | Copyright 1993 Cygnus Support | |
13 | ||
2a6585f0 EZ |
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. | |
c906108c SS |
18 | @end ifinfo |
19 | ||
20 | @c This title page illustrates only one of the | |
21 | @c two methods of forming a title page. | |
22 | ||
23 | @titlepage | |
24 | @title Libgdb | |
25 | @subtitle Version 0.3 | |
26 | @subtitle Oct 1993 | |
27 | @author Thomas Lord | |
28 | ||
29 | @c The following two commands | |
30 | @c start the copyright page. | |
31 | @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. | |
36 | ||
37 | Copyright @copyright{} 1993 Cygnus Support | |
38 | @end titlepage | |
39 | ||
40 | @ifinfo | |
41 | @node Top, Overview, (dir), (dir) | |
42 | ||
43 | This info file documents libgdb: an API for GDB, the GNU symbolic debugger. | |
44 | ||
45 | @menu | |
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 | |
49 | Command Interpreter . | |
50 | * I/O:: How the Server's I/O Can be Used. | |
51 | * Invoking:: Invoking the Interpreter, Executing | |
52 | Commands. | |
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 | |
57 | @end menu | |
58 | ||
59 | @end ifinfo | |
60 | @node Overview, Interpreter, top, top | |
61 | @comment node-name, next, previous, up | |
62 | @chapter Overview | |
63 | @cindex overview | |
64 | @cindex definitions | |
65 | ||
66 | @heading Function and Purpose | |
67 | ||
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. | |
71 | ||
72 | ||
73 | @heading This Document | |
74 | ||
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 | |
78 | running application. | |
79 | ||
80 | ||
81 | @heading Terminology | |
82 | ||
83 | In this document, @dfn{libgdb} refers to a library containing the | |
84 | functions defined herein, @dfn{application} refers to any program built | |
85 | with that library. | |
86 | ||
87 | ||
88 | @heading Dependencies | |
89 | ||
90 | Programs which are linked with libgdb must be linked with libbfd, | |
91 | libopcodes, libiberty, and libmmalloc. | |
92 | ||
93 | @heading Acknowledgments | |
94 | ||
95 | Essential contributions to this design were made by Stu Grossman, Jim | |
96 | Kingdon, and Rich Pixley. | |
97 | ||
98 | @node Interpreter, Top Level, Overview, Top | |
99 | @comment node-name, next, previous, up | |
100 | @chapter Libgdb is an Interpreter Based Server | |
101 | @cindex interpreter | |
102 | @cindex server | |
103 | ||
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 | |
107 | debugging functions. | |
108 | ||
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. | |
112 | ||
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. | |
116 | ||
117 | Finally, libgdb includes provisions for asynchronous processing within | |
118 | the application. | |
119 | ||
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 | |
125 | the application. | |
126 | ||
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. | |
134 | ||
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. | |
139 | ||
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 | |
143 | in novel ways. | |
144 | ||
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. | |
151 | ||
152 | @node Top Level, I/O, Interpreter, Top | |
153 | @chapter You Provide the Top Level for the Libgdb Command Interpreter | |
154 | @cindex {top level} | |
155 | ||
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. | |
161 | ||
162 | @heading Initialization | |
163 | ||
164 | Before calling any other libgdb functions, call this: | |
165 | ||
166 | @deftypefun void gdb_init (void) | |
167 | Perform one-time initialization for libgdb. | |
168 | @end deftypefun | |
169 | ||
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 | |
172 | explained below. | |
173 | ||
174 | @heading The Top-Level Loop | |
175 | ||
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: | |
178 | ||
179 | @example | |
180 | while (gdb_still_going ()) | |
181 | @{ | |
182 | if (!GDB_TOP_LEVEL ()) | |
183 | @{ | |
184 | char * command; | |
185 | gdb_start_top_loop (); | |
186 | command = process_events (); | |
187 | gdb_execute_command (command); | |
188 | gdb_finish_top_loop (); | |
189 | @} | |
190 | @} | |
191 | @end example | |
192 | ||
193 | The function @code{gdb_still_going} returns 1 until the gdb command | |
194 | `quit' is run. | |
195 | ||
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. | |
201 | ||
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). | |
210 | ||
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. | |
218 | ||
219 | @heading Breakpoint Commands | |
220 | ||
221 | Breakpoint commands are scripts of GDB operations associated with | |
222 | particular breakpoints. When a breakpoint is reached, its associated | |
223 | commands are executed. | |
224 | ||
225 | Breakpoint commands are invoked by the libgdb function | |
226 | @code{gdb_finish_top_loop}. | |
227 | ||
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}. | |
232 | ||
233 | @heading Application Initialization | |
234 | ||
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}. | |
241 | ||
242 | ||
243 | @heading Cleanup | |
244 | ||
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. | |
248 | ||
249 | ||
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 | |
253 | @cindex I/O | |
254 | ||
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 | |
261 | this. | |
262 | ||
263 | ||
264 | @heading I/O Vectors | |
265 | ||
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 | |
269 | time. | |
270 | ||
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. | |
276 | ||
277 | The application allocates these structures, initializes them to all bits | |
278 | zero, fills in the function pointers, and then registers names for them | |
279 | them with libgdb. | |
280 | @end deftp | |
281 | ||
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}) | |
286 | @example | |
287 | char * @var{name}; | |
288 | struct gdb_output_vector * @var{vec}; | |
289 | @end example | |
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. | |
292 | @end deftypefun | |
293 | ||
294 | ||
295 | ||
296 | @subheading Output | |
297 | ||
298 | An output vector is a structure with at least these fields: | |
299 | ||
300 | @example | |
301 | struct gdb_output_vector | |
302 | @{ | |
303 | /* output */ | |
304 | void (*put_string) (struct gdb_output_vector *, char * str); | |
305 | @} | |
306 | @end example | |
307 | ||
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 | |
310 | your function. | |
311 | ||
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. | |
319 | ||
320 | @subheading Input | |
321 | ||
322 | @example | |
323 | struct gdb_input_vector | |
324 | @{ | |
325 | int (*query) (struct gdb_input_vector *, | |
326 | char * prompt, | |
327 | int quit_allowed); | |
328 | int * (*selection) (struct gdb_input_vector *, | |
329 | char * prompt, | |
330 | char ** choices); | |
331 | char * (*read_string) (struct gdb_input_vector *, | |
332 | char * prompt); | |
333 | char ** (*read_strings) (struct gdb_input_vector *, | |
334 | char * prompt); | |
335 | @} | |
336 | @end example | |
337 | ||
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 | |
340 | your functions. | |
341 | ||
342 | There are four kinds of input requests explicitly made by libgdb. | |
343 | ||
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. | |
348 | ||
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. | |
354 | ||
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. | |
358 | ||
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. | |
363 | ||
364 | @heading I/O Redirection from the Application Top-Level | |
365 | ||
366 | @deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *) | |
367 | @example | |
368 | ||
369 | struct gdb_io_vecs | |
370 | @{ | |
371 | struct gdb_input_vector * input; | |
372 | struct gdb_output_vector * error; | |
373 | struct gdb_output_vector * info; | |
374 | struct gdb_output_vector * value; | |
375 | @} | |
376 | @end example | |
377 | ||
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. | |
381 | ||
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 | |
384 | place). | |
385 | @end deftypefun | |
386 | ||
387 | It is explained in a later chapter how to redirect output temporarily. | |
388 | (@xref{Invoking}.) | |
389 | ||
390 | @heading I/O Redirection in Debugger Commands | |
391 | ||
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: | |
395 | ||
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. | |
401 | @end defun | |
402 | ||
403 | ||
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. | |
408 | ||
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. | |
415 | @end defun | |
416 | ||
417 | ||
418 | @heading Initial Conditions | |
419 | ||
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. | |
423 | ||
424 | The default query function always returns `y'. Other input functions | |
425 | always abort. The default output functions discard output silently. | |
426 | ||
427 | ||
428 | @node Invoking, Defining Commands, I/O, Top | |
429 | @chapter Invoking the Interpreter, Executing Commands | |
430 | @cindex {executing commands} | |
431 | @cindex {invoking the interpreter} | |
432 | ||
433 | This section introduces the libgdb functions which invoke the command | |
434 | interpreter. | |
435 | ||
436 | @deftypefun void gdb_execute_command (@var{command}) | |
437 | @example | |
438 | char * @var{command}; | |
439 | @end example | |
440 | Interpret the argument debugger command. An error handler must be set | |
441 | when this function is called. (@xref{Top Level}.) | |
442 | @end deftypefun | |
443 | ||
444 | It is possible to override the current I/O vectors for the duration of a | |
445 | single command: | |
446 | ||
447 | @deftypefun void gdb_execute_with_io (@var{command}, @var{vecs}) | |
448 | @example | |
449 | char * @var{command}; | |
450 | struct gdb_io_vecs * @var{vecs}; | |
451 | ||
452 | struct gdb_io_vecs | |
453 | @{ | |
454 | struct gdb_input_vector * input; | |
455 | struct gdb_output_vector * error; | |
456 | struct gdb_output_vector * info; | |
457 | struct gdb_output_vector * value; | |
458 | @} | |
459 | @end example | |
460 | ||
461 | Execute @var{command}, temporarily using the i/o vectors in @var{vecs}. | |
462 | ||
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. | |
465 | @end deftypefun | |
466 | ||
467 | @deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd}) | |
468 | @example | |
469 | char * cmd; | |
470 | @end example | |
471 | @deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input}) | |
472 | @example | |
473 | char * cmd; | |
474 | struct gdb_input_vector * input; | |
475 | @end example | |
476 | @page | |
477 | @example | |
478 | struct gdb_str_output | |
479 | @{ | |
480 | char * error; | |
481 | char * info; | |
482 | char * value; | |
483 | @}; | |
484 | @end example | |
485 | ||
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 | |
489 | kind. | |
490 | ||
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. | |
493 | ||
494 | In all cases, the strings returned are allocated by malloc and should be | |
495 | freed by the caller. | |
496 | ||
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. | |
500 | ||
501 | This function does not require that an error handler be installed. | |
502 | @end deftypefun | |
503 | ||
504 | @deftypefun void execute_catching_errors (@var{command}) | |
505 | @example | |
506 | char * @var{command}; | |
507 | @end example | |
508 | Like @code{execute_command} except that no error handler is required. | |
509 | @end deftypefun | |
510 | ||
511 | @deftypefun void execute_with_text (@var{command}, @var{text}) | |
512 | @example | |
513 | char * @var{command}; | |
514 | char ** @var{text}; | |
515 | @end example | |
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. | |
520 | ||
521 | This form of execute_command is useful for commands like @code{define}, | |
522 | @code{document}, and @code{commands}. | |
523 | @end deftypefun | |
524 | ||
525 | ||
526 | ||
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} | |
531 | ||
532 | Applications are, of course, free to take advantage of the existing GDB | |
533 | macro definition capability (the @code{define} and @code{document} | |
534 | functions). | |
535 | ||
536 | In addition, an application can add new primitives to the GDB command | |
537 | language. | |
538 | ||
539 | @deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc}) | |
540 | @example | |
541 | char * @var{name}; | |
542 | gdb_cmd_fn @var{fn}; | |
543 | char * @var{doc}; | |
544 | ||
545 | typedef void (*gdb_cmd_fn) (char * args); | |
546 | @end example | |
547 | ||
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. | |
551 | ||
552 | Calling this function twice with the same name replaces an earlier | |
553 | definition, but application commands can not replace builtin commands of | |
554 | the same name. | |
555 | ||
556 | The documentation string of the command is set to a copy the string | |
557 | @var{doc}. | |
558 | @end deftypefun | |
559 | ||
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} | |
564 | ||
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: | |
569 | @page | |
570 | @deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg}) | |
571 | @example | |
572 | char * @var{name}; | |
573 | int (*@var{fn}) (void *); | |
574 | void * @var{fn_arg}; | |
575 | @end example | |
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. | |
580 | ||
581 | No libgdb functions should be called by @var{fn}. | |
582 | @end deftypefun | |
583 | ||
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. | |
587 | ||
588 | ||
589 | @node Asynchronous, Commands, Variables, Top | |
590 | @chapter Scheduling Asynchronous Computations | |
591 | @cindex asynchronous | |
592 | ||
593 | ||
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 | |
596 | operations. | |
597 | ||
598 | @deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg}) | |
599 | @example | |
600 | void (*@var{fn})(void * fn_arg, int (*gdb_poll)()); | |
601 | void * @var{fn_arg}; | |
602 | @end example | |
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. | |
611 | ||
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. | |
615 | ||
616 | No libgdb functions should be called from an application's poll function, | |
617 | with one exception: @code{gdb_request_quit}. | |
618 | @end deftypefun | |
619 | ||
620 | ||
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. | |
625 | ||
626 | The quit is not immediate. It will not occur until at least after the | |
627 | application's poll function returns. | |
628 | @end deftypefun | |
629 | ||
630 | @node Commands, Top, Asynchronous, Top | |
631 | @comment node-name, next, previous, up | |
632 | @chapter Debugger Commands for Libgdb Applications | |
633 | ||
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. | |
637 | ||
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. | |
640 | ||
641 | @menu | |
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 | |
645 | @end menu | |
646 | ||
647 | @node Command Hooks, View Commands, Commands, Commands | |
648 | @comment node-name, next, previous, up | |
649 | @section Setting Hooks to Execute With Debugger Commands. | |
650 | ||
651 | Debugger commands support hooks. A command hook is executed just before | |
652 | the interpreter invokes the hooked command. | |
653 | ||
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. | |
656 | ||
657 | A user hook is created for a command XYZZY by using | |
658 | @code{define-command} to create a command called @code{hook-XYZZY}. | |
659 | ||
660 | An application hook is created for a command XYZZY by using | |
661 | @code{define-command} to create a command called @code{apphook-XYZZY}. | |
662 | ||
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. | |
669 | (@xref{I/O}.) | |
670 | ||
671 | @node View Commands, Breakpoints, Command Hooks, Commands | |
672 | @comment node-name, next, previous, up | |
673 | @section View Commands Mirror Show Commands | |
674 | ||
675 | The GDB command language contains many @code{set} and @code{show} | |
676 | commands. These commands are used to modify or examine parameters to | |
677 | the debugger. | |
678 | ||
679 | It is difficult to get the current state of a parameter from the | |
680 | @code{show} command because @code{show} is very verbose. | |
681 | ||
682 | @example | |
683 | (gdb) show check type | |
684 | Type checking is "auto; currently off". | |
685 | (gdb) show width | |
686 | Number of characters gdb thinks are in a line is 80. | |
687 | @end example | |
688 | ||
689 | For every @code{show} command, libgdb includes a @code{view} command. | |
690 | @code{view} is like @code{show} without the verbose commentary: | |
691 | ||
692 | @example | |
693 | (gdb) view check type | |
694 | auto; currently off | |
695 | (gdb) view width | |
696 | 80 | |
697 | @end example | |
698 | ||
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.) | |
702 | ||
703 | @node Breakpoints, Structured Output, View Commands, Commands | |
704 | @comment node-name, next, previous, up | |
705 | @section The Application Can Have Its Own Breakpoints | |
706 | ||
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. | |
711 | ||
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. | |
715 | ||
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). | |
724 | ||
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. | |
728 | @end deffn | |
729 | ||
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 | |
737 | target). | |
738 | ||
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. | |
742 | @end deffn | |
743 | ||
744 | @node Structured Output, Commands, Breakpoints, Commands | |
745 | @comment node-name, next, previous, up | |
746 | @section Structured Output, The @code{Explain} Command | |
747 | ||
748 | (This section may be subject to considerable revision.) | |
749 | ||
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, | |
753 | ||
754 | @example | |
755 | (gdb) print foo | |
756 | $16 = @{v = 0x38ae0, v_length = 40@} | |
757 | @end example | |
758 | ||
759 | On the basis of this output, a user knows, for example, that | |
760 | @code{$16.v} refers to a pointer valued @code{0x38ae0} | |
761 | ||
762 | A new output command helps to make information like this available to | |
763 | the application. | |
764 | ||
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. | |
770 | @end deffn | |
771 | ||
772 | As an example, @code{explain argv} might produce this output: | |
773 | ||
774 | @example | |
775 | (exp-attribute | |
776 | ((expression "$19") | |
777 | (type "char **") | |
778 | (address "48560") | |
779 | (deref-expression "*$19")) | |
780 | "$19 = 0x3800\n") | |
781 | @end example | |
782 | ||
783 | The syntax of output from @code{explain} is: | |
784 | ||
785 | @example | |
786 | <explanation> := <quoted-string> | |
787 | | (exp-concat <explanation> <explanation>*) | |
788 | | (exp-attribute <property-list> <explanation>) | |
789 | ||
790 | <property-list> := ( <property-pair>* ) | |
791 | ||
792 | <property-pair> := ( <property-name> <quoted-string> ) | |
793 | @end example | |
794 | ||
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 | |
800 | @code{explain}. | |
801 | ||
802 | Property names are made up of alphabetic characters, dashes, and | |
803 | underscores. | |
804 | ||
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. | |
809 | ||
810 | The initial set of properties defined includes: | |
811 | ||
812 | @itemize @bullet | |
813 | @item @code{expression} | |
814 | ||
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 | |
817 | part of the string. | |
818 | ||
819 | @item @code{type} | |
820 | ||
821 | This is a user-readable name for the type of the attributed value. | |
822 | ||
823 | @item @code{address} | |
824 | ||
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. | |
829 | ||
830 | @item @code{deref-expression} | |
831 | ||
832 | If the attributed value is a pointer type, this is an expression that | |
833 | refers to the dereferenced value. | |
834 | @end itemize | |
835 | ||
836 | Here is a larger example, using the same object passed to @code{print} | |
837 | in an earlier example of this section. | |
838 | ||
839 | @example | |
840 | (gdb) explain foo | |
841 | (exp-attribute | |
842 | ( (expression "$16") | |
843 | (type "struct bytecode_vector") | |
844 | (address 14336) ) | |
845 | (exp-concat | |
846 | "$16 = @{" | |
847 | (exp-attribute | |
848 | ( (expression "$16.v") | |
849 | (type "char *") | |
850 | (address 14336) | |
851 | (deref-expression "*$16.v") ) | |
852 | "v = 0x38ae0") | |
853 | (exp-attribute | |
854 | ( (expression "$16.v_length") | |
855 | (type "int") | |
856 | (address 14340) ) | |
857 | ", v_length = 40") | |
858 | "@}\n")) | |
859 | @end example | |
860 | ||
861 | It is undefined how libgdb will indent these lines of output or | |
862 | where newlines will be included. | |
863 | ||
864 | @bye |