This file documents libgdb, the GNU library for symbolic debuggers.

Copyright 1993 Cygnus Support

Permission is granted to ...

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:

 -- Function: const char ** gdb_warranty ()
     (warranty_info) Return a pointer to the text of the GDB disclaimer.

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.

Copying
*******

blah blah

Overview
********

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

Programming Conventions for Libgdb Clients
******************************************

Naming Conventions
==================

Names intentionally exported from libgdb all begin gdb_ as in gdb_use_file.

Error Returns
=============

Libgdb functions that might not succeed generally have a return type of gdb_error_t.

 -- Function: const char * gdb_error_msg (gdb_error_t ERROR)
     returns a reasonable error message for ERROR.

Blocking I/O
============

[[[....]]]

Global Parameters
=================

the current directory
---------------------

 -- Function: gdb_error_t gdb_cd (char * DIR)
     Specify gdb's default directory as well as the working directory for the inferior (when first started).

     (cd_command)

 -- Function: char * gdb_copy_pwd ()
     Make a copy of the name of gdb's default directory.

     (pwd_command)

controlling the input/output radix
----------------------------------

 -- Function: gdb_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)

 -- Function: gdb_error_t gdb_set_input_radix (int)
 -- Function: gdb_error_t gdb_set_output_radix (int)
 -- Function: gdb_error_t gdb_set_radix (int)
     Valid output radixes are only 0 (heuristic), 10, and 16.

     (set_radix)

manipulating environments
-------------------------

 -- Type: struct environ

          struct environ
          {
            int allocated;
            char ** vector;
          }

     A `struct environ' holds a description of environment variable bindings.

 -- Function: struct environ * gdb_make_environ ()
     Create a new (empty) environment.

     (make_environ)

 -- Function: void gdb_free_environ (struct environ *)
     Free an environment allocated by `gdb_make_environ'.

     (free_environ)

 -- Function: void gdb_init_environ (struct environ * env)
     Copy the processes environment into ENV.

     (init_environ)

 -- Function: char ** gdb_get_in_environ (const struct environ * ENV, const char * VAR)
     Look up the binding of VAR in ENV.

     (get_in_environ)

 -- Function: void gdb_set_in_environ (struct environ * ENV, const char * VAR, const char * VALUE)
     Lookup/bind variables within an environment. (set_in_environ)

legal notices
-------------

 -- Function: char ** gdb_copying ()
 -- Function: 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)

the inferior's terminal
-----------------------

 -- Function: void gdb_inferiors_io (int STD_IN, int STD_OUT, int STD_ERR)
     Assert that the given descriptors should be copied into descriptors 0, 1, and 2 of the inferior when it is next run.

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.

     struct a_gdb_cback;
     typedef void (*a_gdb_cback_fn) (struct a_gdb_cback *,
                                     int, char *);

Suppose the client wants the callback to be implemented by 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:

     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;

stream callbacks
----------------

A common kind of callback takes just a character pointer, presumed to point to part or all of an informational message.

     struct gdb_stream_cback;
     typedef void (*gdb_stream_cback_fn) (struct gdb_stream_cback *,
     				     char *);

integer callbacks
-----------------

Another common kind of callback takes just an integer.

     struct gdb_int_cback;
     typedef void (*gdb_int_cback_fn) (struct gdb_int_cback *, int);

