1 @c Copyright (C) 2008-2014 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 * Progspaces In Guile:: Program spaces
146 * Objfiles In Guile:: Object files in Guile
147 * Frames In Guile:: Accessing inferior stack frames from Guile
148 * Blocks In Guile:: Accessing blocks from Guile
149 * Symbols In Guile:: Guile representation of symbols
150 * Symbol Tables In Guile:: Guile representation of symbol tables
151 * Breakpoints In Guile:: Manipulating breakpoints using Guile
152 * Lazy Strings In Guile:: Guile representation of lazy strings
153 * Architectures In Guile:: Guile representation of architectures
154 * Disassembly In Guile:: Disassembling instructions from Guile
155 * I/O Ports in Guile:: GDB I/O ports
156 * Memory Ports in Guile:: Accessing memory through ports and bytevectors
157 * Iterators In Guile:: Basic iterator support
161 @subsubsection Basic Guile
164 @cindex guile pagination
165 At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
166 @code{current-error-port} to print using @value{GDBN}'s output-paging streams.
167 A Guile program which outputs to one of these streams may have its
168 output interrupted by the user (@pxref{Screen Size}). In this
169 situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
171 Guile's history mechanism uses the same naming as @value{GDBN}'s,
172 namely the user of dollar-variables (e.g., $1, $2, etc.).
173 The results of evaluations in Guile and in GDB are counted separately,
174 @code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}.
176 @value{GDBN} is not thread-safe. If your Guile program uses multiple
177 threads, you must be careful to only call @value{GDBN}-specific
178 functions in the @value{GDBN} thread.
180 Some care must be taken when writing Guile code to run in
181 @value{GDBN}. Two things are worth noting in particular:
185 @value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
186 Guile code must not override these, or even change the options using
187 @code{sigaction}. If your program changes the handling of these
188 signals, @value{GDBN} will most likely stop working correctly. Note
189 that it is unfortunately common for GUI toolkits to install a
190 @code{SIGCHLD} handler.
193 @value{GDBN} takes care to mark its internal file descriptors as
194 close-on-exec. However, this cannot be done in a thread-safe way on
195 all platforms. Your Guile programs should be aware of this and
196 should both create new file descriptors with the close-on-exec flag
197 set and arrange to close unneeded file descriptors before starting a
201 @cindex guile gdb module
202 @value{GDBN} introduces a new Guile module, named @code{gdb}. All
203 methods and classes added by @value{GDBN} are placed in this module.
204 @value{GDBN} does not automatically @code{import} the @code{gdb} module,
205 scripts must do this themselves. There are various options for how to
206 import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
207 module is imported to the user.
208 To simplify interactive use, it is recommended to add one of the following
212 guile (use-modules (gdb))
216 guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
219 Which one to choose depends on your preference.
220 The second one adds @code{gdb:} as a prefix to all module functions
223 The rest of this manual assumes the @code{gdb} module has been imported
224 without any prefix. See the Guile documentation for @code{use-modules}
226 (@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}).
231 (gdb) guile (value-type (make-value 1))
232 ERROR: Unbound variable: value-type
233 Error while executing Scheme code.
234 (gdb) guile (use-modules (gdb))
235 (gdb) guile (value-type (make-value 1))
240 The @code{(gdb)} module provides these basic Guile functions.
243 @deffn {Scheme Procedure} execute command @r{[}#:from-tty boolean@r{]} @r{[}#:to-string boolean@r{]}
244 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
245 If a @value{GDBN} exception happens while @var{command} runs, it is
246 translated as described in
247 @ref{Guile Exception Handling,,Guile Exception Handling}.
249 @var{from-tty} specifies whether @value{GDBN} ought to consider this
250 command as having originated from the user invoking it interactively.
251 It must be a boolean value. If omitted, it defaults to @code{#f}.
253 By default, any output produced by @var{command} is sent to
254 @value{GDBN}'s standard output (and to the log output if logging is
255 turned on). If the @var{to-string} parameter is
256 @code{#t}, then output will be collected by @code{execute} and
257 returned as a string. The default is @code{#f}, in which case the
258 return value is unspecified. If @var{to-string} is @code{#t}, the
259 @value{GDBN} virtual terminal will be temporarily set to unlimited width
260 and height, and its pagination will be disabled; @pxref{Screen Size}.
263 @deffn {Scheme Procedure} history-ref number
264 Return a value from @value{GDBN}'s value history (@pxref{Value
265 History}). The @var{number} argument indicates which history element to return.
266 If @var{number} is negative, then @value{GDBN} will take its absolute value
267 and count backward from the last element (i.e., the most recent element) to
268 find the value to return. If @var{number} is zero, then @value{GDBN} will
269 return the most recent element. If the element specified by @var{number}
270 doesn't exist in the value history, a @code{gdb:error} exception will be
273 If no exception is raised, the return value is always an instance of
274 @code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
276 @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
277 @code{$1} in @value{GDBN}'s value history contains the result of evaluating
278 an expression from @value{GDBN}'s command line and @code{$1} from Guile's
279 history contains the result of evaluating an expression from Guile's
283 @deffn {Scheme Procedure} history-append! value
284 Append @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
285 value history. Return its index in the history.
287 Putting into history values returned by Guile extensions will allow
288 the user convenient access to those values via CLI history
292 @deffn {Scheme Procedure} parse-and-eval expression
293 Parse @var{expression} as an expression in the current language,
294 evaluate it, and return the result as a @code{<gdb:value>}.
295 The @var{expression} must be a string.
297 This function can be useful when implementing a new command
298 (@pxref{Commands In Guile}), as it provides a way to parse the
299 command's arguments as an expression.
300 It is also is useful when computing values.
301 For example, it is the only way to get the value of a
302 convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
305 @node Guile Configuration
306 @subsubsection Guile Configuration
307 @cindex guile configuration
309 @value{GDBN} provides these Scheme functions to access various configuration
312 @deffn {Scheme Procedure} data-directory
313 Return a string containing @value{GDBN}'s data directory.
314 This directory contains @value{GDBN}'s ancillary files, including
315 the Guile modules provided by @value{GDBN}.
318 @deffn {Scheme Procedure} gdb-version
319 Return a string containing the @value{GDBN} version.
322 @deffn {Scheme Procedure} host-config
323 Return a string containing the host configuration.
324 This is the string passed to @code{--host} when @value{GDBN} was configured.
327 @deffn {Scheme Procedure} target-config
328 Return a string containing the target configuration.
329 This is the string passed to @code{--target} when @value{GDBN} was configured.
332 @node GDB Scheme Data Types
333 @subsubsection GDB Scheme Data Types
336 The values exposed by @value{GDBN} to Guile are known as
337 @dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN}
338 object, and each is disjoint from all other types known to Guile.
340 @deffn {Scheme Procedure} gdb-object-kind object
341 Return the kind of the @value{GDBN} object, e.g., @code{<gdb:breakpoint>},
345 @value{GDBN} defines the following object types:
349 @xref{Architectures In Guile}.
352 @xref{Blocks In Guile}.
354 @item <gdb:block-symbols-iterator>
355 @xref{Blocks In Guile}.
357 @item <gdb:breakpoint>
358 @xref{Breakpoints In Guile}.
361 @xref{Commands In Guile}.
363 @item <gdb:exception>
364 @xref{Guile Exception Handling}.
367 @xref{Frames In Guile}.
370 @xref{Iterators In Guile}.
372 @item <gdb:lazy-string>
373 @xref{Lazy Strings In Guile}.
376 @xref{Objfiles In Guile}.
378 @item <gdb:pretty-printer>
379 @xref{Guile Pretty Printing API}.
381 @item <gdb:pretty-printer-worker>
382 @xref{Guile Pretty Printing API}.
384 @item <gdb:progspace>
385 @xref{Progspaces In Guile}.
388 @xref{Symbols In Guile}.
391 @xref{Symbol Tables In Guile}.
394 @xref{Symbol Tables In Guile}.
397 @xref{Types In Guile}.
400 @xref{Types In Guile}.
403 @xref{Values From Inferior In Guile}.
406 The following @value{GDBN} objects are managed internally so that the
407 Scheme function @code{eq?} may be applied to them.
412 @item <gdb:breakpoint>
415 @item <gdb:progspace>
421 @node Guile Exception Handling
422 @subsubsection Guile Exception Handling
423 @cindex guile exceptions
424 @cindex exceptions, guile
425 @kindex set guile print-stack
427 When executing the @code{guile} command, Guile exceptions
428 uncaught within the Guile code are translated to calls to the
429 @value{GDBN} error-reporting mechanism. If the command that called
430 @code{guile} does not handle the error, @value{GDBN} will
431 terminate it and report the error according to the setting of
432 the @code{guile print-stack} parameter.
434 The @code{guile print-stack} parameter has three settings:
441 An error message is printed containing the Guile exception name,
442 the associated value, and the Guile call stack backtrace at the
443 point where the exception was raised. Example:
446 (@value{GDBP}) guile (display foo)
447 ERROR: In procedure memoize-variable-access!:
448 ERROR: Unbound variable: foo
449 Error while executing Scheme code.
453 In addition to an error message a full backtrace is printed.
456 (@value{GDBP}) set guile print-stack full
457 (@value{GDBP}) guile (display foo)
460 157: 10 [catch #t #<catch-closure 2c76e20> ...]
462 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
464 157: 8 [catch #t #<catch-closure 2c76d20> ...]
466 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
467 ?: 6 [call-with-input-string "(display foo)" ...]
469 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
470 In ice-9/eval-string.scm:
471 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
472 37: 3 [lp (display foo)]
475 393: 1 [eval #<memoized foo> ()]
477 ?: 0 [memoize-variable-access! #<memoized foo> ...]
479 ERROR: In procedure memoize-variable-access!:
480 ERROR: Unbound variable: foo
481 Error while executing Scheme code.
485 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
486 Guile code are converted to Guile exceptions. The type of the
487 Guile exception depends on the error.
489 Guile procedures provided by @value{GDBN} can throw the standard
490 Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
492 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
493 prompt) is translated to a Guile @code{signal} exception with value
496 @value{GDBN} Guile procedures can also throw these exceptions:
500 This exception is a catch-all for errors generated from within @value{GDBN}.
502 @item gdb:invalid-object
503 This exception is thrown when accessing Guile objects that wrap underlying
504 @value{GDBN} objects have become invalid. For example, a
505 @code{<gdb:breakpoint>} object becomes invalid if the user deletes it
506 from the command line. The object still exists in Guile, but the
507 object it represents is gone. Further operations on this breakpoint
508 will throw this exception.
510 @item gdb:memory-error
511 This exception is thrown when an operation tried to access invalid
512 memory in the inferior.
514 @item gdb:pp-type-error
515 This exception is thrown when a Guile pretty-printer passes a bad object
519 The following exception-related procedures are provided by the
522 @deffn {Scheme Procedure} make-exception key args
523 Return a @code{<gdb:exception>} object given by its @var{key} and
524 @var{args}, which are the standard Guile parameters of an exception.
525 See the Guile documentation for more information (@pxref{Exceptions,,,
526 guile, GNU Guile Reference Manual}).
529 @deffn {Scheme Procedure} exception? object
530 Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
531 Otherwise return @code{#f}.
534 @deffn {Scheme Procedure} exception-key exception
535 Return the @var{args} field of a @code{<gdb:exception>} object.
538 @deffn {Scheme Procedure} exception-args exception
539 Return the @var{args} field of a @code{<gdb:exception>} object.
542 @node Values From Inferior In Guile
543 @subsubsection Values From Inferior In Guile
544 @cindex values from inferior, in guile
545 @cindex guile, working with values from inferior
547 @tindex @code{<gdb:value>}
548 @value{GDBN} provides values it obtains from the inferior program in
549 an object of type @code{<gdb:value>}. @value{GDBN} uses this object
550 for its internal bookkeeping of the inferior's values, and for
551 fetching values when necessary.
553 @value{GDBN} does not memoize @code{<gdb:value>} objects.
554 @code{make-value} always returns a fresh object.
557 (gdb) guile (eq? (make-value 1) (make-value 1))
559 (gdb) guile (equal? (make-value 1) (make-value 1))
563 A @code{<gdb:value>} that represents a function can be executed via
564 inferior function call with @code{value-call}.
565 Any arguments provided to the call must match the function's prototype,
566 and must be provided in the order specified by that prototype.
568 For example, @code{some-val} is a @code{<gdb:value>} instance
569 representing a function that takes two integers as arguments. To
570 execute this function, call it like so:
573 (define result (value-call some-val 10 20))
576 Any values returned from a function call are @code{<gdb:value>} objects.
578 Note: Unlike Python scripting in @value{GDBN},
579 inferior values that are simple scalars cannot be used directly in
580 Scheme expressions that are valid for the value's data type.
581 For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
582 And inferior values that are structures or instances of some class cannot
583 be accessed using any special syntax, instead @code{value-field} must be used.
585 The following value-related procedures are provided by the
588 @deffn {Scheme Procedure} value? object
589 Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
590 Otherwise return @code{#f}.
593 @deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]}
594 Many Scheme values can be converted directly to a @code{<gdb:value>}
595 with this procedure. If @var{type} is specified, the result is a value
596 of this type, and if @var{value} can't be represented with this type
597 an exception is thrown. Otherwise the type of the result is determined from
598 @var{value} as described below.
600 @xref{Architectures In Guile}, for a list of the builtin
601 types for an architecture.
603 Here's how Scheme values are converted when @var{type} argument to
604 @code{make-value} is not specified:
608 A Scheme boolean is converted the boolean type for the current language.
611 A Scheme integer is converted to the first of a C @code{int},
612 @code{unsigned int}, @code{long}, @code{unsigned long},
613 @code{long long} or @code{unsigned long long} type
614 for the current architecture that can represent the value.
616 If the Scheme integer cannot be represented as a target integer
617 an @code{out-of-range} exception is thrown.
620 A Scheme real is converted to the C @code{double} type for the
621 current architecture.
624 A Scheme string is converted to a string in the current target
625 language using the current target encoding.
626 Characters that cannot be represented in the current target encoding
627 are replaced with the corresponding escape sequence. This is Guile's
628 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy
629 (@pxref{Strings,,, guile, GNU Guile Reference Manual}).
631 Passing @var{type} is not supported in this case,
632 if it is provided a @code{wrong-type-arg} exception is thrown.
634 @item @code{<gdb:lazy-string>}
635 If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
636 Guile}), then the @code{lazy-string->value} procedure is called, and
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 Scheme bytevector
643 If @var{value} is a Scheme bytevector and @var{type} is provided,
644 @var{value} must be the same size, in bytes, of values of type @var{type},
645 and the result is essentially created by using @code{memcpy}.
647 If @var{value} is a Scheme bytevector and @var{type} is not provided,
648 the result is an array of type @code{uint8} of the same length.
652 @cindex optimized out value in guile
653 @deffn {Scheme Procedure} value-optimized-out? value
654 Return @code{#t} if the compiler optimized out @var{value},
655 thus it is not available for fetching from the inferior.
656 Otherwise return @code{#f}.
659 @deffn {Scheme Procedure} value-address value
660 If @var{value} is addressable, returns a
661 @code{<gdb:value>} object representing the address.
662 Otherwise, @code{#f} is returned.
665 @deffn {Scheme Procedure} value-type value
666 Return the type of @var{value} as a @code{<gdb:type>} object
667 (@pxref{Types In Guile}).
670 @deffn {Scheme Procedure} value-dynamic-type value
671 Return the dynamic type of @var{value}. This uses C@t{++} run-time
672 type information (@acronym{RTTI}) to determine the dynamic type of the
673 value. If the value is of class type, it will return the class in
674 which the value is embedded, if any. If the value is of pointer or
675 reference to a class type, it will compute the dynamic type of the
676 referenced object, and return a pointer or reference to that type,
677 respectively. In all other cases, it will return the value's static
680 Note that this feature will only work when debugging a C@t{++} program
681 that includes @acronym{RTTI} for the object in question. Otherwise,
682 it will just return the static type of the value as in @kbd{ptype foo}.
683 @xref{Symbols, ptype}.
686 @deffn {Scheme Procedure} value-cast value type
687 Return a new instance of @code{<gdb:value>} that is the result of
688 casting @var{value} to the type described by @var{type}, which must
689 be a @code{<gdb:type>} object. If the cast cannot be performed for some
690 reason, this method throws an exception.
693 @deffn {Scheme Procedure} value-dynamic-cast value type
694 Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
695 operator were used. Consult a C@t{++} reference for details.
698 @deffn {Scheme Procedure} value-reinterpret-cast value type
699 Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
700 operator were used. Consult a C@t{++} reference for details.
703 @deffn {Scheme Procedure} value-dereference value
704 For pointer data types, this method returns a new @code{<gdb:value>} object
705 whose contents is the object pointed to by @var{value}. For example, if
706 @code{foo} is a C pointer to an @code{int}, declared in your C program as
713 then you can use the corresponding @code{<gdb:value>} to access what
714 @code{foo} points to like this:
717 (define bar (value-dereference foo))
720 The result @code{bar} will be a @code{<gdb:value>} object holding the
721 value pointed to by @code{foo}.
723 A similar function @code{value-referenced-value} exists which also
724 returns @code{<gdb:value>} objects corresonding to the values pointed to
725 by pointer values (and additionally, values referenced by reference
726 values). However, the behavior of @code{value-dereference}
727 differs from @code{value-referenced-value} by the fact that the
728 behavior of @code{value-dereference} is identical to applying the C
729 unary operator @code{*} on a given value. For example, consider a
730 reference to a pointer @code{ptrref}, declared in your C@t{++} program
738 intptr &ptrref = ptr;
741 Though @code{ptrref} is a reference value, one can apply the method
742 @code{value-dereference} to the @code{<gdb:value>} object corresponding
743 to it and obtain a @code{<gdb:value>} which is identical to that
744 corresponding to @code{val}. However, if you apply the method
745 @code{value-referenced-value}, the result would be a @code{<gdb:value>}
746 object identical to that corresponding to @code{ptr}.
749 (define scm-ptrref (parse-and-eval "ptrref"))
750 (define scm-val (value-dereference scm-ptrref))
751 (define scm-ptr (value-referenced-value scm-ptrref))
754 The @code{<gdb:value>} object @code{scm-val} is identical to that
755 corresponding to @code{val}, and @code{scm-ptr} is identical to that
756 corresponding to @code{ptr}. In general, @code{value-dereference} can
757 be applied whenever the C unary operator @code{*} can be applied
758 to the corresponding C value. For those cases where applying both
759 @code{value-dereference} and @code{value-referenced-value} is allowed,
760 the results obtained need not be identical (as we have seen in the above
761 example). The results are however identical when applied on
762 @code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
763 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
766 @deffn {Scheme Procedure} value-referenced-value value
767 For pointer or reference data types, this method returns a new
768 @code{<gdb:value>} object corresponding to the value referenced by the
769 pointer/reference value. For pointer data types,
770 @code{value-dereference} and @code{value-referenced-value} produce
771 identical results. The difference between these methods is that
772 @code{value-dereference} cannot get the values referenced by reference
773 values. For example, consider a reference to an @code{int}, declared
774 in your C@t{++} program as
782 then applying @code{value-dereference} to the @code{<gdb:value>} object
783 corresponding to @code{ref} will result in an error, while applying
784 @code{value-referenced-value} will result in a @code{<gdb:value>} object
785 identical to that corresponding to @code{val}.
788 (define scm-ref (parse-and-eval "ref"))
789 (define err-ref (value-dereference scm-ref)) ;; error
790 (define scm-val (value-referenced-value scm-ref)) ;; ok
793 The @code{<gdb:value>} object @code{scm-val} is identical to that
794 corresponding to @code{val}.
797 @deffn {Scheme Procedure} value-field value field-name
798 Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
801 @deffn {Scheme Procedure} value-subscript value index
802 Return the value of array @var{value} at index @var{index}.
803 The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
806 @deffn {Scheme Procedure} value-call value arg-list
807 Perform an inferior function call, taking @var{value} as a pointer
808 to the function to call.
809 Each element of list @var{arg-list} must be a <gdb:value> object or an object
810 that can be converted to a value.
811 The result is the value returned by the function.
814 @deffn {Scheme Procedure} value->bool value
815 Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
816 The value must be ``integer like''. Pointers are ok.
819 @deffn {Scheme Procedure} value->integer
820 Return the Scheme integer representing @code{<gdb:value>} @var{value}.
821 The value must be ``integer like''. Pointers are ok.
824 @deffn {Scheme Procedure} value->real
825 Return the Scheme real number representing @code{<gdb:value>} @var{value}.
826 The value must be a number.
829 @deffn {Scheme Procedure} value->bytevector
830 Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
831 @var{value}. No transformation, endian or otherwise, is performed.
835 @deffn {Scheme Procedure} value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
836 If @var{value>} represents a string, then this method
837 converts the contents to a Guile string. Otherwise, this method will
840 Values are interpreted as strings according to the rules of the
841 current language. If the optional length argument is given, the
842 string will be converted to that length, and will include any embedded
843 zeroes that the string may contain. Otherwise, for languages
844 where the string is zero-terminated, the entire string will be
847 For example, in C-like languages, a value is a string if it is a pointer
848 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
851 If the optional @var{encoding} argument is given, it must be a string
852 naming the encoding of the string in the @code{<gdb:value>}, such as
853 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
854 the same encodings as the corresponding argument to Guile's
855 @code{scm_from_stringn} function, and the Guile codec machinery will be used
856 to convert the string. If @var{encoding} is not given, or if
857 @var{encoding} is the empty string, then either the @code{target-charset}
858 (@pxref{Character Sets}) will be used, or a language-specific encoding
859 will be used, if the current language is able to supply one.
861 The optional @var{errors} argument is one of @code{#f}, @code{error} or
862 @code{substitute}. @code{error} and @code{substitute} must be symbols.
863 If @var{errors} is not specified, or if its value is @code{#f}, then the
864 default conversion strategy is used, which is set with the Scheme function
865 @code{set-port-conversion-strategy!}.
866 If the value is @code{'error} then an exception is thrown if there is any
867 conversion error. If the value is @code{'substitute} then any conversion
868 error is replaced with question marks.
869 @xref{Strings,,, guile, GNU Guile Reference Manual}.
871 If the optional @var{length} argument is given, the string will be
872 fetched and converted to the given length.
873 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
877 @deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]}
878 If this @code{<gdb:value>} represents a string, then this method
879 converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
880 In Guile}). Otherwise, this method will throw an exception.
882 If the optional @var{encoding} argument is given, it must be a string
883 naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
884 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
885 @var{encoding} argument is an encoding that @value{GDBN} does not
886 recognize, @value{GDBN} will raise an error.
888 When a lazy string is printed, the @value{GDBN} encoding machinery is
889 used to convert the string during printing. If the optional
890 @var{encoding} argument is not provided, or is an empty string,
891 @value{GDBN} will automatically select the encoding most suitable for
892 the string type. For further information on encoding in @value{GDBN}
893 please see @ref{Character Sets}.
895 If the optional @var{length} argument is given, the string will be
896 fetched and encoded to the length of characters specified. If
897 the @var{length} argument is not provided, the string will be fetched
898 and encoded until a null of appropriate width is found.
899 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
902 @deffn {Scheme Procedure} value-lazy? value
903 Return @code{#t} if @var{value} has not yet been fetched
905 Otherwise return @code{#f}.
906 @value{GDBN} does not fetch values until necessary, for efficiency.
910 (define myval (parse-and-eval "somevar"))
913 The value of @code{somevar} is not fetched at this time. It will be
914 fetched when the value is needed, or when the @code{fetch-lazy}
915 procedure is invoked.
918 @deffn {Scheme Procedure} make-lazy-value type address
919 Return a @code{<gdb:value>} that will be lazily fetched from the
920 target. The object of type @code{<gdb:type>} whose value to fetch is
921 specified by its @var{type} and its target memory @var{address}, which
925 @deffn {Scheme Procedure} value-fetch-lazy! value
926 If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
927 then the value is fetched from the inferior.
928 Any errors that occur in the process will produce a Guile exception.
930 If @var{value} is not a lazy value, this method has no effect.
932 The result of this function is unspecified.
935 @deffn {Scheme Procedure} value-print value
936 Return the string representation (print form) of @code{<gdb:value>}
940 @node Arithmetic In Guile
941 @subsubsection Arithmetic In Guile
943 The @code{(gdb)} module provides several functions for performing
944 arithmetic on @code{<gdb:value>} objects.
945 The arithmetic is performed as if it were done by the target,
946 and therefore has target semantics which are not necessarily
947 those of Scheme. For example operations work with a fixed precision,
948 not the arbitrary precision of Scheme.
950 Wherever a function takes an integer or pointer as an operand,
951 @value{GDBN} will convert appropriate Scheme values to perform
954 @deffn {Scheme Procedure} value-add a b
957 @deffn {Scheme Procedure} value-sub a b
960 @deffn {Scheme Procedure} value-mul a b
963 @deffn {Scheme Procedure} value-div a b
966 @deffn {Scheme Procedure} value-rem a b
969 @deffn {Scheme Procedure} value-mod a b
972 @deffn {Scheme Procedure} value-pow a b
975 @deffn {Scheme Procedure} value-not a
978 @deffn {Scheme Procedure} value-neg a
981 @deffn {Scheme Procedure} value-pos a
984 @deffn {Scheme Procedure} value-abs a
987 @deffn {Scheme Procedure} value-lsh a b
990 @deffn {Scheme Procedure} value-rsh a b
993 @deffn {Scheme Procedure} value-min a b
996 @deffn {Scheme Procedure} value-max a b
999 @deffn {Scheme Procedure} value-lognot a
1002 @deffn {Scheme Procedure} value-logand a b
1005 @deffn {Scheme Procedure} value-logior a b
1008 @deffn {Scheme Procedure} value-logxor a b
1011 @deffn {Scheme Procedure} value=? a b
1014 @deffn {Scheme Procedure} value<? a b
1017 @deffn {Scheme Procedure} value<=? a b
1020 @deffn {Scheme Procedure} value>? a b
1023 @deffn {Scheme Procedure} value>=? a b
1026 Scheme does not provide a @code{not-equal} function,
1027 and thus Guile support in @value{GDBN} does not either.
1029 @node Types In Guile
1030 @subsubsection Types In Guile
1031 @cindex types in guile
1032 @cindex guile, working with types
1035 @value{GDBN} represents types from the inferior in objects of type
1038 The following type-related procedures are provided by the
1039 @code{(gdb)} module.
1041 @deffn {Scheme Procedure} type? object
1042 Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
1043 Otherwise return @code{#f}.
1046 @deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
1047 This function looks up a type by its @var{name}, which must be a string.
1049 If @var{block} is given, it is an object of type @code{<gdb:block>},
1050 and @var{name} is looked up in that scope.
1051 Otherwise, it is searched for globally.
1053 Ordinarily, this function will return an instance of @code{<gdb:type>}.
1054 If the named type cannot be found, it will throw an exception.
1057 @deffn {Scheme Procedure} type-code type
1058 Return the type code of @var{type}. The type code will be one of the
1059 @code{TYPE_CODE_} constants defined below.
1062 @deffn {Scheme Procedure} type-tag type
1063 Return the tag name of @var{type}. The tag name is the name after
1064 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1065 languages have this concept. If this type has no tag name, then
1066 @code{#f} is returned.
1069 @deffn {Scheme Procedure} type-name type
1070 Return the name of @var{type}.
1071 If this type has no name, then @code{#f} is returned.
1074 @deffn {Scheme Procedure} type-print-name type
1075 Return the print name of @var{type}.
1076 This returns something even for anonymous types.
1077 For example, for an anonymous C struct @code{"struct @{...@}"} is returned.
1080 @deffn {Scheme Procedure} type-sizeof type
1081 Return the size of this type, in target @code{char} units. Usually, a
1082 target's @code{char} type will be an 8-bit byte. However, on some
1083 unusual platforms, this type may have a different size.
1086 @deffn {Scheme Procedure} type-strip-typedefs type
1087 Return a new @code{<gdb:type>} that represents the real type of @var{type},
1088 after removing all layers of typedefs.
1091 @deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]}
1092 Return a new @code{<gdb:type>} object which represents an array of this
1093 type. If one argument is given, it is the inclusive upper bound of
1094 the array; in this case the lower bound is zero. If two arguments are
1095 given, the first argument is the lower bound of the array, and the
1096 second argument is the upper bound of the array. An array's length
1097 must not be negative, but the bounds can be.
1100 @deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]}
1101 Return a new @code{<gdb:type>} object which represents a vector of this
1102 type. If one argument is given, it is the inclusive upper bound of
1103 the vector; in this case the lower bound is zero. If two arguments are
1104 given, the first argument is the lower bound of the vector, and the
1105 second argument is the upper bound of the vector. A vector's length
1106 must not be negative, but the bounds can be.
1108 The difference between an @code{array} and a @code{vector} is that
1109 arrays behave like in C: when used in expressions they decay to a pointer
1110 to the first element whereas vectors are treated as first class values.
1113 @deffn {Scheme Procedure} type-pointer type
1114 Return a new @code{<gdb:type>} object which represents a pointer to
1118 @deffn {Scheme Procedure} type-range type
1119 Return a list of two elements: the low bound and high bound of @var{type}.
1120 If @var{type} does not have a range, an exception is thrown.
1123 @deffn {Scheme Procedure} type-reference type
1124 Return a new @code{<gdb:type>} object which represents a reference to
1128 @deffn {Scheme Procedure} type-target type
1129 Return a new @code{<gdb:type>} object which represents the target type
1132 For a pointer type, the target type is the type of the pointed-to
1133 object. For an array type (meaning C-like arrays), the target type is
1134 the type of the elements of the array. For a function or method type,
1135 the target type is the type of the return value. For a complex type,
1136 the target type is the type of the elements. For a typedef, the
1137 target type is the aliased type.
1139 If the type does not have a target, this method will throw an
1143 @deffn {Scheme Procedure} type-const type
1144 Return a new @code{<gdb:type>} object which represents a
1145 @code{const}-qualified variant of @var{type}.
1148 @deffn {Scheme Procedure} type-volatile type
1149 Return a new @code{<gdb:type>} object which represents a
1150 @code{volatile}-qualified variant of @var{type}.
1153 @deffn {Scheme Procedure} type-unqualified type
1154 Return a new @code{<gdb:type>} object which represents an unqualified
1155 variant of @var{type}. That is, the result is neither @code{const} nor
1159 @deffn {Scheme Procedure} type-num-fields
1160 Return the number of fields of @code{<gdb:type>} @var{type}.
1163 @deffn {Scheme Procedure} type-fields type
1164 Return the fields of @var{type} as a list.
1165 For structure and union types, @code{fields} has the usual meaning.
1166 Range types have two fields, the minimum and maximum values. Enum types
1167 have one field per enum constant. Function and method types have one
1168 field per parameter. The base types of C@t{++} classes are also
1169 represented as fields. If the type has no fields, or does not fit
1170 into one of these categories, an empty list will be returned.
1171 @xref{Fields of a type in Guile}.
1174 @deffn {Scheme Procedure} make-field-iterator type
1175 Return the fields of @var{type} as a <gdb:iterator> object.
1176 @xref{Iterators In Guile}.
1179 @deffn {Scheme Procedure} type-field type field-name
1180 Return field named @var{field-name} in @var{type}.
1181 The result is an object of type @code{<gdb:field>}.
1182 @xref{Fields of a type in Guile}.
1183 If the type does not have fields, or @var{field-name} is not a field
1184 of @var{type}, an exception is thrown.
1186 For example, if @code{some-type} is a @code{<gdb:type>} instance holding
1187 a structure type, you can access its @code{foo} field with:
1190 (define bar (type-field some-type "foo"))
1193 @code{bar} will be a @code{<gdb:field>} object.
1196 @deffn {Scheme Procedure} type-has-field? type name
1197 Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
1198 Otherwise return @code{#f}.
1201 Each type has a code, which indicates what category this type falls
1202 into. The available type categories are represented by constants
1203 defined in the @code{(gdb)} module:
1207 The type is a pointer.
1209 @item TYPE_CODE_ARRAY
1210 The type is an array.
1212 @item TYPE_CODE_STRUCT
1213 The type is a structure.
1215 @item TYPE_CODE_UNION
1216 The type is a union.
1218 @item TYPE_CODE_ENUM
1219 The type is an enum.
1221 @item TYPE_CODE_FLAGS
1222 A bit flags type, used for things such as status registers.
1224 @item TYPE_CODE_FUNC
1225 The type is a function.
1228 The type is an integer type.
1231 A floating point type.
1233 @item TYPE_CODE_VOID
1234 The special type @code{void}.
1239 @item TYPE_CODE_RANGE
1240 A range type, that is, an integer type with bounds.
1242 @item TYPE_CODE_STRING
1243 A string type. Note that this is only used for certain languages with
1244 language-defined string types; C strings are not represented this way.
1246 @item TYPE_CODE_BITSTRING
1247 A string of bits. It is deprecated.
1249 @item TYPE_CODE_ERROR
1250 An unknown or erroneous type.
1252 @item TYPE_CODE_METHOD
1253 A method type, as found in C@t{++} or Java.
1255 @item TYPE_CODE_METHODPTR
1256 A pointer-to-member-function.
1258 @item TYPE_CODE_MEMBERPTR
1259 A pointer-to-member.
1264 @item TYPE_CODE_CHAR
1267 @item TYPE_CODE_BOOL
1270 @item TYPE_CODE_COMPLEX
1271 A complex float type.
1273 @item TYPE_CODE_TYPEDEF
1274 A typedef to some other type.
1276 @item TYPE_CODE_NAMESPACE
1277 A C@t{++} namespace.
1279 @item TYPE_CODE_DECFLOAT
1280 A decimal floating point type.
1282 @item TYPE_CODE_INTERNAL_FUNCTION
1283 A function internal to @value{GDBN}. This is the type used to represent
1284 convenience functions (@pxref{Convenience Funs}).
1287 Further support for types is provided in the @code{(gdb types)}
1288 Guile module (@pxref{Guile Types Module}).
1290 @anchor{Fields of a type in Guile}
1291 Each field is represented as an object of type @code{<gdb:field>}.
1293 The following field-related procedures are provided by the
1294 @code{(gdb)} module:
1296 @deffn {Scheme Procedure} field? object
1297 Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
1298 Otherwise return @code{#f}.
1301 @deffn {Scheme Procedure} field-name field
1302 Return the name of the field, or @code{#f} for anonymous fields.
1305 @deffn {Scheme Procedure} field-type field
1306 Return the type of the field. This is usually an instance of
1307 @code{<gdb:type>}, but it can be @code{#f} in some situations.
1310 @deffn {Scheme Procedure} field-enumval field
1311 Return the enum value represented by @code{<gdb:field>} @var{field}.
1314 @deffn {Scheme Procedure} field-bitpos field
1315 Return the bit position of @code{<gdb:field>} @var{field}.
1316 This attribute is not available for @code{static} fields (as in
1320 @deffn {Scheme Procedure} field-bitsize field
1321 If the field is packed, or is a bitfield, return the size of
1322 @code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
1323 in which case the field's size is given by its type.
1326 @deffn {Scheme Procedure} field-artificial? field
1327 Return @code{#t} if the field is artificial, usually meaning that
1328 it was provided by the compiler and not the user.
1329 Otherwise return @code{#f}.
1332 @deffn {Scheme Procedure} field-base-class? field
1333 Return @code{#t} if the field represents a base class of a C@t{++}
1335 Otherwise return @code{#f}.
1338 @node Guile Pretty Printing API
1339 @subsubsection Guile Pretty Printing API
1340 @cindex guile pretty printing api
1342 An example output is provided (@pxref{Pretty Printing}).
1344 A pretty-printer is represented by an object of type <gdb:pretty-printer>.
1345 Pretty-printer objects are created with @code{make-pretty-printer}.
1347 The following pretty-printer-related procedures are provided by the
1348 @code{(gdb)} module:
1350 @deffn {Scheme Procedure} make-pretty-printer name lookup-function
1351 Return a @code{<gdb:pretty-printer>} object named @var{name}.
1353 @var{lookup-function} is a function of one parameter: the value to
1354 be printed. If the value is handled by this pretty-printer, then
1355 @var{lookup-function} returns an object of type
1356 <gdb:pretty-printer-worker> to perform the actual pretty-printing.
1357 Otherwise @var{lookup-function} returns @code{#f}.
1360 @deffn {Scheme Procedure} pretty-printer? object
1361 Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
1362 Otherwise return @code{#f}.
1365 @deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer
1366 Return @code{#t} if @var{pretty-printer} is enabled.
1367 Otherwise return @code{#f}.
1370 @deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag
1371 Set the enabled flag of @var{pretty-printer} to @var{flag}.
1372 The value returned in unspecified.
1375 @deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children
1376 Return an object of type @code{<gdb:pretty-printer-worker>}.
1378 This function takes three parameters:
1382 @var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
1383 front end via MI to change the formatting of the value being printed.
1384 The value must be a string or @code{#f} (meaning there is no hint).
1385 Several values for @var{display-hint}
1386 are predefined by @value{GDBN}:
1390 Indicate that the object being printed is ``array-like''. The CLI
1391 uses this to respect parameters such as @code{set print elements} and
1392 @code{set print array}.
1395 Indicate that the object being printed is ``map-like'', and that the
1396 children of this value can be assumed to alternate between keys and
1400 Indicate that the object being printed is ``string-like''. If the
1401 printer's @code{to-string} function returns a Guile string of some
1402 kind, then @value{GDBN} will call its internal language-specific
1403 string-printing function to format the string. For the CLI this means
1404 adding quotation marks, possibly escaping some characters, respecting
1405 @code{set print elements}, and the like.
1409 @var{to-string} is either a function of one parameter, the
1410 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1412 When printing from the CLI, if the @code{to-string} method exists,
1413 then @value{GDBN} will prepend its result to the values returned by
1414 @code{children}. Exactly how this formatting is done is dependent on
1415 the display hint, and may change as more hints are added. Also,
1416 depending on the print settings (@pxref{Print Settings}), the CLI may
1417 print just the result of @code{to-string} in a stack trace, omitting
1418 the result of @code{children}.
1420 If this method returns a string, it is printed verbatim.
1422 Otherwise, if this method returns an instance of @code{<gdb:value>},
1423 then @value{GDBN} prints this value. This may result in a call to
1424 another pretty-printer.
1426 If instead the method returns a Guile value which is convertible to a
1427 @code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
1428 the resulting value. Again, this may result in a call to another
1429 pretty-printer. Guile scalars (integers, floats, and booleans) and
1430 strings are convertible to @code{<gdb:value>}; other types are not.
1432 Finally, if this method returns @code{#f} then no further operations
1433 are peformed in this method and nothing is printed.
1435 If the result is not one of these types, an exception is raised.
1437 @var{to-string} may also be @code{#f} in which case it is left to
1438 @var{children} to print the value.
1441 @var{children} is either a function of one parameter, the
1442 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1444 @value{GDBN} will call this function on a pretty-printer to compute the
1445 children of the pretty-printer's value.
1447 This function must return a <gdb:iterator> object.
1448 Each item returned by the iterator must be a tuple holding
1449 two elements. The first element is the ``name'' of the child; the
1450 second element is the child's value. The value can be any Guile
1451 object which is convertible to a @value{GDBN} value.
1453 If @var{children} is @code{#f}, @value{GDBN} will act
1454 as though the value has no children.
1458 @value{GDBN} provides a function which can be used to look up the
1459 default pretty-printer for a @code{<gdb:value>}:
1461 @deffn {Scheme Procedure} default-visualizer value
1462 This function takes a @code{<gdb:value>} object as an argument. If a
1463 pretty-printer for this value exists, then it is returned. If no such
1464 printer exists, then this returns @code{#f}.
1467 @node Selecting Guile Pretty-Printers
1468 @subsubsection Selecting Guile Pretty-Printers
1469 @cindex selecting guile pretty-printers
1471 The Guile list @code{*pretty-printers*} contains a set of
1472 @code{<gdb:pretty-printer>} registered objects.
1473 Printers in this list are called @code{global}
1474 printers, they're available when debugging any inferior.
1475 In addition to this, each @code{<gdb:objfile>} object contains its
1476 own set of pretty-printers (@pxref{Objfiles In Guile}).
1478 Pretty-printer lookup is done by passing the value to be printed to the
1479 lookup function of each enabled object in turn.
1480 Lookup stops when a lookup function returns a non-@code{#f} value
1481 or when the list is exhausted.
1483 @value{GDBN} first checks the result of @code{objfile-pretty-printers}
1484 of each @code{<gdb:objfile>} in the current program space and iteratively
1485 calls each enabled lookup function in the list for that @code{<gdb:objfile>}
1486 until a non-@code{#f} object is returned.
1487 Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
1488 object or @code{#f}. Otherwise an exception is thrown.
1489 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1490 searches the global pretty-printer list, calling each enabled function
1491 until a non-@code{#f} object is returned.
1493 The order in which the objfiles are searched is not specified. For a
1494 given list, functions are always invoked from the head of the list,
1495 and iterated over sequentially until the end of the list, or a
1496 @code{<gdb:pretty-printer-worker>} object is returned.
1498 For various reasons a pretty-printer may not work.
1499 For example, the underlying data structure may have changed and
1500 the pretty-printer is out of date.
1502 The consequences of a broken pretty-printer are severe enough that
1503 @value{GDBN} provides support for enabling and disabling individual
1504 printers. For example, if @code{print frame-arguments} is on,
1505 a backtrace can become highly illegible if any argument is printed
1506 with a broken printer.
1508 Pretty-printers are enabled and disabled from Scheme by calling
1509 @code{set-pretty-printer-enabled!}.
1510 @xref{Guile Pretty Printing API}.
1512 @node Writing a Guile Pretty-Printer
1513 @subsubsection Writing a Guile Pretty-Printer
1514 @cindex writing a Guile pretty-printer
1516 A pretty-printer consists of two basic parts: a lookup function to determine
1517 if the type is supported, and the printer itself.
1519 Here is an example showing how a @code{std::string} printer might be
1520 written. @xref{Guile Pretty Printing API}, for details.
1523 (define (make-my-string-printer value)
1524 "Print a my::string string"
1525 (make-pretty-printer-worker
1528 (value-field value "_data"))
1532 And here is an example showing how a lookup function for the printer
1533 example above might be written.
1536 (define (str-lookup-function pretty-printer value)
1537 (let ((tag (type-tag (value-type value))))
1539 (string-prefix? "std::string<" tag)
1540 (make-my-string-printer value))))
1543 Then to register this printer in the global printer list:
1546 (append-pretty-printer!
1547 (make-pretty-printer "my-string" str-lookup-function))
1550 The example lookup function extracts the value's type, and attempts to
1551 match it to a type that it can pretty-print. If it is a type the
1552 printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
1553 If not, it returns @code{#f}.
1555 We recommend that you put your core pretty-printers into a Guile
1556 package. If your pretty-printers are for use with a library, we
1557 further recommend embedding a version number into the package name.
1558 This practice will enable @value{GDBN} to load multiple versions of
1559 your pretty-printers at the same time, because they will have
1562 You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
1563 can be evaluated multiple times without changing its meaning. An
1564 ideal auto-load file will consist solely of @code{import}s of your
1565 printer modules, followed by a call to a register pretty-printers with
1566 the current objfile.
1568 Taken as a whole, this approach will scale nicely to multiple
1569 inferiors, each potentially using a different library version.
1570 Embedding a version number in the Guile package name will ensure that
1571 @value{GDBN} is able to load both sets of printers simultaneously.
1572 Then, because the search for pretty-printers is done by objfile, and
1573 because your auto-loaded code took care to register your library's
1574 printers with a specific objfile, @value{GDBN} will find the correct
1575 printers for the specific version of the library used by each
1578 To continue the @code{my::string} example,
1579 this code might appear in @code{(my-project my-library v1)}:
1583 (define (register-printers objfile)
1584 (append-objfile-pretty-printer!
1585 (make-pretty-printer "my-string" str-lookup-function)))
1589 And then the corresponding contents of the auto-load file would be:
1592 (use-modules (gdb) (my-project my-library v1))
1593 (register-printers (current-objfile))
1596 The previous example illustrates a basic pretty-printer.
1597 There are a few things that can be improved on.
1598 The printer only handles one type, whereas a library typically has
1599 several types. One could install a lookup function for each desired type
1600 in the library, but one could also have a single lookup function recognize
1601 several types. The latter is the conventional way this is handled.
1602 If a pretty-printer can handle multiple data types, then its
1603 @dfn{subprinters} are the printers for the individual data types.
1605 The @code{(gdb printing)} module provides a formal way of solving this
1606 problem (@pxref{Guile Printing Module}).
1607 Here is another example that handles multiple types.
1609 These are the types we are going to pretty-print:
1612 struct foo @{ int a, b; @};
1613 struct bar @{ struct foo x, y; @};
1616 Here are the printers:
1619 (define (make-foo-printer value)
1620 "Print a foo object"
1621 (make-pretty-printer-worker
1624 (format #f "a=<~a> b=<~a>"
1625 (value-field value "a") (value-field value "a")))
1628 (define (make-bar-printer value)
1629 "Print a bar object"
1630 (make-pretty-printer-worker
1633 (format #f "x=<~a> y=<~a>"
1634 (value-field value "x") (value-field value "y")))
1638 This example doesn't need a lookup function, that is handled by the
1639 @code{(gdb printing)} module. Instead a function is provided to build up
1640 the object that handles the lookup.
1643 (use-modules (gdb printing))
1645 (define (build-pretty-printer)
1646 (let ((pp (make-pretty-printer-collection "my-library")))
1647 (pp-collection-add-tag-printer "foo" make-foo-printer)
1648 (pp-collection-add-tag-printer "bar" make-bar-printer)
1652 And here is the autoload support:
1655 (use-modules (gdb) (my-library))
1656 (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
1659 Finally, when this printer is loaded into @value{GDBN}, here is the
1660 corresponding output of @samp{info pretty-printer}:
1663 (gdb) info pretty-printer
1670 @node Commands In Guile
1671 @subsubsection Commands In Guile
1673 @cindex commands in guile
1674 @cindex guile commands
1675 You can implement new @value{GDBN} CLI commands in Guile. A CLI
1676 command object is created with the @code{make-command} Guile function,
1677 and added to @value{GDBN} with the @code{register-command!} Guile function.
1678 This two-step approach is taken to separate out the side-effect of adding
1679 the command to @value{GDBN} from @code{make-command}.
1681 There is no support for multi-line commands, that is commands that
1682 consist of multiple lines and are terminated with @code{end}.
1684 @c TODO: line length
1685 @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{]})
1687 The argument @var{name} is the name of the command. If @var{name} consists of
1688 multiple words, then the initial words are looked for as prefix
1689 commands. In this case, if one of the prefix commands does not exist,
1690 an exception is raised.
1692 The result is the @code{<gdb:command>} object representing the command.
1693 The command is not usable until it has been registered with @value{GDBN}
1694 with @code{register-command!}.
1696 The rest of the arguments are optional.
1698 The argument @var{invoke} is a procedure of three arguments: @var{self},
1699 @var{args} and @var{from-tty}. The argument @var{self} is the
1700 @code{<gdb:command>} object representing the command.
1701 The argument @var{args} is a string representing the arguments passed to
1702 the command, after leading and trailing whitespace has been stripped.
1703 The argument @var{from-tty} is a boolean flag and specifies whether the
1704 command should consider itself to have been originated from the user
1705 invoking it interactively. If this function throws an exception,
1706 it is turned into a @value{GDBN} @code{error} call.
1707 Otherwise, the return value is ignored.
1709 The argument @var{command-class} is one of the @samp{COMMAND_} constants
1710 defined below. This argument tells @value{GDBN} how to categorize the
1711 new command in the help system. The default is @code{COMMAND_NONE}.
1713 The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_}
1714 constants defined below, or a procedure, also defined below.
1715 This argument tells @value{GDBN} how to perform completion
1716 for this command. If not provided or if the value is @code{#f},
1717 then no completion is performed on the command.
1719 The argument @var{prefix} is a boolean flag indicating whether the new
1720 command is a prefix command; sub-commands of this command may be
1723 The argument @var{doc-string} is help text for the new command.
1724 If no documentation string is provided, the default value ``This command is
1725 not documented.'' is used.
1728 @deffn {Scheme Procedure} register-command! command
1729 Add @var{command}, a @code{<gdb:command>} object, to @value{GDBN}'s
1731 It is an error to register a command more than once.
1732 The result is unspecified.
1735 @deffn {Scheme Procedure} command? object
1736 Return @code{#t} if @var{object} is a @code{<gdb:command>} object.
1737 Otherwise return @code{#f}.
1740 @cindex don't repeat Guile command
1741 @deffn {Scheme Procedure} dont-repeat
1742 By default, a @value{GDBN} command is repeated when the user enters a
1743 blank line at the command prompt. A command can suppress this
1744 behavior by invoking the @code{dont-repeat} function. This is similar
1745 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
1748 @deffn {Scheme Procedure} string->argv string
1749 Convert a string to a list of strings split up according to
1750 @value{GDBN}'s argv parsing rules.
1751 It is recommended to use this for consistency.
1752 Arguments are separated by spaces and may be quoted.
1756 scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
1757 $1 = ("1" "2 \"3" "4 \"5" "6 '7")
1761 @deffn {Scheme Procedure} throw-user-error message . args
1762 Throw a @code{gdb:user-error} exception.
1763 The argument @var{message} is the error message as a format string, like the
1764 @var{fmt} argument to the @code{format} Scheme function.
1765 @xref{Formatted Output,,, guile, GNU Guile Reference Manual}.
1766 The argument @var{args} is a list of the optional arguments of @var{message}.
1768 This is used when the command detects a user error of some kind,
1769 say a bad command argument.
1772 (gdb) guile (use-modules (gdb))
1774 (register-command! (make-command "test-user-error"
1775 #:command-class COMMAND_OBSCURE
1776 #:invoke (lambda (self arg from-tty)
1777 (throw-user-error "Bad argument ~a" arg))))
1779 (gdb) test-user-error ugh
1780 ERROR: Bad argument ugh
1784 @cindex completion of Guile commands
1785 @deffn completer self text word
1786 If the @var{completer} option to @code{make-command} is a procedure,
1787 it takes three arguments: @var{self} which is the @code{<gdb:command>}
1788 object, and @var{text} and @var{word} which are both strings.
1789 The argument @var{text} holds the complete command line up to the cursor's
1790 location. The argument @var{word} holds the last word of the command line;
1791 this is computed using a word-breaking heuristic.
1793 All forms of completion are handled by this function, that is,
1794 the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}),
1795 and the @code{complete} command (@pxref{Help, complete}).
1797 This procedure can return several kinds of values:
1801 If the return value is a list, the contents of the list are used as the
1802 completions. It is up to @var{completer} to ensure that the
1803 contents actually do complete the word. An empty list is
1804 allowed, it means that there were no completions available. Only
1805 string elements of the list are used; other elements in the
1809 If the return value is a @code{<gdb:iterator>} object, it is iterated over to
1810 obtain the completions. It is up to @code{completer-procedure} to ensure
1811 that the results actually do complete the word. Only
1812 string elements of the result are used; other elements in the
1813 sequence are ignored.
1816 All other results are treated as though there were no available
1821 When a new command is registered, it will have been declared as a member of
1822 some general class of commands. This is used to classify top-level
1823 commands in the on-line help system; note that prefix commands are not
1824 listed under their own category but rather that of their top-level
1825 command. The available classifications are represented by constants
1826 defined in the @code{gdb} module:
1830 The command does not belong to any particular class. A command in
1831 this category will not be displayed in any of the help categories.
1832 This is the default.
1834 @item COMMAND_RUNNING
1835 The command is related to running the inferior. For example,
1836 @code{start}, @code{step}, and @code{continue} are in this category.
1837 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
1838 commands in this category.
1841 The command is related to data or variables. For example,
1842 @code{call}, @code{find}, and @code{print} are in this category. Type
1843 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
1847 The command has to do with manipulation of the stack. For example,
1848 @code{backtrace}, @code{frame}, and @code{return} are in this
1849 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
1850 list of commands in this category.
1853 This class is used for file-related commands. For example,
1854 @code{file}, @code{list} and @code{section} are in this category.
1855 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
1856 commands in this category.
1858 @item COMMAND_SUPPORT
1859 This should be used for ``support facilities'', generally meaning
1860 things that are useful to the user when interacting with @value{GDBN},
1861 but not related to the state of the inferior. For example,
1862 @code{help}, @code{make}, and @code{shell} are in this category. Type
1863 @kbd{help support} at the @value{GDBN} prompt to see a list of
1864 commands in this category.
1866 @item COMMAND_STATUS
1867 The command is an @samp{info}-related command, that is, related to the
1868 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
1869 and @code{show} are in this category. Type @kbd{help status} at the
1870 @value{GDBN} prompt to see a list of commands in this category.
1872 @item COMMAND_BREAKPOINTS
1873 The command has to do with breakpoints. For example, @code{break},
1874 @code{clear}, and @code{delete} are in this category. Type @kbd{help
1875 breakpoints} at the @value{GDBN} prompt to see a list of commands in
1878 @item COMMAND_TRACEPOINTS
1879 The command has to do with tracepoints. For example, @code{trace},
1880 @code{actions}, and @code{tfind} are in this category. Type
1881 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
1882 commands in this category.
1885 The command is a general purpose command for the user, and typically
1886 does not fit in one of the other categories.
1887 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
1888 a list of commands in this category, as well as the list of gdb macros
1889 (@pxref{Sequences}).
1891 @item COMMAND_OBSCURE
1892 The command is only used in unusual circumstances, or is not of
1893 general interest to users. For example, @code{checkpoint},
1894 @code{fork}, and @code{stop} are in this category. Type @kbd{help
1895 obscure} at the @value{GDBN} prompt to see a list of commands in this
1898 @item COMMAND_MAINTENANCE
1899 The command is only useful to @value{GDBN} maintainers. The
1900 @code{maintenance} and @code{flushregs} commands are in this category.
1901 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
1902 commands in this category.
1905 A new command can use a predefined completion function, either by
1906 specifying it via an argument at initialization, or by returning it
1907 from the @code{completer} procedure. These predefined completion
1908 constants are all defined in the @code{gdb} module:
1912 This constant means that no completion should be done.
1914 @item COMPLETE_FILENAME
1915 This constant means that filename completion should be performed.
1917 @item COMPLETE_LOCATION
1918 This constant means that location completion should be done.
1919 @xref{Specify Location}.
1921 @item COMPLETE_COMMAND
1922 This constant means that completion should examine @value{GDBN}
1925 @item COMPLETE_SYMBOL
1926 This constant means that completion should be done using symbol names
1929 @item COMPLETE_EXPRESSION
1930 This constant means that completion should be done on expressions.
1931 Often this means completing on symbol names, but some language
1932 parsers also have support for completing on field names.
1935 The following code snippet shows how a trivial CLI command can be
1936 implemented in Guile:
1940 (register-command! (make-command "hello-world"
1941 #:command-class COMMAND_USER
1942 #:doc "Greet the whole world."
1943 #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
1949 @node Progspaces In Guile
1950 @subsubsection Program Spaces In Guile
1952 @cindex progspaces in guile
1953 @tindex <gdb:progspace>
1954 A program space, or @dfn{progspace}, represents a symbolic view
1955 of an address space.
1956 It consists of all of the objfiles of the program.
1957 @xref{Objfiles In Guile}.
1958 @xref{Inferiors and Programs, program spaces}, for more details
1959 about program spaces.
1961 Each progspace is represented by an instance of the @code{<gdb:progspace>}
1962 smob. @xref{GDB Scheme Data Types}.
1964 The following progspace-related functions are available in the
1965 @code{(gdb)} module:
1967 @deffn {Scheme Procedure} progspace? object
1968 Return @code{#t} if @var{object} is a @code{<gdb:progspace>} object.
1969 Otherwise return @code{#f}.
1972 @deffn {Scheme Procedure} progspace-valid? progspace
1973 Return @code{#t} if @var{progspace} is valid, @code{#f} if not.
1974 A @code{<gdb:progspace>} object can become invalid
1975 if the program it refers to is not loaded in @value{GDBN} any longer.
1978 @deffn {Scheme Procedure} current-progspace
1979 This function returns the program space of the currently selected inferior.
1980 There is always a current progspace, this never returns @code{#f}.
1981 @xref{Inferiors and Programs}.
1984 @deffn {Scheme Procedure} progspaces
1985 Return a list of all the progspaces currently known to @value{GDBN}.
1988 @deffn {Scheme Procedure} progspace-filename progspace
1989 Return the absolute file name of @var{progspace} as a string.
1990 This is the name of the file passed as the argument to the @code{file}
1991 or @code{symbol-file} commands.
1992 If the program space does not have an associated file name,
1993 then @code{#f} is returned. This occurs, for example, when @value{GDBN}
1994 is started without a program to debug.
1996 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2000 @deffn {Scheme Procedure} progspace-objfiles progspace
2001 Return the list of objfiles of @var{progspace}.
2002 The order of objfiles in the result is arbitrary.
2003 Each element is an object of type @code{<gdb:objfile>}.
2004 @xref{Objfiles In Guile}.
2006 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2010 @deffn {Scheme Procedure} progspace-pretty-printers progspace
2011 Return the list of pretty-printers of @var{progspace}.
2012 Each element is an object of type @code{<gdb:pretty-printer>}.
2013 @xref{Guile Pretty Printing API}, for more information.
2016 @deffn {Scheme Procedure} set-progspace-pretty-printers! progspace printer-list
2017 Set the list of registered @code{<gdb:pretty-printer>} objects for
2018 @var{progspace} to @var{printer-list}.
2019 @xref{Guile Pretty Printing API}, for more information.
2022 @node Objfiles In Guile
2023 @subsubsection Objfiles In Guile
2025 @cindex objfiles in guile
2026 @tindex <gdb:objfile>
2027 @value{GDBN} loads symbols for an inferior from various
2028 symbol-containing files (@pxref{Files}). These include the primary
2029 executable file, any shared libraries used by the inferior, and any
2030 separate debug info files (@pxref{Separate Debug Files}).
2031 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
2033 Each objfile is represented as an object of type @code{<gdb:objfile>}.
2035 The following objfile-related procedures are provided by the
2036 @code{(gdb)} module:
2038 @deffn {Scheme Procedure} objfile? object
2039 Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
2040 Otherwise return @code{#f}.
2043 @deffn {Scheme Procedure} objfile-valid? objfile
2044 Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
2045 A @code{<gdb:objfile>} object can become invalid
2046 if the object file it refers to is not loaded in @value{GDBN} any
2047 longer. All other @code{<gdb:objfile>} procedures will throw an exception
2048 if it is invalid at the time the procedure is called.
2051 @deffn {Scheme Procedure} objfile-filename objfile
2052 Return the file name of @var{objfile} as a string.
2055 @deffn {Scheme Procedure} objfile-pretty-printers objfile
2056 Return the list of registered @code{<gdb:pretty-printer>} objects for
2057 @var{objfile}. @xref{Guile Pretty Printing API}, for more information.
2060 @deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
2061 Set the list of registered @code{<gdb:pretty-printer>} objects for
2062 @var{objfile} to @var{printer-list}. The
2063 @var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
2064 @xref{Guile Pretty Printing API}, for more information.
2067 @deffn {Scheme Procedure} current-objfile
2068 When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
2069 sets the ``current objfile'' to the corresponding objfile. This
2070 function returns the current objfile. If there is no current objfile,
2071 this function returns @code{#f}.
2074 @deffn {Scheme Procedure} objfiles
2075 Return a list of all the objfiles in the current program space.
2078 @node Frames In Guile
2079 @subsubsection Accessing inferior stack frames from Guile.
2081 @cindex frames in guile
2082 When the debugged program stops, @value{GDBN} is able to analyze its call
2083 stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
2084 represents a frame in the stack. A @code{<gdb:frame>} object is only valid
2085 while its corresponding frame exists in the inferior's stack. If you try
2086 to use an invalid frame object, @value{GDBN} will throw a
2087 @code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
2089 Two @code{<gdb:frame>} objects can be compared for equality with the
2090 @code{equal?} function, like:
2093 (@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
2097 The following frame-related procedures are provided by the
2098 @code{(gdb)} module:
2100 @deffn {Scheme Procedure} frame? object
2101 Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
2102 Otherwise return @code{#f}.
2105 @deffn {Scheme Procedure} frame-valid? frame
2106 Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
2107 A frame object can become invalid if the frame it refers to doesn't
2108 exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
2109 an exception if the frame is invalid at the time the procedure is called.
2112 @deffn {Scheme Procedure} frame-name frame
2113 Return the function name of @var{frame}, or @code{#f} if it can't be
2117 @deffn {Scheme Procedure} frame-arch frame
2118 Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
2119 architecture. @xref{Architectures In Guile}.
2122 @deffn {Scheme Procedure} frame-type frame
2123 Return the type of @var{frame}. The value can be one of:
2127 An ordinary stack frame.
2130 A fake stack frame that was created by @value{GDBN} when performing an
2131 inferior function call.
2134 A frame representing an inlined function. The function was inlined
2135 into a @code{NORMAL_FRAME} that is older than this one.
2137 @item TAILCALL_FRAME
2138 A frame representing a tail call. @xref{Tail Call Frames}.
2140 @item SIGTRAMP_FRAME
2141 A signal trampoline frame. This is the frame created by the OS when
2142 it calls into a signal handler.
2145 A fake stack frame representing a cross-architecture call.
2147 @item SENTINEL_FRAME
2148 This is like @code{NORMAL_FRAME}, but it is only used for the
2153 @deffn {Scheme Procedure} frame-unwind-stop-reason frame
2154 Return an integer representing the reason why it's not possible to find
2155 more frames toward the outermost frame. Use
2156 @code{unwind-stop-reason-string} to convert the value returned by this
2157 function to a string. The value can be one of:
2160 @item FRAME_UNWIND_NO_REASON
2161 No particular reason (older frames should be available).
2163 @item FRAME_UNWIND_NULL_ID
2164 The previous frame's analyzer returns an invalid result.
2166 @item FRAME_UNWIND_OUTERMOST
2167 This frame is the outermost.
2169 @item FRAME_UNWIND_UNAVAILABLE
2170 Cannot unwind further, because that would require knowing the
2171 values of registers or memory that have not been collected.
2173 @item FRAME_UNWIND_INNER_ID
2174 This frame ID looks like it ought to belong to a NEXT frame,
2175 but we got it for a PREV frame. Normally, this is a sign of
2176 unwinder failure. It could also indicate stack corruption.
2178 @item FRAME_UNWIND_SAME_ID
2179 This frame has the same ID as the previous one. That means
2180 that unwinding further would almost certainly give us another
2181 frame with exactly the same ID, so break the chain. Normally,
2182 this is a sign of unwinder failure. It could also indicate
2185 @item FRAME_UNWIND_NO_SAVED_PC
2186 The frame unwinder did not find any saved PC, but we needed
2187 one to unwind further.
2189 @item FRAME_UNWIND_MEMORY_ERROR
2190 The frame unwinder caused an error while trying to access memory.
2192 @item FRAME_UNWIND_FIRST_ERROR
2193 Any stop reason greater or equal to this value indicates some kind
2194 of error. This special value facilitates writing code that tests
2195 for errors in unwinding in a way that will work correctly even if
2196 the list of the other values is modified in future @value{GDBN}
2197 versions. Using it, you could write:
2200 (define reason (frame-unwind-stop-readon (selected-frame)))
2201 (define reason-str (unwind-stop-reason-string reason))
2202 (if (>= reason FRAME_UNWIND_FIRST_ERROR)
2203 (format #t "An error occured: ~s\n" reason-str))
2208 @deffn {Scheme Procedure} frame-pc frame
2209 Return the frame's resume address.
2212 @deffn {Scheme Procedure} frame-block frame
2213 Return the frame's code block as a @code{<gdb:block>} object.
2214 @xref{Blocks In Guile}.
2217 @deffn {Scheme Procedure} frame-function frame
2218 Return the symbol for the function corresponding to this frame
2219 as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
2220 @xref{Symbols In Guile}.
2223 @deffn {Scheme Procedure} frame-older frame
2224 Return the frame that called @var{frame}.
2227 @deffn {Scheme Procedure} frame-newer frame
2228 Return the frame called by @var{frame}.
2231 @deffn {Scheme Procedure} frame-sal frame
2232 Return the frame's @code{<gdb:sal>} (symtab and line) object.
2233 @xref{Symbol Tables In Guile}.
2236 @deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]}
2237 Return the value of @var{variable} in @var{frame}. If the optional
2238 argument @var{block} is provided, search for the variable from that
2239 block; otherwise start at the frame's current block (which is
2240 determined by the frame's current program counter). The
2241 @var{variable} must be given as a string or a @code{<gdb:symbol>}
2242 object, and @var{block} must be a @code{<gdb:block>} object.
2245 @deffn {Scheme Procedure} frame-select frame
2246 Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
2250 @deffn {Scheme Procedure} selected-frame
2251 Return the selected frame object. @xref{Selection,,Selecting a Frame}.
2254 @deffn {Scheme Procedure} newest-frame
2255 Return the newest frame object for the selected thread.
2258 @deffn {Scheme Procedure} unwind-stop-reason-string reason
2259 Return a string explaining the reason why @value{GDBN} stopped unwinding
2260 frames, as expressed by the given @var{reason} code (an integer, see the
2261 @code{frame-unwind-stop-reason} procedure above in this section).
2264 @node Blocks In Guile
2265 @subsubsection Accessing blocks from Guile.
2267 @cindex blocks in guile
2270 In @value{GDBN}, symbols are stored in blocks. A block corresponds
2271 roughly to a scope in the source code. Blocks are organized
2272 hierarchically, and are represented individually in Guile as an object
2273 of type @code{<gdb:block>}. Blocks rely on debugging information being
2276 A frame has a block. Please see @ref{Frames In Guile}, for a more
2277 in-depth discussion of frames.
2279 The outermost block is known as the @dfn{global block}. The global
2280 block typically holds public global variables and functions.
2282 The block nested just inside the global block is the @dfn{static
2283 block}. The static block typically holds file-scoped variables and
2286 @value{GDBN} provides a method to get a block's superblock, but there
2287 is currently no way to examine the sub-blocks of a block, or to
2288 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
2291 Here is a short example that should help explain blocks:
2294 /* This is in the global block. */
2297 /* This is in the static block. */
2298 static int file_scope;
2300 /* 'function' is in the global block, and 'argument' is
2301 in a block nested inside of 'function'. */
2302 int function (int argument)
2304 /* 'local' is in a block inside 'function'. It may or may
2305 not be in the same block as 'argument'. */
2309 /* 'inner' is in a block whose superblock is the one holding
2313 /* If this call is expanded by the compiler, you may see
2314 a nested block here whose function is 'inline_function'
2315 and whose superblock is the one holding 'inner'. */
2321 The following block-related procedures are provided by the
2322 @code{(gdb)} module:
2324 @deffn {Scheme Procedure} block? object
2325 Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
2326 Otherwise return @code{#f}.
2329 @deffn {Scheme Procedure} block-valid? block
2330 Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
2331 @code{#f} if not. A block object can become invalid if the block it
2332 refers to doesn't exist anymore in the inferior. All other
2333 @code{<gdb:block>} methods will throw an exception if it is invalid at
2334 the time the procedure is called. The block's validity is also checked
2335 during iteration over symbols of the block.
2338 @deffn {Scheme Procedure} block-start block
2339 Return the start address of @code{<gdb:block>} @var{block}.
2342 @deffn {Scheme Procedure} block-end block
2343 Return the end address of @code{<gdb:block>} @var{block}.
2346 @deffn {Scheme Procedure} block-function block
2347 Return the name of @code{<gdb:block>} @var{block} represented as a
2348 @code{<gdb:symbol>} object.
2349 If the block is not named, then @code{#f} is returned.
2351 For ordinary function blocks, the superblock is the static block.
2352 However, you should note that it is possible for a function block to
2353 have a superblock that is not the static block -- for instance this
2354 happens for an inlined function.
2357 @deffn {Scheme Procedure} block-superblock block
2358 Return the block containing @code{<gdb:block>} @var{block}.
2359 If the parent block does not exist, then @code{#f} is returned.
2362 @deffn {Scheme Procedure} block-global-block block
2363 Return the global block associated with @code{<gdb:block>} @var{block}.
2366 @deffn {Scheme Procedure} block-static-block block
2367 Return the static block associated with @code{<gdb:block>} @var{block}.
2370 @deffn {Scheme Procedure} block-global? block
2371 Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
2372 Otherwise return @code{#f}.
2375 @deffn {Scheme Procedure} block-static? block
2376 Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
2377 Otherwise return @code{#f}.
2380 @deffn {Scheme Procedure} block-symbols
2381 Return a list of all symbols (as <gdb:symbol> objects) in
2382 @code{<gdb:block>} @var{block}.
2385 @deffn {Scheme Procedure} make-block-symbols-iterator block
2386 Return an object of type @code{<gdb:iterator>} that will iterate
2387 over all symbols of the block.
2388 Guile programs should not assume that a specific block object will
2389 always contain a given symbol, since changes in @value{GDBN} features and
2390 infrastructure may cause symbols move across blocks in a symbol table.
2391 @xref{Iterators In Guile}.
2394 @deffn {Scheme Procedure} block-symbols-progress?
2395 Return #t if the object is a <gdb:block-symbols-progress> object.
2396 This object would be obtained from the @code{progress} element of the
2397 @code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
2400 @deffn {Scheme Procedure} lookup-block pc
2401 Return the innermost @code{<gdb:block>} containing the given @var{pc}
2402 value. If the block cannot be found for the @var{pc} value specified,
2403 the function will return @code{#f}.
2406 @node Symbols In Guile
2407 @subsubsection Guile representation of Symbols.
2409 @cindex symbols in guile
2410 @tindex <gdb:symbol>
2412 @value{GDBN} represents every variable, function and type as an
2413 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
2414 Guile represents these symbols in @value{GDBN} with the
2415 @code{<gdb:symbol>} object.
2417 The following symbol-related procedures are provided by the
2418 @code{(gdb)} module:
2420 @deffn {Scheme Procedure} symbol? object
2421 Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
2422 Otherwise return @code{#f}.
2425 @deffn {Scheme Procedure} symbol-valid? symbol
2426 Return @code{#t} if the @code{<gdb:symbol>} object is valid,
2427 @code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
2428 the symbol it refers to does not exist in @value{GDBN} any longer.
2429 All other @code{<gdb:symbol>} procedures will throw an exception if it is
2430 invalid at the time the procedure is called.
2433 @deffn {Scheme Procedure} symbol-type symbol
2434 Return the type of @var{symbol} or @code{#f} if no type is recorded.
2435 The result is an object of type @code{<gdb:type>}.
2436 @xref{Types In Guile}.
2439 @deffn {Scheme Procedure} symbol-symtab symbol
2440 Return the symbol table in which @var{symbol} appears.
2441 The result is an object of type @code{<gdb:symtab>}.
2442 @xref{Symbol Tables In Guile}.
2445 @deffn {Scheme Procedure} symbol-line symbol
2446 Return the line number in the source code at which @var{symbol} was defined.
2450 @deffn {Scheme Procedure} symbol-name symbol
2451 Return the name of @var{symbol} as a string.
2454 @deffn {Scheme Procedure} symbol-linkage-name symbol
2455 Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
2458 @deffn {Scheme Procedure} symbol-print-name symbol
2459 Return the name of @var{symbol} in a form suitable for output. This is either
2460 @code{name} or @code{linkage_name}, depending on whether the user
2461 asked @value{GDBN} to display demangled or mangled names.
2464 @deffn {Scheme Procedure} symbol-addr-class symbol
2465 Return the address class of the symbol. This classifies how to find the value
2466 of a symbol. Each address class is a constant defined in the
2467 @code{(gdb)} module and described later in this chapter.
2470 @deffn {Scheme Procedure} symbol-needs-frame? symbol
2471 Return @code{#t} if evaluating @var{symbol}'s value requires a frame
2472 (@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
2473 local variables will require a frame, but other symbols will not.
2476 @deffn {Scheme Procedure} symbol-argument? symbol
2477 Return @code{#t} if @var{symbol} is an argument of a function.
2478 Otherwise return @code{#f}.
2481 @deffn {Scheme Procedure} symbol-constant? symbol
2482 Return @code{#t} if @var{symbol} is a constant.
2483 Otherwise return @code{#f}.
2486 @deffn {Scheme Procedure} symbol-function? symbol
2487 Return @code{#t} if @var{symbol} is a function or a method.
2488 Otherwise return @code{#f}.
2491 @deffn {Scheme Procedure} symbol-variable? symbol
2492 Return @code{#t} if @var{symbol} is a variable.
2493 Otherwise return @code{#f}.
2496 @deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]}
2497 Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
2498 functions, this computes the address of the function, cast to the
2499 appropriate type. If the symbol requires a frame in order to compute
2500 its value, then @var{frame} must be given. If @var{frame} is not
2501 given, or if @var{frame} is invalid, then an exception is thrown.
2504 @c TODO: line length
2505 @deffn {Scheme Procedure} lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]}
2506 This function searches for a symbol by name. The search scope can be
2507 restricted to the parameters defined in the optional domain and block
2510 @var{name} is the name of the symbol. It must be a string. The
2511 optional @var{block} argument restricts the search to symbols visible
2512 in that @var{block}. The @var{block} argument must be a
2513 @code{<gdb:block>} object. If omitted, the block for the current frame
2514 is used. The optional @var{domain} argument restricts
2515 the search to the domain type. The @var{domain} argument must be a
2516 domain constant defined in the @code{(gdb)} module and described later
2519 The result is a list of two elements.
2520 The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2522 If the symbol is found, the second element is @code{#t} if the symbol
2523 is a field of a method's object (e.g., @code{this} in C@t{++}),
2524 otherwise it is @code{#f}.
2525 If the symbol is not found, the second element is @code{#f}.
2528 @deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]}
2529 This function searches for a global symbol by name.
2530 The search scope can be restricted by the domain argument.
2532 @var{name} is the name of the symbol. It must be a string.
2533 The optional @var{domain} argument restricts the search to the domain type.
2534 The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
2535 module and described later in this chapter.
2537 The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2541 The available domain categories in @code{<gdb:symbol>} are represented
2542 as constants in the @code{(gdb)} module:
2545 @item SYMBOL_UNDEF_DOMAIN
2546 This is used when a domain has not been discovered or none of the
2547 following domains apply. This usually indicates an error either
2548 in the symbol information or in @value{GDBN}'s handling of symbols.
2550 @item SYMBOL_VAR_DOMAIN
2551 This domain contains variables, function names, typedef names and enum
2554 @item SYMBOL_STRUCT_DOMAIN
2555 This domain holds struct, union and enum type names.
2557 @item SYMBOL_LABEL_DOMAIN
2558 This domain contains names of labels (for gotos).
2560 @item SYMBOL_VARIABLES_DOMAIN
2561 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
2562 contains everything minus functions and types.
2564 @item SYMBOL_FUNCTION_DOMAIN
2565 This domain contains all functions.
2567 @item SYMBOL_TYPES_DOMAIN
2568 This domain contains all types.
2571 The available address class categories in @code{<gdb:symbol>} are represented
2572 as constants in the @code{gdb} module:
2575 @item SYMBOL_LOC_UNDEF
2576 If this is returned by address class, it indicates an error either in
2577 the symbol information or in @value{GDBN}'s handling of symbols.
2579 @item SYMBOL_LOC_CONST
2580 Value is constant int.
2582 @item SYMBOL_LOC_STATIC
2583 Value is at a fixed address.
2585 @item SYMBOL_LOC_REGISTER
2586 Value is in a register.
2588 @item SYMBOL_LOC_ARG
2589 Value is an argument. This value is at the offset stored within the
2590 symbol inside the frame's argument list.
2592 @item SYMBOL_LOC_REF_ARG
2593 Value address is stored in the frame's argument list. Just like
2594 @code{LOC_ARG} except that the value's address is stored at the
2595 offset, not the value itself.
2597 @item SYMBOL_LOC_REGPARM_ADDR
2598 Value is a specified register. Just like @code{LOC_REGISTER} except
2599 the register holds the address of the argument instead of the argument
2602 @item SYMBOL_LOC_LOCAL
2603 Value is a local variable.
2605 @item SYMBOL_LOC_TYPEDEF
2606 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
2609 @item SYMBOL_LOC_BLOCK
2612 @item SYMBOL_LOC_CONST_BYTES
2613 Value is a byte-sequence.
2615 @item SYMBOL_LOC_UNRESOLVED
2616 Value is at a fixed address, but the address of the variable has to be
2617 determined from the minimal symbol table whenever the variable is
2620 @item SYMBOL_LOC_OPTIMIZED_OUT
2621 The value does not actually exist in the program.
2623 @item SYMBOL_LOC_COMPUTED
2624 The value's address is a computed location.
2627 @node Symbol Tables In Guile
2628 @subsubsection Symbol table representation in Guile.
2630 @cindex symbol tables in guile
2631 @tindex <gdb:symtab>
2634 Access to symbol table data maintained by @value{GDBN} on the inferior
2635 is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
2636 @code{<gdb:symtab>}. Symbol table and line data for a frame is returned
2637 from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
2638 @xref{Frames In Guile}.
2640 For more information on @value{GDBN}'s symbol table management, see
2641 @ref{Symbols, ,Examining the Symbol Table}.
2643 The following symtab-related procedures are provided by the
2644 @code{(gdb)} module:
2646 @deffn {Scheme Procedure} symtab? object
2647 Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
2648 Otherwise return @code{#f}.
2651 @deffn {Scheme Procedure} symtab-valid? symtab
2652 Return @code{#t} if the @code{<gdb:symtab>} object is valid,
2653 @code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
2654 the symbol table it refers to no longer exists in @value{GDBN}.
2655 All other @code{<gdb:symtab>} procedures will throw an exception
2656 if it is invalid at the time the procedure is called.
2659 @deffn {Scheme Procedure} symtab-filename symtab
2660 Return the symbol table's source filename.
2663 @deffn {Scheme Procedure} symtab-fullname symtab
2664 Return the symbol table's source absolute file name.
2667 @deffn {Scheme Procedure} symtab-objfile symtab
2668 Return the symbol table's backing object file. @xref{Objfiles In Guile}.
2671 @deffn {Scheme Procedure} symtab-global-block symtab
2672 Return the global block of the underlying symbol table.
2673 @xref{Blocks In Guile}.
2676 @deffn {Scheme Procedure} symtab-static-block symtab
2677 Return the static block of the underlying symbol table.
2678 @xref{Blocks In Guile}.
2681 The following symtab-and-line-related procedures are provided by the
2682 @code{(gdb)} module:
2684 @deffn {Scheme Procedure} sal? object
2685 Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
2686 Otherwise return @code{#f}.
2689 @deffn {Scheme Procedure} sal-valid? sal
2690 Return @code{#t} if @var{sal} is valid, @code{#f} if not.
2691 A @code{<gdb:sal>} object becomes invalid when the Symbol table object
2692 it refers to no longer exists in @value{GDBN}. All other
2693 @code{<gdb:sal>} procedures will throw an exception if it is
2694 invalid at the time the procedure is called.
2697 @deffn {Scheme Procedure} sal-symtab sal
2698 Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
2701 @deffn {Scheme Procedure} sal-line sal
2702 Return the line number for @var{sal}.
2705 @deffn {Scheme Procedure} sal-pc sal
2706 Return the start of the address range occupied by code for @var{sal}.
2709 @deffn {Scheme Procedure} sal-last sal
2710 Return the end of the address range occupied by code for @var{sal}.
2713 @deffn {Scheme Procedure} find-pc-line pc
2714 Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
2715 If an invalid value of @var{pc} is passed as an argument, then the
2716 @code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
2717 object will be @code{#f} and 0 respectively.
2720 @node Breakpoints In Guile
2721 @subsubsection Manipulating breakpoints using Guile
2723 @cindex breakpoints in guile
2724 @tindex <gdb:breakpoint>
2726 Breakpoints in Guile are represented by objects of type
2727 @code{<gdb:breakpoint>}.
2729 The following breakpoint-related procedures are provided by the
2730 @code{(gdb)} module:
2732 @c TODO: line length
2733 @deffn {Scheme Procedure} create-breakpoint! location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
2734 Create a new breakpoint according to @var{spec}, a string naming the
2735 location of the breakpoint, or an expression that defines a watchpoint.
2736 The contents can be any location recognized by the @code{break} command,
2737 or in the case of a watchpoint, by the @code{watch} command.
2739 The optional @var{type} denotes the breakpoint to create.
2740 This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
2741 and defaults to @code{BP_BREAKPOINT}.
2743 The optional @var{wp-class} argument defines the class of watchpoint to
2744 create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
2745 not provided, it is assumed to be a @code{WP_WRITE} class.
2747 The optional @var{internal} argument allows the breakpoint to become
2748 invisible to the user. The breakpoint will neither be reported when
2749 created, nor will it be listed in the output from @code{info breakpoints}
2750 (but will be listed with the @code{maint info breakpoints} command).
2751 If an internal flag is not provided, the breakpoint is visible
2754 When a watchpoint is created, @value{GDBN} will try to create a
2755 hardware assisted watchpoint. If successful, the type of the watchpoint
2756 is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
2757 for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
2758 and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
2759 If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
2761 The available types are represented by constants defined in the @code{gdb}
2766 Normal code breakpoint.
2769 Watchpoint breakpoint.
2771 @item BP_HARDWARE_WATCHPOINT
2772 Hardware assisted watchpoint.
2773 This value cannot be specified when creating the breakpoint.
2775 @item BP_READ_WATCHPOINT
2776 Hardware assisted read watchpoint.
2777 This value cannot be specified when creating the breakpoint.
2779 @item BP_ACCESS_WATCHPOINT
2780 Hardware assisted access watchpoint.
2781 This value cannot be specified when creating the breakpoint.
2784 The available watchpoint types represented by constants are defined in the
2785 @code{(gdb)} module:
2789 Read only watchpoint.
2792 Write only watchpoint.
2795 Read/Write watchpoint.
2800 @deffn {Scheme Procedure} breakpoint-delete! breakpoint
2801 Permanently delete @var{breakpoint}. This also invalidates the
2802 Guile @var{breakpoint} object. Any further attempt to access the
2803 object will throw an exception.
2806 @deffn {Scheme Procedure} breakpoints
2807 Return a list of all breakpoints.
2808 Each element of the list is a @code{<gdb:breakpoint>} object.
2811 @deffn {Scheme Procedure} breakpoint? object
2812 Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
2813 and @code{#f} otherwise.
2816 @deffn {Scheme Procedure} breakpoint-valid? breakpoint
2817 Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
2818 A @code{<gdb:breakpoint>} object can become invalid
2819 if the user deletes the breakpoint. In this case, the object still
2820 exists, but the underlying breakpoint does not. In the cases of
2821 watchpoint scope, the watchpoint remains valid even if execution of the
2822 inferior leaves the scope of that watchpoint.
2825 @deffn {Scheme Procedure} breakpoint-number breakpoint
2826 Return the breakpoint's number --- the identifier used by
2827 the user to manipulate the breakpoint.
2830 @deffn {Scheme Procedure} breakpoint-type breakpoint
2831 Return the breakpoint's type --- the identifier used to
2832 determine the actual breakpoint type or use-case.
2835 @deffn {Scheme Procedure} breakpoint-visible? breakpoint
2836 Return @code{#t} if the breakpoint is visible to the user
2837 when hit, or when the @samp{info breakpoints} command is run.
2838 Otherwise return @code{#f}.
2841 @deffn {Scheme Procedure} breakpoint-location breakpoint
2842 Return the location of the breakpoint, as specified by
2843 the user. It is a string. If the breakpoint does not have a location
2844 (that is, it is a watchpoint) return @code{#f}.
2847 @deffn {Scheme Procedure} breakpoint-expression breakpoint
2848 Return the breakpoint expression, as specified by the user. It is a string.
2849 If the breakpoint does not have an expression (the breakpoint is not a
2850 watchpoint) return @code{#f}.
2853 @deffn {Scheme Procedure} breakpoint-enabled? breakpoint
2854 Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
2857 @deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag
2858 Set the enabled state of @var{breakpoint} to @var{flag}.
2859 If flag is @code{#f} it is disabled, otherwise it is enabled.
2862 @deffn {Scheme Procedure} breakpoint-silent? breakpoint
2863 Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
2865 Note that a breakpoint can also be silent if it has commands and the
2866 first command is @code{silent}. This is not reported by the
2867 @code{silent} attribute.
2870 @deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag
2871 Set the silent state of @var{breakpoint} to @var{flag}.
2872 If flag is @code{#f} the breakpoint is made silent,
2873 otherwise it is made non-silent (or noisy).
2876 @deffn {Scheme Procedure} breakpoint-ignore-count breakpoint
2877 Return the ignore count for @var{breakpoint}.
2880 @deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count
2881 Set the ignore count for @var{breakpoint} to @var{count}.
2884 @deffn {Scheme Procedure} breakpoint-hit-count breakpoint
2885 Return hit count of @var{breakpoint}.
2888 @deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count
2889 Set the hit count of @var{breakpoint} to @var{count}.
2890 At present, @var{count} must be zero.
2893 @deffn {Scheme Procedure} breakpoint-thread breakpoint
2894 Return the thread-id for thread-specific breakpoint @var{breakpoint}.
2895 Return #f if @var{breakpoint} is not thread-specific.
2898 @deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f
2899 Set the thread-id for @var{breakpoint} to @var{thread-id}.
2900 If set to @code{#f}, the breakpoint is no longer thread-specific.
2903 @deffn {Scheme Procedure} breakpoint-task breakpoint
2904 If the breakpoint is Ada task-specific, return the Ada task id.
2905 If the breakpoint is not task-specific (or the underlying
2906 language is not Ada), return @code{#f}.
2909 @deffn {Scheme Procedure} set-breakpoint-task! breakpoint task
2910 Set the Ada task of @var{breakpoint} to @var{task}.
2911 If set to @code{#f}, the breakpoint is no longer task-specific.
2914 @deffn {Scheme Procedure} breakpoint-condition breakpoint
2915 Return the condition of @var{breakpoint}, as specified by the user.
2916 It is a string. If there is no condition, return @code{#f}.
2919 @deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition
2920 Set the condition of @var{breakpoint} to @var{condition},
2921 which must be a string. If set to @code{#f} then the breakpoint
2922 becomes unconditional.
2925 @deffn {Scheme Procedure} breakpoint-stop breakpoint
2926 Return the stop predicate of @var{breakpoint}.
2927 See @code{set-breakpoint-stop!} below in this section.
2930 @deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
2931 Set the stop predicate of @var{breakpoint}. The predicate
2932 @var{procedure} takes one argument: the <gdb:breakpoint> object.
2933 If this predicate is set to a procedure then it is invoked whenever
2934 the inferior reaches this breakpoint. If it returns @code{#t},
2935 or any non-@code{#f} value, then the inferior is stopped,
2936 otherwise the inferior will continue.
2938 If there are multiple breakpoints at the same location with a
2939 @code{stop} predicate, each one will be called regardless of the
2940 return status of the previous. This ensures that all @code{stop}
2941 predicates have a chance to execute at that location. In this scenario
2942 if one of the methods returns @code{#t} but the others return
2943 @code{#f}, the inferior will still be stopped.
2945 You should not alter the execution state of the inferior (i.e.@:, step,
2946 next, etc.), alter the current frame context (i.e.@:, change the current
2947 active frame), or alter, add or delete any breakpoint. As a general
2948 rule, you should not alter any data within @value{GDBN} or the inferior
2951 Example @code{stop} implementation:
2954 (define (my-stop? bkpt)
2955 (let ((int-val (parse-and-eval "foo")))
2956 (value=? int-val 3)))
2957 (define bkpt (create-breakpoint! "main.c:42"))
2958 (set-breakpoint-stop! bkpt my-stop?)
2962 @deffn {Scheme Procedure} breakpoint-commands breakpoint
2963 Return the commands attached to @var{breakpoint} as a string,
2964 or @code{#f} if there are none.
2967 @node Lazy Strings In Guile
2968 @subsubsection Guile representation of lazy strings.
2970 @cindex lazy strings in guile
2971 @tindex <gdb:lazy-string>
2973 A @dfn{lazy string} is a string whose contents is not retrieved or
2974 encoded until it is needed.
2976 A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
2977 @code{address} that points to a region of memory, an @code{encoding}
2978 that will be used to encode that region of memory, and a @code{length}
2979 to delimit the region of memory that represents the string. The
2980 difference between a @code{<gdb:lazy-string>} and a string wrapped within
2981 a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
2982 differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
2983 retrieved and encoded during printing, while a @code{<gdb:value>}
2984 wrapping a string is immediately retrieved and encoded on creation.
2986 The following lazy-string-related procedures are provided by the
2987 @code{(gdb)} module:
2989 @deffn {Scheme Procedure} lazy-string? object
2990 Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
2991 Otherwise return @code{#f}.
2994 @deffn {Scheme Procedure} lazy-string-address lazy-sring
2995 Return the address of @var{lazy-string}.
2998 @deffn {Scheme Procedure} lazy-string-length lazy-string
2999 Return the length of @var{lazy-string} in characters. If the
3000 length is -1, then the string will be fetched and encoded up to the
3001 first null of appropriate width.
3004 @deffn {Scheme Procedure} lazy-string-encoding lazy-string
3005 Return the encoding that will be applied to @var{lazy-string}
3006 when the string is printed by @value{GDBN}. If the encoding is not
3007 set, or contains an empty string, then @value{GDBN} will select the
3008 most appropriate encoding when the string is printed.
3011 @deffn {Scheme Procedure} lazy-string-type lazy-string
3012 Return the type that is represented by @var{lazy-string}'s type.
3013 For a lazy string this will always be a pointer type. To
3014 resolve this to the lazy string's character type, use @code{type-target-type}.
3015 @xref{Types In Guile}.
3018 @deffn {Scheme Procedure} lazy-string->value lazy-string
3019 Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
3020 will point to the string in memory, but will lose all the delayed
3021 retrieval, encoding and handling that @value{GDBN} applies to a
3022 @code{<gdb:lazy-string>}.
3025 @node Architectures In Guile
3026 @subsubsection Guile representation of architectures
3028 @cindex guile architectures
3031 @value{GDBN} uses architecture specific parameters and artifacts in a
3032 number of its various computations. An architecture is represented
3033 by an instance of the @code{<gdb:arch>} class.
3035 The following architecture-related procedures are provided by the
3036 @code{(gdb)} module:
3038 @deffn {Scheme Procedure} arch? object
3039 Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
3040 Otherwise return @code{#f}.
3043 @deffn {Scheme Procedure} current-arch
3044 Return the current architecture as a @code{<gdb:arch>} object.
3047 @deffn {Scheme Procedure} arch-name arch
3048 Return the name (string value) of @code{<gdb:arch>} @var{arch}.
3051 @deffn {Scheme Procedure} arch-charset arch
3052 Return name of target character set of @code{<gdb:arch>} @var{arch}.
3055 @deffn {Scheme Procedure} arch-wide-charset
3056 Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
3059 Each architecture provides a set of predefined types, obtained by
3060 the following functions.
3062 @deffn {Scheme Procedure} arch-void-type arch
3063 Return the @code{<gdb:type>} object for a @code{void} type
3064 of architecture @var{arch}.
3067 @deffn {Scheme Procedure} arch-char-type arch
3068 Return the @code{<gdb:type>} object for a @code{char} type
3069 of architecture @var{arch}.
3072 @deffn {Scheme Procedure} arch-short-type arch
3073 Return the @code{<gdb:type>} object for a @code{short} type
3074 of architecture @var{arch}.
3077 @deffn {Scheme Procedure} arch-int-type arch
3078 Return the @code{<gdb:type>} object for an @code{int} type
3079 of architecture @var{arch}.
3082 @deffn {Scheme Procedure} arch-long-type arch
3083 Return the @code{<gdb:type>} object for a @code{long} type
3084 of architecture @var{arch}.
3087 @deffn {Scheme Procedure} arch-schar-type arch
3088 Return the @code{<gdb:type>} object for a @code{signed char} type
3089 of architecture @var{arch}.
3092 @deffn {Scheme Procedure} arch-uchar-type arch
3093 Return the @code{<gdb:type>} object for an @code{unsigned char} type
3094 of architecture @var{arch}.
3097 @deffn {Scheme Procedure} arch-ushort-type arch
3098 Return the @code{<gdb:type>} object for an @code{unsigned short} type
3099 of architecture @var{arch}.
3102 @deffn {Scheme Procedure} arch-uint-type arch
3103 Return the @code{<gdb:type>} object for an @code{unsigned int} type
3104 of architecture @var{arch}.
3107 @deffn {Scheme Procedure} arch-ulong-type arch
3108 Return the @code{<gdb:type>} object for an @code{unsigned long} type
3109 of architecture @var{arch}.
3112 @deffn {Scheme Procedure} arch-float-type arch
3113 Return the @code{<gdb:type>} object for a @code{float} type
3114 of architecture @var{arch}.
3117 @deffn {Scheme Procedure} arch-double-type arch
3118 Return the @code{<gdb:type>} object for a @code{double} type
3119 of architecture @var{arch}.
3122 @deffn {Scheme Procedure} arch-longdouble-type arch
3123 Return the @code{<gdb:type>} object for a @code{long double} type
3124 of architecture @var{arch}.
3127 @deffn {Scheme Procedure} arch-bool-type arch
3128 Return the @code{<gdb:type>} object for a @code{bool} type
3129 of architecture @var{arch}.
3132 @deffn {Scheme Procedure} arch-longlong-type arch
3133 Return the @code{<gdb:type>} object for a @code{long long} type
3134 of architecture @var{arch}.
3137 @deffn {Scheme Procedure} arch-ulonglong-type arch
3138 Return the @code{<gdb:type>} object for an @code{unsigned long long} type
3139 of architecture @var{arch}.
3142 @deffn {Scheme Procedure} arch-int8-type arch
3143 Return the @code{<gdb:type>} object for an @code{int8} type
3144 of architecture @var{arch}.
3147 @deffn {Scheme Procedure} arch-uint8-type arch
3148 Return the @code{<gdb:type>} object for a @code{uint8} type
3149 of architecture @var{arch}.
3152 @deffn {Scheme Procedure} arch-int16-type arch
3153 Return the @code{<gdb:type>} object for an @code{int16} type
3154 of architecture @var{arch}.
3157 @deffn {Scheme Procedure} arch-uint16-type arch
3158 Return the @code{<gdb:type>} object for a @code{uint16} type
3159 of architecture @var{arch}.
3162 @deffn {Scheme Procedure} arch-int32-type arch
3163 Return the @code{<gdb:type>} object for an @code{int32} type
3164 of architecture @var{arch}.
3167 @deffn {Scheme Procedure} arch-uint32-type arch
3168 Return the @code{<gdb:type>} object for a @code{uint32} type
3169 of architecture @var{arch}.
3172 @deffn {Scheme Procedure} arch-int64-type arch
3173 Return the @code{<gdb:type>} object for an @code{int64} type
3174 of architecture @var{arch}.
3177 @deffn {Scheme Procedure} arch-uint64-type arch
3178 Return the @code{<gdb:type>} object for a @code{uint64} type
3179 of architecture @var{arch}.
3185 (gdb) guile (type-name (arch-uchar-type (current-arch)))
3189 @node Disassembly In Guile
3190 @subsubsection Disassembly In Guile
3192 The disassembler can be invoked from Scheme code.
3193 Furthermore, the disassembler can take a Guile port as input,
3194 allowing one to disassemble from any source, and not just target memory.
3196 @c TODO: line length
3197 @deffn {Scheme Procedure} arch-disassemble arch start-pc @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size size@r{]} @r{[}#:count count@r{]}
3198 Return a list of disassembled instructions starting from the memory
3199 address @var{start-pc}.
3201 The optional argument @var{port} specifies the input port to read bytes from.
3202 If @var{port} is @code{#f} then bytes are read from target memory.
3204 The optional argument @var{offset} specifies the address offset of the
3205 first byte in @var{port}. This is useful, for example, when @var{port}
3206 specifies a @samp{bytevector} and you want the bytevector to be disassembled
3207 as if it came from that address. The @var{start-pc} passed to the reader
3208 for @var{port} is offset by the same amount.
3212 (gdb) guile (use-modules (rnrs io ports))
3213 (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
3214 (gdb) guile (define mem (open-memory #:start pc))
3215 (gdb) guile (define bv (get-bytevector-n mem 10))
3216 (gdb) guile (define bv-port (open-bytevector-input-port bv))
3217 (gdb) guile (define arch (current-arch))
3218 (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
3219 (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
3222 The optional arguments @var{size} and
3223 @var{count} determine the number of instructions in the returned list.
3224 If either @var{size} or @var{count} is specified as zero, then
3225 no instructions are disassembled and an empty list is returned.
3226 If both the optional arguments @var{size} and @var{count} are
3227 specified, then a list of at most @var{count} disassembled instructions
3228 whose start address falls in the closed memory address interval from
3229 @var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
3230 If @var{size} is not specified, but @var{count} is specified,
3231 then @var{count} number of instructions starting from the address
3232 @var{start-pc} are returned. If @var{count} is not specified but
3233 @var{size} is specified, then all instructions whose start address
3234 falls in the closed memory address interval from @var{start-pc} to
3235 (@var{start-pc} + @var{size} - 1) are returned.
3236 If neither @var{size} nor @var{count} are specified, then a single
3237 instruction at @var{start-pc} is returned.
3239 Each element of the returned list is an alist (associative list)
3240 with the following keys:
3245 The value corresponding to this key is a Guile integer of
3246 the memory address of the instruction.
3249 The value corresponding to this key is a string value which represents
3250 the instruction with assembly language mnemonics. The assembly
3251 language flavor used is the same as that specified by the current CLI
3252 variable @code{disassembly-flavor}. @xref{Machine Code}.
3255 The value corresponding to this key is the length of the instruction in bytes.
3260 @node I/O Ports in Guile
3261 @subsubsection I/O Ports in Guile
3263 @deffn {Scheme Procedure} input-port
3264 Return @value{GDBN}'s input port as a Guile port object.
3267 @deffn {Scheme Procedure} output-port
3268 Return @value{GDBN}'s output port as a Guile port object.
3271 @deffn {Scheme Procedure} error-port
3272 Return @value{GDBN}'s error port as a Guile port object.
3275 @deffn {Scheme Procedure} stdio-port? object
3276 Return @code{#t} if @var{object} is a @value{GDBN} stdio port.
3277 Otherwise return @code{#f}.
3280 @node Memory Ports in Guile
3281 @subsubsection Memory Ports in Guile
3283 @value{GDBN} provides a @code{port} interface to target memory.
3284 This allows Guile code to read/write target memory using Guile's port and
3285 bytevector functionality. The main routine is @code{open-memory} which
3286 returns a port object. One can then read/write memory using that object.
3288 @deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
3289 Return a port object that can be used for reading and writing memory.
3290 The port will be open according to @var{mode}, which is the standard
3291 mode argument to Guile port open routines, except that it is
3292 restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For
3293 compatibility @samp{"b"} (binary) may also be present, but we ignore
3294 it: memory ports are binary only. The default is @samp{"r"},
3297 The chunk of memory that can be accessed can be bounded.
3298 If both @var{start} and @var{size} are unspecified, all of memory can be
3299 accessed. If only @var{start} is specified, all of memory from that point
3300 on can be accessed. If only @var{size} if specified, all memory in the
3301 range [0,@var{size}) can be accessed. If both are specified, all memory
3302 in the rane [@var{start},@var{start}+@var{size}) can be accessed.
3305 @deffn {Scheme Procedure} memory-port?
3306 Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
3307 Otherwise return @code{#f}.
3310 @deffn {Scheme Procedure} memory-port-range memory-port
3311 Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
3312 of two elements: @code{(start end)}. The range is @var{start} to @var{end}
3316 @deffn {Scheme Procedure} memory-port-read-buffer-size memory-port
3317 Return the size of the read buffer of @code{<gdb:memory-port>}
3321 @deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
3322 Set the size of the read buffer of @code{<gdb:memory-port>}
3323 @var{memory-port} to @var{size}. The result is unspecified.
3326 @deffn {Scheme Procedure} memory-port-write-buffer-size memory-port
3327 Return the size of the write buffer of @code{<gdb:memory-port>}
3331 @deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
3332 Set the size of the write buffer of @code{<gdb:memory-port>}
3333 @var{memory-port} to @var{size}. The result is unspecified.
3336 A memory port is closed like any other port, with @code{close-port}.
3338 Combined with Guile's @code{bytevectors}, memory ports provide a lot
3339 of utility. For example, to fill a buffer of 10 integers in memory,
3340 one can do something like the following.
3343 ;; In the program: int buffer[10];
3344 (use-modules (rnrs bytevectors))
3345 (use-modules (rnrs io ports))
3346 (define addr (parse-and-eval "buffer"))
3348 (define byte-size (* n 4))
3349 (define mem-port (open-memory #:mode "r+" #:start
3350 (value->integer addr) #:size byte-size))
3351 (define byte-vec (make-bytevector byte-size))
3354 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
3355 (put-bytevector mem-port byte-vec)
3356 (close-port mem-port)
3359 @node Iterators In Guile
3360 @subsubsection Iterators In Guile
3362 @cindex guile iterators
3363 @tindex <gdb:iterator>
3365 A simple iterator facility is provided to allow, for example,
3366 iterating over the set of program symbols without having to first
3367 construct a list of all of them. A useful contribution would be
3368 to add support for SRFI 41 and SRFI 45.
3370 @deffn {Scheme Procedure} make-iterator object progress next!
3371 A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
3372 procedure. It takes three arguments: the object to be iterated over,
3373 an object to record the progress of the iteration, and a procedure to
3374 return the next element in the iteration, or an implementation chosen value
3375 to denote the end of iteration.
3377 By convention, end of iteration is marked with @code{(end-of-iteration)},
3378 and may be tested with the @code{end-of-iteration?} predicate.
3379 The result of @code{(end-of-iteration)} is chosen so that it is not
3380 otherwise used by the @code{(gdb)} module. If you are using
3381 @code{<gdb:iterator>} in your own code it is your responsibility to
3382 maintain this invariant.
3384 A trivial example for illustration's sake:
3387 (use-modules (gdb iterator))
3388 (define my-list (list 1 2 3))
3390 (make-iterator my-list my-list
3392 (let ((l (iterator-progress iter)))
3396 (set-iterator-progress! iter (cdr l))
3400 Here is a slightly more realistic example, which computes a list of all the
3401 functions in @code{my-global-block}.
3404 (use-modules (gdb iterator))
3405 (define this-sal (find-pc-line (frame-pc (selected-frame))))
3406 (define this-symtab (sal-symtab this-sal))
3407 (define this-global-block (symtab-global-block this-symtab))
3408 (define syms-iter (make-block-symbols-iterator this-global-block))
3409 (define functions (iterator-filter symbol-function? syms-iter))
3413 @deffn {Scheme Procedure} iterator? object
3414 Return @code{#t} if @var{object} is a @code{<gdb:iterator>} object.
3415 Otherwise return @code{#f}.
3418 @deffn {Scheme Procedure} iterator-object iterator
3419 Return the first argument that was passed to @code{make-iterator}.
3420 This is the object being iterated over.
3423 @deffn {Scheme Procedure} iterator-progress iterator
3424 Return the object tracking iteration progress.
3427 @deffn {Scheme Procedure} set-iterator-progress! iterator new-value
3428 Set the object tracking iteration progress.
3431 @deffn {Scheme Procedure} iterator-next! iterator
3432 Invoke the procedure that was the third argument to @code{make-iterator},
3433 passing it one argument, the @code{<gdb:iterator>} object.
3434 The result is either the next element in the iteration, or an end
3435 marker as implemented by the @code{next!} procedure.
3436 By convention the end marker is the result of @code{(end-of-iteration)}.
3439 @deffn {Scheme Procedure} end-of-iteration
3440 Return the Scheme object that denotes end of iteration.
3443 @deffn {Scheme Procedure} end-of-iteration? object
3444 Return @code{#t} if @var{object} is the end of iteration marker.
3445 Otherwise return @code{#f}.
3448 These functions are provided by the @code{(gdb iterator)} module to
3449 assist in using iterators.
3451 @deffn {Scheme Procedure} make-list-iterator list
3452 Return a @code{<gdb:iterator>} object that will iterate over @var{list}.
3455 @deffn {Scheme Procedure} iterator->list iterator
3456 Return the elements pointed to by @var{iterator} as a list.
3459 @deffn {Scheme Procedure} iterator-map proc iterator
3460 Return the list of objects obtained by applying @var{proc} to the object
3461 pointed to by @var{iterator} and to each subsequent object.
3464 @deffn {Scheme Procedure} iterator-for-each proc iterator
3465 Apply @var{proc} to each element pointed to by @var{iterator}.
3466 The result is unspecified.
3469 @deffn {Scheme Procedure} iterator-filter pred iterator
3470 Return the list of elements pointed to by @var{iterator} that satisfy
3474 @deffn {Scheme Procedure} iterator-until pred iterator
3475 Run @var{iterator} until the result of @code{(pred element)} is true
3476 and return that as the result. Otherwise return @code{#f}.
3479 @node Guile Auto-loading
3480 @subsection Guile Auto-loading
3481 @cindex guile auto-loading
3483 When a new object file is read (for example, due to the @code{file}
3484 command, or because the inferior has loaded a shared library),
3485 @value{GDBN} will look for Guile support scripts in two ways:
3486 @file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
3487 @xref{Auto-loading extensions}.
3489 The auto-loading feature is useful for supplying application-specific
3490 debugging commands and scripts.
3492 Auto-loading can be enabled or disabled,
3493 and the list of auto-loaded scripts can be printed.
3496 @anchor{set auto-load guile-scripts}
3497 @kindex set auto-load guile-scripts
3498 @item set auto-load guile-scripts [on|off]
3499 Enable or disable the auto-loading of Guile scripts.
3501 @anchor{show auto-load guile-scripts}
3502 @kindex show auto-load guile-scripts
3503 @item show auto-load guile-scripts
3504 Show whether auto-loading of Guile scripts is enabled or disabled.
3506 @anchor{info auto-load guile-scripts}
3507 @kindex info auto-load guile-scripts
3508 @cindex print list of auto-loaded Guile scripts
3509 @item info auto-load guile-scripts [@var{regexp}]
3510 Print the list of all Guile scripts that @value{GDBN} auto-loaded.
3512 Also printed is the list of Guile scripts that were mentioned in
3513 the @code{.debug_gdb_scripts} section and were not found.
3514 This is useful because their names are not printed when @value{GDBN}
3515 tries to load them and fails. There may be many of them, and printing
3516 an error message for each one is problematic.
3518 If @var{regexp} is supplied only Guile scripts with matching names are printed.
3523 (gdb) info auto-load guile-scripts
3525 Yes scm-section-script.scm
3526 full name: /tmp/scm-section-script.scm
3527 No my-foo-pretty-printers.scm
3531 When reading an auto-loaded file, @value{GDBN} sets the
3532 @dfn{current objfile}. This is available via the @code{current-objfile}
3533 procedure (@pxref{Objfiles In Guile}). This can be useful for
3534 registering objfile-specific pretty-printers.
3537 @subsection Guile Modules
3538 @cindex guile modules
3540 @value{GDBN} comes with several modules to assist writing Guile code.
3543 * Guile Printing Module:: Building and registering pretty-printers
3544 * Guile Types Module:: Utilities for working with types
3547 @node Guile Printing Module
3548 @subsubsection Guile Printing Module
3550 This module provides a collection of utilities for working with
3556 (use-modules (gdb printing))
3559 @deffn {Scheme Procedure} prepend-pretty-printer! object printer
3560 Add @var{printer} to the front of the list of pretty-printers for
3561 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3562 or @code{#f} in which case @var{printer} is added to the global list of
3566 @deffn {Scheme Procecure} append-pretty-printer! object printer
3567 Add @var{printer} to the end of the list of pretty-printers for
3568 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3569 or @code{#f} in which case @var{printer} is added to the global list of
3573 @node Guile Types Module
3574 @subsubsection Guile Types Module
3576 This module provides a collection of utilities for working with
3577 @code{<gdb:type>} objects.
3582 (use-modules (gdb types))
3585 @deffn {Scheme Procedure} get-basic-type type
3586 Return @var{type} with const and volatile qualifiers stripped,
3587 and with typedefs and C@t{++} references converted to the underlying type.
3592 typedef const int const_int;
3594 const_int& foo_ref (foo);
3595 int main () @{ return 0; @}
3602 (gdb) guile (use-modules (gdb) (gdb types))
3603 (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
3604 (gdb) guile (get-basic-type (value-type foo-ref))
3609 @deffn {Scheme Procedure} type-has-field-deep? type field
3610 Return @code{#t} if @var{type}, assumed to be a type with fields
3611 (e.g., a structure or union), has field @var{field}.
3612 Otherwise return @code{#f}.
3613 This searches baseclasses, whereas @code{type-has-field?} does not.
3616 @deffn {Scheme Procedure} make-enum-hashtable enum-type
3617 Return a Guile hash table produced from @var{enum-type}.
3618 Elements in the hash table are referenced with @code{hashq-ref}.