1 \input texinfo @c -*-texinfo-*-
3 @setfilename libgdb.info
9 This file documents libgdb, the GNU library for symbolic debuggers.
11 Copyright 1993 Cygnus Support
13 Permission is granted to ...
16 @c This title page illustrates only one of the
17 @c two methods of forming a title page.
25 @c The following two commands
26 @c start the copyright page.
28 @vskip 0pt plus 1filll
29 Copyright @copyright{} 1993 COPYRIGHT-OWNER
33 Permission is granted to ...
36 @node Top, Overview, (dir), (dir)
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.
43 This is an early draft of this document. Subsequent versions will likely
44 contain revisions, deletions and additions.
46 This document applies to version 0.0.
48 Text marked `[[[' indicates areas which require expansion.
50 Many nodes describe library entry points by giving a prototype and brief
53 @deftypefun {const char **} gdb_warranty ()
55 Return a pointer to the text of the GDB disclaimer.
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.
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
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.
82 @node Copying, Overview, top, top
83 @comment node-name, next, previous, up
89 @node Overview, Conventions, Copying, top
90 @comment node-name, next, previous, up
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.
104 @node Conventions, Targets, Overview, top
105 @comment node-name, next, previous, up
106 @chapter Programming Conventions for Libgdb Clients
109 @heading Naming Conventions
111 Names intentionally exported from libgdb all begin @code{gdb_}
112 as in @code{gdb_use_file}.
115 @heading Error Returns
117 Libgdb functions that might not succeed generally have a return
118 type of @code{gdb_error_t}.
120 @deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error})
121 returns a reasonable error message for @var{error}.
125 @heading Blocking I/O
130 @heading Global Parameters
131 @subheading the current directory
132 @deftypefun error_t gdb_cd (char * @var{dir})
133 Specify gdb's default directory as well as the working
134 directory for the inferior (when first started).@*
138 @deftypefun {char *} gdb_copy_pwd ()
139 Make a copy of the name of gdb's default directory.@*
144 @subheading controlling the input/output radix
145 @deftypefun error_t gdb_set_base (int)
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
153 @deftypefun error_t gdb_set_input_radix (int)
154 @deftypefunx error_t gdb_set_output_radix (int)
155 @deftypefunx error_t gdb_set_radix (int)
156 Valid output radixes are only 0 (heuristic), 10, and 16.@*
161 @subheading manipulating environments
162 @deftp Type {struct environ}
170 A `struct environ' holds a description of environment
174 @deftypefun {struct environ *} gdb_make_environ ()
175 Create a new (empty) environment.@*
179 @deftypefun {void} gdb_free_environ (struct environ *)
180 Free an environment allocated by `gdb_make_environ'.@*
184 @deftypefun {void} gdb_init_environ (struct environ * env)
185 Copy the processes environment into ENV.@*
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}.@*
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.
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)
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
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.
232 typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *,
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:
244 struct a_gdb_cback gdb_cback; /* must be first */
249 foo_helper (struct a_gdb_cback * callback, int i, char * cp)
251 foo ( ((struct my_cback *)callback)->magic_number, i, c);
262 @subheading stream callbacks
264 A common kind of callback takes just a character pointer,
265 presumed to point to part or all of an informational
269 struct gdb_stream_cback;
270 typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *,
275 @subheading integer callbacks
277 Another common kind of callback takes just an integer.
280 struct gdb_int_cback;
281 typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int);
284 @node Targets, Symtabs, Conventions, top
285 @comment node-name, next, previous, up
286 @chapter Selecting Targets and Symbol Tables for Debugging
289 @deftypefun gdb_error_t gdb_use_file (char * @var{filename})
290 Arrange to read both executable code and symbol table information
293 This is exactly equivalent to a sequence of two calls:
295 gdb_use_exec_file (filename);
296 gdb_use_symbol_file (filename);
302 @deftypefun gdb_error_t gdb_use_exec_file (char * @var{filename})
303 Read the code to debug from `filename'.@*
308 @deftypefun {char *} gdb_get_exec_file ()
309 Return the name of the executable file as a string or 0
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.
320 If @var{filename} is @code{NULL}, no core file is used.@*
325 @deftypefun gdb_error_t gdb_use_symbol_file (char * @var{filename})
326 Arrange to read symbol table information from `filename'.
330 gdb_symbol_file_add (filename, 1, (CORE_ADDR)0, 1, 0, 0);
332 See @code{gdb_symbol_file_add} for finer control over the symbol
334 (symbol_file_command)
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
344 @item struct gdb_stream_cback * @var{info_out}
346 Callback to handle informational output.
348 @item char * @var{name}
350 If not 0, verbose output will occur.
352 @item int @var{be_verbose}
354 Regulates the amount of informational output produced.
356 @item CORE_ADDR @var{text_addr}
358 is the address at which the named file is presumed to have
361 @item int @var{replace}@*
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.
367 @item int @var{readnow}
369 If not 0, eagerly read symbols from this file,otherwise
370 symbols will only be read lazily (as needed).
375 @deftypefun {char *} gdb_copy_exec_path ()
376 Make a copy of the execution path.@*
377 [[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]@*
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.@*
389 @deftypefun gdb_error_t gdb_target_device (char * @var{name})
390 Connects the libgdb host environment to a target machine
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.
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.
407 @node Symtabs, Source, Targets, top
408 @comment node-name, next, previous, up
409 @chapter Accessing symbol tables and debugging information.
411 @cindex {Symbol Tables}
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.
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.
428 @deftypefun int gdb_symtab_to_line_count (struct symtab *)
433 @deftypefun {struct symtab *} gdb_filename_to_symtab (char * @var{filename})
434 Lookup the symbol table of a source file named NAME.@*
439 @deftp Type {struct symtab_and_line}
441 struct symtab_and_line
443 struct symtab *symtab;
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.
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.
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.@*
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.@*
480 @deftypefun {struct symtabs_and_lines} gdb_decode_line (@var{argptr}, @var{firstln}, @var{default_symtab}, @var{default_line}, @var{canonical})
484 struct symtab * default_symtab;
488 Parse a string that specifies a line number in GDB syntax.
489 @var{argptr} will be advanced over the characters actually parsed.
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.
499 FILE:FUNCTION -- likewise, but prefer functions in that file.
500 *EXPR -- line in which address EXPR appears.
502 FUNCTION may be an undebuggable function found in minimal symbol
505 If the argument FUNFIRSTLINE is nonzero, we want the first line
506 of real code inside a function when a function is specified.
508 DEFAULT_SYMTAB specifies the file to use if none is specified.
509 It defaults to current_source_symtab.
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
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.
524 The return value of this function includes allocated memory
525 which the caller is responsible for freeing:
527 struct symtabs_and_lines sals;
528 sals = decode_line_spec (arg, 1);
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
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.@*
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')@*
556 @deftypefun int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out})
558 struct symtab * @var{start_out};
560 CORE_ADDR * @var{start_out};
561 CORE_ADDR * @var{end_out};
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}}.
567 Returns 1 to indicate success.@*
568 Returns 0 if could not find the specified line.@*
573 @deftypefun int gdb_find_pc_partial_function (@var{pc}, @var{name}, @var{address}, @var{endaddr})
577 CORE_ADDR *@var{address};
578 CORE_ADDR *@var{endaddr};
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.
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");
596 (find_pc_partial_function)
600 @deftypefun void gdb_list_symbols (@var{info_out}, @var{regexp}, @var{class}, @var{bpt})
602 struct gdb_stream_cback * @var{info_out};
607 List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}.
610 If @var{class} is ...
613 0, list all symbols except functions, type names, and
616 1, list only functions.
618 2, list only type names.
620 3, list only method names.
622 BPT is non-zero if set a breakpoint at the functions we find.@*
623 (variables_info, functions_info, types_info, list_symbols)
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
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}.@*
639 @deftypefun int print_frame_arg_vars (struct gdb_stream_cback *, FRAME)
640 Similar to `gdb_locals_info'.@*
644 @node Source, Running, Symtabs, top
645 @comment node-name, next, previous, up
646 @chapter Relating Inferiors to Source Files
648 @cindex {source files}
650 How to find the source that corresponds to executable code and the
651 executable code that corresponds to a line of source.
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
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.]]]@*
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.@*
675 -- IDIOM: The gdb command `show directories'.
677 puts_filtered ("Source directories searched: ");
678 puts_filtered (source_path);
679 puts_filtered ("\n");
684 @deftypefun {char *} gdb_source_path ()
685 Return the path in which source files are sought.@*
690 @deftypefun void gdb_modify_source_path (char * @var{dirnames})
691 Change the source path according to dirnames.@*
696 See `Symtabs' for functions relating symbol tables to files.
700 See `Symtabs' for functions relating source lines to PC values.
704 [[[Try to expose sources_info without having to introduce struct object *?]]]
708 @node Running, Stopping, Source, top
709 @comment node-name, next, previous, up
710 @chapter Creating, Continuing, and Stepping Through an Inferior Process
714 @deftypefun gdb_error_t gdb_target_create_inferior (@var{exec}, @var{args}, @var{environ})
716 char * @var{exec_file};
717 char * @var{inferior_args};
718 char ** @var{inferior_environment_vector};
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)
727 @deftypefun int gdb_target_has_execution ()
728 Return non-0 if an inferior is running.@*
729 (target_has_execution)
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.@*
741 @deftypefun gdb_error_t gdb_step_1 (@var{skip_subs}, @var{single_inst}, @var{repeat_count})
747 Continue a program a little bit. Roughly:
749 for (; count > 0; --count)
750 gdb_clear_proceed_status ();
753 (next_command, nexti_command, step_command, stepi_command)
757 -- IDIOM: Continuing a program where it stopped.
759 gdb_clear_proceed_status ();
760 gdb_proceed ((CORE_ADDR) -1, -1, 0);
765 -- IDIOM: Continuing a program giving it a specified signal.
767 gdb_clear_proceed_status ();
768 gdb_proceed ((CORE_ADDR) -1, signum, 0);
773 @deftypefun {char *} strtosigno (char * @var{str})
776 signum = strtosigno (signum_exp);
779 /* Not found as a name, try it as an expression. */
780 signum = parse_and_eval_address (signum_exp);
782 gdb_clear_proceed_status ();
788 -- IDIOM: Continuing a program at a specified address.
790 gdb_clear_proceed_status ();
791 gdb_proceed (addr, 0, 0);
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
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}.
809 [[[Some of these should be documented, others hidden.]]]
813 step_range_start = 0;
815 step_frame_address = 0;
816 step_over_calls = -1;
818 stop_soon_quietly = 0;
819 proceed_to_finish = 0;
820 breakpoint_proceeded = 1; /* We're about to proceed... */
822 /* Discard any remaining commands or status from previous stop. */
823 bpstat_clear (&stop_bpstat);
825 (clear_proceed_status)
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.
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.
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}).@*
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
855 @deftypefun int gdb_inferior_pid ()
856 0 or the valid pid of an inferior.
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
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).@*
880 @node Stopping, Stack, Running, top
881 @comment node-name, next, previous, up
882 @chapter Using Breakpoints, Signaling an Inferior
887 @deftp Type {struct breakpoint}
888 Breakpoints are typically represented @code{struct breakpoint *}.
892 @deftypefun {struct breakpoint *} gdb_find_breakpoint (int)
893 Find a breakpoint given it's number (return 0 if it doesn't exist).
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)
906 @deftypefun gdb_error_t gdb_set_watchpt (@var{brk_out}, @var{exp_string}, @var{exp}, @var{exp_valid_block})
908 struct breakpoint * @var{brk_out};
909 char * @var{exp_string};
910 struct expression * @var{exp};
911 struct block * @var{expression_valid_block};
913 Set a watchpoint for the given expression.@*
918 @deftypefun void gdb_set_ignore_count (int @var{bptnum}, int @var{count})
919 Set ignore-count of breakpoint number BPTNUM to COUNT.@*
924 @deftypefun {struct gdb_bp_condition *} gdb_set_condition (@var{bp}, @var{exp_str}, @var{cond})
927 char * @var{exp_str};
928 struct gdb_bp_condition * @var{cond};
930 typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num);
931 struct gdb_bp_condition
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.
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.@*
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)
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
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').@*
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]]]
978 @deftp Type {struct breakpoint_cback}
980 typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num);
981 struct breakpoint_cback
983 breakpoint_cback_fn fn;
987 Breakpoints can have an associated function which is called
988 when the program is stopped by that breakpoint.@*
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
996 [[[In the long run, the command interpreter should be available
997 for the use of hooks like this one.]]]
1001 @deftypefun {struct breakpoint_cback *} gdb_get_breakpoint_cback (int @var{bp_num})
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)
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.@*
1021 @deftypefun void gdb_handle_command (char * @var{args})
1022 Takes arguments like the gdb command `handle' and has
1028 @deftypefun void gdb_signals_info (struct gdb_stream_cback *)
1029 Show how signals are handled.@*
1034 @node Stack, Expressions, Stopping, top
1035 @comment node-name, next, previous, up
1036 @chapter Accessing An Inferior's Execution Stack
1039 @cindex {stack frames}
1044 This type representing active stack frames in the inferior.
1045 Consider this type opaque.
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.@*
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.@*
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
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)
1078 @deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@*
1079 (Example use: Implementing @code{disassemble_command})@*
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)
1091 @deftypefun int gdb_selected_frame_level ()
1092 Level of the selected frame:@*
1095 or -1 for frame specified by address with no defined level.@*
1096 (variable selected_frame_level)
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
1108 -- IDIOM: Computing Frame Levels@*
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
1116 if (get_current_frame()) {
1117 for (frame1 = get_prev_frame (0);
1118 frame1 && frame1 != frame;
1119 frame1 = get_prev_frame (frame1))
1125 @deftypefun void gdb_print_stack_frame (@var{cback}, @var{frame}, @var{level}, @var{source})
1127 struct gdb_stream_cback * @var{cback};
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.@*
1144 @deftypefun void gdb_print_backtrace (cback, @var{count}, @var{from_tty})
1146 struct gdb_stream_cback * @var{cback};
1150 Print briefly all stack frames or just the innermost @var{count} frames.@*
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.
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)
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.@*
1182 @node Expressions, Values, Stack, top
1183 @comment node-name, next, previous, up
1184 @chapter How to Parse and Evaluate Expressions
1187 @cindex {expression evaluation}
1191 @deftp Type {struct expression *}
1192 This represents a parsed expression as might be used for a
1193 breakpoint condition.
1197 @deftp Type {struct block}
1198 Describes a lexical environment.
1202 See also `Examining'
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).
1214 If @var{comma} is nonzero, stop if a comma is reached.
1215 (See `Stack' for information about the selected frame)
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
1222 (evaluate_expression)
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.@*
1234 @node Values, Examining, Expressions, top
1235 @comment node-name, next, previous, up
1236 @chapter Data from the Inferior, the Values of Expressions
1238 @cindex {expression values}
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}.
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}.
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}.@*
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.@*
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}.@*
1272 There is a `history list' -- a numbered list of values for
1273 future reference. These can be referred to in expressions,
1276 @deftypefun int gdb_record_latest_value (value @var{val})
1277 Add a value to the history list.@*
1278 (record_latest_value)
1282 @deftypefun value gdb_access_value_history (int @var{index})
1283 Retrieve a value from the history list.@*
1284 (access_value_history)
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.]]]
1293 @node Examining, Types, Values, top
1294 @comment node-name, next, previous, up
1295 @chapter Formatting Values as Strings
1299 @cindex {pretty printing}
1302 Many functions in this section use @code{struct gdb_stream_cback}.
1303 That structure is explained in `Basics'.
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.@*
1316 @deftypefun static void gdb_printf_command (struct gdb_stream_cback * @var{cback}, char * @var{format}, value * @var{values}, int @var{n_values})@*
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]]]@*
1331 -- IDIOM: This prints the values of all convenience variables:
1333 for (var = internalvars; var; var = var->next)
1335 printf_filtered ("$%s = ", var->name);
1336 value_print (var->value, stdout, 0, Val_pretty_default);
1337 printf_filtered ("\n");
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.@*
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.@*
1357 -- IDIOM: This is the core of a dissasemble command:
1359 for (pc = low; pc < high; )
1361 print_address (pc, stdout);
1362 printf_filtered (":\t");
1363 pc += print_insn (pc, stdout);
1364 printf_filtered ("\n");
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)
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
1377 (info registers, info all-registers, nofp_registers_info, all_registers_info)
1381 @deftypefun char * gdb_register_name (int @var{i})
1382 Look up a register name by number.
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.
1392 @deftypefun CORE_ADDR gdb_read_pc ()
1393 Return the contents of the inferior's program counter.
1397 @deftypefun int gdb_is_stepping ()
1398 If true, the inferior is stopped after being stepped.
1402 @deftypefun void gdb_current_breakpoints (gdb_int_cback)
1403 Call a callback for each of the current breakpoints.@*
1408 @deftypefun int gdb_stop_signal ()
1409 Return the signal that stopped the inferior.
1413 @deftypefun char * strsigno (int)
1414 Return a symbolic name for a signal.
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)
1425 [[[what is appropriate?]]]
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}
1435 @node Types, top, Examining, top
1436 @comment node-name, next, previous, up
1437 @chapter Examining the Types of an Inferior's Data
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
1449 @deftypefun void type_print (@var{type}, @var{varstring}, @var{stream_cback}, @var{show})
1451 struct type @var{*type};
1452 char @var{*varstring};
1453 struct gdb_stream_cback * @var{stream_cback};
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}.
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').
1468 [[[In the long run, we need something to programmaticly read off type
1469 structures in a machine/language independent way.]]]