Info Catalog gdb: Guile API gdb: Guile Configuration

gdb: Basic Guile

 
 23.3.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 (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' and 'SIGINT'.  Guile code must
      not override these, or even change the options using 'sigaction'.
      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 a 'SIGCHLD' 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 ((guile)Using Guile Modules).
 
    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 while COMMAND runs, it is translated as described
      in Guile Exception Handling 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 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 GDB virtual terminal will be temporarily set to unlimited width
      and height, and its pagination will be disabled; Screen
      Size.
 
  -- Scheme Procedure: history-ref number
      Return a value from GDB's value history (Value History).
      The NUMBER argument indicates which history element to return.  If
      NUMBER 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.  If NUMBER is zero, then GDB 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>' (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>'.  The EXPRESSION must
      be a string.
 
      This function can be useful when implementing a new command (
      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 (Convenience Vars) as a '<gdb:value>'.
 

Info Catalog gdb: Guile API gdb: Guile Configuration