Extending GDBN using Guile
==========================

You can extend GDBN using the Guile implementation of the Scheme programming language (http://www.gnu.org/software/guile/). This feature is available only if GDBN was configured using --with-guile.

Guile Introduction
------------------

Guile is an implementation of the Scheme programming language and is the GNU project's official extension language.

Guile support in GDBN follows the Python support in GDBN reasonably closely, so concepts there should carry over. However, some things are done differently where it makes sense.

GDBN requires Guile version 3.0, 2.2, or 2.0.

Guile scripts used by GDBN should be installed in DATA-DIRECTORY/guile, where DATA-DIRECTORY is the data directory as determined at GDBN startup (see Data Files). This directory, known as the guile directory, is automatically added to the Guile Search Path in order to allow the Guile interpreter to locate all scripts installed at this location.

Guile Commands
--------------

GDBN provides two commands for accessing the Guile interpreter:

guile-repl
gr
     The guile-repl command can be used to start an interactive Guile prompt or repl.  To return to GDBN, type ,q or the EOF character (e.g., Ctrl-D on an empty prompt).  These commands do not take any arguments.

guile [SCHEME-EXPRESSION]
gu [SCHEME-EXPRESSION]
     The guile command can be used to evaluate a Scheme expression.

     If given an argument, GDBN will pass the argument to the Guile interpreter for evaluation.

          (GDBP) guile (display (+ 20 3)) (newline)
          23

     The result of the Scheme expression is displayed using normal Guile rules.

          (GDBP) guile (+ 20 3)
          23

     If you do not provide an argument to guile, it will act as a multi-line command, like define.  In this case, the Guile script is made up of subsequent command lines, given after the guile command.  This command list is terminated using a line containing end.  For example:

          (GDBP) guile
          >(display 23)
          >(newline)
          >end
          23

It is also possible to execute a Guile script from the GDBN interpreter:

source script-name
     The script name must end with .scm and GDBN must be configured to recognize the script language based on filename extension using the script-extension setting.  See Extending GDB.

guile (load "script-name")
     This method uses the load Guile function. It takes a string argument that is the name of the script to load. See the Guile documentation for a description of this function. (see Loading (GNU Guile Reference Manual)).

Guile API
---------

You can get quick online help for GDBN's Guile API by issuing the command help guile, or by issuing the command ,help from an interactive Guile session.  Furthermore, most Guile procedures provided by GDBN have doc strings which can be obtained with ,describe PROCEDURE-NAME or ,d PROCEDURE-NAME from the Guile interactive prompt.

Basic Guile
...........

At startup, GDBN overrides Guile's current-output-port and current-error-port to print using GDBN's output-paging streams. A Guile program which outputs to one of these streams may have its output interrupted by the user (see Screen Size).  In this situation, a Guile signal exception is thrown with value SIGINT.

Guile's history mechanism uses the same naming as GDBN's, namely the user of dollar-variables (e.g., $1, $2, etc.). The results of evaluations in Guile and in GDB are counted separately, $1 in Guile is not the same value as $1 in GDBN.

GDBN is not thread-safe.  If your Guile program uses multiple threads, you must be careful to only call GDBN-specific functions in the GDBN thread.

Some care must be taken when writing Guile code to run in GDBN.  Two things are worth noting in particular:

  * GDBN installs handlers for SIGCHLD and SIGINT. Guile code must not override these, or even change the options using sigaction.  If your program changes the handling of these signals, GDBN will most likely stop working correctly.  Note that it is unfortunately common for GUI toolkits to install a SIGCHLD handler.

  * GDBN takes care to mark its internal file descriptors as close-on-exec.  However, this cannot be done in a thread-safe way on all platforms.  Your Guile programs should be aware of this and should both create new file descriptors with the close-on-exec flag set and arrange to close unneeded file descriptors before starting a child process.

GDBN introduces a new Guile module, named gdb.  All methods and classes added by GDBN are placed in this module. GDBN does not automatically import the gdb module, scripts must do this themselves.  There are various options for how to import a module, so GDBN leaves the choice of how the gdb module is imported to the user. To simplify interactive use, it is recommended to add one of the following to your ~/.gdbinit.

     guile (use-modules (gdb))

     guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))

Which one to choose depends on your preference. The second one adds gdb: as a prefix to all module functions and variables.

The rest of this manual assumes the gdb module has been imported without any prefix.  See the Guile documentation for use-modules for more information (see Using Guile Modules (GNU Guile Reference Manual)).

Example:

     (gdb) guile (value-type (make-value 1))
     ERROR: Unbound variable: value-type
     Error while executing Scheme code.
     (gdb) guile (use-modules (gdb))
     (gdb) guile (value-type (make-value 1))
     int
     (gdb)

