Commit | Line | Data |
---|---|---|
1113279c TL |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename libgdb.info | |
4 | @settitle Libgdb | |
5 | @setchapternewpage odd | |
6 | @c %**end of header | |
7 | ||
8 | @ifinfo | |
9 | This file documents libgdb, the GNU library for symbolic debuggers. | |
10 | ||
11 | Copyright 1993 Cygnus Support | |
12 | ||
13 | Permission is granted to ... | |
14 | @end ifinfo | |
15 | ||
16 | @c This title page illustrates only one of the | |
17 | @c two methods of forming a title page. | |
18 | ||
19 | @titlepage | |
20 | @title Libgdb | |
21 | @subtitle Version 0.1 | |
22 | @subtitle 27 Sep 1993 | |
23 | @author Thomas Lord | |
24 | ||
25 | @c The following two commands | |
26 | @c start the copyright page. | |
27 | @page | |
28 | @vskip 0pt plus 1filll | |
29 | Copyright @copyright{} 1993 COPYRIGHT-OWNER | |
30 | ||
31 | Published by ... | |
32 | ||
33 | Permission is granted to ... | |
34 | @end titlepage | |
35 | ||
36 | @node Top, Overview, (dir), (dir) | |
37 | ||
38 | @ifinfo | |
39 | ||
40 | Libgdb is a library which provides the core functionality of a symbolic | |
41 | debugger. It is derived from GNU GDB and depends on the BFD library. | |
42 | ||
43 | This is an early draft of this document. Subsequent versions will likely | |
44 | contain revisions, deletions and additions. | |
45 | ||
46 | This document applies to version 0.0. | |
47 | ||
48 | Text marked `[[[' indicates areas which require expansion. | |
49 | ||
50 | Many nodes describe library entry points by giving a prototype and brief | |
51 | description: | |
52 | ||
53 | @deftypefun {const char **} gdb_warranty () | |
54 | (warranty_info) | |
55 | Return a pointer to the text of the GDB disclaimer. | |
56 | @end deftypefun | |
57 | ||
58 | The parenthesized symbols (e.g. `(warranty_info)') refer to the | |
59 | existing GDB source and generally indicate where to find code with | |
60 | which to implement the library function. | |
61 | @end ifinfo | |
62 | ||
63 | @menu | |
64 | * Copying:: Your rights and freedoms. | |
65 | * Overview:: The basics of libgdb and this document. | |
66 | * Conventions:: Programming conventions for users of libgdb. | |
67 | * Targets:: Selecting debugging targets and symbol tables. | |
68 | * Symtabs:: Accessing symbol tables and debugging information. | |
69 | * Source:: Relating inferiors to source files. | |
70 | * Running:: Creating, continuing, and stepping through an | |
71 | inferior process. | |
72 | * Stopping:: Using breakpoints, signaling an inferior. | |
73 | * Stack:: Accessing an inferior's execution stack. | |
74 | * Expressions:: How to parse and evaluate expressions in the | |
75 | context of an inferior. | |
76 | * Values:: Data from the inferior, the values of expressions. | |
77 | * Examining:: Formatting values as strings. | |
78 | * Types:: Examining the types of an inferiors data. | |
79 | @end menu | |
80 | ||
81 | ||
82 | @node Copying, Overview, top, top | |
83 | @comment node-name, next, previous, up | |
84 | @chapter Copying | |
85 | @cindex copying | |
86 | ||
87 | blah blah | |
88 | ||
89 | @node Overview, Conventions, Copying, top | |
90 | @comment node-name, next, previous, up | |
91 | @chapter Overview | |
92 | @cindex overview | |
93 | @cindex definitions | |
94 | ||
95 | ||
96 | Libgdb is a library which provides the core functionality of a symbolic | |
97 | debugger. It is derived from GNU GDB and depends on the BFD library. | |
98 | ||
99 | target | |
100 | inferior | |
101 | ||
102 | ||
103 | ||
104 | @node Conventions, Targets, Overview, top | |
105 | @comment node-name, next, previous, up | |
106 | @chapter Programming Conventions for Libgdb Clients | |
107 | @cindex Conventions | |
108 | ||
109 | @heading Naming Conventions | |
110 | ||
111 | Names intentionally exported from libgdb all begin @code{gdb_} | |
112 | as in @code{gdb_use_file}. | |
113 | ||
114 | ||
115 | @heading Error Returns | |
116 | ||
117 | Libgdb functions that might not succeed generally have a return | |
118 | type of @code{gdb_error_t}. | |
119 | ||
120 | @deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error}) | |
121 | returns a reasonable error message for @var{error}. | |
059e8ee2 | 122 | @end deftypefun |
1113279c TL |
123 | |
124 | ||
125 | @heading Blocking I/O | |
126 | ||
127 | [[[....]]] | |
128 | ||
129 | ||
130 | @heading Global Parameters | |
131 | @subheading the current directory | |
059e8ee2 | 132 | @deftypefun gdb_error_t gdb_cd (char * @var{dir}) |
1113279c TL |
133 | Specify gdb's default directory as well as the working |
134 | directory for the inferior (when first started).@* | |
135 | (cd_command) | |
136 | @end deftypefun | |
137 | ||
138 | @deftypefun {char *} gdb_copy_pwd () | |
139 | Make a copy of the name of gdb's default directory.@* | |
140 | (pwd_command) | |
141 | @end deftypefun | |
142 | ||
143 | ||
144 | @subheading controlling the input/output radix | |
059e8ee2 | 145 | @deftypefun gdb_error_t gdb_set_base (int) |
1113279c TL |
146 | Change the default output radix to 10 or 16, or set it to 0 |
147 | (heuristic). This command is mostly obsolete now that the print | |
148 | command allows formats to apply to aggregates, but is still handy | |
149 | occasionally.@* | |
150 | (set_base_command) | |
151 | @end deftypefun | |
152 | ||
059e8ee2 TL |
153 | @deftypefun gdb_error_t gdb_set_input_radix (int) |
154 | @deftypefunx gdb_error_t gdb_set_output_radix (int) | |
155 | @deftypefunx gdb_error_t gdb_set_radix (int) | |
1113279c TL |
156 | Valid output radixes are only 0 (heuristic), 10, and 16.@* |
157 | (set_radix) | |
158 | @end deftypefun | |
159 | ||
160 | ||
161 | @subheading manipulating environments | |
162 | @deftp Type {struct environ} | |
163 | @example | |
164 | struct environ | |
165 | @{ | |
166 | int allocated; | |
167 | char ** vector; | |
168 | @} | |
169 | @end example | |
170 | A `struct environ' holds a description of environment | |
171 | variable bindings. | |
172 | @end deftp | |
173 | ||
174 | @deftypefun {struct environ *} gdb_make_environ () | |
175 | Create a new (empty) environment.@* | |
176 | (make_environ) | |
177 | @end deftypefun | |
178 | ||
179 | @deftypefun {void} gdb_free_environ (struct environ *) | |
180 | Free an environment allocated by `gdb_make_environ'.@* | |
181 | (free_environ) | |
182 | @end deftypefun | |
183 | ||
184 | @deftypefun {void} gdb_init_environ (struct environ * env) | |
185 | Copy the processes environment into ENV.@* | |
186 | (init_environ) | |
187 | @end deftypefun | |
188 | ||
189 | @deftypefun {char **} gdb_get_in_environ (const struct environ * @var{env}, const char * @var{var}) | |
190 | Look up the binding of @var{var} in @var{env}.@* | |
191 | (get_in_environ) | |
192 | @end deftypefun | |
193 | ||
194 | ||
195 | @deftypefun {void} gdb_set_in_environ (struct environ * @var{env}, const char * @var{var}, const char * @var{value}) | |
196 | Lookup/bind variables within an environment. | |
197 | (set_in_environ) | |
198 | @end deftypefun | |
199 | ||
200 | ||
201 | @subheading legal notices | |
202 | @deftypefun {char **} gdb_copying () | |
203 | @deftypefunx {char **} gdb_warranty () | |
204 | These return pointers to NULL terminated arrays of strings. | |
205 | They contain text which describes the conditions under which | |
206 | libgdb is distributed (`gdb_copying') and which explains to | |
207 | users that there is no warranty for libgdb (`gdb_warranty').@* | |
208 | (show_warranty_command, show_copying_command) | |
209 | @end deftypefun | |
210 | ||
211 | ||
212 | @subheading the inferior's terminal | |
213 | @deftypefun void gdb_inferiors_io (int @var{std_in}, int @var{std_out}, int @var{std_err}) | |
214 | Assert that the given descriptors should be copied into | |
215 | descriptors 0, 1, and 2 of the inferior when it | |
216 | is next run. | |
217 | @end deftypefun | |
218 | ||
219 | ||
220 | @heading callbacks | |
221 | ||
222 | One idiom used in several places deserves mention. | |
223 | At times, it makes sense for libgdb functions to | |
224 | invoke functions provided by the libgdb client. | |
225 | Where this is the case, callback structures are used | |
226 | to refer to client functions. For example, here | |
227 | are the declarations for a callback to which libgdb | |
228 | will pass an integer and a character pointer. | |
229 | ||
230 | @example | |
231 | struct a_gdb_cback; | |
232 | typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *, | |
233 | int, char *); | |
234 | @end example | |
235 | ||
236 | Suppose the client wants the callback to be implemented | |
237 | by @code{foo} which we will assume takes not only the integer | |
238 | and character pointer, but also a floating point number. | |
239 | The client could use these declarations: | |
240 | ||
241 | @example | |
242 | struct my_cback | |
059e8ee2 | 243 | @{ |
1113279c TL |
244 | struct a_gdb_cback gdb_cback; /* must be first */ |
245 | float magic_number; | |
059e8ee2 | 246 | @}; |
1113279c TL |
247 | |
248 | void | |
249 | foo_helper (struct a_gdb_cback * callback, int i, char * cp) | |
059e8ee2 | 250 | @{ |
1113279c | 251 | foo ( ((struct my_cback *)callback)->magic_number, i, c); |
059e8ee2 | 252 | @} |
1113279c TL |
253 | |
254 | struct my_cback | |
059e8ee2 | 255 | @{ |
1113279c TL |
256 | foo_helper, |
257 | 1079252848.8 | |
059e8ee2 | 258 | @} the_cback; |
1113279c TL |
259 | @end example |
260 | ||
261 | ||
262 | @subheading stream callbacks | |
263 | ||
264 | A common kind of callback takes just a character pointer, | |
265 | presumed to point to part or all of an informational | |
266 | message. | |
267 | ||
268 | @example | |
269 | struct gdb_stream_cback; | |
270 | typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *, | |
271 | char *); | |
272 | @end example | |
273 | ||
274 | ||
275 | @subheading integer callbacks | |
276 | ||
277 | Another common kind of callback takes just an integer. | |
278 | ||
279 | @example | |
280 | struct gdb_int_cback; | |
281 | typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int); | |
282 | @end example | |
283 | ||
284 | @node Targets, Symtabs, Conventions, top | |
285 | @comment node-name, next, previous, up | |
286 | @chapter Selecting Targets and Symbol Tables for Debugging | |
287 | @cindex targets | |
288 | ||
289 | @deftypefun gdb_error_t gdb_use_file (char * @var{filename}) | |
290 | Arrange to read both executable code and symbol table information | |
291 | from FILENAME. | |
292 | ||
293 | This is exactly equivalent to a sequence of two calls: | |
294 | @example | |
295 | gdb_use_exec_file (filename); | |
296 | gdb_use_symbol_file (filename); | |
297 | @end example | |
298 | (file_command) | |
299 | @end deftypefun | |
300 | ||
301 | ||
302 | @deftypefun gdb_error_t gdb_use_exec_file (char * @var{filename}) | |
303 | Read the code to debug from `filename'.@* | |
304 | (exec_file_command) | |
305 | @end deftypefun | |
306 | ||
307 | ||
308 | @deftypefun {char *} gdb_get_exec_file () | |
309 | Return the name of the executable file as a string or 0 | |
310 | if there is none. | |
311 | @end deftypefun | |
312 | ||
313 | ||
314 | @deftypefun gdb_error_t gdb_use_core (char * @var{filename}) | |
315 | Specify the whereabouts of a core dump file to be used as the | |
316 | "contents of memory". Traditionally, core files contain only some | |
317 | parts of the address space of the process that generated them; GDB | |
318 | can access the executable file itself for other parts. | |
319 | ||
320 | If @var{filename} is @code{NULL}, no core file is used.@* | |
321 | (core_file_command) | |
322 | @end deftypefun | |
323 | ||
324 | ||
325 | @deftypefun gdb_error_t gdb_use_symbol_file (char * @var{filename}) | |
326 | Arrange to read symbol table information from `filename'. | |
327 | ||
328 | This is the same as: | |
329 | ||
330 | gdb_symbol_file_add (filename, 1, (CORE_ADDR)0, 1, 0, 0); | |
331 | ||
332 | See @code{gdb_symbol_file_add} for finer control over the symbol | |
333 | table.@* | |
334 | (symbol_file_command) | |
335 | @end deftypefun | |
336 | ||
337 | ||
338 | @deftypefun gdb_error_t gdb_symbol_file_add (@var{name}, @var{verbose}, @var{text_addr}, @var{replace}, @var{eager}) | |
339 | Arrange to read additional symbol table information from | |
340 | the file `name'. | |
341 | ||
342 | The arguments are: | |
343 | @itemize @minus | |
344 | @item struct gdb_stream_cback * @var{info_out} | |
345 | ||
346 | Callback to handle informational output. | |
347 | ||
348 | @item char * @var{name} | |
349 | ||
350 | If not 0, verbose output will occur. | |
351 | ||
352 | @item int @var{be_verbose} | |
353 | ||
354 | Regulates the amount of informational output produced. | |
355 | ||
356 | @item CORE_ADDR @var{text_addr} | |
357 | ||
358 | is the address at which the named file is presumed to have | |
359 | been loaded. | |
360 | ||
361 | @item int @var{replace}@* | |
362 | ||
363 | If not 0, this will become the only file | |
364 | in the symbol table -- all previously loaded | |
365 | symbol table information will be discarded. | |
366 | ||
367 | @item int @var{readnow} | |
368 | ||
369 | If not 0, eagerly read symbols from this file,otherwise | |
370 | symbols will only be read lazily (as needed). | |
371 | @end itemize | |
372 | @end deftypefun | |
373 | ||
374 | ||
375 | @deftypefun {char *} gdb_copy_exec_path () | |
376 | Make a copy of the execution path.@* | |
377 | [[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]@* | |
378 | (path_info) | |
379 | @end deftypefun | |
380 | ||
381 | ||
382 | @deftypefun void gdb_mod_exec_path (char * @var{dirnames}) | |
383 | Add zero or more directories to the front of the execution path. | |
384 | @var{dirnames} should be a colon separated list of directory names.@* | |
385 | (path_command) | |
386 | @end deftypefun | |
387 | ||
388 | ||
389 | @deftypefun gdb_error_t gdb_target_device (char * @var{name}) | |
390 | Connects the libgdb host environment to a target machine | |
391 | or process.@* | |
392 | (target foo) | |
393 | @end deftypefun | |
394 | ||
395 | ||
396 | @deftypefun gdb_error_t gdb_set_baud (int @var{rate}) | |
397 | If using a remote target connected by a serial port, | |
398 | use RATE as the communication speed. | |
399 | @end deftypefun | |
400 | ||
401 | ||
402 | @deftypefun gdb_error_t gdb_set_target_debugging (int @var{level}) | |
403 | Choose the level of verboseness of with which a remote | |
404 | target produces debugging output. | |
405 | @end deftypefun | |
406 | ||
407 | @node Symtabs, Source, Targets, top | |
408 | @comment node-name, next, previous, up | |
409 | @chapter Accessing symbol tables and debugging information. | |
410 | @cindex Symtabs | |
411 | @cindex {Symbol Tables} | |
412 | ||
413 | @deftp Type {struct symtab} | |
414 | Each source file is represented by a struct symtab. | |
415 | In many contexts, @code{struct symtab *} is used in preference | |
416 | to a {char *} filename to refer to the source. | |
417 | @end deftp | |
418 | ||
419 | ||
420 | @deftypefun {char *} gdb_symtab_to_filename (struct symtab *) | |
421 | @deftypefunx {char *} gdb_symtab_to_dirname (struct symtab *) | |
422 | Return the location of the file corresponding to this symtab. | |
423 | @code{gdb_symtab_to_dirname} might return @code{NULL} if no directory | |
424 | is known. @code{gdb_symtab_to_line_count} might return -1 if line | |
425 | number information is unavailable. | |
426 | @end deftypefun | |
427 | ||
428 | @deftypefun int gdb_symtab_to_line_count (struct symtab *) | |
429 | (See also `Source') | |
430 | @end deftypefun | |
431 | ||
432 | ||
433 | @deftypefun {struct symtab *} gdb_filename_to_symtab (char * @var{filename}) | |
434 | Lookup the symbol table of a source file named NAME.@* | |
435 | (lookup_symtab) | |
436 | @end deftypefun | |
437 | ||
438 | ||
439 | @deftp Type {struct symtab_and_line} | |
440 | @example | |
441 | struct symtab_and_line | |
442 | @{ | |
443 | struct symtab *symtab; | |
444 | int line; | |
445 | CORE_ADDR pc; | |
446 | CORE_ADDR end; | |
447 | @} | |
448 | @end example | |
449 | ||
450 | @code{struct symtab_and_line} is used to refer to a particular line | |
451 | of source code. It is used to locate breakpoints in the source | |
452 | code and the executable. | |
453 | ||
454 | @code{line} starts at 1 and proceeds through symtab->nlines. | |
455 | 0 is never a valid line number; it is used to indicate | |
456 | that line number information is not available. | |
457 | @end deftp | |
458 | ||
459 | ||
460 | @deftypefun {struct symtab_and_line} gdb_find_pc_line (CORE_ADDR @var{pc}, int @var{notcurrent}) | |
461 | Find the source file and line number for a given @var{pc} value. | |
462 | Return a structure containing a symtab pointer, a line number, | |
463 | and a pc range for the entire source line. | |
464 | The value's @code{.pc} field is NOT the specified @var{pc}. | |
465 | @var{notcurrent} nonzero means, if specified pc is on a line boundary, | |
466 | use the line that ends there. Otherwise, in that case, the line | |
467 | that begins there is used.@* | |
468 | (find_pc_line) | |
469 | @end deftypefun | |
470 | ||
471 | ||
472 | @deftypefun gdb_error_t gdb_find_line (struct symtab_and_line * @var{out}, struct symtab *, int) | |
473 | Create a symtab_and_line for a given symtab and line number. | |
474 | In other words, if you know the source file and line, | |
475 | this returns a location for the breakpoint.@* | |
476 | (resolve_sal_pc) | |
477 | @end deftypefun | |
478 | ||
479 | ||
480 | @deftypefun {struct symtabs_and_lines} gdb_decode_line (@var{argptr}, @var{firstln}, @var{default_symtab}, @var{default_line}, @var{canonical}) | |
481 | @example | |
482 | char ** argptr; | |
483 | int funfirstline; | |
484 | struct symtab * default_symtab; | |
485 | int default_line; | |
486 | char *** canonical; | |
487 | @end example | |
488 | Parse a string that specifies a line number in GDB syntax. | |
489 | @var{argptr} will be advanced over the characters actually parsed. | |
490 | ||
491 | The string can be: | |
492 | ||
493 | LINENUM -- that line number in current file. PC returned is 0. | |
494 | FILE:LINENUM -- that line in that file. PC returned is 0. | |
495 | FUNCTION -- line number of openbrace of that function. | |
496 | PC returned is the start of the function. | |
497 | VARIABLE -- line number of definition of that variable. | |
498 | PC returned is 0. | |
499 | FILE:FUNCTION -- likewise, but prefer functions in that file. | |
500 | *EXPR -- line in which address EXPR appears. | |
501 | ||
502 | FUNCTION may be an undebuggable function found in minimal symbol | |
503 | table. | |
504 | ||
505 | If the argument FUNFIRSTLINE is nonzero, we want the first line | |
506 | of real code inside a function when a function is specified. | |
507 | ||
508 | DEFAULT_SYMTAB specifies the file to use if none is specified. | |
509 | It defaults to current_source_symtab. | |
510 | ||
511 | DEFAULT_LINE specifies the line number to use for relative line | |
512 | numbers (that start with signs). Defaults to current_source_line. | |
513 | If CANONICAL is non-NULL, store an array of strings containing the | |
514 | canonical line specs there if necessary. Currently overloaded | |
515 | member functions and line numbers or static functions without a | |
516 | filename yield a canonical line spec. The array and the line spec | |
517 | strings are allocated on the heap, it is the callers responsibility | |
518 | to free them. | |
519 | ||
520 | Note that it is possible to return zero for the symtab | |
521 | if no file is validly specified. Callers must check that. | |
522 | Also, the line number returned may be invalid. | |
523 | ||
524 | The return value of this function includes allocated memory | |
525 | which the caller is responsible for freeing: | |
526 | ||
527 | struct symtabs_and_lines sals; | |
528 | sals = decode_line_spec (arg, 1); | |
529 | .... | |
530 | free (sals.sals);@* | |
531 | (decode_line_1) | |
532 | @end deftypefun | |
533 | ||
534 | ||
535 | @deftp Type {struct block *} | |
536 | Lexical environments in the program are represented by struct block. | |
537 | These are useful as arguements to expression parsing functions (see | |
538 | `Expressions'). | |
539 | @end deftp | |
540 | ||
541 | ||
542 | @deftypefun {struct block *} gdb_block_for_pc (CORE_ADDR) | |
543 | Return the innermost lexical block containing the | |
544 | specified pc value, or 0 if there is none.@* | |
545 | (block_for_pc) | |
546 | @end deftypefun | |
547 | ||
548 | ||
549 | @deftypefun {struct block *} gdb_get_frame_block (FRAME @var{frame}) | |
550 | This returns the block being executed by a given | |
551 | stack frame (see `Stack')@* | |
552 | (get_frame_block) | |
553 | @end deftypefun | |
554 | ||
555 | ||
556 | @deftypefun int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out}) | |
557 | @example | |
558 | struct symtab * @var{start_out}; | |
559 | int @var{line}; | |
560 | CORE_ADDR * @var{start_out}; | |
561 | CORE_ADDR * @var{end_out}; | |
562 | @end example | |
563 | Find the range of pc values in a line.@* | |
564 | Store the starting pc of the line into @code{*@var{startptr}}. | |
565 | and the ending pc (start of next line) into @code{*@var{endptr}}. | |
566 | ||
567 | Returns 1 to indicate success.@* | |
568 | Returns 0 if could not find the specified line.@* | |
569 | (find_line_pc_range) | |
570 | @end deftypefun | |
571 | ||
572 | ||
573 | @deftypefun int gdb_find_pc_partial_function (@var{pc}, @var{name}, @var{address}, @var{endaddr}) | |
574 | @example | |
575 | CORE_ADDR @var{pc}; | |
576 | char **@var{name}; | |
577 | CORE_ADDR *@var{address}; | |
578 | CORE_ADDR *@var{endaddr}; | |
579 | @end example | |
580 | Finds the "function" (text symbol) that is smaller than @var{pc} but | |
581 | greatest of all of the potential text symbols. Sets @code{*@var{name}} | |
582 | and/or @code{*@var{address}} conditionally if that pointer is non-null. If | |
583 | @var{endaddr} is non-null, then set @code{*@var{endaddr}} to be the end of | |
584 | the function (exclusive), but passing @var{endaddr} as non-null means that | |
585 | the function might cause symbols to be read. This function either succeeds | |
586 | or fails (not halfway succeeds). If it succeeds, it sets | |
587 | @code{*@var{name}}, @code{*@var{address}}, and @code{*@var{endaddr}} to | |
588 | real information and returns 1. If it fails, it sets @code{*@var{name}}, | |
589 | @code{*@var{address}}, and @code{*@var{endaddr}} to zero and returns 0. | |
590 | ||
591 | @example | |
592 | pc = get_frame_pc (selected_frame); | |
593 | if (find_pc_partial_function (pc, &name, &low, &high) == 0) | |
594 | error ("No function contains program counter for selected frame.\n"); | |
595 | @end example | |
596 | (find_pc_partial_function) | |
597 | @end deftypefun | |
598 | ||
599 | ||
600 | @deftypefun void gdb_list_symbols (@var{info_out}, @var{regexp}, @var{class}, @var{bpt}) | |
601 | @example | |
602 | struct gdb_stream_cback * @var{info_out}; | |
603 | char * @var{regexp}; | |
604 | int @var{class}; | |
605 | int @var{bpt}; | |
606 | @end example | |
607 | List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}. | |
608 | ||
609 | ||
610 | If @var{class} is ... | |
611 | @itemize @bullet | |
612 | @item | |
613 | 0, list all symbols except functions, type names, and | |
614 | constants (enums). | |
615 | @item | |
616 | 1, list only functions. | |
617 | @item | |
618 | 2, list only type names. | |
619 | @item | |
620 | 3, list only method names. | |
621 | @end itemize | |
622 | BPT is non-zero if set a breakpoint at the functions we find.@* | |
623 | (variables_info, functions_info, types_info, list_symbols) | |
624 | @end deftypefun | |
625 | ||
626 | ||
627 | @deftypefun int gdb_locals_info (struct gdb_stream_cback * @var{info_out}, FRAME @var{frame}) | |
628 | Print all the local variables in the given frame. | |
629 | including all the blocks active in that frame | |
630 | at its current pc. | |
631 | ||
632 | Returns 1 if the job was done, | |
633 | or 0 if nothing was printed because we have no info | |
634 | on the function running in @var{frame}.@* | |
635 | (locals_info) | |
636 | @end deftypefun | |
637 | ||
638 | ||
639 | @deftypefun int print_frame_arg_vars (struct gdb_stream_cback *, FRAME) | |
640 | Similar to `gdb_locals_info'.@* | |
641 | (args_info) | |
642 | @end deftypefun | |
643 | ||
644 | @node Source, Running, Symtabs, top | |
645 | @comment node-name, next, previous, up | |
646 | @chapter Relating Inferiors to Source Files | |
647 | @cindex source | |
648 | @cindex {source files} | |
649 | ||
650 | How to find the source that corresponds to executable code and the | |
651 | executable code that corresponds to a line of source. | |
652 | ||
653 | @deftypefun {char *} gdb_copy_source_fullname (struct symtab *@var{s}) | |
654 | Return a copy of the full path name to a source file. | |
655 | (See `Symtabs' for more information about filenames | |
656 | and symbol tables.). | |
657 | @end deftypefun | |
658 | ||
659 | ||
660 | @deftypefun int gdb_open_source_file (struct symtab *@var{s}) | |
661 | Open a source file corresponding to @var{s}. Returns a file descriptor | |
662 | or negative number for error. | |
663 | [[[We may decide not to provide this function.]]]@* | |
664 | (open_source_file) | |
665 | @end deftypefun | |
666 | ||
667 | ||
668 | @deftypefun int gdb_source_line_pos (struct symtab * @var{s}, int @var{lineno}) | |
669 | Return the byte offset of a given line of source | |
670 | or a negative number if @var{lineno} is out of range.@* | |
671 | (find_source_lines) | |
672 | @end deftypefun | |
673 | ||
674 | ||
675 | -- IDIOM: The gdb command `show directories'. | |
676 | @example | |
677 | puts_filtered ("Source directories searched: "); | |
678 | puts_filtered (source_path); | |
679 | puts_filtered ("\n"); | |
680 | @end example | |
681 | (show_directories) | |
682 | ||
683 | ||
684 | @deftypefun {char *} gdb_source_path () | |
685 | Return the path in which source files are sought.@* | |
686 | (source_path) | |
687 | @end deftypefun | |
688 | ||
689 | ||
690 | @deftypefun void gdb_modify_source_path (char * @var{dirnames}) | |
691 | Change the source path according to dirnames.@* | |
692 | (directory_command) | |
693 | @end deftypefun | |
694 | ||
695 | ||
696 | See `Symtabs' for functions relating symbol tables to files. | |
697 | (source_info) | |
698 | ||
699 | ||
700 | See `Symtabs' for functions relating source lines to PC values. | |
701 | (line_info) | |
702 | ||
703 | ||
704 | [[[Try to expose sources_info without having to introduce struct object *?]]] | |
705 | (sources_info) | |
706 | ||
707 | ||
708 | @node Running, Stopping, Source, top | |
709 | @comment node-name, next, previous, up | |
710 | @chapter Creating, Continuing, and Stepping Through an Inferior Process | |
711 | @cindex running | |
712 | ||
713 | ||
714 | @deftypefun gdb_error_t gdb_target_create_inferior (@var{exec}, @var{args}, @var{environ}) | |
715 | @example | |
716 | char * @var{exec_file}; | |
717 | char * @var{inferior_args}; | |
718 | char ** @var{inferior_environment_vector}; | |
719 | @end example | |
720 | Create a running inferior. | |
721 | [[[I think the exec_file parameter is redundant. Perhaps this will take | |
722 | only two arguments.]]]@* | |
723 | (run_command, target_create_inferior) | |
724 | @end deftypefun | |
725 | ||
726 | ||
727 | @deftypefun int gdb_target_has_execution () | |
728 | Return non-0 if an inferior is running.@* | |
729 | (target_has_execution) | |
730 | @end deftypefun | |
731 | ||
732 | ||
733 | @deftypefun void gdb_target_kill () | |
734 | Kill the inferior process. Make it go away. | |
735 | The inferior may become a core file. | |
736 | If so, gdb_target_has_stack() will return non-0.@* | |
737 | (target_kill) | |
738 | @end deftypefun | |
739 | ||
740 | ||
741 | @deftypefun gdb_error_t gdb_step_1 (@var{skip_subs}, @var{single_inst}, @var{repeat_count}) | |
742 | @example | |
743 | int skip_subs; | |
744 | int single_inst; | |
745 | int repeat_count; | |
746 | @end example | |
747 | Continue a program a little bit. Roughly: | |
748 | @example | |
749 | for (; count > 0; --count) | |
750 | gdb_clear_proceed_status (); | |
751 | gdb_proceed (...); | |
752 | @end example | |
753 | (next_command, nexti_command, step_command, stepi_command) | |
754 | @end deftypefun | |
755 | ||
756 | ||
757 | -- IDIOM: Continuing a program where it stopped. | |
758 | @example | |
759 | gdb_clear_proceed_status (); | |
760 | gdb_proceed ((CORE_ADDR) -1, -1, 0); | |
761 | @end example | |
762 | (continue_command) | |
763 | ||
764 | ||
765 | -- IDIOM: Continuing a program giving it a specified signal. | |
766 | @example | |
767 | gdb_clear_proceed_status (); | |
768 | gdb_proceed ((CORE_ADDR) -1, signum, 0); | |
769 | @end example | |
770 | (signal_command) | |
771 | ||
772 | ||
773 | @deftypefun {char *} strtosigno (char * @var{str}) | |
774 | (Typical use:) | |
775 | @example | |
776 | signum = strtosigno (signum_exp); | |
777 | ||
778 | if (signum == 0) | |
779 | /* Not found as a name, try it as an expression. */ | |
780 | signum = parse_and_eval_address (signum_exp); | |
781 | ||
782 | gdb_clear_proceed_status (); | |
783 | gdb_proceed (); | |
784 | @end example | |
785 | @end deftypefun | |
786 | ||
787 | ||
788 | -- IDIOM: Continuing a program at a specified address. | |
789 | @example | |
790 | gdb_clear_proceed_status (); | |
791 | gdb_proceed (addr, 0, 0); | |
792 | @end example | |
793 | (jump_command) | |
794 | ||
795 | ||
796 | @deftypefun gdb_error_t gdb_finish () | |
797 | "finish": Set a temporary breakpoint at the place | |
798 | the selected frame will return to, then continue. | |
799 | This is a convenience function but it summarizes a lot | |
800 | of other stuff.@* | |
801 | (finish_command) | |
802 | @end deftypefun | |
803 | ||
804 | ||
805 | @deftypefun void gdb_clear_proceed_status () | |
806 | Clear out all variables saying what to do when inferior is continued. | |
807 | First do this, then set the ones you want, then call @code{gdb_proceed}. | |
808 | ||
809 | [[[Some of these should be documented, others hidden.]]] | |
810 | @example | |
811 | The variables are: | |
812 | trap_expected = 0; | |
813 | step_range_start = 0; | |
814 | step_range_end = 0; | |
815 | step_frame_address = 0; | |
816 | step_over_calls = -1; | |
817 | stop_after_trap = 0; | |
818 | stop_soon_quietly = 0; | |
819 | proceed_to_finish = 0; | |
820 | breakpoint_proceeded = 1; /* We're about to proceed... */ | |
821 | ||
822 | /* Discard any remaining commands or status from previous stop. */ | |
823 | bpstat_clear (&stop_bpstat); | |
824 | @end example | |
825 | (clear_proceed_status) | |
826 | @end deftypefun | |
827 | ||
828 | ||
829 | @deftypefun void gdb_proceed (CORE_ADDR @var{addr}, int @var{signal}, int @var{step}) | |
830 | Basic routine for continuing the program in various fashions. | |
831 | ||
832 | @var{addr} is the address to resume at, or -1 for resume where stopped.@* | |
833 | @var{signal} is the signal to give it, or 0 for none, | |
834 | or -1 for act according to how it stopped.@* | |
835 | @var{step} is nonzero if should trap after one instruction. | |
836 | -1 means return after that and print nothing.@* | |
837 | You should probably set various step_... variables | |
838 | before calling here, if you are stepping. | |
839 | ||
840 | You should call @code{gdb_clear_proceed_status} before calling proceed. | |
841 | (See the documentation for @code{gdb_clear_proceed_status} for more | |
842 | parameters to @code{gdb_proceed}).@* | |
843 | (proceed) | |
844 | @end deftypefun | |
845 | ||
846 | ||
847 | @deftypefun gdb_error_t gdb_return (value @var{return_value}, FRAME @var{frame}) | |
848 | Make @var{frame} return to @var{value} to it's caller. | |
849 | Unlike the other functions in this section, this doesn't | |
850 | call proceed. | |
851 | (return_command) | |
852 | @end deftypefun | |
853 | ||
854 | ||
855 | @deftypefun int gdb_inferior_pid () | |
856 | 0 or the valid pid of an inferior. | |
857 | @end deftypefun | |
858 | ||
859 | ||
860 | @deftypefun gdb_error_t gdb_attach (int @var{pid}) | |
861 | takes a program started up outside of gdb and | |
862 | `attaches'' to it. This stops it cold in its tracks and allows us | |
863 | to start debugging it. and wait for the trace-trap that results | |
864 | from attaching.@* | |
865 | (attach_command) | |
866 | @end deftypefun | |
867 | ||
868 | ||
869 | @deftypefun gdb_error_t gdb_detach (int @var{signal_num}) | |
870 | Takes a program previously attached to and detaches it. | |
871 | The program resumes execution and will no longer stop | |
872 | on signals, etc. We better not have left any breakpoints | |
873 | in the program or it'll die when it hits one. For this | |
874 | to work, it may be necessary for the process to have been | |
875 | previously attached. It *might* work if the program was | |
876 | started via the normal ptrace (PTRACE_TRACEME).@* | |
877 | (detach_command) | |
878 | @end deftypefun | |
879 | ||
880 | @node Stopping, Stack, Running, top | |
881 | @comment node-name, next, previous, up | |
882 | @chapter Using Breakpoints, Signaling an Inferior | |
883 | @cindex stopping | |
884 | @cindex breakpoints | |
885 | ||
886 | ||
887 | @deftp Type {struct breakpoint} | |
888 | Breakpoints are typically represented @code{struct breakpoint *}. | |
889 | @end deftp | |
890 | ||
891 | ||
892 | @deftypefun {struct breakpoint *} gdb_find_breakpoint (int) | |
893 | Find a breakpoint given it's number (return 0 if it doesn't exist). | |
894 | @end deftypefun | |
895 | ||
896 | @deftypefun gdb_error_t gdb_set_break (struct breakpoint * @var{brk_out}, struct symtab_and_line) | |
897 | @deftypefunx gdb_error_t gdb_set_tbreak (struct breakpoint *, struct symtab_and_line) | |
898 | @deftypefunx gdb_error_t gdb_set_until (struct breakpoint *, struct symtab_and_line) | |
899 | These three are like their command language counterparts. | |
900 | They are front ends to `gdb_set_raw_breakpoint'. | |
901 | See `Symtabs' for sources of `struct symtab_and_line'.@* | |
902 | (break_command, break_command_1, until_command, tbreak_command) | |
903 | @end deftypefun | |
904 | ||
905 | ||
906 | @deftypefun gdb_error_t gdb_set_watchpt (@var{brk_out}, @var{exp_string}, @var{exp}, @var{exp_valid_block}) | |
907 | @example | |
908 | struct breakpoint * @var{brk_out}; | |
909 | char * @var{exp_string}; | |
910 | struct expression * @var{exp}; | |
911 | struct block * @var{expression_valid_block}; | |
912 | @end example | |
913 | Set a watchpoint for the given expression.@* | |
914 | (watch_command) | |
915 | @end deftypefun | |
916 | ||
917 | ||
918 | @deftypefun void gdb_set_ignore_count (int @var{bptnum}, int @var{count}) | |
919 | Set ignore-count of breakpoint number BPTNUM to COUNT.@* | |
920 | (set_ignore_count) | |
921 | @end deftypefun | |
922 | ||
923 | ||
924 | @deftypefun {struct gdb_bp_condition *} gdb_set_condition (@var{bp}, @var{exp_str}, @var{cond}) | |
925 | @example | |
926 | int @var{pbtnum}; | |
927 | char * @var{exp_str}; | |
928 | struct gdb_bp_condition * @var{cond}; | |
929 | ||
930 | typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num); | |
931 | struct gdb_bp_condition | |
059e8ee2 | 932 | @{ |
1113279c | 933 | gdb_bp_fn fn; |
059e8ee2 | 934 | @}; |
1113279c TL |
935 | @end example |
936 | Add a condition to a breakpoint. | |
937 | The condition is a callback which should return | |
938 | 0 to skip the breakpoint, and 1 to break at it. | |
939 | It is called at times when the break might occur. | |
940 | ||
941 | A useful application of these callbacks to attach | |
942 | an expression to breakpoints like the gdb `condition' | |
943 | command. See `Expressions' for the parsing and | |
944 | evaluation of expressions.@* | |
945 | (condition_command) | |
946 | @end deftypefun | |
947 | ||
948 | ||
949 | @deftypefun gdb_error_t gdb_enable_breakpoint (struct breakpoint * @var{bpt}, int @var{once}) | |
950 | @deftypefunx gdb_error_t gdb_disable_breakpoint (struct breakpoint * @var{bpt}) | |
951 | Enable/disable a breakpoint. If `once' is not 0, the | |
952 | breakpoint is only temporarily enabled.@* | |
953 | (enable_breakpoint, disable_breakpoint, enable_command) | |
954 | @end deftypefun | |
955 | ||
956 | ||
957 | @deftypefun gdb_error_t gdb_delete_breakpoint (struct breakpoint * @var{bpt}) | |
958 | Delete a breakpoint and clean up all traces of it in the | |
959 | data structures.@* | |
960 | (delete_breakpoint) | |
961 | @end deftypefun | |
962 | ||
963 | ||
964 | @deftypefun void gdb_clear_breakpoints (struct symtabs_and_lines * @var{sals}) | |
965 | Clear breakpoints from a list of program locations as | |
966 | might be returned by `gdb_decode_line' (see `Symtabs').@* | |
967 | (clear_command) | |
968 | @end deftypefun | |
969 | ||
970 | ||
971 | @deftypefun {static struct symtabs_and_lines} get_catch_sals (int @var{this_level_only}) | |
972 | Return the line numbers of all exception handlers currently | |
973 | active (or `this_level_only'?? [[[?]]]). | |
974 | [[[The implementation should remember to resolve_sal_pc]]] | |
975 | @end deftypefun | |
976 | ||
977 | ||
978 | @deftp Type {struct breakpoint_cback} | |
979 | @example | |
980 | typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num); | |
981 | struct breakpoint_cback | |
059e8ee2 | 982 | @{ |
1113279c | 983 | breakpoint_cback_fn fn; |
059e8ee2 | 984 | @}; |
1113279c TL |
985 | @end example |
986 | ||
987 | Breakpoints can have an associated function which is called | |
988 | when the program is stopped by that breakpoint.@* | |
989 | (commands_command) | |
990 | @end deftp | |
991 | ||
992 | ||
993 | @deftypefun {struct breakpoint_cback *} gdb_set_breakpoint_cback (int @var{bp_num}, struct breakpoint_cback *) | |
994 | This sets a breakpoint callback and returns the previous callback value | |
995 | for that breakpoint. | |
996 | [[[In the long run, the command interpreter should be available | |
997 | for the use of hooks like this one.]]] | |
998 | @end deftypefun | |
999 | ||
1000 | ||
1001 | @deftypefun {struct breakpoint_cback *} gdb_get_breakpoint_cback (int @var{bp_num}) | |
1002 | @end deftypefun | |
1003 | ||
1004 | ||
1005 | @deftypefun void gdb_breakpoints_info (struct gdb_stream_cback, int @var{bp_num}, int @var{watches}) | |
1006 | Print information on breakpoint number @var{bnum}, or -1 if all. | |
1007 | If @var{watches} is zero, process only breakpoints; if @var{watches} | |
1008 | is nonzero, process only watchpoints. | |
1009 | [[[In the long run, expose the information read off by this function.]]]@* | |
1010 | (info breakpoints, info watchpoints, breakpoints_info, breakpoint_1) | |
1011 | @end deftypefun | |
1012 | ||
1013 | ||
1014 | @deftypefun void gdb_catch_info (struct gdb_stream_cback *) | |
1015 | Print a list of all the exception handlers that are active in the | |
1016 | current stack frame at the current point of execution.@* | |
1017 | (catch_info) | |
1018 | @end deftypefun | |
1019 | ||
1020 | ||
1021 | @deftypefun void gdb_handle_command (char * @var{args}) | |
1022 | Takes arguments like the gdb command `handle' and has | |
1023 | the same effect.@* | |
1024 | (handle_command) | |
1025 | @end deftypefun | |
1026 | ||
1027 | ||
1028 | @deftypefun void gdb_signals_info (struct gdb_stream_cback *) | |
1029 | Show how signals are handled.@* | |
1030 | (signals_info) | |
1031 | @end deftypefun | |
1032 | ||
1033 | ||
1034 | @node Stack, Expressions, Stopping, top | |
1035 | @comment node-name, next, previous, up | |
1036 | @chapter Accessing An Inferior's Execution Stack | |
1037 | @cindex stack | |
1038 | @cindex FRAME | |
1039 | @cindex {stack frames} | |
1040 | ||
1041 | ||
1042 | ||
1043 | @deftp Type FRAME | |
1044 | This type representing active stack frames in the inferior. | |
1045 | Consider this type opaque. | |
1046 | @end deftp | |
1047 | ||
1048 | ||
1049 | @deftypefun FRAME gdb_get_innermost_frame () | |
1050 | Returns the innermost frame or the frame most recently designated | |
1051 | as current by a call to gdb_set_current_frame.@* | |
1052 | (get_current_frame) | |
1053 | @end deftypefun | |
1054 | ||
1055 | ||
1056 | @deftypefun FRAME gdb_get_caller_frame (FRAME @var{frame}) | |
1057 | Return the frame that called @var{frame}.@* | |
1058 | If @var{frame} is the original frame (it has no caller), return 0.@* | |
1059 | (get_prev_frame) | |
1060 | @end deftypefun | |
1061 | ||
1062 | ||
1063 | @deftypefun FRAME gdb_get_called_frame (FRAME @var{frame}) | |
1064 | Return the frame that @var{frame} calls (0 if @var{frame} is the innermost | |
1065 | frame).@* | |
1066 | (get_next_frame) | |
1067 | @end deftypefun | |
1068 | ||
1069 | ||
1070 | @deftypefun FRAME gdb_parse_frame_specification (char * @var{frame_exp}) | |
1071 | Read a frame specification in whatever the appropriate format is. | |
1072 | Call @code{error}() If the specification is in any way invalid (i.e. | |
1073 | this function never returns NULL).@* | |
1074 | (parse_frame_specification) | |
1075 | @end deftypefun | |
1076 | ||
1077 | ||
1078 | @deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@* | |
1079 | (Example use: Implementing @code{disassemble_command})@* | |
1080 | (get_frame_pc) | |
1081 | @end deftypefun | |
1082 | ||
1083 | ||
1084 | @deftypefun FRAME gdb_selected_frame () | |
1085 | The "selected" stack frame is used by default for local and | |
1086 | arg access. May be @code{NULL}, for no selected frame.@* | |
1087 | (variable selected_frame) | |
1088 | @end deftypefun | |
1089 | ||
1090 | ||
1091 | @deftypefun int gdb_selected_frame_level () | |
1092 | Level of the selected frame:@* | |
1093 | 0 for innermost,@* | |
1094 | 1 for its caller,@* | |
1095 | or -1 for frame specified by address with no defined level.@* | |
1096 | (variable selected_frame_level) | |
1097 | @end deftypefun | |
1098 | ||
1099 | ||
1100 | @deftypefun void gdb_select_frame (FRAME @var{frame}, int @var{level}) | |
1101 | Select frame @var{frame}, and note that its stack level is @var{level}. | |
1102 | @var{level} may be -1 if an actual level number is not known. | |
1103 | Calls @code{set_language} to establish the correct language for the | |
1104 | selected frame. | |
1105 | @end deftypefun | |
1106 | ||
1107 | ||
1108 | -- IDIOM: Computing Frame Levels@* | |
1109 | @example | |
1110 | /* Try to figure out what level this frame is as before a | |
1111 | call to gdb_select_frame. But if there is | |
1112 | no current stack, don't error out, just pass -1 | |
1113 | instead. */ | |
1114 | frame1 = 0; | |
1115 | level = -1; | |
059e8ee2 | 1116 | if (get_current_frame()) @{ |
1113279c TL |
1117 | for (frame1 = get_prev_frame (0); |
1118 | frame1 && frame1 != frame; | |
1119 | frame1 = get_prev_frame (frame1)) | |
1120 | level++; | |
059e8ee2 | 1121 | @} |
1113279c TL |
1122 | @end example |
1123 | ||
1124 | ||
1125 | @deftypefun void gdb_print_stack_frame (@var{cback}, @var{frame}, @var{level}, @var{source}) | |
1126 | @example | |
1127 | struct gdb_stream_cback * @var{cback}; | |
1128 | FRAME @var{frame}; | |
1129 | int @var{level}; | |
1130 | int @var{source}; | |
1131 | @end example | |
1132 | Print a stack frame briefly. @var{frame} should be the frame id | |
1133 | and @var{level} should be its level in the stack (or -1 for level not defined). | |
1134 | This prints the level, the function executing, the arguments, | |
1135 | and the file name and line number.@* | |
1136 | If the pc is not at the beginning of the source line, | |
1137 | the actual pc is printed at the beginning.@* | |
1138 | If @var{source} is 1, print the source line as well.@* | |
1139 | If @var{source} is -1, print ONLY the source line.@* | |
1140 | (print_stack_frame) | |
1141 | @end deftypefun | |
1142 | ||
1143 | ||
1144 | @deftypefun void gdb_print_backtrace (cback, @var{count}, @var{from_tty}) | |
1145 | @example | |
1146 | struct gdb_stream_cback * @var{cback}; | |
1147 | int @var{count}; | |
1148 | int @var{from_tty}; | |
1149 | @end example | |
1150 | Print briefly all stack frames or just the innermost @var{count} frames.@* | |
1151 | (backtrace_command) | |
1152 | @end deftypefun | |
1153 | ||
1154 | ||
1155 | @deftypefun FRAME gdb_find_relative_frame (FRAME @var{frame}, int * @var{level_offset_ptr}) | |
1156 | Find a frame a certain number of levels away from @var{frame}. | |
1157 | @var{level_offset_ptr} points to an int containing the number of levels. | |
1158 | Positive means go to earlier frames (up); negative, the reverse. | |
1159 | The int that contains the number of levels is counted toward | |
1160 | zero as the frames for those levels are found. | |
1161 | If the top or bottom frame is reached, that frame is returned, | |
1162 | but the final value of @var{*level_offset_ptr} is nonzero and indicates | |
1163 | how much farther the original request asked to go. | |
1164 | @end deftypefun | |
1165 | ||
1166 | ||
1167 | @deftypefun FRAME gdb_select_frame_downward (int @var{count}) | |
1168 | @deftypefunx FRAME gdb_select_frame_upward (int @var{count}) | |
1169 | Simply a combination of find_relative_frame and select_frame. | |
1170 | Returns the newly selected frame.@* | |
1171 | (down_silently_command, up_silently_command) | |
1172 | @end deftypefun | |
1173 | ||
1174 | ||
1175 | @deftypefun void gdb_frame_info (struct gdb_stream_cback * @var{cback}, FRAME @var{frame}) | |
1176 | Print verbosely the selected the argument @var{frame}. | |
1177 | This means absolutely all information in the frame is printed.@* | |
1178 | (frame_info) | |
1179 | @end deftypefun | |
1180 | ||
1181 | ||
1182 | @node Expressions, Values, Stack, top | |
1183 | @comment node-name, next, previous, up | |
1184 | @chapter How to Parse and Evaluate Expressions | |
1185 | @cindex parsing | |
1186 | @cindex expressions | |
1187 | @cindex {expression evaluation} | |
1188 | @cindex evaluation | |
1189 | ||
1190 | ||
1191 | @deftp Type {struct expression *} | |
1192 | This represents a parsed expression as might be used for a | |
1193 | breakpoint condition. | |
1194 | @end deftp | |
1195 | ||
1196 | ||
1197 | @deftp Type {struct block} | |
1198 | Describes a lexical environment. | |
1199 | @end deftp | |
1200 | ||
1201 | See also `Values' | |
1202 | See also `Examining' | |
1203 | ||
1204 | ||
1205 | @deftypefun struct expression * parse_exp_1 (char ** @var{stringptr}, struct block * @var{block} int @var{comma}) | |
1206 | Read an expression from the string @code{*@var{stringptr}} points to, | |
1207 | parse it, and return a pointer to a struct expression that we malloc. | |
1208 | Use @var{block} as the lexical context for variable names; | |
1209 | if @var{block} is zero, use the block of the selected stack frame. | |
1210 | Meanwhile, advance @code{*@var{stringptr}} to point after the expression, | |
1211 | at the first nonwhite character that is not part of the expression | |
1212 | (possibly a null character). | |
1213 | ||
1214 | If @var{comma} is nonzero, stop if a comma is reached. | |
1215 | (See `Stack' for information about the selected frame) | |
1216 | @end deftypefun | |
1217 | ||
1218 | ||
1219 | @deftypefun gdb_error_t gdb_evaluate_expression (value * @var{value_out}, struct expression * @var{exp}) | |
1220 | Evaluate an expression. See `values' for more information about | |
1221 | the return type.@* | |
1222 | (evaluate_expression) | |
1223 | @end deftypefun | |
1224 | ||
1225 | ||
1226 | @deftypefun value gdb_evaluate_type (struct expression @var{*exp}) | |
1227 | Evaluate an expression, avoiding all memory references | |
1228 | and getting a value whose type alone is correct.@* | |
1229 | (evaluate_type) | |
1230 | @end deftypefun | |
1231 | ||
1232 | ||
1233 | ||
1234 | @node Values, Examining, Expressions, top | |
1235 | @comment node-name, next, previous, up | |
1236 | @chapter Data from the Inferior, the Values of Expressions | |
1237 | @cindex values | |
1238 | @cindex {expression values} | |
1239 | ||
1240 | Values are allocated by functions such as @code{gdb_evaluate_expression}. | |
1241 | All currently allocated values are on the list @code{all_values} and can be | |
1242 | freed by calling @code{gdb_free_all_values}. | |
1243 | ||
1244 | To preserve a value across calls to @code{gdb_free_all_values}, use | |
1245 | @code{gdb_release_value}. Values added to the history list are automaticly | |
1246 | released. To free a released value use @code{gdb_free_value}. | |
1247 | ||
1248 | ||
1249 | @deftypefun void gdb_free_value (value) | |
1250 | Free the memory associated with a released value. | |
1251 | Do not call this function except on values that have been | |
1252 | passed to @code{gdb_release_value}.@* | |
1253 | (gdb_value_free) | |
1254 | @end deftypefun | |
1255 | ||
1256 | ||
1257 | @deftypefun void gdb_free_all_values (void) | |
1258 | Free all allocated values which haven't been released. | |
1259 | This should be called periodically from outside the dynamic | |
1260 | scope of libgdb functions.@* | |
1261 | (free_all_values) | |
1262 | @end deftypefun | |
1263 | ||
1264 | ||
1265 | @deftypefun void gdb_release_value (value @var{val}) | |
1266 | Remove a value from the list @code{all_values} in order to | |
1267 | protect it from @code{gdb_free_all_values}.@* | |
1268 | (release_value) | |
1269 | @end deftypefun | |
1270 | ||
1271 | ||
1272 | There is a `history list' -- a numbered list of values for | |
1273 | future reference. These can be referred to in expressions, | |
1274 | for example. | |
1275 | ||
1276 | @deftypefun int gdb_record_latest_value (value @var{val}) | |
1277 | Add a value to the history list.@* | |
1278 | (record_latest_value) | |
1279 | @end deftypefun | |
1280 | ||
1281 | ||
1282 | @deftypefun value gdb_access_value_history (int @var{index}) | |
1283 | Retrieve a value from the history list.@* | |
1284 | (access_value_history) | |
1285 | @end deftypefun | |
1286 | ||
1287 | ||
1288 | [[[At the moment, the only libgdb use for values is | |
1289 | string formatting (see `Examining'). So, they are treated | |
1290 | as opaque. It'd be useful to expose more of them in the long run.]]] | |
1291 | ||
1292 | ||
1293 | @node Examining, Types, Values, top | |
1294 | @comment node-name, next, previous, up | |
1295 | @chapter Formatting Values as Strings | |
1296 | @cindex examining | |
1297 | @cindex printing | |
1298 | @cindex formatting | |
1299 | @cindex {pretty printing} | |
1300 | ||
1301 | ||
1302 | Many functions in this section use @code{struct gdb_stream_cback}. | |
1303 | That structure is explained in `Basics'. | |
1304 | ||
1305 | ||
1306 | @deftypefun void gdb_print_formatted (struct gdb_stream_cback * @var{cback}, value @var{val}, int @var{format}, int @var{size}) | |
1307 | Print value @var{val} on a stream according to @var{format}, a letter or 0. | |
1308 | Do not end with a newline. | |
1309 | 0 means print @var{val} according to its own type. | |
1310 | @var{size} is the letter for the size of datum being printed. | |
1311 | This is used to pad hex numbers so they line up.@* | |
1312 | (print_formatted) | |
1313 | @end deftypefun | |
1314 | ||
1315 | ||
1316 | @deftypefun static void gdb_printf_command (struct gdb_stream_cback * @var{cback}, char * @var{format}, value * @var{values}, int @var{n_values})@* | |
1317 | (printf_command) | |
1318 | @end deftypefun | |
1319 | ||
1320 | ||
1321 | @deftypefun int gdb_value_print (struct gdb_stream_cback * @var{cback}, @var{value}, int @var{format}, enum @var{val_prettyprint}) | |
1322 | Print the value @var{val} in C-ish syntax on @var{stream}. | |
1323 | @var{format} is a format-letter, or 0 for print in natural format of data type. | |
1324 | If the object printed is a string pointer, returns | |
1325 | the number of string bytes printed. | |
1326 | [[[implementation: watch the change in argument order]]]@* | |
1327 | (value_print) | |
1328 | @end deftypefun | |
1329 | ||
1330 | ||
1331 | -- IDIOM: This prints the values of all convenience variables: | |
1332 | @example | |
1333 | for (var = internalvars; var; var = var->next) | |
059e8ee2 | 1334 | @{ |
1113279c TL |
1335 | printf_filtered ("$%s = ", var->name); |
1336 | value_print (var->value, stdout, 0, Val_pretty_default); | |
1337 | printf_filtered ("\n"); | |
059e8ee2 | 1338 | @} |
1113279c TL |
1339 | @end example |
1340 | ||
1341 | ||
1342 | @deftypefun int gdb_print_insn (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{memaddr}) | |
1343 | Print the instruction at @var{memaddr} and return the | |
1344 | length of the instruction in bytes.@* | |
1345 | (print_insn) | |
1346 | @end deftypefun | |
1347 | ||
1348 | ||
1349 | @deftypefun void gdb_print_address (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{addr}) | |
1350 | Print address @var{addr} symbolically on @var{stream}. | |
1351 | First print it as a number. Then perhaps print | |
1352 | @code{<SYMBOL + OFFSET>} after the number.@* | |
1353 | (print_address) | |
1354 | @end deftypefun | |
1355 | ||
1356 | ||
1357 | -- IDIOM: This is the core of a dissasemble command: | |
1358 | @example | |
1359 | for (pc = low; pc < high; ) | |
059e8ee2 | 1360 | @{ |
1113279c TL |
1361 | print_address (pc, stdout); |
1362 | printf_filtered (":\t"); | |
1363 | pc += print_insn (pc, stdout); | |
1364 | printf_filtered ("\n"); | |
059e8ee2 | 1365 | @} |
1113279c TL |
1366 | @end example |
1367 | Advice for computing pc extents like @code{low} and @code{high} | |
1368 | can be found in `Symtabs' -- for example, @code{gdb_find_line_pc_range}.@* | |
1369 | (disassemble_command) | |
1370 | ||
1371 | ||
1372 | @deftypefun void gdb_print_registers (struct gdb_stream_cback * @var{cback}, int @var{regnum}, int @var{fpregs}, int @var{fancy}) | |
1373 | Print the values of registers. | |
1374 | @var{regnum} can be -1 (print all the registers) or a specific register number. | |
1375 | If @var{regnum} is -1, @var{fpregs} determines whether floating point registers are | |
1376 | shown.@* | |
1377 | (info registers, info all-registers, nofp_registers_info, all_registers_info) | |
1378 | @end deftypefun | |
1379 | ||
1380 | ||
1381 | @deftypefun char * gdb_register_name (int @var{i}) | |
1382 | Look up a register name by number. | |
1383 | @end deftypefun | |
1384 | ||
1385 | ||
1386 | @deftypefun int gdb_parse_register_name (char ** @var{name}) | |
1387 | Parse a register name and advance a text pointer. | |
1388 | Return -1 for bogus names. | |
1389 | @end deftypefun | |
1390 | ||
1391 | ||
1392 | @deftypefun CORE_ADDR gdb_read_pc () | |
1393 | Return the contents of the inferior's program counter. | |
1394 | @end deftypefun | |
1395 | ||
1396 | ||
1397 | @deftypefun int gdb_is_stepping () | |
1398 | If true, the inferior is stopped after being stepped. | |
1399 | @end deftypefun | |
1400 | ||
1401 | ||
1402 | @deftypefun void gdb_current_breakpoints (gdb_int_cback) | |
1403 | Call a callback for each of the current breakpoints.@* | |
1404 | (program_info) | |
1405 | @end deftypefun | |
1406 | ||
1407 | ||
1408 | @deftypefun int gdb_stop_signal () | |
1409 | Return the signal that stopped the inferior. | |
1410 | @end deftypefun | |
1411 | ||
1412 | ||
1413 | @deftypefun char * strsigno (int) | |
1414 | Return a symbolic name for a signal. | |
1415 | @end deftypefun | |
1416 | ||
1417 | ||
1418 | @deftypefun void gdb_target_info (struct gdb_stream_cback *) | |
1419 | Print status information about target we're accessing.@* | |
1420 | (target_files_info, e.g. child_files_info) | |
1421 | @end deftypefun | |
1422 | ||
1423 | ||
1424 | float_info | |
1425 | [[[what is appropriate?]]] | |
1426 | ||
1427 | ||
1428 | @deftypefun void gdb_address_info (struct gdb_stream_cback * @var{cback}, char * @var{symbol}); | |
1429 | Like the `info address' command -- show where @var{symbol} | |
1430 | is located.@* | |
1431 | (address_info) | |
1432 | @end deftypefun | |
1433 | ||
1434 | ||
1435 | @node Types, top, Examining, top | |
1436 | @comment node-name, next, previous, up | |
1437 | @chapter Examining the Types of an Inferior's Data | |
1438 | @cindex types | |
1439 | ||
1440 | ||
1441 | @deftp Type {struct type} | |
1442 | @code{struct type *} is used to represent a type. For example, that is | |
1443 | the type returned by the macro @code{VALUE_TYPE(val)} which yields the | |
1444 | type of inferior data recorded in @code{val}. (see `evaluate_type' in | |
1445 | `Expressions'). | |
1446 | @end deftp | |
1447 | ||
1448 | ||
1449 | @deftypefun void type_print (@var{type}, @var{varstring}, @var{stream_cback}, @var{show}) | |
1450 | @example | |
1451 | struct type @var{*type}; | |
1452 | char @var{*varstring}; | |
1453 | struct gdb_stream_cback * @var{stream_cback}; | |
1454 | FILE @var{*stream}; | |
1455 | int @var{show}; | |
1456 | @end example | |
1457 | Print a description of a type @var{type} in the form of a declaration of a | |
1458 | variable named @var{varstring}. (@var{varstring} is demangled if necessary.) | |
1459 | Output goes to @var{stream_cback}. | |
1460 | ||
1461 | If @var{show} is positive, we show the contents of the outermost level | |
1462 | of structure even if there is a type name that could be used instead. | |
1463 | If @var{show} is negative, we never show the details of elements' types. | |
1464 | (See `Basics' for an explanation of `struct gdb_stream_cback'). | |
1465 | @end deftypefun | |
1466 | ||
1467 | ||
1468 | [[[In the long run, we need something to programmaticly read off type | |
1469 | structures in a machine/language independent way.]]] | |
1470 | ||
059e8ee2 | 1471 | @bye |