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 * Objfiles In Guile:: Object files in Guile
145 * Frames In Guile:: Accessing inferior stack frames from Guile
146 * Blocks In Guile:: Accessing blocks from Guile
147 * Symbols In Guile:: Guile representation of symbols
148 * Symbol Tables In Guile:: Guile representation of symbol tables
149 * Breakpoints In Guile:: Manipulating breakpoints using Guile
150 * Lazy Strings In Guile:: Guile representation of lazy strings
151 * Architectures In Guile:: Guile representation of architectures
152 * Disassembly In Guile:: Disassembling instructions from Guile
153 * I/O Ports in Guile:: GDB I/O ports
154 * Memory Ports in Guile:: Accessing memory through ports and bytevectors
155 * Iterators In Guile:: Basic iterator support
159 @subsubsection Basic Guile
162 @cindex guile pagination
163 At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
164 @code{current-error-port} to print using @value{GDBN}'s output-paging streams.
165 A Guile program which outputs to one of these streams may have its
166 output interrupted by the user (@pxref{Screen Size}). In this
167 situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
169 Guile's history mechanism uses the same naming as @value{GDBN}'s,
170 namely the user of dollar-variables (e.g., $1, $2, etc.).
171 The results of evaluations in Guile and in GDB are counted separately,
172 @code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}.
174 @value{GDBN} is not thread-safe. If your Guile program uses multiple
175 threads, you must be careful to only call @value{GDBN}-specific
176 functions in the @value{GDBN} thread.
178 Some care must be taken when writing Guile code to run in
179 @value{GDBN}. Two things are worth noting in particular:
183 @value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
184 Guile code must not override these, or even change the options using
185 @code{sigaction}. If your program changes the handling of these
186 signals, @value{GDBN} will most likely stop working correctly. Note
187 that it is unfortunately common for GUI toolkits to install a
188 @code{SIGCHLD} handler.
191 @value{GDBN} takes care to mark its internal file descriptors as
192 close-on-exec. However, this cannot be done in a thread-safe way on
193 all platforms. Your Guile programs should be aware of this and
194 should both create new file descriptors with the close-on-exec flag
195 set and arrange to close unneeded file descriptors before starting a
199 @cindex guile gdb module
200 @value{GDBN} introduces a new Guile module, named @code{gdb}. All
201 methods and classes added by @value{GDBN} are placed in this module.
202 @value{GDBN} does not automatically @code{import} the @code{gdb} module,
203 scripts must do this themselves. There are various options for how to
204 import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
205 module is imported to the user.
206 To simplify interactive use, it is recommended to add one of the following
210 guile (use-modules (gdb))
214 guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
217 Which one to choose depends on your preference.
218 The second one adds @code{gdb:} as a prefix to all module functions
221 The rest of this manual assumes the @code{gdb} module has been imported
222 without any prefix. See the Guile documentation for @code{use-modules}
224 (@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}).
229 (gdb) guile (value-type (make-value 1))
230 ERROR: Unbound variable: value-type
231 Error while executing Scheme code.
232 (gdb) guile (use-modules (gdb))
233 (gdb) guile (value-type (make-value 1))
238 The @code{(gdb)} module provides these basic Guile functions.
241 @deffn {Scheme Procedure} execute command @r{[}#:from-tty boolean@r{]}@r{[}#:to-string boolean@r{]}
242 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
243 If a @value{GDBN} exception happens while @var{command} runs, it is
244 translated as described in
245 @ref{Guile Exception Handling,,Guile Exception Handling}.
247 @var{from-tty} specifies whether @value{GDBN} ought to consider this
248 command as having originated from the user invoking it interactively.
249 It must be a boolean value. If omitted, it defaults to @code{#f}.
251 By default, any output produced by @var{command} is sent to
252 @value{GDBN}'s standard output (and to the log output if logging is
253 turned on). If the @var{to-string} parameter is
254 @code{#t}, then output will be collected by @code{gdb.execute} and
255 returned as a string. The default is @code{#f}, in which case the
256 return value is unspecified. If @var{to-string} is @code{#t}, the
257 @value{GDBN} virtual terminal will be temporarily set to unlimited width
258 and height, and its pagination will be disabled; @pxref{Screen Size}.
261 @deffn {Scheme Procedure} history-ref number
262 Return a value from @value{GDBN}'s value history (@pxref{Value
263 History}). The @var{number} argument indicates which history element to return.
264 If @var{number} is negative, then @value{GDBN} will take its absolute value
265 and count backward from the last element (i.e., the most recent element) to
266 find the value to return. If @var{number} is zero, then @value{GDBN} will
267 return the most recent element. If the element specified by @var{number}
268 doesn't exist in the value history, a @code{gdb:error} exception will be
271 If no exception is raised, the return value is always an instance of
272 @code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
274 @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
275 @code{$1} in @value{GDBN}'s value history contains the result of evaluating
276 an expression from @value{GDBN}'s command line and @code{$1} from Guile's
277 history contains the result of evaluating an expression from Guile's
281 @deffn {Scheme Procedure} history-append! value
282 Append @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
283 value history. Return its index in the history.
285 Putting into history values returned by Guile extensions will allow
286 the user convenient access to those values via CLI history
290 @deffn {Scheme Procedure} parse-and-eval expression
291 Parse @var{expression} as an expression in the current language,
292 evaluate it, and return the result as a @code{<gdb:value>}.
293 The @var{expression} must be a string.
295 This function is useful when computing values.
296 For example, it is the only way to get the value of a
297 convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
300 @deffn {Scheme Procedure} string->argv string
301 Convert a string to a list of strings split up according to
302 @value{GDBN}'s argv parsing rules.
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 @value{GDBN} uses Guile's @dfn{smob} (small object)
337 data type for all @value{GDBN} objects
338 (@pxref{Defining New Types (Smobs),,, guile, GNU Guile Reference Manual}).
339 The smobs that @value{GDBN} provides are called @dfn{gsmobs}.
341 @deffn {Scheme Procedure} gsmob-kind gsmob
342 Return the kind of the gsmob, e.g., @code{<gdb:breakpoint>},
346 Every @code{gsmob} provides a common set of functions for extending
347 them in simple ways. Each @code{gsmob} has a list of properties,
348 initially empty. These properties are akin to Guile's object properties,
349 but are stored with the @code{gsmob}
350 (@pxref{Object Properties,,, guile, GNU Guile Reference Manual}).
351 Property names can be any @code{eq?}-able value, but it is recommended
352 that they be symbols.
354 @deffn {Scheme Procedure} set-gsmob-property! gsmob property-name value
355 Set the value of property @code{property-name} to value @code{value}.
356 The result is unspecified.
359 @deffn {Scheme Procedure} gsmob-property gsmob property-name
360 Return the value of property @code{property-name}.
361 If the property isn't present then @code{#f} is returned.
364 @deffn {Scheme Procedure} gsmob-has-property? gsmob property-name
365 Return @code{#t} if @code{gsmob} has property @code{property-name}.
366 Otherwise return @code{#f}.
369 @deffn {Scheme Procedure} gsmob-properties gsmob
370 Return an unsorted list of names of properties.
373 @value{GDBN} defines the following Scheme smobs:
377 @xref{Architectures In Guile}.
380 @xref{Blocks In Guile}.
382 @item <gdb:block-symbols-iterator>
383 @xref{Blocks In Guile}.
385 @item <gdb:breakpoint>
386 @xref{Breakpoints In Guile}.
388 @item <gdb:exception>
389 @xref{Guile Exception Handling}.
392 @xref{Frames In Guile}.
395 @xref{Iterators In Guile}.
397 @item <gdb:lazy-string>
398 @xref{Lazy Strings In Guile}.
401 @xref{Objfiles In Guile}.
403 @item <gdb:pretty-printer>
404 @xref{Guile Pretty Printing API}.
406 @item <gdb:pretty-printer-worker>
407 @xref{Guile Pretty Printing API}.
410 @xref{Symbols In Guile}.
413 @xref{Symbol Tables In Guile}.
416 @xref{Symbol Tables In Guile}.
419 @xref{Types In Guile}.
422 @xref{Types In Guile}.
425 @xref{Values From Inferior In Guile}.
428 The following gsmobs are managed internally so that the Scheme function
429 @code{eq?} may be applied to them.
434 @item <gdb:breakpoint>
442 @node Guile Exception Handling
443 @subsubsection Guile Exception Handling
444 @cindex guile exceptions
445 @cindex exceptions, guile
446 @kindex set guile print-stack
448 When executing the @code{guile} command, Guile exceptions
449 uncaught within the Guile code are translated to calls to the
450 @value{GDBN} error-reporting mechanism. If the command that called
451 @code{guile} does not handle the error, @value{GDBN} will
452 terminate it and report the error according to the setting of
453 the @code{guile print-stack} parameter.
455 The @code{guile print-stack} parameter has three settings:
462 An error message is printed containing the Guile exception name,
463 the associated value, and the Guile call stack backtrace at the
464 point where the exception was raised. Example:
467 (@value{GDBP}) guile (display foo)
468 ERROR: In procedure memoize-variable-access!:
469 ERROR: Unbound variable: foo
470 Error while executing Scheme code.
474 In addition to an error message a full backtrace is printed.
477 (@value{GDBP}) set guile print-stack full
478 (@value{GDBP}) guile (display foo)
481 157: 10 [catch #t #<catch-closure 2c76e20> ...]
483 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
485 157: 8 [catch #t #<catch-closure 2c76d20> ...]
487 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
488 ?: 6 [call-with-input-string "(display foo)" ...]
490 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
491 In ice-9/eval-string.scm:
492 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
493 37: 3 [lp (display foo)]
496 393: 1 [eval #<memoized foo> ()]
498 ?: 0 [memoize-variable-access! #<memoized foo> ...]
500 ERROR: In procedure memoize-variable-access!:
501 ERROR: Unbound variable: foo
502 Error while executing Scheme code.
506 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
507 Guile code are converted to Guile exceptions. The type of the
508 Guile exception depends on the error.
510 Guile procedures provided by @value{GDBN} can throw the standard
511 Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
513 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
514 prompt) is translated to a Guile @code{signal} exception with value
517 @value{GDBN} Guile procedures can also throw these exceptions:
521 This exception is a catch-all for errors generated from within @value{GDBN}.
523 @item gdb:invalid-object
524 This exception is thrown when accessing Guile objects that wrap underlying
525 @value{GDBN} objects have become invalid. For example, a
526 @code{<gdb:breakpoint>} object becomes invalid if the user deletes it
527 from the command line. The object still exists in Guile, but the
528 object it represents is gone. Further operations on this breakpoint
529 will throw this exception.
531 @item gdb:memory-error
532 This exception is thrown when an operation tried to access invalid
533 memory in the inferior.
535 @item gdb:pp-type-error
536 This exception is thrown when a Guile pretty-printer passes a bad object
540 The following exception-related procedures are provided by the
543 @deffn {Scheme Procedure} make-exception key args
544 Return a @code{<gdb:exception>} object given by its @var{key} and
545 @var{args}, which are the standard Guile parameters of an exception.
546 See the Guile documentation for more information (@pxref{Exceptions,,,
547 guile, GNU Guile Reference Manual}).
550 @deffn {Scheme Procedure} exception? object
551 Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
552 Otherwise return @code{#f}.
555 @deffn {Scheme Procedure} exception-key exception
556 Return the @var{args} field of a @code{<gdb:exception>} object.
559 @deffn {Scheme Procedure} exception-args exception
560 Return the @var{args} field of a @code{<gdb:exception>} object.
563 @node Values From Inferior In Guile
564 @subsubsection Values From Inferior In Guile
565 @cindex values from inferior, in guile
566 @cindex guile, working with values from inferior
568 @tindex @code{<gdb:value>}
569 @value{GDBN} provides values it obtains from the inferior program in
570 an object of type @code{<gdb:value>}. @value{GDBN} uses this object
571 for its internal bookkeeping of the inferior's values, and for
572 fetching values when necessary.
574 @value{GDBN} does not memoize @code{<gdb:value>} objects.
575 @code{make-value} always returns a fresh object.
578 (gdb) guile (eq? (make-value 1) (make-value 1))
580 (gdb) guile (equal? (make-value 1) (make-value 1))
584 A @code{<gdb:value>} that represents a function can be executed via
585 inferior function call with @code{value-call}.
586 Any arguments provided to the call must match the function's prototype,
587 and must be provided in the order specified by that prototype.
589 For example, @code{some-val} is a @code{<gdb:value>} instance
590 representing a function that takes two integers as arguments. To
591 execute this function, call it like so:
594 (define result (value-call some-val 10 20))
597 Any values returned from a function call are @code{<gdb:value>} objects.
599 Note: Unlike Python scripting in @value{GDBN},
600 inferior values that are simple scalars cannot be used directly in
601 Scheme expressions that are valid for the value's data type.
602 For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
603 And inferior values that are structures or instances of some class cannot
604 be accessed using any special syntax, instead @code{value-field} must be used.
606 The following value-related procedures are provided by the
609 @deffn {Scheme Procedure} value? object
610 Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
611 Otherwise return @code{#f}.
614 @deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]}
615 Many Scheme values can be converted directly to a @code{<gdb:value>}
616 with this procedure. If @var{type} is specified, the result is a value
617 of this type, and if @var{value} can't be represented with this type
618 an exception is thrown. Otherwise the type of the result is determined from
619 @var{value} as described below.
621 @xref{Architectures In Guile}, for a list of the builtin
622 types for an architecture.
624 Here's how Scheme values are converted when @var{type} argument to
625 @code{make-value} is not specified:
629 A Scheme boolean is converted the boolean type for the current language.
632 A Scheme integer is converted to the first of a C @code{int},
633 @code{unsigned int}, @code{long}, @code{unsigned long},
634 @code{long long} or @code{unsigned long long} type
635 for the current architecture that can represent the value.
637 If the Scheme integer cannot be represented as a target integer
638 an @code{out-of-range} exception is thrown.
641 A Scheme real is converted to the C @code{double} type for the
642 current architecture.
645 A Scheme string is converted to a string in the current target
646 language using the current target encoding.
647 Characters that cannot be represented in the current target encoding
648 are replaced with the corresponding escape sequence. This is Guile's
649 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy
650 (@pxref{Strings,,, guile, GNU Guile Reference Manual}).
652 Passing @var{type} is not supported in this case,
653 if it is provided a @code{wrong-type-arg} exception is thrown.
655 @item @code{<gdb:lazy-string>}
656 If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
657 Guile}), then the @code{lazy-string->value} procedure is called, and
660 Passing @var{type} is not supported in this case,
661 if it is provided a @code{wrong-type-arg} exception is thrown.
663 @item Scheme bytevector
664 If @var{value} is a Scheme bytevector and @var{type} is provided,
665 @var{value} must be the same size, in bytes, of values of type @var{type},
666 and the result is essentially created by using @code{memcpy}.
668 If @var{value} is a Scheme bytevector and @var{type} is not provided,
669 the result is an array of type @code{uint8} of the same length.
673 @cindex optimized out value in guile
674 @deffn {Scheme Procedure} value-optimized-out? value
675 Return @code{#t} if the compiler optimized out @var{value},
676 thus it is not available for fetching from the inferior.
677 Otherwise return @code{#f}.
680 @deffn {Scheme Procedure} value-address value
681 If @var{value} is addressable, returns a
682 @code{<gdb:value>} object representing the address.
683 Otherwise, @code{#f} is returned.
686 @deffn {Scheme Procedure} value-type value
687 Return the type of @var{value} as a @code{<gdb:type>} object
688 (@pxref{Types In Guile}).
691 @deffn {Scheme Procedure} value-dynamic-type value
692 Return the dynamic type of @var{value}. This uses C@t{++} run-time
693 type information (@acronym{RTTI}) to determine the dynamic type of the
694 value. If the value is of class type, it will return the class in
695 which the value is embedded, if any. If the value is of pointer or
696 reference to a class type, it will compute the dynamic type of the
697 referenced object, and return a pointer or reference to that type,
698 respectively. In all other cases, it will return the value's static
701 Note that this feature will only work when debugging a C@t{++} program
702 that includes @acronym{RTTI} for the object in question. Otherwise,
703 it will just return the static type of the value as in @kbd{ptype foo}.
704 @xref{Symbols, ptype}.
707 @deffn {Scheme Procedure} value-cast value type
708 Return a new instance of @code{<gdb:value>} that is the result of
709 casting @var{value} to the type described by @var{type}, which must
710 be a @code{<gdb:type>} object. If the cast cannot be performed for some
711 reason, this method throws an exception.
714 @deffn {Scheme Procedure} value-dynamic-cast value type
715 Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
716 operator were used. Consult a C@t{++} reference for details.
719 @deffn {Scheme Procedure} value-reinterpret-cast value type
720 Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
721 operator were used. Consult a C@t{++} reference for details.
724 @deffn {Scheme Procedure} value-dereference value
725 For pointer data types, this method returns a new @code{<gdb:value>} object
726 whose contents is the object pointed to by @var{value}. For example, if
727 @code{foo} is a C pointer to an @code{int}, declared in your C program as
734 then you can use the corresponding @code{<gdb:value>} to access what
735 @code{foo} points to like this:
738 (define bar (value-dereference foo))
741 The result @code{bar} will be a @code{<gdb:value>} object holding the
742 value pointed to by @code{foo}.
744 A similar function @code{value-referenced-value} exists which also
745 returns @code{<gdb:value>} objects corresonding to the values pointed to
746 by pointer values (and additionally, values referenced by reference
747 values). However, the behavior of @code{value-dereference}
748 differs from @code{value-referenced-value} by the fact that the
749 behavior of @code{value-dereference} is identical to applying the C
750 unary operator @code{*} on a given value. For example, consider a
751 reference to a pointer @code{ptrref}, declared in your C@t{++} program
759 intptr &ptrref = ptr;
762 Though @code{ptrref} is a reference value, one can apply the method
763 @code{value-dereference} to the @code{<gdb:value>} object corresponding
764 to it and obtain a @code{<gdb:value>} which is identical to that
765 corresponding to @code{val}. However, if you apply the method
766 @code{value-referenced-value}, the result would be a @code{<gdb:value>}
767 object identical to that corresponding to @code{ptr}.
770 (define scm-ptrref (parse-and-eval "ptrref"))
771 (define scm-val (value-dereference scm-ptrref))
772 (define scm-ptr (value-referenced-value scm-ptrref))
775 The @code{<gdb:value>} object @code{scm-val} is identical to that
776 corresponding to @code{val}, and @code{scm-ptr} is identical to that
777 corresponding to @code{ptr}. In general, @code{value-dereference} can
778 be applied whenever the C unary operator @code{*} can be applied
779 to the corresponding C value. For those cases where applying both
780 @code{value-dereference} and @code{value-referenced-value} is allowed,
781 the results obtained need not be identical (as we have seen in the above
782 example). The results are however identical when applied on
783 @code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
784 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
787 @deffn {Scheme Procedure} value-referenced-value value
788 For pointer or reference data types, this method returns a new
789 @code{<gdb:value>} object corresponding to the value referenced by the
790 pointer/reference value. For pointer data types,
791 @code{value-dereference} and @code{value-referenced-value} produce
792 identical results. The difference between these methods is that
793 @code{value-dereference} cannot get the values referenced by reference
794 values. For example, consider a reference to an @code{int}, declared
795 in your C@t{++} program as
803 then applying @code{value-dereference} to the @code{<gdb:value>} object
804 corresponding to @code{ref} will result in an error, while applying
805 @code{value-referenced-value} will result in a @code{<gdb:value>} object
806 identical to that corresponding to @code{val}.
809 (define scm-ref (parse-and-eval "ref"))
810 (define err-ref (value-dereference scm-ref)) ;; error
811 (define scm-val (value-referenced-value scm-ref)) ;; ok
814 The @code{<gdb:value>} object @code{scm-val} is identical to that
815 corresponding to @code{val}.
818 @deffn {Scheme Procedure} value-field value field-name
819 Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
822 @deffn {Scheme Procedure} value-subscript value index
823 Return the value of array @var{value} at index @var{index}.
824 The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
827 @deffn {Scheme Procedure} value-call value arg-list
828 Perform an inferior function call, taking @var{value} as a pointer
829 to the function to call.
830 Each element of list @var{arg-list} must be a <gdb:value> object or an object
831 that can be converted to a value.
832 The result is the value returned by the function.
835 @deffn {Scheme Procedure} value->bool value
836 Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
837 The value must be ``integer like''. Pointers are ok.
840 @deffn {Scheme Procedure} value->integer
841 Return the Scheme integer representing @code{<gdb:value>} @var{value}.
842 The value must be ``integer like''. Pointers are ok.
845 @deffn {Scheme Procedure} value->real
846 Return the Scheme real number representing @code{<gdb:value>} @var{value}.
847 The value must be a number.
850 @deffn {Scheme Procedure} value->bytevector
851 Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
852 @var{value}. No transformation, endian or otherwise, is performed.
856 @deffn {Scheme Procedure} value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
857 If @var{value>} represents a string, then this method
858 converts the contents to a Guile string. Otherwise, this method will
861 Values are interpreted as strings according to the rules of the
862 current language. If the optional length argument is given, the
863 string will be converted to that length, and will include any embedded
864 zeroes that the string may contain. Otherwise, for languages
865 where the string is zero-terminated, the entire string will be
868 For example, in C-like languages, a value is a string if it is a pointer
869 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
872 If the optional @var{encoding} argument is given, it must be a string
873 naming the encoding of the string in the @code{<gdb:value>}, such as
874 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
875 the same encodings as the corresponding argument to Guile's
876 @code{scm_from_stringn} function, and the Guile codec machinery will be used
877 to convert the string. If @var{encoding} is not given, or if
878 @var{encoding} is the empty string, then either the @code{target-charset}
879 (@pxref{Character Sets}) will be used, or a language-specific encoding
880 will be used, if the current language is able to supply one.
882 The optional @var{errors} argument is one of @code{#f}, @code{error} or
883 @code{substitute}. @code{error} and @code{substitute} must be symbols.
884 If @var{errors} is not specified, or if its value is @code{#f}, then the
885 default conversion strategy is used, which is set with the Scheme function
886 @code{set-port-conversion-strategy!}.
887 If the value is @code{'error} then an exception is thrown if there is any
888 conversion error. If the value is @code{'substitute} then any conversion
889 error is replaced with question marks.
890 @xref{Strings,,, guile, GNU Guile Reference Manual}.
892 If the optional @var{length} argument is given, the string will be
893 fetched and converted to the given length.
894 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
898 @deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]}
899 If this @code{<gdb:value>} represents a string, then this method
900 converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
901 In Guile}). Otherwise, this method will throw an exception.
903 If the optional @var{encoding} argument is given, it must be a string
904 naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
905 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
906 @var{encoding} argument is an encoding that @value{GDBN} does not
907 recognize, @value{GDBN} will raise an error.
909 When a lazy string is printed, the @value{GDBN} encoding machinery is
910 used to convert the string during printing. If the optional
911 @var{encoding} argument is not provided, or is an empty string,
912 @value{GDBN} will automatically select the encoding most suitable for
913 the string type. For further information on encoding in @value{GDBN}
914 please see @ref{Character Sets}.
916 If the optional @var{length} argument is given, the string will be
917 fetched and encoded to the length of characters specified. If
918 the @var{length} argument is not provided, the string will be fetched
919 and encoded until a null of appropriate width is found.
920 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
923 @deffn {Scheme Procedure} value-lazy? value
924 Return @code{#t} if @var{value} has not yet been fetched
926 Otherwise return @code{#f}.
927 @value{GDBN} does not fetch values until necessary, for efficiency.
931 (define myval (parse-and-eval "somevar"))
934 The value of @code{somevar} is not fetched at this time. It will be
935 fetched when the value is needed, or when the @code{fetch-lazy}
936 procedure is invoked.
939 @deffn {Scheme Procedure} make-lazy-value type address
940 Return a @code{<gdb:value>} that will be lazily fetched from the
941 target. The object of type @code{<gdb:type>} whose value to fetch is
942 specified by its @var{type} and its target memory @var{address}, which
946 @deffn {Scheme Procedure} value-fetch-lazy! value
947 If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
948 then the value is fetched from the inferior.
949 Any errors that occur in the process will produce a Guile exception.
951 If @var{value} is not a lazy value, this method has no effect.
953 The result of this function is unspecified.
956 @deffn {Scheme Procedure} value-print value
957 Return the string representation (print form) of @code{<gdb:value>}
961 @node Arithmetic In Guile
962 @subsubsection Arithmetic In Guile
964 The @code{(gdb)} module provides several functions for performing
965 arithmetic on @code{<gdb:value>} objects.
966 The arithmetic is performed as if it were done by the target,
967 and therefore has target semantics which are not necessarily
968 those of Scheme. For example operations work with a fixed precision,
969 not the arbitrary precision of Scheme.
971 Wherever a function takes an integer or pointer as an operand,
972 @value{GDBN} will convert appropriate Scheme values to perform
975 @deffn {Scheme Procedure} value-add a b
978 @deffn {Scheme Procedure} value-sub a b
981 @deffn {Scheme Procedure} value-mul a b
984 @deffn {Scheme Procedure} value-div a b
987 @deffn {Scheme Procedure} value-rem a b
990 @deffn {Scheme Procedure} value-mod a b
993 @deffn {Scheme Procedure} value-pow a b
996 @deffn {Scheme Procedure} value-not a
999 @deffn {Scheme Procedure} value-neg a
1002 @deffn {Scheme Procedure} value-pos a
1005 @deffn {Scheme Procedure} value-abs a
1008 @deffn {Scheme Procedure} value-lsh a b
1011 @deffn {Scheme Procedure} value-rsh a b
1014 @deffn {Scheme Procedure} value-min a b
1017 @deffn {Scheme Procedure} value-max a b
1020 @deffn {Scheme Procedure} value-lognot a
1023 @deffn {Scheme Procedure} value-logand a b
1026 @deffn {Scheme Procedure} value-logior a b
1029 @deffn {Scheme Procedure} value-logxor a b
1032 @deffn {Scheme Procedure} value=? a b
1035 @deffn {Scheme Procedure} value<? a b
1038 @deffn {Scheme Procedure} value<=? a b
1041 @deffn {Scheme Procedure} value>? a b
1044 @deffn {Scheme Procedure} value>=? a b
1047 Scheme does not provide a @code{not-equal} function,
1048 and thus Guile support in @value{GDBN} does not either.
1050 @node Types In Guile
1051 @subsubsection Types In Guile
1052 @cindex types in guile
1053 @cindex guile, working with types
1056 @value{GDBN} represents types from the inferior in objects of type
1059 The following type-related procedures are provided by the
1060 @code{(gdb)} module.
1062 @deffn {Scheme Procedure} type? object
1063 Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
1064 Otherwise return @code{#f}.
1067 @deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
1068 This function looks up a type by its @var{name}, which must be a string.
1070 If @var{block} is given, it is an object of type @code{<gdb:block>},
1071 and @var{name} is looked up in that scope.
1072 Otherwise, it is searched for globally.
1074 Ordinarily, this function will return an instance of @code{<gdb:type>}.
1075 If the named type cannot be found, it will throw an exception.
1078 @deffn {Scheme Procedure} type-code type
1079 Return the type code of @var{type}. The type code will be one of the
1080 @code{TYPE_CODE_} constants defined below.
1083 @deffn {Scheme Procedure} type-tag type
1084 Return the tag name of @var{type}. The tag name is the name after
1085 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1086 languages have this concept. If this type has no tag name, then
1087 @code{#f} is returned.
1090 @deffn {Scheme Procedure} type-name type
1091 Return the name of @var{type}.
1092 If this type has no name, then @code{#f} is returned.
1095 @deffn {Scheme Procedure} type-print-name type
1096 Return the print name of @var{type}.
1097 This returns something even for anonymous types.
1098 For example, for an anonymous C struct @code{"struct @{...@}"} is returned.
1101 @deffn {Scheme Procedure} type-sizeof type
1102 Return the size of this type, in target @code{char} units. Usually, a
1103 target's @code{char} type will be an 8-bit byte. However, on some
1104 unusual platforms, this type may have a different size.
1107 @deffn {Scheme Procedure} type-strip-typedefs type
1108 Return a new @code{<gdb:type>} that represents the real type of @var{type},
1109 after removing all layers of typedefs.
1112 @deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]}
1113 Return a new @code{<gdb:type>} object which represents an array of this
1114 type. If one argument is given, it is the inclusive upper bound of
1115 the array; in this case the lower bound is zero. If two arguments are
1116 given, the first argument is the lower bound of the array, and the
1117 second argument is the upper bound of the array. An array's length
1118 must not be negative, but the bounds can be.
1121 @deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]}
1122 Return a new @code{<gdb:type>} object which represents a vector of this
1123 type. If one argument is given, it is the inclusive upper bound of
1124 the vector; in this case the lower bound is zero. If two arguments are
1125 given, the first argument is the lower bound of the vector, and the
1126 second argument is the upper bound of the vector. A vector's length
1127 must not be negative, but the bounds can be.
1129 The difference between an @code{array} and a @code{vector} is that
1130 arrays behave like in C: when used in expressions they decay to a pointer
1131 to the first element whereas vectors are treated as first class values.
1134 @deffn {Scheme Procedure} type-pointer type
1135 Return a new @code{<gdb:type>} object which represents a pointer to
1139 @deffn {Scheme Procedure} type-range type
1140 Return a list of two elements: the low bound and high bound of @var{type}.
1141 If @var{type} does not have a range, an exception is thrown.
1144 @deffn {Scheme Procedure} type-reference type
1145 Return a new @code{<gdb:type>} object which represents a reference to
1149 @deffn {Scheme Procedure} type-target type
1150 Return a new @code{<gdb:type>} object which represents the target type
1153 For a pointer type, the target type is the type of the pointed-to
1154 object. For an array type (meaning C-like arrays), the target type is
1155 the type of the elements of the array. For a function or method type,
1156 the target type is the type of the return value. For a complex type,
1157 the target type is the type of the elements. For a typedef, the
1158 target type is the aliased type.
1160 If the type does not have a target, this method will throw an
1164 @deffn {Scheme Procedure} type-const type
1165 Return a new @code{<gdb:type>} object which represents a
1166 @code{const}-qualified variant of @var{type}.
1169 @deffn {Scheme Procedure} type-volatile type
1170 Return a new @code{<gdb:type>} object which represents a
1171 @code{volatile}-qualified variant of @var{type}.
1174 @deffn {Scheme Procedure} type-unqualified type
1175 Return a new @code{<gdb:type>} object which represents an unqualified
1176 variant of @var{type}. That is, the result is neither @code{const} nor
1180 @deffn {Scheme Procedure} type-num-fields
1181 Return the number of fields of @code{<gdb:type>} @var{type}.
1184 @deffn {Scheme Procedure} type-fields type
1185 Return the fields of @var{type} as a list.
1186 For structure and union types, @code{fields} has the usual meaning.
1187 Range types have two fields, the minimum and maximum values. Enum types
1188 have one field per enum constant. Function and method types have one
1189 field per parameter. The base types of C@t{++} classes are also
1190 represented as fields. If the type has no fields, or does not fit
1191 into one of these categories, an empty list will be returned.
1192 @xref{Fields of a type in Guile}.
1195 @deffn {Scheme Procedure} make-field-iterator type
1196 Return the fields of @var{type} as a <gdb:iterator> object.
1197 @xref{Iterators In Guile}.
1200 @deffn {Scheme Procedure} type-field type field-name
1201 Return field named @var{field-name} in @var{type}.
1202 The result is an object of type @code{<gdb:field>}.
1203 @xref{Fields of a type in Guile}.
1204 If the type does not have fields, or @var{field-name} is not a field
1205 of @var{type}, an exception is thrown.
1207 For example, if @code{some-type} is a @code{<gdb:type>} instance holding
1208 a structure type, you can access its @code{foo} field with:
1211 (define bar (type-field some-type "foo"))
1214 @code{bar} will be a @code{<gdb:field>} object.
1217 @deffn {Scheme Procedure} type-has-field? type name
1218 Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
1219 Otherwise return @code{#f}.
1222 Each type has a code, which indicates what category this type falls
1223 into. The available type categories are represented by constants
1224 defined in the @code{(gdb)} module:
1228 The type is a pointer.
1230 @item TYPE_CODE_ARRAY
1231 The type is an array.
1233 @item TYPE_CODE_STRUCT
1234 The type is a structure.
1236 @item TYPE_CODE_UNION
1237 The type is a union.
1239 @item TYPE_CODE_ENUM
1240 The type is an enum.
1242 @item TYPE_CODE_FLAGS
1243 A bit flags type, used for things such as status registers.
1245 @item TYPE_CODE_FUNC
1246 The type is a function.
1249 The type is an integer type.
1252 A floating point type.
1254 @item TYPE_CODE_VOID
1255 The special type @code{void}.
1260 @item TYPE_CODE_RANGE
1261 A range type, that is, an integer type with bounds.
1263 @item TYPE_CODE_STRING
1264 A string type. Note that this is only used for certain languages with
1265 language-defined string types; C strings are not represented this way.
1267 @item TYPE_CODE_BITSTRING
1268 A string of bits. It is deprecated.
1270 @item TYPE_CODE_ERROR
1271 An unknown or erroneous type.
1273 @item TYPE_CODE_METHOD
1274 A method type, as found in C@t{++} or Java.
1276 @item TYPE_CODE_METHODPTR
1277 A pointer-to-member-function.
1279 @item TYPE_CODE_MEMBERPTR
1280 A pointer-to-member.
1285 @item TYPE_CODE_CHAR
1288 @item TYPE_CODE_BOOL
1291 @item TYPE_CODE_COMPLEX
1292 A complex float type.
1294 @item TYPE_CODE_TYPEDEF
1295 A typedef to some other type.
1297 @item TYPE_CODE_NAMESPACE
1298 A C@t{++} namespace.
1300 @item TYPE_CODE_DECFLOAT
1301 A decimal floating point type.
1303 @item TYPE_CODE_INTERNAL_FUNCTION
1304 A function internal to @value{GDBN}. This is the type used to represent
1305 convenience functions (@pxref{Convenience Funs}).
1308 Further support for types is provided in the @code{(gdb types)}
1309 Guile module (@pxref{Guile Types Module}).
1311 @anchor{Fields of a type in Guile}
1312 Each field is represented as an object of type @code{<gdb:field>}.
1314 The following field-related procedures are provided by the
1315 @code{(gdb)} module:
1317 @deffn {Scheme Procedure} field? object
1318 Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
1319 Otherwise return @code{#f}.
1322 @deffn {Scheme Procedure} field-name field
1323 Return the name of the field, or @code{#f} for anonymous fields.
1326 @deffn {Scheme Procedure} field-type field
1327 Return the type of the field. This is usually an instance of
1328 @code{<gdb:type>}, but it can be @code{#f} in some situations.
1331 @deffn {Scheme Procedure} field-enumval field
1332 Return the enum value represented by @code{<gdb:field>} @var{field}.
1335 @deffn {Scheme Procedure} field-bitpos field
1336 Return the bit position of @code{<gdb:field>} @var{field}.
1337 This attribute is not available for @code{static} fields (as in
1341 @deffn {Scheme Procedure} field-bitsize field
1342 If the field is packed, or is a bitfield, return the size of
1343 @code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
1344 in which case the field's size is given by its type.
1347 @deffn {Scheme Procedure} field-artificial? field
1348 Return @code{#t} if the field is artificial, usually meaning that
1349 it was provided by the compiler and not the user.
1350 Otherwise return @code{#f}.
1353 @deffn {Scheme Procedure} field-base-class? field
1354 Return @code{#t} if the field represents a base class of a C@t{++}
1356 Otherwise return @code{#f}.
1359 @node Guile Pretty Printing API
1360 @subsubsection Guile Pretty Printing API
1361 @cindex guile pretty printing api
1363 An example output is provided (@pxref{Pretty Printing}).
1365 A pretty-printer is represented by an object of type <gdb:pretty-printer>.
1366 Pretty-printer objects are created with @code{make-pretty-printer}.
1368 The following pretty-printer-related procedures are provided by the
1369 @code{(gdb)} module:
1371 @deffn {Scheme Procedure} make-pretty-printer name lookup-function
1372 Return a @code{<gdb:pretty-printer>} object named @var{name}.
1374 @var{lookup-function} is a function of one parameter: the value to
1375 be printed. If the value is handled by this pretty-printer, then
1376 @var{lookup-function} returns an object of type
1377 <gdb:pretty-printer-worker> to perform the actual pretty-printing.
1378 Otherwise @var{lookup-function} returns @code{#f}.
1381 @deffn {Scheme Procedure} pretty-printer? object
1382 Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
1383 Otherwise return @code{#f}.
1386 @deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer
1387 Return @code{#t} if @var{pretty-printer} is enabled.
1388 Otherwise return @code{#f}.
1391 @deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag
1392 Set the enabled flag of @var{pretty-printer} to @var{flag}.
1393 The value returned in unspecified.
1396 @deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children
1397 Return an object of type @code{<gdb:pretty-printer-worker>}.
1399 This function takes three parameters:
1403 @var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
1404 front end via MI to change the formatting of the value being printed.
1405 The value must be a string or @code{#f} (meaning there is no hint).
1406 Several values for @var{display-hint}
1407 are predefined by @value{GDBN}:
1411 Indicate that the object being printed is ``array-like''. The CLI
1412 uses this to respect parameters such as @code{set print elements} and
1413 @code{set print array}.
1416 Indicate that the object being printed is ``map-like'', and that the
1417 children of this value can be assumed to alternate between keys and
1421 Indicate that the object being printed is ``string-like''. If the
1422 printer's @code{to-string} function returns a Guile string of some
1423 kind, then @value{GDBN} will call its internal language-specific
1424 string-printing function to format the string. For the CLI this means
1425 adding quotation marks, possibly escaping some characters, respecting
1426 @code{set print elements}, and the like.
1430 @var{to-string} is either a function of one parameter, the
1431 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1433 When printing from the CLI, if the @code{to-string} method exists,
1434 then @value{GDBN} will prepend its result to the values returned by
1435 @code{children}. Exactly how this formatting is done is dependent on
1436 the display hint, and may change as more hints are added. Also,
1437 depending on the print settings (@pxref{Print Settings}), the CLI may
1438 print just the result of @code{to-string} in a stack trace, omitting
1439 the result of @code{children}.
1441 If this method returns a string, it is printed verbatim.
1443 Otherwise, if this method returns an instance of @code{<gdb:value>},
1444 then @value{GDBN} prints this value. This may result in a call to
1445 another pretty-printer.
1447 If instead the method returns a Guile value which is convertible to a
1448 @code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
1449 the resulting value. Again, this may result in a call to another
1450 pretty-printer. Guile scalars (integers, floats, and booleans) and
1451 strings are convertible to @code{<gdb:value>}; other types are not.
1453 Finally, if this method returns @code{#f} then no further operations
1454 are peformed in this method and nothing is printed.
1456 If the result is not one of these types, an exception is raised.
1458 @var{to-string} may also be @code{#f} in which case it is left to
1459 @var{children} to print the value.
1462 @var{children} is either a function of one parameter, the
1463 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1465 @value{GDBN} will call this function on a pretty-printer to compute the
1466 children of the pretty-printer's value.
1468 This function must return a <gdb:iterator> object.
1469 Each item returned by the iterator must be a tuple holding
1470 two elements. The first element is the ``name'' of the child; the
1471 second element is the child's value. The value can be any Guile
1472 object which is convertible to a @value{GDBN} value.
1474 If @var{children} is @code{#f}, @value{GDBN} will act
1475 as though the value has no children.
1479 @value{GDBN} provides a function which can be used to look up the
1480 default pretty-printer for a @code{<gdb:value>}:
1482 @deffn {Scheme Procedure} default-visualizer value
1483 This function takes a @code{<gdb:value>} object as an argument. If a
1484 pretty-printer for this value exists, then it is returned. If no such
1485 printer exists, then this returns @code{#f}.
1488 @node Selecting Guile Pretty-Printers
1489 @subsubsection Selecting Guile Pretty-Printers
1490 @cindex selecting guile pretty-printers
1492 The Guile list @code{*pretty-printers*} contains a set of
1493 @code{<gdb:pretty-printer>} registered objects.
1494 Printers in this list are called @code{global}
1495 printers, they're available when debugging any inferior.
1496 In addition to this, each @code{<gdb:objfile>} object contains its
1497 own set of pretty-printers (@pxref{Objfiles In Guile}).
1499 Pretty-printer lookup is done by passing the value to be printed to the
1500 lookup function of each enabled object in turn.
1501 Lookup stops when a lookup function returns a non-@code{#f} value
1502 or when the list is exhausted.
1504 @value{GDBN} first checks the result of @code{objfile-pretty-printers}
1505 of each @code{<gdb:objfile>} in the current program space and iteratively
1506 calls each enabled lookup function in the list for that @code{<gdb:objfile>}
1507 until a non-@code{#f} object is returned.
1508 Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
1509 object or @code{#f}. Otherwise an exception is thrown.
1510 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1511 searches the global pretty-printer list, calling each enabled function
1512 until a non-@code{#f} object is returned.
1514 The order in which the objfiles are searched is not specified. For a
1515 given list, functions are always invoked from the head of the list,
1516 and iterated over sequentially until the end of the list, or a
1517 @code{<gdb:pretty-printer-worker>} object is returned.
1519 For various reasons a pretty-printer may not work.
1520 For example, the underlying data structure may have changed and
1521 the pretty-printer is out of date.
1523 The consequences of a broken pretty-printer are severe enough that
1524 @value{GDBN} provides support for enabling and disabling individual
1525 printers. For example, if @code{print frame-arguments} is on,
1526 a backtrace can become highly illegible if any argument is printed
1527 with a broken printer.
1529 Pretty-printers are enabled and disabled from Scheme by calling
1530 @code{set-pretty-printer-enabled!}.
1531 @xref{Guile Pretty Printing API}.
1533 @node Writing a Guile Pretty-Printer
1534 @subsubsection Writing a Guile Pretty-Printer
1535 @cindex writing a Guile pretty-printer
1537 A pretty-printer consists of two basic parts: a lookup function to determine
1538 if the type is supported, and the printer itself.
1540 Here is an example showing how a @code{std::string} printer might be
1541 written. @xref{Guile Pretty Printing API}, for details.
1544 (define (make-my-string-printer value)
1545 "Print a my::string string"
1546 (make-pretty-printer-worker
1549 (value-field value "_data"))
1553 And here is an example showing how a lookup function for the printer
1554 example above might be written.
1557 (define (str-lookup-function pretty-printer value)
1558 (let ((tag (type-tag (value-type value))))
1560 (string-prefix? "std::string<" tag)
1561 (make-my-string-printer value))))
1564 Then to register this printer in the global printer list:
1567 (append-pretty-printer!
1568 (make-pretty-printer "my-string" str-lookup-function))
1571 The example lookup function extracts the value's type, and attempts to
1572 match it to a type that it can pretty-print. If it is a type the
1573 printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
1574 If not, it returns @code{#f}.
1576 We recommend that you put your core pretty-printers into a Guile
1577 package. If your pretty-printers are for use with a library, we
1578 further recommend embedding a version number into the package name.
1579 This practice will enable @value{GDBN} to load multiple versions of
1580 your pretty-printers at the same time, because they will have
1583 You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
1584 can be evaluated multiple times without changing its meaning. An
1585 ideal auto-load file will consist solely of @code{import}s of your
1586 printer modules, followed by a call to a register pretty-printers with
1587 the current objfile.
1589 Taken as a whole, this approach will scale nicely to multiple
1590 inferiors, each potentially using a different library version.
1591 Embedding a version number in the Guile package name will ensure that
1592 @value{GDBN} is able to load both sets of printers simultaneously.
1593 Then, because the search for pretty-printers is done by objfile, and
1594 because your auto-loaded code took care to register your library's
1595 printers with a specific objfile, @value{GDBN} will find the correct
1596 printers for the specific version of the library used by each
1599 To continue the @code{my::string} example,
1600 this code might appear in @code{(my-project my-library v1)}:
1604 (define (register-printers objfile)
1605 (append-objfile-pretty-printer!
1606 (make-pretty-printer "my-string" str-lookup-function)))
1610 And then the corresponding contents of the auto-load file would be:
1613 (use-modules (gdb) (my-project my-library v1))
1614 (register-printers (current-objfile))
1617 The previous example illustrates a basic pretty-printer.
1618 There are a few things that can be improved on.
1619 The printer only handles one type, whereas a library typically has
1620 several types. One could install a lookup function for each desired type
1621 in the library, but one could also have a single lookup function recognize
1622 several types. The latter is the conventional way this is handled.
1623 If a pretty-printer can handle multiple data types, then its
1624 @dfn{subprinters} are the printers for the individual data types.
1626 The @code{(gdb printing)} module provides a formal way of solving this
1627 problem (@pxref{Guile Printing Module}).
1628 Here is another example that handles multiple types.
1630 These are the types we are going to pretty-print:
1633 struct foo @{ int a, b; @};
1634 struct bar @{ struct foo x, y; @};
1637 Here are the printers:
1640 (define (make-foo-printer value)
1641 "Print a foo object"
1642 (make-pretty-printer-worker
1645 (format #f "a=<~a> b=<~a>"
1646 (value-field value "a") (value-field value "a")))
1649 (define (make-bar-printer value)
1650 "Print a bar object"
1651 (make-pretty-printer-worker
1654 (format #f "x=<~a> y=<~a>"
1655 (value-field value "x") (value-field value "y")))
1659 This example doesn't need a lookup function, that is handled by the
1660 @code{(gdb printing)} module. Instead a function is provided to build up
1661 the object that handles the lookup.
1664 (use-modules (gdb printing))
1666 (define (build-pretty-printer)
1667 (let ((pp (make-pretty-printer-collection "my-library")))
1668 (pp-collection-add-tag-printer "foo" make-foo-printer)
1669 (pp-collection-add-tag-printer "bar" make-bar-printer)
1673 And here is the autoload support:
1676 (use-modules (gdb) (my-library))
1677 (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
1680 Finally, when this printer is loaded into @value{GDBN}, here is the
1681 corresponding output of @samp{info pretty-printer}:
1684 (gdb) info pretty-printer
1691 @node Objfiles In Guile
1692 @subsubsection Objfiles In Guile
1694 @cindex objfiles in guile
1695 @tindex <gdb:objfile>
1696 @value{GDBN} loads symbols for an inferior from various
1697 symbol-containing files (@pxref{Files}). These include the primary
1698 executable file, any shared libraries used by the inferior, and any
1699 separate debug info files (@pxref{Separate Debug Files}).
1700 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
1702 Each objfile is represented as an object of type @code{<gdb:objfile>}.
1704 The following objfile-related procedures are provided by the
1705 @code{(gdb)} module:
1707 @deffn {Scheme Procedure} objfile? object
1708 Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
1709 Otherwise return @code{#f}.
1712 @deffn {Scheme Procedure} objfile-valid? objfile
1713 Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
1714 A @code{<gdb:objfile>} object can become invalid
1715 if the object file it refers to is not loaded in @value{GDBN} any
1716 longer. All other @code{<gdb:objfile>} procedures will throw an exception
1717 if it is invalid at the time the procedure is called.
1720 @deffn {Scheme Procedure} objfile-filename objfile
1721 Return the file name of @var{objfile} as a string.
1724 @deffn {Scheme Procedure} objfile-pretty-printers objfile
1725 Return the list of registered @code{<gdb:pretty-printer>} objects for
1726 @var{objfile}. @xref{Guile Pretty Printing API}, for more information.
1729 @deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
1730 Set the list of registered @code{<gdb:pretty-printer>} objects for
1731 @var{objfile} to @var{printer-list}. The
1732 @var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
1733 @xref{Guile Pretty Printing API}, for more information.
1736 @deffn {Scheme Procedure} current-objfile
1737 When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
1738 sets the ``current objfile'' to the corresponding objfile. This
1739 function returns the current objfile. If there is no current objfile,
1740 this function returns @code{#f}.
1743 @deffn {Scheme Procedure} objfiles
1744 Return a list of all the objfiles in the current program space.
1747 @node Frames In Guile
1748 @subsubsection Accessing inferior stack frames from Guile.
1750 @cindex frames in guile
1751 When the debugged program stops, @value{GDBN} is able to analyze its call
1752 stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
1753 represents a frame in the stack. A @code{<gdb:frame>} object is only valid
1754 while its corresponding frame exists in the inferior's stack. If you try
1755 to use an invalid frame object, @value{GDBN} will throw a
1756 @code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
1758 Two @code{<gdb:frame>} objects can be compared for equality with the
1759 @code{equal?} function, like:
1762 (@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
1766 The following frame-related procedures are provided by the
1767 @code{(gdb)} module:
1769 @deffn {Scheme Procedure} frame? object
1770 Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
1771 Otherwise return @code{#f}.
1774 @deffn {Scheme Procedure} frame-valid? frame
1775 Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
1776 A frame object can become invalid if the frame it refers to doesn't
1777 exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
1778 an exception if the frame is invalid at the time the procedure is called.
1781 @deffn {Scheme Procedure} frame-name frame
1782 Return the function name of @var{frame}, or @code{#f} if it can't be
1786 @deffn {Scheme Procedure} frame-arch frame
1787 Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
1788 architecture. @xref{Architectures In Guile}.
1791 @deffn {Scheme Procedure} frame-type frame
1792 Return the type of @var{frame}. The value can be one of:
1796 An ordinary stack frame.
1799 A fake stack frame that was created by @value{GDBN} when performing an
1800 inferior function call.
1803 A frame representing an inlined function. The function was inlined
1804 into a @code{NORMAL_FRAME} that is older than this one.
1806 @item TAILCALL_FRAME
1807 A frame representing a tail call. @xref{Tail Call Frames}.
1809 @item SIGTRAMP_FRAME
1810 A signal trampoline frame. This is the frame created by the OS when
1811 it calls into a signal handler.
1814 A fake stack frame representing a cross-architecture call.
1816 @item SENTINEL_FRAME
1817 This is like @code{NORMAL_FRAME}, but it is only used for the
1822 @deffn {Scheme Procedure} frame-unwind-stop-reason frame
1823 Return an integer representing the reason why it's not possible to find
1824 more frames toward the outermost frame. Use
1825 @code{unwind-stop-reason-string} to convert the value returned by this
1826 function to a string. The value can be one of:
1829 @item FRAME_UNWIND_NO_REASON
1830 No particular reason (older frames should be available).
1832 @item FRAME_UNWIND_NULL_ID
1833 The previous frame's analyzer returns an invalid result.
1835 @item FRAME_UNWIND_OUTERMOST
1836 This frame is the outermost.
1838 @item FRAME_UNWIND_UNAVAILABLE
1839 Cannot unwind further, because that would require knowing the
1840 values of registers or memory that have not been collected.
1842 @item FRAME_UNWIND_INNER_ID
1843 This frame ID looks like it ought to belong to a NEXT frame,
1844 but we got it for a PREV frame. Normally, this is a sign of
1845 unwinder failure. It could also indicate stack corruption.
1847 @item FRAME_UNWIND_SAME_ID
1848 This frame has the same ID as the previous one. That means
1849 that unwinding further would almost certainly give us another
1850 frame with exactly the same ID, so break the chain. Normally,
1851 this is a sign of unwinder failure. It could also indicate
1854 @item FRAME_UNWIND_NO_SAVED_PC
1855 The frame unwinder did not find any saved PC, but we needed
1856 one to unwind further.
1858 @item FRAME_UNWIND_FIRST_ERROR
1859 Any stop reason greater or equal to this value indicates some kind
1860 of error. This special value facilitates writing code that tests
1861 for errors in unwinding in a way that will work correctly even if
1862 the list of the other values is modified in future @value{GDBN}
1863 versions. Using it, you could write:
1866 (define reason (frame-unwind-stop-readon (selected-frame)))
1867 (define reason-str (unwind-stop-reason-string reason))
1868 (if (>= reason FRAME_UNWIND_FIRST_ERROR)
1869 (format #t "An error occured: ~s\n" reason-str))
1874 @deffn {Scheme Procedure} frame-pc frame
1875 Return the frame's resume address.
1878 @deffn {Scheme Procedure} frame-block frame
1879 Return the frame's code block as a @code{<gdb:block>} object.
1880 @xref{Blocks In Guile}.
1883 @deffn {Scheme Procedure} frame-function frame
1884 Return the symbol for the function corresponding to this frame
1885 as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
1886 @xref{Symbols In Guile}.
1889 @deffn {Scheme Procedure} frame-older frame
1890 Return the frame that called @var{frame}.
1893 @deffn {Scheme Procedure} frame-newer frame
1894 Return the frame called by @var{frame}.
1897 @deffn {Scheme Procedure} frame-sal frame
1898 Return the frame's @code{<gdb:sal>} (symtab and line) object.
1899 @xref{Symbol Tables In Guile}.
1902 @deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]}
1903 Return the value of @var{variable} in @var{frame}. If the optional
1904 argument @var{block} is provided, search for the variable from that
1905 block; otherwise start at the frame's current block (which is
1906 determined by the frame's current program counter). The
1907 @var{variable} must be given as a string or a @code{<gdb:symbol>}
1908 object, and @var{block} must be a @code{<gdb:block>} object.
1911 @deffn {Scheme Procedure} frame-select frame
1912 Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
1916 @deffn {Scheme Procedure} selected-frame
1917 Return the selected frame object. @xref{Selection,,Selecting a Frame}.
1920 @deffn {Scheme Procedure} newest-frame
1921 Return the newest frame object for the selected thread.
1924 @deffn {Scheme Procedure} unwind-stop-reason-string reason
1925 Return a string explaining the reason why @value{GDBN} stopped unwinding
1926 frames, as expressed by the given @var{reason} code (an integer, see the
1927 @code{frame-unwind-stop-reason} procedure above in this section).
1930 @node Blocks In Guile
1931 @subsubsection Accessing blocks from Guile.
1933 @cindex blocks in guile
1936 In @value{GDBN}, symbols are stored in blocks. A block corresponds
1937 roughly to a scope in the source code. Blocks are organized
1938 hierarchically, and are represented individually in Guile as an object
1939 of type @code{<gdb:block>}. Blocks rely on debugging information being
1942 A frame has a block. Please see @ref{Frames In Guile}, for a more
1943 in-depth discussion of frames.
1945 The outermost block is known as the @dfn{global block}. The global
1946 block typically holds public global variables and functions.
1948 The block nested just inside the global block is the @dfn{static
1949 block}. The static block typically holds file-scoped variables and
1952 @value{GDBN} provides a method to get a block's superblock, but there
1953 is currently no way to examine the sub-blocks of a block, or to
1954 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
1957 Here is a short example that should help explain blocks:
1960 /* This is in the global block. */
1963 /* This is in the static block. */
1964 static int file_scope;
1966 /* 'function' is in the global block, and 'argument' is
1967 in a block nested inside of 'function'. */
1968 int function (int argument)
1970 /* 'local' is in a block inside 'function'. It may or may
1971 not be in the same block as 'argument'. */
1975 /* 'inner' is in a block whose superblock is the one holding
1979 /* If this call is expanded by the compiler, you may see
1980 a nested block here whose function is 'inline_function'
1981 and whose superblock is the one holding 'inner'. */
1987 The following block-related procedures are provided by the
1988 @code{(gdb)} module:
1990 @deffn {Scheme Procedure} block? object
1991 Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
1992 Otherwise return @code{#f}.
1995 @deffn {Scheme Procedure} block-valid? block
1996 Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
1997 @code{#f} if not. A block object can become invalid if the block it
1998 refers to doesn't exist anymore in the inferior. All other
1999 @code{<gdb:block>} methods will throw an exception if it is invalid at
2000 the time the procedure is called. The block's validity is also checked
2001 during iteration over symbols of the block.
2004 @deffn {Scheme Procedure} block-start block
2005 Return the start address of @code{<gdb:block>} @var{block}.
2008 @deffn {Scheme Procedure} block-end block
2009 Return the end address of @code{<gdb:block>} @var{block}.
2012 @deffn {Scheme Procedure} block-function block
2013 Return the name of @code{<gdb:block>} @var{block} represented as a
2014 @code{<gdb:symbol>} object.
2015 If the block is not named, then @code{#f} is returned.
2017 For ordinary function blocks, the superblock is the static block.
2018 However, you should note that it is possible for a function block to
2019 have a superblock that is not the static block -- for instance this
2020 happens for an inlined function.
2023 @deffn {Scheme Procedure} block-superblock block
2024 Return the block containing @code{<gdb:block>} @var{block}.
2025 If the parent block does not exist, then @code{#f} is returned.
2028 @deffn {Scheme Procedure} block-global-block block
2029 Return the global block associated with @code{<gdb:block>} @var{block}.
2032 @deffn {Scheme Procedure} block-static-block block
2033 Return the static block associated with @code{<gdb:block>} @var{block}.
2036 @deffn {Scheme Procedure} block-global? block
2037 Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
2038 Otherwise return @code{#f}.
2041 @deffn {Scheme Procedure} block-static? block
2042 Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
2043 Otherwise return @code{#f}.
2046 @deffn {Scheme Procedure} block-symbols
2047 Return a list of all symbols (as <gdb:symbol> objects) in
2048 @code{<gdb:block>} @var{block}.
2051 @deffn {Scheme Procedure} make-block-symbols-iterator block
2052 Return an object of type @code{<gdb:iterator>} that will iterate
2053 over all symbols of the block.
2054 Guile programs should not assume that a specific block object will
2055 always contain a given symbol, since changes in @value{GDBN} features and
2056 infrastructure may cause symbols move across blocks in a symbol table.
2057 @xref{Iterators In Guile}.
2060 @deffn {Scheme Procedure} block-symbols-progress?
2061 Return #t if the object is a <gdb:block-symbols-progress> object.
2062 This object would be obtained from the @code{progress} element of the
2063 @code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
2066 @deffn {Scheme Procedure} lookup-block pc
2067 Return the innermost @code{<gdb:block>} containing the given @var{pc}
2068 value. If the block cannot be found for the @var{pc} value specified,
2069 the function will return @code{#f}.
2072 @node Symbols In Guile
2073 @subsubsection Guile representation of Symbols.
2075 @cindex symbols in guile
2076 @tindex <gdb:symbol>
2078 @value{GDBN} represents every variable, function and type as an
2079 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
2080 Guile represents these symbols in @value{GDBN} with the
2081 @code{<gdb:symbol>} object.
2083 The following symbol-related procedures are provided by the
2084 @code{(gdb)} module:
2086 @deffn {Scheme Procedure} symbol? object
2087 Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
2088 Otherwise return @code{#f}.
2091 @deffn {Scheme Procedure} symbol-valid? symbol
2092 Return @code{#t} if the @code{<gdb:symbol>} object is valid,
2093 @code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
2094 the symbol it refers to does not exist in @value{GDBN} any longer.
2095 All other @code{<gdb:symbol>} procedures will throw an exception if it is
2096 invalid at the time the procedure is called.
2099 @deffn {Scheme Procedure} symbol-type symbol
2100 Return the type of @var{symbol} or @code{#f} if no type is recorded.
2101 The result is an object of type @code{<gdb:type>}.
2102 @xref{Types In Guile}.
2105 @deffn {Scheme Procedure} symbol-symtab symbol
2106 Return the symbol table in which @var{symbol} appears.
2107 The result is an object of type @code{<gdb:symtab>}.
2108 @xref{Symbol Tables In Guile}.
2111 @deffn {Scheme Procedure} symbol-line symbol
2112 Return the line number in the source code at which @var{symbol} was defined.
2116 @deffn {Scheme Procedure} symbol-name symbol
2117 Return the name of @var{symbol} as a string.
2120 @deffn {Scheme Procedure} symbol-linkage-name symbol
2121 Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
2124 @deffn {Scheme Procedure} symbol-print-name symbol
2125 Return the name of @var{symbol} in a form suitable for output. This is either
2126 @code{name} or @code{linkage_name}, depending on whether the user
2127 asked @value{GDBN} to display demangled or mangled names.
2130 @deffn {Scheme Procedure} symbol-addr-class symbol
2131 Return the address class of the symbol. This classifies how to find the value
2132 of a symbol. Each address class is a constant defined in the
2133 @code{(gdb)} module and described later in this chapter.
2136 @deffn {Scheme Procedure} symbol-needs-frame? symbol
2137 Return @code{#t} if evaluating @var{symbol}'s value requires a frame
2138 (@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
2139 local variables will require a frame, but other symbols will not.
2142 @deffn {Scheme Procedure} symbol-argument? symbol
2143 Return @code{#t} if @var{symbol} is an argument of a function.
2144 Otherwise return @code{#f}.
2147 @deffn {Scheme Procedure} symbol-constant? symbol
2148 Return @code{#t} if @var{symbol} is a constant.
2149 Otherwise return @code{#f}.
2152 @deffn {Scheme Procedure} symbol-function? symbol
2153 Return @code{#t} if @var{symbol} is a function or a method.
2154 Otherwise return @code{#f}.
2157 @deffn {Scheme Procedure} symbol-variable? symbol
2158 Return @code{#t} if @var{symbol} is a variable.
2159 Otherwise return @code{#f}.
2162 @deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]}
2163 Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
2164 functions, this computes the address of the function, cast to the
2165 appropriate type. If the symbol requires a frame in order to compute
2166 its value, then @var{frame} must be given. If @var{frame} is not
2167 given, or if @var{frame} is invalid, then an exception is thrown.
2170 @c TODO: line length
2171 @deffn {Scheme Procedure} lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]}
2172 This function searches for a symbol by name. The search scope can be
2173 restricted to the parameters defined in the optional domain and block
2176 @var{name} is the name of the symbol. It must be a string. The
2177 optional @var{block} argument restricts the search to symbols visible
2178 in that @var{block}. The @var{block} argument must be a
2179 @code{<gdb:block>} object. If omitted, the block for the current frame
2180 is used. The optional @var{domain} argument restricts
2181 the search to the domain type. The @var{domain} argument must be a
2182 domain constant defined in the @code{(gdb)} module and described later
2185 The result is a list of two elements.
2186 The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2188 If the symbol is found, the second element is @code{#t} if the symbol
2189 is a field of a method's object (e.g., @code{this} in C@t{++}),
2190 otherwise it is @code{#f}.
2191 If the symbol is not found, the second element is @code{#f}.
2194 @deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]}
2195 This function searches for a global symbol by name.
2196 The search scope can be restricted by the domain argument.
2198 @var{name} is the name of the symbol. It must be a string.
2199 The optional @var{domain} argument restricts the search to the domain type.
2200 The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
2201 module and described later in this chapter.
2203 The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2207 The available domain categories in @code{<gdb:symbol>} are represented
2208 as constants in the @code{(gdb)} module:
2211 @item SYMBOL_UNDEF_DOMAIN
2212 This is used when a domain has not been discovered or none of the
2213 following domains apply. This usually indicates an error either
2214 in the symbol information or in @value{GDBN}'s handling of symbols.
2216 @item SYMBOL_VAR_DOMAIN
2217 This domain contains variables, function names, typedef names and enum
2220 @item SYMBOL_STRUCT_DOMAIN
2221 This domain holds struct, union and enum type names.
2223 @item SYMBOL_LABEL_DOMAIN
2224 This domain contains names of labels (for gotos).
2226 @item SYMBOL_VARIABLES_DOMAIN
2227 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
2228 contains everything minus functions and types.
2230 @item SYMBOL_FUNCTION_DOMAIN
2231 This domain contains all functions.
2233 @item SYMBOL_TYPES_DOMAIN
2234 This domain contains all types.
2237 The available address class categories in @code{<gdb:symbol>} are represented
2238 as constants in the @code{gdb} module:
2241 @item SYMBOL_LOC_UNDEF
2242 If this is returned by address class, it indicates an error either in
2243 the symbol information or in @value{GDBN}'s handling of symbols.
2245 @item SYMBOL_LOC_CONST
2246 Value is constant int.
2248 @item SYMBOL_LOC_STATIC
2249 Value is at a fixed address.
2251 @item SYMBOL_LOC_REGISTER
2252 Value is in a register.
2254 @item SYMBOL_LOC_ARG
2255 Value is an argument. This value is at the offset stored within the
2256 symbol inside the frame's argument list.
2258 @item SYMBOL_LOC_REF_ARG
2259 Value address is stored in the frame's argument list. Just like
2260 @code{LOC_ARG} except that the value's address is stored at the
2261 offset, not the value itself.
2263 @item SYMBOL_LOC_REGPARM_ADDR
2264 Value is a specified register. Just like @code{LOC_REGISTER} except
2265 the register holds the address of the argument instead of the argument
2268 @item SYMBOL_LOC_LOCAL
2269 Value is a local variable.
2271 @item SYMBOL_LOC_TYPEDEF
2272 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
2275 @item SYMBOL_LOC_BLOCK
2278 @item SYMBOL_LOC_CONST_BYTES
2279 Value is a byte-sequence.
2281 @item SYMBOL_LOC_UNRESOLVED
2282 Value is at a fixed address, but the address of the variable has to be
2283 determined from the minimal symbol table whenever the variable is
2286 @item SYMBOL_LOC_OPTIMIZED_OUT
2287 The value does not actually exist in the program.
2289 @item SYMBOL_LOC_COMPUTED
2290 The value's address is a computed location.
2293 @node Symbol Tables In Guile
2294 @subsubsection Symbol table representation in Guile.
2296 @cindex symbol tables in guile
2297 @tindex <gdb:symtab>
2300 Access to symbol table data maintained by @value{GDBN} on the inferior
2301 is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
2302 @code{<gdb:symtab>}. Symbol table and line data for a frame is returned
2303 from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
2304 @xref{Frames In Guile}.
2306 For more information on @value{GDBN}'s symbol table management, see
2307 @ref{Symbols, ,Examining the Symbol Table}.
2309 The following symtab-related procedures are provided by the
2310 @code{(gdb)} module:
2312 @deffn {Scheme Procedure} symtab? object
2313 Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
2314 Otherwise return @code{#f}.
2317 @deffn {Scheme Procedure} symtab-valid? symtab
2318 Return @code{#t} if the @code{<gdb:symtab>} object is valid,
2319 @code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
2320 the symbol table it refers to no longer exists in @value{GDBN}.
2321 All other @code{<gdb:symtab>} procedures will throw an exception
2322 if it is invalid at the time the procedure is called.
2325 @deffn {Scheme Procedure} symtab-filename symtab
2326 Return the symbol table's source filename.
2329 @deffn {Scheme Procedure} symtab-fullname symtab
2330 Return the symbol table's source absolute file name.
2333 @deffn {Scheme Procedure} symtab-objfile symtab
2334 Return the symbol table's backing object file. @xref{Objfiles In Guile}.
2337 @deffn {Scheme Procedure} symtab-global-block symtab
2338 Return the global block of the underlying symbol table.
2339 @xref{Blocks In Guile}.
2342 @deffn {Scheme Procedure} symtab-static-block symtab
2343 Return the static block of the underlying symbol table.
2344 @xref{Blocks In Guile}.
2347 The following symtab-and-line-related procedures are provided by the
2348 @code{(gdb)} module:
2350 @deffn {Scheme Procedure} sal? object
2351 Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
2352 Otherwise return @code{#f}.
2355 @deffn {Scheme Procedure} sal-valid? sal
2356 Return @code{#t} if @var{sal} is valid, @code{#f} if not.
2357 A @code{<gdb:sal>} object becomes invalid when the Symbol table object
2358 it refers to no longer exists in @value{GDBN}. All other
2359 @code{<gdb:sal>} procedures will throw an exception if it is
2360 invalid at the time the procedure is called.
2363 @deffn {Scheme Procedure} sal-symtab sal
2364 Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
2367 @deffn {Scheme Procedure} sal-line sal
2368 Return the line number for @var{sal}.
2371 @deffn {Scheme Procedure} sal-pc sal
2372 Return the start of the address range occupied by code for @var{sal}.
2375 @deffn {Scheme Procedure} sal-last sal
2376 Return the end of the address range occupied by code for @var{sal}.
2379 @deffn {Scheme Procedure} find-pc-line pc
2380 Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
2381 If an invalid value of @var{pc} is passed as an argument, then the
2382 @code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
2383 object will be @code{#f} and 0 respectively.
2386 @node Breakpoints In Guile
2387 @subsubsection Manipulating breakpoints using Guile
2389 @cindex breakpoints in guile
2390 @tindex <gdb:breakpoint>
2392 Breakpoints in Guile are represented by objects of type
2393 @code{<gdb:breakpoint>}.
2395 The following breakpoint-related procedures are provided by the
2396 @code{(gdb)} module:
2398 @c TODO: line length
2399 @deffn {Scheme Procedure} create-breakpoint! location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
2400 Create a new breakpoint according to @var{spec}, a string naming the
2401 location of the breakpoint, or an expression that defines a watchpoint.
2402 The contents can be any location recognized by the @code{break} command,
2403 or in the case of a watchpoint, by the @code{watch} command.
2405 The optional @var{type} denotes the breakpoint to create.
2406 This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
2407 and defaults to @code{BP_BREAKPOINT}.
2409 The optional @var{wp-class} argument defines the class of watchpoint to
2410 create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
2411 not provided, it is assumed to be a @code{WP_WRITE} class.
2413 The optional @var{internal} argument allows the breakpoint to become
2414 invisible to the user. The breakpoint will neither be reported when
2415 created, nor will it be listed in the output from @code{info breakpoints}
2416 (but will be listed with the @code{maint info breakpoints} command).
2417 If an internal flag is not provided, the breakpoint is visible
2420 When a watchpoint is created, @value{GDBN} will try to create a
2421 hardware assisted watchpoint. If successful, the type of the watchpoint
2422 is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
2423 for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
2424 and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
2425 If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
2427 The available types are represented by constants defined in the @code{gdb}
2432 Normal code breakpoint.
2435 Watchpoint breakpoint.
2437 @item BP_HARDWARE_WATCHPOINT
2438 Hardware assisted watchpoint.
2439 This value cannot be specified when creating the breakpoint.
2441 @item BP_READ_WATCHPOINT
2442 Hardware assisted read watchpoint.
2443 This value cannot be specified when creating the breakpoint.
2445 @item BP_ACCESS_WATCHPOINT
2446 Hardware assisted access watchpoint.
2447 This value cannot be specified when creating the breakpoint.
2450 The available watchpoint types represented by constants are defined in the
2451 @code{(gdb)} module:
2455 Read only watchpoint.
2458 Write only watchpoint.
2461 Read/Write watchpoint.
2466 @deffn {Scheme Procedure} breakpoint-delete! breakpoint
2467 Permanently delete @var{breakpoint}. This also invalidates the
2468 Guile @var{breakpoint} object. Any further attempt to access the
2469 object will throw an exception.
2472 @deffn {Scheme Procedure} breakpoints
2473 Return a list of all breakpoints.
2474 Each element of the list is a @code{<gdb:breakpoint>} object.
2477 @deffn {Scheme Procedure} breakpoint? object
2478 Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
2479 and @code{#f} otherwise.
2482 @deffn {Scheme Procedure} breakpoint-valid? breakpoint
2483 Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
2484 A @code{<gdb:breakpoint>} object can become invalid
2485 if the user deletes the breakpoint. In this case, the object still
2486 exists, but the underlying breakpoint does not. In the cases of
2487 watchpoint scope, the watchpoint remains valid even if execution of the
2488 inferior leaves the scope of that watchpoint.
2491 @deffn {Scheme Procedure} breakpoint-number breakpoint
2492 Return the breakpoint's number --- the identifier used by
2493 the user to manipulate the breakpoint.
2496 @deffn {Scheme Procedure} breakpoint-type breakpoint
2497 Return the breakpoint's type --- the identifier used to
2498 determine the actual breakpoint type or use-case.
2501 @deffn {Scheme Procedure} breakpoint-visible? breakpoint
2502 Return @code{#t} if the breakpoint is visible to the user
2503 when hit, or when the @samp{info breakpoints} command is run.
2504 Otherwise return @code{#f}.
2507 @deffn {Scheme Procedure} breakpoint-location breakpoint
2508 Return the location of the breakpoint, as specified by
2509 the user. It is a string. If the breakpoint does not have a location
2510 (that is, it is a watchpoint) return @code{#f}.
2513 @deffn {Scheme Procedure} breakpoint-expression breakpoint
2514 Return the breakpoint expression, as specified by the user. It is a string.
2515 If the breakpoint does not have an expression (the breakpoint is not a
2516 watchpoint) return @code{#f}.
2519 @deffn {Scheme Procedure} breakpoint-enabled? breakpoint
2520 Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
2523 @deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag
2524 Set the enabled state of @var{breakpoint} to @var{flag}.
2525 If flag is @code{#f} it is disabled, otherwise it is enabled.
2528 @deffn {Scheme Procedure} breakpoint-silent? breakpoint
2529 Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
2531 Note that a breakpoint can also be silent if it has commands and the
2532 first command is @code{silent}. This is not reported by the
2533 @code{silent} attribute.
2536 @deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag
2537 Set the silent state of @var{breakpoint} to @var{flag}.
2538 If flag is @code{#f} the breakpoint is made silent,
2539 otherwise it is made non-silent (or noisy).
2542 @deffn {Scheme Procedure} breakpoint-ignore-count breakpoint
2543 Return the ignore count for @var{breakpoint}.
2546 @deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count
2547 Set the ignore count for @var{breakpoint} to @var{count}.
2550 @deffn {Scheme Procedure} breakpoint-hit-count breakpoint
2551 Return hit count of @var{breakpoint}.
2554 @deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count
2555 Set the hit count of @var{breakpoint} to @var{count}.
2556 At present, @var{count} must be zero.
2559 @deffn {Scheme Procedure} breakpoint-thread breakpoint
2560 Return the thread-id for thread-specific breakpoint @var{breakpoint}.
2561 Return #f if @var{breakpoint} is not thread-specific.
2564 @deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f
2565 Set the thread-id for @var{breakpoint} to @var{thread-id}.
2566 If set to @code{#f}, the breakpoint is no longer thread-specific.
2569 @deffn {Scheme Procedure} breakpoint-task breakpoint
2570 If the breakpoint is Ada task-specific, return the Ada task id.
2571 If the breakpoint is not task-specific (or the underlying
2572 language is not Ada), return @code{#f}.
2575 @deffn {Scheme Procedure} set-breakpoint-task! breakpoint task
2576 Set the Ada task of @var{breakpoint} to @var{task}.
2577 If set to @code{#f}, the breakpoint is no longer task-specific.
2580 @deffn {Scheme Procedure} breakpoint-condition breakpoint
2581 Return the condition of @var{breakpoint}, as specified by the user.
2582 It is a string. If there is no condition, return @code{#f}.
2585 @deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition
2586 Set the condition of @var{breakpoint} to @var{condition},
2587 which must be a string. If set to @code{#f} then the breakpoint
2588 becomes unconditional.
2591 @deffn {Scheme Procedure} breakpoint-stop breakpoint
2592 Return the stop predicate of @var{breakpoint}.
2593 See @code{set-breakpoint-stop!} below in this section.
2596 @deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
2597 Set the stop predicate of @var{breakpoint}. The predicate
2598 @var{procedure} takes one argument: the <gdb:breakpoint> object.
2599 If this predicate is set to a procedure then it is invoked whenever
2600 the inferior reaches this breakpoint. If it returns @code{#t},
2601 or any non-@code{#f} value, then the inferior is stopped,
2602 otherwise the inferior will continue.
2604 If there are multiple breakpoints at the same location with a
2605 @code{stop} predicate, each one will be called regardless of the
2606 return status of the previous. This ensures that all @code{stop}
2607 predicates have a chance to execute at that location. In this scenario
2608 if one of the methods returns @code{#t} but the others return
2609 @code{#f}, the inferior will still be stopped.
2611 You should not alter the execution state of the inferior (i.e.@:, step,
2612 next, etc.), alter the current frame context (i.e.@:, change the current
2613 active frame), or alter, add or delete any breakpoint. As a general
2614 rule, you should not alter any data within @value{GDBN} or the inferior
2617 Example @code{stop} implementation:
2620 (define (my-stop? bkpt)
2621 (let ((int-val (parse-and-eval "foo")))
2622 (value=? int-val 3)))
2623 (define bkpt (create-breakpoint! "main.c:42"))
2624 (set-breakpoint-stop! bkpt my-stop?)
2628 @deffn {Scheme Procedure} breakpoint-commands breakpoint
2629 Return the commands attached to @var{breakpoint} as a string,
2630 or @code{#f} if there are none.
2633 @node Lazy Strings In Guile
2634 @subsubsection Guile representation of lazy strings.
2636 @cindex lazy strings in guile
2637 @tindex <gdb:lazy-string>
2639 A @dfn{lazy string} is a string whose contents is not retrieved or
2640 encoded until it is needed.
2642 A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
2643 @code{address} that points to a region of memory, an @code{encoding}
2644 that will be used to encode that region of memory, and a @code{length}
2645 to delimit the region of memory that represents the string. The
2646 difference between a @code{<gdb:lazy-string>} and a string wrapped within
2647 a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
2648 differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
2649 retrieved and encoded during printing, while a @code{<gdb:value>}
2650 wrapping a string is immediately retrieved and encoded on creation.
2652 The following lazy-string-related procedures are provided by the
2653 @code{(gdb)} module:
2655 @deffn {Scheme Procedure} lazy-string? object
2656 Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
2657 Otherwise return @code{#f}.
2660 @deffn {Scheme Procedure} lazy-string-address lazy-sring
2661 Return the address of @var{lazy-string}.
2664 @deffn {Scheme Procedure} lazy-string-length lazy-string
2665 Return the length of @var{lazy-string} in characters. If the
2666 length is -1, then the string will be fetched and encoded up to the
2667 first null of appropriate width.
2670 @deffn {Scheme Procedure} lazy-string-encoding lazy-string
2671 Return the encoding that will be applied to @var{lazy-string}
2672 when the string is printed by @value{GDBN}. If the encoding is not
2673 set, or contains an empty string, then @value{GDBN} will select the
2674 most appropriate encoding when the string is printed.
2677 @deffn {Scheme Procedure} lazy-string-type lazy-string
2678 Return the type that is represented by @var{lazy-string}'s type.
2679 For a lazy string this will always be a pointer type. To
2680 resolve this to the lazy string's character type, use @code{type-target-type}.
2681 @xref{Types In Guile}.
2684 @deffn {Scheme Procedure} lazy-string->value lazy-string
2685 Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
2686 will point to the string in memory, but will lose all the delayed
2687 retrieval, encoding and handling that @value{GDBN} applies to a
2688 @code{<gdb:lazy-string>}.
2691 @node Architectures In Guile
2692 @subsubsection Guile representation of architectures
2694 @cindex guile architectures
2697 @value{GDBN} uses architecture specific parameters and artifacts in a
2698 number of its various computations. An architecture is represented
2699 by an instance of the @code{<gdb:arch>} class.
2701 The following architecture-related procedures are provided by the
2702 @code{(gdb)} module:
2704 @deffn {Scheme Procedure} arch? object
2705 Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
2706 Otherwise return @code{#f}.
2709 @deffn {Scheme Procedure} current-arch
2710 Return the current architecture as a @code{<gdb:arch>} object.
2713 @deffn {Scheme Procedure} arch-name arch
2714 Return the name (string value) of @code{<gdb:arch>} @var{arch}.
2717 @deffn {Scheme Procedure} arch-charset arch
2718 Return name of target character set of @code{<gdb:arch>} @var{arch}.
2721 @deffn {Scheme Procedure} arch-wide-charset
2722 Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
2725 Each architecture provides a set of predefined types, obtained by
2726 the following functions.
2728 @deffn {Scheme Procedure} arch-void-type arch
2729 Return the @code{<gdb:type>} object for a @code{void} type
2730 of architecture @var{arch}.
2733 @deffn {Scheme Procedure} arch-char-type arch
2734 Return the @code{<gdb:type>} object for a @code{char} type
2735 of architecture @var{arch}.
2738 @deffn {Scheme Procedure} arch-short-type arch
2739 Return the @code{<gdb:type>} object for a @code{short} type
2740 of architecture @var{arch}.
2743 @deffn {Scheme Procedure} arch-int-type arch
2744 Return the @code{<gdb:type>} object for an @code{int} type
2745 of architecture @var{arch}.
2748 @deffn {Scheme Procedure} arch-long-type arch
2749 Return the @code{<gdb:type>} object for a @code{long} type
2750 of architecture @var{arch}.
2753 @deffn {Scheme Procedure} arch-schar-type arch
2754 Return the @code{<gdb:type>} object for a @code{signed char} type
2755 of architecture @var{arch}.
2758 @deffn {Scheme Procedure} arch-uchar-type arch
2759 Return the @code{<gdb:type>} object for an @code{unsigned char} type
2760 of architecture @var{arch}.
2763 @deffn {Scheme Procedure} arch-ushort-type arch
2764 Return the @code{<gdb:type>} object for an @code{unsigned short} type
2765 of architecture @var{arch}.
2768 @deffn {Scheme Procedure} arch-uint-type arch
2769 Return the @code{<gdb:type>} object for an @code{unsigned int} type
2770 of architecture @var{arch}.
2773 @deffn {Scheme Procedure} arch-ulong-type arch
2774 Return the @code{<gdb:type>} object for an @code{unsigned long} type
2775 of architecture @var{arch}.
2778 @deffn {Scheme Procedure} arch-float-type arch
2779 Return the @code{<gdb:type>} object for a @code{float} type
2780 of architecture @var{arch}.
2783 @deffn {Scheme Procedure} arch-double-type arch
2784 Return the @code{<gdb:type>} object for a @code{double} type
2785 of architecture @var{arch}.
2788 @deffn {Scheme Procedure} arch-longdouble-type arch
2789 Return the @code{<gdb:type>} object for a @code{long double} type
2790 of architecture @var{arch}.
2793 @deffn {Scheme Procedure} arch-bool-type arch
2794 Return the @code{<gdb:type>} object for a @code{bool} type
2795 of architecture @var{arch}.
2798 @deffn {Scheme Procedure} arch-longlong-type arch
2799 Return the @code{<gdb:type>} object for a @code{long long} type
2800 of architecture @var{arch}.
2803 @deffn {Scheme Procedure} arch-ulonglong-type arch
2804 Return the @code{<gdb:type>} object for an @code{unsigned long long} type
2805 of architecture @var{arch}.
2808 @deffn {Scheme Procedure} arch-int8-type arch
2809 Return the @code{<gdb:type>} object for an @code{int8} type
2810 of architecture @var{arch}.
2813 @deffn {Scheme Procedure} arch-uint8-type arch
2814 Return the @code{<gdb:type>} object for a @code{uint8} type
2815 of architecture @var{arch}.
2818 @deffn {Scheme Procedure} arch-int16-type arch
2819 Return the @code{<gdb:type>} object for an @code{int16} type
2820 of architecture @var{arch}.
2823 @deffn {Scheme Procedure} arch-uint16-type arch
2824 Return the @code{<gdb:type>} object for a @code{uint16} type
2825 of architecture @var{arch}.
2828 @deffn {Scheme Procedure} arch-int32-type arch
2829 Return the @code{<gdb:type>} object for an @code{int32} type
2830 of architecture @var{arch}.
2833 @deffn {Scheme Procedure} arch-uint32-type arch
2834 Return the @code{<gdb:type>} object for a @code{uint32} type
2835 of architecture @var{arch}.
2838 @deffn {Scheme Procedure} arch-int64-type arch
2839 Return the @code{<gdb:type>} object for an @code{int64} type
2840 of architecture @var{arch}.
2843 @deffn {Scheme Procedure} arch-uint64-type arch
2844 Return the @code{<gdb:type>} object for a @code{uint64} type
2845 of architecture @var{arch}.
2851 (gdb) guile (type-name (arch-uchar-type (current-arch)))
2855 @node Disassembly In Guile
2856 @subsubsection Disassembly In Guile
2858 The disassembler can be invoked from Scheme code.
2859 Furthermore, the disassembler can take a Guile port as input,
2860 allowing one to disassemble from any source, and not just target memory.
2862 @c TODO: line length
2863 @deffn {Scheme Procedure} arch-disassemble arch start-pc @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size size@r{]} @r{[}#:count count@r{]}
2864 Return a list of disassembled instructions starting from the memory
2865 address @var{start-pc}.
2867 The optional argument @var{port} specifies the input port to read bytes from.
2868 If @var{port} is @code{#f} then bytes are read from target memory.
2870 The optional argument @var{offset} specifies the address offset of the
2871 first byte in @var{port}. This is useful, for example, when @var{port}
2872 specifies a @samp{bytevector} and you want the bytevector to be disassembled
2873 as if it came from that address. The @var{start-pc} passed to the reader
2874 for @var{port} is offset by the same amount.
2878 (gdb) guile (use-modules (rnrs io ports))
2879 (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
2880 (gdb) guile (define mem (open-memory #:start pc))
2881 (gdb) guile (define bv (get-bytevector-n mem 10))
2882 (gdb) guile (define bv-port (open-bytevector-input-port bv))
2883 (gdb) guile (define arch (current-arch))
2884 (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
2885 (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
2888 The optional arguments @var{size} and
2889 @var{count} determine the number of instructions in the returned list.
2890 If either @var{size} or @var{count} is specified as zero, then
2891 no instructions are disassembled and an empty list is returned.
2892 If both the optional arguments @var{size} and @var{count} are
2893 specified, then a list of at most @var{count} disassembled instructions
2894 whose start address falls in the closed memory address interval from
2895 @var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
2896 If @var{size} is not specified, but @var{count} is specified,
2897 then @var{count} number of instructions starting from the address
2898 @var{start-pc} are returned. If @var{count} is not specified but
2899 @var{size} is specified, then all instructions whose start address
2900 falls in the closed memory address interval from @var{start-pc} to
2901 (@var{start-pc} + @var{size} - 1) are returned.
2902 If neither @var{size} nor @var{count} are specified, then a single
2903 instruction at @var{start-pc} is returned.
2905 Each element of the returned list is an alist (associative list)
2906 with the following keys:
2911 The value corresponding to this key is a Guile integer of
2912 the memory address of the instruction.
2915 The value corresponding to this key is a string value which represents
2916 the instruction with assembly language mnemonics. The assembly
2917 language flavor used is the same as that specified by the current CLI
2918 variable @code{disassembly-flavor}. @xref{Machine Code}.
2921 The value corresponding to this key is the length of the instruction in bytes.
2926 @node I/O Ports in Guile
2927 @subsubsection I/O Ports in Guile
2929 @deffn {Scheme Procedure} input-port
2930 Return @value{GDBN}'s input port as a Guile port object.
2933 @deffn {Scheme Procedure} output-port
2934 Return @value{GDBN}'s output port as a Guile port object.
2937 @deffn {Scheme Procedure} error-port
2938 Return @value{GDBN}'s error port as a Guile port object.
2941 @deffn {Scheme Procedure} stdio-port? object
2942 Return @code{#t} if @var{object} is a @value{GDBN} stdio port.
2943 Otherwise return @code{#f}.
2946 @node Memory Ports in Guile
2947 @subsubsection Memory Ports in Guile
2949 @value{GDBN} provides a @code{port} interface to target memory.
2950 This allows Guile code to read/write target memory using Guile's port and
2951 bytevector functionality. The main routine is @code{open-memory} which
2952 returns a port object. One can then read/write memory using that object.
2954 @deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
2955 Return a port object that can be used for reading and writing memory.
2956 The port will be open according to @var{mode}, which is the standard
2957 mode argument to Guile port open routines, except that it is
2958 restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For
2959 compatibility @samp{"b"} (binary) may also be present, but we ignore
2960 it: memory ports are binary only. The default is @samp{"r"},
2963 The chunk of memory that can be accessed can be bounded.
2964 If both @var{start} and @var{size} are unspecified, all of memory can be
2965 accessed. If only @var{start} is specified, all of memory from that point
2966 on can be accessed. If only @var{size} if specified, all memory in the
2967 range [0,@var{size}) can be accessed. If both are specified, all memory
2968 in the rane [@var{start},@var{start}+@var{size}) can be accessed.
2971 @deffn {Scheme Procedure} memory-port?
2972 Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
2973 Otherwise return @code{#f}.
2976 @deffn {Scheme Procedure} memory-port-range memory-port
2977 Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
2978 of two elements: @code{(start end)}. The range is @var{start} to @var{end}
2982 @deffn {Scheme Procedure} memory-port-read-buffer-size memory-port
2983 Return the size of the read buffer of @code{<gdb:memory-port>}
2987 @deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
2988 Set the size of the read buffer of @code{<gdb:memory-port>}
2989 @var{memory-port} to @var{size}. The result is unspecified.
2992 @deffn {Scheme Procedure} memory-port-write-buffer-size memory-port
2993 Return the size of the write buffer of @code{<gdb:memory-port>}
2997 @deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
2998 Set the size of the write buffer of @code{<gdb:memory-port>}
2999 @var{memory-port} to @var{size}. The result is unspecified.
3002 A memory port is closed like any other port, with @code{close-port}.
3004 Combined with Guile's @code{bytevectors}, memory ports provide a lot
3005 of utility. For example, to fill a buffer of 10 integers in memory,
3006 one can do something like the following.
3009 ;; In the program: int buffer[10];
3010 (use-modules (rnrs bytevectors))
3011 (use-modules (rnrs io ports))
3012 (define addr (parse-and-eval "buffer"))
3014 (define byte-size (* n 4))
3015 (define mem-port (open-memory #:mode "r+" #:start
3016 (value->integer addr) #:size byte-size))
3017 (define byte-vec (make-bytevector byte-size))
3020 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
3021 (put-bytevector mem-port byte-vec)
3022 (close-port mem-port)
3025 @node Iterators In Guile
3026 @subsubsection Iterators In Guile
3028 @cindex guile iterators
3029 @tindex <gdb:iterator>
3031 A simple iterator facility is provided to allow, for example,
3032 iterating over the set of program symbols without having to first
3033 construct a list of all of them. A useful contribution would be
3034 to add support for SRFI 41 and SRFI 45.
3036 @deffn {Scheme Procedure} make-iterator object progress next!
3037 A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
3038 procedure. It takes three arguments: the object to be iterated over,
3039 an object to record the progress of the iteration, and a procedure to
3040 return the next element in the iteration, or an implementation chosen value
3041 to denote the end of iteration.
3043 By convention, end of iteration is marked with @code{(end-of-iteration)},
3044 and may be tested with the @code{end-of-iteration?} predicate.
3045 The result of @code{(end-of-iteration)} is chosen so that it is not
3046 otherwise used by the @code{(gdb)} module. If you are using
3047 @code{<gdb:iterator>} in your own code it is your responsibility to
3048 maintain this invariant.
3050 A trivial example for illustration's sake:
3053 (use-modules (gdb iterator))
3054 (define my-list (list 1 2 3))
3056 (make-iterator my-list my-list
3058 (let ((l (iterator-progress iter)))
3062 (set-iterator-progress! iter (cdr l))
3066 Here is a slightly more realistic example, which computes a list of all the
3067 functions in @code{my-global-block}.
3070 (use-modules (gdb iterator))
3071 (define this-sal (find-pc-line (frame-pc (selected-frame))))
3072 (define this-symtab (sal-symtab this-sal))
3073 (define this-global-block (symtab-global-block this-symtab))
3074 (define syms-iter (make-block-symbols-iterator this-global-block))
3075 (define functions (iterator-filter symbol-function? syms-iter))
3079 @deffn {Scheme Procedure} iterator? object
3080 Return @code{#t} if @var{object} is a @code{<gdb:iterator>} object.
3081 Otherwise return @code{#f}.
3084 @deffn {Scheme Procedure} iterator-object iterator
3085 Return the first argument that was passed to @code{make-iterator}.
3086 This is the object being iterated over.
3089 @deffn {Scheme Procedure} iterator-progress iterator
3090 Return the object tracking iteration progress.
3093 @deffn {Scheme Procedure} set-iterator-progress! iterator new-value
3094 Set the object tracking iteration progress.
3097 @deffn {Scheme Procedure} iterator-next! iterator
3098 Invoke the procedure that was the third argument to @code{make-iterator},
3099 passing it one argument, the @code{<gdb:iterator>} object.
3100 The result is either the next element in the iteration, or an end
3101 marker as implemented by the @code{next!} procedure.
3102 By convention the end marker is the result of @code{(end-of-iteration)}.
3105 @deffn {Scheme Procedure} end-of-iteration
3106 Return the Scheme object that denotes end of iteration.
3109 @deffn {Scheme Procedure} end-of-iteration? object
3110 Return @code{#t} if @var{object} is the end of iteration marker.
3111 Otherwise return @code{#f}.
3114 These functions are provided by the @code{(gdb iterator)} module to
3115 assist in using iterators.
3117 @deffn {Scheme Procedure} make-list-iterator list
3118 Return a @code{<gdb:iterator>} object that will iterate over @var{list}.
3121 @deffn {Scheme Procedure} iterator->list iterator
3122 Return the elements pointed to by @var{iterator} as a list.
3125 @deffn {Scheme Procedure} iterator-map proc iterator
3126 Return the list of objects obtained by applying @var{proc} to the object
3127 pointed to by @var{iterator} and to each subsequent object.
3130 @deffn {Scheme Procedure} iterator-for-each proc iterator
3131 Apply @var{proc} to each element pointed to by @var{iterator}.
3132 The result is unspecified.
3135 @deffn {Scheme Procedure} iterator-filter pred iterator
3136 Return the list of elements pointed to by @var{iterator} that satisfy
3140 @deffn {Scheme Procedure} iterator-until pred iterator
3141 Run @var{iterator} until the result of @code{(pred element)} is true
3142 and return that as the result. Otherwise return @code{#f}.
3145 @node Guile Auto-loading
3146 @subsection Guile Auto-loading
3147 @cindex guile auto-loading
3149 When a new object file is read (for example, due to the @code{file}
3150 command, or because the inferior has loaded a shared library),
3151 @value{GDBN} will look for Guile support scripts in two ways:
3152 @file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
3153 @xref{Auto-loading extensions}.
3155 The auto-loading feature is useful for supplying application-specific
3156 debugging commands and scripts.
3158 Auto-loading can be enabled or disabled,
3159 and the list of auto-loaded scripts can be printed.
3162 @anchor{set auto-load guile-scripts}
3163 @kindex set auto-load guile-scripts
3164 @item set auto-load guile-scripts [on|off]
3165 Enable or disable the auto-loading of Guile scripts.
3167 @anchor{show auto-load guile-scripts}
3168 @kindex show auto-load guile-scripts
3169 @item show auto-load guile-scripts
3170 Show whether auto-loading of Guile scripts is enabled or disabled.
3172 @anchor{info auto-load guile-scripts}
3173 @kindex info auto-load guile-scripts
3174 @cindex print list of auto-loaded Guile scripts
3175 @item info auto-load guile-scripts [@var{regexp}]
3176 Print the list of all Guile scripts that @value{GDBN} auto-loaded.
3178 Also printed is the list of Guile scripts that were mentioned in
3179 the @code{.debug_gdb_scripts} section and were not found.
3180 This is useful because their names are not printed when @value{GDBN}
3181 tries to load them and fails. There may be many of them, and printing
3182 an error message for each one is problematic.
3184 If @var{regexp} is supplied only Guile scripts with matching names are printed.
3189 (gdb) info auto-load guile-scripts
3191 Yes scm-section-script.scm
3192 full name: /tmp/scm-section-script.scm
3193 No my-foo-pretty-printers.scm
3197 When reading an auto-loaded file, @value{GDBN} sets the
3198 @dfn{current objfile}. This is available via the @code{current-objfile}
3199 procedure (@pxref{Objfiles In Guile}). This can be useful for
3200 registering objfile-specific pretty-printers.
3203 @subsection Guile Modules
3204 @cindex guile modules
3206 @value{GDBN} comes with several modules to assist writing Guile code.
3209 * Guile Printing Module:: Building and registering pretty-printers
3210 * Guile Types Module:: Utilities for working with types
3213 @node Guile Printing Module
3214 @subsubsection Guile Printing Module
3216 This module provides a collection of utilities for working with
3222 (use-modules (gdb printing))
3225 @deffn {Scheme Procedure} prepend-pretty-printer! object printer
3226 Add @var{printer} to the front of the list of pretty-printers for
3227 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3228 or @code{#f} in which case @var{printer} is added to the global list of
3232 @deffn {Scheme Procecure} append-pretty-printer! object printer
3233 Add @var{printer} to the end of the list of pretty-printers for
3234 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3235 or @code{#f} in which case @var{printer} is added to the global list of
3239 @node Guile Types Module
3240 @subsubsection Guile Types Module
3242 This module provides a collection of utilities for working with
3243 @code{<gdb:type>} objects.
3248 (use-modules (gdb types))
3251 @deffn {Scheme Procedure} get-basic-type type
3252 Return @var{type} with const and volatile qualifiers stripped,
3253 and with typedefs and C@t{++} references converted to the underlying type.
3258 typedef const int const_int;
3260 const_int& foo_ref (foo);
3261 int main () @{ return 0; @}
3268 (gdb) guile (use-modules (gdb) (gdb types))
3269 (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
3270 (gdb) guile (get-basic-type (value-type foo-ref))
3275 @deffn {Scheme Procedure} type-has-field-deep? type field
3276 Return @code{#t} if @var{type}, assumed to be a type with fields
3277 (e.g., a structure or union), has field @var{field}.
3278 Otherwise return @code{#f}.
3279 This searches baseclasses, whereas @code{type-has-field?} does not.
3282 @deffn {Scheme Procedure} make-enum-hashtable enum-type
3283 Return a Guile hash table produced from @var{enum-type}.
3284 Elements in the hash table are referenced with @code{hashq-ref}.