Selecting Targets and Symbol Tables for Debugging
*************************************************

 -- Function: gdb_error_t gdb_use_file (char * FILENAME)
     Arrange to read both executable code and symbol table information from FILENAME.

     This is exactly equivalent to a sequence of two calls:

            gdb_use_exec_file (filename);
            gdb_use_symbol_file (filename);

     (file_command)

 -- Function: gdb_error_t gdb_use_exec_file (char * FILENAME)
     Read the code to debug from `filename'.

     (exec_file_command)

 -- Function: char * gdb_get_exec_file ()
     Return the name of the executable file as a string or 0 if there is none.

 -- Function: gdb_error_t gdb_use_core (char * 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 FILENAME is NULL, no core file is used.

     (core_file_command)

 -- Function: gdb_error_t gdb_use_symbol_file (char * 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 gdb_symbol_file_add for finer control over the symbol table.

     (symbol_file_command)

 -- Function: gdb_error_t gdb_symbol_file_add (NAME, VERBOSE, TEXT_ADDR, REPLACE, EAGER)
     Arrange to read additional symbol table information from the file `name'.

     The arguments are:

       - struct gdb_stream_cback * INFO_OUT

          Callback to handle informational output.

       - char * NAME

          If not 0, verbose output will occur.

       - int BE_VERBOSE

          Regulates the amount of informational output produced.

       - CORE_ADDR TEXT_ADDR

          is the address at which the named file is presumed to have been loaded.

       - int REPLACE

          If not 0, this will become the only file in the symbol table -- all previously loaded symbol table information will be discarded.

       - int READNOW

          If not 0, eagerly read symbols from this file,otherwise symbols will only be read lazily (as needed).

 -- Function: char * gdb_copy_exec_path ()
     Make a copy of the execution path.

     [[[implement: strsave(get_in_environ (inferior_environ, "PATH"));]]]

     (path_info)

 -- Function: void gdb_mod_exec_path (char * DIRNAMES)
     Add zero or more directories to the front of the execution path. DIRNAMES should be a colon separated list of directory names.

     (path_command)

 -- Function: gdb_error_t gdb_target_device (char * NAME)
     Connects the libgdb host environment to a target machine or process.

     (target foo)

 -- Function: gdb_error_t gdb_set_baud (int RATE)
     If using a remote target connected by a serial port, use RATE as the communication speed.

 -- Function: gdb_error_t gdb_set_target_debugging (int LEVEL)
     Choose the level of verboseness of with which a remote target produces debugging output.

