From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 24355 invoked by alias); 24 Dec 2013 19:03:09 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 24234 invoked by uid 89); 24 Dec 2013 19:03:08 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=3.2 required=5.0 tests=AWL,BAYES_50,FREEMAIL_ENVFROM_END_DIGIT,FREEMAIL_FROM,KAM_STOCKTIP,MSGID_FROM_MTA_HEADER,RCVD_IN_DNSWL_LOW,SPF_PASS autolearn=no version=3.3.2 X-HELO: mail-pa0-f47.google.com Received: from mail-pa0-f47.google.com (HELO mail-pa0-f47.google.com) (209.85.220.47) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Tue, 24 Dec 2013 19:02:53 +0000 Received: by mail-pa0-f47.google.com with SMTP id kq14so6792741pab.20 for ; Tue, 24 Dec 2013 11:02:51 -0800 (PST) X-Received: by 10.66.164.36 with SMTP id yn4mr26961629pab.42.1387911771418; Tue, 24 Dec 2013 11:02:51 -0800 (PST) Received: from sspiff.org (173-13-178-53-sfba.hfc.comcastbusiness.net. [173.13.178.53]) by mx.google.com with ESMTPSA id at4sm43447287pbc.30.2013.12.24.11.02.48 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 24 Dec 2013 11:02:49 -0800 (PST) Message-ID: <52b9da59.64ab440a.0b0b.7e1c@mx.google.com> Received: by sspiff.org (sSMTP sendmail emulation); Tue, 24 Dec 2013 11:02:24 -0800 Date: Tue, 24 Dec 2013 19:03:00 -0000 From: Doug Evans To: gdb-patches@sourceware.org Subject: [PATCH v1 02/36] Guile extension language: doc additions X-IsSubscribed: yes X-SW-Source: 2013-12/txt/msg00929.txt.bz2 This patch has the doc additions. There's still some to be written, but I think it's in good enough shape to get feedback on. 2013-12-24 Doug Evans doc/ * Makefile.in (GDB_DOC_FILES): Add guile.texi. * gdb.texinfo * guile.texi: New file. diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 60feae3..4c5023f 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -130,6 +130,7 @@ GDB_DOC_BUILD_INCLUDES = \ GDBvn.texi GDB_DOC_FILES = \ $(srcdir)/gdb.texinfo \ + $(srcdir)/guile.texi \ $(GDB_DOC_SOURCE_INCLUDES) \ $(GDB_DOC_BUILD_INCLUDES) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 7560152..f1834a0 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -22247,6 +22247,12 @@ These are @value{GDBN} control commands for the auto-loading: @tab Show setting of @value{GDBN} Python scripts. @item @xref{info auto-load python-scripts}. @tab Show state of @value{GDBN} Python scripts. +@item @xref{set auto-load guile-scripts}. +@tab Control for @value{GDBN} Guile scripts. +@item @xref{show auto-load guile-scripts}. +@tab Show setting of @value{GDBN} Guile scripts. +@item @xref{info auto-load guile-scripts}. +@tab Show state of @value{GDBN} Guile scripts. @item @xref{set auto-load scripts-directory}. @tab Control for @value{GDBN} auto-loaded scripts location. @item @xref{show auto-load scripts-directory}. @@ -22873,7 +22879,9 @@ being debugged. @menu * Sequences:: Canned Sequences of @value{GDBN} Commands * Python:: Extending @value{GDBN} using Python +* Guile:: Extending @value{GDBN} using Guile * Auto-loading extensions:: Automatically loading extensions +* Multiple Extension Languages:: Working with multiple extension languages * Aliases:: Creating new spellings of existing commands @end menu @@ -27868,6 +27876,9 @@ substitute_prompt (``frame: \f, @end smallexample @end table +@c Guile docs live in a separate file. +@include guile.texi + @node Auto-loading extensions @section Auto-loading extensions @cindex auto-loading extensions @@ -27913,6 +27924,8 @@ where @var{ext} is the file extension for the extension language: GDB's own command language @item @file{@var{objfile}-gdb.py} Python +@item @file{@var{objfile}-gdb.scm} +Guile @end table @var{script-name} is formed by ensuring that the file name of @var{objfile} @@ -28006,6 +28019,7 @@ for example, this GCC macro for Python scripts. @end example @noindent +For Guile scripts, replace @code{.byte 1} with @code{.byte 3}. Then one can reference the macro in a header or source file like this: @example @@ -28077,6 +28091,26 @@ cumbersome. It may be easier to specify the scripts in the top of the source tree to the source search path. @end itemize +@node Multiple Extension Languages +@section Multiple Extension Languages + +The Guile and Python extension languages do not share any state, +and generally do not interfere with each other. +There are some things to be aware of, however. + +@subsection Python comes first + +Python was @value{GDBN}'s first extension language, and to avoid breaking +existing behaviour Python comes first. This is generally solved by the +``first one wins'' principle. @value{GDBN} maintains a list of enabled +extension languages, and when it makes a call to an extension language, +(say to pretty-print a value), it tries each in turn until an extension +language indicates it has performed the request (e.g., has returned the +pretty-printed form of a value). +This extends to errors while performing such requests: If an error happens +while, for example, trying to pretty-print an object then the error is +reported and any following extension languages are not tried. + @node Aliases @section Creating new spellings of existing commands @cindex aliases for commands diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi new file mode 100644 index 0000000..0c050d4 --- /dev/null +++ b/gdb/doc/guile.texi @@ -0,0 +1,3095 @@ +@node Guile +@section Extending @value{GDBN} using Guile +@cindex guile scripting +@cindex scripting with guile + +You can extend @value{GDBN} using the @uref{http://www.gnu.org/software/guile/, +Guile implementation of the Scheme programming language}. +This feature is available only if @value{GDBN} was configured using +@option{--with-guile}. + +@menu +* Guile Introduction:: Introduction to Guile scripting in @value{GDBN} +* Guile Commands:: Accessing Guile from @value{GDBN} +* Guile API:: Accessing @value{GDBN} from Guile +* Guile Auto-loading:: Automatically loading Guile code +* Guile Modules:: Guile modules provided by @value{GDBN} +@end menu + +@node Guile Introduction +@subsection Guile Introduction + +Guile is an implementation of the Scheme programming language +and is the GNU project's official extension language. + +Guile support in @value{GDBN} follows the Python support in @value{GDBN} +reasonably closely, so concepts there should carry over. +However, some things are done differently where it makes sense. + +@value{GDBN} requires Guile version 2.0 or greater. +Older versions are not supported. +Guile version 2.0.9 is well tested, earlier 2.0 versions are not. + +The implementation uses Guile's @code{smob} (small object) +data type for all @value{GDBN} objects. This allows gluing Guile +into @value{GDBN} very easily. + +@cindex guile directory +Guile scripts used by @value{GDBN} should be installed in +@file{@var{data-directory}/guile}, where @var{data-directory} is +the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). +This directory, known as the @dfn{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. + +@node Guile Commands +@subsection Guile Commands +@cindex guile commands +@cindex commands to access guile + +@value{GDBN} provides two commands for accessing the Guile interpreter: + +@table @code +@kindex guile-interactive +@kindex gi +@item guile-interactive +@itemx gi +The @code{guile-interactive} command can be used +to start an interactive Guile prompt. To return to @value{GDBN}, +type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on +an empty prompt). These commands do not take any arguments. + +@kindex guile +@kindex gu +@item guile @r{[}@var{command}@r{]} +@itemx gu @r{[}@var{command}@r{]} +The @code{guile} command can be used to evaluate a Scheme expression. + +If given an argument, @value{GDBN} will pass the argument to the Guile +interpreter for evaluation. + +@smallexample +(@value{GDBP}) guile (display (+ 20 3)) (newline) +23 +@end smallexample + +The result of the Scheme expression is displayed using normal Guile rules. + +@smallexample +(@value{GDBP}) guile (+ 20 3) +23 +@end smallexample + +If you do not provide an argument to @code{guile}, it will act as a +multi-line command, like @code{define}. In this case, the Guile +script is made up of subsequent command lines, given after the +@code{guile} command. This command list is terminated using a line +containing @code{end}. For example: + +@smallexample +(@value{GDBP}) guile +>(display 23) +>(newline) +>end +23 +@end smallexample +@end table + +It is also possible to execute a Guile script from the @value{GDBN} +interpreter: + +@table @code +@item source @file{script-name} +The script name must end with @samp{.scm} and @value{GDBN} must be configured +to recognize the script language based on filename extension using +the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}. + +@item guile (load "script-name") +This method uses the @code{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. +@end table + +@node Guile API +@subsection Guile API +@cindex guile api +@cindex programming in guile + +You can get quick online help for @value{GDBN}'s Guile API by issuing +the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help} +from an interactive Guile session. Furthermore, most Guile procedures +provided by @value{GDBN} have doc strings which can be obtained with +@kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}} +from the Guile interactive prompt. + +@menu +* Basic Guile:: Basic Guile Functions +* Guile Configuration:: Guile configuration variables +* Guile Exception Handling:: How Guile exceptions are translated +* Values From Inferior In Guile:: Guile representation of values +* Arithmetic In Guile:: Arithmetic in Guile +* Types In Guile:: Guile representation of types +* Guile Pretty Printing API:: Pretty-printing values with Guile +* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer +* Writing a Guile Pretty-Printer:: Writing a pretty-printer +* Objfiles In Guile:: Object files in Guile +* Frames In Guile:: Accessing inferior stack frames from Guile +* Blocks In Guile:: Accessing blocks from Guile +* Symbols In Guile:: Guile representation of symbols +* Symbol Tables In Guile:: Guile representation of symbol tables +* Breakpoints In Guile:: Manipulating breakpoints using Guile +* Lazy Strings In Guile:: Guile representation of lazy strings +* Architectures In Guile:: Guile representation of architectures +* Disassembly In Guile:: Disassembling instructions from Guile +* I/O Ports in Guile:: GDB I/O ports +* Memory Ports in Guile:: Accessing memory through ports and bytevectors +* Iterators In Guile:: Basic iterator support +@end menu + +@node Basic Guile +@subsubsection Basic Guile + +@cindex guile stdout +@cindex guile pagination +At startup, @value{GDBN} overrides Guile's @code{current-output-port} and +@code{current-error-port} to print using @value{GDBN}'s output-paging streams. +A Guile program which outputs to one of these streams may have its +output interrupted by the user (@pxref{Screen Size}). In this +situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}. + +Guile's history mechanism uses the same naming as @value{GDBN}'s, +namely the user of dollar-variables (e.g., $1, $2, etc.). +However, the values are independent, @code{$1} in Guile is not the +same value as @code{$1} in @value{GDBN}. + +@value{GDBN} is not thread-safe. If your Guile program uses multiple +threads, you must be careful to only call @value{GDBN}-specific +functions in the main @value{GDBN} thread. + +Some care must be taken when writing Guile code to run in +@value{GDBN}. Two things are worth noting in particular: + +@itemize @bullet +@item +@value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}. +Guile code must not override these, or even change the options using +@code{sigaction}. If your program changes the handling of these +signals, @value{GDBN} will most likely stop working correctly. Note +that it is unfortunately common for GUI toolkits to install a +@code{SIGCHLD} handler. + +@item +@value{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. +@end itemize + +@cindex guile gdb module +@value{GDBN} introduces a new Guile module, named @code{gdb}. All +methods and classes added by @value{GDBN} are placed in this module. +@value{GDBN} does not automatically @code{import} the @code{gdb} module, +scripts must do this themselves. There are various options for how to +import a module, so @value{GDBN} leaves the choice of how the @code{gdb} +module is imported to the user. +To simplify interactive use, it is recommended to add one of the following +to your ~/.gdbinit. + +@smallexample +guile (use-modules (gdb)) +@end smallexample + +@smallexample +guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:))) +@end smallexample + +Which one to choose depends on your preference. +The second one adds @code{gdb:} as a prefix to all module functions +and variables. + +The rest of this manual assumes the @code{gdb} module has been imported +without any prefix. See the Guile documentation for @code{use-modules} +for more information. + +Example: + +@smallexample +(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) +@end smallexample + +The @code{(gdb)} module provides these basic Guile functions. + +@c TODO: line length +@defun execute command @r{[}#:from-tty boolean@r{]}@r{[}#:to-string boolean@r{]} +Evaluate @var{command}, a string, as a @value{GDBN} CLI command. +If a @value{GDBN} exception happens while @var{command} runs, it is +translated as described in +@ref{Guile Exception Handling,,Guile Exception Handling}. + +@var{from-tty} specifies whether @value{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 @code{#f}. + +By default, any output produced by @var{command} is sent to +@value{GDBN}'s standard output. If the @var{to-string} parameter is +@code{#t}, then output will be collected by @code{gdb.execute} and +returned as a string. The default is @code{#f}, in which case the +return value is unspecified. If @var{to-string} is @code{#t}, the +@value{GDBN} virtual terminal will be temporarily set to unlimited width +and height, and its pagination will be disabled; @pxref{Screen Size}. +@end defun + +@defun history-ref number +Return a value from @value{GDBN}'s value history (@pxref{Value +History}). @var{number} indicates which history element to return. +If @var{number} is negative, then @value{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 @var{number} is zero, then @value{GDBN} will +return the most recent element. If the element specified by @var{number} +doesn't exist in the value history, a @code{gdb:error} exception will be +raised. + +If no exception is raised, the return value is always an instance of +@code{} (@pxref{Values From Inferior In Guile}). + +@emph{Note:} @value{GDBN}'s value history is independent of Guile's. +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's +history, nor is the reverse true. +@end defun + +@defun parse-and-eval expression +Parse @var{expression} as an expression in the current language, +evaluate it, and return the result as a @code{}. +@var{expression} must be a string. + +This function is useful when computing values. +For example, it is the only way to get the value of a +convenience variable (@pxref{Convenience Vars}) as a @code{}. +@end defun + +@defun string->argv string +Convert a string to a list of strings split up according to +@value{GDBN}'s argv parsing rules. +@end defun + +@node Guile Configuration +@subsubsection Guile Configuration + +@value{GDBN} provides these variables that specify various configuration +parameters. They are read-only. +By convention global variables are named @code{*variable*}. + +@defun data-directory +Return a string containing @value{GDBN}'s data directory. +This directory contains @value{GDBN}'s ancillary files, including +the Guile modules provided by @value{GDBN}. +@end defun + +@defun gdb-version +Return a string containing the @value{GDBN} version. +@end defun + +@defun host-config +Return a string containing the host configuration. +This is the string passed to @code{--host} when @value{GDBN} was configured. +@end defun + +@defun target-config +Return a string containing the target configuration. +This is the string passed to @code{--target} when @value{GDBN} was configured. +@end defun + +@node Guile Exception Handling +@subsubsection Guile Exception Handling +@cindex guile exceptions +@cindex exceptions, guile +@kindex set guile print-stack + +When executing the @code{guile} command, Guile exceptions +uncaught within the Guile code are translated to calls to the +@value{GDBN} error-reporting mechanism. If the command that called +@code{guile} does not handle the error, @value{GDBN} will +terminate it and report the error according to the setting of +the @code{guile print-stack} parameter. + +The @code{guile print-stack} parameter has three settings: + +@table @code +@item none +Nothing is printed. + +@item 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: + +@smallexample +(@value{GDBP}) guile (display foo) +ERROR: In procedure memoize-variable-access!: +ERROR: Unbound variable: foo +Error while executing Scheme code. +@end smallexample + +@item full +In addition to an error message a full backtrace is printed. + +@smallexample +(@value{GDBP}) set guile print-stack full +(@value{GDBP}) guile (display foo) +Backtrace: +In ice-9/boot-9.scm: + 157: 10 [catch #t # ...] +In unknown file: + ?: 9 [apply-smob/1 #] +In ice-9/boot-9.scm: + 157: 8 [catch #t # ...] +In unknown file: + ?: 7 [apply-smob/1 #] + ?: 6 [call-with-input-string "(display foo)" ...] +In ice-9/boot-9.scm: +2320: 5 [save-module-excursion #] +In ice-9/eval-string.scm: + 44: 4 [read-and-eval # #:lang ...] + 37: 3 [lp (display foo)] +In ice-9/eval.scm: + 387: 2 [eval # ()] + 393: 1 [eval # ()] +In unknown file: + ?: 0 [memoize-variable-access! # ...] + +ERROR: In procedure memoize-variable-access!: +ERROR: Unbound variable: foo +Error while executing Scheme code. +@end smallexample +@end table + +@value{GDBN} errors that happen in @value{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 @value{GDBN} can throw the standard +Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}. + +User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination +prompt) is translated to a Guile @code{signal} exception with value +@code{SIGINT}. + +@value{GDBN} Guile procedures can also throw these exceptions: + +@ftable @code +@item gdb:error +This exception is a catch-all for errors generated from within @value{GDBN}. + +@item gdb:invalid-object +This exception is thrown when accessing Guile objects that wrap underlying +@value{GDBN} objects have become invalid. For example, a +@code{} 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. + +@item gdb:memory-error +This exception is thrown when an operation tried to access invalid +memory in the inferior. + +@item gdb:pp-type-error +This exception is thrown when a Guile pretty-printer passes a bad object +to @value{GDBN}. +@end ftable + +The following exception-related procedures are provided by the +@code{(gdb)} module. + +@defun make-exception key args +Return a @code{} object. +@var{key} and @var{args} are the standard Guile parameters of an exception. +See Guile documentation for more information. +@end defun + +@defun exception? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun exception-key exception +Return the @var{args} field of a @code{} object. +@end defun + +@defun exception-args exception +Return the @var{args} field of a @code{} object. +@end defun + +@node Values From Inferior In Guile +@subsubsection Values From Inferior In Guile +@cindex values from inferior, in guile +@cindex guile, working with values from inferior + +@tindex @code{} +@value{GDBN} provides values it obtains from the inferior program in +an object of type @code{}. @value{GDBN} uses this object +for its internal bookkeeping of the inferior's values, and for +fetching values when necessary. + +@value{GDBN} does not memoize @code{} objects. +Therefore @code{eq?} does not work as expected. +However @code{equal?} does work. + +@smallexample +(gdb) guile (eq? (make-value 1) (make-value 1)) +$1 = #f +(gdb) guile (equal? (make-value 1) (make-value 1)) +$1 = #t +@end smallexample + +A @code{} that represents a function can be executed via +inferior function call with @code{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, @code{some-val} is a @code{} instance +representing a function that takes two integers as arguments. To +execute this function, call it like so: + +@smallexample +(define result (value-call some-val 10 20)) +@end smallexample + +Any values returned from a function call are @code{} objects. + +Note: Unlike Python scripting in @value{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, @code{(+ (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 @code{value-field} must be used. + +The following value-related procedures are provided by the +@code{(gdb)} module. + +@defun value? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun make-value value @r{[}#:type type@r{]} +Many Scheme values can be converted directly to a @code{} via +with this procedure. If @var{type} is specified, the result is a value +of this type, and if @var{value} can't be represented with this type +an exception is thrown. Otherwise the type of the result is determined from +@var{value} as described below. + +The following Scheme objects are accepted for @var{value}: + +@table @asis +@item Scheme boolean +A Scheme boolean is converted to @var{type} if provided, otherwise +the boolean type for the current language. + +@item Scheme integer +A Scheme integer is converted to a value of type @var{type} if provided. + +If @var{type} is not provided, +a Scheme integer is converted to the first of a C @code{int}, +@code{unsigned int}, @code{long}, @code{unsigned long}, +@code{long long} or @code{unsigned long long} type +for the current architecture that can represent the value. +To force a particular type use +@code{(make-value @var{value} #:type @var{type})}. +@xref{Architectures In Guile}, for a list of the builtin +types for an architecture. + +If the Scheme integer cannot be represented as a target integer +an @code{out-of-range} exception is thrown. + +@item Scheme real +A Scheme real is converted to a value of type @var{type} if provided. + +If @var{type} is not provided, +a Scheme real is converted to the C @code{double} type for the +current architecture. + +@item Scheme string +A Scheme string is converted to a target string, using the current +target encoding. + +Passing @var{type} is not supported in this case, +if it is provided a @code{wrong-type-arg} exception is thrown. + +@item @code{} +If @var{value} is a @code{} object (@pxref{Lazy Strings In +Guile}), then the @code{lazy-string->value} procedure is called, and +its result is used. + +Passing @var{type} is not supported in this case, +if it is provided a @code{wrong-type-arg} exception is thrown. + +@item Scheme bytevector +If @var{value} is a Scheme bytevector and @var{type} is provided, +@var{value} must be the same size, in bytes, of values of type @var{type}, +and the result is essentially created by using @code{memcpy}. + +If @var{value} is a Scheme bytevector and @var{type} is not provided, +the result is an array of type @code{uint8} of the same length. +@end table +@end defun + +@cindex optimized out value in guile +@defun value-optimized-out? value +Return @code{#t} if the compiler optimized out @var{value}, +thus it is not available for fetching from the inferior. +@end defun + +@defun value-address value +If @var{value} is addressable, returns a +@code{} object representing the address. +Otherwise, @code{#f} is returned. +@end defun + +@defun value-type value +Return the type of @var{value} as a @code{} object +(@pxref{Types In Guile}). +@end defun + +@defun value-dynamic-type value +Return the dynamic type of @var{value}. This uses C@t{++} run-time +type information (@acronym{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@t{++} program +that includes @acronym{RTTI} for the object in question. Otherwise, +it will just return the static type of the value as in @kbd{ptype foo}. +@xref{Symbols, ptype}. +@end defun + +@defun value-cast value type +Return a new instance of @code{} that is the result of +casting @var{value} to the type described by @var{type}, which must +be a @code{} object. If the cast cannot be performed for some +reason, this method throws an exception. +@end defun + +@defun value-dynamic-cast value type +Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast} +operator were used. Consult a C@t{++} reference for details. +@end defun + +@defun value-reinterpret-cast value type +Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast} +operator were used. Consult a C@t{++} reference for details. +@end defun + +@defun value-dereference value +For pointer data types, this method returns a new @code{} object +whose contents is the object pointed to by @var{value}. For example, if +@code{foo} is a C pointer to an @code{int}, declared in your C program as + +@smallexample +int *foo; +@end smallexample + +@noindent +then you can use the corresponding @code{} to access what +@code{foo} points to like this: + +@smallexample +(define bar (value-dereference foo)) +@end smallexample + +The result @code{bar} will be a @code{} object holding the +value pointed to by @code{foo}. + +A similar function @code{value-referenced-value} exists which also +returns @code{} objects corresonding to the values pointed to +by pointer values (and additionally, values referenced by reference +values). However, the behavior of @code{value-dereference} +differs from @code{value-referenced-value} by the fact that the +behavior of @code{value-dereference} is identical to applying the C +unary operator @code{*} on a given value. For example, consider a +reference to a pointer @code{ptrref}, declared in your C@t{++} program +as + +@smallexample +typedef int *intptr; +... +int val = 10; +intptr ptr = &val; +intptr &ptrref = ptr; +@end smallexample + +Though @code{ptrref} is a reference value, one can apply the method +@code{value-dereference} to the @code{} object corresponding +to it and obtain a @code{} which is identical to that +corresponding to @code{val}. However, if you apply the method +@code{value-referenced-value}, the result would be a @code{} +object identical to that corresponding to @code{ptr}. + +@smallexample +(define scm-ptrref (parse-and-eval "ptrref")) +(define scm-val (value-dereference scm-ptrref)) +(define scm-ptr (value-referenced-value scm-ptrref)) +@end smallexample + +The @code{} object @code{scm-val} is identical to that +corresponding to @code{val}, and @code{scm-ptr} is identical to that +corresponding to @code{ptr}. In general, @code{value-dereference} can +be applied whenever the C unary operator @code{*} can be applied +to the corresponding C value. For those cases where applying both +@code{value-dereference} and @code{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 +@code{} objects corresponding to pointers (@code{} +objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program. +@end defun + +@defun value-referenced-value value +For pointer or reference data types, this method returns a new +@code{} object corresponding to the value referenced by the +pointer/reference value. For pointer data types, +@code{value-dereference} and @code{value-referenced-value} produce +identical results. The difference between these methods is that +@code{value-dereference} cannot get the values referenced by reference +values. For example, consider a reference to an @code{int}, declared +in your C@t{++} program as + +@smallexample +int val = 10; +int &ref = val; +@end smallexample + +@noindent +then applying @code{value-dereference} to the @code{} object +corresponding to @code{ref} will result in an error, while applying +@code{value-referenced-value} will result in a @code{} object +identical to that corresponding to @code{val}. + +@smallexample +(define scm-ref (parse-and-eval "ref")) +(define err-ref (value-dereference scm-ref)) ;; error +(define scm-val (value-referenced-value scm-ref)) ;; ok +@end smallexample + +The @code{} object @code{scm-val} is identical to that +corresponding to @code{val}. +@end defun + +@defun value-field value field-name +Return field @var{field-name} from @code{} object @var{value}. +@end defun + +@defun value-subscript value index +Return the value of array @var{value} at index @var{index}. +@var{value} must be a subscriptable @code{} object. +@end defun + +@defun value-call value arg-list +Perform an inferior function call, taking @var{value} as a pointer +to the function to call. +Each element of list @var{arg-list} must be a object or an object +that can be converted to one. +The result is the value returned by the function. +@end defun + +@defun value->bool value +Return the Scheme boolean representing @code{} @var{value}. +The value must be ``integer like''. Pointers are ok. +@end defun + +@defun value->integer +Return the Scheme integer representing @code{} @var{value}. +The value must be ``integer like''. Pointers are ok. +@end defun + +@defun value->real +Return the Scheme real number representing @code{} @var{value}. +The value must be a number. +@end defun + +@defun value->bytevector +Return a Scheme bytevector with the raw contents of @code{} +@var{value}. No transformation, endian or otherwise, is performed. +@end defun + +@c TODO: line length +@defun value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]} +If @var{value>} represents a string, then this method +converts the contents to a Guile string. Otherwise, this method will +throw an exception. + +Strings are recognized in a language-specific way; whether a given +@code{} represents a string is determined by the current +language. + +For C-like languages, a value is a string if it is a pointer to or an +array of characters or ints. The string is assumed to be terminated +by a zero of the appropriate width. However if the optional length +argument is given, the string will be converted to that given length, +ignoring any embedded zeros that the string may contain. + +If the optional @var{encoding} argument is given, it must be a string +naming the encoding of the string in the @code{}, such as +@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts +the same encodings as the corresponding argument to Guile's +@code{scm_from_stringn} function, and the Guile codec machinery will be used +to convert the string. If @var{encoding} is not given, or if +@var{encoding} is the empty string, then either the @code{target-charset} +(@pxref{Character Sets}) will be used, or a language-specific encoding +will be used, if the current language is able to supply one. + +The optional @var{errors} argument is either @code{"strict"} +or @code{"replace"}. A value of @code{"strict"} corresponds to +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"} +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}. + +If the optional @var{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 @code{} integer. +@end defun + +@c TODO: line length +@defun value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]}) +If this @code{} represents a string, then this method +converts @var{value} to a @code{} integer. +@end defun + +@defun value-lazy? value +Return @code{#t} if @var{value} has not yet been fetched +from the inferior. +@value{GDBN} does not fetch values until necessary, for efficiency. +For example: + +@smallexample +(define myval (parse-and-eval "somevar")) +@end smallexample + +The value of @code{somevar} is not fetched at this time. It will be +fetched when the value is needed, or when the @code{fetch-lazy} +procedure is invoked. +@end defun + +@defun make-lazy-value type address +Return a @code{} that will be lazily fetched from the target. +@var{type} is an object of type @code{} and @var{address} is +a Scheme integer of the address of the object in target memory. +@end defun + +@defun value-fetch-lazy! value +If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}), +then the value is fetched from the inferior. +Any errors that occur in the process will produce a Guile exception. + +If @var{value} is not a lazy value, this method has no effect. + +The result of this function is unspecified. +@end defun + +@defun value-print value +Return the string representation (print form) of @code{} +@var{value}. +@end defun + +@node Arithmetic In Guile +@subsubsection Arithmetic In Guile + +The @code{(gdb)} module provides several functions for performing +arithmetic on @code{} 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, +@value{GDBN} will convert appropriate Scheme values to perform +the operation. + +@defun value-add a b +@end defun + +@defun value-sub a b +@end defun + +@defun value-mul a b +@end defun + +@defun value-div a b +@end defun + +@defun value-rem a b +@end defun + +@defun value-mod a b +@end defun + +@defun value-pow a b +@end defun + +@defun value-not a +@end defun + +@defun value-neg a +@end defun + +@defun value-pos a +@end defun + +@defun value-abs a +@end defun + +@defun value-lsh a b +@end defun + +@defun value-rsh a b +@end defun + +@defun value-max a b +@end defun + +@defun value-max a b +@end defun + +@defun value-lognot a +@end defun + +@defun value-logand a b +@end defun + +@defun value-logior a b +@end defun + +@defun value-logxor a b +@end defun + +@defun value=? a b +@end defun + +@defun value? a b +@end defun + +@defun value>=? a b +@end defun + +Scheme does not provide a @code{not-equal} function, +and thus Guile support in @value{GDBN} does not either. + +@node Types In Guile +@subsubsection Types In Guile +@cindex types in guile +@cindex guile, working with types + +@tindex +@value{GDBN} represents types from the inferior in objects of type +@code{}. + +The following type-related procedures are provided by the +@code{(gdb)} module. + +@defun type? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun lookup-type name @r{[}#:block block@r{]} +This function looks up a type by name. @var{name} is the name of the +type to look up. It must be a string. + +If @var{block} is given, it is an object of type @code{}, +and @var{name} is looked up in that scope. +Otherwise, it is searched for globally. + +Ordinarily, this function will return an instance of @code{}. +If the named type cannot be found, it will throw an exception. +@end defun + +@defun type-code type +Return the type code for this type. The type code will be one of the +@code{TYPE_CODE_} constants defined below. +@end defun + +@defun type-tag type +Return the tag name for this type. The tag name is the name after +@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all +languages have this concept. If this type has no tag name, then +@code{#f} is returned. +@end defun + +@defun type-sizeof type +Return the size of this type, in target @code{char} units. Usually, a +target's @code{char} type will be an 8-bit byte. However, on some +unusual platforms, this type may have a different size. +@end defun + +@defun type-strip-typedefs type +Return a new @code{} that represents the real type of @var{type}, +after removing all layers of typedefs. +@end defun + +@defun type-array type @var{n1} @r{[}@var{n2}@r{]} +Return a new @code{} 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. +@end defun + +@defun type-vector type @var{n1} @r{[}@var{n2}@r{]} +Return a new @code{} 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 @code{array} and a @code{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. +@end defun + +@defun type-pointer type +Return a new @code{} object which represents a pointer to +@var{type}. +@end defun + +@defun type-range type +Return a list of two elements: the low bound and high bound of @var{type}. +If @var{type} does not have a range, an exception is thrown. +@end defun + +@defun type-reference type +Return a new @code{} object which represents a reference to +@var{type}. +@end defun + +@defun type-target type +Return a new @code{} object which represents the target type +of @var{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. +@end defun + +@defun type-const type +Return a new @code{} object which represents a +@code{const}-qualified variant of @var{type}. +@end defun + +@defun type-volatile type +Return a new @code{} object which represents a +@code{volatile}-qualified variant of @var{type}. +@end defun + +@defun type-unqualified type +Return a new @code{} object which represents an unqualified +variant of @var{type}. That is, the result is neither @code{const} nor +@code{volatile}. +@end defun + +@defun type-name type +Return the name of @code{} @var{type}. +@end defun + +@defun type-num-fields +Return the number of fields of @code{} @var{type}. +@end defun + +@defun type-fields type +Return the fields of @var{type} as a list. +For structure and union types, @code{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@t{++} 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. +@xref{Fields of a Type in Guile}. +@end defun + +@defun make-field-iterator type +Return the fields of @var{type} as a object. +@xref{Iterators In Guile}. +@end defun + +@defun type-field type field-name +Return field named @var{field-name} in @var{type}. +The result is an object of type @code{}. +@xref{Fields of a Type in Guile}. +If the type does not have fields, or @var{field-name} is not a field +of @var{type}, an exception is thrown. + +For example, if @code{some-type} is a @code{} instance holding +a structure type, you can access its @code{foo} field with: + +@smallexample +(define bar (type-field some-type "foo")) +@end smallexample + +@code{bar} will be a @code{} object. +@end defun + +@defun type-has-field? type name +Return @code{#t} if @code{} @var{type} has field named @var{name}. +@end defun + +Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the @code{(gdb)} module: + +@table @code +@findex TYPE_CODE_PTR +@item TYPE_CODE_PTR +The type is a pointer. + +@findex TYPE_CODE_ARRAY +@item TYPE_CODE_ARRAY +The type is an array. + +@findex TYPE_CODE_STRUCT +@item TYPE_CODE_STRUCT +The type is a structure. + +@findex TYPE_CODE_UNION +@item TYPE_CODE_UNION +The type is a union. + +@findex TYPE_CODE_ENUM +@item TYPE_CODE_ENUM +The type is an enum. + +@findex TYPE_CODE_FLAGS +@item TYPE_CODE_FLAGS +A bit flags type, used for things such as status registers. + +@findex TYPE_CODE_FUNC +@item TYPE_CODE_FUNC +The type is a function. + +@findex TYPE_CODE_INT +@item TYPE_CODE_INT +The type is an integer type. + +@findex TYPE_CODE_FLT +@item TYPE_CODE_FLT +A floating point type. + +@findex TYPE_CODE_VOID +@item TYPE_CODE_VOID +The special type @code{void}. + +@findex TYPE_CODE_SET +@item TYPE_CODE_SET +A Pascal set type. + +@findex TYPE_CODE_RANGE +@item TYPE_CODE_RANGE +A range type, that is, an integer type with bounds. + +@findex TYPE_CODE_STRING +@item 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. + +@findex TYPE_CODE_BITSTRING +@item TYPE_CODE_BITSTRING +A string of bits. It is deprecated. + +@findex TYPE_CODE_ERROR +@item TYPE_CODE_ERROR +An unknown or erroneous type. + +@findex TYPE_CODE_METHOD +@item TYPE_CODE_METHOD +A method type, as found in C@t{++} or Java. + +@findex TYPE_CODE_METHODPTR +@item TYPE_CODE_METHODPTR +A pointer-to-member-function. + +@findex TYPE_CODE_MEMBERPTR +@item TYPE_CODE_MEMBERPTR +A pointer-to-member. + +@findex TYPE_CODE_REF +@item TYPE_CODE_REF +A reference type. + +@findex TYPE_CODE_CHAR +@item TYPE_CODE_CHAR +A character type. + +@findex TYPE_CODE_BOOL +@item TYPE_CODE_BOOL +A boolean type. + +@findex TYPE_CODE_COMPLEX +@item TYPE_CODE_COMPLEX +A complex float type. + +@findex TYPE_CODE_TYPEDEF +@item TYPE_CODE_TYPEDEF +A typedef to some other type. + +@findex TYPE_CODE_NAMESPACE +@item TYPE_CODE_NAMESPACE +A C@t{++} namespace. + +@findex TYPE_CODE_DECFLOAT +@item TYPE_CODE_DECFLOAT +A decimal floating point type. + +@findex TYPE_CODE_INTERNAL_FUNCTION +@item TYPE_CODE_INTERNAL_FUNCTION +A function internal to @value{GDBN}. This is the type used to represent +convenience functions. +@end table + +Further support for types is provided in the @code{(gdb types)} +Guile module (@pxref{Guile Types Module}). + +@anchor{Fields of a Type in Guile} +Each field is represented as an object of type @code{}. + +The following field-related procedures are provided by the +@code{(gdb)} module: + +@defun field? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun field-name field +Return the name of the field, or @code{#f} for anonymous fields. +@end defun + +@defun field-type field +Return the type of the field. This is usually an instance of +@code{}, but it can be @code{#f} in some situations. +@end defun + +@defun field-enumval field +Return the enum value represented by @code{} @var{field}. +@end defun + +@defun field-bitpos field +Return the bit position of @code{} @var{field}. +This attribute is not available for @code{static} fields (as in +C@t{++} or Java). +@end defun + +@defun field-bitsize field +If the field is packed, or is a bitfield, return the size of +@code{} @var{field} in bits. Otherwise, zero is returned; +in which case the field's size is given by its type. +@end defun + +@defun field-artificial? field +Return @code{#t} if the field is artificial, usually meaning that +it was provided by the compiler and not the user. +@end defun + +@defun field-base-class? field +Return @code{#t} if the field represents a base class of a C@t{++} +structure. +@end defun + +@node Guile Pretty Printing API +@subsubsection Guile Pretty Printing API + +An example output is provided (@pxref{Pretty Printing}). + +A pretty-printer is represented by an object of type . +Pretty-printer objects are created with @code{make-pretty-printer}. + +The following pretty-printer-related procedures are provided by the +@code{(gdb)} module: + +@defun make-pretty-printer name lookup-function +Return a @code{} object named @var{name}. + +@var{lookup-function} is a function of one parameter: the value to +be printed. If the value is handled by this pretty-printer, then +@var{lookup-function} returns an object of type + to perform the actual pretty-printing. +Otherwise @var{lookup-function} returns @code{#f}. +@end defun + +@defun pretty-printer? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun pretty-printer-enabled? pretty-printer +Return @code{#t} if @var{pretty-printer} is enabled. +@end defun + +@defun set-pretty-printer-enabled! pretty-printer flag +Set the enabled flag of @var{pretty-printer} to @var{flag}. +The value returned in unspecified. +@end defun + +@defun make-pretty-printer-worker display-hint to-string children +Return an object of type @code{}. + +This function takes three parameters: + +@table @samp +@item display-hint +@var{display-hint} provides a hint to @value{GDBN} or @value{GDBN} +front end via MI to change the formatting of the value being printed. +The value must be a string or @code{#f} (meaning there is no hint). +Several values for @var{display-hint} +are predefined by @value{GDBN}: + +@table @samp +@item array +Indicate that the object being printed is ``array-like''. The CLI +uses this to respect parameters such as @code{set print elements} and +@code{set print array}. + +@item 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. + +@item string +Indicate that the object being printed is ``string-like''. If the +printer's @code{to-string} function returns a Guile string of some +kind, then @value{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 +@code{set print elements}, and the like. +@end table + +@item to-string +@var{to-string} is either a function of one parameter, the +@code{} object, or @code{#f}. + +When printing from the CLI, if the @code{to-string} method exists, +then @value{GDBN} will prepend its result to the values returned by +@code{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 (@pxref{Print Settings}), the CLI may +print just the result of @code{to-string} in a stack trace, omitting +the result of @code{children}. + +If this method returns a string, it is printed verbatim. + +Otherwise, if this method returns an instance of @code{}, +then @value{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 +@code{}, then @value{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 @code{}; other types are not. + +Finally, if this method returns @code{#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. + +@var{to-string} may also be @code{#f} in which case it is left to +@var{children} to print the value. + +@item children +@var{children} is either a function of one parameter, the +@code{} object, or @code{#f}. + +@value{GDBN} will call this function on a pretty-printer to compute the +children of the pretty-printer's value. + +This function must return a 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 @value{GDBN} value. + +If @var{children} is @code{#f}, @value{GDBN} will act +as though the value has no children. +@end table +@end defun + +@value{GDBN} provides a function which can be used to look up the +default pretty-printer for a @code{}: + +@defun default-visualizer value +This function takes a @code{} object as an argument. If a +pretty-printer for this value exists, then it is returned. If no such +printer exists, then this returns @code{#f}. +@end defun + +@node Selecting Guile Pretty-Printers +@subsubsection Selecting Guile Pretty-Printers + +The Guile list @code{*pretty-printers*} contains a set of +@code{} registered objects. +Printers in this list are called @code{global} +printers, they're available when debugging any inferior. +In addition to this, each @code{} object contains its +own set of pretty-printers (@pxref{Objfiles In Guile}). + +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-@code{#f} value +or when the list is exhausted. + +@value{GDBN} first checks the result of @code{objfile-pretty-printers} +of each @code{} in the current program space and iteratively +calls each enabled lookup function in the list for that @code{} +until a non-@code{#f} object is returned. +Lookup functions must return either a @code{} +object or @code{#f}. Otherwise an exception is thrown. +If no pretty-printer is found in the objfile lists, @value{GDBN} then +searches the global pretty-printer list, calling each enabled function +until a non-@code{#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 +@code{} 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 +@value{GDBN} provides support for enabling and disabling individual +printers. For example, if @code{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 +@code{set-pretty-printer-enabled!}. +@xref{Guile Pretty Printing API}. + +@node Writing a Guile Pretty-Printer +@subsubsection Writing a Guile Pretty-Printer +@cindex 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 @code{std::string} printer might be +written. @xref{Guile Pretty Printing API}, for details. + +@smallexample +(define (make-my-string-printer value) + "Print a my::string string" + (make-pretty-printer-worker + "string" + (lambda (printer) + (value-field value "_data")) + #f)) +@end smallexample + +And here is an example showing how a lookup function for the printer +example above might be written. + +@smallexample +(define (string-begins-with str prefix) + (= (string-prefix-length str prefix) (string-length prefix))) + +(define (str-lookup-function value) + (let ((tag (type-tag (value-type value)))) + (and tag + (string-begins-with tag "my::string<") + (make-std-string-printer value)))) +@end smallexample + +Then to register this printer in the global printer list: + +@smallexample +(append-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function)) +@end smallexample + +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 object. +If not, it returns @code{#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 @value{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 (@pxref{Guile Auto-loading}) such that it +can be evaluated multiple times without changing its meaning. An +ideal auto-load file will consist solely of @code{import}s 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 +@value{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, @value{GDBN} will find the correct +printers for the specific version of the library used by each +inferior. + +To continue the @code{my::string} example, +this code might appear in @code{(my-project my-library v1)}: + +@smallexample +(use-modules ((gdb))) +(define (register-printers objfile) + (append-objfile-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function))) +@end smallexample + +@noindent +And then the corresponding contents of the auto-load file would be: + +@smallexample +(use-modules ((gdb) (my-project my-library v1))) +(register-printers (current-objfile)) +@end smallexample + +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 +@dfn{subprinters} are the printers for the individual data types. + +The @code{(gdb printing)} module provides a formal way of solving this +problem (@pxref{Guile Printing Module}). +Here is another example that handles multiple types. + +These are the types we are going to pretty-print: + +@smallexample +struct foo @{ int a, b; @}; +struct bar @{ struct foo x, y; @}; +@end smallexample + +Here are the printers: + +@smallexample +(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)) +@end smallexample + +This example doesn't need a lookup function, that is handled by the +@code{(gdb printing)} module. Instead a function is provided to build up +the object that handles the lookup. + +@smallexample +(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)) +@end smallexample + +And here is the autoload support: + +@smallexample +(use-modules ((gdb) (my-library))) +(append-objfile-pretty-printer! (current-objfile) (build-pretty-printer)) +@end smallexample + +Finally, when this printer is loaded into @value{GDBN}, here is the +corresponding output of @samp{info pretty-printer}: + +@smallexample +(gdb) info pretty-printer +my_library.so: + my-library + foo + bar +@end smallexample + +@node Objfiles In Guile +@subsubsection Objfiles In Guile + +@cindex objfiles in guile +@tindex +@value{GDBN} loads symbols for an inferior from various +symbol-containing files (@pxref{Files}). These include the primary +executable file, any shared libraries used by the inferior, and any +separate debug info files (@pxref{Separate Debug Files}). +@value{GDBN} calls these symbol-containing files @dfn{objfiles}. + +Each objfile is represented as an object of type @code{}. + +The following objfile-related procedures are provided by the +@code{(gdb)} module: + +@defun objfile? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun objfile-valid? objfile +Return @code{#t} if @var{objfile} is valid, @code{#f} if not. +A @code{} object can become invalid +if the object file it refers to is not loaded in @value{GDBN} any +longer. All other @code{} procedures will throw an exception +if it is invalid at the time the procedure is called. +@end defun + +@defun objfile-filename objfile +Return the file name of @var{objfile} as a string. +@end defun + +@defun objfile-pretty-printers objfile +Return the list of registered @code{} objects for +@var{objfile}. @xref{Guile Pretty Printing API}, for more information. +@end defun + +@defun set-objfile-pretty-printers! objfile printer-list +Set the list of registered @code{} objects for +@var{objfile} to @var{printer-list}. +@var{printer-list} must be a list of @code{} objects. +@xref{Guile Pretty Printing API}, for more information. +@end defun + +@defun current-objfile +When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN} +sets the ``current objfile'' to the corresponding objfile. This +function returns the current objfile. If there is no current objfile, +this function returns @code{#f}. +@end defun + +@defun objfiles +Return a list of all the objfiles in the current program space. +@end defun + +@node Frames In Guile +@subsubsection Accessing inferior stack frames from Guile. + +@cindex frames in guile +When the debugged program stops, @value{GDBN} is able to analyze its call +stack (@pxref{Frames,,Stack frames}). The @code{} class +represents a frame in the stack. A @code{} object is only valid +while its corresponding frame exists in the inferior's stack. If you try +to use an invalid frame object, @value{GDBN} will throw a +@code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}). + +Two @code{} objects can be compared for equality with the +@code{equal?} function, like: + +@smallexample +(@value{GDBP}) guile (equal? (newest-frame) (selected-frame)) +#t +@end smallexample + +The following frame-related procedures are provided by the +@code{(gdb)} module: + +@defun frame? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun frame-valid? frame +Returns @code{#t} if @var{frame} is valid, @code{#f} if not. +A frame object can become invalid if the frame it refers to doesn't +exist anymore in the inferior. All @code{} procedures will throw +an exception if the frame is invalid at the time the procedure is called. +@end defun + +@defun frame-name frame +Return the function name of @var{frame}, or @code{#f} if it can't be +obtained. +@end defun + +@defun frame-arch frame +Return the @code{} object corresponding to @var{frame}'s +architecture. @xref{Architectures In Guile}. +@end defun + +@defun frame-type frame +Return the type of @var{frame}. The value can be one of: + +@table @code +@item NORMAL_FRAME +An ordinary stack frame. + +@item DUMMY_FRAME +A fake stack frame that was created by @value{GDBN} when performing an +inferior function call. + +@item INLINE_FRAME +A frame representing an inlined function. The function was inlined +into a @code{NORMAL_FRAME} that is older than this one. + +@item TAILCALL_FRAME +A frame representing a tail call. @xref{Tail Call Frames}. + +@item SIGTRAMP_FRAME +A signal trampoline frame. This is the frame created by the OS when +it calls into a signal handler. + +@item ARCH_FRAME +A fake stack frame representing a cross-architecture call. + +@item SENTINEL_FRAME +This is like @code{NORMAL_FRAME}, but it is only used for the +newest frame. +@end table +@end defun + +@defun 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 +@code{unwind-stop-reason-string} to convert the value returned by this +function to a string. The value can be one of: + +@table @code +@item FRAME_UNWIND_NO_REASON +No particular reason (older frames should be available). + +@item FRAME_UNWIND_NULL_ID +The previous frame's analyzer returns an invalid result. + +@item FRAME_UNWIND_OUTERMOST +This frame is the outermost. + +@item FRAME_UNWIND_UNAVAILABLE +Cannot unwind further, because that would require knowing the +values of registers or memory that have not been collected. + +@item 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. + +@item 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. + +@item FRAME_UNWIND_NO_SAVED_PC +The frame unwinder did not find any saved PC, but we needed +one to unwind further. + +@item 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 @value{GDBN} +versions. Using it, you could write: + +@smallexample +(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)) +@end smallexample +@end table +@end defun + +@defun frame-pc frame +Return the frame's resume address. +@end defun + +@defun frame-block frame +Return the frame's code block as a @code{} object. +@xref{Blocks In Guile}. +@end defun + +@defun frame-function frame +Return the symbol for the function corresponding to this frame +as a @code{} object, or @code{#f} if there isn't one. +@xref{Symbols In Guile}. +@end defun + +@defun frame-older frame +Return the frame that called @var{frame}. +@end defun + +@defun frame-newer frame +Return the frame called by @var{frame}. +@end defun + +@defun frame-sal frame +Return the frame's @code{} (symtab and line) object. +@xref{Symbol Tables In Guile}. +@end defun + +@defun frame-read-var variable @r{[}#:block block@r{]} +Return the value of @var{variable} in this frame. If the optional +argument @var{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). @var{variable} +must be a string or a @code{} object. @var{block} must be a +@code{} object. +@end defun + +@defun frame-select frame +Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the +Stack}. +@end defun + +@defun selected-frame +Return the selected frame object. @xref{Selection,,Selecting a Frame}. +@end defun + +@defun newest-frame +Return the newest frame object for the selected thread. +@end defun + +@defun unwind-stop-reason-string reason +Return a string explaining the reason why @value{GDBN} stopped unwinding +frames, as expressed by the given @var{reason} code (an integer, see the +@code{frame-unwind-stop-reason} procedure above in this section). +@end defun + +@node Blocks In Guile +@subsubsection Accessing blocks from Guile. + +@cindex blocks in guile +@tindex + +In @value{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 @code{}. Blocks rely on debugging information being +available. + +A frame has a block. Please see @ref{Frames In Guile}, for a more +in-depth discussion of frames. + +The outermost block is known as the @dfn{global block}. The global +block typically holds public global variables and functions. + +The block nested just inside the global block is the @dfn{static +block}. The static block typically holds file-scoped variables and +functions. + +@value{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 (@pxref{Symbol Tables In +Guile}). + +Here is a short example that should help explain blocks: + +@smallexample +/* 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 (); + @} +@} +@end smallexample + +The following block-related procedures are provided by the +@code{(gdb)} module: + +@defun block? object +Return @code{#t} if @var{object} is a @code{} object. +@end defun + +@defun block-valid? block +Returns @code{#t} if @code{} @var{block} is valid, +@code{#f} if not. A block object can become invalid if the block it +refers to doesn't exist anymore in the inferior. All other +@code{} 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. +@end defun + +@defun block-start block +Return the start address of @code{} @var{block}. +@end defun + +@defun block-end block +Return the end address of @code{} @var{block}. +@end defun + +@defun block-function block +Return the name of @code{} @var{block} represented as a +@code{} object. +If the block is not named, then @code{#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. +@end defun + +@defun block-superblock block +Return the block containing @code{} @var{block}. +If the parent block does not exist, then @code{#f} is returned. +@end defun + +@defun block-global-block block +Return the global block associated with @code{} @var{block}. +@end defun + +@defun block-static-block block +Return the static block associated with @code{} @var{block}. +@end defun + +@defun block-global? block +Return @code{#t} if @code{} @var{block} is a global block. +@end defun + +@defun block-static? block +Return @code{#t} if @code{} @var{block} is a static block. +@end defun + +@defun block-symbols +Return a list of all symbols (as objects) in +@code{} @var{block}. +@end defun + +@defun make-block-symbols-iterator block +Return an object of type @code{} 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 @value{GDBN} features and +infrastructure may cause symbols move across blocks in a symbol table. +@end defun + +@defun block-symbols-progress? +Return #t if the object is a object. +This object would be obtained from the @code{progress} element of the +@code{} object returned by @code{make-block-symbols-iterator}. +@xref{Iterators In Guile}. +@end defun + +@defun lookup-block pc +Return the innermost @code{} containing the given @var{pc} +value. If the block cannot be found for the @var{pc} value specified, +the function will return @code{#f}. +@end defun + +@node Symbols In Guile +@subsubsection Guile representation of Symbols. + +@cindex symbols in guile +@tindex + +@value{GDBN} represents every variable, function and type as an +entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}. +Guile represents these symbols in @value{GDBN} with the +@code{} object. + +The following symbol-related procedures are provided by the +@code{(gdb)} module: + +@defun symbol? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun symbol-valid? symbol +Return @code{#t} if the @code{} object is valid, +@code{#f} if not. A @code{} object can become invalid if +the symbol it refers to does not exist in @value{GDBN} any longer. +All other @code{} procedures will throw an exception if it is +invalid at the time the procedure is called. +@end defun + +@defun symbol-type symbol +Return the type of @var{symbol} or @code{#f} if no type is recorded. +The result is an object of type @code{}. +@xref{Types In Guile}. +@end defun + +@defun symbol-symtab symbol +Return the symbol table in which @var{symbol} appears. +The result is an object of type @code{}. +@xref{Symbol Tables In Guile}. +@end defun + +@defun symbol-line symbol +Return the line number in the source code at which @var{symbol} was defined. +This is an integer. +@end defun + +@defun symbol-name symbol +Return the name of @var{symbol} as a string. +@end defun + +@defun symbol-linkage-name symbol +Return the name of @var{symbol}, as used by the linker (i.e., may be mangled). +@end defun + +@defun symbol-print-name symbol +Return the name of @var{symbol} in a form suitable for output. This is either +@code{name} or @code{linkage_name}, depending on whether the user +asked @value{GDBN} to display demangled or mangled names. +@end defun + +@defun 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 +@code{(gdb)} module and described later in this chapter. +@end defun + +@defun symbol-needs-frame? symbol +Return @code{#t} if evaluating @var{symbol}'s value requires a frame +(@pxref{Frames In Guile}) and @code{#f} otherwise. Typically, +local variables will require a frame, but other symbols will not. +@end defun + +@defun symbol-argument? symbol +Return @code{#t} if @var{symbol} is an argument of a function. +@end defun + +@defun symbol-constant? symbol +Return @code{#t} if @var{symbol} is a constant. +@end defun + +@defun symbol-function? symbol +Return @code{#t} if @var{symbol} is a function or a method. +@end defun + +@defun symbol-variable? symbol +Return @code{#t} if @var{symbol} is a variable. +@end defun + +@defun symbol-value symbol @r{[}#:frame frame@r{]} +Compute the value of @var{symbol}, as a @code{}. 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 @var{frame} must be given. If @var{frame} is not +given, or if @var{frame} is invalid, then an exception is thrown. +@end defun + +@c TODO: line length +@defun lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]} +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. + +@var{name} is the name of the symbol. It must be a string. The +optional @var{block} argument restricts the search to symbols visible +in that @var{block}. The @var{block} argument must be a +@code{} object. If omitted, the block for the current frame +is used. The optional @var{domain} argument restricts +the search to the domain type. The @var{domain} argument must be a +domain constant defined in the @code{(gdb)} module and described later +in this chapter. + +The result is a list of two elements. +The first element is a @code{} object or @code{#f} if the symbol +is not found. +If the symbol is found, the second element is @code{#t} if the symbol +is a field of a method's object (e.g., @code{this} in C@t{++}), +otherwise it is @code{#f}. +If the symbol is not found, the second element is @code{#f}. +@end defun + +@defun lookup-global-symbol name @r{[}#:domain domain@r{]} +This function searches for a global symbol by name. +The search scope can be restricted by the domain argument. + +@var{name} is the name of the symbol. It must be a string. +The optional @var{domain} argument restricts the search to the domain type. +The @var{domain} argument must be a domain constant defined in the @code{(gdb)} +module and described later in this chapter. + +The result is a @code{} object or @code{#f} if the symbol +is not found. +@end defun + +The available domain categories in @code{} are represented +as constants in the @code{(gdb)} module: + +@table @code +@findex SYMBOL_UNDEF_DOMAIN +@item 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 @value{GDBN}'s handling of symbols. +@findex SYMBOL_VAR_DOMAIN +@item SYMBOL_VAR_DOMAIN +This domain contains variables, function names, typedef names and enum +type values. +@findex SYMBOL_STRUCT_DOMAIN +@item SYMBOL_STRUCT_DOMAIN +This domain holds struct, union and enum type names. +@findex SYMBOL_LABEL_DOMAIN +@item SYMBOL_LABEL_DOMAIN +This domain contains names of labels (for gotos). +@findex SYMBOL_VARIABLES_DOMAIN +@item SYMBOL_VARIABLES_DOMAIN +This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it +contains everything minus functions and types. +@findex SYMBOL_FUNCTIONS_DOMAIN +@item SYMBOL_FUNCTION_DOMAIN +This domain contains all functions. +@findex SYMBOL_TYPES_DOMAIN +@item SYMBOL_TYPES_DOMAIN +This domain contains all types. +@end table + +The available address class categories in @code{} are represented +as constants in the @code{gdb} module: + +@table @code +@findex SYMBOL_LOC_UNDEF +@item SYMBOL_LOC_UNDEF +If this is returned by address class, it indicates an error either in +the symbol information or in @value{GDBN}'s handling of symbols. +@findex SYMBOL_LOC_CONST +@item SYMBOL_LOC_CONST +Value is constant int. +@findex SYMBOL_LOC_STATIC +@item SYMBOL_LOC_STATIC +Value is at a fixed address. +@findex SYMBOL_LOC_REGISTER +@item SYMBOL_LOC_REGISTER +Value is in a register. +@findex SYMBOL_LOC_ARG +@item SYMBOL_LOC_ARG +Value is an argument. This value is at the offset stored within the +symbol inside the frame's argument list. +@findex SYMBOL_LOC_REF_ARG +@item SYMBOL_LOC_REF_ARG +Value address is stored in the frame's argument list. Just like +@code{LOC_ARG} except that the value's address is stored at the +offset, not the value itself. +@findex SYMBOL_LOC_REGPARM_ADDR +@item SYMBOL_LOC_REGPARM_ADDR +Value is a specified register. Just like @code{LOC_REGISTER} except +the register holds the address of the argument instead of the argument +itself. +@findex SYMBOL_LOC_LOCAL +@item SYMBOL_LOC_LOCAL +Value is a local variable. +@findex SYMBOL_LOC_TYPEDEF +@item SYMBOL_LOC_TYPEDEF +Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all +have this class. +@findex SYMBOL_LOC_BLOCK +@item SYMBOL_LOC_BLOCK +Value is a block. +@findex SYMBOL_LOC_CONST_BYTES +@item SYMBOL_LOC_CONST_BYTES +Value is a byte-sequence. +@findex SYMBOL_LOC_UNRESOLVED +@item 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. +@findex SYMBOL_LOC_OPTIMIZED_OUT +@item SYMBOL_LOC_OPTIMIZED_OUT +The value does not actually exist in the program. +@findex SYMBOL_LOC_COMPUTED +@item SYMBOL_LOC_COMPUTED +The value's address is a computed location. +@end table + +@node Symbol Tables In Guile +@subsubsection Symbol table representation in Guile. + +@cindex symbol tables in guile +@tindex +@tindex + +Access to symbol table data maintained by @value{GDBN} on the inferior +is exposed to Guile via two objects: @code{} (symtab-and-line) and +@code{}. Symbol table and line data for a frame is returned +from the @code{frame-find-sal} @code{} procedure. +@xref{Frames In Guile}. + +For more information on @value{GDBN}'s symbol table management, see +@ref{Symbols, ,Examining the Symbol Table}. + +The following symtab-related procedures are provided by the +@code{(gdb)} module: + +@defun symtab? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun symtab-valid? symtab +Return @code{#t} if the @code{} object is valid, +@code{#f} if not. A @code{} object becomes invalid when +the symbol table it refers to no longer exists in @value{GDBN}. +All other @code{} procedures will throw an exception +if it is invalid at the time the procedure is called. +@end defun + +@defun symtab-filename symtab +Return the symbol table's source filename. +@end defun + +@defun symtab-fullname symtab +Return the symbol table's source absolute file name. +@end defun + +@defun symtab-objfile symtab +Return the symbol table's backing object file. @xref{Objfiles In Guile}. +@end defun + +@defun symtab-global-block symtab +Return the global block of the underlying symbol table. +@xref{Blocks In Guile}. +@end defun + +@defun symtab-static-block symtab +Return the static block of the underlying symbol table. +@xref{Blocks In Guile}. +@end defun + +The following symtab-and-line-related procedures are provided by the +@code{(gdb)} module: + +@defun sal? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun sal-valid? sal +Return @code{#t} if @var{sal} is valid, @code{#f} if not. +A @code{} object becomes invalid when the Symbol table object +it refers to no longer exists in @value{GDBN}. All other +@code{} procedures will throw an exception if it is +invalid at the time the procedure is called. +@end defun + +@defun sal-symtab sal +Return the symbol table object (@code{}) for @var{sal}. +@end defun + +@defun sal-line sal +Return the line number for @var{sal}. +@end defun + +@defun sal-pc sal +Return the start of the address range occupied by code for @var{sal}. +@end defun + +@defun sal-last sal +Return the end of the address range occupied by code for @var{sal}. +@end defun + +@defun find-pc-line pc +Return the @code{} object corresponding to the @var{pc} value. +If an invalid value of @var{pc} is passed as an argument, then the +@code{symtab} and @code{line} attributes of the returned @code{} +object will be @code{#f} and 0 respectively. +@end defun + +@node Breakpoints In Guile +@subsubsection Manipulating breakpoints using Guile + +@cindex breakpoints in guile +@tindex + +Breakpoints in Guile are represented by objects of type +@code{}. + +The following breakpoint-related procedures are provided by the +@code{(gdb)} module: + +@c TODO: line length +@defun make-breakpoint location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]} +Create a new breakpoint. @var{spec} is a string naming the +location of the breakpoint, or an expression that defines a watchpoint. +The contents can be any location recognized by the @code{break} command, +or in the case of a watchpoint, by the @code{watch} command. + +The optional @var{type} denotes the breakpoint to create. +This argument can be either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. +@var{type} defaults to @code{BP_BREAKPOINT}. + +The optional @var{wp-class} argument defines the class of watchpoint to +create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is +not provided, it is assumed to be a @code{WP_WRITE} class. + +The optional @var{internal} argument allows the breakpoint to become +invisible to the user. The breakpoint will neither be reported when +created, nor will it be listed in the output from @code{info breakpoints} +(but will be listed with the @code{maint info breakpoints} command). +If an internal flag is not provided, the breakpoint is visible +(non-internal). + +When a watchpoint is created, @value{GDBN} will try to create a +hardware assisted watchpoint. If successful, the type of the watchpoint +is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT} +for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ}, +and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}. +If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}. + +The available types are represented by constants defined in the @code{gdb} +module: + +@table @code +@findex BP_BREAKPOINT +@item BP_BREAKPOINT +Normal code breakpoint. + +@findex BP_WATCHPOINT +@item BP_WATCHPOINT +Watchpoint breakpoint. + +@findex BP_HARDWARE_WATCHPOINT +@item BP_HARDWARE_WATCHPOINT +Hardware assisted watchpoint. +This value cannot be specified when creating the breakpoint. + +@findex BP_READ_WATCHPOINT +@item BP_READ_WATCHPOINT +Hardware assisted read watchpoint. +This value cannot be specified when creating the breakpoint. + +@findex BP_ACCESS_WATCHPOINT +@item BP_ACCESS_WATCHPOINT +Hardware assisted access watchpoint. +This value cannot be specified when creating the breakpoint. +@end table + +The available watchpoint types represented by constants are defined in the +@code{(gdb)} module: + +@table @code +@findex WP_READ +@item WP_READ +Read only watchpoint. + +@findex WP_WRITE +@item WP_WRITE +Write only watchpoint. + +@findex WP_ACCESS +@item WP_ACCESS +Read/Write watchpoint. +@end table + +@end defun + +@defun breakpoint-delete! breakpoint +Permanently delete @var{breakpoint}. This also invalidates the +Guile @var{breakpoint} object. Any further attempt to access the +object will throw an exception. +@end defun + +@defun breakpoints +Return a list of all breakpoints. +Each element of the list is a @code{} object. +@end defun + +@defun breakpoint? object +Return @code{#t} if @var{object} is a @code{} object, +and @code{#f} otherwise. +@end defun + +@defun breakpoint-valid? breakpoint +Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise. +A @code{} 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. +@end defun + +@defun breakpoint-number breakpoint +Return the breakpoint's number --- the identifier used by +the user to manipulate the breakpoint. +@end defun + +@defun breakpoint-type breakpoint +Return the breakpoint's type --- the identifier used to +determine the actual breakpoint type or use-case. +@end defun + +@defun breakpoint-visible? breakpoint +Return @code{#t} if the breakpoint is visible to the user +when hit, or when the @samp{info breakpoints} command is run. +@end defun + +@defun 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 @code{#f}. +@end defun + +@defun 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 @code{#f}. +@end defun + +@defun breakpoint-enabled? breakpoint +Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise. +@end defun + +@defun set-breakpoint-enabled! breakpoint flag +Set the enabled state of @var{breakpoint} to @var{flag}. +If flag is @code{#f} it is disabled, otherwise it is enabled. +@end defun + +@defun breakpoint-silent? breakpoint +Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise. + +Note that a breakpoint can also be silent if it has commands and the +first command is @code{silent}. This is not reported by the +@code{silent} attribute. +@end defun + +@defun set-breakpoint-silent! breakpoint flag +Set the silent state of @var{breakpoint} to @var{flag}. +If flag is @code{#f} the breakpoint is made silent, +otherwise it is made non-silent (or noisy). +@end defun + +@defun breakpoint-ignore-count breakpoint +Return the ignore count for @var{breakpoint}. +@end defun + +@defun set-breakpoint-ignore-count! breakpoint count +Set the ignore count for @var{breakpoint} to @var{count}. +@end defun + +@defun breakpoint-hit-count breakpoint +Return hit count of @var{breakpoint}. +@end defun + +@defun set-breakpoint-hit-count! breakpoint count +Set the hit count of @var{breakpoint} to @var{count}. +At present, @var{count} must be zero. +@end defun + +@defun breakpoint-thread breakpoint +Return the thread-id for thread-specific breakpoint @var{breakpoint}. +Return #f if @var{breakpoint} is not thread-specific. +@end defun + +@defun set-breakpoint-thread! breakpoint thread-id|#f +Set the thread-id for @var{breakpoint} to @var{thread-id}. +If set to @code{#f}, the breakpoint is no longer thread-specific. +@end defun + +@defun 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 @code{#f}. +@end defun + +@defun set-breakpoint-task! breakpoint task +Set the Ada task of @var{breakpoint} to @var{task}. +If set to @code{#f}, the breakpoint is no longer task-specific. +@end defun + +@defun breakpoint-condition breakpoint +Return the condition of @var{breakpoint}, as specified by the user. +It is a string. If there is no condition, return @code{#f}. +@end defun + +@defun set-breakpoint-condition! breakpoint condition +Set the condition of @var{breakpoint} to @var{condition}, +which must be a string. If set to @code{#f} then the breakpoint +becomes unconditional. +@end defun + +@defun breakpoint-stop breakpoint +Return the stop predicate of @var{breakpoint}. +See @code{set-breakpoint-stop!} below in this section. +@end defun + +@defun set-breakpoint-stop! breakpoint procedure|#f +Set the stop predicate of @var{breakpoint}. +@var{procedure} takes one argument: the object. +If this predicate is set to a procedure then it is invoked whenever +the inferior reaches this breakpoint. If it returns @code{#t}, +or any non-@code{#f} value, then the inferior is stopped, +otherwise the inferior will continue. + +If there are multiple breakpoints at the same location with a +@code{stop} predicate, each one will be called regardless of the +return status of the previous. This ensures that all @code{stop} +predicates have a chance to execute at that location. In this scenario +if one of the methods returns @code{#t} but the others return +@code{#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 @value{GDBN} or the inferior +at this time. + +Example @code{stop} implementation: + +@smallexample +(define (my-stop? bkpt) + (let ((int-val (parse-and-eval "foo"))) + (value=? int-val 3))) +(define bkpt (make-breakpoint "main.c:42")) +(set-breakpoint-stop! bkpt my-stop?) +@end smallexample +@end defun + +@defun breakpoint-commands breakpoint +Return the commands attached to @var{breakpoint} as a string, +or @code{#f} if there are none. +@end defun + +@node Lazy Strings In Guile +@subsubsection Guile representation of lazy strings. + +@cindex lazy strings in guile +@tindex + +A @dfn{lazy string} is a string whose contents is not retrieved or +encoded until it is needed. + +A @code{} is represented in @value{GDBN} as an +@code{address} that points to a region of memory, an @code{encoding} +that will be used to encode that region of memory, and a @code{length} +to delimit the region of memory that represents the string. The +difference between a @code{} and a string wrapped within +a @code{} is that a @code{} will be treated +differently by @value{GDBN} when printing. A @code{} is +retrieved and encoded during printing, while a @code{} +wrapping a string is immediately retrieved and encoded on creation. + +The following lazy-string-related procedures are provided by the +@code{(gdb)} module: + +@defun lazy-string? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun lazy-string-address lazy-sring +Return the address of @var{lazy-string}. +@end defun + +@defun lazy-string-length lazy-string +Return the length of @var{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. +@end defun + +@defun lazy-string-encoding lazy-string +Return the encoding that will be applied to @var{lazy-string} +when the string is printed by @value{GDBN}. If the encoding is not +set, or contains an empty string, then @value{GDBN} will select the +most appropriate encoding when the string is printed. +@end defun + +@defun lazy-string-type lazy-string +Return the type that is represented by @var{lazy-string}'s type. +For a lazy string this will always be a pointer type. To +resolve this to the lazy string's character type, use @code{type-target-type}. +@xref{Types In Guile}. +@end defun + +@defun lazy-string->value lazy-string +Convert the @code{} to a @code{}. This value +will point to the string in memory, but will lose all the delayed +retrieval, encoding and handling that @value{GDBN} applies to a +@code{}. +@end defun + +@node Architectures In Guile +@subsubsection Guile representation of architectures + +@cindex guile architectures +@tindex + +@value{GDBN} uses architecture specific parameters and artifacts in a +number of its various computations. An architecture is represented +by an instance of the @code{} class. + +The following architecture-related procedures are provided by the +@code{(gdb)} module: + +@defun arch? object +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun current-arch +Return the current architecture as a @code{} object. +@end defun + +@defun arch-name arch +Return the name (string value) of @code{} @var{arch}. +@end defun + +@defun arch-charset arch +Return name of target character set of @code{} @var{arch}. +@end defun + +@defun arch-wide-charset +Return name of target wide character set of @code{} @var{arch}. +@end defun + +Each architecture provides a set of predefined types, obtained by +the following functions. + +@defun arch-void-type arch +Return the @code{} object for a @code{void} type +of architecture @var{arch}. +@end defun + +@defun arch-char-type arch +Return the @code{} object for a @code{char} type +of architecture @var{arch}. +@end defun + +@defun arch-short-type arch +Return the @code{} object for a @code{short} type +of architecture @var{arch}. +@end defun + +@defun arch-int-type arch +Return the @code{} object for an @code{int} type +of architecture @var{arch}. +@end defun + +@defun arch-long-type arch +Return the @code{} object for a @code{long} type +of architecture @var{arch}. +@end defun + +@defun arch-schar-type arch +Return the @code{} object for a @code{signed char} type +of architecture @var{arch}. +@end defun + +@defun arch-uchar-type arch +Return the @code{} object for an @code{unsigned char} type +of architecture @var{arch}. +@end defun + +@defun arch-ushort-type arch +Return the @code{} object for an @code{unsigned short} type +of architecture @var{arch}. +@end defun + +@defun arch-uint-type arch +Return the @code{} object for an @code{unsigned int} type +of architecture @var{arch}. +@end defun + +@defun arch-ulong-type arch +Return the @code{} object for an @code{unsigned long} type +of architecture @var{arch}. +@end defun + +@defun arch-float-type arch +Return the @code{} object for a @code{float} type +of architecture @var{arch}. +@end defun + +@defun arch-double-type arch +Return the @code{} object for a @code{double} type +of architecture @var{arch}. +@end defun + +@defun arch-longdouble-type arch +Return the @code{} object for a @code{long double} type +of architecture @var{arch}. +@end defun + +@defun arch-bool-type arch +Return the @code{} object for a @code{bool} type +of architecture @var{arch}. +@end defun + +@defun arch-longlong-type arch +Return the @code{} object for a @code{long long} type +of architecture @var{arch}. +@end defun + +@defun arch-ulonglong-type arch +Return the @code{} object for an @code{unsigned long long} type +of architecture @var{arch}. +@end defun + +@defun arch-int8-type arch +Return the @code{} object for an @code{int8} type +of architecture @var{arch}. +@end defun + +@defun arch-uint8-type arch +Return the @code{} object for a @code{uint8} type +of architecture @var{arch}. +@end defun + +@defun arch-int16-type arch +Return the @code{} object for an @code{int16} type +of architecture @var{arch}. +@end defun + +@defun arch-uint16-type arch +Return the @code{} object for a @code{uint16} type +of architecture @var{arch}. +@end defun + +@defun arch-int32-type arch +Return the @code{} object for an @code{int32} type +of architecture @var{arch}. +@end defun + +@defun arch-uint32-type arch +Return the @code{} object for a @code{uint32} type +of architecture @var{arch}. +@end defun + +@defun arch-int64-type arch +Return the @code{} object for an @code{int64} type +of architecture @var{arch}. +@end defun + +@defun arch-uint64-type arch +Return the @code{} object for a @code{uint64} type +of architecture @var{arch}. +@end defun + +Example: + +@smallexample +(gdb) guile (type-name (arch-uchar-type (current-arch))) +"unsigned char" +@end smallexample + +@node Disassembly In Guile +@subsubsection 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. + +@c TODO: line length +@defun arch-disassemble arch @var{start-pc} @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size @var{size}@r{]} @r{[}#:count @var{count}@r{]}) +Return a list of disassembled instructions starting from the memory +address @var{start-pc}. + +The optional argument @var{port} specifies the input port to read bytes from. +If @var{port} is @code{#f} then bytes are read from target memory. + +The optional argument @var{offset} specifies the address offset of the +first byte in @var{port}. This is useful, for example, when @var{port} +specifies a @samp{bytevector} and you want the bytevector to be disassembled +as if it came from that address. The @var{start-pc} passed to the reader +for @var{port} is offset by the same amount. + +Example: +@smallexample +(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))) +@end smallexample + +The optional arguments @var{size} and +@var{count} determine the number of instructions in the returned list. +If either @var{size} or @var{count} is specified as zero, then +no instructions are disassembled and an empty list is returned. +If both the optional arguments @var{size} and @var{count} are +specified, then a list of at most @var{count} disassembled instructions +whose start address falls in the closed memory address interval from +@var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned. +If @var{size} is not specified, but @var{count} is specified, +then @var{count} number of instructions starting from the address +@var{start-pc} are returned. If @var{count} is not specified but +@var{size} is specified, then all instructions whose start address +falls in the closed memory address interval from @var{start-pc} to +(@var{start-pc} + @var{size} - 1) are returned. +If neither @var{size} nor @var{count} are specified, then a single +instruction at @var{start-pc} is returned. + +Each element of the returned list is an alist (associative list) +with the following keys: + +@table @code + +@item address +The value corresponding to this key is a Guile integer of +the memory address of the instruction. + +@item 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 @code{disassembly-flavor}. @xref{Machine Code}. + +@item length +The value corresponding to this key is the length of the instruction in bytes. + +@end table +@end defun + +@node I/O Ports in Guile +@subsubsection I/O Ports in Guile + +@defun input-port +Return @value{GDBN}'s input port as a Guile port object. +@end defun + +@defun output-port +Return @value{GDBN}'s output port as a Guile port object. +@end defun + +@defun error-port +Return @value{GDBN}'s error port as a Guile port object. +@end defun + +@node Memory Ports in Guile +@subsubsection Memory Ports in Guile + +@value{GDBN} provides a @code{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 @code{open-memory} which +returns a port object. One can then read/write memory using that object. + +@defun open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]} +Return a port object that can be used for reading and writing memory. +@var{mode} is the standard mode argument to Guile port open routines, +except that it is restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. +For compatibility @samp{"b"} (binary) may also be present, +but we ignore it: memory ports are binary only. +The default is @samp{"r"}, read-only. + +The chunk of memory that can be accessed can be bounded. +If both @var{start} and @var{size} are unspecified, all of memory can be +accessed. If only @var{start} is specified, all of memory from that point +on can be accessed. If only @var{size} if specified, all memory in the +range [0,@var{size} can be accessed. If both are specified, all memory +in the rane [@var{start},@var{start}+@var{size}) can be accessed. +@end defun + +@defun memory-port? +Return @code{#t} if @var{object} is an object of type @code{}. +@end defun + +@defun memory-port-range memory-port +Return the range of @code{} @var{memory-port} as a list +of two elements: @code{(start end)}. The range is @var{start} to @var{end} +inclusive. +@end defun + +@defun memory-port-read-buffer-size memory-port +Return the size of the read buffer of @code{} +@var{memory-port}. +@end defun + +@defun set-memory-port-read-buffer-size! memory-port size +Set the size of the read buffer of @code{} +@var{memory-port} to @var{size}. The result is unspecified. +@end defun + +@defun memory-port-write-buffer-size memory-port +Return the size of the write buffer of @code{} +@var{memory-port}. +@end defun + +@defun set-memory-port-write-buffer-size! memory-port size +Set the size of the write buffer of @code{} +@var{memory-port} to @var{size}. The result is unspecified. +@end defun + +A memory port is closed like any other port, with @code{close-port}. + +Combined with Guile's @code{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. + +@smallexample +;; 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) +@end smallexample + +@node Iterators In Guile +@subsubsection Iterators In Guile + +@cindex guile iterators +@tindex + +An experimental 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. Scheme has support for iterators via, +for example, SRFI 41 and SRFI 45. Hopefully something efficient and +agreeable can be worked out that uses them or something else. + +@defun make-iterator +A @code{} object is constructed with the @code{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. + +A trivial example for illustration's sake: + +@smallexample +(use-modules (gdb experimental)) +(define my-list (list 1 2 3)) +(define end-marker #f) +(define iter (make-iterator my-list my-list + (lambda (iter) + (let ((l (iterator-progress iter))) + (if (eq? l '()) + end-marker + (begin + (set-iterator-progress! iter (cdr l)) + (car l))))))) +@end smallexample + +It is not expected that iterators will be used like that, +that was just for illustration's sake. +Here is a slightly more realistic example, which computes a list of all the +functions in @code{my-global-block}. + +@smallexample +(use-modules (gdb experimental)) +(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 #f)) +@end smallexample +@end defun + +These functions are provided to assist in writing the @code{next!} procedure: + +@table @code +@item iterator-object +Return the first argument that was passed to @code{make-iterator}. +This is the object being iterated over. + +@item iterator-progress +Return the object tracking iteration progress. + +@item set-iterator-progress! +Set the object tracking iteration progress. + +@item iterator-next! +Invoke the procedure that was the third argument to @code{make-iterator}, +passing it one argument, the @code{} object. +The result is either the next element in the iteration, or and end +marker as implemented by the @code{next!} procedure. +@end table + +@node Guile Auto-loading +@subsection Guile Auto-loading +@cindex guile auto-loading + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for Guile support scripts in two ways: +@file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section. +@xref{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. + +@table @code +@anchor{set auto-load guile-scripts} +@kindex set auto-load guile-scripts +@item set auto-load guile-scripts [on|off] +Enable or disable the auto-loading of Guile scripts. + +@anchor{show auto-load guile-scripts} +@kindex show auto-load guile-scripts +@item show auto-load guile-scripts +Show whether auto-loading of Guile scripts is enabled or disabled. + +@anchor{info auto-load guile-scripts} +@kindex info auto-load guile-scripts +@cindex print list of auto-loaded Guile scripts +@item info auto-load guile-scripts [@var{regexp}] +Print the list of all Guile scripts that @value{GDBN} auto-loaded. + +Also printed is the list of Guile scripts that were mentioned in +the @code{.debug_gdb_scripts} section and were not found. +This is useful because their names are not printed when @value{GDBN} +tries to load them and fails. There may be many of them, and printing +an error message for each one is problematic. + +If @var{regexp} is supplied only Guile scripts with matching names are printed. + +Example: + +@smallexample +(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 +@end smallexample +@end table + +When reading an auto-loaded file, @value{GDBN} sets the +@dfn{current objfile}. This is available via the @code{current-objfile} +procedure (@pxref{Objfiles In Guile}). This can be useful for +registering objfile-specific pretty-printers. + +@node Guile Modules +@subsection Guile Modules +@cindex guile modules + +@value{GDBN} comes with several modules to assist writing Guile code. + +@menu +* Guile Printing Module:: Building and registering pretty-printers +* Guile Types Module:: Utilities for working with types +@end menu + +@node Guile Printing Module +@subsubsection Guile Printing Module +@cindex (gdb printing) + +This module provides a collection of utilities for working with +pretty-printers. + +Usage: + +@smallexample +(use-modules (gdb printing)) +@end smallexample + +@table @code +@item prepend-pretty-printer! @var{obj} @var{printer} +Add @var{printer} to the front of the list of pretty-printers for @var{obj}. +@var{obj} must either be a @code{} object or @code{#f} in which +case @var{printer} is added to the global list of printers. + +@item append-pretty-printer! @var{obj} @var{printer} +Add @var{printer} to the end of the list of pretty-printers for @var{obj}. +@var{obj} must either be a @code{} object or @code{#f} in which +case @var{printer} is added to the global list of printers. +@end table + +@node Guile Types Module +@subsubsection Guile Types Module +@cindex (gdb types) + +This module provides a collection of utilities for working with +@code{} objects. + +Usage: + +@smallexample +(use-modules (gdb types)) +@end smallexample + +@table @code +@item get-basic-type @var{type} +Return @var{type} with const and volatile qualifiers stripped, +and with typedefs and C@t{++} references converted to the underlying type. + +C@t{++} example: + +@smallexample +typedef const int const_int; +const_int foo (3); +const_int& foo_ref (foo); +int main () @{ return 0; @} +@end smallexample + +Then in gdb: + +@smallexample +(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 +@end smallexample + +@item type-has-field-deep? @var{type} @var{field} +Return @code{#t} if @var{type}, assumed to be a type with fields +(e.g., a structure or union), has field @var{field}. +This searches baseclasses, whereas @code{type-has-field?} does not. + +@item make-enum-hashtable @var{enum-type} +Return a Guile hash table produced from @var{enum-type}. +Elements in the hash table are referenced with @code{hashq-ref}. +@end table