1 @c Copyright (C) 2008-2015 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Guile
15 @cindex guile scripting
16 @cindex scripting with guile
18 You can extend @value{GDBN} using the @uref{http://www.gnu.org/software/guile/,
19 Guile implementation of the Scheme programming language}.
20 This feature is available only if @value{GDBN} was configured using
21 @option{--with-guile}.
24 * Guile Introduction:: Introduction to Guile scripting in @value{GDBN}
25 * Guile Commands:: Accessing Guile from @value{GDBN}
26 * Guile API:: Accessing @value{GDBN} from Guile
27 * Guile Auto-loading:: Automatically loading Guile code
28 * Guile Modules:: Guile modules provided by @value{GDBN}
31 @node Guile Introduction
32 @subsection Guile Introduction
34 Guile is an implementation of the Scheme programming language
35 and is the GNU project's official extension language.
37 Guile support in @value{GDBN} follows the Python support in @value{GDBN}
38 reasonably closely, so concepts there should carry over.
39 However, some things are done differently where it makes sense.
41 @value{GDBN} requires Guile version 2.0 or greater.
42 Older versions are not supported.
44 @cindex guile scripts directory
45 Guile scripts used by @value{GDBN} should be installed in
46 @file{@var{data-directory}/guile}, where @var{data-directory} is
47 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
48 This directory, known as the @dfn{guile directory},
49 is automatically added to the Guile Search Path in order to allow
50 the Guile interpreter to locate all scripts installed at this location.
53 @subsection Guile Commands
54 @cindex guile commands
55 @cindex commands to access guile
57 @value{GDBN} provides two commands for accessing the Guile interpreter:
64 The @code{guile-repl} command can be used to start an interactive
65 Guile prompt or @dfn{repl}. To return to @value{GDBN},
66 type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on
67 an empty prompt). These commands do not take any arguments.
71 @item guile @r{[}@var{scheme-expression}@r{]}
72 @itemx gu @r{[}@var{scheme-expression}@r{]}
73 The @code{guile} command can be used to evaluate a Scheme expression.
75 If given an argument, @value{GDBN} will pass the argument to the Guile
76 interpreter for evaluation.
79 (@value{GDBP}) guile (display (+ 20 3)) (newline)
83 The result of the Scheme expression is displayed using normal Guile rules.
86 (@value{GDBP}) guile (+ 20 3)
90 If you do not provide an argument to @code{guile}, it will act as a
91 multi-line command, like @code{define}. In this case, the Guile
92 script is made up of subsequent command lines, given after the
93 @code{guile} command. This command list is terminated using a line
94 containing @code{end}. For example:
105 It is also possible to execute a Guile script from the @value{GDBN}
109 @item source @file{script-name}
110 The script name must end with @samp{.scm} and @value{GDBN} must be configured
111 to recognize the script language based on filename extension using
112 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
114 @item guile (load "script-name")
115 This method uses the @code{load} Guile function.
116 It takes a string argument that is the name of the script to load.
117 See the Guile documentation for a description of this function.
118 (@pxref{Loading,,, guile, GNU Guile Reference Manual}).
122 @subsection Guile API
124 @cindex programming in guile
126 You can get quick online help for @value{GDBN}'s Guile API by issuing
127 the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help}
128 from an interactive Guile session. Furthermore, most Guile procedures
129 provided by @value{GDBN} have doc strings which can be obtained with
130 @kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}}
131 from the Guile interactive prompt.
134 * Basic Guile:: Basic Guile Functions
135 * Guile Configuration:: Guile configuration variables
136 * GDB Scheme Data Types:: Scheme representations of GDB objects
137 * Guile Exception Handling:: How Guile exceptions are translated
138 * Values From Inferior In Guile:: Guile representation of values
139 * Arithmetic In Guile:: Arithmetic in Guile
140 * Types In Guile:: Guile representation of types
141 * Guile Pretty Printing API:: Pretty-printing values with Guile
142 * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
143 * Writing a Guile Pretty-Printer:: Writing a pretty-printer
144 * Commands In Guile:: Implementing new commands in Guile
145 * Parameters In Guile:: Adding new @value{GDBN} parameters
146 * Progspaces In Guile:: Program spaces
147 * Objfiles In Guile:: Object files in Guile
148 * Frames In Guile:: Accessing inferior stack frames from Guile
149 * Blocks In Guile:: Accessing blocks from Guile
150 * Symbols In Guile:: Guile representation of symbols
151 * Symbol Tables In Guile:: Guile representation of symbol tables
152 * Breakpoints In Guile:: Manipulating breakpoints using Guile
153 * Lazy Strings In Guile:: Guile representation of lazy strings
154 * Architectures In Guile:: Guile representation of architectures
155 * Disassembly In Guile:: Disassembling instructions from Guile
156 * I/O Ports in Guile:: GDB I/O ports
157 * Memory Ports in Guile:: Accessing memory through ports and bytevectors
158 * Iterators In Guile:: Basic iterator support
162 @subsubsection Basic Guile
165 @cindex guile pagination
166 At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
167 @code{current-error-port} to print using @value{GDBN}'s output-paging streams.
168 A Guile program which outputs to one of these streams may have its
169 output interrupted by the user (@pxref{Screen Size}). In this
170 situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
172 Guile's history mechanism uses the same naming as @value{GDBN}'s,
173 namely the user of dollar-variables (e.g., $1, $2, etc.).
174 The results of evaluations in Guile and in GDB are counted separately,
175 @code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}.
177 @value{GDBN} is not thread-safe. If your Guile program uses multiple
178 threads, you must be careful to only call @value{GDBN}-specific
179 functions in the @value{GDBN} thread.
181 Some care must be taken when writing Guile code to run in
182 @value{GDBN}. Two things are worth noting in particular:
186 @value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
187 Guile code must not override these, or even change the options using
188 @code{sigaction}. If your program changes the handling of these
189 signals, @value{GDBN} will most likely stop working correctly. Note
190 that it is unfortunately common for GUI toolkits to install a
191 @code{SIGCHLD} handler.
194 @value{GDBN} takes care to mark its internal file descriptors as
195 close-on-exec. However, this cannot be done in a thread-safe way on
196 all platforms. Your Guile programs should be aware of this and
197 should both create new file descriptors with the close-on-exec flag
198 set and arrange to close unneeded file descriptors before starting a
202 @cindex guile gdb module
203 @value{GDBN} introduces a new Guile module, named @code{gdb}. All
204 methods and classes added by @value{GDBN} are placed in this module.
205 @value{GDBN} does not automatically @code{import} the @code{gdb} module,
206 scripts must do this themselves. There are various options for how to
207 import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
208 module is imported to the user.
209 To simplify interactive use, it is recommended to add one of the following
213 guile (use-modules (gdb))
217 guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
220 Which one to choose depends on your preference.
221 The second one adds @code{gdb:} as a prefix to all module functions
224 The rest of this manual assumes the @code{gdb} module has been imported
225 without any prefix. See the Guile documentation for @code{use-modules}
227 (@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}).
232 (gdb) guile (value-type (make-value 1))
233 ERROR: Unbound variable: value-type
234 Error while executing Scheme code.
235 (gdb) guile (use-modules (gdb))
236 (gdb) guile (value-type (make-value 1))
241 The @code{(gdb)} module provides these basic Guile functions.
244 @deffn {Scheme Procedure} execute command @r{[}#:from-tty boolean@r{]} @r{[}#:to-string boolean@r{]}
245 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
246 If a @value{GDBN} exception happens while @var{command} runs, it is
247 translated as described in
248 @ref{Guile Exception Handling,,Guile Exception Handling}.
250 @var{from-tty} specifies whether @value{GDBN} ought to consider this
251 command as having originated from the user invoking it interactively.
252 It must be a boolean value. If omitted, it defaults to @code{#f}.
254 By default, any output produced by @var{command} is sent to
255 @value{GDBN}'s standard output (and to the log output if logging is
256 turned on). If the @var{to-string} parameter is
257 @code{#t}, then output will be collected by @code{execute} and
258 returned as a string. The default is @code{#f}, in which case the
259 return value is unspecified. If @var{to-string} is @code{#t}, the
260 @value{GDBN} virtual terminal will be temporarily set to unlimited width
261 and height, and its pagination will be disabled; @pxref{Screen Size}.
264 @deffn {Scheme Procedure} history-ref number
265 Return a value from @value{GDBN}'s value history (@pxref{Value
266 History}). The @var{number} argument indicates which history element to return.
267 If @var{number} is negative, then @value{GDBN} will take its absolute value
268 and count backward from the last element (i.e., the most recent element) to
269 find the value to return. If @var{number} is zero, then @value{GDBN} will
270 return the most recent element. If the element specified by @var{number}
271 doesn't exist in the value history, a @code{gdb:error} exception will be
274 If no exception is raised, the return value is always an instance of
275 @code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
277 @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
278 @code{$1} in @value{GDBN}'s value history contains the result of evaluating
279 an expression from @value{GDBN}'s command line and @code{$1} from Guile's
280 history contains the result of evaluating an expression from Guile's
284 @deffn {Scheme Procedure} history-append! value
285 Append @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
286 value history. Return its index in the history.
288 Putting into history values returned by Guile extensions will allow
289 the user convenient access to those values via CLI history
293 @deffn {Scheme Procedure} parse-and-eval expression
294 Parse @var{expression} as an expression in the current language,
295 evaluate it, and return the result as a @code{<gdb:value>}.
296 The @var{expression} must be a string.
298 This function can be useful when implementing a new command
299 (@pxref{Commands In Guile}), as it provides a way to parse the
300 command's arguments as an expression.
301 It is also is useful when computing values.
302 For example, it is the only way to get the value of a
303 convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
306 @node Guile Configuration
307 @subsubsection Guile Configuration
308 @cindex guile configuration
310 @value{GDBN} provides these Scheme functions to access various configuration
313 @deffn {Scheme Procedure} data-directory
314 Return a string containing @value{GDBN}'s data directory.
315 This directory contains @value{GDBN}'s ancillary files.
318 @deffn {Scheme Procedure} guile-data-directory
319 Return a string containing @value{GDBN}'s Guile data directory.
320 This directory contains the Guile modules provided by @value{GDBN}.
323 @deffn {Scheme Procedure} gdb-version
324 Return a string containing the @value{GDBN} version.
327 @deffn {Scheme Procedure} host-config
328 Return a string containing the host configuration.
329 This is the string passed to @code{--host} when @value{GDBN} was configured.
332 @deffn {Scheme Procedure} target-config
333 Return a string containing the target configuration.
334 This is the string passed to @code{--target} when @value{GDBN} was configured.
337 @node GDB Scheme Data Types
338 @subsubsection GDB Scheme Data Types
341 The values exposed by @value{GDBN} to Guile are known as
342 @dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN}
343 object, and each is disjoint from all other types known to Guile.
345 @deffn {Scheme Procedure} gdb-object-kind object
346 Return the kind of the @value{GDBN} object, e.g., @code{<gdb:breakpoint>},
350 @value{GDBN} defines the following object types:
354 @xref{Architectures In Guile}.
357 @xref{Blocks In Guile}.
359 @item <gdb:block-symbols-iterator>
360 @xref{Blocks In Guile}.
362 @item <gdb:breakpoint>
363 @xref{Breakpoints In Guile}.
366 @xref{Commands In Guile}.
368 @item <gdb:exception>
369 @xref{Guile Exception Handling}.
372 @xref{Frames In Guile}.
375 @xref{Iterators In Guile}.
377 @item <gdb:lazy-string>
378 @xref{Lazy Strings In Guile}.
381 @xref{Objfiles In Guile}.
383 @item <gdb:parameter>
384 @xref{Parameters In Guile}.
386 @item <gdb:pretty-printer>
387 @xref{Guile Pretty Printing API}.
389 @item <gdb:pretty-printer-worker>
390 @xref{Guile Pretty Printing API}.
392 @item <gdb:progspace>
393 @xref{Progspaces In Guile}.
396 @xref{Symbols In Guile}.
399 @xref{Symbol Tables In Guile}.
402 @xref{Symbol Tables In Guile}.
405 @xref{Types In Guile}.
408 @xref{Types In Guile}.
411 @xref{Values From Inferior In Guile}.
414 The following @value{GDBN} objects are managed internally so that the
415 Scheme function @code{eq?} may be applied to them.
420 @item <gdb:breakpoint>
423 @item <gdb:progspace>
429 @node Guile Exception Handling
430 @subsubsection Guile Exception Handling
431 @cindex guile exceptions
432 @cindex exceptions, guile
433 @kindex set guile print-stack
435 When executing the @code{guile} command, Guile exceptions
436 uncaught within the Guile code are translated to calls to the
437 @value{GDBN} error-reporting mechanism. If the command that called
438 @code{guile} does not handle the error, @value{GDBN} will
439 terminate it and report the error according to the setting of
440 the @code{guile print-stack} parameter.
442 The @code{guile print-stack} parameter has three settings:
449 An error message is printed containing the Guile exception name,
450 the associated value, and the Guile call stack backtrace at the
451 point where the exception was raised. Example:
454 (@value{GDBP}) guile (display foo)
455 ERROR: In procedure memoize-variable-access!:
456 ERROR: Unbound variable: foo
457 Error while executing Scheme code.
461 In addition to an error message a full backtrace is printed.
464 (@value{GDBP}) set guile print-stack full
465 (@value{GDBP}) guile (display foo)
468 157: 10 [catch #t #<catch-closure 2c76e20> ...]
470 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
472 157: 8 [catch #t #<catch-closure 2c76d20> ...]
474 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
475 ?: 6 [call-with-input-string "(display foo)" ...]
477 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
478 In ice-9/eval-string.scm:
479 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
480 37: 3 [lp (display foo)]
483 393: 1 [eval #<memoized foo> ()]
485 ?: 0 [memoize-variable-access! #<memoized foo> ...]
487 ERROR: In procedure memoize-variable-access!:
488 ERROR: Unbound variable: foo
489 Error while executing Scheme code.
493 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
494 Guile code are converted to Guile exceptions. The type of the
495 Guile exception depends on the error.
497 Guile procedures provided by @value{GDBN} can throw the standard
498 Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
500 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
501 prompt) is translated to a Guile @code{signal} exception with value
504 @value{GDBN} Guile procedures can also throw these exceptions:
508 This exception is a catch-all for errors generated from within @value{GDBN}.
510 @item gdb:invalid-object
511 This exception is thrown when accessing Guile objects that wrap underlying
512 @value{GDBN} objects have become invalid. For example, a
513 @code{<gdb:breakpoint>} object becomes invalid if the user deletes it
514 from the command line. The object still exists in Guile, but the
515 object it represents is gone. Further operations on this breakpoint
516 will throw this exception.
518 @item gdb:memory-error
519 This exception is thrown when an operation tried to access invalid
520 memory in the inferior.
522 @item gdb:pp-type-error
523 This exception is thrown when a Guile pretty-printer passes a bad object
527 The following exception-related procedures are provided by the
530 @deffn {Scheme Procedure} make-exception key args
531 Return a @code{<gdb:exception>} object given by its @var{key} and
532 @var{args}, which are the standard Guile parameters of an exception.
533 See the Guile documentation for more information (@pxref{Exceptions,,,
534 guile, GNU Guile Reference Manual}).
537 @deffn {Scheme Procedure} exception? object
538 Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
539 Otherwise return @code{#f}.
542 @deffn {Scheme Procedure} exception-key exception
543 Return the @var{args} field of a @code{<gdb:exception>} object.
546 @deffn {Scheme Procedure} exception-args exception
547 Return the @var{args} field of a @code{<gdb:exception>} object.
550 @node Values From Inferior In Guile
551 @subsubsection Values From Inferior In Guile
552 @cindex values from inferior, in guile
553 @cindex guile, working with values from inferior
555 @tindex @code{<gdb:value>}
556 @value{GDBN} provides values it obtains from the inferior program in
557 an object of type @code{<gdb:value>}. @value{GDBN} uses this object
558 for its internal bookkeeping of the inferior's values, and for
559 fetching values when necessary.
561 @value{GDBN} does not memoize @code{<gdb:value>} objects.
562 @code{make-value} always returns a fresh object.
565 (gdb) guile (eq? (make-value 1) (make-value 1))
567 (gdb) guile (equal? (make-value 1) (make-value 1))
571 A @code{<gdb:value>} that represents a function can be executed via
572 inferior function call with @code{value-call}.
573 Any arguments provided to the call must match the function's prototype,
574 and must be provided in the order specified by that prototype.
576 For example, @code{some-val} is a @code{<gdb:value>} instance
577 representing a function that takes two integers as arguments. To
578 execute this function, call it like so:
581 (define result (value-call some-val 10 20))
584 Any values returned from a function call are @code{<gdb:value>} objects.
586 Note: Unlike Python scripting in @value{GDBN},
587 inferior values that are simple scalars cannot be used directly in
588 Scheme expressions that are valid for the value's data type.
589 For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
590 And inferior values that are structures or instances of some class cannot
591 be accessed using any special syntax, instead @code{value-field} must be used.
593 The following value-related procedures are provided by the
596 @deffn {Scheme Procedure} value? object
597 Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
598 Otherwise return @code{#f}.
601 @deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]}
602 Many Scheme values can be converted directly to a @code{<gdb:value>}
603 with this procedure. If @var{type} is specified, the result is a value
604 of this type, and if @var{value} can't be represented with this type
605 an exception is thrown. Otherwise the type of the result is determined from
606 @var{value} as described below.
608 @xref{Architectures In Guile}, for a list of the builtin
609 types for an architecture.
611 Here's how Scheme values are converted when @var{type} argument to
612 @code{make-value} is not specified:
616 A Scheme boolean is converted the boolean type for the current language.
619 A Scheme integer is converted to the first of a C @code{int},
620 @code{unsigned int}, @code{long}, @code{unsigned long},
621 @code{long long} or @code{unsigned long long} type
622 for the current architecture that can represent the value.
624 If the Scheme integer cannot be represented as a target integer
625 an @code{out-of-range} exception is thrown.
628 A Scheme real is converted to the C @code{double} type for the
629 current architecture.
632 A Scheme string is converted to a string in the current target
633 language using the current target encoding.
634 Characters that cannot be represented in the current target encoding
635 are replaced with the corresponding escape sequence. This is Guile's
636 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy
637 (@pxref{Strings,,, guile, GNU Guile Reference Manual}).
639 Passing @var{type} is not supported in this case,
640 if it is provided a @code{wrong-type-arg} exception is thrown.
642 @item @code{<gdb:lazy-string>}
643 If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
644 Guile}), then the @code{lazy-string->value} procedure is called, and
647 Passing @var{type} is not supported in this case,
648 if it is provided a @code{wrong-type-arg} exception is thrown.
650 @item Scheme bytevector
651 If @var{value} is a Scheme bytevector and @var{type} is provided,
652 @var{value} must be the same size, in bytes, of values of type @var{type},
653 and the result is essentially created by using @code{memcpy}.
655 If @var{value} is a Scheme bytevector and @var{type} is not provided,
656 the result is an array of type @code{uint8} of the same length.
660 @cindex optimized out value in guile
661 @deffn {Scheme Procedure} value-optimized-out? value
662 Return @code{#t} if the compiler optimized out @var{value},
663 thus it is not available for fetching from the inferior.
664 Otherwise return @code{#f}.
667 @deffn {Scheme Procedure} value-address value
668 If @var{value} is addressable, returns a
669 @code{<gdb:value>} object representing the address.
670 Otherwise, @code{#f} is returned.
673 @deffn {Scheme Procedure} value-type value
674 Return the type of @var{value} as a @code{<gdb:type>} object
675 (@pxref{Types In Guile}).
678 @deffn {Scheme Procedure} value-dynamic-type value
679 Return the dynamic type of @var{value}. This uses C@t{++} run-time
680 type information (@acronym{RTTI}) to determine the dynamic type of the
681 value. If the value is of class type, it will return the class in
682 which the value is embedded, if any. If the value is of pointer or
683 reference to a class type, it will compute the dynamic type of the
684 referenced object, and return a pointer or reference to that type,
685 respectively. In all other cases, it will return the value's static
688 Note that this feature will only work when debugging a C@t{++} program
689 that includes @acronym{RTTI} for the object in question. Otherwise,
690 it will just return the static type of the value as in @kbd{ptype foo}.
691 @xref{Symbols, ptype}.
694 @deffn {Scheme Procedure} value-cast value type
695 Return a new instance of @code{<gdb:value>} that is the result of
696 casting @var{value} to the type described by @var{type}, which must
697 be a @code{<gdb:type>} object. If the cast cannot be performed for some
698 reason, this method throws an exception.
701 @deffn {Scheme Procedure} value-dynamic-cast value type
702 Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
703 operator were used. Consult a C@t{++} reference for details.
706 @deffn {Scheme Procedure} value-reinterpret-cast value type
707 Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
708 operator were used. Consult a C@t{++} reference for details.
711 @deffn {Scheme Procedure} value-dereference value
712 For pointer data types, this method returns a new @code{<gdb:value>} object
713 whose contents is the object pointed to by @var{value}. For example, if
714 @code{foo} is a C pointer to an @code{int}, declared in your C program as
721 then you can use the corresponding @code{<gdb:value>} to access what
722 @code{foo} points to like this:
725 (define bar (value-dereference foo))
728 The result @code{bar} will be a @code{<gdb:value>} object holding the
729 value pointed to by @code{foo}.
731 A similar function @code{value-referenced-value} exists which also
732 returns @code{<gdb:value>} objects corresonding to the values pointed to
733 by pointer values (and additionally, values referenced by reference
734 values). However, the behavior of @code{value-dereference}
735 differs from @code{value-referenced-value} by the fact that the
736 behavior of @code{value-dereference} is identical to applying the C
737 unary operator @code{*} on a given value. For example, consider a
738 reference to a pointer @code{ptrref}, declared in your C@t{++} program
746 intptr &ptrref = ptr;
749 Though @code{ptrref} is a reference value, one can apply the method
750 @code{value-dereference} to the @code{<gdb:value>} object corresponding
751 to it and obtain a @code{<gdb:value>} which is identical to that
752 corresponding to @code{val}. However, if you apply the method
753 @code{value-referenced-value}, the result would be a @code{<gdb:value>}
754 object identical to that corresponding to @code{ptr}.
757 (define scm-ptrref (parse-and-eval "ptrref"))
758 (define scm-val (value-dereference scm-ptrref))
759 (define scm-ptr (value-referenced-value scm-ptrref))
762 The @code{<gdb:value>} object @code{scm-val} is identical to that
763 corresponding to @code{val}, and @code{scm-ptr} is identical to that
764 corresponding to @code{ptr}. In general, @code{value-dereference} can
765 be applied whenever the C unary operator @code{*} can be applied
766 to the corresponding C value. For those cases where applying both
767 @code{value-dereference} and @code{value-referenced-value} is allowed,
768 the results obtained need not be identical (as we have seen in the above
769 example). The results are however identical when applied on
770 @code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
771 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
774 @deffn {Scheme Procedure} value-referenced-value value
775 For pointer or reference data types, this method returns a new
776 @code{<gdb:value>} object corresponding to the value referenced by the
777 pointer/reference value. For pointer data types,
778 @code{value-dereference} and @code{value-referenced-value} produce
779 identical results. The difference between these methods is that
780 @code{value-dereference} cannot get the values referenced by reference
781 values. For example, consider a reference to an @code{int}, declared
782 in your C@t{++} program as
790 then applying @code{value-dereference} to the @code{<gdb:value>} object
791 corresponding to @code{ref} will result in an error, while applying
792 @code{value-referenced-value} will result in a @code{<gdb:value>} object
793 identical to that corresponding to @code{val}.
796 (define scm-ref (parse-and-eval "ref"))
797 (define err-ref (value-dereference scm-ref)) ;; error
798 (define scm-val (value-referenced-value scm-ref)) ;; ok
801 The @code{<gdb:value>} object @code{scm-val} is identical to that
802 corresponding to @code{val}.
805 @deffn {Scheme Procedure} value-field value field-name
806 Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
809 @deffn {Scheme Procedure} value-subscript value index
810 Return the value of array @var{value} at index @var{index}.
811 The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
814 @deffn {Scheme Procedure} value-call value arg-list
815 Perform an inferior function call, taking @var{value} as a pointer
816 to the function to call.
817 Each element of list @var{arg-list} must be a <gdb:value> object or an object
818 that can be converted to a value.
819 The result is the value returned by the function.
822 @deffn {Scheme Procedure} value->bool value
823 Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
824 The value must be ``integer like''. Pointers are ok.
827 @deffn {Scheme Procedure} value->integer
828 Return the Scheme integer representing @code{<gdb:value>} @var{value}.
829 The value must be ``integer like''. Pointers are ok.
832 @deffn {Scheme Procedure} value->real
833 Return the Scheme real number representing @code{<gdb:value>} @var{value}.
834 The value must be a number.
837 @deffn {Scheme Procedure} value->bytevector
838 Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
839 @var{value}. No transformation, endian or otherwise, is performed.
843 @deffn {Scheme Procedure} value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
844 If @var{value>} represents a string, then this method
845 converts the contents to a Guile string. Otherwise, this method will
848 Values are interpreted as strings according to the rules of the
849 current language. If the optional length argument is given, the
850 string will be converted to that length, and will include any embedded
851 zeroes that the string may contain. Otherwise, for languages
852 where the string is zero-terminated, the entire string will be
855 For example, in C-like languages, a value is a string if it is a pointer
856 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
859 If the optional @var{encoding} argument is given, it must be a string
860 naming the encoding of the string in the @code{<gdb:value>}, such as
861 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
862 the same encodings as the corresponding argument to Guile's
863 @code{scm_from_stringn} function, and the Guile codec machinery will be used
864 to convert the string. If @var{encoding} is not given, or if
865 @var{encoding} is the empty string, then either the @code{target-charset}
866 (@pxref{Character Sets}) will be used, or a language-specific encoding
867 will be used, if the current language is able to supply one.
869 The optional @var{errors} argument is one of @code{#f}, @code{error} or
870 @code{substitute}. @code{error} and @code{substitute} must be symbols.
871 If @var{errors} is not specified, or if its value is @code{#f}, then the
872 default conversion strategy is used, which is set with the Scheme function
873 @code{set-port-conversion-strategy!}.
874 If the value is @code{'error} then an exception is thrown if there is any
875 conversion error. If the value is @code{'substitute} then any conversion
876 error is replaced with question marks.
877 @xref{Strings,,, guile, GNU Guile Reference Manual}.
879 If the optional @var{length} argument is given, the string will be
880 fetched and converted to the given length.
881 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
885 @deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]}
886 If this @code{<gdb:value>} represents a string, then this method
887 converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
888 In Guile}). Otherwise, this method will throw an exception.
890 If the optional @var{encoding} argument is given, it must be a string
891 naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
892 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
893 @var{encoding} argument is an encoding that @value{GDBN} does not
894 recognize, @value{GDBN} will raise an error.
896 When a lazy string is printed, the @value{GDBN} encoding machinery is
897 used to convert the string during printing. If the optional
898 @var{encoding} argument is not provided, or is an empty string,
899 @value{GDBN} will automatically select the encoding most suitable for
900 the string type. For further information on encoding in @value{GDBN}
901 please see @ref{Character Sets}.
903 If the optional @var{length} argument is given, the string will be
904 fetched and encoded to the length of characters specified. If
905 the @var{length} argument is not provided, the string will be fetched
906 and encoded until a null of appropriate width is found.
907 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
910 @deffn {Scheme Procedure} value-lazy? value
911 Return @code{#t} if @var{value} has not yet been fetched
913 Otherwise return @code{#f}.
914 @value{GDBN} does not fetch values until necessary, for efficiency.
918 (define myval (parse-and-eval "somevar"))
921 The value of @code{somevar} is not fetched at this time. It will be
922 fetched when the value is needed, or when the @code{fetch-lazy}
923 procedure is invoked.
926 @deffn {Scheme Procedure} make-lazy-value type address
927 Return a @code{<gdb:value>} that will be lazily fetched from the
928 target. The object of type @code{<gdb:type>} whose value to fetch is
929 specified by its @var{type} and its target memory @var{address}, which
933 @deffn {Scheme Procedure} value-fetch-lazy! value
934 If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
935 then the value is fetched from the inferior.
936 Any errors that occur in the process will produce a Guile exception.
938 If @var{value} is not a lazy value, this method has no effect.
940 The result of this function is unspecified.
943 @deffn {Scheme Procedure} value-print value
944 Return the string representation (print form) of @code{<gdb:value>}
948 @node Arithmetic In Guile
949 @subsubsection Arithmetic In Guile
951 The @code{(gdb)} module provides several functions for performing
952 arithmetic on @code{<gdb:value>} objects.
953 The arithmetic is performed as if it were done by the target,
954 and therefore has target semantics which are not necessarily
955 those of Scheme. For example operations work with a fixed precision,
956 not the arbitrary precision of Scheme.
958 Wherever a function takes an integer or pointer as an operand,
959 @value{GDBN} will convert appropriate Scheme values to perform
962 @deffn {Scheme Procedure} value-add a b
965 @deffn {Scheme Procedure} value-sub a b
968 @deffn {Scheme Procedure} value-mul a b
971 @deffn {Scheme Procedure} value-div a b
974 @deffn {Scheme Procedure} value-rem a b
977 @deffn {Scheme Procedure} value-mod a b
980 @deffn {Scheme Procedure} value-pow a b
983 @deffn {Scheme Procedure} value-not a
986 @deffn {Scheme Procedure} value-neg a
989 @deffn {Scheme Procedure} value-pos a
992 @deffn {Scheme Procedure} value-abs a
995 @deffn {Scheme Procedure} value-lsh a b
998 @deffn {Scheme Procedure} value-rsh a b
1001 @deffn {Scheme Procedure} value-min a b
1004 @deffn {Scheme Procedure} value-max a b
1007 @deffn {Scheme Procedure} value-lognot a
1010 @deffn {Scheme Procedure} value-logand a b
1013 @deffn {Scheme Procedure} value-logior a b
1016 @deffn {Scheme Procedure} value-logxor a b
1019 @deffn {Scheme Procedure} value=? a b
1022 @deffn {Scheme Procedure} value<? a b
1025 @deffn {Scheme Procedure} value<=? a b
1028 @deffn {Scheme Procedure} value>? a b
1031 @deffn {Scheme Procedure} value>=? a b
1034 Scheme does not provide a @code{not-equal} function,
1035 and thus Guile support in @value{GDBN} does not either.
1037 @node Types In Guile
1038 @subsubsection Types In Guile
1039 @cindex types in guile
1040 @cindex guile, working with types
1043 @value{GDBN} represents types from the inferior in objects of type
1046 The following type-related procedures are provided by the
1047 @code{(gdb)} module.
1049 @deffn {Scheme Procedure} type? object
1050 Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
1051 Otherwise return @code{#f}.
1054 @deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
1055 This function looks up a type by its @var{name}, which must be a string.
1057 If @var{block} is given, it is an object of type @code{<gdb:block>},
1058 and @var{name} is looked up in that scope.
1059 Otherwise, it is searched for globally.
1061 Ordinarily, this function will return an instance of @code{<gdb:type>}.
1062 If the named type cannot be found, it will throw an exception.
1065 @deffn {Scheme Procedure} type-code type
1066 Return the type code of @var{type}. The type code will be one of the
1067 @code{TYPE_CODE_} constants defined below.
1070 @deffn {Scheme Procedure} type-tag type
1071 Return the tag name of @var{type}. The tag name is the name after
1072 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1073 languages have this concept. If this type has no tag name, then
1074 @code{#f} is returned.
1077 @deffn {Scheme Procedure} type-name type
1078 Return the name of @var{type}.
1079 If this type has no name, then @code{#f} is returned.
1082 @deffn {Scheme Procedure} type-print-name type
1083 Return the print name of @var{type}.
1084 This returns something even for anonymous types.
1085 For example, for an anonymous C struct @code{"struct @{...@}"} is returned.
1088 @deffn {Scheme Procedure} type-sizeof type
1089 Return the size of this type, in target @code{char} units. Usually, a
1090 target's @code{char} type will be an 8-bit byte. However, on some
1091 unusual platforms, this type may have a different size.
1094 @deffn {Scheme Procedure} type-strip-typedefs type
1095 Return a new @code{<gdb:type>} that represents the real type of @var{type},
1096 after removing all layers of typedefs.
1099 @deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]}
1100 Return a new @code{<gdb:type>} object which represents an array of this
1101 type. If one argument is given, it is the inclusive upper bound of
1102 the array; in this case the lower bound is zero. If two arguments are
1103 given, the first argument is the lower bound of the array, and the
1104 second argument is the upper bound of the array. An array's length
1105 must not be negative, but the bounds can be.
1108 @deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]}
1109 Return a new @code{<gdb:type>} object which represents a vector of this
1110 type. If one argument is given, it is the inclusive upper bound of
1111 the vector; in this case the lower bound is zero. If two arguments are
1112 given, the first argument is the lower bound of the vector, and the
1113 second argument is the upper bound of the vector. A vector's length
1114 must not be negative, but the bounds can be.
1116 The difference between an @code{array} and a @code{vector} is that
1117 arrays behave like in C: when used in expressions they decay to a pointer
1118 to the first element whereas vectors are treated as first class values.
1121 @deffn {Scheme Procedure} type-pointer type
1122 Return a new @code{<gdb:type>} object which represents a pointer to
1126 @deffn {Scheme Procedure} type-range type
1127 Return a list of two elements: the low bound and high bound of @var{type}.
1128 If @var{type} does not have a range, an exception is thrown.
1131 @deffn {Scheme Procedure} type-reference type
1132 Return a new @code{<gdb:type>} object which represents a reference to
1136 @deffn {Scheme Procedure} type-target type
1137 Return a new @code{<gdb:type>} object which represents the target type
1140 For a pointer type, the target type is the type of the pointed-to
1141 object. For an array type (meaning C-like arrays), the target type is
1142 the type of the elements of the array. For a function or method type,
1143 the target type is the type of the return value. For a complex type,
1144 the target type is the type of the elements. For a typedef, the
1145 target type is the aliased type.
1147 If the type does not have a target, this method will throw an
1151 @deffn {Scheme Procedure} type-const type
1152 Return a new @code{<gdb:type>} object which represents a
1153 @code{const}-qualified variant of @var{type}.
1156 @deffn {Scheme Procedure} type-volatile type
1157 Return a new @code{<gdb:type>} object which represents a
1158 @code{volatile}-qualified variant of @var{type}.
1161 @deffn {Scheme Procedure} type-unqualified type
1162 Return a new @code{<gdb:type>} object which represents an unqualified
1163 variant of @var{type}. That is, the result is neither @code{const} nor
1167 @deffn {Scheme Procedure} type-num-fields
1168 Return the number of fields of @code{<gdb:type>} @var{type}.
1171 @deffn {Scheme Procedure} type-fields type
1172 Return the fields of @var{type} as a list.
1173 For structure and union types, @code{fields} has the usual meaning.
1174 Range types have two fields, the minimum and maximum values. Enum types
1175 have one field per enum constant. Function and method types have one
1176 field per parameter. The base types of C@t{++} classes are also
1177 represented as fields. If the type has no fields, or does not fit
1178 into one of these categories, an empty list will be returned.
1179 @xref{Fields of a type in Guile}.
1182 @deffn {Scheme Procedure} make-field-iterator type
1183 Return the fields of @var{type} as a <gdb:iterator> object.
1184 @xref{Iterators In Guile}.
1187 @deffn {Scheme Procedure} type-field type field-name
1188 Return field named @var{field-name} in @var{type}.
1189 The result is an object of type @code{<gdb:field>}.
1190 @xref{Fields of a type in Guile}.
1191 If the type does not have fields, or @var{field-name} is not a field
1192 of @var{type}, an exception is thrown.
1194 For example, if @code{some-type} is a @code{<gdb:type>} instance holding
1195 a structure type, you can access its @code{foo} field with:
1198 (define bar (type-field some-type "foo"))
1201 @code{bar} will be a @code{<gdb:field>} object.
1204 @deffn {Scheme Procedure} type-has-field? type name
1205 Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
1206 Otherwise return @code{#f}.
1209 Each type has a code, which indicates what category this type falls
1210 into. The available type categories are represented by constants
1211 defined in the @code{(gdb)} module:
1215 The type is a pointer.
1217 @item TYPE_CODE_ARRAY
1218 The type is an array.
1220 @item TYPE_CODE_STRUCT
1221 The type is a structure.
1223 @item TYPE_CODE_UNION
1224 The type is a union.
1226 @item TYPE_CODE_ENUM
1227 The type is an enum.
1229 @item TYPE_CODE_FLAGS
1230 A bit flags type, used for things such as status registers.
1232 @item TYPE_CODE_FUNC
1233 The type is a function.
1236 The type is an integer type.
1239 A floating point type.
1241 @item TYPE_CODE_VOID
1242 The special type @code{void}.
1247 @item TYPE_CODE_RANGE
1248 A range type, that is, an integer type with bounds.
1250 @item TYPE_CODE_STRING
1251 A string type. Note that this is only used for certain languages with
1252 language-defined string types; C strings are not represented this way.
1254 @item TYPE_CODE_BITSTRING
1255 A string of bits. It is deprecated.
1257 @item TYPE_CODE_ERROR
1258 An unknown or erroneous type.
1260 @item TYPE_CODE_METHOD
1261 A method type, as found in C@t{++} or Java.
1263 @item TYPE_CODE_METHODPTR
1264 A pointer-to-member-function.
1266 @item TYPE_CODE_MEMBERPTR
1267 A pointer-to-member.
1272 @item TYPE_CODE_CHAR
1275 @item TYPE_CODE_BOOL
1278 @item TYPE_CODE_COMPLEX
1279 A complex float type.
1281 @item TYPE_CODE_TYPEDEF
1282 A typedef to some other type.
1284 @item TYPE_CODE_NAMESPACE
1285 A C@t{++} namespace.
1287 @item TYPE_CODE_DECFLOAT
1288 A decimal floating point type.
1290 @item TYPE_CODE_INTERNAL_FUNCTION
1291 A function internal to @value{GDBN}. This is the type used to represent
1292 convenience functions (@pxref{Convenience Funs}).
1295 Further support for types is provided in the @code{(gdb types)}
1296 Guile module (@pxref{Guile Types Module}).
1298 @anchor{Fields of a type in Guile}
1299 Each field is represented as an object of type @code{<gdb:field>}.
1301 The following field-related procedures are provided by the
1302 @code{(gdb)} module:
1304 @deffn {Scheme Procedure} field? object
1305 Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
1306 Otherwise return @code{#f}.
1309 @deffn {Scheme Procedure} field-name field
1310 Return the name of the field, or @code{#f} for anonymous fields.
1313 @deffn {Scheme Procedure} field-type field
1314 Return the type of the field. This is usually an instance of
1315 @code{<gdb:type>}, but it can be @code{#f} in some situations.
1318 @deffn {Scheme Procedure} field-enumval field
1319 Return the enum value represented by @code{<gdb:field>} @var{field}.
1322 @deffn {Scheme Procedure} field-bitpos field
1323 Return the bit position of @code{<gdb:field>} @var{field}.
1324 This attribute is not available for @code{static} fields (as in
1328 @deffn {Scheme Procedure} field-bitsize field
1329 If the field is packed, or is a bitfield, return the size of
1330 @code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
1331 in which case the field's size is given by its type.
1334 @deffn {Scheme Procedure} field-artificial? field
1335 Return @code{#t} if the field is artificial, usually meaning that
1336 it was provided by the compiler and not the user.
1337 Otherwise return @code{#f}.
1340 @deffn {Scheme Procedure} field-base-class? field
1341 Return @code{#t} if the field represents a base class of a C@t{++}
1343 Otherwise return @code{#f}.
1346 @node Guile Pretty Printing API
1347 @subsubsection Guile Pretty Printing API
1348 @cindex guile pretty printing api
1350 An example output is provided (@pxref{Pretty Printing}).
1352 A pretty-printer is represented by an object of type <gdb:pretty-printer>.
1353 Pretty-printer objects are created with @code{make-pretty-printer}.
1355 The following pretty-printer-related procedures are provided by the
1356 @code{(gdb)} module:
1358 @deffn {Scheme Procedure} make-pretty-printer name lookup-function
1359 Return a @code{<gdb:pretty-printer>} object named @var{name}.
1361 @var{lookup-function} is a function of one parameter: the value to
1362 be printed. If the value is handled by this pretty-printer, then
1363 @var{lookup-function} returns an object of type
1364 <gdb:pretty-printer-worker> to perform the actual pretty-printing.
1365 Otherwise @var{lookup-function} returns @code{#f}.
1368 @deffn {Scheme Procedure} pretty-printer? object
1369 Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
1370 Otherwise return @code{#f}.
1373 @deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer
1374 Return @code{#t} if @var{pretty-printer} is enabled.
1375 Otherwise return @code{#f}.
1378 @deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag
1379 Set the enabled flag of @var{pretty-printer} to @var{flag}.
1380 The value returned is unspecified.
1383 @deffn {Scheme Procedure} pretty-printers
1384 Return the list of global pretty-printers.
1387 @deffn {Scheme Procedure} set-pretty-printers! pretty-printers
1388 Set the list of global pretty-printers to @var{pretty-printers}.
1389 The value returned is unspecified.
1392 @deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children
1393 Return an object of type @code{<gdb:pretty-printer-worker>}.
1395 This function takes three parameters:
1399 @var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
1400 front end via MI to change the formatting of the value being printed.
1401 The value must be a string or @code{#f} (meaning there is no hint).
1402 Several values for @var{display-hint}
1403 are predefined by @value{GDBN}:
1407 Indicate that the object being printed is ``array-like''. The CLI
1408 uses this to respect parameters such as @code{set print elements} and
1409 @code{set print array}.
1412 Indicate that the object being printed is ``map-like'', and that the
1413 children of this value can be assumed to alternate between keys and
1417 Indicate that the object being printed is ``string-like''. If the
1418 printer's @code{to-string} function returns a Guile string of some
1419 kind, then @value{GDBN} will call its internal language-specific
1420 string-printing function to format the string. For the CLI this means
1421 adding quotation marks, possibly escaping some characters, respecting
1422 @code{set print elements}, and the like.
1426 @var{to-string} is either a function of one parameter, the
1427 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1429 When printing from the CLI, if the @code{to-string} method exists,
1430 then @value{GDBN} will prepend its result to the values returned by
1431 @code{children}. Exactly how this formatting is done is dependent on
1432 the display hint, and may change as more hints are added. Also,
1433 depending on the print settings (@pxref{Print Settings}), the CLI may
1434 print just the result of @code{to-string} in a stack trace, omitting
1435 the result of @code{children}.
1437 If this method returns a string, it is printed verbatim.
1439 Otherwise, if this method returns an instance of @code{<gdb:value>},
1440 then @value{GDBN} prints this value. This may result in a call to
1441 another pretty-printer.
1443 If instead the method returns a Guile value which is convertible to a
1444 @code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
1445 the resulting value. Again, this may result in a call to another
1446 pretty-printer. Guile scalars (integers, floats, and booleans) and
1447 strings are convertible to @code{<gdb:value>}; other types are not.
1449 Finally, if this method returns @code{#f} then no further operations
1450 are peformed in this method and nothing is printed.
1452 If the result is not one of these types, an exception is raised.
1454 @var{to-string} may also be @code{#f} in which case it is left to
1455 @var{children} to print the value.
1458 @var{children} is either a function of one parameter, the
1459 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1461 @value{GDBN} will call this function on a pretty-printer to compute the
1462 children of the pretty-printer's value.
1464 This function must return a <gdb:iterator> object.
1465 Each item returned by the iterator must be a tuple holding
1466 two elements. The first element is the ``name'' of the child; the
1467 second element is the child's value. The value can be any Guile
1468 object which is convertible to a @value{GDBN} value.
1470 If @var{children} is @code{#f}, @value{GDBN} will act
1471 as though the value has no children.
1475 @value{GDBN} provides a function which can be used to look up the
1476 default pretty-printer for a @code{<gdb:value>}:
1478 @deffn {Scheme Procedure} default-visualizer value
1479 This function takes a @code{<gdb:value>} object as an argument. If a
1480 pretty-printer for this value exists, then it is returned. If no such
1481 printer exists, then this returns @code{#f}.
1484 @node Selecting Guile Pretty-Printers
1485 @subsubsection Selecting Guile Pretty-Printers
1486 @cindex selecting guile pretty-printers
1488 There are three sets of pretty-printers that @value{GDBN} searches:
1492 Per-objfile list of pretty-printers (@pxref{Objfiles In Guile}).
1494 Per-progspace list of pretty-printers (@pxref{Progspaces In Guile}).
1496 The global list of pretty-printers (@pxref{Guile Pretty Printing API}).
1497 These printers are available when debugging any inferior.
1500 Pretty-printer lookup is done by passing the value to be printed to the
1501 lookup function of each enabled object in turn.
1502 Lookup stops when a lookup function returns a non-@code{#f} value
1503 or when the list is exhausted.
1504 Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
1505 object or @code{#f}. Otherwise an exception is thrown.
1507 @value{GDBN} first checks the result of @code{objfile-pretty-printers}
1508 of each @code{<gdb:objfile>} in the current program space and iteratively
1509 calls each enabled lookup function in the list for that @code{<gdb:objfile>}
1510 until a non-@code{#f} object is returned.
1511 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1512 searches the result of @code{progspace-pretty-printers} of the current
1513 program space, calling each enabled function until a non-@code{#f} object
1515 After these lists have been exhausted, it tries the global pretty-printers
1516 list, obtained with @code{pretty-printers}, again calling each enabled
1517 function until a non-@code{#f} object is returned.
1519 The order in which the objfiles are searched is not specified. For a
1520 given list, functions are always invoked from the head of the list,
1521 and iterated over sequentially until the end of the list, or a
1522 @code{<gdb:pretty-printer-worker>} object is returned.
1524 For various reasons a pretty-printer may not work.
1525 For example, the underlying data structure may have changed and
1526 the pretty-printer is out of date.
1528 The consequences of a broken pretty-printer are severe enough that
1529 @value{GDBN} provides support for enabling and disabling individual
1530 printers. For example, if @code{print frame-arguments} is on,
1531 a backtrace can become highly illegible if any argument is printed
1532 with a broken printer.
1534 Pretty-printers are enabled and disabled from Scheme by calling
1535 @code{set-pretty-printer-enabled!}.
1536 @xref{Guile Pretty Printing API}.
1538 @node Writing a Guile Pretty-Printer
1539 @subsubsection Writing a Guile Pretty-Printer
1540 @cindex writing a Guile pretty-printer
1542 A pretty-printer consists of two basic parts: a lookup function to determine
1543 if the type is supported, and the printer itself.
1545 Here is an example showing how a @code{std::string} printer might be
1546 written. @xref{Guile Pretty Printing API}, for details.
1549 (define (make-my-string-printer value)
1550 "Print a my::string string"
1551 (make-pretty-printer-worker
1554 (value-field value "_data"))
1558 And here is an example showing how a lookup function for the printer
1559 example above might be written.
1562 (define (str-lookup-function pretty-printer value)
1563 (let ((tag (type-tag (value-type value))))
1565 (string-prefix? "std::string<" tag)
1566 (make-my-string-printer value))))
1569 Then to register this printer in the global printer list:
1572 (append-pretty-printer!
1573 (make-pretty-printer "my-string" str-lookup-function))
1576 The example lookup function extracts the value's type, and attempts to
1577 match it to a type that it can pretty-print. If it is a type the
1578 printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
1579 If not, it returns @code{#f}.
1581 We recommend that you put your core pretty-printers into a Guile
1582 package. If your pretty-printers are for use with a library, we
1583 further recommend embedding a version number into the package name.
1584 This practice will enable @value{GDBN} to load multiple versions of
1585 your pretty-printers at the same time, because they will have
1588 You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
1589 can be evaluated multiple times without changing its meaning. An
1590 ideal auto-load file will consist solely of @code{import}s of your
1591 printer modules, followed by a call to a register pretty-printers with
1592 the current objfile.
1594 Taken as a whole, this approach will scale nicely to multiple
1595 inferiors, each potentially using a different library version.
1596 Embedding a version number in the Guile package name will ensure that
1597 @value{GDBN} is able to load both sets of printers simultaneously.
1598 Then, because the search for pretty-printers is done by objfile, and
1599 because your auto-loaded code took care to register your library's
1600 printers with a specific objfile, @value{GDBN} will find the correct
1601 printers for the specific version of the library used by each
1604 To continue the @code{my::string} example,
1605 this code might appear in @code{(my-project my-library v1)}:
1609 (define (register-printers objfile)
1610 (append-objfile-pretty-printer!
1611 (make-pretty-printer "my-string" str-lookup-function)))
1615 And then the corresponding contents of the auto-load file would be:
1618 (use-modules (gdb) (my-project my-library v1))
1619 (register-printers (current-objfile))
1622 The previous example illustrates a basic pretty-printer.
1623 There are a few things that can be improved on.
1624 The printer only handles one type, whereas a library typically has
1625 several types. One could install a lookup function for each desired type
1626 in the library, but one could also have a single lookup function recognize
1627 several types. The latter is the conventional way this is handled.
1628 If a pretty-printer can handle multiple data types, then its
1629 @dfn{subprinters} are the printers for the individual data types.
1631 The @code{(gdb printing)} module provides a formal way of solving this
1632 problem (@pxref{Guile Printing Module}).
1633 Here is another example that handles multiple types.
1635 These are the types we are going to pretty-print:
1638 struct foo @{ int a, b; @};
1639 struct bar @{ struct foo x, y; @};
1642 Here are the printers:
1645 (define (make-foo-printer value)
1646 "Print a foo object"
1647 (make-pretty-printer-worker
1650 (format #f "a=<~a> b=<~a>"
1651 (value-field value "a") (value-field value "a")))
1654 (define (make-bar-printer value)
1655 "Print a bar object"
1656 (make-pretty-printer-worker
1659 (format #f "x=<~a> y=<~a>"
1660 (value-field value "x") (value-field value "y")))
1664 This example doesn't need a lookup function, that is handled by the
1665 @code{(gdb printing)} module. Instead a function is provided to build up
1666 the object that handles the lookup.
1669 (use-modules (gdb printing))
1671 (define (build-pretty-printer)
1672 (let ((pp (make-pretty-printer-collection "my-library")))
1673 (pp-collection-add-tag-printer "foo" make-foo-printer)
1674 (pp-collection-add-tag-printer "bar" make-bar-printer)
1678 And here is the autoload support:
1681 (use-modules (gdb) (my-library))
1682 (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
1685 Finally, when this printer is loaded into @value{GDBN}, here is the
1686 corresponding output of @samp{info pretty-printer}:
1689 (gdb) info pretty-printer
1696 @node Commands In Guile
1697 @subsubsection Commands In Guile
1699 @cindex commands in guile
1700 @cindex guile commands
1701 You can implement new @value{GDBN} CLI commands in Guile. A CLI
1702 command object is created with the @code{make-command} Guile function,
1703 and added to @value{GDBN} with the @code{register-command!} Guile function.
1704 This two-step approach is taken to separate out the side-effect of adding
1705 the command to @value{GDBN} from @code{make-command}.
1707 There is no support for multi-line commands, that is commands that
1708 consist of multiple lines and are terminated with @code{end}.
1710 @c TODO: line length
1711 @deffn {Scheme Procedure} (make-command name @r{[}#:invoke invoke{]} @r{[}#:command-class command-class@r{]} @r{[}#:completer-class completer{]} @r{[}#:prefix? prefix@r{]} @r{[}#:doc doc-string{]})
1713 The argument @var{name} is the name of the command. If @var{name} consists of
1714 multiple words, then the initial words are looked for as prefix
1715 commands. In this case, if one of the prefix commands does not exist,
1716 an exception is raised.
1718 The result is the @code{<gdb:command>} object representing the command.
1719 The command is not usable until it has been registered with @value{GDBN}
1720 with @code{register-command!}.
1722 The rest of the arguments are optional.
1724 The argument @var{invoke} is a procedure of three arguments: @var{self},
1725 @var{args} and @var{from-tty}. The argument @var{self} is the
1726 @code{<gdb:command>} object representing the command.
1727 The argument @var{args} is a string representing the arguments passed to
1728 the command, after leading and trailing whitespace has been stripped.
1729 The argument @var{from-tty} is a boolean flag and specifies whether the
1730 command should consider itself to have been originated from the user
1731 invoking it interactively. If this function throws an exception,
1732 it is turned into a @value{GDBN} @code{error} call.
1733 Otherwise, the return value is ignored.
1735 The argument @var{command-class} is one of the @samp{COMMAND_} constants
1736 defined below. This argument tells @value{GDBN} how to categorize the
1737 new command in the help system. The default is @code{COMMAND_NONE}.
1739 The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_}
1740 constants defined below, or a procedure, also defined below.
1741 This argument tells @value{GDBN} how to perform completion
1742 for this command. If not provided or if the value is @code{#f},
1743 then no completion is performed on the command.
1745 The argument @var{prefix} is a boolean flag indicating whether the new
1746 command is a prefix command; sub-commands of this command may be
1749 The argument @var{doc-string} is help text for the new command.
1750 If no documentation string is provided, the default value ``This command is
1751 not documented.'' is used.
1754 @deffn {Scheme Procedure} register-command! command
1755 Add @var{command}, a @code{<gdb:command>} object, to @value{GDBN}'s
1757 It is an error to register a command more than once.
1758 The result is unspecified.
1761 @deffn {Scheme Procedure} command? object
1762 Return @code{#t} if @var{object} is a @code{<gdb:command>} object.
1763 Otherwise return @code{#f}.
1766 @cindex don't repeat Guile command
1767 @deffn {Scheme Procedure} dont-repeat
1768 By default, a @value{GDBN} command is repeated when the user enters a
1769 blank line at the command prompt. A command can suppress this
1770 behavior by invoking the @code{dont-repeat} function. This is similar
1771 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
1774 @deffn {Scheme Procedure} string->argv string
1775 Convert a string to a list of strings split up according to
1776 @value{GDBN}'s argv parsing rules.
1777 It is recommended to use this for consistency.
1778 Arguments are separated by spaces and may be quoted.
1782 scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
1783 $1 = ("1" "2 \"3" "4 \"5" "6 '7")
1787 @deffn {Scheme Procedure} throw-user-error message . args
1788 Throw a @code{gdb:user-error} exception.
1789 The argument @var{message} is the error message as a format string, like the
1790 @var{fmt} argument to the @code{format} Scheme function.
1791 @xref{Formatted Output,,, guile, GNU Guile Reference Manual}.
1792 The argument @var{args} is a list of the optional arguments of @var{message}.
1794 This is used when the command detects a user error of some kind,
1795 say a bad command argument.
1798 (gdb) guile (use-modules (gdb))
1800 (register-command! (make-command "test-user-error"
1801 #:command-class COMMAND_OBSCURE
1802 #:invoke (lambda (self arg from-tty)
1803 (throw-user-error "Bad argument ~a" arg))))
1805 (gdb) test-user-error ugh
1806 ERROR: Bad argument ugh
1810 @cindex completion of Guile commands
1811 @deffn completer self text word
1812 If the @var{completer} option to @code{make-command} is a procedure,
1813 it takes three arguments: @var{self} which is the @code{<gdb:command>}
1814 object, and @var{text} and @var{word} which are both strings.
1815 The argument @var{text} holds the complete command line up to the cursor's
1816 location. The argument @var{word} holds the last word of the command line;
1817 this is computed using a word-breaking heuristic.
1819 All forms of completion are handled by this function, that is,
1820 the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}),
1821 and the @code{complete} command (@pxref{Help, complete}).
1823 This procedure can return several kinds of values:
1827 If the return value is a list, the contents of the list are used as the
1828 completions. It is up to @var{completer} to ensure that the
1829 contents actually do complete the word. An empty list is
1830 allowed, it means that there were no completions available. Only
1831 string elements of the list are used; other elements in the
1835 If the return value is a @code{<gdb:iterator>} object, it is iterated over to
1836 obtain the completions. It is up to @code{completer-procedure} to ensure
1837 that the results actually do complete the word. Only
1838 string elements of the result are used; other elements in the
1839 sequence are ignored.
1842 All other results are treated as though there were no available
1847 When a new command is registered, it will have been declared as a member of
1848 some general class of commands. This is used to classify top-level
1849 commands in the on-line help system; note that prefix commands are not
1850 listed under their own category but rather that of their top-level
1851 command. The available classifications are represented by constants
1852 defined in the @code{gdb} module:
1856 The command does not belong to any particular class. A command in
1857 this category will not be displayed in any of the help categories.
1858 This is the default.
1860 @item COMMAND_RUNNING
1861 The command is related to running the inferior. For example,
1862 @code{start}, @code{step}, and @code{continue} are in this category.
1863 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
1864 commands in this category.
1867 The command is related to data or variables. For example,
1868 @code{call}, @code{find}, and @code{print} are in this category. Type
1869 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
1873 The command has to do with manipulation of the stack. For example,
1874 @code{backtrace}, @code{frame}, and @code{return} are in this
1875 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
1876 list of commands in this category.
1879 This class is used for file-related commands. For example,
1880 @code{file}, @code{list} and @code{section} are in this category.
1881 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
1882 commands in this category.
1884 @item COMMAND_SUPPORT
1885 This should be used for ``support facilities'', generally meaning
1886 things that are useful to the user when interacting with @value{GDBN},
1887 but not related to the state of the inferior. For example,
1888 @code{help}, @code{make}, and @code{shell} are in this category. Type
1889 @kbd{help support} at the @value{GDBN} prompt to see a list of
1890 commands in this category.
1892 @item COMMAND_STATUS
1893 The command is an @samp{info}-related command, that is, related to the
1894 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
1895 and @code{show} are in this category. Type @kbd{help status} at the
1896 @value{GDBN} prompt to see a list of commands in this category.
1898 @item COMMAND_BREAKPOINTS
1899 The command has to do with breakpoints. For example, @code{break},
1900 @code{clear}, and @code{delete} are in this category. Type @kbd{help
1901 breakpoints} at the @value{GDBN} prompt to see a list of commands in
1904 @item COMMAND_TRACEPOINTS
1905 The command has to do with tracepoints. For example, @code{trace},
1906 @code{actions}, and @code{tfind} are in this category. Type
1907 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
1908 commands in this category.
1911 The command is a general purpose command for the user, and typically
1912 does not fit in one of the other categories.
1913 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
1914 a list of commands in this category, as well as the list of gdb macros
1915 (@pxref{Sequences}).
1917 @item COMMAND_OBSCURE
1918 The command is only used in unusual circumstances, or is not of
1919 general interest to users. For example, @code{checkpoint},
1920 @code{fork}, and @code{stop} are in this category. Type @kbd{help
1921 obscure} at the @value{GDBN} prompt to see a list of commands in this
1924 @item COMMAND_MAINTENANCE
1925 The command is only useful to @value{GDBN} maintainers. The
1926 @code{maintenance} and @code{flushregs} commands are in this category.
1927 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
1928 commands in this category.
1931 A new command can use a predefined completion function, either by
1932 specifying it via an argument at initialization, or by returning it
1933 from the @code{completer} procedure. These predefined completion
1934 constants are all defined in the @code{gdb} module:
1938 This constant means that no completion should be done.
1940 @item COMPLETE_FILENAME
1941 This constant means that filename completion should be performed.
1943 @item COMPLETE_LOCATION
1944 This constant means that location completion should be done.
1945 @xref{Specify Location}.
1947 @item COMPLETE_COMMAND
1948 This constant means that completion should examine @value{GDBN}
1951 @item COMPLETE_SYMBOL
1952 This constant means that completion should be done using symbol names
1955 @item COMPLETE_EXPRESSION
1956 This constant means that completion should be done on expressions.
1957 Often this means completing on symbol names, but some language
1958 parsers also have support for completing on field names.
1961 The following code snippet shows how a trivial CLI command can be
1962 implemented in Guile:
1966 (register-command! (make-command "hello-world"
1967 #:command-class COMMAND_USER
1968 #:doc "Greet the whole world."
1969 #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
1975 @node Parameters In Guile
1976 @subsubsection Parameters In Guile
1978 @cindex parameters in guile
1979 @cindex guile parameters
1981 You can implement new @value{GDBN} @dfn{parameters} using Guile
1982 @footnote{Note that @value{GDBN} parameters must not be confused with
1983 Guile’s parameter objects (@pxref{Parameters,,, guile, GNU Guile
1984 Reference Manual}).}.
1986 There are many parameters that already exist and can be set in
1987 @value{GDBN}. Two examples are: @code{set follow-fork} and
1988 @code{set charset}. Setting these parameters influences certain
1989 behavior in @value{GDBN}. Similarly, you can define parameters that
1990 can be used to influence behavior in custom Guile scripts and commands.
1992 A new parameter is defined with the @code{make-parameter} Guile function,
1993 and added to @value{GDBN} with the @code{register-parameter!} Guile function.
1994 This two-step approach is taken to separate out the side-effect of adding
1995 the parameter to @value{GDBN} from @code{make-parameter}.
1997 Parameters are exposed to the user via the @code{set} and
1998 @code{show} commands. @xref{Help}.
2001 @deffn {Scheme Procedure} (make-parameter name @r{[}#:command-class command-class@r{]} @r{[}#:parameter-type parameter-type{]} @r{[}#:enum-list enum-list@r{]} @r{[}#:set-func set-func{]} @r{[}#:show-func show-func{]} @r{[}#:doc doc{]} @r{[}#:set-doc set-doc{]} @r{[}#:show-doc show-doc{]} @r{[}#:initial-value initial-value{]})
2003 The argument @var{name} is the name of the new parameter. If @var{name}
2004 consists of multiple words, then the initial words are looked for as prefix
2005 parameters. An example of this can be illustrated with the
2006 @code{set print} set of parameters. If @var{name} is
2007 @code{print foo}, then @code{print} will be searched as the prefix
2008 parameter. In this case the parameter can subsequently be accessed in
2009 @value{GDBN} as @code{set print foo}.
2010 If @var{name} consists of multiple words, and no prefix parameter group
2011 can be found, an exception is raised.
2013 The result is the @code{<gdb:parameter>} object representing the parameter.
2014 The parameter is not usable until it has been registered with @value{GDBN}
2015 with @code{register-parameter!}.
2017 The rest of the arguments are optional.
2019 The argument @var{command-class} should be one of the @samp{COMMAND_} constants
2020 (@pxref{Commands In Guile}). This argument tells @value{GDBN} how to
2021 categorize the new parameter in the help system.
2022 The default is @code{COMMAND_NONE}.
2024 The argument @var{parameter-type} should be one of the @samp{PARAM_} constants
2025 defined below. This argument tells @value{GDBN} the type of the new
2026 parameter; this information is used for input validation and
2027 completion. The default is @code{PARAM_BOOLEAN}.
2029 If @var{parameter-type} is @code{PARAM_ENUM}, then
2030 @var{enum-list} must be a list of strings. These strings
2031 represent the possible values for the parameter.
2033 If @var{parameter-type} is not @code{PARAM_ENUM}, then the presence
2034 of @var{enum-list} will cause an exception to be thrown.
2036 The argument @var{set-func} is a function of one argument: @var{self} which
2037 is the @code{<gdb:parameter>} object representing the parameter.
2038 @value{GDBN} will call this function when a @var{parameter}'s value has
2039 been changed via the @code{set} API (for example, @kbd{set foo off}).
2040 The value of the parameter has already been set to the new value.
2041 This function must return a string to be displayed to the user.
2042 @value{GDBN} will add a trailing newline if the string is non-empty.
2043 @value{GDBN} generally doesn't print anything when a parameter is set,
2044 thus typically this function should return @samp{""}.
2045 A non-empty string result should typically be used for displaying warnings
2048 The argument @var{show-func} is a function of two arguments: @var{self} which
2049 is the @code{<gdb:parameter>} object representing the parameter, and
2050 @var{svalue} which is the string representation of the current value.
2051 @value{GDBN} will call this function when a @var{parameter}'s
2052 @code{show} API has been invoked (for example, @kbd{show foo}).
2053 This function must return a string, and will be displayed to the user.
2054 @value{GDBN} will add a trailing newline.
2056 The argument @var{doc} is the help text for the new parameter.
2057 If there is no documentation string, a default value is used.
2059 The argument @var{set-doc} is the help text for this parameter's
2062 The argument @var{show-doc} is the help text for this parameter's
2063 @code{show} command.
2065 The argument @var{initial-value} specifies the initial value of the parameter.
2066 If it is a function, it takes one parameter, the @code{<gdb:parameter>}
2067 object and its result is used as the initial value of the parameter.
2068 The initial value must be valid for the parameter type,
2069 otherwise an exception is thrown.
2072 @deffn {Scheme Procedure} register-parameter! parameter
2073 Add @var{parameter}, a @code{<gdb:parameter>} object, to @value{GDBN}'s
2075 It is an error to register a parameter more than once.
2076 The result is unspecified.
2079 @deffn {Scheme Procedure} parameter? object
2080 Return @code{#t} if @var{object} is a @code{<gdb:parameter>} object.
2081 Otherwise return @code{#f}.
2084 @deffn {Scheme Procedure} parameter-value parameter
2085 Return the value of @var{parameter} which may either be
2086 a @code{<gdb:parameter>} object or a string naming the parameter.
2089 @deffn {Scheme Procedure} set-parameter-value! parameter new-value
2090 Assign @var{parameter} the value of @var{new-value}.
2091 The argument @var{parameter} must be an object of type @code{<gdb:parameter>}.
2092 @value{GDBN} does validation when assignments are made.
2095 When a new parameter is defined, its type must be specified. The
2096 available types are represented by constants defined in the @code{gdb}
2101 The value is a plain boolean. The Guile boolean values, @code{#t}
2102 and @code{#f} are the only valid values.
2104 @item PARAM_AUTO_BOOLEAN
2105 The value has three possible states: true, false, and @samp{auto}. In
2106 Guile, true and false are represented using boolean constants, and
2107 @samp{auto} is represented using @code{#:auto}.
2109 @item PARAM_UINTEGER
2110 The value is an unsigned integer. The value of 0 should be
2111 interpreted to mean ``unlimited''.
2113 @item PARAM_ZINTEGER
2114 The value is an integer.
2116 @item PARAM_ZUINTEGER
2117 The value is an unsigned integer.
2119 @item PARAM_ZUINTEGER_UNLIMITED
2120 The value is an integer in the range @samp{[0, INT_MAX]}.
2121 A value of @samp{-1} means ``unlimited'', and other negative
2122 numbers are not allowed.
2125 The value is a string. When the user modifies the string, any escape
2126 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
2127 translated into corresponding characters and encoded into the current
2130 @item PARAM_STRING_NOESCAPE
2131 The value is a string. When the user modifies the string, escapes are
2132 passed through untranslated.
2134 @item PARAM_OPTIONAL_FILENAME
2135 The value is a either a filename (a string), or @code{#f}.
2137 @item PARAM_FILENAME
2138 The value is a filename. This is just like
2139 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
2142 The value is a string, which must be one of a collection of string
2143 constants provided when the parameter is created.
2146 @node Progspaces In Guile
2147 @subsubsection Program Spaces In Guile
2149 @cindex progspaces in guile
2150 @tindex <gdb:progspace>
2151 A program space, or @dfn{progspace}, represents a symbolic view
2152 of an address space.
2153 It consists of all of the objfiles of the program.
2154 @xref{Objfiles In Guile}.
2155 @xref{Inferiors and Programs, program spaces}, for more details
2156 about program spaces.
2158 Each progspace is represented by an instance of the @code{<gdb:progspace>}
2159 smob. @xref{GDB Scheme Data Types}.
2161 The following progspace-related functions are available in the
2162 @code{(gdb)} module:
2164 @deffn {Scheme Procedure} progspace? object
2165 Return @code{#t} if @var{object} is a @code{<gdb:progspace>} object.
2166 Otherwise return @code{#f}.
2169 @deffn {Scheme Procedure} progspace-valid? progspace
2170 Return @code{#t} if @var{progspace} is valid, @code{#f} if not.
2171 A @code{<gdb:progspace>} object can become invalid
2172 if the program it refers to is not loaded in @value{GDBN} any longer.
2175 @deffn {Scheme Procedure} current-progspace
2176 This function returns the program space of the currently selected inferior.
2177 There is always a current progspace, this never returns @code{#f}.
2178 @xref{Inferiors and Programs}.
2181 @deffn {Scheme Procedure} progspaces
2182 Return a list of all the progspaces currently known to @value{GDBN}.
2185 @deffn {Scheme Procedure} progspace-filename progspace
2186 Return the absolute file name of @var{progspace} as a string.
2187 This is the name of the file passed as the argument to the @code{file}
2188 or @code{symbol-file} commands.
2189 If the program space does not have an associated file name,
2190 then @code{#f} is returned. This occurs, for example, when @value{GDBN}
2191 is started without a program to debug.
2193 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2197 @deffn {Scheme Procedure} progspace-objfiles progspace
2198 Return the list of objfiles of @var{progspace}.
2199 The order of objfiles in the result is arbitrary.
2200 Each element is an object of type @code{<gdb:objfile>}.
2201 @xref{Objfiles In Guile}.
2203 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2207 @deffn {Scheme Procedure} progspace-pretty-printers progspace
2208 Return the list of pretty-printers of @var{progspace}.
2209 Each element is an object of type @code{<gdb:pretty-printer>}.
2210 @xref{Guile Pretty Printing API}, for more information.
2213 @deffn {Scheme Procedure} set-progspace-pretty-printers! progspace printer-list
2214 Set the list of registered @code{<gdb:pretty-printer>} objects for
2215 @var{progspace} to @var{printer-list}.
2216 @xref{Guile Pretty Printing API}, for more information.
2219 @node Objfiles In Guile
2220 @subsubsection Objfiles In Guile
2222 @cindex objfiles in guile
2223 @tindex <gdb:objfile>
2224 @value{GDBN} loads symbols for an inferior from various
2225 symbol-containing files (@pxref{Files}). These include the primary
2226 executable file, any shared libraries used by the inferior, and any
2227 separate debug info files (@pxref{Separate Debug Files}).
2228 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
2230 Each objfile is represented as an object of type @code{<gdb:objfile>}.
2232 The following objfile-related procedures are provided by the
2233 @code{(gdb)} module:
2235 @deffn {Scheme Procedure} objfile? object
2236 Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
2237 Otherwise return @code{#f}.
2240 @deffn {Scheme Procedure} objfile-valid? objfile
2241 Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
2242 A @code{<gdb:objfile>} object can become invalid
2243 if the object file it refers to is not loaded in @value{GDBN} any
2244 longer. All other @code{<gdb:objfile>} procedures will throw an exception
2245 if it is invalid at the time the procedure is called.
2248 @deffn {Scheme Procedure} objfile-filename objfile
2249 Return the file name of @var{objfile} as a string,
2250 with symbolic links resolved.
2253 @deffn {Scheme Procedure} objfile-progspace objfile
2254 Return the @code{<gdb:progspace>} that this object file lives in.
2255 @xref{Progspaces In Guile}, for more on progspaces.
2258 @deffn {Scheme Procedure} objfile-pretty-printers objfile
2259 Return the list of registered @code{<gdb:pretty-printer>} objects for
2260 @var{objfile}. @xref{Guile Pretty Printing API}, for more information.
2263 @deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
2264 Set the list of registered @code{<gdb:pretty-printer>} objects for
2265 @var{objfile} to @var{printer-list}. The
2266 @var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
2267 @xref{Guile Pretty Printing API}, for more information.
2270 @deffn {Scheme Procedure} current-objfile
2271 When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
2272 sets the ``current objfile'' to the corresponding objfile. This
2273 function returns the current objfile. If there is no current objfile,
2274 this function returns @code{#f}.
2277 @deffn {Scheme Procedure} objfiles
2278 Return a list of all the objfiles in the current program space.
2281 @node Frames In Guile
2282 @subsubsection Accessing inferior stack frames from Guile.
2284 @cindex frames in guile
2285 When the debugged program stops, @value{GDBN} is able to analyze its call
2286 stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
2287 represents a frame in the stack. A @code{<gdb:frame>} object is only valid
2288 while its corresponding frame exists in the inferior's stack. If you try
2289 to use an invalid frame object, @value{GDBN} will throw a
2290 @code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
2292 Two @code{<gdb:frame>} objects can be compared for equality with the
2293 @code{equal?} function, like:
2296 (@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
2300 The following frame-related procedures are provided by the
2301 @code{(gdb)} module:
2303 @deffn {Scheme Procedure} frame? object
2304 Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
2305 Otherwise return @code{#f}.
2308 @deffn {Scheme Procedure} frame-valid? frame
2309 Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
2310 A frame object can become invalid if the frame it refers to doesn't
2311 exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
2312 an exception if the frame is invalid at the time the procedure is called.
2315 @deffn {Scheme Procedure} frame-name frame
2316 Return the function name of @var{frame}, or @code{#f} if it can't be
2320 @deffn {Scheme Procedure} frame-arch frame
2321 Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
2322 architecture. @xref{Architectures In Guile}.
2325 @deffn {Scheme Procedure} frame-type frame
2326 Return the type of @var{frame}. The value can be one of:
2330 An ordinary stack frame.
2333 A fake stack frame that was created by @value{GDBN} when performing an
2334 inferior function call.
2337 A frame representing an inlined function. The function was inlined
2338 into a @code{NORMAL_FRAME} that is older than this one.
2340 @item TAILCALL_FRAME
2341 A frame representing a tail call. @xref{Tail Call Frames}.
2343 @item SIGTRAMP_FRAME
2344 A signal trampoline frame. This is the frame created by the OS when
2345 it calls into a signal handler.
2348 A fake stack frame representing a cross-architecture call.
2350 @item SENTINEL_FRAME
2351 This is like @code{NORMAL_FRAME}, but it is only used for the
2356 @deffn {Scheme Procedure} frame-unwind-stop-reason frame
2357 Return an integer representing the reason why it's not possible to find
2358 more frames toward the outermost frame. Use
2359 @code{unwind-stop-reason-string} to convert the value returned by this
2360 function to a string. The value can be one of:
2363 @item FRAME_UNWIND_NO_REASON
2364 No particular reason (older frames should be available).
2366 @item FRAME_UNWIND_NULL_ID
2367 The previous frame's analyzer returns an invalid result.
2369 @item FRAME_UNWIND_OUTERMOST
2370 This frame is the outermost.
2372 @item FRAME_UNWIND_UNAVAILABLE
2373 Cannot unwind further, because that would require knowing the
2374 values of registers or memory that have not been collected.
2376 @item FRAME_UNWIND_INNER_ID
2377 This frame ID looks like it ought to belong to a NEXT frame,
2378 but we got it for a PREV frame. Normally, this is a sign of
2379 unwinder failure. It could also indicate stack corruption.
2381 @item FRAME_UNWIND_SAME_ID
2382 This frame has the same ID as the previous one. That means
2383 that unwinding further would almost certainly give us another
2384 frame with exactly the same ID, so break the chain. Normally,
2385 this is a sign of unwinder failure. It could also indicate
2388 @item FRAME_UNWIND_NO_SAVED_PC
2389 The frame unwinder did not find any saved PC, but we needed
2390 one to unwind further.
2392 @item FRAME_UNWIND_MEMORY_ERROR
2393 The frame unwinder caused an error while trying to access memory.
2395 @item FRAME_UNWIND_FIRST_ERROR
2396 Any stop reason greater or equal to this value indicates some kind
2397 of error. This special value facilitates writing code that tests
2398 for errors in unwinding in a way that will work correctly even if
2399 the list of the other values is modified in future @value{GDBN}
2400 versions. Using it, you could write:
2403 (define reason (frame-unwind-stop-readon (selected-frame)))
2404 (define reason-str (unwind-stop-reason-string reason))
2405 (if (>= reason FRAME_UNWIND_FIRST_ERROR)
2406 (format #t "An error occured: ~s\n" reason-str))
2411 @deffn {Scheme Procedure} frame-pc frame
2412 Return the frame's resume address.
2415 @deffn {Scheme Procedure} frame-block frame
2416 Return the frame's code block as a @code{<gdb:block>} object.
2417 @xref{Blocks In Guile}.
2420 @deffn {Scheme Procedure} frame-function frame
2421 Return the symbol for the function corresponding to this frame
2422 as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
2423 @xref{Symbols In Guile}.
2426 @deffn {Scheme Procedure} frame-older frame
2427 Return the frame that called @var{frame}.
2430 @deffn {Scheme Procedure} frame-newer frame
2431 Return the frame called by @var{frame}.
2434 @deffn {Scheme Procedure} frame-sal frame
2435 Return the frame's @code{<gdb:sal>} (symtab and line) object.
2436 @xref{Symbol Tables In Guile}.
2439 @deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]}
2440 Return the value of @var{variable} in @var{frame}. If the optional
2441 argument @var{block} is provided, search for the variable from that
2442 block; otherwise start at the frame's current block (which is
2443 determined by the frame's current program counter). The
2444 @var{variable} must be given as a string or a @code{<gdb:symbol>}
2445 object, and @var{block} must be a @code{<gdb:block>} object.
2448 @deffn {Scheme Procedure} frame-select frame
2449 Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
2453 @deffn {Scheme Procedure} selected-frame
2454 Return the selected frame object. @xref{Selection,,Selecting a Frame}.
2457 @deffn {Scheme Procedure} newest-frame
2458 Return the newest frame object for the selected thread.
2461 @deffn {Scheme Procedure} unwind-stop-reason-string reason
2462 Return a string explaining the reason why @value{GDBN} stopped unwinding
2463 frames, as expressed by the given @var{reason} code (an integer, see the
2464 @code{frame-unwind-stop-reason} procedure above in this section).
2467 @node Blocks In Guile
2468 @subsubsection Accessing blocks from Guile.
2470 @cindex blocks in guile
2473 In @value{GDBN}, symbols are stored in blocks. A block corresponds
2474 roughly to a scope in the source code. Blocks are organized
2475 hierarchically, and are represented individually in Guile as an object
2476 of type @code{<gdb:block>}. Blocks rely on debugging information being
2479 A frame has a block. Please see @ref{Frames In Guile}, for a more
2480 in-depth discussion of frames.
2482 The outermost block is known as the @dfn{global block}. The global
2483 block typically holds public global variables and functions.
2485 The block nested just inside the global block is the @dfn{static
2486 block}. The static block typically holds file-scoped variables and
2489 @value{GDBN} provides a method to get a block's superblock, but there
2490 is currently no way to examine the sub-blocks of a block, or to
2491 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
2494 Here is a short example that should help explain blocks:
2497 /* This is in the global block. */
2500 /* This is in the static block. */
2501 static int file_scope;
2503 /* 'function' is in the global block, and 'argument' is
2504 in a block nested inside of 'function'. */
2505 int function (int argument)
2507 /* 'local' is in a block inside 'function'. It may or may
2508 not be in the same block as 'argument'. */
2512 /* 'inner' is in a block whose superblock is the one holding
2516 /* If this call is expanded by the compiler, you may see
2517 a nested block here whose function is 'inline_function'
2518 and whose superblock is the one holding 'inner'. */
2524 The following block-related procedures are provided by the
2525 @code{(gdb)} module:
2527 @deffn {Scheme Procedure} block? object
2528 Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
2529 Otherwise return @code{#f}.
2532 @deffn {Scheme Procedure} block-valid? block
2533 Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
2534 @code{#f} if not. A block object can become invalid if the block it
2535 refers to doesn't exist anymore in the inferior. All other
2536 @code{<gdb:block>} methods will throw an exception if it is invalid at
2537 the time the procedure is called. The block's validity is also checked
2538 during iteration over symbols of the block.
2541 @deffn {Scheme Procedure} block-start block
2542 Return the start address of @code{<gdb:block>} @var{block}.
2545 @deffn {Scheme Procedure} block-end block
2546 Return the end address of @code{<gdb:block>} @var{block}.
2549 @deffn {Scheme Procedure} block-function block
2550 Return the name of @code{<gdb:block>} @var{block} represented as a
2551 @code{<gdb:symbol>} object.
2552 If the block is not named, then @code{#f} is returned.
2554 For ordinary function blocks, the superblock is the static block.
2555 However, you should note that it is possible for a function block to
2556 have a superblock that is not the static block -- for instance this
2557 happens for an inlined function.
2560 @deffn {Scheme Procedure} block-superblock block
2561 Return the block containing @code{<gdb:block>} @var{block}.
2562 If the parent block does not exist, then @code{#f} is returned.
2565 @deffn {Scheme Procedure} block-global-block block
2566 Return the global block associated with @code{<gdb:block>} @var{block}.
2569 @deffn {Scheme Procedure} block-static-block block
2570 Return the static block associated with @code{<gdb:block>} @var{block}.
2573 @deffn {Scheme Procedure} block-global? block
2574 Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
2575 Otherwise return @code{#f}.
2578 @deffn {Scheme Procedure} block-static? block
2579 Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
2580 Otherwise return @code{#f}.
2583 @deffn {Scheme Procedure} block-symbols
2584 Return a list of all symbols (as <gdb:symbol> objects) in
2585 @code{<gdb:block>} @var{block}.
2588 @deffn {Scheme Procedure} make-block-symbols-iterator block
2589 Return an object of type @code{<gdb:iterator>} that will iterate
2590 over all symbols of the block.
2591 Guile programs should not assume that a specific block object will
2592 always contain a given symbol, since changes in @value{GDBN} features and
2593 infrastructure may cause symbols move across blocks in a symbol table.
2594 @xref{Iterators In Guile}.
2597 @deffn {Scheme Procedure} block-symbols-progress?
2598 Return #t if the object is a <gdb:block-symbols-progress> object.
2599 This object would be obtained from the @code{progress} element of the
2600 @code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
2603 @deffn {Scheme Procedure} lookup-block pc
2604 Return the innermost @code{<gdb:block>} containing the given @var{pc}
2605 value. If the block cannot be found for the @var{pc} value specified,
2606 the function will return @code{#f}.
2609 @node Symbols In Guile
2610 @subsubsection Guile representation of Symbols.
2612 @cindex symbols in guile
2613 @tindex <gdb:symbol>
2615 @value{GDBN} represents every variable, function and type as an
2616 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
2617 Guile represents these symbols in @value{GDBN} with the
2618 @code{<gdb:symbol>} object.
2620 The following symbol-related procedures are provided by the
2621 @code{(gdb)} module:
2623 @deffn {Scheme Procedure} symbol? object
2624 Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
2625 Otherwise return @code{#f}.
2628 @deffn {Scheme Procedure} symbol-valid? symbol
2629 Return @code{#t} if the @code{<gdb:symbol>} object is valid,
2630 @code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
2631 the symbol it refers to does not exist in @value{GDBN} any longer.
2632 All other @code{<gdb:symbol>} procedures will throw an exception if it is
2633 invalid at the time the procedure is called.
2636 @deffn {Scheme Procedure} symbol-type symbol
2637 Return the type of @var{symbol} or @code{#f} if no type is recorded.
2638 The result is an object of type @code{<gdb:type>}.
2639 @xref{Types In Guile}.
2642 @deffn {Scheme Procedure} symbol-symtab symbol
2643 Return the symbol table in which @var{symbol} appears.
2644 The result is an object of type @code{<gdb:symtab>}.
2645 @xref{Symbol Tables In Guile}.
2648 @deffn {Scheme Procedure} symbol-line symbol
2649 Return the line number in the source code at which @var{symbol} was defined.
2653 @deffn {Scheme Procedure} symbol-name symbol
2654 Return the name of @var{symbol} as a string.
2657 @deffn {Scheme Procedure} symbol-linkage-name symbol
2658 Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
2661 @deffn {Scheme Procedure} symbol-print-name symbol
2662 Return the name of @var{symbol} in a form suitable for output. This is either
2663 @code{name} or @code{linkage_name}, depending on whether the user
2664 asked @value{GDBN} to display demangled or mangled names.
2667 @deffn {Scheme Procedure} symbol-addr-class symbol
2668 Return the address class of the symbol. This classifies how to find the value
2669 of a symbol. Each address class is a constant defined in the
2670 @code{(gdb)} module and described later in this chapter.
2673 @deffn {Scheme Procedure} symbol-needs-frame? symbol
2674 Return @code{#t} if evaluating @var{symbol}'s value requires a frame
2675 (@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
2676 local variables will require a frame, but other symbols will not.
2679 @deffn {Scheme Procedure} symbol-argument? symbol
2680 Return @code{#t} if @var{symbol} is an argument of a function.
2681 Otherwise return @code{#f}.
2684 @deffn {Scheme Procedure} symbol-constant? symbol
2685 Return @code{#t} if @var{symbol} is a constant.
2686 Otherwise return @code{#f}.
2689 @deffn {Scheme Procedure} symbol-function? symbol
2690 Return @code{#t} if @var{symbol} is a function or a method.
2691 Otherwise return @code{#f}.
2694 @deffn {Scheme Procedure} symbol-variable? symbol
2695 Return @code{#t} if @var{symbol} is a variable.
2696 Otherwise return @code{#f}.
2699 @deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]}
2700 Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
2701 functions, this computes the address of the function, cast to the
2702 appropriate type. If the symbol requires a frame in order to compute
2703 its value, then @var{frame} must be given. If @var{frame} is not
2704 given, or if @var{frame} is invalid, then an exception is thrown.
2707 @c TODO: line length
2708 @deffn {Scheme Procedure} lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]}
2709 This function searches for a symbol by name. The search scope can be
2710 restricted to the parameters defined in the optional domain and block
2713 @var{name} is the name of the symbol. It must be a string. The
2714 optional @var{block} argument restricts the search to symbols visible
2715 in that @var{block}. The @var{block} argument must be a
2716 @code{<gdb:block>} object. If omitted, the block for the current frame
2717 is used. The optional @var{domain} argument restricts
2718 the search to the domain type. The @var{domain} argument must be a
2719 domain constant defined in the @code{(gdb)} module and described later
2722 The result is a list of two elements.
2723 The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2725 If the symbol is found, the second element is @code{#t} if the symbol
2726 is a field of a method's object (e.g., @code{this} in C@t{++}),
2727 otherwise it is @code{#f}.
2728 If the symbol is not found, the second element is @code{#f}.
2731 @deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]}
2732 This function searches for a global symbol by name.
2733 The search scope can be restricted by the domain argument.
2735 @var{name} is the name of the symbol. It must be a string.
2736 The optional @var{domain} argument restricts the search to the domain type.
2737 The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
2738 module and described later in this chapter.
2740 The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2744 The available domain categories in @code{<gdb:symbol>} are represented
2745 as constants in the @code{(gdb)} module:
2748 @item SYMBOL_UNDEF_DOMAIN
2749 This is used when a domain has not been discovered or none of the
2750 following domains apply. This usually indicates an error either
2751 in the symbol information or in @value{GDBN}'s handling of symbols.
2753 @item SYMBOL_VAR_DOMAIN
2754 This domain contains variables, function names, typedef names and enum
2757 @item SYMBOL_STRUCT_DOMAIN
2758 This domain holds struct, union and enum type names.
2760 @item SYMBOL_LABEL_DOMAIN
2761 This domain contains names of labels (for gotos).
2763 @item SYMBOL_VARIABLES_DOMAIN
2764 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
2765 contains everything minus functions and types.
2767 @item SYMBOL_FUNCTION_DOMAIN
2768 This domain contains all functions.
2770 @item SYMBOL_TYPES_DOMAIN
2771 This domain contains all types.
2774 The available address class categories in @code{<gdb:symbol>} are represented
2775 as constants in the @code{gdb} module:
2778 @item SYMBOL_LOC_UNDEF
2779 If this is returned by address class, it indicates an error either in
2780 the symbol information or in @value{GDBN}'s handling of symbols.
2782 @item SYMBOL_LOC_CONST
2783 Value is constant int.
2785 @item SYMBOL_LOC_STATIC
2786 Value is at a fixed address.
2788 @item SYMBOL_LOC_REGISTER
2789 Value is in a register.
2791 @item SYMBOL_LOC_ARG
2792 Value is an argument. This value is at the offset stored within the
2793 symbol inside the frame's argument list.
2795 @item SYMBOL_LOC_REF_ARG
2796 Value address is stored in the frame's argument list. Just like
2797 @code{LOC_ARG} except that the value's address is stored at the
2798 offset, not the value itself.
2800 @item SYMBOL_LOC_REGPARM_ADDR
2801 Value is a specified register. Just like @code{LOC_REGISTER} except
2802 the register holds the address of the argument instead of the argument
2805 @item SYMBOL_LOC_LOCAL
2806 Value is a local variable.
2808 @item SYMBOL_LOC_TYPEDEF
2809 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
2812 @item SYMBOL_LOC_BLOCK
2815 @item SYMBOL_LOC_CONST_BYTES
2816 Value is a byte-sequence.
2818 @item SYMBOL_LOC_UNRESOLVED
2819 Value is at a fixed address, but the address of the variable has to be
2820 determined from the minimal symbol table whenever the variable is
2823 @item SYMBOL_LOC_OPTIMIZED_OUT
2824 The value does not actually exist in the program.
2826 @item SYMBOL_LOC_COMPUTED
2827 The value's address is a computed location.
2830 @node Symbol Tables In Guile
2831 @subsubsection Symbol table representation in Guile.
2833 @cindex symbol tables in guile
2834 @tindex <gdb:symtab>
2837 Access to symbol table data maintained by @value{GDBN} on the inferior
2838 is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
2839 @code{<gdb:symtab>}. Symbol table and line data for a frame is returned
2840 from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
2841 @xref{Frames In Guile}.
2843 For more information on @value{GDBN}'s symbol table management, see
2844 @ref{Symbols, ,Examining the Symbol Table}.
2846 The following symtab-related procedures are provided by the
2847 @code{(gdb)} module:
2849 @deffn {Scheme Procedure} symtab? object
2850 Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
2851 Otherwise return @code{#f}.
2854 @deffn {Scheme Procedure} symtab-valid? symtab
2855 Return @code{#t} if the @code{<gdb:symtab>} object is valid,
2856 @code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
2857 the symbol table it refers to no longer exists in @value{GDBN}.
2858 All other @code{<gdb:symtab>} procedures will throw an exception
2859 if it is invalid at the time the procedure is called.
2862 @deffn {Scheme Procedure} symtab-filename symtab
2863 Return the symbol table's source filename.
2866 @deffn {Scheme Procedure} symtab-fullname symtab
2867 Return the symbol table's source absolute file name.
2870 @deffn {Scheme Procedure} symtab-objfile symtab
2871 Return the symbol table's backing object file. @xref{Objfiles In Guile}.
2874 @deffn {Scheme Procedure} symtab-global-block symtab
2875 Return the global block of the underlying symbol table.
2876 @xref{Blocks In Guile}.
2879 @deffn {Scheme Procedure} symtab-static-block symtab
2880 Return the static block of the underlying symbol table.
2881 @xref{Blocks In Guile}.
2884 The following symtab-and-line-related procedures are provided by the
2885 @code{(gdb)} module:
2887 @deffn {Scheme Procedure} sal? object
2888 Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
2889 Otherwise return @code{#f}.
2892 @deffn {Scheme Procedure} sal-valid? sal
2893 Return @code{#t} if @var{sal} is valid, @code{#f} if not.
2894 A @code{<gdb:sal>} object becomes invalid when the Symbol table object
2895 it refers to no longer exists in @value{GDBN}. All other
2896 @code{<gdb:sal>} procedures will throw an exception if it is
2897 invalid at the time the procedure is called.
2900 @deffn {Scheme Procedure} sal-symtab sal
2901 Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
2904 @deffn {Scheme Procedure} sal-line sal
2905 Return the line number for @var{sal}.
2908 @deffn {Scheme Procedure} sal-pc sal
2909 Return the start of the address range occupied by code for @var{sal}.
2912 @deffn {Scheme Procedure} sal-last sal
2913 Return the end of the address range occupied by code for @var{sal}.
2916 @deffn {Scheme Procedure} find-pc-line pc
2917 Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
2918 If an invalid value of @var{pc} is passed as an argument, then the
2919 @code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
2920 object will be @code{#f} and 0 respectively.
2923 @node Breakpoints In Guile
2924 @subsubsection Manipulating breakpoints using Guile
2926 @cindex breakpoints in guile
2927 @tindex <gdb:breakpoint>
2929 Breakpoints in Guile are represented by objects of type
2930 @code{<gdb:breakpoint>}. New breakpoints can be created with the
2931 @code{make-breakpoint} Guile function, and then added to @value{GDBN} with the
2932 @code{register-breakpoint!} Guile function.
2933 This two-step approach is taken to separate out the side-effect of adding
2934 the breakpoint to @value{GDBN} from @code{make-breakpoint}.
2936 Support is also provided to view and manipulate breakpoints created
2939 The following breakpoint-related procedures are provided by the
2940 @code{(gdb)} module:
2942 @c TODO: line length
2943 @deffn {Scheme Procedure} make-breakpoint location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
2944 Create a new breakpoint at @var{location}, a string naming the
2945 location of the breakpoint, or an expression that defines a watchpoint.
2946 The contents can be any location recognized by the @code{break} command,
2947 or in the case of a watchpoint, by the @code{watch} command.
2949 The breakpoint is initially marked as @samp{invalid}.
2950 The breakpoint is not usable until it has been registered with @value{GDBN}
2951 with @code{register-breakpoint!}, at which point it becomes @samp{valid}.
2952 The result is the @code{<gdb:breakpoint>} object representing the breakpoint.
2954 The optional @var{type} denotes the breakpoint to create.
2955 This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
2956 and defaults to @code{BP_BREAKPOINT}.
2958 The optional @var{wp-class} argument defines the class of watchpoint to
2959 create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
2960 not provided, it is assumed to be a @code{WP_WRITE} class.
2962 The optional @var{internal} argument allows the breakpoint to become
2963 invisible to the user. The breakpoint will neither be reported when
2964 registered, nor will it be listed in the output from @code{info breakpoints}
2965 (but will be listed with the @code{maint info breakpoints} command).
2966 If an internal flag is not provided, the breakpoint is visible
2969 When a watchpoint is created, @value{GDBN} will try to create a
2970 hardware assisted watchpoint. If successful, the type of the watchpoint
2971 is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
2972 for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
2973 and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
2974 If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
2976 The available types are represented by constants defined in the @code{gdb}
2981 Normal code breakpoint.
2984 Watchpoint breakpoint.
2986 @item BP_HARDWARE_WATCHPOINT
2987 Hardware assisted watchpoint.
2988 This value cannot be specified when creating the breakpoint.
2990 @item BP_READ_WATCHPOINT
2991 Hardware assisted read watchpoint.
2992 This value cannot be specified when creating the breakpoint.
2994 @item BP_ACCESS_WATCHPOINT
2995 Hardware assisted access watchpoint.
2996 This value cannot be specified when creating the breakpoint.
2999 The available watchpoint types represented by constants are defined in the
3000 @code{(gdb)} module:
3004 Read only watchpoint.
3007 Write only watchpoint.
3010 Read/Write watchpoint.
3015 @deffn {Scheme Procedure} register-breakpoint! breakpoint
3016 Add @var{breakpoint}, a @code{<gdb:breakpoint>} object, to @value{GDBN}'s
3017 list of breakpoints. The breakpoint must have been created with
3018 @code{make-breakpoint}. One cannot register breakpoints that have been
3019 created outside of Guile. Once a breakpoint is registered it becomes
3021 It is an error to register an already registered breakpoint.
3022 The result is unspecified.
3025 @deffn {Scheme Procedure} delete-breakpoint! breakpoint
3026 Remove @var{breakpoint} from @value{GDBN}'s list of breakpoints.
3027 This also invalidates the Guile @var{breakpoint} object.
3028 Any further attempt to access the object will throw an exception.
3030 If @var{breakpoint} was created from Guile with @code{make-breakpoint}
3031 it may be re-registered with @value{GDBN}, in which case the breakpoint
3032 becomes valid again.
3035 @deffn {Scheme Procedure} breakpoints
3036 Return a list of all breakpoints.
3037 Each element of the list is a @code{<gdb:breakpoint>} object.
3040 @deffn {Scheme Procedure} breakpoint? object
3041 Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
3042 and @code{#f} otherwise.
3045 @deffn {Scheme Procedure} breakpoint-valid? breakpoint
3046 Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
3047 Breakpoints created with @code{make-breakpoint} are marked as invalid
3048 until they are registered with @value{GDBN} with @code{register-breakpoint!}.
3049 A @code{<gdb:breakpoint>} object can become invalid
3050 if the user deletes the breakpoint. In this case, the object still
3051 exists, but the underlying breakpoint does not. In the cases of
3052 watchpoint scope, the watchpoint remains valid even if execution of the
3053 inferior leaves the scope of that watchpoint.
3056 @deffn {Scheme Procedure} breakpoint-number breakpoint
3057 Return the breakpoint's number --- the identifier used by
3058 the user to manipulate the breakpoint.
3061 @deffn {Scheme Procedure} breakpoint-type breakpoint
3062 Return the breakpoint's type --- the identifier used to
3063 determine the actual breakpoint type or use-case.
3066 @deffn {Scheme Procedure} breakpoint-visible? breakpoint
3067 Return @code{#t} if the breakpoint is visible to the user
3068 when hit, or when the @samp{info breakpoints} command is run.
3069 Otherwise return @code{#f}.
3072 @deffn {Scheme Procedure} breakpoint-location breakpoint
3073 Return the location of the breakpoint, as specified by
3074 the user. It is a string. If the breakpoint does not have a location
3075 (that is, it is a watchpoint) return @code{#f}.
3078 @deffn {Scheme Procedure} breakpoint-expression breakpoint
3079 Return the breakpoint expression, as specified by the user. It is a string.
3080 If the breakpoint does not have an expression (the breakpoint is not a
3081 watchpoint) return @code{#f}.
3084 @deffn {Scheme Procedure} breakpoint-enabled? breakpoint
3085 Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
3088 @deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag
3089 Set the enabled state of @var{breakpoint} to @var{flag}.
3090 If flag is @code{#f} it is disabled, otherwise it is enabled.
3093 @deffn {Scheme Procedure} breakpoint-silent? breakpoint
3094 Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
3096 Note that a breakpoint can also be silent if it has commands and the
3097 first command is @code{silent}. This is not reported by the
3098 @code{silent} attribute.
3101 @deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag
3102 Set the silent state of @var{breakpoint} to @var{flag}.
3103 If flag is @code{#f} the breakpoint is made silent,
3104 otherwise it is made non-silent (or noisy).
3107 @deffn {Scheme Procedure} breakpoint-ignore-count breakpoint
3108 Return the ignore count for @var{breakpoint}.
3111 @deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count
3112 Set the ignore count for @var{breakpoint} to @var{count}.
3115 @deffn {Scheme Procedure} breakpoint-hit-count breakpoint
3116 Return hit count of @var{breakpoint}.
3119 @deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count
3120 Set the hit count of @var{breakpoint} to @var{count}.
3121 At present, @var{count} must be zero.
3124 @deffn {Scheme Procedure} breakpoint-thread breakpoint
3125 Return the thread-id for thread-specific breakpoint @var{breakpoint}.
3126 Return #f if @var{breakpoint} is not thread-specific.
3129 @deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f
3130 Set the thread-id for @var{breakpoint} to @var{thread-id}.
3131 If set to @code{#f}, the breakpoint is no longer thread-specific.
3134 @deffn {Scheme Procedure} breakpoint-task breakpoint
3135 If the breakpoint is Ada task-specific, return the Ada task id.
3136 If the breakpoint is not task-specific (or the underlying
3137 language is not Ada), return @code{#f}.
3140 @deffn {Scheme Procedure} set-breakpoint-task! breakpoint task
3141 Set the Ada task of @var{breakpoint} to @var{task}.
3142 If set to @code{#f}, the breakpoint is no longer task-specific.
3145 @deffn {Scheme Procedure} breakpoint-condition breakpoint
3146 Return the condition of @var{breakpoint}, as specified by the user.
3147 It is a string. If there is no condition, return @code{#f}.
3150 @deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition
3151 Set the condition of @var{breakpoint} to @var{condition},
3152 which must be a string. If set to @code{#f} then the breakpoint
3153 becomes unconditional.
3156 @deffn {Scheme Procedure} breakpoint-stop breakpoint
3157 Return the stop predicate of @var{breakpoint}.
3158 See @code{set-breakpoint-stop!} below in this section.
3161 @deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
3162 Set the stop predicate of @var{breakpoint}. The predicate
3163 @var{procedure} takes one argument: the <gdb:breakpoint> object.
3164 If this predicate is set to a procedure then it is invoked whenever
3165 the inferior reaches this breakpoint. If it returns @code{#t},
3166 or any non-@code{#f} value, then the inferior is stopped,
3167 otherwise the inferior will continue.
3169 If there are multiple breakpoints at the same location with a
3170 @code{stop} predicate, each one will be called regardless of the
3171 return status of the previous. This ensures that all @code{stop}
3172 predicates have a chance to execute at that location. In this scenario
3173 if one of the methods returns @code{#t} but the others return
3174 @code{#f}, the inferior will still be stopped.
3176 You should not alter the execution state of the inferior (i.e.@:, step,
3177 next, etc.), alter the current frame context (i.e.@:, change the current
3178 active frame), or alter, add or delete any breakpoint. As a general
3179 rule, you should not alter any data within @value{GDBN} or the inferior
3182 Example @code{stop} implementation:
3185 (define (my-stop? bkpt)
3186 (let ((int-val (parse-and-eval "foo")))
3187 (value=? int-val 3)))
3188 (define bkpt (make-breakpoint "main.c:42"))
3189 (register-breakpoint! bkpt)
3190 (set-breakpoint-stop! bkpt my-stop?)
3194 @deffn {Scheme Procedure} breakpoint-commands breakpoint
3195 Return the commands attached to @var{breakpoint} as a string,
3196 or @code{#f} if there are none.
3199 @node Lazy Strings In Guile
3200 @subsubsection Guile representation of lazy strings.
3202 @cindex lazy strings in guile
3203 @tindex <gdb:lazy-string>
3205 A @dfn{lazy string} is a string whose contents is not retrieved or
3206 encoded until it is needed.
3208 A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
3209 @code{address} that points to a region of memory, an @code{encoding}
3210 that will be used to encode that region of memory, and a @code{length}
3211 to delimit the region of memory that represents the string. The
3212 difference between a @code{<gdb:lazy-string>} and a string wrapped within
3213 a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
3214 differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
3215 retrieved and encoded during printing, while a @code{<gdb:value>}
3216 wrapping a string is immediately retrieved and encoded on creation.
3218 The following lazy-string-related procedures are provided by the
3219 @code{(gdb)} module:
3221 @deffn {Scheme Procedure} lazy-string? object
3222 Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
3223 Otherwise return @code{#f}.
3226 @deffn {Scheme Procedure} lazy-string-address lazy-sring
3227 Return the address of @var{lazy-string}.
3230 @deffn {Scheme Procedure} lazy-string-length lazy-string
3231 Return the length of @var{lazy-string} in characters. If the
3232 length is -1, then the string will be fetched and encoded up to the
3233 first null of appropriate width.
3236 @deffn {Scheme Procedure} lazy-string-encoding lazy-string
3237 Return the encoding that will be applied to @var{lazy-string}
3238 when the string is printed by @value{GDBN}. If the encoding is not
3239 set, or contains an empty string, then @value{GDBN} will select the
3240 most appropriate encoding when the string is printed.
3243 @deffn {Scheme Procedure} lazy-string-type lazy-string
3244 Return the type that is represented by @var{lazy-string}'s type.
3245 For a lazy string this will always be a pointer type. To
3246 resolve this to the lazy string's character type, use @code{type-target-type}.
3247 @xref{Types In Guile}.
3250 @deffn {Scheme Procedure} lazy-string->value lazy-string
3251 Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
3252 will point to the string in memory, but will lose all the delayed
3253 retrieval, encoding and handling that @value{GDBN} applies to a
3254 @code{<gdb:lazy-string>}.
3257 @node Architectures In Guile
3258 @subsubsection Guile representation of architectures
3260 @cindex guile architectures
3263 @value{GDBN} uses architecture specific parameters and artifacts in a
3264 number of its various computations. An architecture is represented
3265 by an instance of the @code{<gdb:arch>} class.
3267 The following architecture-related procedures are provided by the
3268 @code{(gdb)} module:
3270 @deffn {Scheme Procedure} arch? object
3271 Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
3272 Otherwise return @code{#f}.
3275 @deffn {Scheme Procedure} current-arch
3276 Return the current architecture as a @code{<gdb:arch>} object.
3279 @deffn {Scheme Procedure} arch-name arch
3280 Return the name (string value) of @code{<gdb:arch>} @var{arch}.
3283 @deffn {Scheme Procedure} arch-charset arch
3284 Return name of target character set of @code{<gdb:arch>} @var{arch}.
3287 @deffn {Scheme Procedure} arch-wide-charset
3288 Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
3291 Each architecture provides a set of predefined types, obtained by
3292 the following functions.
3294 @deffn {Scheme Procedure} arch-void-type arch
3295 Return the @code{<gdb:type>} object for a @code{void} type
3296 of architecture @var{arch}.
3299 @deffn {Scheme Procedure} arch-char-type arch
3300 Return the @code{<gdb:type>} object for a @code{char} type
3301 of architecture @var{arch}.
3304 @deffn {Scheme Procedure} arch-short-type arch
3305 Return the @code{<gdb:type>} object for a @code{short} type
3306 of architecture @var{arch}.
3309 @deffn {Scheme Procedure} arch-int-type arch
3310 Return the @code{<gdb:type>} object for an @code{int} type
3311 of architecture @var{arch}.
3314 @deffn {Scheme Procedure} arch-long-type arch
3315 Return the @code{<gdb:type>} object for a @code{long} type
3316 of architecture @var{arch}.
3319 @deffn {Scheme Procedure} arch-schar-type arch
3320 Return the @code{<gdb:type>} object for a @code{signed char} type
3321 of architecture @var{arch}.
3324 @deffn {Scheme Procedure} arch-uchar-type arch
3325 Return the @code{<gdb:type>} object for an @code{unsigned char} type
3326 of architecture @var{arch}.
3329 @deffn {Scheme Procedure} arch-ushort-type arch
3330 Return the @code{<gdb:type>} object for an @code{unsigned short} type
3331 of architecture @var{arch}.
3334 @deffn {Scheme Procedure} arch-uint-type arch
3335 Return the @code{<gdb:type>} object for an @code{unsigned int} type
3336 of architecture @var{arch}.
3339 @deffn {Scheme Procedure} arch-ulong-type arch
3340 Return the @code{<gdb:type>} object for an @code{unsigned long} type
3341 of architecture @var{arch}.
3344 @deffn {Scheme Procedure} arch-float-type arch
3345 Return the @code{<gdb:type>} object for a @code{float} type
3346 of architecture @var{arch}.
3349 @deffn {Scheme Procedure} arch-double-type arch
3350 Return the @code{<gdb:type>} object for a @code{double} type
3351 of architecture @var{arch}.
3354 @deffn {Scheme Procedure} arch-longdouble-type arch
3355 Return the @code{<gdb:type>} object for a @code{long double} type
3356 of architecture @var{arch}.
3359 @deffn {Scheme Procedure} arch-bool-type arch
3360 Return the @code{<gdb:type>} object for a @code{bool} type
3361 of architecture @var{arch}.
3364 @deffn {Scheme Procedure} arch-longlong-type arch
3365 Return the @code{<gdb:type>} object for a @code{long long} type
3366 of architecture @var{arch}.
3369 @deffn {Scheme Procedure} arch-ulonglong-type arch
3370 Return the @code{<gdb:type>} object for an @code{unsigned long long} type
3371 of architecture @var{arch}.
3374 @deffn {Scheme Procedure} arch-int8-type arch
3375 Return the @code{<gdb:type>} object for an @code{int8} type
3376 of architecture @var{arch}.
3379 @deffn {Scheme Procedure} arch-uint8-type arch
3380 Return the @code{<gdb:type>} object for a @code{uint8} type
3381 of architecture @var{arch}.
3384 @deffn {Scheme Procedure} arch-int16-type arch
3385 Return the @code{<gdb:type>} object for an @code{int16} type
3386 of architecture @var{arch}.
3389 @deffn {Scheme Procedure} arch-uint16-type arch
3390 Return the @code{<gdb:type>} object for a @code{uint16} type
3391 of architecture @var{arch}.
3394 @deffn {Scheme Procedure} arch-int32-type arch
3395 Return the @code{<gdb:type>} object for an @code{int32} type
3396 of architecture @var{arch}.
3399 @deffn {Scheme Procedure} arch-uint32-type arch
3400 Return the @code{<gdb:type>} object for a @code{uint32} type
3401 of architecture @var{arch}.
3404 @deffn {Scheme Procedure} arch-int64-type arch
3405 Return the @code{<gdb:type>} object for an @code{int64} type
3406 of architecture @var{arch}.
3409 @deffn {Scheme Procedure} arch-uint64-type arch
3410 Return the @code{<gdb:type>} object for a @code{uint64} type
3411 of architecture @var{arch}.
3417 (gdb) guile (type-name (arch-uchar-type (current-arch)))
3421 @node Disassembly In Guile
3422 @subsubsection Disassembly In Guile
3424 The disassembler can be invoked from Scheme code.
3425 Furthermore, the disassembler can take a Guile port as input,
3426 allowing one to disassemble from any source, and not just target memory.
3428 @c TODO: line length
3429 @deffn {Scheme Procedure} arch-disassemble arch start-pc @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size size@r{]} @r{[}#:count count@r{]}
3430 Return a list of disassembled instructions starting from the memory
3431 address @var{start-pc}.
3433 The optional argument @var{port} specifies the input port to read bytes from.
3434 If @var{port} is @code{#f} then bytes are read from target memory.
3436 The optional argument @var{offset} specifies the address offset of the
3437 first byte in @var{port}. This is useful, for example, when @var{port}
3438 specifies a @samp{bytevector} and you want the bytevector to be disassembled
3439 as if it came from that address. The @var{start-pc} passed to the reader
3440 for @var{port} is offset by the same amount.
3444 (gdb) guile (use-modules (rnrs io ports))
3445 (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
3446 (gdb) guile (define mem (open-memory #:start pc))
3447 (gdb) guile (define bv (get-bytevector-n mem 10))
3448 (gdb) guile (define bv-port (open-bytevector-input-port bv))
3449 (gdb) guile (define arch (current-arch))
3450 (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
3451 (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
3454 The optional arguments @var{size} and
3455 @var{count} determine the number of instructions in the returned list.
3456 If either @var{size} or @var{count} is specified as zero, then
3457 no instructions are disassembled and an empty list is returned.
3458 If both the optional arguments @var{size} and @var{count} are
3459 specified, then a list of at most @var{count} disassembled instructions
3460 whose start address falls in the closed memory address interval from
3461 @var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
3462 If @var{size} is not specified, but @var{count} is specified,
3463 then @var{count} number of instructions starting from the address
3464 @var{start-pc} are returned. If @var{count} is not specified but
3465 @var{size} is specified, then all instructions whose start address
3466 falls in the closed memory address interval from @var{start-pc} to
3467 (@var{start-pc} + @var{size} - 1) are returned.
3468 If neither @var{size} nor @var{count} are specified, then a single
3469 instruction at @var{start-pc} is returned.
3471 Each element of the returned list is an alist (associative list)
3472 with the following keys:
3477 The value corresponding to this key is a Guile integer of
3478 the memory address of the instruction.
3481 The value corresponding to this key is a string value which represents
3482 the instruction with assembly language mnemonics. The assembly
3483 language flavor used is the same as that specified by the current CLI
3484 variable @code{disassembly-flavor}. @xref{Machine Code}.
3487 The value corresponding to this key is the length of the instruction in bytes.
3492 @node I/O Ports in Guile
3493 @subsubsection I/O Ports in Guile
3495 @deffn {Scheme Procedure} input-port
3496 Return @value{GDBN}'s input port as a Guile port object.
3499 @deffn {Scheme Procedure} output-port
3500 Return @value{GDBN}'s output port as a Guile port object.
3503 @deffn {Scheme Procedure} error-port
3504 Return @value{GDBN}'s error port as a Guile port object.
3507 @deffn {Scheme Procedure} stdio-port? object
3508 Return @code{#t} if @var{object} is a @value{GDBN} stdio port.
3509 Otherwise return @code{#f}.
3512 @node Memory Ports in Guile
3513 @subsubsection Memory Ports in Guile
3515 @value{GDBN} provides a @code{port} interface to target memory.
3516 This allows Guile code to read/write target memory using Guile's port and
3517 bytevector functionality. The main routine is @code{open-memory} which
3518 returns a port object. One can then read/write memory using that object.
3520 @deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
3521 Return a port object that can be used for reading and writing memory.
3522 The port will be open according to @var{mode}, which is the standard
3523 mode argument to Guile port open routines, except that it is
3524 restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For
3525 compatibility @samp{"b"} (binary) may also be present, but we ignore
3526 it: memory ports are binary only. The default is @samp{"r"},
3529 The chunk of memory that can be accessed can be bounded.
3530 If both @var{start} and @var{size} are unspecified, all of memory can be
3531 accessed. If only @var{start} is specified, all of memory from that point
3532 on can be accessed. If only @var{size} if specified, all memory in the
3533 range [0,@var{size}) can be accessed. If both are specified, all memory
3534 in the rane [@var{start},@var{start}+@var{size}) can be accessed.
3537 @deffn {Scheme Procedure} memory-port?
3538 Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
3539 Otherwise return @code{#f}.
3542 @deffn {Scheme Procedure} memory-port-range memory-port
3543 Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
3544 of two elements: @code{(start end)}. The range is @var{start} to @var{end}
3548 @deffn {Scheme Procedure} memory-port-read-buffer-size memory-port
3549 Return the size of the read buffer of @code{<gdb:memory-port>}
3553 @deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
3554 Set the size of the read buffer of @code{<gdb:memory-port>}
3555 @var{memory-port} to @var{size}. The result is unspecified.
3558 @deffn {Scheme Procedure} memory-port-write-buffer-size memory-port
3559 Return the size of the write buffer of @code{<gdb:memory-port>}
3563 @deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
3564 Set the size of the write buffer of @code{<gdb:memory-port>}
3565 @var{memory-port} to @var{size}. The result is unspecified.
3568 A memory port is closed like any other port, with @code{close-port}.
3570 Combined with Guile's @code{bytevectors}, memory ports provide a lot
3571 of utility. For example, to fill a buffer of 10 integers in memory,
3572 one can do something like the following.
3575 ;; In the program: int buffer[10];
3576 (use-modules (rnrs bytevectors))
3577 (use-modules (rnrs io ports))
3578 (define addr (parse-and-eval "buffer"))
3580 (define byte-size (* n 4))
3581 (define mem-port (open-memory #:mode "r+" #:start
3582 (value->integer addr) #:size byte-size))
3583 (define byte-vec (make-bytevector byte-size))
3586 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
3587 (put-bytevector mem-port byte-vec)
3588 (close-port mem-port)
3591 @node Iterators In Guile
3592 @subsubsection Iterators In Guile
3594 @cindex guile iterators
3595 @tindex <gdb:iterator>
3597 A simple iterator facility is provided to allow, for example,
3598 iterating over the set of program symbols without having to first
3599 construct a list of all of them. A useful contribution would be
3600 to add support for SRFI 41 and SRFI 45.
3602 @deffn {Scheme Procedure} make-iterator object progress next!
3603 A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
3604 procedure. It takes three arguments: the object to be iterated over,
3605 an object to record the progress of the iteration, and a procedure to
3606 return the next element in the iteration, or an implementation chosen value
3607 to denote the end of iteration.
3609 By convention, end of iteration is marked with @code{(end-of-iteration)},
3610 and may be tested with the @code{end-of-iteration?} predicate.
3611 The result of @code{(end-of-iteration)} is chosen so that it is not
3612 otherwise used by the @code{(gdb)} module. If you are using
3613 @code{<gdb:iterator>} in your own code it is your responsibility to
3614 maintain this invariant.
3616 A trivial example for illustration's sake:
3619 (use-modules (gdb iterator))
3620 (define my-list (list 1 2 3))
3622 (make-iterator my-list my-list
3624 (let ((l (iterator-progress iter)))
3628 (set-iterator-progress! iter (cdr l))
3632 Here is a slightly more realistic example, which computes a list of all the
3633 functions in @code{my-global-block}.
3636 (use-modules (gdb iterator))
3637 (define this-sal (find-pc-line (frame-pc (selected-frame))))
3638 (define this-symtab (sal-symtab this-sal))
3639 (define this-global-block (symtab-global-block this-symtab))
3640 (define syms-iter (make-block-symbols-iterator this-global-block))
3641 (define functions (iterator-filter symbol-function? syms-iter))
3645 @deffn {Scheme Procedure} iterator? object
3646 Return @code{#t} if @var{object} is a @code{<gdb:iterator>} object.
3647 Otherwise return @code{#f}.
3650 @deffn {Scheme Procedure} iterator-object iterator
3651 Return the first argument that was passed to @code{make-iterator}.
3652 This is the object being iterated over.
3655 @deffn {Scheme Procedure} iterator-progress iterator
3656 Return the object tracking iteration progress.
3659 @deffn {Scheme Procedure} set-iterator-progress! iterator new-value
3660 Set the object tracking iteration progress.
3663 @deffn {Scheme Procedure} iterator-next! iterator
3664 Invoke the procedure that was the third argument to @code{make-iterator},
3665 passing it one argument, the @code{<gdb:iterator>} object.
3666 The result is either the next element in the iteration, or an end
3667 marker as implemented by the @code{next!} procedure.
3668 By convention the end marker is the result of @code{(end-of-iteration)}.
3671 @deffn {Scheme Procedure} end-of-iteration
3672 Return the Scheme object that denotes end of iteration.
3675 @deffn {Scheme Procedure} end-of-iteration? object
3676 Return @code{#t} if @var{object} is the end of iteration marker.
3677 Otherwise return @code{#f}.
3680 These functions are provided by the @code{(gdb iterator)} module to
3681 assist in using iterators.
3683 @deffn {Scheme Procedure} make-list-iterator list
3684 Return a @code{<gdb:iterator>} object that will iterate over @var{list}.
3687 @deffn {Scheme Procedure} iterator->list iterator
3688 Return the elements pointed to by @var{iterator} as a list.
3691 @deffn {Scheme Procedure} iterator-map proc iterator
3692 Return the list of objects obtained by applying @var{proc} to the object
3693 pointed to by @var{iterator} and to each subsequent object.
3696 @deffn {Scheme Procedure} iterator-for-each proc iterator
3697 Apply @var{proc} to each element pointed to by @var{iterator}.
3698 The result is unspecified.
3701 @deffn {Scheme Procedure} iterator-filter pred iterator
3702 Return the list of elements pointed to by @var{iterator} that satisfy
3706 @deffn {Scheme Procedure} iterator-until pred iterator
3707 Run @var{iterator} until the result of @code{(pred element)} is true
3708 and return that as the result. Otherwise return @code{#f}.
3711 @node Guile Auto-loading
3712 @subsection Guile Auto-loading
3713 @cindex guile auto-loading
3715 When a new object file is read (for example, due to the @code{file}
3716 command, or because the inferior has loaded a shared library),
3717 @value{GDBN} will look for Guile support scripts in two ways:
3718 @file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
3719 @xref{Auto-loading extensions}.
3721 The auto-loading feature is useful for supplying application-specific
3722 debugging commands and scripts.
3724 Auto-loading can be enabled or disabled,
3725 and the list of auto-loaded scripts can be printed.
3728 @anchor{set auto-load guile-scripts}
3729 @kindex set auto-load guile-scripts
3730 @item set auto-load guile-scripts [on|off]
3731 Enable or disable the auto-loading of Guile scripts.
3733 @anchor{show auto-load guile-scripts}
3734 @kindex show auto-load guile-scripts
3735 @item show auto-load guile-scripts
3736 Show whether auto-loading of Guile scripts is enabled or disabled.
3738 @anchor{info auto-load guile-scripts}
3739 @kindex info auto-load guile-scripts
3740 @cindex print list of auto-loaded Guile scripts
3741 @item info auto-load guile-scripts [@var{regexp}]
3742 Print the list of all Guile scripts that @value{GDBN} auto-loaded.
3744 Also printed is the list of Guile scripts that were mentioned in
3745 the @code{.debug_gdb_scripts} section and were not found.
3746 This is useful because their names are not printed when @value{GDBN}
3747 tries to load them and fails. There may be many of them, and printing
3748 an error message for each one is problematic.
3750 If @var{regexp} is supplied only Guile scripts with matching names are printed.
3755 (gdb) info auto-load guile-scripts
3757 Yes scm-section-script.scm
3758 full name: /tmp/scm-section-script.scm
3759 No my-foo-pretty-printers.scm
3763 When reading an auto-loaded file, @value{GDBN} sets the
3764 @dfn{current objfile}. This is available via the @code{current-objfile}
3765 procedure (@pxref{Objfiles In Guile}). This can be useful for
3766 registering objfile-specific pretty-printers.
3769 @subsection Guile Modules
3770 @cindex guile modules
3772 @value{GDBN} comes with several modules to assist writing Guile code.
3775 * Guile Printing Module:: Building and registering pretty-printers
3776 * Guile Types Module:: Utilities for working with types
3779 @node Guile Printing Module
3780 @subsubsection Guile Printing Module
3782 This module provides a collection of utilities for working with
3788 (use-modules (gdb printing))
3791 @deffn {Scheme Procedure} prepend-pretty-printer! object printer
3792 Add @var{printer} to the front of the list of pretty-printers for
3793 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3794 or @code{#f} in which case @var{printer} is added to the global list of
3798 @deffn {Scheme Procecure} append-pretty-printer! object printer
3799 Add @var{printer} to the end of the list of pretty-printers for
3800 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3801 or @code{#f} in which case @var{printer} is added to the global list of
3805 @node Guile Types Module
3806 @subsubsection Guile Types Module
3808 This module provides a collection of utilities for working with
3809 @code{<gdb:type>} objects.
3814 (use-modules (gdb types))
3817 @deffn {Scheme Procedure} get-basic-type type
3818 Return @var{type} with const and volatile qualifiers stripped,
3819 and with typedefs and C@t{++} references converted to the underlying type.
3824 typedef const int const_int;
3826 const_int& foo_ref (foo);
3827 int main () @{ return 0; @}
3834 (gdb) guile (use-modules (gdb) (gdb types))
3835 (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
3836 (gdb) guile (get-basic-type (value-type foo-ref))
3841 @deffn {Scheme Procedure} type-has-field-deep? type field
3842 Return @code{#t} if @var{type}, assumed to be a type with fields
3843 (e.g., a structure or union), has field @var{field}.
3844 Otherwise return @code{#f}.
3845 This searches baseclasses, whereas @code{type-has-field?} does not.
3848 @deffn {Scheme Procedure} make-enum-hashtable enum-type
3849 Return a Guile hash table produced from @var{enum-type}.
3850 Elements in the hash table are referenced with @code{hashq-ref}.