Basic Guile (Debugging with GDB)
Next: Guile Configuration, Up: Guile API [Contents][Index]
23.4.3.1 Basic Guile
At startup, GDB overrides Guile’s current-output-port
and current-error-port
to print using GDB’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 GDB’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 GDB.
GDB is not thread-safe. If your Guile program uses multiple threads, you must be careful to only call GDB-specific functions in the GDB thread.
Some care must be taken when writing Guile code to run in GDB. Two things are worth noting in particular:
- GDB installs handlers for
SIGCHLD
andSIGINT
. Guile code must not override these, or even change the options usingsigaction
. If your program changes the handling of these signals, GDB will most likely stop working correctly. Note that it is unfortunately common for GUI toolkits to install aSIGCHLD
handler. - GDB 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.
GDB introduces a new Guile module, named gdb
. All methods and classes added by GDB are placed in this module. GDB does not automatically import
the gdb
module, scripts must do this themselves. There are various options for how to import a module, so GDB 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 in 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 GDB CLI command. If a GDB exception happens whilecommand
runs, it is translated as described in Guile Exception Handling.from-tty
specifies whether GDB 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 GDB’s standard output (and to the log output if logging is turned on). If theto-string
parameter is#t
, then output will be collected byexecute
and returned as a string. The default is#f
, in which case the return value is unspecified. Ifto-string
is#t
, the GDB 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 GDB’s value history (see Value History). The
number
argument indicates which history element to return. Ifnumber
is negative, then GDB will take its absolute value and count backward from the last element (i.e., the most recent element) to find the value to return. Ifnumber
is zero, then GDB will return the most recent element. If the element specified bynumber
doesn’t exist in the value history, agdb: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: GDB’s value history is independent of Guile’s.
$1
in GDB’s value history contains the result of evaluating an expression from GDB’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 GDB’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>
. Theexpression
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>
.
Next: Guile Configuration, Up: Guile API [Contents][Index]