diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 4 | ||||
| -rw-r--r-- | gdb/doc/libgdb.texinfo | 1470 |
2 files changed, 1474 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 750c4cd..ac48fed 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +Mon Oct 4 10:42:18 1993 Tom Lord (lord@rtl.cygnus.com) + + * libgdb.texinfo: new file. Spec for the gdb library. + Sun Oct 3 15:26:56 1993 Jim Kingdon (kingdon@lioth.cygnus.com) * stabs.texinfo (Include Files): Fix typo (start -> end). diff --git a/gdb/doc/libgdb.texinfo b/gdb/doc/libgdb.texinfo new file mode 100644 index 0000000..49df038 --- /dev/null +++ b/gdb/doc/libgdb.texinfo @@ -0,0 +1,1470 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename libgdb.info +@settitle Libgdb +@setchapternewpage odd +@c %**end of header + +@ifinfo +This file documents libgdb, the GNU library for symbolic debuggers. + +Copyright 1993 Cygnus Support + +Permission is granted to ... +@end ifinfo + +@c This title page illustrates only one of the +@c two methods of forming a title page. + +@titlepage +@title Libgdb +@subtitle Version 0.1 +@subtitle 27 Sep 1993 +@author Thomas Lord + +@c The following two commands +@c start the copyright page. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993 COPYRIGHT-OWNER + +Published by ... + +Permission is granted to ... +@end titlepage + +@node Top, Overview, (dir), (dir) + +@ifinfo + +Libgdb is a library which provides the core functionality of a symbolic +debugger. It is derived from GNU GDB and depends on the BFD library. + +This is an early draft of this document. Subsequent versions will likely +contain revisions, deletions and additions. + +This document applies to version 0.0. + +Text marked `[[[' indicates areas which require expansion. + +Many nodes describe library entry points by giving a prototype and brief +description: + +@deftypefun {const char **} gdb_warranty () +(warranty_info) +Return a pointer to the text of the GDB disclaimer. +@end deftypefun + +The parenthesized symbols (e.g. `(warranty_info)') refer to the +existing GDB source and generally indicate where to find code with +which to implement the library function. +@end ifinfo + +@menu +* Copying:: Your rights and freedoms. +* Overview:: The basics of libgdb and this document. +* Conventions:: Programming conventions for users of libgdb. +* Targets:: Selecting debugging targets and symbol tables. +* Symtabs:: Accessing symbol tables and debugging information. +* Source:: Relating inferiors to source files. +* Running:: Creating, continuing, and stepping through an + inferior process. +* Stopping:: Using breakpoints, signaling an inferior. +* Stack:: Accessing an inferior's execution stack. +* Expressions:: How to parse and evaluate expressions in the + context of an inferior. +* Values:: Data from the inferior, the values of expressions. +* Examining:: Formatting values as strings. +* Types:: Examining the types of an inferiors data. +@end menu + + +@node Copying, Overview, top, top +@comment node-name, next, previous, up +@chapter Copying +@cindex copying + +blah blah + +@node Overview, Conventions, Copying, top +@comment node-name, next, previous, up +@chapter Overview +@cindex overview +@cindex definitions + + +Libgdb is a library which provides the core functionality of a symbolic +debugger. It is derived from GNU GDB and depends on the BFD library. + +target +inferior + + + +@node Conventions, Targets, Overview, top +@comment node-name, next, previous, up +@chapter Programming Conventions for Libgdb Clients +@cindex Conventions + +@heading Naming Conventions + +Names intentionally exported from libgdb all begin @code{gdb_} +as in @code{gdb_use_file}. + + +@heading Error Returns + +Libgdb functions that might not succeed generally have a return +type of @code{gdb_error_t}. + +@deftypefun {const char *} gdb_error_msg (gdb_error_t @var{error}) +returns a reasonable error message for @var{error}. +@end defun + + +@heading Blocking I/O + +[[[....]]] + + +@heading Global Parameters +@subheading the current directory +@deftypefun error_t gdb_cd (char * @var{dir}) +Specify gdb's default directory as well as the working +directory for the inferior (when first started).@* +(cd_command) +@end deftypefun + +@deftypefun {char *} gdb_copy_pwd () +Make a copy of the name of gdb's default directory.@* +(pwd_command) +@end deftypefun + + +@subheading controlling the input/output radix +@deftypefun error_t gdb_set_base (int) +Change the default output radix to 10 or 16, or set it to 0 +(heuristic). This command is mostly obsolete now that the print +command allows formats to apply to aggregates, but is still handy +occasionally.@* +(set_base_command) +@end deftypefun + +@deftypefun error_t gdb_set_input_radix (int) +@deftypefunx error_t gdb_set_output_radix (int) +@deftypefunx error_t gdb_set_radix (int) +Valid output radixes are only 0 (heuristic), 10, and 16.@* +(set_radix) +@end deftypefun + + +@subheading manipulating environments +@deftp Type {struct environ} +@example +struct environ +@{ + int allocated; + char ** vector; +@} +@end example +A `struct environ' holds a description of environment +variable bindings. +@end deftp + +@deftypefun {struct environ *} gdb_make_environ () +Create a new (empty) environment.@* +(make_environ) +@end deftypefun + +@deftypefun {void} gdb_free_environ (struct environ *) +Free an environment allocated by `gdb_make_environ'.@* +(free_environ) +@end deftypefun + +@deftypefun {void} gdb_init_environ (struct environ * env) +Copy the processes environment into ENV.@* +(init_environ) +@end deftypefun + +@deftypefun {char **} gdb_get_in_environ (const struct environ * @var{env}, const char * @var{var}) +Look up the binding of @var{var} in @var{env}.@* +(get_in_environ) +@end deftypefun + + +@deftypefun {void} gdb_set_in_environ (struct environ * @var{env}, const char * @var{var}, const char * @var{value}) +Lookup/bind variables within an environment. +(set_in_environ) +@end deftypefun + + +@subheading legal notices +@deftypefun {char **} gdb_copying () +@deftypefunx {char **} gdb_warranty () +These return pointers to NULL terminated arrays of strings. +They contain text which describes the conditions under which +libgdb is distributed (`gdb_copying') and which explains to +users that there is no warranty for libgdb (`gdb_warranty').@* +(show_warranty_command, show_copying_command) +@end deftypefun + + +@subheading the inferior's terminal +@deftypefun void gdb_inferiors_io (int @var{std_in}, int @var{std_out}, int @var{std_err}) +Assert that the given descriptors should be copied into +descriptors 0, 1, and 2 of the inferior when it +is next run. +@end deftypefun + + +@heading callbacks + +One idiom used in several places deserves mention. +At times, it makes sense for libgdb functions to +invoke functions provided by the libgdb client. +Where this is the case, callback structures are used +to refer to client functions. For example, here +are the declarations for a callback to which libgdb +will pass an integer and a character pointer. + +@example +struct a_gdb_cback; +typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *, + int, char *); +@end example + +Suppose the client wants the callback to be implemented +by @code{foo} which we will assume takes not only the integer +and character pointer, but also a floating point number. +The client could use these declarations: + +@example +struct my_cback +{ + struct a_gdb_cback gdb_cback; /* must be first */ + float magic_number; +}; + +void +foo_helper (struct a_gdb_cback * callback, int i, char * cp) +{ + foo ( ((struct my_cback *)callback)->magic_number, i, c); +} + +struct my_cback +{ + foo_helper, + 1079252848.8 +} the_cback; +@end example + + +@subheading stream callbacks + +A common kind of callback takes just a character pointer, +presumed to point to part or all of an informational +message. + +@example +struct gdb_stream_cback; +typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *, + char *); +@end example + + +@subheading integer callbacks + +Another common kind of callback takes just an integer. + +@example +struct gdb_int_cback; +typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int); +@end example + +@node Targets, Symtabs, Conventions, top +@comment node-name, next, previous, up +@chapter Selecting Targets and Symbol Tables for Debugging +@cindex targets + +@deftypefun gdb_error_t gdb_use_file (char * @var{filename}) +Arrange to read both executable code and symbol table information +from FILENAME. + +This is exactly equivalent to a sequence of two calls: +@example + gdb_use_exec_file (filename); + gdb_use_symbol_file (filename); +@end example +(file_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_use_exec_file (char * @var{filename}) +Read the code to debug from `filename'.@* +(exec_file_command) +@end deftypefun + + +@deftypefun {char *} gdb_get_exec_file () +Return the name of the executable file as a string or 0 +if there is none. +@end deftypefun + + +@deftypefun gdb_error_t gdb_use_core (char * @var{filename}) +Specify the whereabouts of a core dump file to be used as the +"contents of memory". Traditionally, core files contain only some +parts of the address space of the process that generated them; GDB +can access the executable file itself for other parts. + +If @var{filename} is @code{NULL}, no core file is used.@* +(core_file_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_use_symbol_file (char * @var{filename}) +Arrange to read symbol table information from `filename'. + +This is the same as: + + gdb_symbol_file_add (filename, 1, (CORE_ADDR)0, 1, 0, 0); + +See @code{gdb_symbol_file_add} for finer control over the symbol +table.@* +(symbol_file_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_symbol_file_add (@var{name}, @var{verbose}, @var{text_addr}, @var{replace}, @var{eager}) +Arrange to read additional symbol table information from +the file `name'. + +The arguments are: +@itemize @minus +@item struct gdb_stream_cback * @var{info_out} + +Callback to handle informational output. + +@item char * @var{name} + +If not 0, verbose output will occur. + +@item int @var{be_verbose} + +Regulates the amount of informational output produced. + +@item CORE_ADDR @var{text_addr} + +is the address at which the named file is presumed to have +been loaded. + +@item int @var{replace}@* + +If not 0, this will become the only file +in the symbol table -- all previously loaded +symbol table information will be discarded. + +@item int @var{readnow} + +If not 0, eagerly read symbols from this file,otherwise +symbols will only be read lazily (as needed). +@end itemize +@end deftypefun + + +@deftypefun {char *} gdb_copy_exec_path () +Make a copy of the execution path.@* +[[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]@* +(path_info) +@end deftypefun + + +@deftypefun void gdb_mod_exec_path (char * @var{dirnames}) +Add zero or more directories to the front of the execution path. +@var{dirnames} should be a colon separated list of directory names.@* +(path_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_target_device (char * @var{name}) +Connects the libgdb host environment to a target machine +or process.@* +(target foo) +@end deftypefun + + +@deftypefun gdb_error_t gdb_set_baud (int @var{rate}) +If using a remote target connected by a serial port, +use RATE as the communication speed. +@end deftypefun + + +@deftypefun gdb_error_t gdb_set_target_debugging (int @var{level}) +Choose the level of verboseness of with which a remote +target produces debugging output. +@end deftypefun + +@node Symtabs, Source, Targets, top +@comment node-name, next, previous, up +@chapter Accessing symbol tables and debugging information. +@cindex Symtabs +@cindex {Symbol Tables} + +@deftp Type {struct symtab} +Each source file is represented by a struct symtab. +In many contexts, @code{struct symtab *} is used in preference +to a {char *} filename to refer to the source. +@end deftp + + +@deftypefun {char *} gdb_symtab_to_filename (struct symtab *) +@deftypefunx {char *} gdb_symtab_to_dirname (struct symtab *) +Return the location of the file corresponding to this symtab. +@code{gdb_symtab_to_dirname} might return @code{NULL} if no directory +is known. @code{gdb_symtab_to_line_count} might return -1 if line +number information is unavailable. +@end deftypefun + +@deftypefun int gdb_symtab_to_line_count (struct symtab *) +(See also `Source') +@end deftypefun + + +@deftypefun {struct symtab *} gdb_filename_to_symtab (char * @var{filename}) +Lookup the symbol table of a source file named NAME.@* +(lookup_symtab) +@end deftypefun + + +@deftp Type {struct symtab_and_line} +@example +struct symtab_and_line +@{ + struct symtab *symtab; + int line; + CORE_ADDR pc; + CORE_ADDR end; +@} +@end example + +@code{struct symtab_and_line} is used to refer to a particular line +of source code. It is used to locate breakpoints in the source +code and the executable. + +@code{line} starts at 1 and proceeds through symtab->nlines. +0 is never a valid line number; it is used to indicate +that line number information is not available. +@end deftp + + +@deftypefun {struct symtab_and_line} gdb_find_pc_line (CORE_ADDR @var{pc}, int @var{notcurrent}) +Find the source file and line number for a given @var{pc} value. +Return a structure containing a symtab pointer, a line number, +and a pc range for the entire source line. +The value's @code{.pc} field is NOT the specified @var{pc}. +@var{notcurrent} nonzero means, if specified pc is on a line boundary, +use the line that ends there. Otherwise, in that case, the line +that begins there is used.@* +(find_pc_line) +@end deftypefun + + +@deftypefun gdb_error_t gdb_find_line (struct symtab_and_line * @var{out}, struct symtab *, int) +Create a symtab_and_line for a given symtab and line number. +In other words, if you know the source file and line, +this returns a location for the breakpoint.@* +(resolve_sal_pc) +@end deftypefun + + +@deftypefun {struct symtabs_and_lines} gdb_decode_line (@var{argptr}, @var{firstln}, @var{default_symtab}, @var{default_line}, @var{canonical}) +@example + char ** argptr; + int funfirstline; + struct symtab * default_symtab; + int default_line; + char *** canonical; +@end example + Parse a string that specifies a line number in GDB syntax. + @var{argptr} will be advanced over the characters actually parsed. + + The string can be: + + LINENUM -- that line number in current file. PC returned is 0. + FILE:LINENUM -- that line in that file. PC returned is 0. + FUNCTION -- line number of openbrace of that function. + PC returned is the start of the function. + VARIABLE -- line number of definition of that variable. + PC returned is 0. + FILE:FUNCTION -- likewise, but prefer functions in that file. + *EXPR -- line in which address EXPR appears. + + FUNCTION may be an undebuggable function found in minimal symbol + table. + + If the argument FUNFIRSTLINE is nonzero, we want the first line + of real code inside a function when a function is specified. + + DEFAULT_SYMTAB specifies the file to use if none is specified. + It defaults to current_source_symtab. + + DEFAULT_LINE specifies the line number to use for relative line + numbers (that start with signs). Defaults to current_source_line. + If CANONICAL is non-NULL, store an array of strings containing the + canonical line specs there if necessary. Currently overloaded + member functions and line numbers or static functions without a + filename yield a canonical line spec. The array and the line spec + strings are allocated on the heap, it is the callers responsibility + to free them. + + Note that it is possible to return zero for the symtab + if no file is validly specified. Callers must check that. + Also, the line number returned may be invalid. + + The return value of this function includes allocated memory + which the caller is responsible for freeing: + + struct symtabs_and_lines sals; + sals = decode_line_spec (arg, 1); + .... + free (sals.sals);@* +(decode_line_1) +@end deftypefun + + +@deftp Type {struct block *} +Lexical environments in the program are represented by struct block. +These are useful as arguements to expression parsing functions (see +`Expressions'). +@end deftp + + +@deftypefun {struct block *} gdb_block_for_pc (CORE_ADDR) +Return the innermost lexical block containing the +specified pc value, or 0 if there is none.@* +(block_for_pc) +@end deftypefun + + +@deftypefun {struct block *} gdb_get_frame_block (FRAME @var{frame}) +This returns the block being executed by a given +stack frame (see `Stack')@* +(get_frame_block) +@end deftypefun + + +@deftypefun int gdb_find_line_pc_range (@var{syms}, @var{line}, @var{start_out}, @var{end_out}) +@example +struct symtab * @var{start_out}; +int @var{line}; +CORE_ADDR * @var{start_out}; +CORE_ADDR * @var{end_out}; +@end example +Find the range of pc values in a line.@* +Store the starting pc of the line into @code{*@var{startptr}}. +and the ending pc (start of next line) into @code{*@var{endptr}}. + +Returns 1 to indicate success.@* +Returns 0 if could not find the specified line.@* +(find_line_pc_range) +@end deftypefun + + +@deftypefun int gdb_find_pc_partial_function (@var{pc}, @var{name}, @var{address}, @var{endaddr}) +@example +CORE_ADDR @var{pc}; +char **@var{name}; +CORE_ADDR *@var{address}; +CORE_ADDR *@var{endaddr}; +@end example +Finds the "function" (text symbol) that is smaller than @var{pc} but +greatest of all of the potential text symbols. Sets @code{*@var{name}} +and/or @code{*@var{address}} conditionally if that pointer is non-null. If +@var{endaddr} is non-null, then set @code{*@var{endaddr}} to be the end of +the function (exclusive), but passing @var{endaddr} as non-null means that +the function might cause symbols to be read. This function either succeeds +or fails (not halfway succeeds). If it succeeds, it sets +@code{*@var{name}}, @code{*@var{address}}, and @code{*@var{endaddr}} to +real information and returns 1. If it fails, it sets @code{*@var{name}}, +@code{*@var{address}}, and @code{*@var{endaddr}} to zero and returns 0. + +@example + pc = get_frame_pc (selected_frame); + if (find_pc_partial_function (pc, &name, &low, &high) == 0) + error ("No function contains program counter for selected frame.\n"); +@end example +(find_pc_partial_function) +@end deftypefun + + +@deftypefun void gdb_list_symbols (@var{info_out}, @var{regexp}, @var{class}, @var{bpt}) +@example +struct gdb_stream_cback * @var{info_out}; +char * @var{regexp}; +int @var{class}; +int @var{bpt}; +@end example +List all symbols (if @var{regexp} is NULL) or all symbols matching @var{regexp}. + + +If @var{class} is ... +@itemize @bullet +@item +0, list all symbols except functions, type names, and +constants (enums). +@item +1, list only functions. +@item +2, list only type names. +@item +3, list only method names. +@end itemize +BPT is non-zero if set a breakpoint at the functions we find.@* +(variables_info, functions_info, types_info, list_symbols) +@end deftypefun + + +@deftypefun int gdb_locals_info (struct gdb_stream_cback * @var{info_out}, FRAME @var{frame}) +Print all the local variables in the given frame. +including all the blocks active in that frame +at its current pc. + +Returns 1 if the job was done, +or 0 if nothing was printed because we have no info +on the function running in @var{frame}.@* +(locals_info) +@end deftypefun + + +@deftypefun int print_frame_arg_vars (struct gdb_stream_cback *, FRAME) +Similar to `gdb_locals_info'.@* +(args_info) +@end deftypefun + +@node Source, Running, Symtabs, top +@comment node-name, next, previous, up +@chapter Relating Inferiors to Source Files +@cindex source +@cindex {source files} + +How to find the source that corresponds to executable code and the +executable code that corresponds to a line of source. + +@deftypefun {char *} gdb_copy_source_fullname (struct symtab *@var{s}) +Return a copy of the full path name to a source file. +(See `Symtabs' for more information about filenames +and symbol tables.). +@end deftypefun + + +@deftypefun int gdb_open_source_file (struct symtab *@var{s}) +Open a source file corresponding to @var{s}. Returns a file descriptor +or negative number for error. +[[[We may decide not to provide this function.]]]@* +(open_source_file) +@end deftypefun + + +@deftypefun int gdb_source_line_pos (struct symtab * @var{s}, int @var{lineno}) +Return the byte offset of a given line of source +or a negative number if @var{lineno} is out of range.@* +(find_source_lines) +@end deftypefun + + + -- IDIOM: The gdb command `show directories'. +@example + puts_filtered ("Source directories searched: "); + puts_filtered (source_path); + puts_filtered ("\n"); +@end example +(show_directories) + + +@deftypefun {char *} gdb_source_path () +Return the path in which source files are sought.@* +(source_path) +@end deftypefun + + +@deftypefun void gdb_modify_source_path (char * @var{dirnames}) +Change the source path according to dirnames.@* +(directory_command) +@end deftypefun + + +See `Symtabs' for functions relating symbol tables to files. +(source_info) + + +See `Symtabs' for functions relating source lines to PC values. +(line_info) + + +[[[Try to expose sources_info without having to introduce struct object *?]]] +(sources_info) + + +@node Running, Stopping, Source, top +@comment node-name, next, previous, up +@chapter Creating, Continuing, and Stepping Through an Inferior Process +@cindex running + + +@deftypefun gdb_error_t gdb_target_create_inferior (@var{exec}, @var{args}, @var{environ}) +@example +char * @var{exec_file}; +char * @var{inferior_args}; +char ** @var{inferior_environment_vector}; +@end example +Create a running inferior. +[[[I think the exec_file parameter is redundant. Perhaps this will take +only two arguments.]]]@* +(run_command, target_create_inferior) +@end deftypefun + + +@deftypefun int gdb_target_has_execution () +Return non-0 if an inferior is running.@* +(target_has_execution) +@end deftypefun + + +@deftypefun void gdb_target_kill () +Kill the inferior process. Make it go away. +The inferior may become a core file. +If so, gdb_target_has_stack() will return non-0.@* +(target_kill) +@end deftypefun + + +@deftypefun gdb_error_t gdb_step_1 (@var{skip_subs}, @var{single_inst}, @var{repeat_count}) +@example +int skip_subs; +int single_inst; +int repeat_count; +@end example +Continue a program a little bit. Roughly: +@example + for (; count > 0; --count) + gdb_clear_proceed_status (); + gdb_proceed (...); +@end example +(next_command, nexti_command, step_command, stepi_command) +@end deftypefun + + + -- IDIOM: Continuing a program where it stopped. +@example + gdb_clear_proceed_status (); + gdb_proceed ((CORE_ADDR) -1, -1, 0); +@end example +(continue_command) + + + -- IDIOM: Continuing a program giving it a specified signal. +@example + gdb_clear_proceed_status (); + gdb_proceed ((CORE_ADDR) -1, signum, 0); +@end example +(signal_command) + + +@deftypefun {char *} strtosigno (char * @var{str}) +(Typical use:) +@example + signum = strtosigno (signum_exp); + + if (signum == 0) + /* Not found as a name, try it as an expression. */ + signum = parse_and_eval_address (signum_exp); + + gdb_clear_proceed_status (); + gdb_proceed (); +@end example +@end deftypefun + + + -- IDIOM: Continuing a program at a specified address. +@example + gdb_clear_proceed_status (); + gdb_proceed (addr, 0, 0); +@end example +(jump_command) + + +@deftypefun gdb_error_t gdb_finish () +"finish": Set a temporary breakpoint at the place +the selected frame will return to, then continue. +This is a convenience function but it summarizes a lot +of other stuff.@* +(finish_command) +@end deftypefun + + +@deftypefun void gdb_clear_proceed_status () +Clear out all variables saying what to do when inferior is continued. +First do this, then set the ones you want, then call @code{gdb_proceed}. + + [[[Some of these should be documented, others hidden.]]] +@example + The variables are: + trap_expected = 0; + step_range_start = 0; + step_range_end = 0; + step_frame_address = 0; + step_over_calls = -1; + stop_after_trap = 0; + stop_soon_quietly = 0; + proceed_to_finish = 0; + breakpoint_proceeded = 1; /* We're about to proceed... */ + + /* Discard any remaining commands or status from previous stop. */ + bpstat_clear (&stop_bpstat); +@end example +(clear_proceed_status) +@end deftypefun + + +@deftypefun void gdb_proceed (CORE_ADDR @var{addr}, int @var{signal}, int @var{step}) +Basic routine for continuing the program in various fashions. + +@var{addr} is the address to resume at, or -1 for resume where stopped.@* +@var{signal} is the signal to give it, or 0 for none, +or -1 for act according to how it stopped.@* +@var{step} is nonzero if should trap after one instruction. +-1 means return after that and print nothing.@* +You should probably set various step_... variables +before calling here, if you are stepping. + +You should call @code{gdb_clear_proceed_status} before calling proceed. +(See the documentation for @code{gdb_clear_proceed_status} for more +parameters to @code{gdb_proceed}).@* +(proceed) +@end deftypefun + + +@deftypefun gdb_error_t gdb_return (value @var{return_value}, FRAME @var{frame}) +Make @var{frame} return to @var{value} to it's caller. +Unlike the other functions in this section, this doesn't +call proceed. +(return_command) +@end deftypefun + + +@deftypefun int gdb_inferior_pid () +0 or the valid pid of an inferior. +@end deftypefun + + +@deftypefun gdb_error_t gdb_attach (int @var{pid}) +takes a program started up outside of gdb and +`attaches'' to it. This stops it cold in its tracks and allows us +to start debugging it. and wait for the trace-trap that results +from attaching.@* +(attach_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_detach (int @var{signal_num}) +Takes a program previously attached to and detaches it. +The program resumes execution and will no longer stop +on signals, etc. We better not have left any breakpoints +in the program or it'll die when it hits one. For this +to work, it may be necessary for the process to have been +previously attached. It *might* work if the program was +started via the normal ptrace (PTRACE_TRACEME).@* +(detach_command) +@end deftypefun + +@node Stopping, Stack, Running, top +@comment node-name, next, previous, up +@chapter Using Breakpoints, Signaling an Inferior +@cindex stopping +@cindex breakpoints + + +@deftp Type {struct breakpoint} +Breakpoints are typically represented @code{struct breakpoint *}. +@end deftp + + +@deftypefun {struct breakpoint *} gdb_find_breakpoint (int) +Find a breakpoint given it's number (return 0 if it doesn't exist). +@end deftypefun + +@deftypefun gdb_error_t gdb_set_break (struct breakpoint * @var{brk_out}, struct symtab_and_line) +@deftypefunx gdb_error_t gdb_set_tbreak (struct breakpoint *, struct symtab_and_line) +@deftypefunx gdb_error_t gdb_set_until (struct breakpoint *, struct symtab_and_line) +These three are like their command language counterparts. +They are front ends to `gdb_set_raw_breakpoint'. +See `Symtabs' for sources of `struct symtab_and_line'.@* +(break_command, break_command_1, until_command, tbreak_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_set_watchpt (@var{brk_out}, @var{exp_string}, @var{exp}, @var{exp_valid_block}) +@example +struct breakpoint * @var{brk_out}; +char * @var{exp_string}; +struct expression * @var{exp}; +struct block * @var{expression_valid_block}; +@end example +Set a watchpoint for the given expression.@* +(watch_command) +@end deftypefun + + +@deftypefun void gdb_set_ignore_count (int @var{bptnum}, int @var{count}) +Set ignore-count of breakpoint number BPTNUM to COUNT.@* +(set_ignore_count) +@end deftypefun + + +@deftypefun {struct gdb_bp_condition *} gdb_set_condition (@var{bp}, @var{exp_str}, @var{cond}) +@example +int @var{pbtnum}; +char * @var{exp_str}; +struct gdb_bp_condition * @var{cond}; + +typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num); +struct gdb_bp_condition +{ + gdb_bp_fn fn; +}; +@end example +Add a condition to a breakpoint. +The condition is a callback which should return +0 to skip the breakpoint, and 1 to break at it. +It is called at times when the break might occur. + +A useful application of these callbacks to attach +an expression to breakpoints like the gdb `condition' +command. See `Expressions' for the parsing and +evaluation of expressions.@* +(condition_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_enable_breakpoint (struct breakpoint * @var{bpt}, int @var{once}) +@deftypefunx gdb_error_t gdb_disable_breakpoint (struct breakpoint * @var{bpt}) +Enable/disable a breakpoint. If `once' is not 0, the +breakpoint is only temporarily enabled.@* +(enable_breakpoint, disable_breakpoint, enable_command) +@end deftypefun + + +@deftypefun gdb_error_t gdb_delete_breakpoint (struct breakpoint * @var{bpt}) +Delete a breakpoint and clean up all traces of it in the +data structures.@* +(delete_breakpoint) +@end deftypefun + + +@deftypefun void gdb_clear_breakpoints (struct symtabs_and_lines * @var{sals}) +Clear breakpoints from a list of program locations as +might be returned by `gdb_decode_line' (see `Symtabs').@* +(clear_command) +@end deftypefun + + +@deftypefun {static struct symtabs_and_lines} get_catch_sals (int @var{this_level_only}) +Return the line numbers of all exception handlers currently +active (or `this_level_only'?? [[[?]]]). +[[[The implementation should remember to resolve_sal_pc]]] +@end deftypefun + + +@deftp Type {struct breakpoint_cback} +@example +typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num); +struct breakpoint_cback +{ + breakpoint_cback_fn fn; +}; +@end example + +Breakpoints can have an associated function which is called +when the program is stopped by that breakpoint.@* +(commands_command) +@end deftp + + +@deftypefun {struct breakpoint_cback *} gdb_set_breakpoint_cback (int @var{bp_num}, struct breakpoint_cback *) +This sets a breakpoint callback and returns the previous callback value +for that breakpoint. +[[[In the long run, the command interpreter should be available + for the use of hooks like this one.]]] +@end deftypefun + + +@deftypefun {struct breakpoint_cback *} gdb_get_breakpoint_cback (int @var{bp_num}) +@end deftypefun + + +@deftypefun void gdb_breakpoints_info (struct gdb_stream_cback, int @var{bp_num}, int @var{watches}) +Print information on breakpoint number @var{bnum}, or -1 if all. +If @var{watches} is zero, process only breakpoints; if @var{watches} +is nonzero, process only watchpoints. +[[[In the long run, expose the information read off by this function.]]]@* +(info breakpoints, info watchpoints, breakpoints_info, breakpoint_1) +@end deftypefun + + +@deftypefun void gdb_catch_info (struct gdb_stream_cback *) +Print a list of all the exception handlers that are active in the +current stack frame at the current point of execution.@* +(catch_info) +@end deftypefun + + +@deftypefun void gdb_handle_command (char * @var{args}) +Takes arguments like the gdb command `handle' and has +the same effect.@* +(handle_command) +@end deftypefun + + +@deftypefun void gdb_signals_info (struct gdb_stream_cback *) +Show how signals are handled.@* +(signals_info) +@end deftypefun + + +@node Stack, Expressions, Stopping, top +@comment node-name, next, previous, up +@chapter Accessing An Inferior's Execution Stack +@cindex stack +@cindex FRAME +@cindex {stack frames} + + + +@deftp Type FRAME +This type representing active stack frames in the inferior. +Consider this type opaque. +@end deftp + + +@deftypefun FRAME gdb_get_innermost_frame () +Returns the innermost frame or the frame most recently designated +as current by a call to gdb_set_current_frame.@* +(get_current_frame) +@end deftypefun + + +@deftypefun FRAME gdb_get_caller_frame (FRAME @var{frame}) +Return the frame that called @var{frame}.@* +If @var{frame} is the original frame (it has no caller), return 0.@* +(get_prev_frame) +@end deftypefun + + +@deftypefun FRAME gdb_get_called_frame (FRAME @var{frame}) +Return the frame that @var{frame} calls (0 if @var{frame} is the innermost +frame).@* +(get_next_frame) +@end deftypefun + + +@deftypefun FRAME gdb_parse_frame_specification (char * @var{frame_exp}) +Read a frame specification in whatever the appropriate format is. +Call @code{error}() If the specification is in any way invalid (i.e. +this function never returns NULL).@* +(parse_frame_specification) +@end deftypefun + + +@deftypefun CORE_ADDR get_frame_pc (FRAME @var{frame})@* +(Example use: Implementing @code{disassemble_command})@* +(get_frame_pc) +@end deftypefun + + +@deftypefun FRAME gdb_selected_frame () +The "selected" stack frame is used by default for local and +arg access. May be @code{NULL}, for no selected frame.@* +(variable selected_frame) +@end deftypefun + + +@deftypefun int gdb_selected_frame_level () +Level of the selected frame:@* +0 for innermost,@* +1 for its caller,@* +or -1 for frame specified by address with no defined level.@* +(variable selected_frame_level) +@end deftypefun + + +@deftypefun void gdb_select_frame (FRAME @var{frame}, int @var{level}) +Select frame @var{frame}, and note that its stack level is @var{level}. +@var{level} may be -1 if an actual level number is not known. +Calls @code{set_language} to establish the correct language for the +selected frame. +@end deftypefun + + + -- IDIOM: Computing Frame Levels@* +@example +/* Try to figure out what level this frame is as before a + call to gdb_select_frame. But if there is + no current stack, don't error out, just pass -1 + instead. */ +frame1 = 0; +level = -1; +if (get_current_frame()) { + for (frame1 = get_prev_frame (0); + frame1 && frame1 != frame; + frame1 = get_prev_frame (frame1)) + level++; +} +@end example + + +@deftypefun void gdb_print_stack_frame (@var{cback}, @var{frame}, @var{level}, @var{source}) +@example +struct gdb_stream_cback * @var{cback}; +FRAME @var{frame}; +int @var{level}; +int @var{source}; +@end example +Print a stack frame briefly. @var{frame} should be the frame id +and @var{level} should be its level in the stack (or -1 for level not defined). +This prints the level, the function executing, the arguments, +and the file name and line number.@* +If the pc is not at the beginning of the source line, +the actual pc is printed at the beginning.@* +If @var{source} is 1, print the source line as well.@* +If @var{source} is -1, print ONLY the source line.@* +(print_stack_frame) +@end deftypefun + + +@deftypefun void gdb_print_backtrace (cback, @var{count}, @var{from_tty}) +@example +struct gdb_stream_cback * @var{cback}; +int @var{count}; +int @var{from_tty}; +@end example +Print briefly all stack frames or just the innermost @var{count} frames.@* +(backtrace_command) +@end deftypefun + + +@deftypefun FRAME gdb_find_relative_frame (FRAME @var{frame}, int * @var{level_offset_ptr}) +Find a frame a certain number of levels away from @var{frame}. +@var{level_offset_ptr} points to an int containing the number of levels. +Positive means go to earlier frames (up); negative, the reverse. +The int that contains the number of levels is counted toward +zero as the frames for those levels are found. +If the top or bottom frame is reached, that frame is returned, +but the final value of @var{*level_offset_ptr} is nonzero and indicates +how much farther the original request asked to go. +@end deftypefun + + +@deftypefun FRAME gdb_select_frame_downward (int @var{count}) +@deftypefunx FRAME gdb_select_frame_upward (int @var{count}) +Simply a combination of find_relative_frame and select_frame. +Returns the newly selected frame.@* +(down_silently_command, up_silently_command) +@end deftypefun + + +@deftypefun void gdb_frame_info (struct gdb_stream_cback * @var{cback}, FRAME @var{frame}) +Print verbosely the selected the argument @var{frame}. +This means absolutely all information in the frame is printed.@* +(frame_info) +@end deftypefun + + +@node Expressions, Values, Stack, top +@comment node-name, next, previous, up +@chapter How to Parse and Evaluate Expressions +@cindex parsing +@cindex expressions +@cindex {expression evaluation} +@cindex evaluation + + +@deftp Type {struct expression *} +This represents a parsed expression as might be used for a +breakpoint condition. +@end deftp + + +@deftp Type {struct block} +Describes a lexical environment. +@end deftp + +See also `Values' +See also `Examining' + + +@deftypefun struct expression * parse_exp_1 (char ** @var{stringptr}, struct block * @var{block} int @var{comma}) +Read an expression from the string @code{*@var{stringptr}} points to, +parse it, and return a pointer to a struct expression that we malloc. +Use @var{block} as the lexical context for variable names; +if @var{block} is zero, use the block of the selected stack frame. +Meanwhile, advance @code{*@var{stringptr}} to point after the expression, +at the first nonwhite character that is not part of the expression +(possibly a null character). + +If @var{comma} is nonzero, stop if a comma is reached. +(See `Stack' for information about the selected frame) +@end deftypefun + + +@deftypefun gdb_error_t gdb_evaluate_expression (value * @var{value_out}, struct expression * @var{exp}) +Evaluate an expression. See `values' for more information about +the return type.@* +(evaluate_expression) +@end deftypefun + + +@deftypefun value gdb_evaluate_type (struct expression @var{*exp}) +Evaluate an expression, avoiding all memory references +and getting a value whose type alone is correct.@* +(evaluate_type) +@end deftypefun + + + +@node Values, Examining, Expressions, top +@comment node-name, next, previous, up +@chapter Data from the Inferior, the Values of Expressions +@cindex values +@cindex {expression values} + +Values are allocated by functions such as @code{gdb_evaluate_expression}. +All currently allocated values are on the list @code{all_values} and can be +freed by calling @code{gdb_free_all_values}. + +To preserve a value across calls to @code{gdb_free_all_values}, use +@code{gdb_release_value}. Values added to the history list are automaticly +released. To free a released value use @code{gdb_free_value}. + + +@deftypefun void gdb_free_value (value) +Free the memory associated with a released value. +Do not call this function except on values that have been +passed to @code{gdb_release_value}.@* +(gdb_value_free) +@end deftypefun + + +@deftypefun void gdb_free_all_values (void) +Free all allocated values which haven't been released. +This should be called periodically from outside the dynamic +scope of libgdb functions.@* +(free_all_values) +@end deftypefun + + +@deftypefun void gdb_release_value (value @var{val}) +Remove a value from the list @code{all_values} in order to +protect it from @code{gdb_free_all_values}.@* +(release_value) +@end deftypefun + + +There is a `history list' -- a numbered list of values for +future reference. These can be referred to in expressions, +for example. + +@deftypefun int gdb_record_latest_value (value @var{val}) +Add a value to the history list.@* +(record_latest_value) +@end deftypefun + + +@deftypefun value gdb_access_value_history (int @var{index}) +Retrieve a value from the history list.@* +(access_value_history) +@end deftypefun + + +[[[At the moment, the only libgdb use for values is + string formatting (see `Examining'). So, they are treated + as opaque. It'd be useful to expose more of them in the long run.]]] + + +@node Examining, Types, Values, top +@comment node-name, next, previous, up +@chapter Formatting Values as Strings +@cindex examining +@cindex printing +@cindex formatting +@cindex {pretty printing} + + +Many functions in this section use @code{struct gdb_stream_cback}. +That structure is explained in `Basics'. + + +@deftypefun void gdb_print_formatted (struct gdb_stream_cback * @var{cback}, value @var{val}, int @var{format}, int @var{size}) +Print value @var{val} on a stream according to @var{format}, a letter or 0. +Do not end with a newline. +0 means print @var{val} according to its own type. +@var{size} is the letter for the size of datum being printed. +This is used to pad hex numbers so they line up.@* +(print_formatted) +@end deftypefun + + +@deftypefun static void gdb_printf_command (struct gdb_stream_cback * @var{cback}, char * @var{format}, value * @var{values}, int @var{n_values})@* +(printf_command) +@end deftypefun + + +@deftypefun int gdb_value_print (struct gdb_stream_cback * @var{cback}, @var{value}, int @var{format}, enum @var{val_prettyprint}) +Print the value @var{val} in C-ish syntax on @var{stream}. +@var{format} is a format-letter, or 0 for print in natural format of data type. +If the object printed is a string pointer, returns +the number of string bytes printed. +[[[implementation: watch the change in argument order]]]@* +(value_print) +@end deftypefun + + + -- IDIOM: This prints the values of all convenience variables: +@example +for (var = internalvars; var; var = var->next) +{ +printf_filtered ("$%s = ", var->name); +value_print (var->value, stdout, 0, Val_pretty_default); +printf_filtered ("\n"); +} +@end example + + +@deftypefun int gdb_print_insn (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{memaddr}) +Print the instruction at @var{memaddr} and return the +length of the instruction in bytes.@* +(print_insn) +@end deftypefun + + +@deftypefun void gdb_print_address (struct gdb_stream_cback * @var{cback}, CORE_ADDR @var{addr}) +Print address @var{addr} symbolically on @var{stream}. +First print it as a number. Then perhaps print +@code{<SYMBOL + OFFSET>} after the number.@* +(print_address) +@end deftypefun + + + -- IDIOM: This is the core of a dissasemble command: +@example +for (pc = low; pc < high; ) +{ + print_address (pc, stdout); + printf_filtered (":\t"); + pc += print_insn (pc, stdout); + printf_filtered ("\n"); +} +@end example +Advice for computing pc extents like @code{low} and @code{high} +can be found in `Symtabs' -- for example, @code{gdb_find_line_pc_range}.@* +(disassemble_command) + + +@deftypefun void gdb_print_registers (struct gdb_stream_cback * @var{cback}, int @var{regnum}, int @var{fpregs}, int @var{fancy}) +Print the values of registers. +@var{regnum} can be -1 (print all the registers) or a specific register number. +If @var{regnum} is -1, @var{fpregs} determines whether floating point registers are +shown.@* +(info registers, info all-registers, nofp_registers_info, all_registers_info) +@end deftypefun + + +@deftypefun char * gdb_register_name (int @var{i}) +Look up a register name by number. +@end deftypefun + + +@deftypefun int gdb_parse_register_name (char ** @var{name}) +Parse a register name and advance a text pointer. +Return -1 for bogus names. +@end deftypefun + + +@deftypefun CORE_ADDR gdb_read_pc () +Return the contents of the inferior's program counter. +@end deftypefun + + +@deftypefun int gdb_is_stepping () +If true, the inferior is stopped after being stepped. +@end deftypefun + + +@deftypefun void gdb_current_breakpoints (gdb_int_cback) +Call a callback for each of the current breakpoints.@* +(program_info) +@end deftypefun + + +@deftypefun int gdb_stop_signal () +Return the signal that stopped the inferior. +@end deftypefun + + +@deftypefun char * strsigno (int) +Return a symbolic name for a signal. +@end deftypefun + + +@deftypefun void gdb_target_info (struct gdb_stream_cback *) +Print status information about target we're accessing.@* +(target_files_info, e.g. child_files_info) +@end deftypefun + + +float_info +[[[what is appropriate?]]] + + +@deftypefun void gdb_address_info (struct gdb_stream_cback * @var{cback}, char * @var{symbol}); +Like the `info address' command -- show where @var{symbol} +is located.@* +(address_info) +@end deftypefun + + +@node Types, top, Examining, top +@comment node-name, next, previous, up +@chapter Examining the Types of an Inferior's Data +@cindex types + + +@deftp Type {struct type} +@code{struct type *} is used to represent a type. For example, that is +the type returned by the macro @code{VALUE_TYPE(val)} which yields the +type of inferior data recorded in @code{val}. (see `evaluate_type' in +`Expressions'). +@end deftp + + +@deftypefun void type_print (@var{type}, @var{varstring}, @var{stream_cback}, @var{show}) +@example +struct type @var{*type}; +char @var{*varstring}; +struct gdb_stream_cback * @var{stream_cback}; +FILE @var{*stream}; +int @var{show}; +@end example +Print a description of a type @var{type} in the form of a declaration of a +variable named @var{varstring}. (@var{varstring} is demangled if necessary.) +Output goes to @var{stream_cback}. + +If @var{show} is positive, we show the contents of the outermost level +of structure even if there is a type name that could be used instead. +If @var{show} is negative, we never show the details of elements' types. +(See `Basics' for an explanation of `struct gdb_stream_cback'). +@end deftypefun + + +[[[In the long run, we need something to programmaticly read off type + structures in a machine/language independent way.]]] + |