Accessing symbol tables and debugging information.
**************************************************

 -- Type: struct symtab
     Each source file is represented by a struct symtab. In many contexts, struct symtab * is used in preference to a char * filename to refer to the source.

 -- Function: char * gdb_symtab_to_filename (struct symtab *)
 -- Function: char * gdb_symtab_to_dirname (struct symtab *)
     Return the location of the file corresponding to this symtab. gdb_symtab_to_dirname might return NULL if no directory is known. gdb_symtab_to_line_count might return -1 if line number information is unavailable.

 -- Function: int gdb_symtab_to_line_count (struct symtab *)
     (See also `Source')

 -- Function: struct symtab * gdb_filename_to_symtab (char * FILENAME)
     Lookup the symbol table of a source file named NAME.

     (lookup_symtab)

 -- Type: struct symtab_and_line

          struct symtab_and_line
          {
            struct symtab *symtab;
            int line;
            CORE_ADDR pc;
            CORE_ADDR end;
          }

     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.

     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.

 -- Function: struct symtab_and_line gdb_find_pc_line (CORE_ADDR PC, int NOTCURRENT)
     Find the source file and line number for a given PC value. Return a structure containing a symtab pointer, a line number, and a pc range for the entire source line. The value's .pc field is NOT the specified PC. 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)

 -- Function: gdb_error_t gdb_find_line (struct symtab_and_line * 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)

 -- Function: struct symtabs_and_lines gdb_decode_line (ARGPTR, FIRSTLN, DEFAULT_SYMTAB, DEFAULT_LINE, CANONICAL)

            char ** argptr;
            int funfirstline;
            struct symtab * default_symtab;
            int default_line;
            char *** canonical;

     Parse a string that specifies a line number in GDB syntax. 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)

 -- Type: struct block *
     Lexical environments in the program are represented by struct block. These are useful as arguements to expression parsing functions (see `Expressions').

 -- Function: 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)

 -- Function: struct block * gdb_get_frame_block (FRAME FRAME)
     This returns the block being executed by a given stack frame (see `Stack')

     (get_frame_block)

 -- Function: int gdb_find_line_pc_range (SYMS, LINE, START_OUT, END_OUT)

          struct symtab * START_OUT;
          int LINE;
          CORE_ADDR * START_OUT;
          CORE_ADDR * END_OUT;

     Find the range of pc values in a line.

     Store the starting pc of the line into *STARTPTR. and the ending pc (start of next line) into *ENDPTR.

     Returns 1 to indicate success.

     Returns 0 if could not find the specified line.

     (find_line_pc_range)

 -- Function: int gdb_find_pc_partial_function (PC, NAME, ADDRESS, ENDADDR)

          CORE_ADDR PC;
          char **NAME;
          CORE_ADDR *ADDRESS;
          CORE_ADDR *ENDADDR;

     Finds the "function" (text symbol) that is smaller than PC but greatest of all of the potential text symbols.  Sets *NAME and/or *ADDRESS conditionally if that pointer is non-null.  If ENDADDR is non-null, then set *ENDADDR to be the end of the function (exclusive), but passing 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 *NAME, *ADDRESS, and *ENDADDR to real information and returns 1.  If it fails, it sets *NAME, *ADDRESS, and *ENDADDR to zero and returns 0.

                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");

     (find_pc_partial_function)

 -- Function: void gdb_list_symbols (INFO_OUT, REGEXP, CLASS, BPT)

          struct gdb_stream_cback * INFO_OUT;
          char * REGEXP;
          int CLASS;
          int BPT;

     List all symbols (if REGEXP is NULL) or all symbols matching REGEXP.

     If CLASS is ...

       * 0, list all symbols except functions, type names, and constants (enums).

       * 1, list only functions.

       * 2, list only type names.

       * 3, list only method names.

     BPT is non-zero if set a breakpoint at the functions we find.

     (variables_info, functions_info, types_info, list_symbols)

 -- Function: int gdb_locals_info (struct gdb_stream_cback * INFO_OUT, FRAME 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 FRAME.

     (locals_info)

 -- Function: int print_frame_arg_vars (struct gdb_stream_cback *, FRAME)
     Similar to `gdb_locals_info'.

     (args_info)

Relating Inferiors to Source Files
**********************************

How to find the source that corresponds to executable code and the executable code that corresponds to a line of source.

 -- Function: char * gdb_copy_source_fullname (struct symtab *S)
     Return a copy of the full path name to a source file. (See `Symtabs' for more information about filenames and symbol tables.).

 -- Function: int gdb_open_source_file (struct symtab *S)
     Open a source file corresponding to S.  Returns a file descriptor or negative number for error. [[[We may decide not to provide this function.]]]

     (open_source_file)

 -- Function: int gdb_source_line_pos (struct symtab * S, int LINENO)
     Return the byte offset of a given line of source or a negative number if LINENO is out of range.

     (find_source_lines)

-- IDIOM: The gdb command `show directories'.

       puts_filtered ("Source directories searched: ");
       puts_filtered (source_path);
       puts_filtered ("\n");

(show_directories)

 -- Function: char * gdb_source_path ()
     Return the path in which source files are sought.

     (source_path)

 -- Function: void gdb_modify_source_path (char * DIRNAMES)
     Change the source path according to dirnames.

     (directory_command)

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)

Creating, Continuing, and Stepping Through an Inferior Process
**************************************************************

 -- Function: gdb_error_t gdb_target_create_inferior (EXEC, ARGS, ENVIRON)

          char * EXEC_FILE;
          char * INFERIOR_ARGS;
          char ** INFERIOR_ENVIRONMENT_VECTOR;

     Create a running inferior. [[[I think the exec_file parameter is redundant.  Perhaps this will take only two arguments.]]]

     (run_command, target_create_inferior)

 -- Function: int gdb_target_has_execution ()
     Return non-0 if an inferior is running.

     (target_has_execution)

 -- Function: 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)

 -- Function: gdb_error_t gdb_step_1 (SKIP_SUBS, SINGLE_INST, REPEAT_COUNT)

          int skip_subs;
          int single_inst;
          int repeat_count;

     Continue a program a little bit.  Roughly:

              for (; count > 0; --count)
                gdb_clear_proceed_status ();
                gdb_proceed (...);

     (next_command, nexti_command, step_command, stepi_command)

-- IDIOM: Continuing a program where it stopped.

       gdb_clear_proceed_status ();
       gdb_proceed ((CORE_ADDR) -1, -1, 0);

(continue_command)

-- IDIOM: Continuing a program giving it a specified signal.

       gdb_clear_proceed_status ();
       gdb_proceed ((CORE_ADDR) -1, signum, 0);

(signal_command)

 -- Function: char * strtosigno (char * STR)
     (Typical use:)

            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 ();

-- IDIOM: Continuing a program at a specified address.

       gdb_clear_proceed_status ();
       gdb_proceed (addr, 0, 0);

(jump_command)

 -- Function: 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)

 -- Function: 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 gdb_proceed.

     [[[Some of these should be documented, others hidden.]]]

            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);

     (clear_proceed_status)

 -- Function: void gdb_proceed (CORE_ADDR ADDR, int SIGNAL, int STEP)
     Basic routine for continuing the program in various fashions.

     ADDR is the address to resume at, or -1 for resume where stopped.

     SIGNAL is the signal to give it, or 0 for none, or -1 for act according to how it stopped.

     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 gdb_clear_proceed_status before calling proceed. (See the documentation for gdb_clear_proceed_status for more parameters to gdb_proceed).

     (proceed)

 -- Function: gdb_error_t gdb_return (value RETURN_VALUE, FRAME FRAME)
     Make FRAME return to VALUE to it's caller. Unlike the other functions in this section, this doesn't call proceed. (return_command)

 -- Function: int gdb_inferior_pid ()
     0 or the valid pid of an inferior.

 -- Function: gdb_error_t gdb_attach (int 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)

 -- Function: gdb_error_t gdb_detach (int 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)