The (gdb) module provides these basic Guile functions.

 -- Scheme Procedure: execute command [#:from-tty boolean]
     [#:to-string boolean]
     Evaluate COMMAND, a string, as a GDBN CLI command. If a GDBN exception happens while COMMAND runs, it is translated as described in Guile Exception Handling.

     FROM-TTY specifies whether GDBN ought to consider this command as having originated from the user invoking it interactively. It must be a boolean value.  If omitted, it defaults to #f.

     By default, any output produced by COMMAND is sent to GDBN's standard output (and to the log output if logging is turned on).  If the TO-STRING parameter is #t, then output will be collected by execute and returned as a string.  The default is #f, in which case the return value is unspecified.  If TO-STRING is #t, the GDBN virtual terminal will be temporarily set to unlimited width and height, and its pagination will be disabled; see Screen Size.

 -- Scheme Procedure: history-ref number
     Return a value from GDBN's value history (see Value History).  The NUMBER argument indicates which history element to return. If NUMBER is negative, then GDBN will take its absolute value and count backward from the last element (i.e., the most recent element) to find the value to return.  If NUMBER is zero, then GDBN will return the most recent element.  If the element specified by NUMBER doesn't exist in the value history, a gdb:error exception will be raised.

     If no exception is raised, the return value is always an instance of <gdb:value> (see Values From Inferior In Guile).

     Note: GDBN's value history is independent of Guile's. $1 in GDBN's value history contains the result of evaluating an expression from GDBN's command line and $1 from Guile's history contains the result of evaluating an expression from Guile's command line.

 -- Scheme Procedure: history-append! value
     Append VALUE, an instance of <gdb:value>, to GDBN's value history.  Return its index in the history.

     Putting into history values returned by Guile extensions will allow the user convenient access to those values via CLI history facilities.

 -- Scheme Procedure: parse-and-eval expression
     Parse EXPRESSION as an expression in the current language, evaluate it, and return the result as a <gdb:value>. The EXPRESSION must be a string.

     This function can be useful when implementing a new command (see Commands In Guile), as it provides a way to parse the command's arguments as an expression. It is also is useful when computing values. For example, it is the only way to get the value of a convenience variable (see Convenience Vars) as a <gdb:value>.

Guile Configuration
...................

GDBN provides these Scheme functions to access various configuration parameters.

 -- Scheme Procedure: data-directory
     Return a string containing GDBN's data directory. This directory contains GDBN's ancillary files.

 -- Scheme Procedure: guile-data-directory
     Return a string containing GDBN's Guile data directory. This directory contains the Guile modules provided by GDBN.

 -- Scheme Procedure: gdb-version
     Return a string containing the GDBN version.

 -- Scheme Procedure: host-config
     Return a string containing the host configuration. This is the string passed to --host when GDBN was configured.

 -- Scheme Procedure: target-config
     Return a string containing the target configuration. This is the string passed to --target when GDBN was configured.

GDB Scheme Data Types
.....................

The values exposed by GDBN to Guile are known as GDBN objects.  There are several kinds of GDBN object, and each is disjoint from all other types known to Guile.

 -- Scheme Procedure: gdb-object-kind object
     Return the kind of the GDBN object, e.g., <gdb:breakpoint>, as a symbol.

GDBN defines the following object types:

<gdb:arch>
     See Architectures In Guile.

<gdb:block>
     See Blocks In Guile.

<gdb:block-symbols-iterator>
     See Blocks In Guile.

<gdb:breakpoint>
     See Breakpoints In Guile.

<gdb:command>
     See Commands In Guile.

<gdb:exception>
     See Guile Exception Handling.

<gdb:frame>
     See Frames In Guile.

<gdb:iterator>
     See Iterators In Guile.

<gdb:lazy-string>
     See Lazy Strings In Guile.

<gdb:objfile>
     See Objfiles In Guile.

<gdb:parameter>
     See Parameters In Guile.

<gdb:pretty-printer>
     See Guile Pretty Printing API.

<gdb:pretty-printer-worker>
     See Guile Pretty Printing API.

<gdb:progspace>
     See Progspaces In Guile.

<gdb:symbol>
     See Symbols In Guile.

<gdb:symtab>
     See Symbol Tables In Guile.

<gdb:sal>
     See Symbol Tables In Guile.

<gdb:type>
     See Types In Guile.

<gdb:field>
     See Types In Guile.

<gdb:value>
     See Values From Inferior In Guile.

The following GDBN objects are managed internally so that the Scheme function eq? may be applied to them.

<gdb:arch>

<gdb:block>

<gdb:breakpoint>

<gdb:frame>

<gdb:objfile>

<gdb:progspace>

<gdb:symbol>

<gdb:symtab>

<gdb:type>

Guile Exception Handling
........................

When executing the guile command, Guile exceptions uncaught within the Guile code are translated to calls to the GDBN error-reporting mechanism.  If the command that called guile does not handle the error, GDBN will terminate it and report the error according to the setting of the guile print-stack parameter.

The guile print-stack parameter has three settings:

none
     Nothing is printed.

message
     An error message is printed containing the Guile exception name, the associated value, and the Guile call stack backtrace at the point where the exception was raised.  Example:

          (GDBP) guile (display foo)
          ERROR: In procedure memoize-variable-access!:
          ERROR: Unbound variable: foo
          Error while executing Scheme code.

full
     In addition to an error message a full backtrace is printed.

          (GDBP) set guile print-stack full
          (GDBP) guile (display foo)
          Guile Backtrace:
          In ice-9/boot-9.scm:
           157: 10 [catch #t #<catch-closure 2c76e20> ...]
          In unknown file:
             ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
          In ice-9/boot-9.scm:
           157: 8 [catch #t #<catch-closure 2c76d20> ...]
          In unknown file:
             ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
             ?: 6 [call-with-input-string "(display foo)" ...]
          In ice-9/boot-9.scm:
          2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
          In ice-9/eval-string.scm:
            44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
            37: 3 [lp (display foo)]
          In ice-9/eval.scm:
           387: 2 [eval # ()]
           393: 1 [eval #<memoized foo> ()]
          In unknown file:
             ?: 0 [memoize-variable-access! #<memoized foo> ...]

          ERROR: In procedure memoize-variable-access!:
          ERROR: Unbound variable: foo
          Error while executing Scheme code.

GDBN errors that happen in GDBN commands invoked by Guile code are converted to Guile exceptions.  The type of the Guile exception depends on the error.

Guile procedures provided by GDBN can throw the standard Guile exceptions like wrong-type-arg and out-of-range.

User interrupt (via C-c or by typing q at a pagination prompt) is translated to a Guile signal exception with value SIGINT.

GDBN Guile procedures can also throw these exceptions:

gdb:error
     This exception is a catch-all for errors generated from within GDBN.

gdb:invalid-object
     This exception is thrown when accessing Guile objects that wrap underlying GDBN objects have become invalid.  For example, a <gdb:breakpoint> object becomes invalid if the user deletes it from the command line.  The object still exists in Guile, but the object it represents is gone.  Further operations on this breakpoint will throw this exception.

gdb:memory-error
     This exception is thrown when an operation tried to access invalid memory in the inferior.

gdb:pp-type-error
     This exception is thrown when a Guile pretty-printer passes a bad object to GDBN.

The following exception-related procedures are provided by the (gdb) module.

 -- Scheme Procedure: make-exception key args
     Return a <gdb:exception> object given by its KEY and ARGS, which are the standard Guile parameters of an exception. See the Guile documentation for more information (see Exceptions (GNU Guile Reference Manual)).

 -- Scheme Procedure: exception? object
     Return #t if OBJECT is a <gdb:exception> object. Otherwise return #f.

 -- Scheme Procedure: exception-key exception
     Return the ARGS field of a <gdb:exception> object.

 -- Scheme Procedure: exception-args exception
     Return the ARGS field of a <gdb:exception> object.

Values From Inferior In Guile
.............................

GDBN provides values it obtains from the inferior program in an object of type <gdb:value>.  GDBN uses this object for its internal bookkeeping of the inferior's values, and for fetching values when necessary.

GDBN does not memoize <gdb:value> objects. make-value always returns a fresh object.

     (gdb) guile (eq? (make-value 1) (make-value 1))
     $1 = #f
     (gdb) guile (equal? (make-value 1) (make-value 1))
     $1 = #t

A <gdb:value> that represents a function can be executed via inferior function call with value-call. Any arguments provided to the call must match the function's prototype, and must be provided in the order specified by that prototype.

For example, some-val is a <gdb:value> instance representing a function that takes two integers as arguments.  To execute this function, call it like so:

     (define result (value-call some-val 10 20))

Any values returned from a function call are <gdb:value> objects.

Note: Unlike Python scripting in GDBN, inferior values that are simple scalars cannot be used directly in Scheme expressions that are valid for the value's data type. For example, (+ (parse-and-eval "int_variable") 2) does not work. And inferior values that are structures or instances of some class cannot be accessed using any special syntax, instead value-field must be used.

The following value-related procedures are provided by the (gdb) module.

 -- Scheme Procedure: value? object
     Return #t if OBJECT is a <gdb:value> object. Otherwise return #f.

 -- Scheme Procedure: make-value value [#:type type]
     Many Scheme values can be converted directly to a <gdb:value> with this procedure.  If TYPE is specified, the result is a value of this type, and if VALUE can't be represented with this type an exception is thrown.  Otherwise the type of the result is determined from VALUE as described below.

     See Architectures In Guile, for a list of the builtin types for an architecture.

     Here's how Scheme values are converted when TYPE argument to make-value is not specified:

     Scheme boolean
          A Scheme boolean is converted the boolean type for the current language.

     Scheme integer
          A Scheme integer is converted to the first of a C int, unsigned int, long, unsigned long, long long or unsigned long long type for the current architecture that can represent the value.

          If the Scheme integer cannot be represented as a target integer an out-of-range exception is thrown.

     Scheme real
          A Scheme real is converted to the C double type for the current architecture.

     Scheme string
          A Scheme string is converted to a string in the current target language using the current target encoding. Characters that cannot be represented in the current target encoding are replaced with the corresponding escape sequence.  This is Guile's SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE conversion strategy (see Strings (GNU Guile Reference Manual)).

          Passing TYPE is not supported in this case, if it is provided a wrong-type-arg exception is thrown.

     <gdb:lazy-string>
          If VALUE is a <gdb:lazy-string> object (see Lazy Strings In Guile), then the lazy-string->value procedure is called, and its result is used.

          Passing TYPE is not supported in this case, if it is provided a wrong-type-arg exception is thrown.

     Scheme bytevector
          If VALUE is a Scheme bytevector and TYPE is provided, VALUE must be the same size, in bytes, of values of type TYPE, and the result is essentially created by using memcpy.

          If VALUE is a Scheme bytevector and TYPE is not provided, the result is an array of type uint8 of the same length.

 -- Scheme Procedure: value-optimized-out? value
     Return #t if the compiler optimized out VALUE, thus it is not available for fetching from the inferior. Otherwise return #f.

 -- Scheme Procedure: value-address value
     If VALUE is addressable, returns a <gdb:value> object representing the address. Otherwise, #f is returned.

 -- Scheme Procedure: value-type value
     Return the type of VALUE as a <gdb:type> object (see Types In Guile).

 -- Scheme Procedure: value-dynamic-type value
     Return the dynamic type of VALUE.  This uses C++ run-time type information (RTTI) to determine the dynamic type of the value.  If the value is of class type, it will return the class in which the value is embedded, if any.  If the value is of pointer or reference to a class type, it will compute the dynamic type of the referenced object, and return a pointer or reference to that type, respectively.  In all other cases, it will return the value's static type.

     Note that this feature will only work when debugging a C++ program that includes RTTI for the object in question.  Otherwise, it will just return the static type of the value as in ptype foo. See ptype.

 -- Scheme Procedure: value-cast value type
     Return a new instance of <gdb:value> that is the result of casting VALUE to the type described by TYPE, which must be a <gdb:type> object.  If the cast cannot be performed for some reason, this method throws an exception.

 -- Scheme Procedure: value-dynamic-cast value type
     Like value-cast, but works as if the C++ dynamic_cast operator were used.  Consult a C++ reference for details.

 -- Scheme Procedure: value-reinterpret-cast value type
     Like value-cast, but works as if the C++ reinterpret_cast operator were used.  Consult a C++ reference for details.

 -- Scheme Procedure: value-dereference value
     For pointer data types, this method returns a new <gdb:value> object whose contents is the object pointed to by VALUE.  For example, if foo is a C pointer to an int, declared in your C program as

          int *foo;

     then you can use the corresponding <gdb:value> to access what foo points to like this:

          (define bar (value-dereference foo))

     The result bar will be a <gdb:value> object holding the value pointed to by foo.

     A similar function value-referenced-value exists which also returns <gdb:value> objects corresponding to the values pointed to by pointer values (and additionally, values referenced by reference values).  However, the behavior of value-dereference differs from value-referenced-value by the fact that the behavior of value-dereference is identical to applying the C unary operator * on a given value.  For example, consider a reference to a pointer ptrref, declared in your C++ program as

          typedef int *intptr;
          ...
          int val = 10;
          intptr ptr = &val;
          intptr &ptrref = ptr;

     Though ptrref is a reference value, one can apply the method value-dereference to the <gdb:value> object corresponding to it and obtain a <gdb:value> which is identical to that corresponding to val.  However, if you apply the method value-referenced-value, the result would be a <gdb:value> object identical to that corresponding to ptr.

          (define scm-ptrref (parse-and-eval "ptrref"))
          (define scm-val (value-dereference scm-ptrref))
          (define scm-ptr (value-referenced-value scm-ptrref))

     The <gdb:value> object scm-val is identical to that corresponding to val, and scm-ptr is identical to that corresponding to ptr.  In general, value-dereference can be applied whenever the C unary operator * can be applied to the corresponding C value.  For those cases where applying both value-dereference and value-referenced-value is allowed, the results obtained need not be identical (as we have seen in the above example).  The results are however identical when applied on <gdb:value> objects corresponding to pointers (<gdb:value> objects with type code TYPE_CODE_PTR) in a C/C++ program.

 -- Scheme Procedure: value-referenced-value value
     For pointer or reference data types, this method returns a new <gdb:value> object corresponding to the value referenced by the pointer/reference value.  For pointer data types, value-dereference and value-referenced-value produce identical results.  The difference between these methods is that value-dereference cannot get the values referenced by reference values.  For example, consider a reference to an int, declared in your C++ program as

          int val = 10;
          int &ref = val;

     then applying value-dereference to the <gdb:value> object corresponding to ref will result in an error, while applying value-referenced-value will result in a <gdb:value> object identical to that corresponding to val.

          (define scm-ref (parse-and-eval "ref"))
          (define err-ref (value-dereference scm-ref))      ;; error
          (define scm-val (value-referenced-value scm-ref)) ;; ok

     The <gdb:value> object scm-val is identical to that corresponding to val.

 -- Scheme Procedure: value-reference-value value
     Return a new <gdb:value> object which is a reference to the value encapsulated by <gdb:value> object VALUE.

 -- Scheme Procedure: value-rvalue-reference-value value
     Return a new <gdb:value> object which is an rvalue reference to the value encapsulated by <gdb:value> object VALUE.

 -- Scheme Procedure: value-const-value value
     Return a new <gdb:value> object which is a const version of <gdb:value> object VALUE.

 -- Scheme Procedure: value-field value field-name
     Return field FIELD-NAME from <gdb:value> object VALUE.

 -- Scheme Procedure: value-subscript value index
     Return the value of array VALUE at index INDEX. The VALUE argument must be a subscriptable <gdb:value> object.

 -- Scheme Procedure: value-call value arg-list
     Perform an inferior function call, taking VALUE as a pointer to the function to call. Each element of list ARG-LIST must be a <gdb:value> object or an object that can be converted to a value. The result is the value returned by the function.

 -- Scheme Procedure: value->bool value
     Return the Scheme boolean representing <gdb:value> VALUE. The value must be ``integer like''.  Pointers are ok.

 -- Scheme Procedure: value->integer
     Return the Scheme integer representing <gdb:value> VALUE. The value must be ``integer like''.  Pointers are ok.

 -- Scheme Procedure: value->real
     Return the Scheme real number representing <gdb:value> VALUE. The value must be a number.

 -- Scheme Procedure: value->bytevector
     Return a Scheme bytevector with the raw contents of <gdb:value> VALUE.  No transformation, endian or otherwise, is performed.

 -- Scheme Procedure: value->string value
     [#:encoding encoding] [#:errors errors]
     [#:length length]
     If VALUE> represents a string, then this method converts the contents to a Guile string.  Otherwise, this method will throw an exception.

     Values are interpreted as strings according to the rules of the current language.  If the optional length argument is given, the string will be converted to that length, and will include any embedded zeroes that the string may contain.  Otherwise, for languages where the string is zero-terminated, the entire string will be converted.

     For example, in C-like languages, a value is a string if it is a pointer to or an array of characters or ints of type wchar_t, char16_t, or char32_t.

     If the optional ENCODING argument is given, it must be a string naming the encoding of the string in the <gdb:value>, such as "ascii", "iso-8859-6" or "utf-8".  It accepts the same encodings as the corresponding argument to Guile's scm_from_stringn function, and the Guile codec machinery will be used to convert the string.  If ENCODING is not given, or if ENCODING is the empty string, then either the target-charset (see Character Sets) will be used, or a language-specific encoding will be used, if the current language is able to supply one.

     The optional ERRORS argument is one of #f, error or substitute.  error and substitute must be symbols. If ERRORS is not specified, or if its value is #f, then the default conversion strategy is used, which is set with the Scheme function set-port-conversion-strategy!. If the value is 'error then an exception is thrown if there is any conversion error.  If the value is 'substitute then any conversion error is replaced with question marks. See Strings (GNU Guile Reference Manual).

     If the optional LENGTH argument is given, the string will be fetched and converted to the given length. The length must be a Scheme integer and not a <gdb:value> integer.

 -- Scheme Procedure: value->lazy-string value
     [#:encoding encoding] [#:length length]
     If this <gdb:value> represents a string, then this method converts VALUE to a <gdb:lazy-string (see Lazy Strings In Guile).  Otherwise, this method will throw an exception.

     If the optional ENCODING argument is given, it must be a string naming the encoding of the <gdb:lazy-string.  Some examples are: "ascii", "iso-8859-6" or "utf-8".  If the ENCODING argument is an encoding that GDBN does not recognize, GDBN will raise an error.

     When a lazy string is printed, the GDBN encoding machinery is used to convert the string during printing.  If the optional ENCODING argument is not provided, or is an empty string, GDBN will automatically select the encoding most suitable for the string type.  For further information on encoding in GDBN please see Character Sets.

     If the optional LENGTH argument is given, the string will be fetched and encoded to the length of characters specified.  If the LENGTH argument is not provided, the string will be fetched and encoded until a null of appropriate width is found. The length must be a Scheme integer and not a <gdb:value> integer.

 -- Scheme Procedure: value-lazy? value
     Return #t if VALUE has not yet been fetched from the inferior. Otherwise return #f. GDBN does not fetch values until necessary, for efficiency. For example:

          (define myval (parse-and-eval "somevar"))

     The value of somevar is not fetched at this time.  It will be fetched when the value is needed, or when the fetch-lazy procedure is invoked.

 -- Scheme Procedure: make-lazy-value type address
     Return a <gdb:value> that will be lazily fetched from the target.  The object of type <gdb:type> whose value to fetch is specified by its TYPE and its target memory ADDRESS, which is a Scheme integer.

 -- Scheme Procedure: value-fetch-lazy! value
     If VALUE is a lazy value ((value-lazy? value) is #t), then the value is fetched from the inferior. Any errors that occur in the process will produce a Guile exception.

     If VALUE is not a lazy value, this method has no effect.

     The result of this function is unspecified.

 -- Scheme Procedure: value-print value
     Return the string representation (print form) of <gdb:value> VALUE.

Arithmetic In Guile
...................

The (gdb) module provides several functions for performing arithmetic on <gdb:value> objects. The arithmetic is performed as if it were done by the target, and therefore has target semantics which are not necessarily those of Scheme.  For example operations work with a fixed precision, not the arbitrary precision of Scheme.

Wherever a function takes an integer or pointer as an operand, GDBN will convert appropriate Scheme values to perform the operation.

 -- Scheme Procedure: value-add a b

 -- Scheme Procedure: value-sub a b

 -- Scheme Procedure: value-mul a b

 -- Scheme Procedure: value-div a b

 -- Scheme Procedure: value-rem a b

 -- Scheme Procedure: value-mod a b

 -- Scheme Procedure: value-pow a b

 -- Scheme Procedure: value-not a

 -- Scheme Procedure: value-neg a

 -- Scheme Procedure: value-pos a

 -- Scheme Procedure: value-abs a

 -- Scheme Procedure: value-lsh a b

 -- Scheme Procedure: value-rsh a b

 -- Scheme Procedure: value-min a b

 -- Scheme Procedure: value-max a b

 -- Scheme Procedure: value-lognot a

 -- Scheme Procedure: value-logand a b

 -- Scheme Procedure: value-logior a b

 -- Scheme Procedure: value-logxor a b

 -- Scheme Procedure: value=? a b

 -- Scheme Procedure: value<? a b

 -- Scheme Procedure: value<=? a b

 -- Scheme Procedure: value>? a b

 -- Scheme Procedure: value>=? a b

Scheme does not provide a not-equal function, and thus Guile support in GDBN does not either.

Types In Guile
..............

GDBN represents types from the inferior in objects of type <gdb:type>.

The following type-related procedures are provided by the (gdb) module.

 -- Scheme Procedure: type? object
     Return #t if OBJECT is an object of type <gdb:type>. Otherwise return #f.

 -- Scheme Procedure: lookup-type name [#:block block]
     This function looks up a type by its NAME, which must be a string.

     If BLOCK is given, it is an object of type <gdb:block>, and NAME is looked up in that scope. Otherwise, it is searched for globally.

     Ordinarily, this function will return an instance of <gdb:type>. If the named type cannot be found, it will throw an exception.

 -- Scheme Procedure: type-code type
     Return the type code of TYPE.  The type code will be one of the TYPE_CODE_ constants defined below.

 -- Scheme Procedure: type-tag type
     Return the tag name of TYPE.  The tag name is the name after struct, union, or enum in C and C++; not all languages have this concept.  If this type has no tag name, then #f is returned.

 -- Scheme Procedure: type-name type
     Return the name of TYPE. If this type has no name, then #f is returned.

 -- Scheme Procedure: type-print-name type
     Return the print name of TYPE. This returns something even for anonymous types. For example, for an anonymous C struct "struct {...}" is returned.

 -- Scheme Procedure: type-sizeof type
     Return the size of this type, in target char units.  Usually, a target's char type will be an 8-bit byte.  However, on some unusual platforms, this type may have a different size.

 -- Scheme Procedure: type-strip-typedefs type
     Return a new <gdb:type> that represents the real type of TYPE, after removing all layers of typedefs.

 -- Scheme Procedure: type-array type n1 [n2]
     Return a new <gdb:type> object which represents an array of this type.  If one argument is given, it is the inclusive upper bound of the array; in this case the lower bound is zero.  If two arguments are given, the first argument is the lower bound of the array, and the second argument is the upper bound of the array.  An array's length must not be negative, but the bounds can be.

 -- Scheme Procedure: type-vector type n1 [n2]
     Return a new <gdb:type> object which represents a vector of this type.  If one argument is given, it is the inclusive upper bound of the vector; in this case the lower bound is zero.  If two arguments are given, the first argument is the lower bound of the vector, and the second argument is the upper bound of the vector.  A vector's length must not be negative, but the bounds can be.

     The difference between an array and a vector is that arrays behave like in C: when used in expressions they decay to a pointer to the first element whereas vectors are treated as first class values.

 -- Scheme Procedure: type-pointer type
     Return a new <gdb:type> object which represents a pointer to TYPE.

 -- Scheme Procedure: type-range type
     Return a list of two elements: the low bound and high bound of TYPE. If TYPE does not have a range, an exception is thrown.

 -- Scheme Procedure: type-reference type
     Return a new <gdb:type> object which represents a reference to TYPE.

 -- Scheme Procedure: type-target type
     Return a new <gdb:type> object which represents the target type of TYPE.

     For a pointer type, the target type is the type of the pointed-to object.  For an array type (meaning C-like arrays), the target type is the type of the elements of the array.  For a function or method type, the target type is the type of the return value.  For a complex type, the target type is the type of the elements.  For a typedef, the target type is the aliased type.

     If the type does not have a target, this method will throw an exception.

 -- Scheme Procedure: type-const type
     Return a new <gdb:type> object which represents a const-qualified variant of TYPE.

 -- Scheme Procedure: type-volatile type
     Return a new <gdb:type> object which represents a volatile-qualified variant of TYPE.

 -- Scheme Procedure: type-unqualified type
     Return a new <gdb:type> object which represents an unqualified variant of TYPE.  That is, the result is neither const nor volatile.

 -- Scheme Procedure: type-num-fields
     Return the number of fields of <gdb:type> TYPE.

 -- Scheme Procedure: type-fields type
     Return the fields of TYPE as a list. For structure and union types, fields has the usual meaning. Range types have two fields, the minimum and maximum values.  Enum types have one field per enum constant.  Function and method types have one field per parameter.  The base types of C++ classes are also represented as fields.  If the type has no fields, or does not fit into one of these categories, an empty list will be returned. See Fields of a type in Guile.

 -- Scheme Procedure: make-field-iterator type
     Return the fields of TYPE as a <gdb:iterator> object. See Iterators In Guile.

 -- Scheme Procedure: type-field type field-name
     Return field named FIELD-NAME in TYPE. The result is an object of type <gdb:field>. See Fields of a type in Guile. If the type does not have fields, or FIELD-NAME is not a field of TYPE, an exception is thrown.

     For example, if some-type is a <gdb:type> instance holding a structure type, you can access its foo field with:

          (define bar (type-field some-type "foo"))

     bar will be a <gdb:field> object.

 -- Scheme Procedure: type-has-field? type name
     Return #t if <gdb:type> TYPE has field named NAME. Otherwise return #f.

Each type has a code, which indicates what category this type falls into.  The available type categories are represented by constants defined in the (gdb) module:

TYPE_CODE_PTR
     The type is a pointer.

TYPE_CODE_ARRAY
     The type is an array.

TYPE_CODE_STRUCT
     The type is a structure.

TYPE_CODE_UNION
     The type is a union.

TYPE_CODE_ENUM
     The type is an enum.

TYPE_CODE_FLAGS
     A bit flags type, used for things such as status registers.

TYPE_CODE_FUNC
     The type is a function.

TYPE_CODE_INT
     The type is an integer type.

TYPE_CODE_FLT
     A floating point type.

TYPE_CODE_VOID
     The special type void.

TYPE_CODE_SET
     A Pascal set type.

TYPE_CODE_RANGE
     A range type, that is, an integer type with bounds.

TYPE_CODE_STRING
     A string type.  Note that this is only used for certain languages with language-defined string types; C strings are not represented this way.

TYPE_CODE_BITSTRING
     A string of bits.  It is deprecated.

TYPE_CODE_ERROR
     An unknown or erroneous type.

TYPE_CODE_METHOD
     A method type, as found in C++.

TYPE_CODE_METHODPTR
     A pointer-to-member-function.

TYPE_CODE_MEMBERPTR
     A pointer-to-member.

TYPE_CODE_REF
     A reference type.

TYPE_CODE_RVALUE_REF
     A C++11 rvalue reference type.

TYPE_CODE_CHAR
     A character type.

TYPE_CODE_BOOL
     A boolean type.

TYPE_CODE_COMPLEX
     A complex float type.

TYPE_CODE_TYPEDEF
     A typedef to some other type.

TYPE_CODE_NAMESPACE
     A C++ namespace.

TYPE_CODE_DECFLOAT
     A decimal floating point type.

TYPE_CODE_INTERNAL_FUNCTION
     A function internal to GDBN.  This is the type used to represent convenience functions (see Convenience Funs).

Further support for types is provided in the (gdb types) Guile module (see Guile Types Module).

Each field is represented as an object of type <gdb:field>.

The following field-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: field? object
     Return #t if OBJECT is an object of type <gdb:field>. Otherwise return #f.

 -- Scheme Procedure: field-name field
     Return the name of the field, or #f for anonymous fields.

 -- Scheme Procedure: field-type field
     Return the type of the field.  This is usually an instance of <gdb:type>, but it can be #f in some situations.

 -- Scheme Procedure: field-enumval field
     Return the enum value represented by <gdb:field> FIELD.

 -- Scheme Procedure: field-bitpos field
     Return the bit position of <gdb:field> FIELD. This attribute is not available for static fields (as in C++).

 -- Scheme Procedure: field-bitsize field
     If the field is packed, or is a bitfield, return the size of <gdb:field> FIELD in bits.  Otherwise, zero is returned; in which case the field's size is given by its type.

 -- Scheme Procedure: field-artificial? field
     Return #t if the field is artificial, usually meaning that it was provided by the compiler and not the user. Otherwise return #f.

 -- Scheme Procedure: field-base-class? field
     Return #t if the field represents a base class of a C++ structure. Otherwise return #f.

Guile Pretty Printing API
.........................

An example output is provided (see Pretty Printing).

A pretty-printer is represented by an object of type <gdb:pretty-printer>. Pretty-printer objects are created with make-pretty-printer.

The following pretty-printer-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: make-pretty-printer name lookup-function
     Return a <gdb:pretty-printer> object named NAME.

     LOOKUP-FUNCTION is a function of one parameter: the value to be printed.  If the value is handled by this pretty-printer, then LOOKUP-FUNCTION returns an object of type <gdb:pretty-printer-worker> to perform the actual pretty-printing. Otherwise LOOKUP-FUNCTION returns #f.

 -- Scheme Procedure: pretty-printer? object
     Return #t if OBJECT is a <gdb:pretty-printer> object. Otherwise return #f.

 -- Scheme Procedure: pretty-printer-enabled? pretty-printer
     Return #t if PRETTY-PRINTER is enabled. Otherwise return #f.

 -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag
     Set the enabled flag of PRETTY-PRINTER to FLAG. The value returned is unspecified.

 -- Scheme Procedure: pretty-printers
     Return the list of global pretty-printers.

 -- Scheme Procedure: set-pretty-printers! pretty-printers
     Set the list of global pretty-printers to PRETTY-PRINTERS. The value returned is unspecified.

 -- Scheme Procedure: make-pretty-printer-worker display-hint to-string children
     Return an object of type <gdb:pretty-printer-worker>.

     This function takes three parameters:

     display-hint
          DISPLAY-HINT provides a hint to GDBN or GDBN front end via MI to change the formatting of the value being printed. The value must be a string or #f (meaning there is no hint). Several values for DISPLAY-HINT are predefined by GDBN:

          array
               Indicate that the object being printed is ``array-like''.  The CLI uses this to respect parameters such as set print elements and set print array.

          map
               Indicate that the object being printed is ``map-like'', and that the children of this value can be assumed to alternate between keys and values.

          string
               Indicate that the object being printed is ``string-like''.  If the printer's to-string function returns a Guile string of some kind, then GDBN will call its internal language-specific string-printing function to format the string.  For the CLI this means adding quotation marks, possibly escaping some characters, respecting set print elements, and the like.

     to-string
          TO-STRING is either a function of one parameter, the <gdb:pretty-printer-worker> object, or #f.

          When printing from the CLI, if the to-string method exists, then GDBN will prepend its result to the values returned by children.  Exactly how this formatting is done is dependent on the display hint, and may change as more hints are added.  Also, depending on the print settings (see Print Settings), the CLI may print just the result of to-string in a stack trace, omitting the result of children.

          If this method returns a string, it is printed verbatim.

          Otherwise, if this method returns an instance of <gdb:value>, then GDBN prints this value.  This may result in a call to another pretty-printer.

          If instead the method returns a Guile value which is convertible to a <gdb:value>, then GDBN performs the conversion and prints the resulting value.  Again, this may result in a call to another pretty-printer.  Guile scalars (integers, floats, and booleans) and strings are convertible to <gdb:value>; other types are not.

          Finally, if this method returns #f then no further operations are peformed in this method and nothing is printed.

          If the result is not one of these types, an exception is raised.

          TO-STRING may also be #f in which case it is left to CHILDREN to print the value.

     children
          CHILDREN is either a function of one parameter, the <gdb:pretty-printer-worker> object, or #f.

          GDBN will call this function on a pretty-printer to compute the children of the pretty-printer's value.

          This function must return a <gdb:iterator> object. Each item returned by the iterator must be a tuple holding two elements.  The first element is the ``name'' of the child; the second element is the child's value.  The value can be any Guile object which is convertible to a GDBN value.

          If CHILDREN is #f, GDBN will act as though the value has no children.

          Children may be hidden from display based on the value of set print max-depth (see Print Settings).

GDBN provides a function which can be used to look up the default pretty-printer for a <gdb:value>:

 -- Scheme Procedure: default-visualizer value
     This function takes a <gdb:value> object as an argument.  If a pretty-printer for this value exists, then it is returned.  If no such printer exists, then this returns #f.

Selecting Guile Pretty-Printers
...............................

There are three sets of pretty-printers that GDBN searches:

  * Per-objfile list of pretty-printers (see Objfiles In Guile).

  * Per-progspace list of pretty-printers (see Progspaces In Guile).

  * The global list of pretty-printers (see Guile Pretty Printing API). These printers are available when debugging any inferior.

Pretty-printer lookup is done by passing the value to be printed to the lookup function of each enabled object in turn. Lookup stops when a lookup function returns a non-#f value or when the list is exhausted. Lookup functions must return either a <gdb:pretty-printer-worker> object or #f.  Otherwise an exception is thrown.

GDBN first checks the result of objfile-pretty-printers of each <gdb:objfile> in the current program space and iteratively calls each enabled lookup function in the list for that <gdb:objfile> until a non-#f object is returned. If no pretty-printer is found in the objfile lists, GDBN then searches the result of progspace-pretty-printers of the current program space, calling each enabled function until a non-#f object is returned. After these lists have been exhausted, it tries the global pretty-printers list, obtained with pretty-printers, again calling each enabled function until a non-#f object is returned.

The order in which the objfiles are searched is not specified.  For a given list, functions are always invoked from the head of the list, and iterated over sequentially until the end of the list, or a <gdb:pretty-printer-worker> object is returned.

For various reasons a pretty-printer may not work. For example, the underlying data structure may have changed and the pretty-printer is out of date.

The consequences of a broken pretty-printer are severe enough that GDBN provides support for enabling and disabling individual printers.  For example, if print frame-arguments is on, a backtrace can become highly illegible if any argument is printed with a broken printer.

Pretty-printers are enabled and disabled from Scheme by calling set-pretty-printer-enabled!. See Guile Pretty Printing API.

Writing a Guile Pretty-Printer
..............................

A pretty-printer consists of two basic parts: a lookup function to determine if the type is supported, and the printer itself.

Here is an example showing how a std::string printer might be written.  See Guile Pretty Printing API, for details.

     (define (make-my-string-printer value)
       "Print a my::string string"
       (make-pretty-printer-worker
        "string"
        (lambda (printer)
          (value-field value "_data"))
        #f))

And here is an example showing how a lookup function for the printer example above might be written.

     (define (str-lookup-function pretty-printer value)
       (let ((tag (type-tag (value-type value))))
         (and tag
              (string-prefix? "std::string<" tag)
              (make-my-string-printer value))))

Then to register this printer in the global printer list:

     (append-pretty-printer!
      (make-pretty-printer "my-string" str-lookup-function))

The example lookup function extracts the value's type, and attempts to match it to a type that it can pretty-print.  If it is a type the printer can pretty-print, it will return a <gdb:pretty-printer-worker> object. If not, it returns #f.

We recommend that you put your core pretty-printers into a Guile package.  If your pretty-printers are for use with a library, we further recommend embedding a version number into the package name. This practice will enable GDBN to load multiple versions of your pretty-printers at the same time, because they will have different names.

You should write auto-loaded code (see Guile Auto-loading) such that it can be evaluated multiple times without changing its meaning.  An ideal auto-load file will consist solely of imports of your printer modules, followed by a call to a register pretty-printers with the current objfile.

Taken as a whole, this approach will scale nicely to multiple inferiors, each potentially using a different library version. Embedding a version number in the Guile package name will ensure that GDBN is able to load both sets of printers simultaneously. Then, because the search for pretty-printers is done by objfile, and because your auto-loaded code took care to register your library's printers with a specific objfile, GDBN will find the correct printers for the specific version of the library used by each inferior.

To continue the my::string example, this code might appear in (my-project my-library v1):

     (use-modules (gdb))
     (define (register-printers objfile)
       (append-objfile-pretty-printer!
        (make-pretty-printer "my-string" str-lookup-function)))

And then the corresponding contents of the auto-load file would be:

     (use-modules (gdb) (my-project my-library v1))
     (register-printers (current-objfile))

The previous example illustrates a basic pretty-printer. There are a few things that can be improved on. The printer only handles one type, whereas a library typically has several types.  One could install a lookup function for each desired type in the library, but one could also have a single lookup function recognize several types.  The latter is the conventional way this is handled. If a pretty-printer can handle multiple data types, then its subprinters are the printers for the individual data types.

The (gdb printing) module provides a formal way of solving this problem (see Guile Printing Module). Here is another example that handles multiple types.

These are the types we are going to pretty-print:

     struct foo { int a, b; };
     struct bar { struct foo x, y; };

Here are the printers:

     (define (make-foo-printer value)
       "Print a foo object"
       (make-pretty-printer-worker
        "foo"
        (lambda (printer)
          (format #f "a=<~a> b=<~a>"
                  (value-field value "a") (value-field value "a")))
        #f))

     (define (make-bar-printer value)
       "Print a bar object"
       (make-pretty-printer-worker
        "foo"
        (lambda (printer)
          (format #f "x=<~a> y=<~a>"
                  (value-field value "x") (value-field value "y")))
        #f))

This example doesn't need a lookup function, that is handled by the (gdb printing) module.  Instead a function is provided to build up the object that handles the lookup.

     (use-modules (gdb printing))

     (define (build-pretty-printer)
       (let ((pp (make-pretty-printer-collection "my-library")))
         (pp-collection-add-tag-printer "foo" make-foo-printer)
         (pp-collection-add-tag-printer "bar" make-bar-printer)
         pp))

And here is the autoload support:

     (use-modules (gdb) (my-library))
     (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))

Finally, when this printer is loaded into GDBN, here is the corresponding output of info pretty-printer:

     (gdb) info pretty-printer
     my_library.so:
       my-library
         foo
         bar

Commands In Guile
.................

You can implement new GDBN CLI commands in Guile.  A CLI command object is created with the make-command Guile function, and added to GDBN with the register-command! Guile function. This two-step approach is taken to separate out the side-effect of adding the command to GDBN from make-command.

There is no support for multi-line commands, that is commands that consist of multiple lines and are terminated with end.

 -- Scheme Procedure: make-command name [#:invoke invoke]
     [#:command-class command-class]
     [#:completer-class completer]
     [#:prefix? prefix] [#:doc doc-string]

     The argument NAME is the name of the command.  If NAME consists of multiple words, then the initial words are looked for as prefix commands.  In this case, if one of the prefix commands does not exist, an exception is raised.

     The result is the <gdb:command> object representing the command. The command is not usable until it has been registered with GDBN with register-command!.

     The rest of the arguments are optional.

     The argument INVOKE is a procedure of three arguments: SELF, ARGS and FROM-TTY.  The argument SELF is the <gdb:command> object representing the command. The argument ARGS is a string representing the arguments passed to the command, after leading and trailing whitespace has been stripped. The argument FROM-TTY is a boolean flag and specifies whether the command should consider itself to have been originated from the user invoking it interactively.  If this function throws an exception, it is turned into a GDBN error call. Otherwise, the return value is ignored.

     The argument COMMAND-CLASS is one of the COMMAND_ constants defined below.  This argument tells GDBN how to categorize the new command in the help system.  The default is COMMAND_NONE.

     The argument COMPLETER is either #f, one of the COMPLETE_ constants defined below, or a procedure, also defined below. This argument tells GDBN how to perform completion for this command.  If not provided or if the value is #f, then no completion is performed on the command.

     The argument PREFIX is a boolean flag indicating whether the new command is a prefix command; sub-commands of this command may be registered.

     The argument DOC-STRING is help text for the new command. If no documentation string is provided, the default value ``This command is not documented.'' is used.

 -- Scheme Procedure: register-command! command
     Add COMMAND, a <gdb:command> object, to GDBN's list of commands. It is an error to register a command more than once. The result is unspecified.

 -- Scheme Procedure: command? object
     Return #t if OBJECT is a <gdb:command> object. Otherwise return #f.

 -- Scheme Procedure: dont-repeat
     By default, a GDBN command is repeated when the user enters a blank line at the command prompt.  A command can suppress this behavior by invoking the dont-repeat function.  This is similar to the user command dont-repeat, see dont-repeat.

 -- Scheme Procedure: string->argv string
     Convert a string to a list of strings split up according to GDBN's argv parsing rules. It is recommended to use this for consistency. Arguments are separated by spaces and may be quoted. Example:

          scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
          $1 = ("1" "2 \"3" "4 \"5" "6 '7")

 -- Scheme Procedure: throw-user-error message . args
     Throw a gdb:user-error exception. The argument MESSAGE is the error message as a format string, like the FMT argument to the format Scheme function. See Formatted Output (GNU Guile Reference Manual). The argument ARGS is a list of the optional arguments of MESSAGE.

     This is used when the command detects a user error of some kind, say a bad command argument.

          (gdb) guile (use-modules (gdb))
          (gdb) guile
          (register-command! (make-command "test-user-error"
            #:command-class COMMAND_OBSCURE
            #:invoke (lambda (self arg from-tty)
              (throw-user-error "Bad argument ~a" arg))))
          end
          (gdb) test-user-error ugh
          ERROR: Bad argument ugh

 -- completer: self text word
     If the COMPLETER option to make-command is a procedure, it takes three arguments: SELF which is the <gdb:command> object, and TEXT and WORD which are both strings. The argument TEXT holds the complete command line up to the cursor's location.  The argument WORD holds the last word of the command line; this is computed using a word-breaking heuristic.

     All forms of completion are handled by this function, that is, the TAB and M-? key bindings (see Completion), and the complete command (see complete).

     This procedure can return several kinds of values:

       * If the return value is a list, the contents of the list are used as the completions.  It is up to COMPLETER to ensure that the contents actually do complete the word.  An empty list is allowed, it means that there were no completions available.  Only string elements of the list are used; other elements in the list are ignored.

       * If the return value is a <gdb:iterator> object, it is iterated over to obtain the completions.  It is up to completer-procedure to ensure that the results actually do complete the word.  Only string elements of the result are used; other elements in the sequence are ignored.

       * All other results are treated as though there were no available completions.

When a new command is registered, it will have been declared as a member of some general class of commands.  This is used to classify top-level commands in the on-line help system; note that prefix commands are not listed under their own category but rather that of their top-level command.  The available classifications are represented by constants defined in the gdb module:

COMMAND_NONE
     The command does not belong to any particular class.  A command in this category will not be displayed in any of the help categories. This is the default.

COMMAND_RUNNING
     The command is related to running the inferior.  For example, start, step, and continue are in this category. Type help running at the GDBN prompt to see a list of commands in this category.

COMMAND_DATA
     The command is related to data or variables.  For example, call, find, and print are in this category.  Type help data at the GDBN prompt to see a list of commands in this category.

COMMAND_STACK
     The command has to do with manipulation of the stack.  For example, backtrace, frame, and return are in this category.  Type help stack at the GDBN prompt to see a list of commands in this category.

COMMAND_FILES
     This class is used for file-related commands.  For example, file, list and section are in this category. Type help files at the GDBN prompt to see a list of commands in this category.

COMMAND_SUPPORT
     This should be used for ``support facilities'', generally meaning things that are useful to the user when interacting with GDBN, but not related to the state of the inferior.  For example, help, make, and shell are in this category.  Type help support at the GDBN prompt to see a list of commands in this category.

COMMAND_STATUS
     The command is an info-related command, that is, related to the state of GDBN itself.  For example, info, macro, and show are in this category.  Type help status at the GDBN prompt to see a list of commands in this category.

COMMAND_BREAKPOINTS
     The command has to do with breakpoints.  For example, break, clear, and delete are in this category.  Type help
     breakpoints at the GDBN prompt to see a list of commands in this category.

COMMAND_TRACEPOINTS
     The command has to do with tracepoints.  For example, trace, actions, and tfind are in this category.  Type help tracepoints at the GDBN prompt to see a list of commands in this category.

COMMAND_USER
     The command is a general purpose command for the user, and typically does not fit in one of the other categories. Type help user-defined at the GDBN prompt to see a list of commands in this category, as well as the list of gdb macros (see Sequences).

COMMAND_OBSCURE
     The command is only used in unusual circumstances, or is not of general interest to users.  For example, checkpoint, fork, and stop are in this category.  Type help
     obscure at the GDBN prompt to see a list of commands in this category.

COMMAND_MAINTENANCE
     The command is only useful to GDBN maintainers.  The maintenance and flushregs commands are in this category. Type help internals at the GDBN prompt to see a list of commands in this category.

A new command can use a predefined completion function, either by specifying it via an argument at initialization, or by returning it from the completer procedure.  These predefined completion constants are all defined in the gdb module:

COMPLETE_NONE
     This constant means that no completion should be done.

COMPLETE_FILENAME
     This constant means that filename completion should be performed.

COMPLETE_LOCATION
     This constant means that location completion should be done. See Location Specifications.

COMPLETE_COMMAND
     This constant means that completion should examine GDBN command names.

COMPLETE_SYMBOL
     This constant means that completion should be done using symbol names as the source.

COMPLETE_EXPRESSION
     This constant means that completion should be done on expressions. Often this means completing on symbol names, but some language parsers also have support for completing on field names.

The following code snippet shows how a trivial CLI command can be implemented in Guile:

     (gdb) guile
     (register-command! (make-command "hello-world"
       #:command-class COMMAND_USER
       #:doc "Greet the whole world."
       #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
     end
     (gdb) hello-world
     Hello, World!

Parameters In Guile
...................

You can implement new GDBN parameters using Guile (Note that GDBN parameters must not be confused with
Guile’s parameter objects (see Parameters (GNU Guile Reference Manual)).).

There are many parameters that already exist and can be set in GDBN.  Two examples are: set follow-fork and set charset.  Setting these parameters influences certain behavior in GDBN.  Similarly, you can define parameters that can be used to influence behavior in custom Guile scripts and commands.

A new parameter is defined with the make-parameter Guile function, and added to GDBN with the register-parameter! Guile function. This two-step approach is taken to separate out the side-effect of adding the parameter to GDBN from make-parameter.

Parameters are exposed to the user via the set and show commands.  See Help.

 -- Scheme Procedure: make-parameter name
     [#:command-class command-class]
     [#:parameter-type parameter-type]
     [#:enum-list enum-list] [#:set-func set-func]
     [#:show-func show-func] [#:doc doc]
     [#:set-doc set-doc] [#:show-doc show-doc]
     [#:initial-value initial-value]

     The argument NAME is the name of the new parameter.  If NAME consists of multiple words, then the initial words are looked for as prefix parameters.  An example of this can be illustrated with the set print set of parameters.  If NAME is print foo, then print will be searched as the prefix parameter.  In this case the parameter can subsequently be accessed in GDBN as set print foo. If NAME consists of multiple words, and no prefix parameter group can be found, an exception is raised.

     The result is the <gdb:parameter> object representing the parameter. The parameter is not usable until it has been registered with GDBN with register-parameter!.

     The rest of the arguments are optional.

     The argument COMMAND-CLASS should be one of the COMMAND_ constants (see Commands In Guile).  This argument tells GDBN how to categorize the new parameter in the help system. The default is COMMAND_NONE.

     The argument PARAMETER-TYPE should be one of the PARAM_ constants defined below.  This argument tells GDBN the type of the new parameter; this information is used for input validation and completion.  The default is PARAM_BOOLEAN.

     If PARAMETER-TYPE is PARAM_ENUM, then ENUM-LIST must be a list of strings.  These strings represent the possible values for the parameter.

     If PARAMETER-TYPE is not PARAM_ENUM, then the presence of ENUM-LIST will cause an exception to be thrown.

     The argument SET-FUNC is a function of one argument: SELF which is the <gdb:parameter> object representing the parameter. GDBN will call this function when a PARAMETER's value has been changed via the set API (for example, set foo off). The value of the parameter has already been set to the new value. This function must return a string to be displayed to the user. GDBN will add a trailing newline if the string is non-empty. GDBN generally doesn't print anything when a parameter is set, thus typically this function should return "". A non-empty string result should typically be used for displaying warnings and errors.

     The argument SHOW-FUNC is a function of two arguments: SELF which is the <gdb:parameter> object representing the parameter, and SVALUE which is the string representation of the current value. GDBN will call this function when a PARAMETER's show API has been invoked (for example, show foo). This function must return a string, and will be displayed to the user. GDBN will add a trailing newline.

     The argument DOC is the help text for the new parameter. If there is no documentation string, a default value is used.

     The argument SET-DOC is the help text for this parameter's set command.

     The argument SHOW-DOC is the help text for this parameter's show command.

     The argument INITIAL-VALUE specifies the initial value of the parameter. If it is a function, it takes one parameter, the <gdb:parameter> object and its result is used as the initial value of the parameter. The initial value must be valid for the parameter type, otherwise an exception is thrown.

 -- Scheme Procedure: register-parameter! parameter
     Add PARAMETER, a <gdb:parameter> object, to GDBN's list of parameters. It is an error to register a parameter more than once. The result is unspecified.

 -- Scheme Procedure: parameter? object
     Return #t if OBJECT is a <gdb:parameter> object. Otherwise return #f.

 -- Scheme Procedure: parameter-value parameter
     Return the value of PARAMETER which may either be a <gdb:parameter> object or a string naming the parameter.

 -- Scheme Procedure: set-parameter-value! parameter new-value
     Assign PARAMETER the value of NEW-VALUE. The argument PARAMETER must be an object of type <gdb:parameter>. GDBN does validation when assignments are made.

When a new parameter is defined, its type must be specified.  The available types are represented by constants defined in the gdb module:

PARAM_BOOLEAN
     The value is a plain boolean.  The Guile boolean values, #t and #f are the only valid values.

PARAM_AUTO_BOOLEAN
     The value has three possible states: true, false, and auto.  In Guile, true and false are represented using boolean constants, and auto is represented using #:auto.

PARAM_UINTEGER
     The value is an unsigned integer.  The value of 0 should be interpreted to mean ``unlimited''.

PARAM_ZINTEGER
     The value is an integer.

PARAM_ZUINTEGER
     The value is an unsigned integer.

PARAM_ZUINTEGER_UNLIMITED
     The value is an integer in the range [0, INT_MAX]. A value of -1 means ``unlimited'', and other negative numbers are not allowed.

PARAM_STRING
     The value is a string.  When the user modifies the string, any escape sequences, such as \t, \f, and octal escapes, are translated into corresponding characters and encoded into the current host charset.

PARAM_STRING_NOESCAPE
     The value is a string.  When the user modifies the string, escapes are passed through untranslated.

PARAM_OPTIONAL_FILENAME
     The value is a either a filename (a string), or #f.

PARAM_FILENAME
     The value is a filename.  This is just like PARAM_STRING_NOESCAPE, but uses file names for completion.

PARAM_ENUM
     The value is a string, which must be one of a collection of string constants provided when the parameter is created.

Program Spaces In Guile
.......................

A program space, or progspace, represents a symbolic view of an address space. It consists of all of the objfiles of the program. See Objfiles In Guile. See program spaces, for more details about program spaces.

Each progspace is represented by an instance of the <gdb:progspace> smob.  See GDB Scheme Data Types.

The following progspace-related functions are available in the (gdb) module:

 -- Scheme Procedure: progspace? object
     Return #t if OBJECT is a <gdb:progspace> object. Otherwise return #f.

 -- Scheme Procedure: progspace-valid? progspace
     Return #t if PROGSPACE is valid, #f if not. A <gdb:progspace> object can become invalid if the program it refers to is not loaded in GDBN any longer.

 -- Scheme Procedure: current-progspace
     This function returns the program space of the currently selected inferior. There is always a current progspace, this never returns #f. See Inferiors Connections and Programs.

 -- Scheme Procedure: progspaces
     Return a list of all the progspaces currently known to GDBN.

 -- Scheme Procedure: progspace-filename progspace
     Return the absolute file name of PROGSPACE as a string. This is the name of the file passed as the argument to the file or symbol-file commands. If the program space does not have an associated file name, then #f is returned.  This occurs, for example, when GDBN is started without a program to debug.

     A gdb:invalid-object-error exception is thrown if PROGSPACE is invalid.

 -- Scheme Procedure: progspace-objfiles progspace
     Return the list of objfiles of PROGSPACE. The order of objfiles in the result is arbitrary. Each element is an object of type <gdb:objfile>. See Objfiles In Guile.

     A gdb:invalid-object-error exception is thrown if PROGSPACE is invalid.

 -- Scheme Procedure: progspace-pretty-printers progspace
     Return the list of pretty-printers of PROGSPACE. Each element is an object of type <gdb:pretty-printer>. See Guile Pretty Printing API, for more information.

 -- Scheme Procedure: set-progspace-pretty-printers! progspace printer-list
     Set the list of registered <gdb:pretty-printer> objects for PROGSPACE to PRINTER-LIST. See Guile Pretty Printing API, for more information.

Objfiles In Guile
.................

GDBN loads symbols for an inferior from various symbol-containing files (see Files).  These include the primary executable file, any shared libraries used by the inferior, and any separate debug info files (see Separate Debug Files). GDBN calls these symbol-containing files objfiles.

Each objfile is represented as an object of type <gdb:objfile>.

The following objfile-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: objfile? object
     Return #t if OBJECT is a <gdb:objfile> object. Otherwise return #f.

 -- Scheme Procedure: objfile-valid? objfile
     Return #t if OBJFILE is valid, #f if not. A <gdb:objfile> object can become invalid if the object file it refers to is not loaded in GDBN any longer.  All other <gdb:objfile> procedures will throw an exception if it is invalid at the time the procedure is called.

 -- Scheme Procedure: objfile-filename objfile
     Return the file name of OBJFILE as a string, with symbolic links resolved.

 -- Scheme Procedure: objfile-progspace objfile
     Return the <gdb:progspace> that this object file lives in. See Progspaces In Guile, for more on progspaces.

 -- Scheme Procedure: objfile-pretty-printers objfile
     Return the list of registered <gdb:pretty-printer> objects for OBJFILE.  See Guile Pretty Printing API, for more information.

 -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list
     Set the list of registered <gdb:pretty-printer> objects for OBJFILE to PRINTER-LIST.  The PRINTER-LIST must be a list of <gdb:pretty-printer> objects. See Guile Pretty Printing API, for more information.

 -- Scheme Procedure: current-objfile
     When auto-loading a Guile script (see Guile Auto-loading), GDBN sets the ``current objfile'' to the corresponding objfile.  This function returns the current objfile.  If there is no current objfile, this function returns #f.

 -- Scheme Procedure: objfiles
     Return a list of all the objfiles in the current program space.

Accessing inferior stack frames from Guile.
...........................................

When the debugged program stops, GDBN is able to analyze its call stack (see Stack frames).  The <gdb:frame> class represents a frame in the stack.  A <gdb:frame> object is only valid while its corresponding frame exists in the inferior's stack.  If you try to use an invalid frame object, GDBN will throw a gdb:invalid-object exception (see Guile Exception Handling).

Two <gdb:frame> objects can be compared for equality with the equal? function, like:

     (GDBP) guile (equal? (newest-frame) (selected-frame))
     #t

The following frame-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: frame? object
     Return #t if OBJECT is a <gdb:frame> object. Otherwise return #f.

 -- Scheme Procedure: frame-valid? frame
     Returns #t if FRAME is valid, #f if not. A frame object can become invalid if the frame it refers to doesn't exist anymore in the inferior.  All <gdb:frame> procedures will throw an exception if the frame is invalid at the time the procedure is called.

 -- Scheme Procedure: frame-name frame
     Return the function name of FRAME, or #f if it can't be obtained.

 -- Scheme Procedure: frame-arch frame
     Return the <gdb:architecture> object corresponding to FRAME's architecture.  See Architectures In Guile.

 -- Scheme Procedure: frame-type frame
     Return the type of FRAME.  The value can be one of:

     NORMAL_FRAME
          An ordinary stack frame.

     DUMMY_FRAME
          A fake stack frame that was created by GDBN when performing an inferior function call.

     INLINE_FRAME
          A frame representing an inlined function.  The function was inlined into a NORMAL_FRAME that is older than this one.

     TAILCALL_FRAME
          A frame representing a tail call.  See Tail Call Frames.

     SIGTRAMP_FRAME
          A signal trampoline frame.  This is the frame created by the OS when it calls into a signal handler.

     ARCH_FRAME
          A fake stack frame representing a cross-architecture call.

     SENTINEL_FRAME
          This is like NORMAL_FRAME, but it is only used for the newest frame.

 -- Scheme Procedure: frame-unwind-stop-reason frame
     Return an integer representing the reason why it's not possible to find more frames toward the outermost frame.  Use unwind-stop-reason-string to convert the value returned by this function to a string. The value can be one of:

     FRAME_UNWIND_NO_REASON
          No particular reason (older frames should be available).

     FRAME_UNWIND_NULL_ID
          The previous frame's analyzer returns an invalid result.

     FRAME_UNWIND_OUTERMOST
          This frame is the outermost.

     FRAME_UNWIND_UNAVAILABLE
          Cannot unwind further, because that would require knowing the values of registers or memory that have not been collected.

     FRAME_UNWIND_INNER_ID
          This frame ID looks like it ought to belong to a NEXT frame, but we got it for a PREV frame.  Normally, this is a sign of unwinder failure.  It could also indicate stack corruption.

     FRAME_UNWIND_SAME_ID
          This frame has the same ID as the previous one.  That means that unwinding further would almost certainly give us another frame with exactly the same ID, so break the chain.  Normally, this is a sign of unwinder failure.  It could also indicate stack corruption.

     FRAME_UNWIND_NO_SAVED_PC
          The frame unwinder did not find any saved PC, but we needed one to unwind further.

     FRAME_UNWIND_MEMORY_ERROR
          The frame unwinder caused an error while trying to access memory.

     FRAME_UNWIND_FIRST_ERROR
          Any stop reason greater or equal to this value indicates some kind of error.  This special value facilitates writing code that tests for errors in unwinding in a way that will work correctly even if the list of the other values is modified in future GDBN versions.  Using it, you could write:

               (define reason (frame-unwind-stop-readon (selected-frame)))
               (define reason-str (unwind-stop-reason-string reason))
               (if (>= reason FRAME_UNWIND_FIRST_ERROR)
                   (format #t "An error occured: ~s\n" reason-str))

 -- Scheme Procedure: frame-pc frame
     Return the frame's resume address.

 -- Scheme Procedure: frame-block frame
     Return the frame's code block as a <gdb:block> object. See Blocks In Guile.

 -- Scheme Procedure: frame-function frame
     Return the symbol for the function corresponding to this frame as a <gdb:symbol> object, or #f if there isn't one. See Symbols In Guile.

 -- Scheme Procedure: frame-older frame
     Return the frame that called FRAME.

 -- Scheme Procedure: frame-newer frame
     Return the frame called by FRAME.

 -- Scheme Procedure: frame-sal frame
     Return the frame's <gdb:sal> (symtab and line) object. See Symbol Tables In Guile.

 -- Scheme Procedure: frame-read-register frame register
     Return the value of REGISTER in FRAME.  REGISTER should be a string, like pc.

 -- Scheme Procedure: frame-read-var frame variable [#:block block]
     Return the value of VARIABLE in FRAME.  If the optional argument BLOCK is provided, search for the variable from that block; otherwise start at the frame's current block (which is determined by the frame's current program counter).  The VARIABLE must be given as a string or a <gdb:symbol> object, and BLOCK must be a <gdb:block> object.

 -- Scheme Procedure: frame-select frame
     Set FRAME to be the selected frame.  See Examining the Stack.

 -- Scheme Procedure: selected-frame
     Return the selected frame object.  See Selecting a Frame.

 -- Scheme Procedure: newest-frame
     Return the newest frame object for the selected thread.

 -- Scheme Procedure: unwind-stop-reason-string reason
     Return a string explaining the reason why GDBN stopped unwinding frames, as expressed by the given REASON code (an integer, see the frame-unwind-stop-reason procedure above in this section).

Accessing blocks from Guile.
............................

In GDBN, symbols are stored in blocks.  A block corresponds roughly to a scope in the source code.  Blocks are organized hierarchically, and are represented individually in Guile as an object of type <gdb:block>.  Blocks rely on debugging information being available.

A frame has a block.  Please see Frames In Guile, for a more in-depth discussion of frames.

The outermost block is known as the global block.  The global block typically holds public global variables and functions.

The block nested just inside the global block is the static block.  The static block typically holds file-scoped variables and functions.

GDBN provides a method to get a block's superblock, but there is currently no way to examine the sub-blocks of a block, or to iterate over all the blocks in a symbol table (see Symbol Tables In Guile).

Here is a short example that should help explain blocks:

     /* This is in the global block.  */
     int global;

     /* This is in the static block.  */
     static int file_scope;

     /* 'function' is in the global block, and 'argument' is
        in a block nested inside of 'function'.  */
     int function (int argument)
     {
       /* 'local' is in a block inside 'function'.  It may or may
          not be in the same block as 'argument'.  */
       int local;

       {
          /* 'inner' is in a block whose superblock is the one holding
             'local'.  */
          int inner;

          /* If this call is expanded by the compiler, you may see
             a nested block here whose function is 'inline_function'
             and whose superblock is the one holding 'inner'.  */
          inline_function ();
       }
     }

The following block-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: block? object
     Return #t if OBJECT is a <gdb:block> object. Otherwise return #f.

 -- Scheme Procedure: block-valid? block
     Returns #t if <gdb:block> BLOCK is valid, #f if not.  A block object can become invalid if the block it refers to doesn't exist anymore in the inferior.  All other <gdb:block> methods will throw an exception if it is invalid at the time the procedure is called.  The block's validity is also checked during iteration over symbols of the block.

 -- Scheme Procedure: block-start block
     Return the start address of <gdb:block> BLOCK.

 -- Scheme Procedure: block-end block
     Return the end address of <gdb:block> BLOCK.

 -- Scheme Procedure: block-function block
     Return the name of <gdb:block> BLOCK represented as a <gdb:symbol> object. If the block is not named, then #f is returned.

     For ordinary function blocks, the superblock is the static block. However, you should note that it is possible for a function block to have a superblock that is not the static block -- for instance this happens for an inlined function.

 -- Scheme Procedure: block-superblock block
     Return the block containing <gdb:block> BLOCK. If the parent block does not exist, then #f is returned.

 -- Scheme Procedure: block-global-block block
     Return the global block associated with <gdb:block> BLOCK.

 -- Scheme Procedure: block-static-block block
     Return the static block associated with <gdb:block> BLOCK.

 -- Scheme Procedure: block-global? block
     Return #t if <gdb:block> BLOCK is a global block. Otherwise return #f.

 -- Scheme Procedure: block-static? block
     Return #t if <gdb:block> BLOCK is a static block. Otherwise return #f.

 -- Scheme Procedure: block-symbols
     Return a list of all symbols (as <gdb:symbol> objects) in <gdb:block> BLOCK.

 -- Scheme Procedure: make-block-symbols-iterator block
     Return an object of type <gdb:iterator> that will iterate over all symbols of the block. Guile programs should not assume that a specific block object will always contain a given symbol, since changes in GDBN features and infrastructure may cause symbols move across blocks in a symbol table. See Iterators In Guile.

 -- Scheme Procedure: block-symbols-progress?
     Return #t if the object is a <gdb:block-symbols-progress> object. This object would be obtained from the progress element of the <gdb:iterator> object returned by make-block-symbols-iterator.

 -- Scheme Procedure: lookup-block pc
     Return the innermost <gdb:block> containing the given PC value.  If the block cannot be found for the PC value specified, the function will return #f.

Guile representation of Symbols.
................................

GDBN represents every variable, function and type as an entry in a symbol table.  See Examining the Symbol Table. Guile represents these symbols in GDBN with the <gdb:symbol> object.

The following symbol-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: symbol? object
     Return #t if OBJECT is an object of type <gdb:symbol>. Otherwise return #f.

 -- Scheme Procedure: symbol-valid? symbol
     Return #t if the <gdb:symbol> object is valid, #f if not.  A <gdb:symbol> object can become invalid if the symbol it refers to does not exist in GDBN any longer. All other <gdb:symbol> procedures will throw an exception if it is invalid at the time the procedure is called.

 -- Scheme Procedure: symbol-type symbol
     Return the type of SYMBOL or #f if no type is recorded. The result is an object of type <gdb:type>. See Types In Guile.

 -- Scheme Procedure: symbol-symtab symbol
     Return the symbol table in which SYMBOL appears. The result is an object of type <gdb:symtab>. See Symbol Tables In Guile.

 -- Scheme Procedure: symbol-line symbol
     Return the line number in the source code at which SYMBOL was defined. This is an integer.

 -- Scheme Procedure: symbol-name symbol
     Return the name of SYMBOL as a string.

 -- Scheme Procedure: symbol-linkage-name symbol
     Return the name of SYMBOL, as used by the linker (i.e., may be mangled).

 -- Scheme Procedure: symbol-print-name symbol
     Return the name of SYMBOL in a form suitable for output.  This is either name or linkage_name, depending on whether the user asked GDBN to display demangled or mangled names.

 -- Scheme Procedure: symbol-addr-class symbol
     Return the address class of the symbol.  This classifies how to find the value of a symbol.  Each address class is a constant defined in the (gdb) module and described later in this chapter.

 -- Scheme Procedure: symbol-needs-frame? symbol
     Return #t if evaluating SYMBOL's value requires a frame (see Frames In Guile) and #f otherwise.  Typically, local variables will require a frame, but other symbols will not.

 -- Scheme Procedure: symbol-argument? symbol
     Return #t if SYMBOL is an argument of a function. Otherwise return #f.

 -- Scheme Procedure: symbol-constant? symbol
     Return #t if SYMBOL is a constant. Otherwise return #f.

 -- Scheme Procedure: symbol-function? symbol
     Return #t if SYMBOL is a function or a method. Otherwise return #f.

 -- Scheme Procedure: symbol-variable? symbol
     Return #t if SYMBOL is a variable. Otherwise return #f.

 -- Scheme Procedure: symbol-value symbol [#:frame frame]
     Compute the value of SYMBOL, as a <gdb:value>.  For functions, this computes the address of the function, cast to the appropriate type.  If the symbol requires a frame in order to compute its value, then FRAME must be given.  If FRAME is not given, or if FRAME is invalid, then an exception is thrown.

 -- Scheme Procedure: lookup-symbol name [#:block block]
     [#:domain domain]
     This function searches for a symbol by name.  The search scope can be restricted to the parameters defined in the optional domain and block arguments.

     NAME is the name of the symbol.  It must be a string.  The optional BLOCK argument restricts the search to symbols visible in that BLOCK.  The BLOCK argument must be a <gdb:block> object.  If omitted, the block for the current frame is used.  The optional DOMAIN argument restricts the search to the domain type.  The DOMAIN argument must be a domain constant defined in the (gdb) module and described later in this chapter.

     The result is a list of two elements. The first element is a <gdb:symbol> object or #f if the symbol is not found. If the symbol is found, the second element is #t if the symbol is a field of a method's object (e.g., this in C++), otherwise it is #f. If the symbol is not found, the second element is #f.

 -- Scheme Procedure: lookup-global-symbol name [#:domain domain]
     This function searches for a global symbol by name. The search scope can be restricted by the domain argument.

     NAME is the name of the symbol.  It must be a string. The optional DOMAIN argument restricts the search to the domain type. The DOMAIN argument must be a domain constant defined in the (gdb) module and described later in this chapter.

     The result is a <gdb:symbol> object or #f if the symbol is not found.

The available domain categories in <gdb:symbol> are represented as constants in the (gdb) module:

SYMBOL_UNDEF_DOMAIN
     This is used when a domain has not been discovered or none of the following domains apply.  This usually indicates an error either in the symbol information or in GDBN's handling of symbols.

SYMBOL_VAR_DOMAIN
     This domain contains variables, function names, typedef names and enum type values.

SYMBOL_STRUCT_DOMAIN
     This domain holds struct, union and enum type names.

SYMBOL_LABEL_DOMAIN
     This domain contains names of labels (for gotos).

SYMBOL_VARIABLES_DOMAIN
     This domain holds a subset of the SYMBOLS_VAR_DOMAIN; it contains everything minus functions and types.

SYMBOL_FUNCTIONS_DOMAIN
     This domain contains all functions.

SYMBOL_TYPES_DOMAIN
     This domain contains all types.

The available address class categories in <gdb:symbol> are represented as constants in the gdb module:

SYMBOL_LOC_UNDEF
     If this is returned by address class, it indicates an error either in the symbol information or in GDBN's handling of symbols.

SYMBOL_LOC_CONST
     Value is constant int.

SYMBOL_LOC_STATIC
     Value is at a fixed address.

SYMBOL_LOC_REGISTER
     Value is in a register.

SYMBOL_LOC_ARG
     Value is an argument.  This value is at the offset stored within the symbol inside the frame's argument list.

SYMBOL_LOC_REF_ARG
     Value address is stored in the frame's argument list.  Just like LOC_ARG except that the value's address is stored at the offset, not the value itself.

SYMBOL_LOC_REGPARM_ADDR
     Value is a specified register.  Just like LOC_REGISTER except the register holds the address of the argument instead of the argument itself.

SYMBOL_LOC_LOCAL
     Value is a local variable.

SYMBOL_LOC_TYPEDEF
     Value not used.  Symbols in the domain SYMBOL_STRUCT_DOMAIN all have this class.

SYMBOL_LOC_BLOCK
     Value is a block.

SYMBOL_LOC_CONST_BYTES
     Value is a byte-sequence.

SYMBOL_LOC_UNRESOLVED
     Value is at a fixed address, but the address of the variable has to be determined from the minimal symbol table whenever the variable is referenced.

SYMBOL_LOC_OPTIMIZED_OUT
     The value does not actually exist in the program.

SYMBOL_LOC_COMPUTED
     The value's address is a computed location.

Symbol table representation in Guile.
.....................................

Access to symbol table data maintained by GDBN on the inferior is exposed to Guile via two objects: <gdb:sal> (symtab-and-line) and <gdb:symtab>.  Symbol table and line data for a frame is returned from the frame-find-sal <gdb:frame> procedure. See Frames In Guile.

For more information on GDBN's symbol table management, see Examining the Symbol Table.

The following symtab-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: symtab? object
     Return #t if OBJECT is an object of type <gdb:symtab>. Otherwise return #f.

 -- Scheme Procedure: symtab-valid? symtab
     Return #t if the <gdb:symtab> object is valid, #f if not.  A <gdb:symtab> object becomes invalid when the symbol table it refers to no longer exists in GDBN. All other <gdb:symtab> procedures will throw an exception if it is invalid at the time the procedure is called.

 -- Scheme Procedure: symtab-filename symtab
     Return the symbol table's source filename.

 -- Scheme Procedure: symtab-fullname symtab
     Return the symbol table's source absolute file name.

 -- Scheme Procedure: symtab-objfile symtab
     Return the symbol table's backing object file.  See Objfiles In Guile.

 -- Scheme Procedure: symtab-global-block symtab
     Return the global block of the underlying symbol table. See Blocks In Guile.

 -- Scheme Procedure: symtab-static-block symtab
     Return the static block of the underlying symbol table. See Blocks In Guile.

The following symtab-and-line-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: sal? object
     Return #t if OBJECT is an object of type <gdb:sal>. Otherwise return #f.

 -- Scheme Procedure: sal-valid? sal
     Return #t if SAL is valid, #f if not. A <gdb:sal> object becomes invalid when the Symbol table object it refers to no longer exists in GDBN.  All other <gdb:sal> procedures will throw an exception if it is invalid at the time the procedure is called.

 -- Scheme Procedure: sal-symtab sal
     Return the symbol table object (<gdb:symtab>) for SAL.

 -- Scheme Procedure: sal-line sal
     Return the line number for SAL.

 -- Scheme Procedure: sal-pc sal
     Return the start of the address range occupied by code for SAL.

 -- Scheme Procedure: sal-last sal
     Return the end of the address range occupied by code for SAL.

 -- Scheme Procedure: find-pc-line pc
     Return the <gdb:sal> object corresponding to the PC value. If an invalid value of PC is passed as an argument, then the symtab and line attributes of the returned <gdb:sal> object will be #f and 0 respectively.

Manipulating breakpoints using Guile
....................................

Breakpoints in Guile are represented by objects of type <gdb:breakpoint>.  New breakpoints can be created with the make-breakpoint Guile function, and then added to GDBN with the register-breakpoint! Guile function. This two-step approach is taken to separate out the side-effect of adding the breakpoint to GDBN from make-breakpoint.

Support is also provided to view and manipulate breakpoints created outside of Guile.

The following breakpoint-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: make-breakpoint location [#:type type]
     [#:wp-class wp-class] [#:internal internal]
     [#:temporary temporary]
     Create a new breakpoint at LOCATION, a string naming the location of the breakpoint, or an expression that defines a watchpoint. The contents can be any location recognized by the break command, or in the case of a watchpoint, by the watch command.

     The breakpoint is initially marked as invalid. The breakpoint is not usable until it has been registered with GDBN with register-breakpoint!, at which point it becomes valid. The result is the <gdb:breakpoint> object representing the breakpoint.

     The optional TYPE denotes the breakpoint to create. This argument can be either BP_BREAKPOINT or BP_WATCHPOINT, and defaults to BP_BREAKPOINT.

     The optional WP-CLASS argument defines the class of watchpoint to create, if TYPE is BP_WATCHPOINT.  If a watchpoint class is not provided, it is assumed to be a WP_WRITE class.

     The optional INTERNAL argument allows the breakpoint to become invisible to the user.  The breakpoint will neither be reported when registered, nor will it be listed in the output from info breakpoints (but will be listed with the maint info breakpoints command). If an internal flag is not provided, the breakpoint is visible (non-internal).

     The optional TEMPORARY argument makes the breakpoint a temporary breakpoint.  Temporary breakpoints are deleted after they have been hit, after which the Guile breakpoint is no longer usable (although it may be re-registered with register-breakpoint!).

     When a watchpoint is created, GDBN will try to create a hardware assisted watchpoint.  If successful, the type of the watchpoint is changed from BP_WATCHPOINT to BP_HARDWARE_WATCHPOINT for WP_WRITE, BP_READ_WATCHPOINT for WP_READ, and BP_ACCESS_WATCHPOINT for WP_ACCESS. If not successful, the type of the watchpoint is left as WP_WATCHPOINT.

     The available types are represented by constants defined in the gdb module:

     BP_BREAKPOINT
          Normal code breakpoint.

     BP_WATCHPOINT
          Watchpoint breakpoint.

     BP_HARDWARE_WATCHPOINT
          Hardware assisted watchpoint. This value cannot be specified when creating the breakpoint.

     BP_READ_WATCHPOINT
          Hardware assisted read watchpoint. This value cannot be specified when creating the breakpoint.

     BP_ACCESS_WATCHPOINT
          Hardware assisted access watchpoint. This value cannot be specified when creating the breakpoint.

     BP_CATCHPOINT
          Catchpoint. This value cannot be specified when creating the breakpoint.

     The available watchpoint types are represented by constants defined in the (gdb) module:

     WP_READ
          Read only watchpoint.

     WP_WRITE
          Write only watchpoint.

     WP_ACCESS
          Read/Write watchpoint.

 -- Scheme Procedure: register-breakpoint! breakpoint
     Add BREAKPOINT, a <gdb:breakpoint> object, to GDBN's list of breakpoints.  The breakpoint must have been created with make-breakpoint.  One cannot register breakpoints that have been created outside of Guile.  Once a breakpoint is registered it becomes valid. It is an error to register an already registered breakpoint. The result is unspecified.

 -- Scheme Procedure: delete-breakpoint! breakpoint
     Remove BREAKPOINT from GDBN's list of breakpoints. This also invalidates the Guile BREAKPOINT object. Any further attempt to access the object will throw an exception.

     If BREAKPOINT was created from Guile with make-breakpoint it may be re-registered with GDBN, in which case the breakpoint becomes valid again.

 -- Scheme Procedure: breakpoints
     Return a list of all breakpoints. Each element of the list is a <gdb:breakpoint> object.

 -- Scheme Procedure: breakpoint? object
     Return #t if OBJECT is a <gdb:breakpoint> object, and #f otherwise.

 -- Scheme Procedure: breakpoint-valid? breakpoint
     Return #t if BREAKPOINT is valid, #f otherwise. Breakpoints created with make-breakpoint are marked as invalid until they are registered with GDBN with register-breakpoint!. A <gdb:breakpoint> object can become invalid if the user deletes the breakpoint.  In this case, the object still exists, but the underlying breakpoint does not.  In the cases of watchpoint scope, the watchpoint remains valid even if execution of the inferior leaves the scope of that watchpoint.

 -- Scheme Procedure: breakpoint-number breakpoint
     Return the breakpoint's number --- the identifier used by the user to manipulate the breakpoint.

 -- Scheme Procedure: breakpoint-temporary? breakpoint
     Return #t if the breakpoint was created as a temporary breakpoint.  Temporary breakpoints are automatically deleted after they've been hit.  Calling this procedure, and all other procedures other than breakpoint-valid? and register-breakpoint!, will result in an error after the breakpoint has been hit (since it has been automatically deleted).

 -- Scheme Procedure: breakpoint-type breakpoint
     Return the breakpoint's type --- the identifier used to determine the actual breakpoint type or use-case.

 -- Scheme Procedure: breakpoint-visible? breakpoint
     Return #t if the breakpoint is visible to the user when hit, or when the info breakpoints command is run. Otherwise return #f.

 -- Scheme Procedure: breakpoint-location breakpoint
     Return the location of the breakpoint, as specified by the user.  It is a string.  If the breakpoint does not have a location (that is, it is a watchpoint) return #f.

 -- Scheme Procedure: breakpoint-expression breakpoint
     Return the breakpoint expression, as specified by the user.  It is a string. If the breakpoint does not have an expression (the breakpoint is not a watchpoint) return #f.

 -- Scheme Procedure: breakpoint-enabled? breakpoint
     Return #t if the breakpoint is enabled, and #f otherwise.

 -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag
     Set the enabled state of BREAKPOINT to FLAG. If flag is #f it is disabled, otherwise it is enabled.

 -- Scheme Procedure: breakpoint-silent? breakpoint
     Return #t if the breakpoint is silent, and #f otherwise.

     Note that a breakpoint can also be silent if it has commands and the first command is silent.  This is not reported by the silent attribute.

 -- Scheme Procedure: set-breakpoint-silent! breakpoint flag
     Set the silent state of BREAKPOINT to FLAG. If flag is #f the breakpoint is made silent, otherwise it is made non-silent (or noisy).

 -- Scheme Procedure: breakpoint-ignore-count breakpoint
     Return the ignore count for BREAKPOINT.

 -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count
     Set the ignore count for BREAKPOINT to COUNT.

 -- Scheme Procedure: breakpoint-hit-count breakpoint
     Return hit count of BREAKPOINT.

 -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count
     Set the hit count of BREAKPOINT to COUNT. At present, COUNT must be zero.

 -- Scheme Procedure: breakpoint-thread breakpoint
     Return the global-thread-id for thread-specific breakpoint BREAKPOINT.  Return #f if BREAKPOINT is not thread-specific.

 -- Scheme Procedure: set-breakpoint-thread! breakpoint global-thread-id|#f
     Set the thread-id for BREAKPOINT to GLOBAL-THREAD-ID If set to #f, the breakpoint is no longer thread-specific.

 -- Scheme Procedure: breakpoint-task breakpoint
     If the breakpoint is Ada task-specific, return the Ada task id. If the breakpoint is not task-specific (or the underlying language is not Ada), return #f.

 -- Scheme Procedure: set-breakpoint-task! breakpoint task
     Set the Ada task of BREAKPOINT to TASK. If set to #f, the breakpoint is no longer task-specific.

 -- Scheme Procedure: breakpoint-condition breakpoint
     Return the condition of BREAKPOINT, as specified by the user. It is a string.  If there is no condition, return #f.

 -- Scheme Procedure: set-breakpoint-condition! breakpoint condition
     Set the condition of BREAKPOINT to CONDITION, which must be a string.  If set to #f then the breakpoint becomes unconditional.

 -- Scheme Procedure: breakpoint-stop breakpoint
     Return the stop predicate of BREAKPOINT. See set-breakpoint-stop! below in this section.

 -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f
     Set the stop predicate of BREAKPOINT.  The predicate PROCEDURE takes one argument: the <gdb:breakpoint> object. If this predicate is set to a procedure then it is invoked whenever the inferior reaches this breakpoint.  If it returns #t, or any non-#f value, then the inferior is stopped, otherwise the inferior will continue.

     If there are multiple breakpoints at the same location with a stop predicate, each one will be called regardless of the return status of the previous.  This ensures that all stop predicates have a chance to execute at that location.  In this scenario if one of the methods returns #t but the others return #f, the inferior will still be stopped.

     You should not alter the execution state of the inferior (i.e., step, next, etc.), alter the current frame context (i.e., change the current active frame), or alter, add or delete any breakpoint.  As a general rule, you should not alter any data within GDBN or the inferior at this time.

     Example stop implementation:

          (define (my-stop? bkpt)
            (let ((int-val (parse-and-eval "foo")))
              (value=? int-val 3)))
          (define bkpt (make-breakpoint "main.c:42"))
          (register-breakpoint! bkpt)
          (set-breakpoint-stop! bkpt my-stop?)

 -- Scheme Procedure: breakpoint-commands breakpoint
     Return the commands attached to BREAKPOINT as a string, or #f if there are none.

Guile representation of lazy strings.
.....................................

A lazy string is a string whose contents is not retrieved or encoded until it is needed.

A <gdb:lazy-string> is represented in GDBN as an address that points to a region of memory, an encoding that will be used to encode that region of memory, and a length to delimit the region of memory that represents the string.  The difference between a <gdb:lazy-string> and a string wrapped within a <gdb:value> is that a <gdb:lazy-string> will be treated differently by GDBN when printing.  A <gdb:lazy-string> is retrieved and encoded during printing, while a <gdb:value> wrapping a string is immediately retrieved and encoded on creation.

The following lazy-string-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: lazy-string? object
     Return #t if OBJECT is an object of type <gdb:lazy-string>. Otherwise return #f.

 -- Scheme Procedure: lazy-string-address lazy-sring
     Return the address of LAZY-STRING.

 -- Scheme Procedure: lazy-string-length lazy-string
     Return the length of LAZY-STRING in characters.  If the length is -1, then the string will be fetched and encoded up to the first null of appropriate width.

 -- Scheme Procedure: lazy-string-encoding lazy-string
     Return the encoding that will be applied to LAZY-STRING when the string is printed by GDBN.  If the encoding is not set, or contains an empty string,  then GDBN will select the most appropriate encoding when the string is printed.

 -- Scheme Procedure: lazy-string-type lazy-string
     Return the type that is represented by LAZY-STRING's type. For a lazy string this is a pointer or array type.  To resolve this to the lazy string's character type, use type-target-type. See Types In Guile.

 -- Scheme Procedure: lazy-string->value lazy-string
     Convert the <gdb:lazy-string> to a <gdb:value>.  This value will point to the string in memory, but will lose all the delayed retrieval, encoding and handling that GDBN applies to a <gdb:lazy-string>.

Guile representation of architectures
.....................................

GDBN uses architecture specific parameters and artifacts in a number of its various computations.  An architecture is represented by an instance of the <gdb:arch> class.

The following architecture-related procedures are provided by the (gdb) module:

 -- Scheme Procedure: arch? object
     Return #t if OBJECT is an object of type <gdb:arch>. Otherwise return #f.

 -- Scheme Procedure: current-arch
     Return the current architecture as a <gdb:arch> object.

 -- Scheme Procedure: arch-name arch
     Return the name (string value) of <gdb:arch> ARCH.

 -- Scheme Procedure: arch-charset arch
     Return name of target character set of <gdb:arch> ARCH.

 -- Scheme Procedure: arch-wide-charset
     Return name of target wide character set of <gdb:arch> ARCH.

Each architecture provides a set of predefined types, obtained by the following functions.

 -- Scheme Procedure: arch-void-type arch
     Return the <gdb:type> object for a void type of architecture ARCH.

 -- Scheme Procedure: arch-char-type arch
     Return the <gdb:type> object for a char type of architecture ARCH.

 -- Scheme Procedure: arch-short-type arch
     Return the <gdb:type> object for a short type of architecture ARCH.

 -- Scheme Procedure: arch-int-type arch
     Return the <gdb:type> object for an int type of architecture ARCH.

 -- Scheme Procedure: arch-long-type arch
     Return the <gdb:type> object for a long type of architecture ARCH.

 -- Scheme Procedure: arch-schar-type arch
     Return the <gdb:type> object for a signed char type of architecture ARCH.

 -- Scheme Procedure: arch-uchar-type arch
     Return the <gdb:type> object for an unsigned char type of architecture ARCH.

 -- Scheme Procedure: arch-ushort-type arch
     Return the <gdb:type> object for an unsigned short type of architecture ARCH.

 -- Scheme Procedure: arch-uint-type arch
     Return the <gdb:type> object for an unsigned int type of architecture ARCH.

 -- Scheme Procedure: arch-ulong-type arch
     Return the <gdb:type> object for an unsigned long type of architecture ARCH.

 -- Scheme Procedure: arch-float-type arch
     Return the <gdb:type> object for a float type of architecture ARCH.

 -- Scheme Procedure: arch-double-type arch
     Return the <gdb:type> object for a double type of architecture ARCH.

 -- Scheme Procedure: arch-longdouble-type arch
     Return the <gdb:type> object for a long double type of architecture ARCH.

 -- Scheme Procedure: arch-bool-type arch
     Return the <gdb:type> object for a bool type of architecture ARCH.

 -- Scheme Procedure: arch-longlong-type arch
     Return the <gdb:type> object for a long long type of architecture ARCH.

 -- Scheme Procedure: arch-ulonglong-type arch
     Return the <gdb:type> object for an unsigned long long type of architecture ARCH.

 -- Scheme Procedure: arch-int8-type arch
     Return the <gdb:type> object for an int8 type of architecture ARCH.

 -- Scheme Procedure: arch-uint8-type arch
     Return the <gdb:type> object for a uint8 type of architecture ARCH.

 -- Scheme Procedure: arch-int16-type arch
     Return the <gdb:type> object for an int16 type of architecture ARCH.

 -- Scheme Procedure: arch-uint16-type arch
     Return the <gdb:type> object for a uint16 type of architecture ARCH.

 -- Scheme Procedure: arch-int32-type arch
     Return the <gdb:type> object for an int32 type of architecture ARCH.

 -- Scheme Procedure: arch-uint32-type arch
     Return the <gdb:type> object for a uint32 type of architecture ARCH.

 -- Scheme Procedure: arch-int64-type arch
     Return the <gdb:type> object for an int64 type of architecture ARCH.

 -- Scheme Procedure: arch-uint64-type arch
     Return the <gdb:type> object for a uint64 type of architecture ARCH.

Example:

     (gdb) guile (type-name (arch-uchar-type (current-arch)))
     "unsigned char"

Disassembly In Guile
....................

The disassembler can be invoked from Scheme code. Furthermore, the disassembler can take a Guile port as input, allowing one to disassemble from any source, and not just target memory.

 -- Scheme Procedure: arch-disassemble arch start-pc
     [#:port port] [#:offset offset]
     [#:size size] [#:count count]
     Return a list of disassembled instructions starting from the memory address START-PC.

     The optional argument PORT specifies the input port to read bytes from. If PORT is #f then bytes are read from target memory.

     The optional argument OFFSET specifies the address offset of the first byte in PORT.  This is useful, for example, when PORT specifies a bytevector and you want the bytevector to be disassembled as if it came from that address.  The START-PC passed to the reader for PORT is offset by the same amount.

     Example:

          (gdb) guile (use-modules (rnrs io ports))
          (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
          (gdb) guile (define mem (open-memory #:start pc))
          (gdb) guile (define bv (get-bytevector-n mem 10))
          (gdb) guile (define bv-port (open-bytevector-input-port bv))
          (gdb) guile (define arch (current-arch))
          (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
          (((address . 4195516) (asm . "mov    $0x4005c8,%edi") (length . 5)))

     The optional arguments SIZE and COUNT determine the number of instructions in the returned list. If either SIZE or COUNT is specified as zero, then no instructions are disassembled and an empty list is returned. If both the optional arguments SIZE and COUNT are specified, then a list of at most COUNT disassembled instructions whose start address falls in the closed memory address interval from START-PC to (START-PC + SIZE - 1) are returned. If SIZE is not specified, but COUNT is specified, then COUNT number of instructions starting from the address START-PC are returned.  If COUNT is not specified but SIZE is specified, then all instructions whose start address falls in the closed memory address interval from START-PC to (START-PC + SIZE - 1) are returned. If neither SIZE nor COUNT are specified, then a single instruction at START-PC is returned.

     Each element of the returned list is an alist (associative list) with the following keys:

     address
          The value corresponding to this key is a Guile integer of the memory address of the instruction.

     asm
          The value corresponding to this key is a string value which represents the instruction with assembly language mnemonics.  The assembly language flavor used is the same as that specified by the current CLI variable disassembly-flavor.  See Machine Code.

     length
          The value corresponding to this key is the length of the instruction in bytes.

I/O Ports in Guile
..................

 -- Scheme Procedure: input-port
     Return GDBN's input port as a Guile port object.

 -- Scheme Procedure: output-port
     Return GDBN's output port as a Guile port object.

 -- Scheme Procedure: error-port
     Return GDBN's error port as a Guile port object.

 -- Scheme Procedure: stdio-port? object
     Return #t if OBJECT is a GDBN stdio port. Otherwise return #f.

Memory Ports in Guile
.....................

GDBN provides a port interface to target memory. This allows Guile code to read/write target memory using Guile's port and bytevector functionality.  The main routine is open-memory which returns a port object.  One can then read/write memory using that object.

 -- Scheme Procedure: open-memory [#:mode mode]
     [#:start address] [#:size size]
     Return a port object that can be used for reading and writing memory. The port will be open according to MODE, which is the standard mode argument to Guile port open routines, except that the "a" and "l" modes are not supported. See File Ports (GNU Guile Reference Manual). The "b" (binary) character may be present, but is ignored: memory ports are binary only.  If "0" is appended then the port is marked as unbuffered. The default is "r", read-only and buffered.

     The chunk of memory that can be accessed can be bounded. If both START and SIZE are unspecified, all of memory can be accessed.  If only START is specified, all of memory from that point on can be accessed.  If only SIZE if specified, all memory in the range [0,SIZE) can be accessed.  If both are specified, all memory in the rane [START,START+SIZE) can be accessed.

 -- Scheme Procedure: memory-port?
     Return #t if OBJECT is an object of type <gdb:memory-port>. Otherwise return #f.

 -- Scheme Procedure: memory-port-range memory-port
     Return the range of <gdb:memory-port> MEMORY-PORT as a list of two elements: (start end).  The range is START to END inclusive.

 -- Scheme Procedure: memory-port-read-buffer-size memory-port
     Return the size of the read buffer of <gdb:memory-port> MEMORY-PORT.

     This procedure is deprecated and will be removed in GDBN 11. It returns 0 when using Guile 2.2 or later.

 -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size
     Set the size of the read buffer of <gdb:memory-port> MEMORY-PORT to SIZE.  The result is unspecified.

     This procedure is deprecated and will be removed in GDBN 11. When GDBN is built with Guile 2.2 or later, you can call setvbuf instead (see setvbuf (GNU Guile Reference Manual)).

 -- Scheme Procedure: memory-port-write-buffer-size memory-port
     Return the size of the write buffer of <gdb:memory-port> MEMORY-PORT.

     This procedure is deprecated and will be removed in GDBN 11. It returns 0 when GDBN is built with Guile 2.2 or later.

 -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port size
     Set the size of the write buffer of <gdb:memory-port> MEMORY-PORT to SIZE.  The result is unspecified.

     This procedure is deprecated and will be removed in GDBN 11. When GDBN is built with Guile 2.2 or later, you can call setvbuf instead.

A memory port is closed like any other port, with close-port.

Combined with Guile's bytevectors, memory ports provide a lot of utility.  For example, to fill a buffer of 10 integers in memory, one can do something like the following.

     ;; In the program: int buffer[10];
     (use-modules (rnrs bytevectors))
     (use-modules (rnrs io ports))
     (define addr (parse-and-eval "buffer"))
     (define n 10)
     (define byte-size (* n 4))
     (define mem-port (open-memory #:mode "r+" #:start
                                   (value->integer addr) #:size byte-size))
     (define byte-vec (make-bytevector byte-size))
     (do ((i 0 (+ i 1)))
         ((>= i n))
         (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
     (put-bytevector mem-port byte-vec)
     (close-port mem-port)

Iterators In Guile
..................

A simple iterator facility is provided to allow, for example, iterating over the set of program symbols without having to first construct a list of all of them.  A useful contribution would be to add support for SRFI 41 and SRFI 45.

 -- Scheme Procedure: make-iterator object progress next!
     A <gdb:iterator> object is constructed with the make-iterator procedure.  It takes three arguments: the object to be iterated over, an object to record the progress of the iteration, and a procedure to return the next element in the iteration, or an implementation chosen value to denote the end of iteration.

     By convention, end of iteration is marked with (end-of-iteration), and may be tested with the end-of-iteration? predicate. The result of (end-of-iteration) is chosen so that it is not otherwise used by the (gdb) module.  If you are using <gdb:iterator> in your own code it is your responsibility to maintain this invariant.

     A trivial example for illustration's sake:

          (use-modules (gdb iterator))
          (define my-list (list 1 2 3))
          (define iter
            (make-iterator my-list my-list
                           (lambda (iter)
                             (let ((l (iterator-progress iter)))
                               (if (eq? l '())
                                   (end-of-iteration)
                                   (begin
                                     (set-iterator-progress! iter (cdr l))
                                     (car l)))))))

     Here is a slightly more realistic example, which computes a list of all the functions in my-global-block.

          (use-modules (gdb iterator))
          (define this-sal (find-pc-line (frame-pc (selected-frame))))
          (define this-symtab (sal-symtab this-sal))
          (define this-global-block (symtab-global-block this-symtab))
          (define syms-iter (make-block-symbols-iterator this-global-block))
          (define functions (iterator-filter symbol-function? syms-iter))

 -- Scheme Procedure: iterator? object
     Return #t if OBJECT is a <gdb:iterator> object. Otherwise return #f.

 -- Scheme Procedure: iterator-object iterator
     Return the first argument that was passed to make-iterator. This is the object being iterated over.

 -- Scheme Procedure: iterator-progress iterator
     Return the object tracking iteration progress.

 -- Scheme Procedure: set-iterator-progress! iterator new-value
     Set the object tracking iteration progress.

 -- Scheme Procedure: iterator-next! iterator
     Invoke the procedure that was the third argument to make-iterator, passing it one argument, the <gdb:iterator> object. The result is either the next element in the iteration, or an end marker as implemented by the next! procedure. By convention the end marker is the result of (end-of-iteration).

 -- Scheme Procedure: end-of-iteration
     Return the Scheme object that denotes end of iteration.

 -- Scheme Procedure: end-of-iteration? object
     Return #t if OBJECT is the end of iteration marker. Otherwise return #f.

These functions are provided by the (gdb iterator) module to assist in using iterators.

 -- Scheme Procedure: make-list-iterator list
     Return a <gdb:iterator> object that will iterate over LIST.

 -- Scheme Procedure: iterator->list iterator
     Return the elements pointed to by ITERATOR as a list.

 -- Scheme Procedure: iterator-map proc iterator
     Return the list of objects obtained by applying PROC to the object pointed to by ITERATOR and to each subsequent object.

 -- Scheme Procedure: iterator-for-each proc iterator
     Apply PROC to each element pointed to by ITERATOR. The result is unspecified.

 -- Scheme Procedure: iterator-filter pred iterator
     Return the list of elements pointed to by ITERATOR that satisfy PRED.

 -- Scheme Procedure: iterator-until pred iterator
     Run ITERATOR until the result of (pred element) is true and return that as the result.  Otherwise return #f.

Guile Auto-loading
------------------

When a new object file is read (for example, due to the file command, or because the inferior has loaded a shared library), GDBN will look for Guile support scripts in two ways: OBJFILE-gdb.scm and the .debug_gdb_scripts section. See Auto-loading extensions.

The auto-loading feature is useful for supplying application-specific debugging commands and scripts.

Auto-loading can be enabled or disabled, and the list of auto-loaded scripts can be printed.

set auto-load guile-scripts [on|off]
     Enable or disable the auto-loading of Guile scripts.

show auto-load guile-scripts
     Show whether auto-loading of Guile scripts is enabled or disabled.

info auto-load guile-scripts [REGEXP]
     Print the list of all Guile scripts that GDBN auto-loaded.

     Also printed is the list of Guile scripts that were mentioned in the .debug_gdb_scripts section and were not found. This is useful because their names are not printed when GDBN tries to load them and fails.  There may be many of them, and printing an error message for each one is problematic.

     If REGEXP is supplied only Guile scripts with matching names are printed.

     Example:

          (gdb) info auto-load guile-scripts
          Loaded Script
          Yes    scm-section-script.scm
                 full name: /tmp/scm-section-script.scm
          No     my-foo-pretty-printers.scm

When reading an auto-loaded file, GDBN sets the current objfile.  This is available via the current-objfile procedure (see Objfiles In Guile).  This can be useful for registering objfile-specific pretty-printers.

Guile Modules
-------------

GDBN comes with several modules to assist writing Guile code.

Guile Printing Module
.....................

This module provides a collection of utilities for working with pretty-printers.

Usage:

     (use-modules (gdb printing))

 -- Scheme Procedure: prepend-pretty-printer! object printer
     Add PRINTER to the front of the list of pretty-printers for OBJECT.  The OBJECT must either be a <gdb:objfile> object, or #f in which case PRINTER is added to the global list of printers.

 -- Scheme Procecure: append-pretty-printer! object printer
     Add PRINTER to the end of the list of pretty-printers for OBJECT.  The OBJECT must either be a <gdb:objfile> object, or #f in which case PRINTER is added to the global list of printers.

Guile Types Module
..................

This module provides a collection of utilities for working with <gdb:type> objects.

Usage:

     (use-modules (gdb types))

 -- Scheme Procedure: get-basic-type type
     Return TYPE with const and volatile qualifiers stripped, and with typedefs and C++ references converted to the underlying type.

     C++ example:

          typedef const int const_int;
          const_int foo (3);
          const_int& foo_ref (foo);
          int main () { return 0; }

     Then in gdb:

          (gdb) start
          (gdb) guile (use-modules (gdb) (gdb types))
          (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
          (gdb) guile (get-basic-type (value-type foo-ref))
          int

 -- Scheme Procedure: type-has-field-deep? type field
     Return #t if TYPE, assumed to be a type with fields (e.g., a structure or union), has field FIELD. Otherwise return #f. This searches baseclasses, whereas type-has-field? does not.

 -- Scheme Procedure: make-enum-hashtable enum-type
     Return a Guile hash table produced from ENUM-TYPE. Elements in the hash table are referenced with hashq-ref.