Commit | Line | Data |
---|---|---|
1113279c TL |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename libgdb.info | |
4 | @settitle Libgdb | |
b94e8c39 | 5 | @setchapternewpage off |
1113279c TL |
6 | @c %**end of header |
7 | ||
8 | @ifinfo | |
b94e8c39 | 9 | This file documents libgdb, the GNU symbolic debugger in a library. |
1113279c | 10 | |
b94e8c39 | 11 | This is Edition 0.3, Oct 1993, of @cite{Libgdb}. |
1113279c TL |
12 | Copyright 1993 Cygnus Support |
13 | ||
b94e8c39 TL |
14 | Permission is granted to make and distribute verbatim copies of |
15 | this manual provided the copyright notice and this permission notice | |
16 | are preserved on all copies. | |
17 | ||
18 | @ignore | |
19 | Permission is granted to process this file through TeX and print the | |
20 | results, provided the printed document carries copying permission | |
21 | notice identical to this one except for the removal of this paragraph | |
22 | (this paragraph not being relevant to the printed manual). | |
23 | ||
24 | @end ignore | |
25 | Permission is granted to copy and distribute modified versions of this | |
26 | manual under the conditions for verbatim copying, provided also that the | |
27 | entire resulting derived work is distributed under the terms of a | |
28 | permission notice identical to this one. | |
29 | ||
30 | Permission is granted to copy and distribute translations of this manual | |
31 | into another language, under the above conditions for modified versions. | |
1113279c TL |
32 | @end ifinfo |
33 | ||
34 | @c This title page illustrates only one of the | |
35 | @c two methods of forming a title page. | |
36 | ||
37 | @titlepage | |
38 | @title Libgdb | |
b94e8c39 TL |
39 | @subtitle Version 0.3 |
40 | @subtitle Oct 1993 | |
1113279c TL |
41 | @author Thomas Lord |
42 | ||
43 | @c The following two commands | |
44 | @c start the copyright page. | |
45 | @page | |
46 | @vskip 0pt plus 1filll | |
b94e8c39 TL |
47 | Permission is granted to make and distribute verbatim copies of |
48 | this manual provided the copyright notice and this permission notice | |
49 | are preserved on all copies. | |
1113279c | 50 | |
b94e8c39 | 51 | Copyright @copyright{} 1993 Cygnus Support |
1113279c TL |
52 | @end titlepage |
53 | ||
1113279c | 54 | @ifinfo |
b94e8c39 | 55 | @node Top, Overview, (dir), (dir) |
1113279c | 56 | |
b94e8c39 | 57 | This info file documents libgdb: an API for GDB, the GNU symbolic debugger. |
1113279c TL |
58 | |
59 | @menu | |
b94e8c39 TL |
60 | * Overview:: The basics of libgdb and this document. |
61 | * Interpreter:: Libgdb is an Interpreter-Based Server. | |
62 | * Top Level:: You Provide the Top Level for the Libgdb | |
63 | Command Interpreter . | |
64 | * I/O:: How the Server's I/O Can be Used. | |
65 | * Invoking:: Invoking the Interpreter, Executing | |
66 | Commands. | |
67 | * Defining Commands:: How New Commands are Created. | |
68 | * Variables:: How Builtin Variables are Defined. | |
69 | * Asynchronous:: Scheduling Asynchronous Computations. | |
70 | * Commands:: Debugger Commands for Libgdb Applications | |
1113279c TL |
71 | @end menu |
72 | ||
b94e8c39 TL |
73 | @end ifinfo |
74 | @node Overview, Interpreter, top, top | |
1113279c TL |
75 | @comment node-name, next, previous, up |
76 | @chapter Overview | |
77 | @cindex overview | |
78 | @cindex definitions | |
79 | ||
b94e8c39 | 80 | @heading Function and Purpose |
1113279c | 81 | |
b94e8c39 TL |
82 | Libgdb is a package which provides an API to the functionality of GDB, |
83 | the GNU symbolic debugger. It is specifically intended to support the | |
84 | development of a symbolic debugger with a graphic interface. | |
1113279c | 85 | |
1113279c | 86 | |
b94e8c39 | 87 | @heading This Document |
1113279c | 88 | |
b94e8c39 TL |
89 | This document is a specification of the libgdb API. It is written in |
90 | the form of a programmer's manual. So the goal of this document is to | |
91 | explain what functions make up the API, and how they can be used in a | |
92 | running application. | |
1113279c | 93 | |
1113279c | 94 | |
b94e8c39 | 95 | @heading Terminology |
1113279c | 96 | |
b94e8c39 TL |
97 | In this document, @dfn{libgdb} refers to a library containing the |
98 | functions defined herein, @dfn{application} refers to any program built | |
99 | with that library. | |
1113279c TL |
100 | |
101 | ||
b94e8c39 | 102 | @heading Dependencies |
1113279c | 103 | |
b94e8c39 TL |
104 | Programs which are linked with libgdb must be linked with libbfd, |
105 | libopcodes, libiberty, and libmmalloc. | |
1113279c | 106 | |
b94e8c39 | 107 | @heading Acknowledgments |
1113279c | 108 | |
b94e8c39 TL |
109 | Essential contributions to this design were made by Stu Grossman, Jim |
110 | Kingdon, and Rich Pixley. | |
1113279c | 111 | |
b94e8c39 TL |
112 | @node Interpreter, Top Level, Overview, Top |
113 | @comment node-name, next, previous, up | |
114 | @chapter Libgdb is an Interpreter Based Server | |
115 | @cindex interpreter | |
116 | @cindex server | |
1113279c | 117 | |
b94e8c39 TL |
118 | To understand libgdb, it is necessary to understand how the library is |
119 | structured. Historically, GDB is written as a small interpreter for a | |
120 | simple command language. The commands of the language perform useful | |
121 | debugging functions. | |
1113279c | 122 | |
b94e8c39 TL |
123 | Libgdb is built from GDB by turning the interpreter into a debugging |
124 | server. The server reads debugging commands from any source and | |
125 | interprets them, directing the output arbitrarily. | |
1113279c | 126 | |
b94e8c39 TL |
127 | In addition to changing GDB from a tty-based program to a server, a |
128 | number of new GDB commands have been added to make the server more | |
129 | useful for a program with a graphic interface. | |
1113279c | 130 | |
b94e8c39 TL |
131 | Finally, libgdb includes provisions for asynchronous processing within |
132 | the application. | |
1113279c | 133 | |
b94e8c39 TL |
134 | Most operations that can be carried out with libgdb involve the GDB |
135 | command interpreter. The usual mode of operation is that the operation | |
136 | is expressed as a string of GDB commands, which the interpreter is then | |
137 | invoked to carry out. The output from commands executed in this manner | |
138 | can be redirected in a variety of useful ways for further processing by | |
139 | the application. | |
1113279c | 140 | |
b94e8c39 TL |
141 | The command interpreter provides an extensive system of hooks so an |
142 | application can monitor any aspect of the debugging library's state. An | |
143 | application can set its own breakpoints and attach commands and | |
144 | conditions to those. It is possible to attach hooks to any debugger | |
145 | command; the hooks are invoked whenever that command is about to be | |
146 | invoked. By means of these, the displays of a graphical interface can | |
147 | be kept fully up to date at all times. | |
1113279c | 148 | |
b94e8c39 TL |
149 | We show you how to define new primitives in the command language. By |
150 | defining new primitives and using them in breakpoint scripts and command | |
151 | hooks, an application can schedule the execution of arbitrary C-code at | |
152 | almost any point of interest in the operation of libgdb. | |
1113279c | 153 | |
b94e8c39 TL |
154 | We show you how to define new GDB convenience variables for which your |
155 | code computes a value on demand. Referring to such variables in a | |
156 | breakpoint condition is a convenient way to conditionalize breakpoints | |
157 | in novel ways. | |
1113279c | 158 | |
b94e8c39 TL |
159 | To summarize: in libgdb, the gdb command language is turned into a |
160 | debugging server. The server takes commands as input, and the server's | |
161 | output is redirectable. An application uses libgdb by formatting | |
162 | debugging commands and invoking the interpreter. The application might | |
163 | maintain breakpoints, watchpoints and many kinds of hooks. An application | |
164 | can define new primitives for the interpreter. | |
1113279c | 165 | |
b94e8c39 TL |
166 | @node Top Level, I/O, Interpreter, Top |
167 | @chapter You Provide the Top Level for the Libgdb Command Interpreter | |
168 | @cindex {top level} | |
1113279c | 169 | |
b94e8c39 TL |
170 | When you use libgdb, your code is providing a @dfn{top level} for the |
171 | command language interpreter. The top level is significant because it | |
172 | provides commands for the the interpreter to execute. In addition, the | |
173 | top level is responsible for handling some kinds of errors, and | |
174 | performing certain cleanup operations on behalf of the interpreter. | |
1113279c | 175 | |
b94e8c39 | 176 | @heading Initialization |
1113279c | 177 | |
b94e8c39 | 178 | Before calling any other libgdb functions, call this: |
1113279c | 179 | |
b94e8c39 TL |
180 | @deftypefun void gdb_init (void) |
181 | Perform one-time initialization for libgdb. | |
1113279c TL |
182 | @end deftypefun |
183 | ||
b94e8c39 TL |
184 | An application may wish to evaluate specific gdb commands as part of its |
185 | own initialization. The details of how this can be accomplished are | |
186 | explained below. | |
1113279c | 187 | |
b94e8c39 | 188 | @heading The Top-Level Loop |
1113279c | 189 | |
b94e8c39 TL |
190 | There is a strong presumption in libgdb that the application has |
191 | the form of a loop. Here is what such a loop might look like: | |
1113279c TL |
192 | |
193 | @example | |
b94e8c39 TL |
194 | while (gdb_still_going ()) |
195 | @{ | |
196 | if (!GDB_TOP_LEVEL ()) | |
197 | @{ | |
198 | char * command; | |
199 | gdb_start_top_loop (); | |
200 | command = process_events (); | |
201 | gdb_execute_command (command); | |
202 | gdb_finish_top_loop (); | |
203 | @} | |
204 | @} | |
1113279c TL |
205 | @end example |
206 | ||
b94e8c39 TL |
207 | The function @code{gdb_still_going} returns 1 until the gdb command |
208 | `quit' is run. | |
209 | ||
210 | The macro @code{GDB_TOP_LEVEL} invokes setjmp to set the top level error | |
211 | handler. When a command results in an error, the interpreter exits with | |
212 | a longjmp. There is nothing special libgdb requires of the top level | |
213 | error handler other than it be present and that it restart the top level | |
214 | loop. Errors are explained in detail in a later chapter. | |
215 | ||
216 | Each time through the top level loop two important things happen: a | |
217 | debugger command is constructed on the basis of user input, and the | |
218 | interpreter is invoked to execute that command. In the sample code, the | |
219 | call to the imaginary function @code{process_events} represents the | |
220 | point at which a graphical interface should read input events until | |
221 | ready to execute a debugger command. The call to | |
222 | @code{gdb_execute_command} invokes the command interpreter (what happens | |
223 | to the output from the command will be explained later). | |
224 | ||
225 | Libgdb manages some resources using the top-level loop. The primary | |
226 | reason for this is error-handling: even if a command terminates with an | |
227 | error, it may already have allocated resources which need to be freed. | |
228 | The freeing of such resources takes place at the top-level, regardless | |
229 | of how the the command exits. The calls to @code{gdb_start_top_loop} | |
230 | and @code{gdb_finish_top_loop} let libgdb know when it is safe to | |
231 | perform operations associated with these resources. | |
232 | ||
233 | @heading Breakpoint Commands | |
234 | ||
235 | Breakpoint commands are scripts of GDB operations associated with | |
236 | particular breakpoints. When a breakpoint is reached, its associated | |
237 | commands are executed. | |
238 | ||
239 | Breakpoint commands are invoked by the libgdb function | |
240 | @code{gdb_finish_top_loop}. | |
241 | ||
242 | Notice that if control returns to the top-level error handler, the | |
243 | execution of breakpoint commands is bypassed. This can happen as a | |
244 | result of errors during either @code{gdb_execute_command} or | |
245 | @code{gdb_finish_top_loop}. | |
246 | ||
247 | @heading Application Initialization | |
248 | ||
249 | Sometimes it is inconvenient to execute commands via a command loop for | |
250 | example, the commands an application uses to initialize itself. An | |
251 | alternative to @code{execute_command} is @code{execute_catching_errors}. | |
252 | When @code{execute_catching_errors} is used, no top level error handler | |
253 | need be in effect, and it is not necessary to call | |
254 | @code{gdb_start_top_loop} or @code{gdb_finish_top_loop}. | |
255 | ||
256 | ||
257 | @heading Cleanup | |
258 | ||
259 | The debugger command ``quit'' performs all necessary cleanup for libgdb. | |
260 | After it has done so, it changes the return value of | |
261 | @code{gdb_still_going} to 0 and returns to the top level error handler. | |
262 | ||
263 | ||
264 | @node I/O, Invoking, Top Level, Top | |
265 | @comment node-name, next, previous, up | |
266 | @chapter How the Server's I/O Can be Used | |
267 | @cindex I/O | |
268 | ||
269 | In the last chapter it was pointed out that a libgdb application is | |
270 | responsible for providing commands for the interpreter to execute. | |
271 | However some commands require further input (for example, the ``quit'' | |
272 | command might ask for confirmation). Almost all commands produce output | |
273 | of some kind. The purpose of this section is to explain how libgdb | |
274 | performs its I/O, and how an application can take advantage of | |
275 | this. | |
276 | ||
277 | ||
278 | @heading I/O Vectors | |
279 | ||
280 | Libgdb has no fixed strategy for I/O. Instead, all operations are | |
281 | performed by functions called via structures of function pointers. | |
282 | Applications supply theses structures and can change them at any | |
283 | time. | |
284 | ||
285 | @deftp Type {struct gdb_input_vector} | |
286 | @deftpx Type {struct gdb_output_vector} | |
287 | These structures contain a set of function pointers. Each function | |
288 | determines how a particular type of i/o is performed. The details of | |
289 | these strucutres are explained below. | |
290 | ||
291 | The application allocates these structures, initializes them to all bits | |
292 | zero, fills in the function pointers, and then registers names for them | |
293 | them with libgdb. | |
294 | @end deftp | |
1113279c | 295 | |
b94e8c39 TL |
296 | @deftypefun void gdb_name_input_vector (@var{name}, @var{vec}) |
297 | @deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec}) | |
298 | @deftypefunx void gdb_name_output_vector (@var{name}, @var{vec}) | |
299 | @deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec}) | |
1113279c | 300 | @example |
b94e8c39 TL |
301 | char * @var{name}; |
302 | struct gdb_output_vector * @var{vec}; | |
1113279c | 303 | @end example |
b94e8c39 TL |
304 | These functions are used to give and remove names to i/o vectors. Note |
305 | that if a name is used twice, the most recent definition applies. | |
1113279c TL |
306 | @end deftypefun |
307 | ||
1113279c | 308 | |
1113279c | 309 | |
b94e8c39 | 310 | @subheading Output |
1113279c | 311 | |
b94e8c39 | 312 | An output vector is a structure with at least these fields: |
1113279c | 313 | |
1113279c | 314 | @example |
b94e8c39 | 315 | struct gdb_output_vector |
1113279c | 316 | @{ |
b94e8c39 TL |
317 | /* output */ |
318 | void (*put_string) (struct gdb_output_vector *, char * str); | |
1113279c TL |
319 | @} |
320 | @end example | |
321 | ||
b94e8c39 TL |
322 | Use the function @code{memset} or something equivalent to initialize an |
323 | output vector to all bits zero. Then fill in the function pointer with | |
324 | your function. | |
1113279c | 325 | |
b94e8c39 TL |
326 | A debugger command can produce three kinds of output: error messages |
327 | (such as when trying to delete a non-existent breakpoint), informational | |
328 | messages (such as the notification printed when a breakpoint is hit), | |
329 | and the output specifically requested by a command (for example, the | |
330 | value printed by the ``print'' command). At any given time, then, | |
331 | libgdb has three output vectors. These are called the @dfn{error}, | |
332 | @dfn{info}, @dfn{value} vector respectively. | |
1113279c | 333 | |
b94e8c39 | 334 | @subheading Input |
1113279c | 335 | |
1113279c | 336 | @example |
b94e8c39 TL |
337 | struct gdb_input_vector |
338 | @{ | |
339 | int (*query) (struct gdb_input_vector *, | |
340 | char * prompt, | |
341 | int quit_allowed); | |
342 | int * (*selection) (struct gdb_input_vector *, | |
343 | char * prompt, | |
344 | char ** choices); | |
345 | char * (*read_string) (struct gdb_input_vector *, | |
346 | char * prompt); | |
347 | char ** (*read_strings) (struct gdb_input_vector *, | |
348 | char * prompt); | |
349 | @} | |
1113279c | 350 | @end example |
1113279c | 351 | |
b94e8c39 TL |
352 | Use the function @code{memset} or something equivalent to initialize an |
353 | input vector to all bits zero. Then fill in the function pointers with | |
354 | your functions. | |
1113279c | 355 | |
b94e8c39 | 356 | There are four kinds of input requests explicitly made by libgdb. |
1113279c | 357 | |
b94e8c39 TL |
358 | A @dfn{query} is a yes or no question. The user can respond to a query |
359 | with an affirmative or negative answer, or by telling gdb to abort the | |
360 | command (in some cases an abort is not permitted). Query should return | |
361 | 'y' or 'n' or 0 to abort. | |
1113279c | 362 | |
b94e8c39 TL |
363 | A @dfn{selection} is a list of options from which the user selects a subset. |
364 | Selections should return a NULL terminated array of integers, which are | |
365 | indexes into the array of choices. It can return NULL instead to abort | |
366 | the command. The array returned by this function will be passed to | |
367 | @code{free} by libgdb. | |
1113279c | 368 | |
b94e8c39 TL |
369 | A @dfn{read_string} asks the user to supply an arbitrary string. It may |
370 | return NULL to abort the command. The string returned by @code{read_string} | |
371 | should be allocated by @code{malloc}; it will be freed by libgdb. | |
1113279c | 372 | |
b94e8c39 TL |
373 | A @dfn{read_strings} asks the user to supply multiple lines of input |
374 | (for example, the body of a command created using `define'). It, too, | |
375 | may return NULL to abort. The array and the strings returned by this | |
376 | function will be freed by libgdb. | |
1113279c | 377 | |
b94e8c39 | 378 | @heading I/O Redirection from the Application Top-Level |
1113279c | 379 | |
b94e8c39 | 380 | @deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *) |
1113279c | 381 | @example |
1113279c | 382 | |
b94e8c39 TL |
383 | struct gdb_io_vecs |
384 | @{ | |
385 | struct gdb_input_vector * input; | |
386 | struct gdb_output_vector * error; | |
387 | struct gdb_output_vector * info; | |
388 | struct gdb_output_vector * value; | |
389 | @} | |
1113279c | 390 | @end example |
1113279c | 391 | |
b94e8c39 TL |
392 | This establishes a new set of i/o vectors, and returns the old setting. |
393 | Any of the pointers in this structure may be NULL, indicating that the | |
394 | current value should be used. | |
1113279c | 395 | |
b94e8c39 TL |
396 | This function is useful for setting up i/o vectors before any libgdb |
397 | commands have been invoked (hence before any input or output has taken | |
398 | place). | |
1113279c TL |
399 | @end deftypefun |
400 | ||
b94e8c39 TL |
401 | It is explained in a later chapter how to redirect output temporarily. |
402 | (@xref{Invoking}.) | |
1113279c | 403 | |
b94e8c39 | 404 | @heading I/O Redirection in Debugger Commands |
1113279c | 405 | |
b94e8c39 TL |
406 | A libgdb application creates input and output vectors and assigns them names. |
407 | Which input and output vectors are used by libgdb is established by | |
408 | executing these debugger commands: | |
1113279c | 409 | |
b94e8c39 TL |
410 | @defun {set input-vector} name |
411 | @defunx {set error-output-vector} name | |
412 | @defunx {set info-output-vector} name | |
413 | @defunx {set value-output-vector} name | |
414 | Choose an I/O vector by name. | |
415 | @end defun | |
1113279c | 416 | |
1113279c | 417 | |
b94e8c39 TL |
418 | A few debugger commands are for use only within commands defined using |
419 | the debugger command `define' (they have no effect at other times). | |
420 | These commands exist so that an application can maintain hooks which | |
421 | redirect output without affecting the global I/O vectors. | |
1113279c | 422 | |
b94e8c39 TL |
423 | @defun with-input-vector name |
424 | @defunx with-error-output-vector name | |
425 | @defunx with-info-output-vector name | |
426 | @defunx with-value-output-vector name | |
427 | Set an I/O vector, but only temporarily. The setting has effect only | |
428 | within the command definition in which it occurs. | |
429 | @end defun | |
1113279c | 430 | |
1113279c | 431 | |
b94e8c39 | 432 | @heading Initial Conditions |
1113279c | 433 | |
b94e8c39 TL |
434 | When libgdb is initialized, a set of default I/O vectors is put in |
435 | place. The default vectors are called @code{default-input-vector}, | |
436 | @code{default-output-vector}, &c. | |
1113279c | 437 | |
b94e8c39 | 438 | The default query function always returns `y'. Other input functions |
199b2450 | 439 | always abort. The default output functions discard output silently. |
1113279c | 440 | |
1113279c | 441 | |
b94e8c39 TL |
442 | @node Invoking, Defining Commands, I/O, Top |
443 | @chapter Invoking the Interpreter, Executing Commands | |
444 | @cindex {executing commands} | |
445 | @cindex {invoking the interpreter} | |
446 | ||
447 | This section introduces the libgdb functions which invoke the command | |
448 | interpreter. | |
1113279c | 449 | |
b94e8c39 | 450 | @deftypefun void gdb_execute_command (@var{command}) |
1113279c | 451 | @example |
b94e8c39 | 452 | char * @var{command}; |
1113279c | 453 | @end example |
b94e8c39 TL |
454 | Interpret the argument debugger command. An error handler must be set |
455 | when this function is called. (@xref{Top Level}.) | |
1113279c TL |
456 | @end deftypefun |
457 | ||
b94e8c39 TL |
458 | It is possible to override the current I/O vectors for the duration of a |
459 | single command: | |
1113279c | 460 | |
b94e8c39 TL |
461 | @deftypefun void gdb_execute_with_io (@var{command}, @var{vecs}) |
462 | @example | |
463 | char * @var{command}; | |
464 | struct gdb_io_vecs * @var{vecs}; | |
1113279c | 465 | |
b94e8c39 TL |
466 | struct gdb_io_vecs |
467 | @{ | |
468 | struct gdb_input_vector * input; | |
469 | struct gdb_output_vector * error; | |
470 | struct gdb_output_vector * info; | |
471 | struct gdb_output_vector * value; | |
472 | @} | |
1113279c | 473 | @end example |
1113279c | 474 | |
b94e8c39 | 475 | Execute @var{command}, temporarily using the i/o vectors in @var{vecs}. |
1113279c | 476 | |
b94e8c39 TL |
477 | Any of the vectors may be NULL, indicating that the current value should |
478 | be used. An error handler must be in place when this function is used. | |
1113279c TL |
479 | @end deftypefun |
480 | ||
b94e8c39 | 481 | @deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd}) |
1113279c | 482 | @example |
b94e8c39 | 483 | char * cmd; |
1113279c | 484 | @end example |
b94e8c39 | 485 | @deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input}) |
1113279c | 486 | @example |
b94e8c39 TL |
487 | char * cmd; |
488 | struct gdb_input_vector * input; | |
1113279c | 489 | @end example |
b94e8c39 | 490 | @page |
1113279c | 491 | @example |
b94e8c39 TL |
492 | struct gdb_str_output |
493 | @{ | |
494 | char * error; | |
495 | char * info; | |
496 | char * value; | |
497 | @}; | |
1113279c | 498 | @end example |
1113279c | 499 | |
b94e8c39 TL |
500 | Execute @var{cmd}, collecting its output as strings. If no error |
501 | occurs, all three strings will be present in the structure, the | |
502 | empty-string rather than NULL standing for no output of a particular | |
503 | kind. | |
1113279c | 504 | |
b94e8c39 TL |
505 | If the command aborts with an error, then the @code{value} field will be |
506 | NULL, though the other two strings will be present. | |
1113279c | 507 | |
b94e8c39 TL |
508 | In all cases, the strings returned are allocated by malloc and should be |
509 | freed by the caller. | |
1113279c | 510 | |
b94e8c39 TL |
511 | The first form listed uses the current input vector, but overrides the |
512 | current output vector. The second form additionally allows the input | |
513 | vector to be overridden. | |
1113279c | 514 | |
b94e8c39 TL |
515 | This function does not require that an error handler be installed. |
516 | @end deftypefun | |
1113279c | 517 | |
b94e8c39 | 518 | @deftypefun void execute_catching_errors (@var{command}) |
1113279c | 519 | @example |
b94e8c39 | 520 | char * @var{command}; |
1113279c | 521 | @end example |
b94e8c39 | 522 | Like @code{execute_command} except that no error handler is required. |
1113279c TL |
523 | @end deftypefun |
524 | ||
b94e8c39 | 525 | @deftypefun void execute_with_text (@var{command}, @var{text}) |
1113279c | 526 | @example |
b94e8c39 TL |
527 | char * @var{command}; |
528 | char ** @var{text}; | |
1113279c | 529 | @end example |
b94e8c39 TL |
530 | Like @code{execute_catching_errors}, except that the input vector is |
531 | overridden. The new input vector handles only calls to @code{query} (by | |
532 | returning 'y') and calls to @code{read_strings} by returning a copy of | |
533 | @var{text} and the strings it points to. | |
1113279c | 534 | |
b94e8c39 TL |
535 | This form of execute_command is useful for commands like @code{define}, |
536 | @code{document}, and @code{commands}. | |
1113279c TL |
537 | @end deftypefun |
538 | ||
539 | ||
1113279c | 540 | |
b94e8c39 TL |
541 | @node Defining Commands, Variables, Invoking, Top |
542 | @comment node-name, next, previous, up | |
543 | @chapter How New Commands are Created | |
544 | @cindex {commands, defining} | |
1113279c | 545 | |
b94e8c39 TL |
546 | Applications are, of course, free to take advantage of the existing GDB |
547 | macro definition capability (the @code{define} and @code{document} | |
548 | functions). | |
1113279c | 549 | |
b94e8c39 TL |
550 | In addition, an application can add new primitives to the GDB command |
551 | language. | |
1113279c | 552 | |
b94e8c39 | 553 | @deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc}) |
1113279c | 554 | @example |
b94e8c39 TL |
555 | char * @var{name}; |
556 | gdb_cmd_fn @var{fn}; | |
59168c8b | 557 | char * @var{doc}; |
1113279c | 558 | |
b94e8c39 | 559 | typedef void (*gdb_cmd_fn) (char * args); |
1113279c | 560 | @end example |
1113279c | 561 | |
b94e8c39 TL |
562 | Create a new command call @var{name}. The new command is in the |
563 | @code{application} help class. When invoked, the command-line arguments | |
564 | to the command are passed as a single string. | |
1113279c | 565 | |
b94e8c39 TL |
566 | Calling this function twice with the same name replaces an earlier |
567 | definition, but application commands can not replace builtin commands of | |
568 | the same name. | |
1113279c | 569 | |
59168c8b TL |
570 | The documentation string of the command is set to a copy the string |
571 | @var{doc}. | |
1113279c TL |
572 | @end deftypefun |
573 | ||
b94e8c39 TL |
574 | @node Variables, Asynchronous, Defining Commands, Top |
575 | @comment node-name, next, previous, up | |
576 | @chapter How Builtin Variables are Defined | |
577 | @cindex {variables, defining} | |
1113279c | 578 | |
b94e8c39 TL |
579 | Convenience variables provide a way for values maintained by libgdb to |
580 | be referenced in expressions (e.g. @code{$bpnum}). Libgdb includes a | |
581 | means by which the application can define new, integer valued | |
582 | convenience variables: | |
583 | @page | |
584 | @deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg}) | |
1113279c | 585 | @example |
b94e8c39 TL |
586 | char * @var{name}; |
587 | int (*@var{fn}) (void *); | |
588 | void * @var{fn_arg}; | |
1113279c | 589 | @end example |
b94e8c39 TL |
590 | This function defines (or undefines) a convenience variable called @var{name}. |
591 | If @var{fn} is NULL, the variable becomes undefined. Otherwise, | |
592 | @var{fn} is a function which, when passed @var{fn_arg} returns the value | |
593 | of the newly defined variable. | |
1113279c | 594 | |
b94e8c39 | 595 | No libgdb functions should be called by @var{fn}. |
1113279c TL |
596 | @end deftypefun |
597 | ||
b94e8c39 TL |
598 | One use for this function is to create breakpoint conditions computed in |
599 | novel ways. This is done by defining a convenience variable and | |
600 | referring to that variable in a breakpoint condition expression. | |
1113279c | 601 | |
1113279c | 602 | |
b94e8c39 TL |
603 | @node Asynchronous, Commands, Variables, Top |
604 | @chapter Scheduling Asynchronous Computations | |
605 | @cindex asynchronous | |
1113279c | 606 | |
1113279c | 607 | |
b94e8c39 TL |
608 | A running libgdb function can take a long time. Libgdb includes a hook |
609 | so that an application can run intermittently during long debugger | |
610 | operations. | |
1113279c | 611 | |
b94e8c39 TL |
612 | @deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg}) |
613 | @example | |
614 | void (*@var{fn})(void * fn_arg, int (*gdb_poll)()); | |
615 | void * @var{fn_arg}; | |
616 | @end example | |
617 | Arrange to call @var{fn} periodically during lengthy debugger operations. | |
618 | If @var{fn} is NULL, polling is turned off. @var{fn} should take two | |
619 | arguments: an opaque pointer passed as @var{fn_arg} to | |
620 | @code{gdb_set_poll_fn}, and a function pointer. The function pointer | |
621 | passed to @var{fn} is provided by libgdb and points to a function that | |
622 | returns 0 when the poll function should return. That is, when | |
623 | @code{(*gdb_poll)()} returns 0, libgdb is ready to continue @var{fn} | |
624 | should return quickly. | |
1113279c | 625 | |
b94e8c39 TL |
626 | It is possible that @code{(*gdb_poll)()} will return 0 the first time it |
627 | is called, so it is reasonable for an application to do minimal processing | |
628 | before checking whether to return. | |
1113279c | 629 | |
b94e8c39 TL |
630 | No libgdb functions should be called from an application's poll function, |
631 | with one exception: @code{gdb_request_quit}. | |
1113279c TL |
632 | @end deftypefun |
633 | ||
634 | ||
b94e8c39 TL |
635 | @deftypefun void gdb_request_quit (void) |
636 | This function, if called from a poll function, requests that the | |
637 | currently executing libgdb command be interrupted as soon as possible, | |
638 | and that control be returned to the top-level via an error. | |
1113279c | 639 | |
b94e8c39 TL |
640 | The quit is not immediate. It will not occur until at least after the |
641 | application's poll function returns. | |
642 | @end deftypefun | |
1113279c | 643 | |
b94e8c39 TL |
644 | @node Commands, Top, Asynchronous, Top |
645 | @comment node-name, next, previous, up | |
646 | @chapter Debugger Commands for Libgdb Applications | |
1113279c | 647 | |
b94e8c39 TL |
648 | The debugger commands available to libgdb applications are the same commands |
649 | available interactively via GDB. This section is an overview of the | |
650 | commands newly created as part of libgdb. | |
1113279c | 651 | |
b94e8c39 TL |
652 | This section is not by any means a complete reference to the GDB command |
653 | language. See the GDB manual for such a reference. | |
1113279c | 654 | |
b94e8c39 TL |
655 | @menu |
656 | * Command Hooks:: Setting Hooks to Execute With Debugger Commands. | |
657 | * View Commands:: View Commands Mirror Show Commands | |
658 | * Breakpoints:: The Application Can Have Its Own Breakpoints | |
659 | @end menu | |
1113279c | 660 | |
b94e8c39 TL |
661 | @node Command Hooks, View Commands, Commands, Commands |
662 | @comment node-name, next, previous, up | |
663 | @section Setting Hooks to Execute With Debugger Commands. | |
1113279c | 664 | |
b94e8c39 TL |
665 | Debugger commands support hooks. A command hook is executed just before |
666 | the interpreter invokes the hooked command. | |
1113279c | 667 | |
b94e8c39 TL |
668 | There are two hooks allowed for every command. By convention, one hook |
669 | is for use by users, the other is for use by the application. | |
1113279c | 670 | |
b94e8c39 TL |
671 | A user hook is created for a command XYZZY by using |
672 | @code{define-command} to create a command called @code{hook-XYZZY}. | |
1113279c | 673 | |
b94e8c39 TL |
674 | An application hook is created for a command XYZZY by using |
675 | @code{define-command} to create a command called @code{apphook-XYZZY}. | |
1113279c | 676 | |
b94e8c39 TL |
677 | Application hooks are useful for interfaces which wish to continuously |
678 | monitor certain aspects of debugger state. The application can set a | |
679 | hook on all commands that might modify the watched state. When the hook | |
680 | is executed, it can use i/o redirection to notify parts of the | |
681 | application that previous data may be out of date. After the top-level loop | |
682 | resumes, the application can recompute any values that may have changed. | |
683 | (@xref{I/O}.) | |
1113279c | 684 | |
b94e8c39 TL |
685 | @node View Commands, Breakpoints, Command Hooks, Commands |
686 | @comment node-name, next, previous, up | |
687 | @section View Commands Mirror Show Commands | |
1113279c | 688 | |
b94e8c39 TL |
689 | The GDB command language contains many @code{set} and @code{show} |
690 | commands. These commands are used to modify or examine parameters to | |
691 | the debugger. | |
1113279c | 692 | |
59168c8b | 693 | It is difficult to get the current state of a parameter from the |
b94e8c39 | 694 | @code{show} command because @code{show} is very verbose. |
1113279c | 695 | |
1113279c | 696 | @example |
b94e8c39 TL |
697 | (gdb) show check type |
698 | Type checking is "auto; currently off". | |
699 | (gdb) show width | |
700 | Number of characters gdb thinks are in a line is 80. | |
1113279c TL |
701 | @end example |
702 | ||
b94e8c39 TL |
703 | For every @code{show} command, libgdb includes a @code{view} command. |
704 | @code{view} is like @code{show} without the verbose commentary: | |
1113279c | 705 | |
1113279c | 706 | @example |
b94e8c39 TL |
707 | (gdb) view check type |
708 | auto; currently off | |
709 | (gdb) view width | |
710 | 80 | |
1113279c | 711 | @end example |
1113279c | 712 | |
b94e8c39 TL |
713 | (The precise format of the ouput from @code{view} is subject to change. |
714 | In particular, @code{view} may one-day print values which can be used as | |
715 | arguments to the corresponding @code{set} command.) | |
716 | ||
717 | @node Breakpoints, Structured Output, View Commands, Commands | |
718 | @comment node-name, next, previous, up | |
719 | @section The Application Can Have Its Own Breakpoints | |
720 | ||
721 | The GDB breakpoint commands were written with a strong presumption that | |
722 | all breakpoints are managed by a human user. Therefore, the command | |
723 | language contains commands like `delete' which affect all breakpoints | |
724 | without discrimination. | |
725 | ||
726 | In libgdb, there is added support for breakpoints and watchpoints which | |
727 | are set by the application and which should not be affected by ordinary, | |
728 | indiscriminate commands. These are called @dfn{protected} breakpoints. | |
729 | ||
730 | @deffn {Debugger Command} break-protected ... | |
731 | @deffnx {Debugger Command} watch-protected ... | |
732 | These work like @code{break} and @code{watch} except that the resulting | |
733 | breakpoint is given a negative number. Negative numbered breakpoints do | |
734 | not appear in the output of @code{info breakpoints} but do in that of | |
735 | @code{info all-breakpoints}. Negative numbered breakpoints are not | |
736 | affected by commands which ordinarily affect `all' breakpoints (e.g. | |
737 | @code{delete} with no arguments). | |
738 | ||
739 | Note that libgdb itself creates protected breakpoints, so programs | |
740 | should not rely on being able to allocate particular protected | |
741 | breakpoint numbers for themselves. | |
742 | @end deffn | |
743 | ||
744 | More than one breakpoint may be set at a given location. Libgdb adds | |
745 | the concept of @dfn{priority} to breakpoints. A priority is an integer, | |
746 | assigned to each breakpoint. When a breakpoint is reached, the | |
747 | conditions of all breakpoints at the same location are evaluated in | |
748 | order of ascending priority. When breakpoint commands are executed, | |
749 | they are also executed in ascending priority (until all have been | |
750 | executed, an error occurs, or one set of commands continues the | |
751 | target). | |
752 | ||
753 | @deffn {Debugger Command} priority n bplist | |
754 | Set the priority for breakpoints @var{bplist} to @var{n}. | |
755 | By default, breakpoints are assigned a priority of zero. | |
756 | @end deffn | |
757 | ||
758 | @node Structured Output, Commands, Breakpoints, Commands | |
759 | @comment node-name, next, previous, up | |
760 | @section Structured Output, The @code{Explain} Command | |
761 | ||
762 | (This section may be subject to considerable revision.) | |
763 | ||
764 | When GDB prints a the value of an expression, the printed representation | |
765 | contains information that can be usefully fed back into future commands | |
766 | and expressions. For example, | |
1113279c | 767 | |
1113279c | 768 | @example |
b94e8c39 TL |
769 | (gdb) print foo |
770 | $16 = @{v = 0x38ae0, v_length = 40@} | |
1113279c | 771 | @end example |
1113279c | 772 | |
b94e8c39 TL |
773 | On the basis of this output, a user knows, for example, that |
774 | @code{$16.v} refers to a pointer valued @code{0x38ae0} | |
1113279c | 775 | |
b94e8c39 TL |
776 | A new output command helps to make information like this available to |
777 | the application. | |
1113279c | 778 | |
b94e8c39 TL |
779 | @deffn {Debugger Command} explain expression |
780 | @deffnx {Debugger Command} explain /format expression | |
781 | Print the value of @var{expression} in the manner of the @code{print} | |
782 | command, but embed that output in a list syntax containing information | |
783 | about the structure of the output. | |
784 | @end deffn | |
1113279c | 785 | |
b94e8c39 | 786 | As an example, @code{explain argv} might produce this output: |
1113279c | 787 | |
1113279c | 788 | @example |
b94e8c39 TL |
789 | (exp-attribute |
790 | ((expression "$19") | |
791 | (type "char **") | |
792 | (address "48560") | |
793 | (deref-expression "*$19")) | |
794 | "$19 = 0x3800\n") | |
1113279c TL |
795 | @end example |
796 | ||
b94e8c39 | 797 | The syntax of output from @code{explain} is: |
1113279c | 798 | |
1113279c | 799 | @example |
b94e8c39 TL |
800 | <explanation> := <quoted-string> |
801 | | (exp-concat <explanation> <explanation>*) | |
802 | | (exp-attribute <property-list> <explanation>) | |
1113279c | 803 | |
b94e8c39 | 804 | <property-list> := ( <property-pair>* ) |
1113279c | 805 | |
b94e8c39 TL |
806 | <property-pair> := ( <property-name> <quoted-string> ) |
807 | @end example | |
1113279c | 808 | |
b94e8c39 TL |
809 | The string-concatenation of all of the @code{<quoted-string>} (except |
810 | those in property lists) yields the output generated by the equivalent | |
811 | @code{print} command. Quoted strings may contain quotes and backslashes | |
812 | if they are escaped by backslash. "\n" in a quoted string stands for | |
813 | newline; unescaped newlines do not occur within the strings output by | |
814 | @code{explain}. | |
1113279c | 815 | |
b94e8c39 TL |
816 | Property names are made up of alphabetic characters, dashes, and |
817 | underscores. | |
1113279c | 818 | |
b94e8c39 TL |
819 | The set of properties is open-ended. As GDB acquires support for new |
820 | source languages and other new capabilities, new property types may be | |
821 | added to the output of this command. Future commands may offer | |
822 | applications some selectivity concerning which properties are reported. | |
1113279c | 823 | |
b94e8c39 | 824 | The initial set of properties defined includes: |
1113279c | 825 | |
b94e8c39 TL |
826 | @itemize @bullet |
827 | @item @code{expression} | |
1113279c | 828 | |
b94e8c39 TL |
829 | This is an expression, such as @code{$42} or @code{$42.x}. The |
830 | expression can be used to refer to the value printed in the attributed | |
831 | part of the string. | |
1113279c | 832 | |
b94e8c39 | 833 | @item @code{type} |
1113279c | 834 | |
b94e8c39 | 835 | This is a user-readable name for the type of the attributed value. |
1113279c | 836 | |
b94e8c39 | 837 | @item @code{address} |
1113279c | 838 | |
b94e8c39 TL |
839 | If the value is stored in a target register, this is a register number. |
840 | If the value is stored in a GDB convenience variable, this is an integer | |
841 | that is unique among all the convenience variables. Otherwise, this is | |
842 | the address in the target where the value is stored. | |
1113279c | 843 | |
b94e8c39 | 844 | @item @code{deref-expression} |
1113279c | 845 | |
b94e8c39 TL |
846 | If the attributed value is a pointer type, this is an expression that |
847 | refers to the dereferenced value. | |
848 | @end itemize | |
1113279c | 849 | |
b94e8c39 TL |
850 | Here is a larger example, using the same object passed to @code{print} |
851 | in an earlier example of this section. | |
1113279c | 852 | |
1113279c | 853 | @example |
b94e8c39 TL |
854 | (gdb) explain foo |
855 | (exp-attribute | |
856 | ( (expression "$16") | |
857 | (type "struct bytecode_vector") | |
858 | (address 14336) ) | |
859 | (exp-concat | |
59168c8b | 860 | "$16 = @{" |
b94e8c39 | 861 | (exp-attribute |
59168c8b | 862 | ( (expression "$16.v") |
b94e8c39 TL |
863 | (type "char *") |
864 | (address 14336) | |
59168c8b | 865 | (deref-expression "*$16.v") ) |
b94e8c39 TL |
866 | "v = 0x38ae0") |
867 | (exp-attribute | |
59168c8b | 868 | ( (expression "$16.v_length") |
b94e8c39 TL |
869 | (type "int") |
870 | (address 14340) ) | |
871 | ", v_length = 40") | |
872 | "@}\n")) | |
1113279c | 873 | @end example |
1113279c | 874 | |
b94e8c39 TL |
875 | It is undefined how libgdb will indent these lines of output or |
876 | where newlines will be included. | |
1113279c | 877 | |
059e8ee2 | 878 | @bye |