Using Breakpoints, Signaling an Inferior
****************************************

 -- Type: struct breakpoint
     Breakpoints are typically represented struct breakpoint *.

 -- Function: struct breakpoint * gdb_find_breakpoint (int)
     Find a breakpoint given it's number (return 0 if it doesn't exist).

 -- Function: gdb_error_t gdb_set_break (struct breakpoint * BRK_OUT, struct symtab_and_line)
 -- Function: gdb_error_t gdb_set_tbreak (struct breakpoint *, struct symtab_and_line)
 -- Function: 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)

 -- Function: gdb_error_t gdb_set_watchpt (BRK_OUT, EXP_STRING, EXP, EXP_VALID_BLOCK)

          struct breakpoint * BRK_OUT;
          char * EXP_STRING;
          struct expression * EXP;
          struct block * EXPRESSION_VALID_BLOCK;

     Set a watchpoint for the given expression.

     (watch_command)

 -- Function: void gdb_set_ignore_count (int BPTNUM, int COUNT)
     Set ignore-count of breakpoint number BPTNUM to COUNT.

     (set_ignore_count)

 -- Function: struct gdb_bp_condition * gdb_set_condition (BP, EXP_STR, COND)

          int PBTNUM;
          char * EXP_STR;
          struct gdb_bp_condition * COND;

          typedef int (*gdb_bp_fn) (struct gdb_bp_condition *, int bp_num);
          struct gdb_bp_condition
          {
            gdb_bp_fn fn;
          };

     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)

 -- Function: gdb_error_t gdb_enable_breakpoint (struct breakpoint * BPT, int ONCE)
 -- Function: gdb_error_t gdb_disable_breakpoint (struct breakpoint * BPT)
     Enable/disable a breakpoint.  If `once' is not 0, the breakpoint is only temporarily enabled.

     (enable_breakpoint, disable_breakpoint, enable_command)

 -- Function: gdb_error_t gdb_delete_breakpoint (struct breakpoint * BPT)
     Delete a breakpoint and clean up all traces of it in the data structures.

     (delete_breakpoint)

 -- Function: void gdb_clear_breakpoints (struct symtabs_and_lines * SALS)
     Clear breakpoints from a list of program locations as might be returned by `gdb_decode_line' (see `Symtabs').

     (clear_command)

 -- Function: static struct symtabs_and_lines get_catch_sals (int 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]]]

 -- Type: struct breakpoint_cback

          typedef void (*breakpoint_cback_fn) (struct breakpoint_cback *, int bp_num);
          struct breakpoint_cback
          {
            breakpoint_cback_fn fn;
          };

     Breakpoints can have an associated function which is called when the program is stopped by that breakpoint.

     (commands_command)

 -- Function: struct breakpoint_cback * gdb_set_breakpoint_cback (int 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.]]]

 -- Function: struct breakpoint_cback * gdb_get_breakpoint_cback (int BP_NUM)

 -- Function: void gdb_breakpoints_info (struct gdb_stream_cback, int BP_NUM, int WATCHES)
     Print information on breakpoint number BNUM, or -1 if all. If WATCHES is zero, process only breakpoints; if 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)

 -- Function: 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)

 -- Function: void gdb_handle_command (char * ARGS)
     Takes arguments like the gdb command `handle' and has the same effect.

     (handle_command)

 -- Function: void gdb_signals_info (struct gdb_stream_cback *)
     Show how signals are handled.

     (signals_info)

Accessing An Inferior's Execution Stack
***************************************

 -- Type: FRAME
     This type representing active stack frames in the inferior. Consider this type opaque.

 -- Function: 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)

 -- Function: FRAME gdb_get_caller_frame (FRAME FRAME)
     Return the frame that called FRAME.

     If FRAME is the original frame (it has no caller), return 0.

     (get_prev_frame)

 -- Function: FRAME gdb_get_called_frame (FRAME FRAME)
     Return the frame that FRAME calls (0 if FRAME is the innermost frame).

     (get_next_frame)

 -- Function: FRAME gdb_parse_frame_specification (char * FRAME_EXP)
     Read a frame specification in whatever the appropriate format is. Call error() If the specification is in any way invalid (i.e. this function never returns NULL).

     (parse_frame_specification)

 -- Function: CORE_ADDR get_frame_pc (FRAME FRAME)

     (Example use: Implementing disassemble_command)

     (get_frame_pc)

 -- Function: FRAME gdb_selected_frame ()
     The "selected" stack frame is used by default for local and arg access. May be NULL, for no selected frame.

     (variable selected_frame)

 -- Function: 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)

 -- Function: void gdb_select_frame (FRAME FRAME, int LEVEL)
     Select frame FRAME, and note that its stack level is LEVEL. LEVEL may be -1 if an actual level number is not known. Calls set_language to establish the correct language for the selected frame.

-- IDIOM: Computing Frame Levels

     /* 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++;
     }

 -- Function: void gdb_print_stack_frame (CBACK, FRAME, LEVEL, SOURCE)

          struct gdb_stream_cback * CBACK;
          FRAME FRAME;
          int LEVEL;
          int SOURCE;

     Print a stack frame briefly.  FRAME should be the frame id and 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 SOURCE is 1, print the source line as well.

     If SOURCE is -1, print ONLY the source line.

     (print_stack_frame)

 -- Function: void gdb_print_backtrace (cback, COUNT, FROM_TTY)

          struct gdb_stream_cback * CBACK;
          int COUNT;
          int FROM_TTY;

     Print briefly all stack frames or just the innermost COUNT frames.

     (backtrace_command)

 -- Function: FRAME gdb_find_relative_frame (FRAME FRAME, int * LEVEL_OFFSET_PTR)
     Find a frame a certain number of levels away from FRAME. 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 *LEVEL_OFFSET_PTR is nonzero and indicates how much farther the original request asked to go.

 -- Function: FRAME gdb_select_frame_downward (int COUNT)
 -- Function: FRAME gdb_select_frame_upward (int COUNT)
     Simply a combination of find_relative_frame and select_frame. Returns the newly selected frame.

     (down_silently_command, up_silently_command)

 -- Function: void gdb_frame_info (struct gdb_stream_cback * CBACK, FRAME FRAME)
     Print verbosely the selected the argument FRAME. This means absolutely all information in the frame is printed.

     (frame_info)

How to Parse and Evaluate Expressions
*************************************

 -- Type: struct expression *
     This represents a parsed expression as might be used for a breakpoint condition.

 -- Type: struct block
     Describes a lexical environment.

See also `Values' See also `Examining'

 -- Function: struct expression * parse_exp_1 (char ** STRINGPTR, struct block * BLOCK int COMMA)
     Read an expression from the string *STRINGPTR points to, parse it, and return a pointer to a  struct expression  that we malloc. Use BLOCK as the lexical context for variable names; if BLOCK is zero, use the block of the selected stack frame. Meanwhile, advance *STRINGPTR to point after the expression, at the first nonwhite character that is not part of the expression (possibly a null character).

     If COMMA is nonzero, stop if a comma is reached. (See `Stack' for information about the selected frame)

 -- Function: gdb_error_t gdb_evaluate_expression (value * VALUE_OUT, struct expression * EXP)
     Evaluate an expression.  See `values' for more information about the return type.

     (evaluate_expression)

 -- Function: value gdb_evaluate_type (struct expression *EXP)
     Evaluate an expression, avoiding all memory references and getting a value whose type alone is correct.

     (evaluate_type)

Data from the Inferior, the Values of Expressions
*************************************************

Values are allocated by functions such as gdb_evaluate_expression. All currently allocated values are on the list all_values and can be freed by calling gdb_free_all_values.

To preserve a value across calls to gdb_free_all_values, use gdb_release_value.  Values added to the history list are automaticly released.  To free a released value use gdb_free_value.

 -- Function: 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 gdb_release_value.

     (gdb_value_free)

 -- Function: 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)

 -- Function: void gdb_release_value (value VAL)
     Remove a value from the list all_values in order to protect it from gdb_free_all_values.

     (release_value)

There is a `history list' -- a numbered list of values for future reference.  These can be referred to in expressions, for example.

 -- Function: int gdb_record_latest_value (value VAL)
     Add a value to the history list.

     (record_latest_value)

 -- Function: value gdb_access_value_history (int INDEX)
     Retrieve a value from the history list.

     (access_value_history)

[[[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.]]]

Formatting Values as Strings
****************************

Many functions in this section use struct gdb_stream_cback. That structure is explained in `Basics'.

 -- Function: void gdb_print_formatted (struct gdb_stream_cback * CBACK, value VAL, int FORMAT, int SIZE)
     Print value VAL on a stream according to FORMAT, a letter or 0. Do not end with a newline. 0 means print VAL according to its own type. SIZE is the letter for the size of datum being printed. This is used to pad hex numbers so they line up.

     (print_formatted)

 -- Function: static void gdb_printf_command (struct gdb_stream_cback * CBACK, char * FORMAT, value * VALUES, int N_VALUES)

     (printf_command)

 -- Function: int gdb_value_print (struct gdb_stream_cback * CBACK, VALUE, int FORMAT, enum VAL_PRETTYPRINT)
     Print the value VAL in C-ish syntax on STREAM. 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)

-- IDIOM: This prints the values of all convenience variables:

     for (var = internalvars; var; var = var->next)
     {
     printf_filtered ("$%s = ", var->name);
     value_print (var->value, stdout, 0, Val_pretty_default);
     printf_filtered ("\n");
     }

 -- Function: int gdb_print_insn (struct gdb_stream_cback * CBACK, CORE_ADDR MEMADDR)
     Print the instruction at MEMADDR and return the length of the instruction in bytes.

     (print_insn)

 -- Function: void gdb_print_address (struct gdb_stream_cback * CBACK, CORE_ADDR ADDR)
     Print address ADDR symbolically on STREAM. First print it as a number.  Then perhaps print <SYMBOL + OFFSET> after the number.

     (print_address)

-- IDIOM: This is the core of a dissasemble command:

     for (pc = low; pc < high; )
     {
       print_address (pc, stdout);
       printf_filtered (":\t");
       pc += print_insn (pc, stdout);
       printf_filtered ("\n");
     }

Advice for computing pc extents like low and high can be found in `Symtabs' -- for example,  gdb_find_line_pc_range.

(disassemble_command)

 -- Function: void gdb_print_registers (struct gdb_stream_cback * CBACK, int REGNUM, int FPREGS, int FANCY)
     Print the values of registers. REGNUM can be -1 (print all the registers) or a specific register number. If REGNUM is -1, FPREGS determines whether floating point registers are shown.

     (info registers, info all-registers, nofp_registers_info, all_registers_info)

 -- Function: char * gdb_register_name (int I)
     Look up a register name by number.

 -- Function: int gdb_parse_register_name (char ** NAME)
     Parse a register name and advance a text pointer. Return -1 for bogus names.

 -- Function: CORE_ADDR gdb_read_pc ()
     Return the contents of the inferior's program counter.

 -- Function: int gdb_is_stepping ()
     If true, the inferior is stopped after being stepped.

 -- Function: void gdb_current_breakpoints (gdb_int_cback)
     Call a callback for each of the current breakpoints.

     (program_info)

 -- Function: int gdb_stop_signal ()
     Return the signal that stopped the inferior.

 -- Function: char * strsigno (int)
     Return a symbolic name for a signal.

 -- Function: void gdb_target_info (struct gdb_stream_cback *)
     Print status information about target we're accessing.

     (target_files_info, e.g. child_files_info)

float_info [[[what is appropriate?]]]

 -- Function: void gdb_address_info (struct gdb_stream_cback * CBACK, char * SYMBOL);
     Like the `info address' command -- show where SYMBOL is located.

     (address_info)

Examining the Types of an Inferior's Data
*****************************************

 -- Type: struct type
     struct type * is used to represent a type.  For example, that is the type returned by the macro VALUE_TYPE(val) which yields the type of inferior data recorded in val.  (see `evaluate_type' in `Expressions').

 -- Function: void type_print (TYPE, VARSTRING, STREAM_CBACK, SHOW)

          struct type *TYPE;
          char *VARSTRING;
          struct gdb_stream_cback * STREAM_CBACK;
          FILE *STREAM;
          int SHOW;

     Print a description of a type TYPE in the form of a declaration of a variable named VARSTRING.  (VARSTRING is demangled if necessary.) Output goes to STREAM_CBACK.

     If 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 SHOW is negative, we never show the details of elements' types. (See `Basics' for an explanation of `struct gdb_stream_cback').

[[[In the long run, we need something to programmaticly read off type structures in a machine/language independent way.]]]