1 @c Copyright (C) 2008--2022 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 3.0, 2.2, or 2.0.
43 @cindex guile scripts directory
44 Guile scripts used by @value{GDBN} should be installed in
45 @file{@var{data-directory}/guile}, where @var{data-directory} is
46 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
47 This directory, known as the @dfn{guile directory},
48 is automatically added to the Guile Search Path in order to allow
49 the Guile interpreter to locate all scripts installed at this location.
52 @subsection Guile Commands
53 @cindex guile commands
54 @cindex commands to access guile
56 @value{GDBN} provides two commands for accessing the Guile interpreter:
63 The @code{guile-repl} command can be used to start an interactive
64 Guile prompt or @dfn{repl}. To return to @value{GDBN},
65 type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on
66 an empty prompt). These commands do not take any arguments.
70 @item guile @r{[}@var{scheme-expression}@r{]}
71 @itemx gu @r{[}@var{scheme-expression}@r{]}
72 The @code{guile} command can be used to evaluate a Scheme expression.
74 If given an argument, @value{GDBN} will pass the argument to the Guile
75 interpreter for evaluation.
78 (@value{GDBP}) guile (display (+ 20 3)) (newline)
82 The result of the Scheme expression is displayed using normal Guile rules.
85 (@value{GDBP}) guile (+ 20 3)
89 If you do not provide an argument to @code{guile}, it will act as a
90 multi-line command, like @code{define}. In this case, the Guile
91 script is made up of subsequent command lines, given after the
92 @code{guile} command. This command list is terminated using a line
93 containing @code{end}. For example:
104 It is also possible to execute a Guile script from the @value{GDBN}
108 @item source @file{script-name}
109 The script name must end with @samp{.scm} and @value{GDBN} must be configured
110 to recognize the script language based on filename extension using
111 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
113 @item guile (load "script-name")
114 This method uses the @code{load} Guile function.
115 It takes a string argument that is the name of the script to load.
116 See the Guile documentation for a description of this function.
117 (@pxref{Loading,,, guile, GNU Guile Reference Manual}).
121 @subsection Guile API
123 @cindex programming in guile
125 You can get quick online help for @value{GDBN}'s Guile API by issuing
126 the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help}
127 from an interactive Guile session. Furthermore, most Guile procedures
128 provided by @value{GDBN} have doc strings which can be obtained with
129 @kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}}
130 from the Guile interactive prompt.
133 * Basic Guile:: Basic Guile Functions
134 * Guile Configuration:: Guile configuration variables
135 * GDB Scheme Data Types:: Scheme representations of GDB objects
136 * Guile Exception Handling:: How Guile exceptions are translated
137 * Values From Inferior In Guile:: Guile representation of values
138 * Arithmetic In Guile:: Arithmetic in Guile
139 * Types In Guile:: Guile representation of types
140 * Guile Pretty Printing API:: Pretty-printing values with Guile
141 * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
142 * Writing a Guile Pretty-Printer:: Writing a pretty-printer
143 * Commands In Guile:: Implementing new commands in Guile
144 * Parameters In Guile:: Adding new @value{GDBN} parameters
145 * Progspaces In Guile:: Program spaces
146 * Objfiles In Guile:: Object files in Guile
147 * Frames In Guile:: Accessing inferior stack frames from Guile
148 * Blocks In Guile:: Accessing blocks from Guile
149 * Symbols In Guile:: Guile representation of symbols
150 * Symbol Tables In Guile:: Guile representation of symbol tables
151 * Breakpoints In Guile:: Manipulating breakpoints using Guile
152 * Lazy Strings In Guile:: Guile representation of lazy strings
153 * Architectures In Guile:: Guile representation of architectures
154 * Disassembly In Guile:: Disassembling instructions from Guile
155 * I/O Ports in Guile:: GDB I/O ports
156 * Memory Ports in Guile:: Accessing memory through ports and bytevectors
157 * Iterators In Guile:: Basic iterator support
161 @subsubsection Basic Guile
164 @cindex guile pagination
165 At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
166 @code{current-error-port} to print using @value{GDBN}'s output-paging streams.
167 A Guile program which outputs to one of these streams may have its
168 output interrupted by the user (@pxref{Screen Size}). In this
169 situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
171 Guile's history mechanism uses the same naming as @value{GDBN}'s,
172 namely the user of dollar-variables (e.g., $1, $2, etc.).
173 The results of evaluations in Guile and in GDB are counted separately,
174 @code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}.
176 @value{GDBN} is not thread-safe. If your Guile program uses multiple
177 threads, you must be careful to only call @value{GDBN}-specific
178 functions in the @value{GDBN} thread.
180 Some care must be taken when writing Guile code to run in
181 @value{GDBN}. Two things are worth noting in particular:
185 @value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
186 Guile code must not override these, or even change the options using
187 @code{sigaction}. If your program changes the handling of these
188 signals, @value{GDBN} will most likely stop working correctly. Note
189 that it is unfortunately common for GUI toolkits to install a
190 @code{SIGCHLD} handler.
193 @value{GDBN} takes care to mark its internal file descriptors as
194 close-on-exec. However, this cannot be done in a thread-safe way on
195 all platforms. Your Guile programs should be aware of this and
196 should both create new file descriptors with the close-on-exec flag
197 set and arrange to close unneeded file descriptors before starting a
201 @cindex guile gdb module
202 @value{GDBN} introduces a new Guile module, named @code{gdb}. All
203 methods and classes added by @value{GDBN} are placed in this module.
204 @value{GDBN} does not automatically @code{import} the @code{gdb} module,
205 scripts must do this themselves. There are various options for how to
206 import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
207 module is imported to the user.
208 To simplify interactive use, it is recommended to add one of the following
212 guile (use-modules (gdb))
216 guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
219 Which one to choose depends on your preference.
220 The second one adds @code{gdb:} as a prefix to all module functions
223 The rest of this manual assumes the @code{gdb} module has been imported
224 without any prefix. See the Guile documentation for @code{use-modules}
226 (@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}).
231 (gdb) guile (value-type (make-value 1))
232 ERROR: Unbound variable: value-type
233 Error while executing Scheme code.
234 (gdb) guile (use-modules (gdb))
235 (gdb) guile (value-type (make-value 1))
240 The @code{(gdb)} module provides these basic Guile functions.
242 @deffn {Scheme Procedure} execute command @w{@r{[}#:from-tty boolean@r{]}} @
243 @w{@r{[}#:to-string boolean@r{]}}
244 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
245 If a @value{GDBN} exception happens while @var{command} runs, it is
246 translated as described in
247 @ref{Guile Exception Handling,,Guile Exception Handling}.
249 @var{from-tty} specifies whether @value{GDBN} ought to consider this
250 command as having originated from the user invoking it interactively.
251 It must be a boolean value. If omitted, it defaults to @code{#f}.
253 By default, any output produced by @var{command} is sent to
254 @value{GDBN}'s standard output (and to the log output if logging is
255 turned on). If the @var{to-string} parameter is
256 @code{#t}, then output will be collected by @code{execute} and
257 returned as a string. The default is @code{#f}, in which case the
258 return value is unspecified. If @var{to-string} is @code{#t}, the
259 @value{GDBN} virtual terminal will be temporarily set to unlimited width
260 and height, and its pagination will be disabled; @pxref{Screen Size}.
263 @deffn {Scheme Procedure} history-ref number
264 Return a value from @value{GDBN}'s value history (@pxref{Value
265 History}). The @var{number} argument indicates which history element to return.
266 If @var{number} is negative, then @value{GDBN} will take its absolute value
267 and count backward from the last element (i.e., the most recent element) to
268 find the value to return. If @var{number} is zero, then @value{GDBN} will
269 return the most recent element. If the element specified by @var{number}
270 doesn't exist in the value history, a @code{gdb:error} exception will be
273 If no exception is raised, the return value is always an instance of
274 @code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
276 @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
277 @code{$1} in @value{GDBN}'s value history contains the result of evaluating
278 an expression from @value{GDBN}'s command line and @code{$1} from Guile's
279 history contains the result of evaluating an expression from Guile's
283 @deffn {Scheme Procedure} history-append! value
284 Append @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
285 value history. Return its index in the history.
287 Putting into history values returned by Guile extensions will allow
288 the user convenient access to those values via CLI history
292 @deffn {Scheme Procedure} parse-and-eval expression
293 Parse @var{expression} as an expression in the current language,
294 evaluate it, and return the result as a @code{<gdb:value>}.
295 The @var{expression} must be a string.
297 This function can be useful when implementing a new command
298 (@pxref{Commands In Guile}), as it provides a way to parse the
299 command's arguments as an expression.
300 It is also is useful when computing values.
301 For example, it is the only way to get the value of a
302 convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
305 @node Guile Configuration
306 @subsubsection Guile Configuration
307 @cindex guile configuration
309 @value{GDBN} provides these Scheme functions to access various configuration
312 @deffn {Scheme Procedure} data-directory
313 Return a string containing @value{GDBN}'s data directory.
314 This directory contains @value{GDBN}'s ancillary files.
317 @deffn {Scheme Procedure} guile-data-directory
318 Return a string containing @value{GDBN}'s Guile data directory.
319 This directory contains the Guile modules provided by @value{GDBN}.
322 @deffn {Scheme Procedure} gdb-version
323 Return a string containing the @value{GDBN} version.
326 @deffn {Scheme Procedure} host-config
327 Return a string containing the host configuration.
328 This is the string passed to @code{--host} when @value{GDBN} was configured.
331 @deffn {Scheme Procedure} target-config
332 Return a string containing the target configuration.
333 This is the string passed to @code{--target} when @value{GDBN} was configured.
336 @node GDB Scheme Data Types
337 @subsubsection GDB Scheme Data Types
340 The values exposed by @value{GDBN} to Guile are known as
341 @dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN}
342 object, and each is disjoint from all other types known to Guile.
344 @deffn {Scheme Procedure} gdb-object-kind object
345 Return the kind of the @value{GDBN} object, e.g., @code{<gdb:breakpoint>},
349 @value{GDBN} defines the following object types:
353 @xref{Architectures In Guile}.
356 @xref{Blocks In Guile}.
358 @item <gdb:block-symbols-iterator>
359 @xref{Blocks In Guile}.
361 @item <gdb:breakpoint>
362 @xref{Breakpoints In Guile}.
365 @xref{Commands In Guile}.
367 @item <gdb:exception>
368 @xref{Guile Exception Handling}.
371 @xref{Frames In Guile}.
374 @xref{Iterators In Guile}.
376 @item <gdb:lazy-string>
377 @xref{Lazy Strings In Guile}.
380 @xref{Objfiles In Guile}.
382 @item <gdb:parameter>
383 @xref{Parameters In Guile}.
385 @item <gdb:pretty-printer>
386 @xref{Guile Pretty Printing API}.
388 @item <gdb:pretty-printer-worker>
389 @xref{Guile Pretty Printing API}.
391 @item <gdb:progspace>
392 @xref{Progspaces In Guile}.
395 @xref{Symbols In Guile}.
398 @xref{Symbol Tables In Guile}.
401 @xref{Symbol Tables In Guile}.
404 @xref{Types In Guile}.
407 @xref{Types In Guile}.
410 @xref{Values From Inferior In Guile}.
413 The following @value{GDBN} objects are managed internally so that the
414 Scheme function @code{eq?} may be applied to them.
419 @item <gdb:breakpoint>
422 @item <gdb:progspace>
428 @node Guile Exception Handling
429 @subsubsection Guile Exception Handling
430 @cindex guile exceptions
431 @cindex exceptions, guile
432 @kindex set guile print-stack
434 When executing the @code{guile} command, Guile exceptions
435 uncaught within the Guile code are translated to calls to the
436 @value{GDBN} error-reporting mechanism. If the command that called
437 @code{guile} does not handle the error, @value{GDBN} will
438 terminate it and report the error according to the setting of
439 the @code{guile print-stack} parameter.
441 The @code{guile print-stack} parameter has three settings:
448 An error message is printed containing the Guile exception name,
449 the associated value, and the Guile call stack backtrace at the
450 point where the exception was raised. Example:
453 (@value{GDBP}) guile (display foo)
454 ERROR: In procedure memoize-variable-access!:
455 ERROR: Unbound variable: foo
456 Error while executing Scheme code.
460 In addition to an error message a full backtrace is printed.
463 (@value{GDBP}) set guile print-stack full
464 (@value{GDBP}) guile (display foo)
467 157: 10 [catch #t #<catch-closure 2c76e20> ...]
469 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
471 157: 8 [catch #t #<catch-closure 2c76d20> ...]
473 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
474 ?: 6 [call-with-input-string "(display foo)" ...]
476 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
477 In ice-9/eval-string.scm:
478 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
479 37: 3 [lp (display foo)]
482 393: 1 [eval #<memoized foo> ()]
484 ?: 0 [memoize-variable-access! #<memoized foo> ...]
486 ERROR: In procedure memoize-variable-access!:
487 ERROR: Unbound variable: foo
488 Error while executing Scheme code.
492 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
493 Guile code are converted to Guile exceptions. The type of the
494 Guile exception depends on the error.
496 Guile procedures provided by @value{GDBN} can throw the standard
497 Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
499 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
500 prompt) is translated to a Guile @code{signal} exception with value
503 @value{GDBN} Guile procedures can also throw these exceptions:
507 This exception is a catch-all for errors generated from within @value{GDBN}.
509 @item gdb:invalid-object
510 This exception is thrown when accessing Guile objects that wrap underlying
511 @value{GDBN} objects have become invalid. For example, a
512 @code{<gdb:breakpoint>} object becomes invalid if the user deletes it
513 from the command line. The object still exists in Guile, but the
514 object it represents is gone. Further operations on this breakpoint
515 will throw this exception.
517 @item gdb:memory-error
518 This exception is thrown when an operation tried to access invalid
519 memory in the inferior.
521 @item gdb:pp-type-error
522 This exception is thrown when a Guile pretty-printer passes a bad object
526 The following exception-related procedures are provided by the
529 @deffn {Scheme Procedure} make-exception key args
530 Return a @code{<gdb:exception>} object given by its @var{key} and
531 @var{args}, which are the standard Guile parameters of an exception.
532 See the Guile documentation for more information (@pxref{Exceptions,,,
533 guile, GNU Guile Reference Manual}).
536 @deffn {Scheme Procedure} exception? object
537 Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
538 Otherwise return @code{#f}.
541 @deffn {Scheme Procedure} exception-key exception
542 Return the @var{args} field of a @code{<gdb:exception>} object.
545 @deffn {Scheme Procedure} exception-args exception
546 Return the @var{args} field of a @code{<gdb:exception>} object.
549 @node Values From Inferior In Guile
550 @subsubsection Values From Inferior In Guile
551 @cindex values from inferior, in guile
552 @cindex guile, working with values from inferior
554 @tindex @code{<gdb:value>}
555 @value{GDBN} provides values it obtains from the inferior program in
556 an object of type @code{<gdb:value>}. @value{GDBN} uses this object
557 for its internal bookkeeping of the inferior's values, and for
558 fetching values when necessary.
560 @value{GDBN} does not memoize @code{<gdb:value>} objects.
561 @code{make-value} always returns a fresh object.
564 (gdb) guile (eq? (make-value 1) (make-value 1))
566 (gdb) guile (equal? (make-value 1) (make-value 1))
570 A @code{<gdb:value>} that represents a function can be executed via
571 inferior function call with @code{value-call}.
572 Any arguments provided to the call must match the function's prototype,
573 and must be provided in the order specified by that prototype.
575 For example, @code{some-val} is a @code{<gdb:value>} instance
576 representing a function that takes two integers as arguments. To
577 execute this function, call it like so:
580 (define result (value-call some-val 10 20))
583 Any values returned from a function call are @code{<gdb:value>} objects.
585 Note: Unlike Python scripting in @value{GDBN},
586 inferior values that are simple scalars cannot be used directly in
587 Scheme expressions that are valid for the value's data type.
588 For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
589 And inferior values that are structures or instances of some class cannot
590 be accessed using any special syntax, instead @code{value-field} must be used.
592 The following value-related procedures are provided by the
595 @deffn {Scheme Procedure} value? object
596 Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
597 Otherwise return @code{#f}.
600 @deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]}
601 Many Scheme values can be converted directly to a @code{<gdb:value>}
602 with this procedure. If @var{type} is specified, the result is a value
603 of this type, and if @var{value} can't be represented with this type
604 an exception is thrown. Otherwise the type of the result is determined from
605 @var{value} as described below.
607 @xref{Architectures In Guile}, for a list of the builtin
608 types for an architecture.
610 Here's how Scheme values are converted when @var{type} argument to
611 @code{make-value} is not specified:
615 A Scheme boolean is converted the boolean type for the current language.
618 A Scheme integer is converted to the first of a C @code{int},
619 @code{unsigned int}, @code{long}, @code{unsigned long},
620 @code{long long} or @code{unsigned long long} type
621 for the current architecture that can represent the value.
623 If the Scheme integer cannot be represented as a target integer
624 an @code{out-of-range} exception is thrown.
627 A Scheme real is converted to the C @code{double} type for the
628 current architecture.
631 A Scheme string is converted to a string in the current target
632 language using the current target encoding.
633 Characters that cannot be represented in the current target encoding
634 are replaced with the corresponding escape sequence. This is Guile's
635 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy
636 (@pxref{Strings,,, guile, GNU Guile Reference Manual}).
638 Passing @var{type} is not supported in this case,
639 if it is provided a @code{wrong-type-arg} exception is thrown.
641 @item @code{<gdb:lazy-string>}
642 If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
643 Guile}), then the @code{lazy-string->value} procedure is called, and
646 Passing @var{type} is not supported in this case,
647 if it is provided a @code{wrong-type-arg} exception is thrown.
649 @item Scheme bytevector
650 If @var{value} is a Scheme bytevector and @var{type} is provided,
651 @var{value} must be the same size, in bytes, of values of type @var{type},
652 and the result is essentially created by using @code{memcpy}.
654 If @var{value} is a Scheme bytevector and @var{type} is not provided,
655 the result is an array of type @code{uint8} of the same length.
659 @cindex optimized out value in guile
660 @deffn {Scheme Procedure} value-optimized-out? value
661 Return @code{#t} if the compiler optimized out @var{value},
662 thus it is not available for fetching from the inferior.
663 Otherwise return @code{#f}.
666 @deffn {Scheme Procedure} value-address value
667 If @var{value} is addressable, returns a
668 @code{<gdb:value>} object representing the address.
669 Otherwise, @code{#f} is returned.
672 @deffn {Scheme Procedure} value-type value
673 Return the type of @var{value} as a @code{<gdb:type>} object
674 (@pxref{Types In Guile}).
677 @deffn {Scheme Procedure} value-dynamic-type value
678 Return the dynamic type of @var{value}. This uses C@t{++} run-time
679 type information (@acronym{RTTI}) to determine the dynamic type of the
680 value. If the value is of class type, it will return the class in
681 which the value is embedded, if any. If the value is of pointer or
682 reference to a class type, it will compute the dynamic type of the
683 referenced object, and return a pointer or reference to that type,
684 respectively. In all other cases, it will return the value's static
687 Note that this feature will only work when debugging a C@t{++} program
688 that includes @acronym{RTTI} for the object in question. Otherwise,
689 it will just return the static type of the value as in @kbd{ptype foo}.
690 @xref{Symbols, ptype}.
693 @deffn {Scheme Procedure} value-cast value type
694 Return a new instance of @code{<gdb:value>} that is the result of
695 casting @var{value} to the type described by @var{type}, which must
696 be a @code{<gdb:type>} object. If the cast cannot be performed for some
697 reason, this method throws an exception.
700 @deffn {Scheme Procedure} value-dynamic-cast value type
701 Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
702 operator were used. Consult a C@t{++} reference for details.
705 @deffn {Scheme Procedure} value-reinterpret-cast value type
706 Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
707 operator were used. Consult a C@t{++} reference for details.
710 @deffn {Scheme Procedure} value-dereference value
711 For pointer data types, this method returns a new @code{<gdb:value>} object
712 whose contents is the object pointed to by @var{value}. For example, if
713 @code{foo} is a C pointer to an @code{int}, declared in your C program as
720 then you can use the corresponding @code{<gdb:value>} to access what
721 @code{foo} points to like this:
724 (define bar (value-dereference foo))
727 The result @code{bar} will be a @code{<gdb:value>} object holding the
728 value pointed to by @code{foo}.
730 A similar function @code{value-referenced-value} exists which also
731 returns @code{<gdb:value>} objects corresponding to the values pointed to
732 by pointer values (and additionally, values referenced by reference
733 values). However, the behavior of @code{value-dereference}
734 differs from @code{value-referenced-value} by the fact that the
735 behavior of @code{value-dereference} is identical to applying the C
736 unary operator @code{*} on a given value. For example, consider a
737 reference to a pointer @code{ptrref}, declared in your C@t{++} program
745 intptr &ptrref = ptr;
748 Though @code{ptrref} is a reference value, one can apply the method
749 @code{value-dereference} to the @code{<gdb:value>} object corresponding
750 to it and obtain a @code{<gdb:value>} which is identical to that
751 corresponding to @code{val}. However, if you apply the method
752 @code{value-referenced-value}, the result would be a @code{<gdb:value>}
753 object identical to that corresponding to @code{ptr}.
756 (define scm-ptrref (parse-and-eval "ptrref"))
757 (define scm-val (value-dereference scm-ptrref))
758 (define scm-ptr (value-referenced-value scm-ptrref))
761 The @code{<gdb:value>} object @code{scm-val} is identical to that
762 corresponding to @code{val}, and @code{scm-ptr} is identical to that
763 corresponding to @code{ptr}. In general, @code{value-dereference} can
764 be applied whenever the C unary operator @code{*} can be applied
765 to the corresponding C value. For those cases where applying both
766 @code{value-dereference} and @code{value-referenced-value} is allowed,
767 the results obtained need not be identical (as we have seen in the above
768 example). The results are however identical when applied on
769 @code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
770 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
773 @deffn {Scheme Procedure} value-referenced-value value
774 For pointer or reference data types, this method returns a new
775 @code{<gdb:value>} object corresponding to the value referenced by the
776 pointer/reference value. For pointer data types,
777 @code{value-dereference} and @code{value-referenced-value} produce
778 identical results. The difference between these methods is that
779 @code{value-dereference} cannot get the values referenced by reference
780 values. For example, consider a reference to an @code{int}, declared
781 in your C@t{++} program as
789 then applying @code{value-dereference} to the @code{<gdb:value>} object
790 corresponding to @code{ref} will result in an error, while applying
791 @code{value-referenced-value} will result in a @code{<gdb:value>} object
792 identical to that corresponding to @code{val}.
795 (define scm-ref (parse-and-eval "ref"))
796 (define err-ref (value-dereference scm-ref)) ;; error
797 (define scm-val (value-referenced-value scm-ref)) ;; ok
800 The @code{<gdb:value>} object @code{scm-val} is identical to that
801 corresponding to @code{val}.
804 @deffn {Scheme Procedure} value-reference-value value
805 Return a new @code{<gdb:value>} object which is a reference to the value
806 encapsulated by @code{<gdb:value>} object @var{value}.
809 @deffn {Scheme Procedure} value-rvalue-reference-value value
810 Return a new @code{<gdb:value>} object which is an rvalue reference to
811 the value encapsulated by @code{<gdb:value>} object @var{value}.
814 @deffn {Scheme Procedure} value-const-value value
815 Return a new @code{<gdb:value>} object which is a @samp{const} version
816 of @code{<gdb:value>} object @var{value}.
819 @deffn {Scheme Procedure} value-field value field-name
820 Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
823 @deffn {Scheme Procedure} value-subscript value index
824 Return the value of array @var{value} at index @var{index}.
825 The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
828 @deffn {Scheme Procedure} value-call value arg-list
829 Perform an inferior function call, taking @var{value} as a pointer
830 to the function to call.
831 Each element of list @var{arg-list} must be a <gdb:value> object or an object
832 that can be converted to a value.
833 The result is the value returned by the function.
836 @deffn {Scheme Procedure} value->bool value
837 Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
838 The value must be ``integer like''. Pointers are ok.
841 @deffn {Scheme Procedure} value->integer
842 Return the Scheme integer representing @code{<gdb:value>} @var{value}.
843 The value must be ``integer like''. Pointers are ok.
846 @deffn {Scheme Procedure} value->real
847 Return the Scheme real number representing @code{<gdb:value>} @var{value}.
848 The value must be a number.
851 @deffn {Scheme Procedure} value->bytevector
852 Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
853 @var{value}. No transformation, endian or otherwise, is performed.
856 @deffn {Scheme Procedure} value->string value @
857 @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:errors errors@r{]}} @
858 @w{@r{[}#:length length@r{]}}
859 If @var{value>} represents a string, then this method
860 converts the contents to a Guile string. Otherwise, this method will
863 Values are interpreted as strings according to the rules of the
864 current language. If the optional length argument is given, the
865 string will be converted to that length, and will include any embedded
866 zeroes that the string may contain. Otherwise, for languages
867 where the string is zero-terminated, the entire string will be
870 For example, in C-like languages, a value is a string if it is a pointer
871 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
874 If the optional @var{encoding} argument is given, it must be a string
875 naming the encoding of the string in the @code{<gdb:value>}, such as
876 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
877 the same encodings as the corresponding argument to Guile's
878 @code{scm_from_stringn} function, and the Guile codec machinery will be used
879 to convert the string. If @var{encoding} is not given, or if
880 @var{encoding} is the empty string, then either the @code{target-charset}
881 (@pxref{Character Sets}) will be used, or a language-specific encoding
882 will be used, if the current language is able to supply one.
884 The optional @var{errors} argument is one of @code{#f}, @code{error} or
885 @code{substitute}. @code{error} and @code{substitute} must be symbols.
886 If @var{errors} is not specified, or if its value is @code{#f}, then the
887 default conversion strategy is used, which is set with the Scheme function
888 @code{set-port-conversion-strategy!}.
889 If the value is @code{'error} then an exception is thrown if there is any
890 conversion error. If the value is @code{'substitute} then any conversion
891 error is replaced with question marks.
892 @xref{Strings,,, guile, GNU Guile Reference Manual}.
894 If the optional @var{length} argument is given, the string will be
895 fetched and converted to the given length.
896 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
899 @deffn {Scheme Procedure} value->lazy-string value @
900 @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:length length@r{]}}
901 If this @code{<gdb:value>} represents a string, then this method
902 converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
903 In Guile}). Otherwise, this method will throw an exception.
905 If the optional @var{encoding} argument is given, it must be a string
906 naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
907 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
908 @var{encoding} argument is an encoding that @value{GDBN} does not
909 recognize, @value{GDBN} will raise an error.
911 When a lazy string is printed, the @value{GDBN} encoding machinery is
912 used to convert the string during printing. If the optional
913 @var{encoding} argument is not provided, or is an empty string,
914 @value{GDBN} will automatically select the encoding most suitable for
915 the string type. For further information on encoding in @value{GDBN}
916 please see @ref{Character Sets}.
918 If the optional @var{length} argument is given, the string will be
919 fetched and encoded to the length of characters specified. If
920 the @var{length} argument is not provided, the string will be fetched
921 and encoded until a null of appropriate width is found.
922 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
925 @deffn {Scheme Procedure} value-lazy? value
926 Return @code{#t} if @var{value} has not yet been fetched
928 Otherwise return @code{#f}.
929 @value{GDBN} does not fetch values until necessary, for efficiency.
933 (define myval (parse-and-eval "somevar"))
936 The value of @code{somevar} is not fetched at this time. It will be
937 fetched when the value is needed, or when the @code{fetch-lazy}
938 procedure is invoked.
941 @deffn {Scheme Procedure} make-lazy-value type address
942 Return a @code{<gdb:value>} that will be lazily fetched from the
943 target. The object of type @code{<gdb:type>} whose value to fetch is
944 specified by its @var{type} and its target memory @var{address}, which
948 @deffn {Scheme Procedure} value-fetch-lazy! value
949 If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
950 then the value is fetched from the inferior.
951 Any errors that occur in the process will produce a Guile exception.
953 If @var{value} is not a lazy value, this method has no effect.
955 The result of this function is unspecified.
958 @deffn {Scheme Procedure} value-print value
959 Return the string representation (print form) of @code{<gdb:value>}
963 @node Arithmetic In Guile
964 @subsubsection Arithmetic In Guile
966 The @code{(gdb)} module provides several functions for performing
967 arithmetic on @code{<gdb:value>} objects.
968 The arithmetic is performed as if it were done by the target,
969 and therefore has target semantics which are not necessarily
970 those of Scheme. For example operations work with a fixed precision,
971 not the arbitrary precision of Scheme.
973 Wherever a function takes an integer or pointer as an operand,
974 @value{GDBN} will convert appropriate Scheme values to perform
977 @deffn {Scheme Procedure} value-add a b
980 @deffn {Scheme Procedure} value-sub a b
983 @deffn {Scheme Procedure} value-mul a b
986 @deffn {Scheme Procedure} value-div a b
989 @deffn {Scheme Procedure} value-rem a b
992 @deffn {Scheme Procedure} value-mod a b
995 @deffn {Scheme Procedure} value-pow a b
998 @deffn {Scheme Procedure} value-not a
1001 @deffn {Scheme Procedure} value-neg a
1004 @deffn {Scheme Procedure} value-pos a
1007 @deffn {Scheme Procedure} value-abs a
1010 @deffn {Scheme Procedure} value-lsh a b
1013 @deffn {Scheme Procedure} value-rsh a b
1016 @deffn {Scheme Procedure} value-min a b
1019 @deffn {Scheme Procedure} value-max a b
1022 @deffn {Scheme Procedure} value-lognot a
1025 @deffn {Scheme Procedure} value-logand a b
1028 @deffn {Scheme Procedure} value-logior a b
1031 @deffn {Scheme Procedure} value-logxor a b
1034 @deffn {Scheme Procedure} value=? a b
1037 @deffn {Scheme Procedure} value<? a b
1040 @deffn {Scheme Procedure} value<=? a b
1043 @deffn {Scheme Procedure} value>? a b
1046 @deffn {Scheme Procedure} value>=? a b
1049 Scheme does not provide a @code{not-equal} function,
1050 and thus Guile support in @value{GDBN} does not either.
1052 @node Types In Guile
1053 @subsubsection Types In Guile
1054 @cindex types in guile
1055 @cindex guile, working with types
1058 @value{GDBN} represents types from the inferior in objects of type
1061 The following type-related procedures are provided by the
1062 @code{(gdb)} module.
1064 @deffn {Scheme Procedure} type? object
1065 Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
1066 Otherwise return @code{#f}.
1069 @deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
1070 This function looks up a type by its @var{name}, which must be a string.
1072 If @var{block} is given, it is an object of type @code{<gdb:block>},
1073 and @var{name} is looked up in that scope.
1074 Otherwise, it is searched for globally.
1076 Ordinarily, this function will return an instance of @code{<gdb:type>}.
1077 If the named type cannot be found, it will throw an exception.
1080 @deffn {Scheme Procedure} type-code type
1081 Return the type code of @var{type}. The type code will be one of the
1082 @code{TYPE_CODE_} constants defined below.
1085 @deffn {Scheme Procedure} type-tag type
1086 Return the tag name of @var{type}. The tag name is the name after
1087 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1088 languages have this concept. If this type has no tag name, then
1089 @code{#f} is returned.
1092 @deffn {Scheme Procedure} type-name type
1093 Return the name of @var{type}.
1094 If this type has no name, then @code{#f} is returned.
1097 @deffn {Scheme Procedure} type-print-name type
1098 Return the print name of @var{type}.
1099 This returns something even for anonymous types.
1100 For example, for an anonymous C struct @code{"struct @{...@}"} is returned.
1103 @deffn {Scheme Procedure} type-sizeof type
1104 Return the size of this type, in target @code{char} units. Usually, a
1105 target's @code{char} type will be an 8-bit byte. However, on some
1106 unusual platforms, this type may have a different size.
1109 @deffn {Scheme Procedure} type-strip-typedefs type
1110 Return a new @code{<gdb:type>} that represents the real type of @var{type},
1111 after removing all layers of typedefs.
1114 @deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]}
1115 Return a new @code{<gdb:type>} object which represents an array of this
1116 type. If one argument is given, it is the inclusive upper bound of
1117 the array; in this case the lower bound is zero. If two arguments are
1118 given, the first argument is the lower bound of the array, and the
1119 second argument is the upper bound of the array. An array's length
1120 must not be negative, but the bounds can be.
1123 @deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]}
1124 Return a new @code{<gdb:type>} object which represents a vector of this
1125 type. If one argument is given, it is the inclusive upper bound of
1126 the vector; in this case the lower bound is zero. If two arguments are
1127 given, the first argument is the lower bound of the vector, and the
1128 second argument is the upper bound of the vector. A vector's length
1129 must not be negative, but the bounds can be.
1131 The difference between an @code{array} and a @code{vector} is that
1132 arrays behave like in C: when used in expressions they decay to a pointer
1133 to the first element whereas vectors are treated as first class values.
1136 @deffn {Scheme Procedure} type-pointer type
1137 Return a new @code{<gdb:type>} object which represents a pointer to
1141 @deffn {Scheme Procedure} type-range type
1142 Return a list of two elements: the low bound and high bound of @var{type}.
1143 If @var{type} does not have a range, an exception is thrown.
1146 @deffn {Scheme Procedure} type-reference type
1147 Return a new @code{<gdb:type>} object which represents a reference to
1151 @deffn {Scheme Procedure} type-target type
1152 Return a new @code{<gdb:type>} object which represents the target type
1155 For a pointer type, the target type is the type of the pointed-to
1156 object. For an array type (meaning C-like arrays), the target type is
1157 the type of the elements of the array. For a function or method type,
1158 the target type is the type of the return value. For a complex type,
1159 the target type is the type of the elements. For a typedef, the
1160 target type is the aliased type.
1162 If the type does not have a target, this method will throw an
1166 @deffn {Scheme Procedure} type-const type
1167 Return a new @code{<gdb:type>} object which represents a
1168 @code{const}-qualified variant of @var{type}.
1171 @deffn {Scheme Procedure} type-volatile type
1172 Return a new @code{<gdb:type>} object which represents a
1173 @code{volatile}-qualified variant of @var{type}.
1176 @deffn {Scheme Procedure} type-unqualified type
1177 Return a new @code{<gdb:type>} object which represents an unqualified
1178 variant of @var{type}. That is, the result is neither @code{const} nor
1182 @deffn {Scheme Procedure} type-num-fields
1183 Return the number of fields of @code{<gdb:type>} @var{type}.
1186 @deffn {Scheme Procedure} type-fields type
1187 Return the fields of @var{type} as a list.
1188 For structure and union types, @code{fields} has the usual meaning.
1189 Range types have two fields, the minimum and maximum values. Enum types
1190 have one field per enum constant. Function and method types have one
1191 field per parameter. The base types of C@t{++} classes are also
1192 represented as fields. If the type has no fields, or does not fit
1193 into one of these categories, an empty list will be returned.
1194 @xref{Fields of a type in Guile}.
1197 @deffn {Scheme Procedure} make-field-iterator type
1198 Return the fields of @var{type} as a <gdb:iterator> object.
1199 @xref{Iterators In Guile}.
1202 @deffn {Scheme Procedure} type-field type field-name
1203 Return field named @var{field-name} in @var{type}.
1204 The result is an object of type @code{<gdb:field>}.
1205 @xref{Fields of a type in Guile}.
1206 If the type does not have fields, or @var{field-name} is not a field
1207 of @var{type}, an exception is thrown.
1209 For example, if @code{some-type} is a @code{<gdb:type>} instance holding
1210 a structure type, you can access its @code{foo} field with:
1213 (define bar (type-field some-type "foo"))
1216 @code{bar} will be a @code{<gdb:field>} object.
1219 @deffn {Scheme Procedure} type-has-field? type name
1220 Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
1221 Otherwise return @code{#f}.
1224 Each type has a code, which indicates what category this type falls
1225 into. The available type categories are represented by constants
1226 defined in the @code{(gdb)} module:
1230 The type is a pointer.
1232 @item TYPE_CODE_ARRAY
1233 The type is an array.
1235 @item TYPE_CODE_STRUCT
1236 The type is a structure.
1238 @item TYPE_CODE_UNION
1239 The type is a union.
1241 @item TYPE_CODE_ENUM
1242 The type is an enum.
1244 @item TYPE_CODE_FLAGS
1245 A bit flags type, used for things such as status registers.
1247 @item TYPE_CODE_FUNC
1248 The type is a function.
1251 The type is an integer type.
1254 A floating point type.
1256 @item TYPE_CODE_VOID
1257 The special type @code{void}.
1262 @item TYPE_CODE_RANGE
1263 A range type, that is, an integer type with bounds.
1265 @item TYPE_CODE_STRING
1266 A string type. Note that this is only used for certain languages with
1267 language-defined string types; C strings are not represented this way.
1269 @item TYPE_CODE_BITSTRING
1270 A string of bits. It is deprecated.
1272 @item TYPE_CODE_ERROR
1273 An unknown or erroneous type.
1275 @item TYPE_CODE_METHOD
1276 A method type, as found in C@t{++}.
1278 @item TYPE_CODE_METHODPTR
1279 A pointer-to-member-function.
1281 @item TYPE_CODE_MEMBERPTR
1282 A pointer-to-member.
1287 @item TYPE_CODE_RVALUE_REF
1288 A C@t{++}11 rvalue reference type.
1290 @item TYPE_CODE_CHAR
1293 @item TYPE_CODE_BOOL
1296 @item TYPE_CODE_COMPLEX
1297 A complex float type.
1299 @item TYPE_CODE_TYPEDEF
1300 A typedef to some other type.
1302 @item TYPE_CODE_NAMESPACE
1303 A C@t{++} namespace.
1305 @item TYPE_CODE_DECFLOAT
1306 A decimal floating point type.
1308 @item TYPE_CODE_INTERNAL_FUNCTION
1309 A function internal to @value{GDBN}. This is the type used to represent
1310 convenience functions (@pxref{Convenience Funs}).
1313 Further support for types is provided in the @code{(gdb types)}
1314 Guile module (@pxref{Guile Types Module}).
1316 @anchor{Fields of a type in Guile}
1317 Each field is represented as an object of type @code{<gdb:field>}.
1319 The following field-related procedures are provided by the
1320 @code{(gdb)} module:
1322 @deffn {Scheme Procedure} field? object
1323 Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
1324 Otherwise return @code{#f}.
1327 @deffn {Scheme Procedure} field-name field
1328 Return the name of the field, or @code{#f} for anonymous fields.
1331 @deffn {Scheme Procedure} field-type field
1332 Return the type of the field. This is usually an instance of
1333 @code{<gdb:type>}, but it can be @code{#f} in some situations.
1336 @deffn {Scheme Procedure} field-enumval field
1337 Return the enum value represented by @code{<gdb:field>} @var{field}.
1340 @deffn {Scheme Procedure} field-bitpos field
1341 Return the bit position of @code{<gdb:field>} @var{field}.
1342 This attribute is not available for @code{static} fields (as in
1346 @deffn {Scheme Procedure} field-bitsize field
1347 If the field is packed, or is a bitfield, return the size of
1348 @code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
1349 in which case the field's size is given by its type.
1352 @deffn {Scheme Procedure} field-artificial? field
1353 Return @code{#t} if the field is artificial, usually meaning that
1354 it was provided by the compiler and not the user.
1355 Otherwise return @code{#f}.
1358 @deffn {Scheme Procedure} field-base-class? field
1359 Return @code{#t} if the field represents a base class of a C@t{++}
1361 Otherwise return @code{#f}.
1364 @node Guile Pretty Printing API
1365 @subsubsection Guile Pretty Printing API
1366 @cindex guile pretty printing api
1368 An example output is provided (@pxref{Pretty Printing}).
1370 A pretty-printer is represented by an object of type <gdb:pretty-printer>.
1371 Pretty-printer objects are created with @code{make-pretty-printer}.
1373 The following pretty-printer-related procedures are provided by the
1374 @code{(gdb)} module:
1376 @deffn {Scheme Procedure} make-pretty-printer name lookup-function
1377 Return a @code{<gdb:pretty-printer>} object named @var{name}.
1379 @var{lookup-function} is a function of one parameter: the value to
1380 be printed. If the value is handled by this pretty-printer, then
1381 @var{lookup-function} returns an object of type
1382 <gdb:pretty-printer-worker> to perform the actual pretty-printing.
1383 Otherwise @var{lookup-function} returns @code{#f}.
1386 @deffn {Scheme Procedure} pretty-printer? object
1387 Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
1388 Otherwise return @code{#f}.
1391 @deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer
1392 Return @code{#t} if @var{pretty-printer} is enabled.
1393 Otherwise return @code{#f}.
1396 @deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag
1397 Set the enabled flag of @var{pretty-printer} to @var{flag}.
1398 The value returned is unspecified.
1401 @deffn {Scheme Procedure} pretty-printers
1402 Return the list of global pretty-printers.
1405 @deffn {Scheme Procedure} set-pretty-printers! pretty-printers
1406 Set the list of global pretty-printers to @var{pretty-printers}.
1407 The value returned is unspecified.
1410 @deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children
1411 Return an object of type @code{<gdb:pretty-printer-worker>}.
1413 This function takes three parameters:
1417 @var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
1418 front end via MI to change the formatting of the value being printed.
1419 The value must be a string or @code{#f} (meaning there is no hint).
1420 Several values for @var{display-hint}
1421 are predefined by @value{GDBN}:
1425 Indicate that the object being printed is ``array-like''. The CLI
1426 uses this to respect parameters such as @code{set print elements} and
1427 @code{set print array}.
1430 Indicate that the object being printed is ``map-like'', and that the
1431 children of this value can be assumed to alternate between keys and
1435 Indicate that the object being printed is ``string-like''. If the
1436 printer's @code{to-string} function returns a Guile string of some
1437 kind, then @value{GDBN} will call its internal language-specific
1438 string-printing function to format the string. For the CLI this means
1439 adding quotation marks, possibly escaping some characters, respecting
1440 @code{set print elements}, and the like.
1444 @var{to-string} is either a function of one parameter, the
1445 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1447 When printing from the CLI, if the @code{to-string} method exists,
1448 then @value{GDBN} will prepend its result to the values returned by
1449 @code{children}. Exactly how this formatting is done is dependent on
1450 the display hint, and may change as more hints are added. Also,
1451 depending on the print settings (@pxref{Print Settings}), the CLI may
1452 print just the result of @code{to-string} in a stack trace, omitting
1453 the result of @code{children}.
1455 If this method returns a string, it is printed verbatim.
1457 Otherwise, if this method returns an instance of @code{<gdb:value>},
1458 then @value{GDBN} prints this value. This may result in a call to
1459 another pretty-printer.
1461 If instead the method returns a Guile value which is convertible to a
1462 @code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
1463 the resulting value. Again, this may result in a call to another
1464 pretty-printer. Guile scalars (integers, floats, and booleans) and
1465 strings are convertible to @code{<gdb:value>}; other types are not.
1467 Finally, if this method returns @code{#f} then no further operations
1468 are peformed in this method and nothing is printed.
1470 If the result is not one of these types, an exception is raised.
1472 @var{to-string} may also be @code{#f} in which case it is left to
1473 @var{children} to print the value.
1476 @var{children} is either a function of one parameter, the
1477 @code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1479 @value{GDBN} will call this function on a pretty-printer to compute the
1480 children of the pretty-printer's value.
1482 This function must return a <gdb:iterator> object.
1483 Each item returned by the iterator must be a tuple holding
1484 two elements. The first element is the ``name'' of the child; the
1485 second element is the child's value. The value can be any Guile
1486 object which is convertible to a @value{GDBN} value.
1488 If @var{children} is @code{#f}, @value{GDBN} will act
1489 as though the value has no children.
1491 Children may be hidden from display based on the value of @samp{set
1492 print max-depth} (@pxref{Print Settings}).
1496 @value{GDBN} provides a function which can be used to look up the
1497 default pretty-printer for a @code{<gdb:value>}:
1499 @deffn {Scheme Procedure} default-visualizer value
1500 This function takes a @code{<gdb:value>} object as an argument. If a
1501 pretty-printer for this value exists, then it is returned. If no such
1502 printer exists, then this returns @code{#f}.
1505 @node Selecting Guile Pretty-Printers
1506 @subsubsection Selecting Guile Pretty-Printers
1507 @cindex selecting guile pretty-printers
1509 There are three sets of pretty-printers that @value{GDBN} searches:
1513 Per-objfile list of pretty-printers (@pxref{Objfiles In Guile}).
1515 Per-progspace list of pretty-printers (@pxref{Progspaces In Guile}).
1517 The global list of pretty-printers (@pxref{Guile Pretty Printing API}).
1518 These printers are available when debugging any inferior.
1521 Pretty-printer lookup is done by passing the value to be printed to the
1522 lookup function of each enabled object in turn.
1523 Lookup stops when a lookup function returns a non-@code{#f} value
1524 or when the list is exhausted.
1525 Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
1526 object or @code{#f}. Otherwise an exception is thrown.
1528 @value{GDBN} first checks the result of @code{objfile-pretty-printers}
1529 of each @code{<gdb:objfile>} in the current program space and iteratively
1530 calls each enabled lookup function in the list for that @code{<gdb:objfile>}
1531 until a non-@code{#f} object is returned.
1532 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1533 searches the result of @code{progspace-pretty-printers} of the current
1534 program space, calling each enabled function until a non-@code{#f} object
1536 After these lists have been exhausted, it tries the global pretty-printers
1537 list, obtained with @code{pretty-printers}, again calling each enabled
1538 function until a non-@code{#f} object is returned.
1540 The order in which the objfiles are searched is not specified. For a
1541 given list, functions are always invoked from the head of the list,
1542 and iterated over sequentially until the end of the list, or a
1543 @code{<gdb:pretty-printer-worker>} object is returned.
1545 For various reasons a pretty-printer may not work.
1546 For example, the underlying data structure may have changed and
1547 the pretty-printer is out of date.
1549 The consequences of a broken pretty-printer are severe enough that
1550 @value{GDBN} provides support for enabling and disabling individual
1551 printers. For example, if @code{print frame-arguments} is on,
1552 a backtrace can become highly illegible if any argument is printed
1553 with a broken printer.
1555 Pretty-printers are enabled and disabled from Scheme by calling
1556 @code{set-pretty-printer-enabled!}.
1557 @xref{Guile Pretty Printing API}.
1559 @node Writing a Guile Pretty-Printer
1560 @subsubsection Writing a Guile Pretty-Printer
1561 @cindex writing a Guile pretty-printer
1563 A pretty-printer consists of two basic parts: a lookup function to determine
1564 if the type is supported, and the printer itself.
1566 Here is an example showing how a @code{std::string} printer might be
1567 written. @xref{Guile Pretty Printing API}, for details.
1570 (define (make-my-string-printer value)
1571 "Print a my::string string"
1572 (make-pretty-printer-worker
1575 (value-field value "_data"))
1579 And here is an example showing how a lookup function for the printer
1580 example above might be written.
1583 (define (str-lookup-function pretty-printer value)
1584 (let ((tag (type-tag (value-type value))))
1586 (string-prefix? "std::string<" tag)
1587 (make-my-string-printer value))))
1590 Then to register this printer in the global printer list:
1593 (append-pretty-printer!
1594 (make-pretty-printer "my-string" str-lookup-function))
1597 The example lookup function extracts the value's type, and attempts to
1598 match it to a type that it can pretty-print. If it is a type the
1599 printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
1600 If not, it returns @code{#f}.
1602 We recommend that you put your core pretty-printers into a Guile
1603 package. If your pretty-printers are for use with a library, we
1604 further recommend embedding a version number into the package name.
1605 This practice will enable @value{GDBN} to load multiple versions of
1606 your pretty-printers at the same time, because they will have
1609 You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
1610 can be evaluated multiple times without changing its meaning. An
1611 ideal auto-load file will consist solely of @code{import}s of your
1612 printer modules, followed by a call to a register pretty-printers with
1613 the current objfile.
1615 Taken as a whole, this approach will scale nicely to multiple
1616 inferiors, each potentially using a different library version.
1617 Embedding a version number in the Guile package name will ensure that
1618 @value{GDBN} is able to load both sets of printers simultaneously.
1619 Then, because the search for pretty-printers is done by objfile, and
1620 because your auto-loaded code took care to register your library's
1621 printers with a specific objfile, @value{GDBN} will find the correct
1622 printers for the specific version of the library used by each
1625 To continue the @code{my::string} example,
1626 this code might appear in @code{(my-project my-library v1)}:
1630 (define (register-printers objfile)
1631 (append-objfile-pretty-printer!
1632 (make-pretty-printer "my-string" str-lookup-function)))
1636 And then the corresponding contents of the auto-load file would be:
1639 (use-modules (gdb) (my-project my-library v1))
1640 (register-printers (current-objfile))
1643 The previous example illustrates a basic pretty-printer.
1644 There are a few things that can be improved on.
1645 The printer only handles one type, whereas a library typically has
1646 several types. One could install a lookup function for each desired type
1647 in the library, but one could also have a single lookup function recognize
1648 several types. The latter is the conventional way this is handled.
1649 If a pretty-printer can handle multiple data types, then its
1650 @dfn{subprinters} are the printers for the individual data types.
1652 The @code{(gdb printing)} module provides a formal way of solving this
1653 problem (@pxref{Guile Printing Module}).
1654 Here is another example that handles multiple types.
1656 These are the types we are going to pretty-print:
1659 struct foo @{ int a, b; @};
1660 struct bar @{ struct foo x, y; @};
1663 Here are the printers:
1666 (define (make-foo-printer value)
1667 "Print a foo object"
1668 (make-pretty-printer-worker
1671 (format #f "a=<~a> b=<~a>"
1672 (value-field value "a") (value-field value "a")))
1675 (define (make-bar-printer value)
1676 "Print a bar object"
1677 (make-pretty-printer-worker
1680 (format #f "x=<~a> y=<~a>"
1681 (value-field value "x") (value-field value "y")))
1685 This example doesn't need a lookup function, that is handled by the
1686 @code{(gdb printing)} module. Instead a function is provided to build up
1687 the object that handles the lookup.
1690 (use-modules (gdb printing))
1692 (define (build-pretty-printer)
1693 (let ((pp (make-pretty-printer-collection "my-library")))
1694 (pp-collection-add-tag-printer "foo" make-foo-printer)
1695 (pp-collection-add-tag-printer "bar" make-bar-printer)
1699 And here is the autoload support:
1702 (use-modules (gdb) (my-library))
1703 (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
1706 Finally, when this printer is loaded into @value{GDBN}, here is the
1707 corresponding output of @samp{info pretty-printer}:
1710 (gdb) info pretty-printer
1717 @node Commands In Guile
1718 @subsubsection Commands In Guile
1720 @cindex commands in guile
1721 @cindex guile commands
1722 You can implement new @value{GDBN} CLI commands in Guile. A CLI
1723 command object is created with the @code{make-command} Guile function,
1724 and added to @value{GDBN} with the @code{register-command!} Guile function.
1725 This two-step approach is taken to separate out the side-effect of adding
1726 the command to @value{GDBN} from @code{make-command}.
1728 There is no support for multi-line commands, that is commands that
1729 consist of multiple lines and are terminated with @code{end}.
1731 @deffn {Scheme Procedure} make-command name @w{@r{[}#:invoke invoke@r{]}} @
1732 @w{@r{[}#:command-class command-class@r{]}} @
1733 @w{@r{[}#:completer-class completer@r{]}} @
1734 @w{@r{[}#:prefix? prefix@r{]}} @w{@r{[}#:doc doc-string@r{]}}
1736 The argument @var{name} is the name of the command. If @var{name} consists of
1737 multiple words, then the initial words are looked for as prefix
1738 commands. In this case, if one of the prefix commands does not exist,
1739 an exception is raised.
1741 The result is the @code{<gdb:command>} object representing the command.
1742 The command is not usable until it has been registered with @value{GDBN}
1743 with @code{register-command!}.
1745 The rest of the arguments are optional.
1747 The argument @var{invoke} is a procedure of three arguments: @var{self},
1748 @var{args} and @var{from-tty}. The argument @var{self} is the
1749 @code{<gdb:command>} object representing the command.
1750 The argument @var{args} is a string representing the arguments passed to
1751 the command, after leading and trailing whitespace has been stripped.
1752 The argument @var{from-tty} is a boolean flag and specifies whether the
1753 command should consider itself to have been originated from the user
1754 invoking it interactively. If this function throws an exception,
1755 it is turned into a @value{GDBN} @code{error} call.
1756 Otherwise, the return value is ignored.
1758 The argument @var{command-class} is one of the @samp{COMMAND_} constants
1759 defined below. This argument tells @value{GDBN} how to categorize the
1760 new command in the help system. The default is @code{COMMAND_NONE}.
1762 The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_}
1763 constants defined below, or a procedure, also defined below.
1764 This argument tells @value{GDBN} how to perform completion
1765 for this command. If not provided or if the value is @code{#f},
1766 then no completion is performed on the command.
1768 The argument @var{prefix} is a boolean flag indicating whether the new
1769 command is a prefix command; sub-commands of this command may be
1772 The argument @var{doc-string} is help text for the new command.
1773 If no documentation string is provided, the default value ``This command is
1774 not documented.'' is used.
1777 @deffn {Scheme Procedure} register-command! command
1778 Add @var{command}, a @code{<gdb:command>} object, to @value{GDBN}'s
1780 It is an error to register a command more than once.
1781 The result is unspecified.
1784 @deffn {Scheme Procedure} command? object
1785 Return @code{#t} if @var{object} is a @code{<gdb:command>} object.
1786 Otherwise return @code{#f}.
1789 @cindex don't repeat Guile command
1790 @deffn {Scheme Procedure} dont-repeat
1791 By default, a @value{GDBN} command is repeated when the user enters a
1792 blank line at the command prompt. A command can suppress this
1793 behavior by invoking the @code{dont-repeat} function. This is similar
1794 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
1797 @deffn {Scheme Procedure} string->argv string
1798 Convert a string to a list of strings split up according to
1799 @value{GDBN}'s argv parsing rules.
1800 It is recommended to use this for consistency.
1801 Arguments are separated by spaces and may be quoted.
1805 scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
1806 $1 = ("1" "2 \"3" "4 \"5" "6 '7")
1810 @deffn {Scheme Procedure} throw-user-error message . args
1811 Throw a @code{gdb:user-error} exception.
1812 The argument @var{message} is the error message as a format string, like the
1813 @var{fmt} argument to the @code{format} Scheme function.
1814 @xref{Formatted Output,,, guile, GNU Guile Reference Manual}.
1815 The argument @var{args} is a list of the optional arguments of @var{message}.
1817 This is used when the command detects a user error of some kind,
1818 say a bad command argument.
1821 (gdb) guile (use-modules (gdb))
1823 (register-command! (make-command "test-user-error"
1824 #:command-class COMMAND_OBSCURE
1825 #:invoke (lambda (self arg from-tty)
1826 (throw-user-error "Bad argument ~a" arg))))
1828 (gdb) test-user-error ugh
1829 ERROR: Bad argument ugh
1833 @cindex completion of Guile commands
1834 @deffn completer self text word
1835 If the @var{completer} option to @code{make-command} is a procedure,
1836 it takes three arguments: @var{self} which is the @code{<gdb:command>}
1837 object, and @var{text} and @var{word} which are both strings.
1838 The argument @var{text} holds the complete command line up to the cursor's
1839 location. The argument @var{word} holds the last word of the command line;
1840 this is computed using a word-breaking heuristic.
1842 All forms of completion are handled by this function, that is,
1843 the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}),
1844 and the @code{complete} command (@pxref{Help, complete}).
1846 This procedure can return several kinds of values:
1850 If the return value is a list, the contents of the list are used as the
1851 completions. It is up to @var{completer} to ensure that the
1852 contents actually do complete the word. An empty list is
1853 allowed, it means that there were no completions available. Only
1854 string elements of the list are used; other elements in the
1858 If the return value is a @code{<gdb:iterator>} object, it is iterated over to
1859 obtain the completions. It is up to @code{completer-procedure} to ensure
1860 that the results actually do complete the word. Only
1861 string elements of the result are used; other elements in the
1862 sequence are ignored.
1865 All other results are treated as though there were no available
1870 When a new command is registered, it will have been declared as a member of
1871 some general class of commands. This is used to classify top-level
1872 commands in the on-line help system; note that prefix commands are not
1873 listed under their own category but rather that of their top-level
1874 command. The available classifications are represented by constants
1875 defined in the @code{gdb} module:
1879 The command does not belong to any particular class. A command in
1880 this category will not be displayed in any of the help categories.
1881 This is the default.
1883 @item COMMAND_RUNNING
1884 The command is related to running the inferior. For example,
1885 @code{start}, @code{step}, and @code{continue} are in this category.
1886 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
1887 commands in this category.
1890 The command is related to data or variables. For example,
1891 @code{call}, @code{find}, and @code{print} are in this category. Type
1892 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
1896 The command has to do with manipulation of the stack. For example,
1897 @code{backtrace}, @code{frame}, and @code{return} are in this
1898 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
1899 list of commands in this category.
1902 This class is used for file-related commands. For example,
1903 @code{file}, @code{list} and @code{section} are in this category.
1904 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
1905 commands in this category.
1907 @item COMMAND_SUPPORT
1908 This should be used for ``support facilities'', generally meaning
1909 things that are useful to the user when interacting with @value{GDBN},
1910 but not related to the state of the inferior. For example,
1911 @code{help}, @code{make}, and @code{shell} are in this category. Type
1912 @kbd{help support} at the @value{GDBN} prompt to see a list of
1913 commands in this category.
1915 @item COMMAND_STATUS
1916 The command is an @samp{info}-related command, that is, related to the
1917 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
1918 and @code{show} are in this category. Type @kbd{help status} at the
1919 @value{GDBN} prompt to see a list of commands in this category.
1921 @item COMMAND_BREAKPOINTS
1922 The command has to do with breakpoints. For example, @code{break},
1923 @code{clear}, and @code{delete} are in this category. Type @kbd{help
1924 breakpoints} at the @value{GDBN} prompt to see a list of commands in
1927 @item COMMAND_TRACEPOINTS
1928 The command has to do with tracepoints. For example, @code{trace},
1929 @code{actions}, and @code{tfind} are in this category. Type
1930 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
1931 commands in this category.
1934 The command is a general purpose command for the user, and typically
1935 does not fit in one of the other categories.
1936 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
1937 a list of commands in this category, as well as the list of gdb macros
1938 (@pxref{Sequences}).
1940 @item COMMAND_OBSCURE
1941 The command is only used in unusual circumstances, or is not of
1942 general interest to users. For example, @code{checkpoint},
1943 @code{fork}, and @code{stop} are in this category. Type @kbd{help
1944 obscure} at the @value{GDBN} prompt to see a list of commands in this
1947 @item COMMAND_MAINTENANCE
1948 The command is only useful to @value{GDBN} maintainers. The
1949 @code{maintenance} and @code{flushregs} commands are in this category.
1950 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
1951 commands in this category.
1954 A new command can use a predefined completion function, either by
1955 specifying it via an argument at initialization, or by returning it
1956 from the @code{completer} procedure. These predefined completion
1957 constants are all defined in the @code{gdb} module:
1961 This constant means that no completion should be done.
1963 @item COMPLETE_FILENAME
1964 This constant means that filename completion should be performed.
1966 @item COMPLETE_LOCATION
1967 This constant means that location completion should be done.
1968 @xref{Specify Location}.
1970 @item COMPLETE_COMMAND
1971 This constant means that completion should examine @value{GDBN}
1974 @item COMPLETE_SYMBOL
1975 This constant means that completion should be done using symbol names
1978 @item COMPLETE_EXPRESSION
1979 This constant means that completion should be done on expressions.
1980 Often this means completing on symbol names, but some language
1981 parsers also have support for completing on field names.
1984 The following code snippet shows how a trivial CLI command can be
1985 implemented in Guile:
1989 (register-command! (make-command "hello-world"
1990 #:command-class COMMAND_USER
1991 #:doc "Greet the whole world."
1992 #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
1998 @node Parameters In Guile
1999 @subsubsection Parameters In Guile
2001 @cindex parameters in guile
2002 @cindex guile parameters
2004 You can implement new @value{GDBN} @dfn{parameters} using Guile
2005 @footnote{Note that @value{GDBN} parameters must not be confused with
2006 Guile’s parameter objects (@pxref{Parameters,,, guile, GNU Guile
2007 Reference Manual}).}.
2009 There are many parameters that already exist and can be set in
2010 @value{GDBN}. Two examples are: @code{set follow-fork} and
2011 @code{set charset}. Setting these parameters influences certain
2012 behavior in @value{GDBN}. Similarly, you can define parameters that
2013 can be used to influence behavior in custom Guile scripts and commands.
2015 A new parameter is defined with the @code{make-parameter} Guile function,
2016 and added to @value{GDBN} with the @code{register-parameter!} Guile function.
2017 This two-step approach is taken to separate out the side-effect of adding
2018 the parameter to @value{GDBN} from @code{make-parameter}.
2020 Parameters are exposed to the user via the @code{set} and
2021 @code{show} commands. @xref{Help}.
2023 @deffn {Scheme Procedure} make-parameter name @
2024 @w{@r{[}#:command-class command-class@r{]}} @
2025 @w{@r{[}#:parameter-type parameter-type@r{]}} @
2026 @w{@r{[}#:enum-list enum-list@r{]}} @w{@r{[}#:set-func set-func@r{]}} @
2027 @w{@r{[}#:show-func show-func@r{]}} @w{@r{[}#:doc doc@r{]}} @
2028 @w{@r{[}#:set-doc set-doc@r{]}} @w{@r{[}#:show-doc show-doc@r{]}} @
2029 @w{@r{[}#:initial-value initial-value@r{]}}
2031 The argument @var{name} is the name of the new parameter. If @var{name}
2032 consists of multiple words, then the initial words are looked for as prefix
2033 parameters. An example of this can be illustrated with the
2034 @code{set print} set of parameters. If @var{name} is
2035 @code{print foo}, then @code{print} will be searched as the prefix
2036 parameter. In this case the parameter can subsequently be accessed in
2037 @value{GDBN} as @code{set print foo}.
2038 If @var{name} consists of multiple words, and no prefix parameter group
2039 can be found, an exception is raised.
2041 The result is the @code{<gdb:parameter>} object representing the parameter.
2042 The parameter is not usable until it has been registered with @value{GDBN}
2043 with @code{register-parameter!}.
2045 The rest of the arguments are optional.
2047 The argument @var{command-class} should be one of the @samp{COMMAND_} constants
2048 (@pxref{Commands In Guile}). This argument tells @value{GDBN} how to
2049 categorize the new parameter in the help system.
2050 The default is @code{COMMAND_NONE}.
2052 The argument @var{parameter-type} should be one of the @samp{PARAM_} constants
2053 defined below. This argument tells @value{GDBN} the type of the new
2054 parameter; this information is used for input validation and
2055 completion. The default is @code{PARAM_BOOLEAN}.
2057 If @var{parameter-type} is @code{PARAM_ENUM}, then
2058 @var{enum-list} must be a list of strings. These strings
2059 represent the possible values for the parameter.
2061 If @var{parameter-type} is not @code{PARAM_ENUM}, then the presence
2062 of @var{enum-list} will cause an exception to be thrown.
2064 The argument @var{set-func} is a function of one argument: @var{self} which
2065 is the @code{<gdb:parameter>} object representing the parameter.
2066 @value{GDBN} will call this function when a @var{parameter}'s value has
2067 been changed via the @code{set} API (for example, @kbd{set foo off}).
2068 The value of the parameter has already been set to the new value.
2069 This function must return a string to be displayed to the user.
2070 @value{GDBN} will add a trailing newline if the string is non-empty.
2071 @value{GDBN} generally doesn't print anything when a parameter is set,
2072 thus typically this function should return @samp{""}.
2073 A non-empty string result should typically be used for displaying warnings
2076 The argument @var{show-func} is a function of two arguments: @var{self} which
2077 is the @code{<gdb:parameter>} object representing the parameter, and
2078 @var{svalue} which is the string representation of the current value.
2079 @value{GDBN} will call this function when a @var{parameter}'s
2080 @code{show} API has been invoked (for example, @kbd{show foo}).
2081 This function must return a string, and will be displayed to the user.
2082 @value{GDBN} will add a trailing newline.
2084 The argument @var{doc} is the help text for the new parameter.
2085 If there is no documentation string, a default value is used.
2087 The argument @var{set-doc} is the help text for this parameter's
2090 The argument @var{show-doc} is the help text for this parameter's
2091 @code{show} command.
2093 The argument @var{initial-value} specifies the initial value of the parameter.
2094 If it is a function, it takes one parameter, the @code{<gdb:parameter>}
2095 object and its result is used as the initial value of the parameter.
2096 The initial value must be valid for the parameter type,
2097 otherwise an exception is thrown.
2100 @deffn {Scheme Procedure} register-parameter! parameter
2101 Add @var{parameter}, a @code{<gdb:parameter>} object, to @value{GDBN}'s
2103 It is an error to register a parameter more than once.
2104 The result is unspecified.
2107 @deffn {Scheme Procedure} parameter? object
2108 Return @code{#t} if @var{object} is a @code{<gdb:parameter>} object.
2109 Otherwise return @code{#f}.
2112 @deffn {Scheme Procedure} parameter-value parameter
2113 Return the value of @var{parameter} which may either be
2114 a @code{<gdb:parameter>} object or a string naming the parameter.
2117 @deffn {Scheme Procedure} set-parameter-value! parameter new-value
2118 Assign @var{parameter} the value of @var{new-value}.
2119 The argument @var{parameter} must be an object of type @code{<gdb:parameter>}.
2120 @value{GDBN} does validation when assignments are made.
2123 When a new parameter is defined, its type must be specified. The
2124 available types are represented by constants defined in the @code{gdb}
2129 The value is a plain boolean. The Guile boolean values, @code{#t}
2130 and @code{#f} are the only valid values.
2132 @item PARAM_AUTO_BOOLEAN
2133 The value has three possible states: true, false, and @samp{auto}. In
2134 Guile, true and false are represented using boolean constants, and
2135 @samp{auto} is represented using @code{#:auto}.
2137 @item PARAM_UINTEGER
2138 The value is an unsigned integer. The value of 0 should be
2139 interpreted to mean ``unlimited''.
2141 @item PARAM_ZINTEGER
2142 The value is an integer.
2144 @item PARAM_ZUINTEGER
2145 The value is an unsigned integer.
2147 @item PARAM_ZUINTEGER_UNLIMITED
2148 The value is an integer in the range @samp{[0, INT_MAX]}.
2149 A value of @samp{-1} means ``unlimited'', and other negative
2150 numbers are not allowed.
2153 The value is a string. When the user modifies the string, any escape
2154 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
2155 translated into corresponding characters and encoded into the current
2158 @item PARAM_STRING_NOESCAPE
2159 The value is a string. When the user modifies the string, escapes are
2160 passed through untranslated.
2162 @item PARAM_OPTIONAL_FILENAME
2163 The value is a either a filename (a string), or @code{#f}.
2165 @item PARAM_FILENAME
2166 The value is a filename. This is just like
2167 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
2170 The value is a string, which must be one of a collection of string
2171 constants provided when the parameter is created.
2174 @node Progspaces In Guile
2175 @subsubsection Program Spaces In Guile
2177 @cindex progspaces in guile
2178 @tindex <gdb:progspace>
2179 A program space, or @dfn{progspace}, represents a symbolic view
2180 of an address space.
2181 It consists of all of the objfiles of the program.
2182 @xref{Objfiles In Guile}.
2183 @xref{Inferiors Connections and Programs, program spaces}, for more details
2184 about program spaces.
2186 Each progspace is represented by an instance of the @code{<gdb:progspace>}
2187 smob. @xref{GDB Scheme Data Types}.
2189 The following progspace-related functions are available in the
2190 @code{(gdb)} module:
2192 @deffn {Scheme Procedure} progspace? object
2193 Return @code{#t} if @var{object} is a @code{<gdb:progspace>} object.
2194 Otherwise return @code{#f}.
2197 @deffn {Scheme Procedure} progspace-valid? progspace
2198 Return @code{#t} if @var{progspace} is valid, @code{#f} if not.
2199 A @code{<gdb:progspace>} object can become invalid
2200 if the program it refers to is not loaded in @value{GDBN} any longer.
2203 @deffn {Scheme Procedure} current-progspace
2204 This function returns the program space of the currently selected inferior.
2205 There is always a current progspace, this never returns @code{#f}.
2206 @xref{Inferiors Connections and Programs}.
2209 @deffn {Scheme Procedure} progspaces
2210 Return a list of all the progspaces currently known to @value{GDBN}.
2213 @deffn {Scheme Procedure} progspace-filename progspace
2214 Return the absolute file name of @var{progspace} as a string.
2215 This is the name of the file passed as the argument to the @code{file}
2216 or @code{symbol-file} commands.
2217 If the program space does not have an associated file name,
2218 then @code{#f} is returned. This occurs, for example, when @value{GDBN}
2219 is started without a program to debug.
2221 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2225 @deffn {Scheme Procedure} progspace-objfiles progspace
2226 Return the list of objfiles of @var{progspace}.
2227 The order of objfiles in the result is arbitrary.
2228 Each element is an object of type @code{<gdb:objfile>}.
2229 @xref{Objfiles In Guile}.
2231 A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
2235 @deffn {Scheme Procedure} progspace-pretty-printers progspace
2236 Return the list of pretty-printers of @var{progspace}.
2237 Each element is an object of type @code{<gdb:pretty-printer>}.
2238 @xref{Guile Pretty Printing API}, for more information.
2241 @deffn {Scheme Procedure} set-progspace-pretty-printers! progspace printer-list
2242 Set the list of registered @code{<gdb:pretty-printer>} objects for
2243 @var{progspace} to @var{printer-list}.
2244 @xref{Guile Pretty Printing API}, for more information.
2247 @node Objfiles In Guile
2248 @subsubsection Objfiles In Guile
2250 @cindex objfiles in guile
2251 @tindex <gdb:objfile>
2252 @value{GDBN} loads symbols for an inferior from various
2253 symbol-containing files (@pxref{Files}). These include the primary
2254 executable file, any shared libraries used by the inferior, and any
2255 separate debug info files (@pxref{Separate Debug Files}).
2256 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
2258 Each objfile is represented as an object of type @code{<gdb:objfile>}.
2260 The following objfile-related procedures are provided by the
2261 @code{(gdb)} module:
2263 @deffn {Scheme Procedure} objfile? object
2264 Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
2265 Otherwise return @code{#f}.
2268 @deffn {Scheme Procedure} objfile-valid? objfile
2269 Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
2270 A @code{<gdb:objfile>} object can become invalid
2271 if the object file it refers to is not loaded in @value{GDBN} any
2272 longer. All other @code{<gdb:objfile>} procedures will throw an exception
2273 if it is invalid at the time the procedure is called.
2276 @deffn {Scheme Procedure} objfile-filename objfile
2277 Return the file name of @var{objfile} as a string,
2278 with symbolic links resolved.
2281 @deffn {Scheme Procedure} objfile-progspace objfile
2282 Return the @code{<gdb:progspace>} that this object file lives in.
2283 @xref{Progspaces In Guile}, for more on progspaces.
2286 @deffn {Scheme Procedure} objfile-pretty-printers objfile
2287 Return the list of registered @code{<gdb:pretty-printer>} objects for
2288 @var{objfile}. @xref{Guile Pretty Printing API}, for more information.
2291 @deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
2292 Set the list of registered @code{<gdb:pretty-printer>} objects for
2293 @var{objfile} to @var{printer-list}. The
2294 @var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
2295 @xref{Guile Pretty Printing API}, for more information.
2298 @deffn {Scheme Procedure} current-objfile
2299 When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
2300 sets the ``current objfile'' to the corresponding objfile. This
2301 function returns the current objfile. If there is no current objfile,
2302 this function returns @code{#f}.
2305 @deffn {Scheme Procedure} objfiles
2306 Return a list of all the objfiles in the current program space.
2309 @node Frames In Guile
2310 @subsubsection Accessing inferior stack frames from Guile.
2312 @cindex frames in guile
2313 When the debugged program stops, @value{GDBN} is able to analyze its call
2314 stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
2315 represents a frame in the stack. A @code{<gdb:frame>} object is only valid
2316 while its corresponding frame exists in the inferior's stack. If you try
2317 to use an invalid frame object, @value{GDBN} will throw a
2318 @code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
2320 Two @code{<gdb:frame>} objects can be compared for equality with the
2321 @code{equal?} function, like:
2324 (@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
2328 The following frame-related procedures are provided by the
2329 @code{(gdb)} module:
2331 @deffn {Scheme Procedure} frame? object
2332 Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
2333 Otherwise return @code{#f}.
2336 @deffn {Scheme Procedure} frame-valid? frame
2337 Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
2338 A frame object can become invalid if the frame it refers to doesn't
2339 exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
2340 an exception if the frame is invalid at the time the procedure is called.
2343 @deffn {Scheme Procedure} frame-name frame
2344 Return the function name of @var{frame}, or @code{#f} if it can't be
2348 @deffn {Scheme Procedure} frame-arch frame
2349 Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
2350 architecture. @xref{Architectures In Guile}.
2353 @deffn {Scheme Procedure} frame-type frame
2354 Return the type of @var{frame}. The value can be one of:
2358 An ordinary stack frame.
2361 A fake stack frame that was created by @value{GDBN} when performing an
2362 inferior function call.
2365 A frame representing an inlined function. The function was inlined
2366 into a @code{NORMAL_FRAME} that is older than this one.
2368 @item TAILCALL_FRAME
2369 A frame representing a tail call. @xref{Tail Call Frames}.
2371 @item SIGTRAMP_FRAME
2372 A signal trampoline frame. This is the frame created by the OS when
2373 it calls into a signal handler.
2376 A fake stack frame representing a cross-architecture call.
2378 @item SENTINEL_FRAME
2379 This is like @code{NORMAL_FRAME}, but it is only used for the
2384 @deffn {Scheme Procedure} frame-unwind-stop-reason frame
2385 Return an integer representing the reason why it's not possible to find
2386 more frames toward the outermost frame. Use
2387 @code{unwind-stop-reason-string} to convert the value returned by this
2388 function to a string. The value can be one of:
2391 @item FRAME_UNWIND_NO_REASON
2392 No particular reason (older frames should be available).
2394 @item FRAME_UNWIND_NULL_ID
2395 The previous frame's analyzer returns an invalid result.
2397 @item FRAME_UNWIND_OUTERMOST
2398 This frame is the outermost.
2400 @item FRAME_UNWIND_UNAVAILABLE
2401 Cannot unwind further, because that would require knowing the
2402 values of registers or memory that have not been collected.
2404 @item FRAME_UNWIND_INNER_ID
2405 This frame ID looks like it ought to belong to a NEXT frame,
2406 but we got it for a PREV frame. Normally, this is a sign of
2407 unwinder failure. It could also indicate stack corruption.
2409 @item FRAME_UNWIND_SAME_ID
2410 This frame has the same ID as the previous one. That means
2411 that unwinding further would almost certainly give us another
2412 frame with exactly the same ID, so break the chain. Normally,
2413 this is a sign of unwinder failure. It could also indicate
2416 @item FRAME_UNWIND_NO_SAVED_PC
2417 The frame unwinder did not find any saved PC, but we needed
2418 one to unwind further.
2420 @item FRAME_UNWIND_MEMORY_ERROR
2421 The frame unwinder caused an error while trying to access memory.
2423 @item FRAME_UNWIND_FIRST_ERROR
2424 Any stop reason greater or equal to this value indicates some kind
2425 of error. This special value facilitates writing code that tests
2426 for errors in unwinding in a way that will work correctly even if
2427 the list of the other values is modified in future @value{GDBN}
2428 versions. Using it, you could write:
2431 (define reason (frame-unwind-stop-readon (selected-frame)))
2432 (define reason-str (unwind-stop-reason-string reason))
2433 (if (>= reason FRAME_UNWIND_FIRST_ERROR)
2434 (format #t "An error occured: ~s\n" reason-str))
2439 @deffn {Scheme Procedure} frame-pc frame
2440 Return the frame's resume address.
2443 @deffn {Scheme Procedure} frame-block frame
2444 Return the frame's code block as a @code{<gdb:block>} object.
2445 @xref{Blocks In Guile}.
2448 @deffn {Scheme Procedure} frame-function frame
2449 Return the symbol for the function corresponding to this frame
2450 as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
2451 @xref{Symbols In Guile}.
2454 @deffn {Scheme Procedure} frame-older frame
2455 Return the frame that called @var{frame}.
2458 @deffn {Scheme Procedure} frame-newer frame
2459 Return the frame called by @var{frame}.
2462 @deffn {Scheme Procedure} frame-sal frame
2463 Return the frame's @code{<gdb:sal>} (symtab and line) object.
2464 @xref{Symbol Tables In Guile}.
2467 @deffn {Scheme Procedure} frame-read-register frame register
2468 Return the value of @var{register} in @var{frame}. @var{register}
2469 should be a string, like @samp{pc}.
2472 @deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]}
2473 Return the value of @var{variable} in @var{frame}. If the optional
2474 argument @var{block} is provided, search for the variable from that
2475 block; otherwise start at the frame's current block (which is
2476 determined by the frame's current program counter). The
2477 @var{variable} must be given as a string or a @code{<gdb:symbol>}
2478 object, and @var{block} must be a @code{<gdb:block>} object.
2481 @deffn {Scheme Procedure} frame-select frame
2482 Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
2486 @deffn {Scheme Procedure} selected-frame
2487 Return the selected frame object. @xref{Selection,,Selecting a Frame}.
2490 @deffn {Scheme Procedure} newest-frame
2491 Return the newest frame object for the selected thread.
2494 @deffn {Scheme Procedure} unwind-stop-reason-string reason
2495 Return a string explaining the reason why @value{GDBN} stopped unwinding
2496 frames, as expressed by the given @var{reason} code (an integer, see the
2497 @code{frame-unwind-stop-reason} procedure above in this section).
2500 @node Blocks In Guile
2501 @subsubsection Accessing blocks from Guile.
2503 @cindex blocks in guile
2506 In @value{GDBN}, symbols are stored in blocks. A block corresponds
2507 roughly to a scope in the source code. Blocks are organized
2508 hierarchically, and are represented individually in Guile as an object
2509 of type @code{<gdb:block>}. Blocks rely on debugging information being
2512 A frame has a block. Please see @ref{Frames In Guile}, for a more
2513 in-depth discussion of frames.
2515 The outermost block is known as the @dfn{global block}. The global
2516 block typically holds public global variables and functions.
2518 The block nested just inside the global block is the @dfn{static
2519 block}. The static block typically holds file-scoped variables and
2522 @value{GDBN} provides a method to get a block's superblock, but there
2523 is currently no way to examine the sub-blocks of a block, or to
2524 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
2527 Here is a short example that should help explain blocks:
2530 /* This is in the global block. */
2533 /* This is in the static block. */
2534 static int file_scope;
2536 /* 'function' is in the global block, and 'argument' is
2537 in a block nested inside of 'function'. */
2538 int function (int argument)
2540 /* 'local' is in a block inside 'function'. It may or may
2541 not be in the same block as 'argument'. */
2545 /* 'inner' is in a block whose superblock is the one holding
2549 /* If this call is expanded by the compiler, you may see
2550 a nested block here whose function is 'inline_function'
2551 and whose superblock is the one holding 'inner'. */
2557 The following block-related procedures are provided by the
2558 @code{(gdb)} module:
2560 @deffn {Scheme Procedure} block? object
2561 Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
2562 Otherwise return @code{#f}.
2565 @deffn {Scheme Procedure} block-valid? block
2566 Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
2567 @code{#f} if not. A block object can become invalid if the block it
2568 refers to doesn't exist anymore in the inferior. All other
2569 @code{<gdb:block>} methods will throw an exception if it is invalid at
2570 the time the procedure is called. The block's validity is also checked
2571 during iteration over symbols of the block.
2574 @deffn {Scheme Procedure} block-start block
2575 Return the start address of @code{<gdb:block>} @var{block}.
2578 @deffn {Scheme Procedure} block-end block
2579 Return the end address of @code{<gdb:block>} @var{block}.
2582 @deffn {Scheme Procedure} block-function block
2583 Return the name of @code{<gdb:block>} @var{block} represented as a
2584 @code{<gdb:symbol>} object.
2585 If the block is not named, then @code{#f} is returned.
2587 For ordinary function blocks, the superblock is the static block.
2588 However, you should note that it is possible for a function block to
2589 have a superblock that is not the static block -- for instance this
2590 happens for an inlined function.
2593 @deffn {Scheme Procedure} block-superblock block
2594 Return the block containing @code{<gdb:block>} @var{block}.
2595 If the parent block does not exist, then @code{#f} is returned.
2598 @deffn {Scheme Procedure} block-global-block block
2599 Return the global block associated with @code{<gdb:block>} @var{block}.
2602 @deffn {Scheme Procedure} block-static-block block
2603 Return the static block associated with @code{<gdb:block>} @var{block}.
2606 @deffn {Scheme Procedure} block-global? block
2607 Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
2608 Otherwise return @code{#f}.
2611 @deffn {Scheme Procedure} block-static? block
2612 Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
2613 Otherwise return @code{#f}.
2616 @deffn {Scheme Procedure} block-symbols
2617 Return a list of all symbols (as <gdb:symbol> objects) in
2618 @code{<gdb:block>} @var{block}.
2621 @deffn {Scheme Procedure} make-block-symbols-iterator block
2622 Return an object of type @code{<gdb:iterator>} that will iterate
2623 over all symbols of the block.
2624 Guile programs should not assume that a specific block object will
2625 always contain a given symbol, since changes in @value{GDBN} features and
2626 infrastructure may cause symbols move across blocks in a symbol table.
2627 @xref{Iterators In Guile}.
2630 @deffn {Scheme Procedure} block-symbols-progress?
2631 Return #t if the object is a <gdb:block-symbols-progress> object.
2632 This object would be obtained from the @code{progress} element of the
2633 @code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
2636 @deffn {Scheme Procedure} lookup-block pc
2637 Return the innermost @code{<gdb:block>} containing the given @var{pc}
2638 value. If the block cannot be found for the @var{pc} value specified,
2639 the function will return @code{#f}.
2642 @node Symbols In Guile
2643 @subsubsection Guile representation of Symbols.
2645 @cindex symbols in guile
2646 @tindex <gdb:symbol>
2648 @value{GDBN} represents every variable, function and type as an
2649 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
2650 Guile represents these symbols in @value{GDBN} with the
2651 @code{<gdb:symbol>} object.
2653 The following symbol-related procedures are provided by the
2654 @code{(gdb)} module:
2656 @deffn {Scheme Procedure} symbol? object
2657 Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
2658 Otherwise return @code{#f}.
2661 @deffn {Scheme Procedure} symbol-valid? symbol
2662 Return @code{#t} if the @code{<gdb:symbol>} object is valid,
2663 @code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
2664 the symbol it refers to does not exist in @value{GDBN} any longer.
2665 All other @code{<gdb:symbol>} procedures will throw an exception if it is
2666 invalid at the time the procedure is called.
2669 @deffn {Scheme Procedure} symbol-type symbol
2670 Return the type of @var{symbol} or @code{#f} if no type is recorded.
2671 The result is an object of type @code{<gdb:type>}.
2672 @xref{Types In Guile}.
2675 @deffn {Scheme Procedure} symbol-symtab symbol
2676 Return the symbol table in which @var{symbol} appears.
2677 The result is an object of type @code{<gdb:symtab>}.
2678 @xref{Symbol Tables In Guile}.
2681 @deffn {Scheme Procedure} symbol-line symbol
2682 Return the line number in the source code at which @var{symbol} was defined.
2686 @deffn {Scheme Procedure} symbol-name symbol
2687 Return the name of @var{symbol} as a string.
2690 @deffn {Scheme Procedure} symbol-linkage-name symbol
2691 Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
2694 @deffn {Scheme Procedure} symbol-print-name symbol
2695 Return the name of @var{symbol} in a form suitable for output. This is either
2696 @code{name} or @code{linkage_name}, depending on whether the user
2697 asked @value{GDBN} to display demangled or mangled names.
2700 @deffn {Scheme Procedure} symbol-addr-class symbol
2701 Return the address class of the symbol. This classifies how to find the value
2702 of a symbol. Each address class is a constant defined in the
2703 @code{(gdb)} module and described later in this chapter.
2706 @deffn {Scheme Procedure} symbol-needs-frame? symbol
2707 Return @code{#t} if evaluating @var{symbol}'s value requires a frame
2708 (@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
2709 local variables will require a frame, but other symbols will not.
2712 @deffn {Scheme Procedure} symbol-argument? symbol
2713 Return @code{#t} if @var{symbol} is an argument of a function.
2714 Otherwise return @code{#f}.
2717 @deffn {Scheme Procedure} symbol-constant? symbol
2718 Return @code{#t} if @var{symbol} is a constant.
2719 Otherwise return @code{#f}.
2722 @deffn {Scheme Procedure} symbol-function? symbol
2723 Return @code{#t} if @var{symbol} is a function or a method.
2724 Otherwise return @code{#f}.
2727 @deffn {Scheme Procedure} symbol-variable? symbol
2728 Return @code{#t} if @var{symbol} is a variable.
2729 Otherwise return @code{#f}.
2732 @deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]}
2733 Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
2734 functions, this computes the address of the function, cast to the
2735 appropriate type. If the symbol requires a frame in order to compute
2736 its value, then @var{frame} must be given. If @var{frame} is not
2737 given, or if @var{frame} is invalid, then an exception is thrown.
2740 @deffn {Scheme Procedure} lookup-symbol name @w{@r{[}#:block block@r{]}} @
2741 @w{@r{[}#:domain domain@r{]}}
2742 This function searches for a symbol by name. The search scope can be
2743 restricted to the parameters defined in the optional domain and block
2746 @var{name} is the name of the symbol. It must be a string. The
2747 optional @var{block} argument restricts the search to symbols visible
2748 in that @var{block}. The @var{block} argument must be a
2749 @code{<gdb:block>} object. If omitted, the block for the current frame
2750 is used. The optional @var{domain} argument restricts
2751 the search to the domain type. The @var{domain} argument must be a
2752 domain constant defined in the @code{(gdb)} module and described later
2755 The result is a list of two elements.
2756 The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2758 If the symbol is found, the second element is @code{#t} if the symbol
2759 is a field of a method's object (e.g., @code{this} in C@t{++}),
2760 otherwise it is @code{#f}.
2761 If the symbol is not found, the second element is @code{#f}.
2764 @deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]}
2765 This function searches for a global symbol by name.
2766 The search scope can be restricted by the domain argument.
2768 @var{name} is the name of the symbol. It must be a string.
2769 The optional @var{domain} argument restricts the search to the domain type.
2770 The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
2771 module and described later in this chapter.
2773 The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2777 The available domain categories in @code{<gdb:symbol>} are represented
2778 as constants in the @code{(gdb)} module:
2781 @item SYMBOL_UNDEF_DOMAIN
2782 This is used when a domain has not been discovered or none of the
2783 following domains apply. This usually indicates an error either
2784 in the symbol information or in @value{GDBN}'s handling of symbols.
2786 @item SYMBOL_VAR_DOMAIN
2787 This domain contains variables, function names, typedef names and enum
2790 @item SYMBOL_STRUCT_DOMAIN
2791 This domain holds struct, union and enum type names.
2793 @item SYMBOL_LABEL_DOMAIN
2794 This domain contains names of labels (for gotos).
2796 @item SYMBOL_VARIABLES_DOMAIN
2797 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
2798 contains everything minus functions and types.
2800 @item SYMBOL_FUNCTIONS_DOMAIN
2801 This domain contains all functions.
2803 @item SYMBOL_TYPES_DOMAIN
2804 This domain contains all types.
2807 The available address class categories in @code{<gdb:symbol>} are represented
2808 as constants in the @code{gdb} module:
2811 @item SYMBOL_LOC_UNDEF
2812 If this is returned by address class, it indicates an error either in
2813 the symbol information or in @value{GDBN}'s handling of symbols.
2815 @item SYMBOL_LOC_CONST
2816 Value is constant int.
2818 @item SYMBOL_LOC_STATIC
2819 Value is at a fixed address.
2821 @item SYMBOL_LOC_REGISTER
2822 Value is in a register.
2824 @item SYMBOL_LOC_ARG
2825 Value is an argument. This value is at the offset stored within the
2826 symbol inside the frame's argument list.
2828 @item SYMBOL_LOC_REF_ARG
2829 Value address is stored in the frame's argument list. Just like
2830 @code{LOC_ARG} except that the value's address is stored at the
2831 offset, not the value itself.
2833 @item SYMBOL_LOC_REGPARM_ADDR
2834 Value is a specified register. Just like @code{LOC_REGISTER} except
2835 the register holds the address of the argument instead of the argument
2838 @item SYMBOL_LOC_LOCAL
2839 Value is a local variable.
2841 @item SYMBOL_LOC_TYPEDEF
2842 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
2845 @item SYMBOL_LOC_BLOCK
2848 @item SYMBOL_LOC_CONST_BYTES
2849 Value is a byte-sequence.
2851 @item SYMBOL_LOC_UNRESOLVED
2852 Value is at a fixed address, but the address of the variable has to be
2853 determined from the minimal symbol table whenever the variable is
2856 @item SYMBOL_LOC_OPTIMIZED_OUT
2857 The value does not actually exist in the program.
2859 @item SYMBOL_LOC_COMPUTED
2860 The value's address is a computed location.
2863 @node Symbol Tables In Guile
2864 @subsubsection Symbol table representation in Guile.
2866 @cindex symbol tables in guile
2867 @tindex <gdb:symtab>
2870 Access to symbol table data maintained by @value{GDBN} on the inferior
2871 is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
2872 @code{<gdb:symtab>}. Symbol table and line data for a frame is returned
2873 from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
2874 @xref{Frames In Guile}.
2876 For more information on @value{GDBN}'s symbol table management, see
2877 @ref{Symbols, ,Examining the Symbol Table}.
2879 The following symtab-related procedures are provided by the
2880 @code{(gdb)} module:
2882 @deffn {Scheme Procedure} symtab? object
2883 Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
2884 Otherwise return @code{#f}.
2887 @deffn {Scheme Procedure} symtab-valid? symtab
2888 Return @code{#t} if the @code{<gdb:symtab>} object is valid,
2889 @code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
2890 the symbol table it refers to no longer exists in @value{GDBN}.
2891 All other @code{<gdb:symtab>} procedures will throw an exception
2892 if it is invalid at the time the procedure is called.
2895 @deffn {Scheme Procedure} symtab-filename symtab
2896 Return the symbol table's source filename.
2899 @deffn {Scheme Procedure} symtab-fullname symtab
2900 Return the symbol table's source absolute file name.
2903 @deffn {Scheme Procedure} symtab-objfile symtab
2904 Return the symbol table's backing object file. @xref{Objfiles In Guile}.
2907 @deffn {Scheme Procedure} symtab-global-block symtab
2908 Return the global block of the underlying symbol table.
2909 @xref{Blocks In Guile}.
2912 @deffn {Scheme Procedure} symtab-static-block symtab
2913 Return the static block of the underlying symbol table.
2914 @xref{Blocks In Guile}.
2917 The following symtab-and-line-related procedures are provided by the
2918 @code{(gdb)} module:
2920 @deffn {Scheme Procedure} sal? object
2921 Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
2922 Otherwise return @code{#f}.
2925 @deffn {Scheme Procedure} sal-valid? sal
2926 Return @code{#t} if @var{sal} is valid, @code{#f} if not.
2927 A @code{<gdb:sal>} object becomes invalid when the Symbol table object
2928 it refers to no longer exists in @value{GDBN}. All other
2929 @code{<gdb:sal>} procedures will throw an exception if it is
2930 invalid at the time the procedure is called.
2933 @deffn {Scheme Procedure} sal-symtab sal
2934 Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
2937 @deffn {Scheme Procedure} sal-line sal
2938 Return the line number for @var{sal}.
2941 @deffn {Scheme Procedure} sal-pc sal
2942 Return the start of the address range occupied by code for @var{sal}.
2945 @deffn {Scheme Procedure} sal-last sal
2946 Return the end of the address range occupied by code for @var{sal}.
2949 @deffn {Scheme Procedure} find-pc-line pc
2950 Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
2951 If an invalid value of @var{pc} is passed as an argument, then the
2952 @code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
2953 object will be @code{#f} and 0 respectively.
2956 @node Breakpoints In Guile
2957 @subsubsection Manipulating breakpoints using Guile
2959 @cindex breakpoints in guile
2960 @tindex <gdb:breakpoint>
2962 Breakpoints in Guile are represented by objects of type
2963 @code{<gdb:breakpoint>}. New breakpoints can be created with the
2964 @code{make-breakpoint} Guile function, and then added to @value{GDBN} with the
2965 @code{register-breakpoint!} Guile function.
2966 This two-step approach is taken to separate out the side-effect of adding
2967 the breakpoint to @value{GDBN} from @code{make-breakpoint}.
2969 Support is also provided to view and manipulate breakpoints created
2972 The following breakpoint-related procedures are provided by the
2973 @code{(gdb)} module:
2975 @deffn {Scheme Procedure} make-breakpoint location @w{@r{[}#:type type@r{]}} @
2976 @w{@r{[}#:wp-class wp-class@r{]}} @w{@r{[}#:internal internal@r{]}} @
2977 @w{@r{[}#:temporary temporary@r{]}}
2978 Create a new breakpoint at @var{location}, a string naming the
2979 location of the breakpoint, or an expression that defines a watchpoint.
2980 The contents can be any location recognized by the @code{break} command,
2981 or in the case of a watchpoint, by the @code{watch} command.
2983 The breakpoint is initially marked as @samp{invalid}.
2984 The breakpoint is not usable until it has been registered with @value{GDBN}
2985 with @code{register-breakpoint!}, at which point it becomes @samp{valid}.
2986 The result is the @code{<gdb:breakpoint>} object representing the breakpoint.
2988 The optional @var{type} denotes the breakpoint to create.
2989 This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
2990 and defaults to @code{BP_BREAKPOINT}.
2992 The optional @var{wp-class} argument defines the class of watchpoint to
2993 create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
2994 not provided, it is assumed to be a @code{WP_WRITE} class.
2996 The optional @var{internal} argument allows the breakpoint to become
2997 invisible to the user. The breakpoint will neither be reported when
2998 registered, nor will it be listed in the output from @code{info breakpoints}
2999 (but will be listed with the @code{maint info breakpoints} command).
3000 If an internal flag is not provided, the breakpoint is visible
3003 The optional @var{temporary} argument makes the breakpoint a temporary
3004 breakpoint. Temporary breakpoints are deleted after they have been hit,
3005 after which the Guile breakpoint is no longer usable (although it may be
3006 re-registered with @code{register-breakpoint!}).
3008 When a watchpoint is created, @value{GDBN} will try to create a
3009 hardware assisted watchpoint. If successful, the type of the watchpoint
3010 is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
3011 for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
3012 and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
3013 If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
3015 The available types are represented by constants defined in the @code{gdb}
3020 Normal code breakpoint.
3023 Watchpoint breakpoint.
3025 @item BP_HARDWARE_WATCHPOINT
3026 Hardware assisted watchpoint.
3027 This value cannot be specified when creating the breakpoint.
3029 @item BP_READ_WATCHPOINT
3030 Hardware assisted read watchpoint.
3031 This value cannot be specified when creating the breakpoint.
3033 @item BP_ACCESS_WATCHPOINT
3034 Hardware assisted access watchpoint.
3035 This value cannot be specified when creating the breakpoint.
3039 This value cannot be specified when creating the breakpoint.
3042 The available watchpoint types are represented by constants defined in the
3043 @code{(gdb)} module:
3047 Read only watchpoint.
3050 Write only watchpoint.
3053 Read/Write watchpoint.
3058 @deffn {Scheme Procedure} register-breakpoint! breakpoint
3059 Add @var{breakpoint}, a @code{<gdb:breakpoint>} object, to @value{GDBN}'s
3060 list of breakpoints. The breakpoint must have been created with
3061 @code{make-breakpoint}. One cannot register breakpoints that have been
3062 created outside of Guile. Once a breakpoint is registered it becomes
3064 It is an error to register an already registered breakpoint.
3065 The result is unspecified.
3068 @deffn {Scheme Procedure} delete-breakpoint! breakpoint
3069 Remove @var{breakpoint} from @value{GDBN}'s list of breakpoints.
3070 This also invalidates the Guile @var{breakpoint} object.
3071 Any further attempt to access the object will throw an exception.
3073 If @var{breakpoint} was created from Guile with @code{make-breakpoint}
3074 it may be re-registered with @value{GDBN}, in which case the breakpoint
3075 becomes valid again.
3078 @deffn {Scheme Procedure} breakpoints
3079 Return a list of all breakpoints.
3080 Each element of the list is a @code{<gdb:breakpoint>} object.
3083 @deffn {Scheme Procedure} breakpoint? object
3084 Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
3085 and @code{#f} otherwise.
3088 @deffn {Scheme Procedure} breakpoint-valid? breakpoint
3089 Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
3090 Breakpoints created with @code{make-breakpoint} are marked as invalid
3091 until they are registered with @value{GDBN} with @code{register-breakpoint!}.
3092 A @code{<gdb:breakpoint>} object can become invalid
3093 if the user deletes the breakpoint. In this case, the object still
3094 exists, but the underlying breakpoint does not. In the cases of
3095 watchpoint scope, the watchpoint remains valid even if execution of the
3096 inferior leaves the scope of that watchpoint.
3099 @deffn {Scheme Procedure} breakpoint-number breakpoint
3100 Return the breakpoint's number --- the identifier used by
3101 the user to manipulate the breakpoint.
3104 @deffn {Scheme Procedure} breakpoint-temporary? breakpoint
3105 Return @code{#t} if the breakpoint was created as a temporary
3106 breakpoint. Temporary breakpoints are automatically deleted after
3107 they've been hit. Calling this procedure, and all other procedures
3108 other than @code{breakpoint-valid?} and @code{register-breakpoint!},
3109 will result in an error after the breakpoint has been hit (since it has
3110 been automatically deleted).
3113 @deffn {Scheme Procedure} breakpoint-type breakpoint
3114 Return the breakpoint's type --- the identifier used to
3115 determine the actual breakpoint type or use-case.
3118 @deffn {Scheme Procedure} breakpoint-visible? breakpoint
3119 Return @code{#t} if the breakpoint is visible to the user
3120 when hit, or when the @samp{info breakpoints} command is run.
3121 Otherwise return @code{#f}.
3124 @deffn {Scheme Procedure} breakpoint-location breakpoint
3125 Return the location of the breakpoint, as specified by
3126 the user. It is a string. If the breakpoint does not have a location
3127 (that is, it is a watchpoint) return @code{#f}.
3130 @deffn {Scheme Procedure} breakpoint-expression breakpoint
3131 Return the breakpoint expression, as specified by the user. It is a string.
3132 If the breakpoint does not have an expression (the breakpoint is not a
3133 watchpoint) return @code{#f}.
3136 @deffn {Scheme Procedure} breakpoint-enabled? breakpoint
3137 Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
3140 @deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag
3141 Set the enabled state of @var{breakpoint} to @var{flag}.
3142 If flag is @code{#f} it is disabled, otherwise it is enabled.
3145 @deffn {Scheme Procedure} breakpoint-silent? breakpoint
3146 Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
3148 Note that a breakpoint can also be silent if it has commands and the
3149 first command is @code{silent}. This is not reported by the
3150 @code{silent} attribute.
3153 @deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag
3154 Set the silent state of @var{breakpoint} to @var{flag}.
3155 If flag is @code{#f} the breakpoint is made silent,
3156 otherwise it is made non-silent (or noisy).
3159 @deffn {Scheme Procedure} breakpoint-ignore-count breakpoint
3160 Return the ignore count for @var{breakpoint}.
3163 @deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count
3164 Set the ignore count for @var{breakpoint} to @var{count}.
3167 @deffn {Scheme Procedure} breakpoint-hit-count breakpoint
3168 Return hit count of @var{breakpoint}.
3171 @deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count
3172 Set the hit count of @var{breakpoint} to @var{count}.
3173 At present, @var{count} must be zero.
3176 @deffn {Scheme Procedure} breakpoint-thread breakpoint
3177 Return the global-thread-id for thread-specific breakpoint
3178 @var{breakpoint}. Return #f if @var{breakpoint} is not
3182 @deffn {Scheme Procedure} set-breakpoint-thread! breakpoint global-thread-id|#f
3183 Set the thread-id for @var{breakpoint} to @var{global-thread-id} If
3184 set to @code{#f}, the breakpoint is no longer thread-specific.
3187 @deffn {Scheme Procedure} breakpoint-task breakpoint
3188 If the breakpoint is Ada task-specific, return the Ada task id.
3189 If the breakpoint is not task-specific (or the underlying
3190 language is not Ada), return @code{#f}.
3193 @deffn {Scheme Procedure} set-breakpoint-task! breakpoint task
3194 Set the Ada task of @var{breakpoint} to @var{task}.
3195 If set to @code{#f}, the breakpoint is no longer task-specific.
3198 @deffn {Scheme Procedure} breakpoint-condition breakpoint
3199 Return the condition of @var{breakpoint}, as specified by the user.
3200 It is a string. If there is no condition, return @code{#f}.
3203 @deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition
3204 Set the condition of @var{breakpoint} to @var{condition},
3205 which must be a string. If set to @code{#f} then the breakpoint
3206 becomes unconditional.
3209 @deffn {Scheme Procedure} breakpoint-stop breakpoint
3210 Return the stop predicate of @var{breakpoint}.
3211 See @code{set-breakpoint-stop!} below in this section.
3214 @deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
3215 Set the stop predicate of @var{breakpoint}. The predicate
3216 @var{procedure} takes one argument: the <gdb:breakpoint> object.
3217 If this predicate is set to a procedure then it is invoked whenever
3218 the inferior reaches this breakpoint. If it returns @code{#t},
3219 or any non-@code{#f} value, then the inferior is stopped,
3220 otherwise the inferior will continue.
3222 If there are multiple breakpoints at the same location with a
3223 @code{stop} predicate, each one will be called regardless of the
3224 return status of the previous. This ensures that all @code{stop}
3225 predicates have a chance to execute at that location. In this scenario
3226 if one of the methods returns @code{#t} but the others return
3227 @code{#f}, the inferior will still be stopped.
3229 You should not alter the execution state of the inferior (i.e.@:, step,
3230 next, etc.), alter the current frame context (i.e.@:, change the current
3231 active frame), or alter, add or delete any breakpoint. As a general
3232 rule, you should not alter any data within @value{GDBN} or the inferior
3235 Example @code{stop} implementation:
3238 (define (my-stop? bkpt)
3239 (let ((int-val (parse-and-eval "foo")))
3240 (value=? int-val 3)))
3241 (define bkpt (make-breakpoint "main.c:42"))
3242 (register-breakpoint! bkpt)
3243 (set-breakpoint-stop! bkpt my-stop?)
3247 @deffn {Scheme Procedure} breakpoint-commands breakpoint
3248 Return the commands attached to @var{breakpoint} as a string,
3249 or @code{#f} if there are none.
3252 @node Lazy Strings In Guile
3253 @subsubsection Guile representation of lazy strings.
3255 @cindex lazy strings in guile
3256 @tindex <gdb:lazy-string>
3258 A @dfn{lazy string} is a string whose contents is not retrieved or
3259 encoded until it is needed.
3261 A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
3262 @code{address} that points to a region of memory, an @code{encoding}
3263 that will be used to encode that region of memory, and a @code{length}
3264 to delimit the region of memory that represents the string. The
3265 difference between a @code{<gdb:lazy-string>} and a string wrapped within
3266 a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
3267 differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
3268 retrieved and encoded during printing, while a @code{<gdb:value>}
3269 wrapping a string is immediately retrieved and encoded on creation.
3271 The following lazy-string-related procedures are provided by the
3272 @code{(gdb)} module:
3274 @deffn {Scheme Procedure} lazy-string? object
3275 Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
3276 Otherwise return @code{#f}.
3279 @deffn {Scheme Procedure} lazy-string-address lazy-sring
3280 Return the address of @var{lazy-string}.
3283 @deffn {Scheme Procedure} lazy-string-length lazy-string
3284 Return the length of @var{lazy-string} in characters. If the
3285 length is -1, then the string will be fetched and encoded up to the
3286 first null of appropriate width.
3289 @deffn {Scheme Procedure} lazy-string-encoding lazy-string
3290 Return the encoding that will be applied to @var{lazy-string}
3291 when the string is printed by @value{GDBN}. If the encoding is not
3292 set, or contains an empty string, then @value{GDBN} will select the
3293 most appropriate encoding when the string is printed.
3296 @deffn {Scheme Procedure} lazy-string-type lazy-string
3297 Return the type that is represented by @var{lazy-string}'s type.
3298 For a lazy string this is a pointer or array type. To
3299 resolve this to the lazy string's character type, use @code{type-target-type}.
3300 @xref{Types In Guile}.
3303 @deffn {Scheme Procedure} lazy-string->value lazy-string
3304 Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
3305 will point to the string in memory, but will lose all the delayed
3306 retrieval, encoding and handling that @value{GDBN} applies to a
3307 @code{<gdb:lazy-string>}.
3310 @node Architectures In Guile
3311 @subsubsection Guile representation of architectures
3313 @cindex guile architectures
3316 @value{GDBN} uses architecture specific parameters and artifacts in a
3317 number of its various computations. An architecture is represented
3318 by an instance of the @code{<gdb:arch>} class.
3320 The following architecture-related procedures are provided by the
3321 @code{(gdb)} module:
3323 @deffn {Scheme Procedure} arch? object
3324 Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
3325 Otherwise return @code{#f}.
3328 @deffn {Scheme Procedure} current-arch
3329 Return the current architecture as a @code{<gdb:arch>} object.
3332 @deffn {Scheme Procedure} arch-name arch
3333 Return the name (string value) of @code{<gdb:arch>} @var{arch}.
3336 @deffn {Scheme Procedure} arch-charset arch
3337 Return name of target character set of @code{<gdb:arch>} @var{arch}.
3340 @deffn {Scheme Procedure} arch-wide-charset
3341 Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
3344 Each architecture provides a set of predefined types, obtained by
3345 the following functions.
3347 @deffn {Scheme Procedure} arch-void-type arch
3348 Return the @code{<gdb:type>} object for a @code{void} type
3349 of architecture @var{arch}.
3352 @deffn {Scheme Procedure} arch-char-type arch
3353 Return the @code{<gdb:type>} object for a @code{char} type
3354 of architecture @var{arch}.
3357 @deffn {Scheme Procedure} arch-short-type arch
3358 Return the @code{<gdb:type>} object for a @code{short} type
3359 of architecture @var{arch}.
3362 @deffn {Scheme Procedure} arch-int-type arch
3363 Return the @code{<gdb:type>} object for an @code{int} type
3364 of architecture @var{arch}.
3367 @deffn {Scheme Procedure} arch-long-type arch
3368 Return the @code{<gdb:type>} object for a @code{long} type
3369 of architecture @var{arch}.
3372 @deffn {Scheme Procedure} arch-schar-type arch
3373 Return the @code{<gdb:type>} object for a @code{signed char} type
3374 of architecture @var{arch}.
3377 @deffn {Scheme Procedure} arch-uchar-type arch
3378 Return the @code{<gdb:type>} object for an @code{unsigned char} type
3379 of architecture @var{arch}.
3382 @deffn {Scheme Procedure} arch-ushort-type arch
3383 Return the @code{<gdb:type>} object for an @code{unsigned short} type
3384 of architecture @var{arch}.
3387 @deffn {Scheme Procedure} arch-uint-type arch
3388 Return the @code{<gdb:type>} object for an @code{unsigned int} type
3389 of architecture @var{arch}.
3392 @deffn {Scheme Procedure} arch-ulong-type arch
3393 Return the @code{<gdb:type>} object for an @code{unsigned long} type
3394 of architecture @var{arch}.
3397 @deffn {Scheme Procedure} arch-float-type arch
3398 Return the @code{<gdb:type>} object for a @code{float} type
3399 of architecture @var{arch}.
3402 @deffn {Scheme Procedure} arch-double-type arch
3403 Return the @code{<gdb:type>} object for a @code{double} type
3404 of architecture @var{arch}.
3407 @deffn {Scheme Procedure} arch-longdouble-type arch
3408 Return the @code{<gdb:type>} object for a @code{long double} type
3409 of architecture @var{arch}.
3412 @deffn {Scheme Procedure} arch-bool-type arch
3413 Return the @code{<gdb:type>} object for a @code{bool} type
3414 of architecture @var{arch}.
3417 @deffn {Scheme Procedure} arch-longlong-type arch
3418 Return the @code{<gdb:type>} object for a @code{long long} type
3419 of architecture @var{arch}.
3422 @deffn {Scheme Procedure} arch-ulonglong-type arch
3423 Return the @code{<gdb:type>} object for an @code{unsigned long long} type
3424 of architecture @var{arch}.
3427 @deffn {Scheme Procedure} arch-int8-type arch
3428 Return the @code{<gdb:type>} object for an @code{int8} type
3429 of architecture @var{arch}.
3432 @deffn {Scheme Procedure} arch-uint8-type arch
3433 Return the @code{<gdb:type>} object for a @code{uint8} type
3434 of architecture @var{arch}.
3437 @deffn {Scheme Procedure} arch-int16-type arch
3438 Return the @code{<gdb:type>} object for an @code{int16} type
3439 of architecture @var{arch}.
3442 @deffn {Scheme Procedure} arch-uint16-type arch
3443 Return the @code{<gdb:type>} object for a @code{uint16} type
3444 of architecture @var{arch}.
3447 @deffn {Scheme Procedure} arch-int32-type arch
3448 Return the @code{<gdb:type>} object for an @code{int32} type
3449 of architecture @var{arch}.
3452 @deffn {Scheme Procedure} arch-uint32-type arch
3453 Return the @code{<gdb:type>} object for a @code{uint32} type
3454 of architecture @var{arch}.
3457 @deffn {Scheme Procedure} arch-int64-type arch
3458 Return the @code{<gdb:type>} object for an @code{int64} type
3459 of architecture @var{arch}.
3462 @deffn {Scheme Procedure} arch-uint64-type arch
3463 Return the @code{<gdb:type>} object for a @code{uint64} type
3464 of architecture @var{arch}.
3470 (gdb) guile (type-name (arch-uchar-type (current-arch)))
3474 @node Disassembly In Guile
3475 @subsubsection Disassembly In Guile
3477 The disassembler can be invoked from Scheme code.
3478 Furthermore, the disassembler can take a Guile port as input,
3479 allowing one to disassemble from any source, and not just target memory.
3481 @deffn {Scheme Procedure} arch-disassemble arch start-pc @
3482 @w{@r{[}#:port port@r{]}} @w{@r{[}#:offset offset@r{]}} @
3483 @w{@r{[}#:size size@r{]}} @w{@r{[}#:count count@r{]}}
3484 Return a list of disassembled instructions starting from the memory
3485 address @var{start-pc}.
3487 The optional argument @var{port} specifies the input port to read bytes from.
3488 If @var{port} is @code{#f} then bytes are read from target memory.
3490 The optional argument @var{offset} specifies the address offset of the
3491 first byte in @var{port}. This is useful, for example, when @var{port}
3492 specifies a @samp{bytevector} and you want the bytevector to be disassembled
3493 as if it came from that address. The @var{start-pc} passed to the reader
3494 for @var{port} is offset by the same amount.
3498 (gdb) guile (use-modules (rnrs io ports))
3499 (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
3500 (gdb) guile (define mem (open-memory #:start pc))
3501 (gdb) guile (define bv (get-bytevector-n mem 10))
3502 (gdb) guile (define bv-port (open-bytevector-input-port bv))
3503 (gdb) guile (define arch (current-arch))
3504 (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
3505 (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
3508 The optional arguments @var{size} and
3509 @var{count} determine the number of instructions in the returned list.
3510 If either @var{size} or @var{count} is specified as zero, then
3511 no instructions are disassembled and an empty list is returned.
3512 If both the optional arguments @var{size} and @var{count} are
3513 specified, then a list of at most @var{count} disassembled instructions
3514 whose start address falls in the closed memory address interval from
3515 @var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
3516 If @var{size} is not specified, but @var{count} is specified,
3517 then @var{count} number of instructions starting from the address
3518 @var{start-pc} are returned. If @var{count} is not specified but
3519 @var{size} is specified, then all instructions whose start address
3520 falls in the closed memory address interval from @var{start-pc} to
3521 (@var{start-pc} + @var{size} - 1) are returned.
3522 If neither @var{size} nor @var{count} are specified, then a single
3523 instruction at @var{start-pc} is returned.
3525 Each element of the returned list is an alist (associative list)
3526 with the following keys:
3531 The value corresponding to this key is a Guile integer of
3532 the memory address of the instruction.
3535 The value corresponding to this key is a string value which represents
3536 the instruction with assembly language mnemonics. The assembly
3537 language flavor used is the same as that specified by the current CLI
3538 variable @code{disassembly-flavor}. @xref{Machine Code}.
3541 The value corresponding to this key is the length of the instruction in bytes.
3546 @node I/O Ports in Guile
3547 @subsubsection I/O Ports in Guile
3549 @deffn {Scheme Procedure} input-port
3550 Return @value{GDBN}'s input port as a Guile port object.
3553 @deffn {Scheme Procedure} output-port
3554 Return @value{GDBN}'s output port as a Guile port object.
3557 @deffn {Scheme Procedure} error-port
3558 Return @value{GDBN}'s error port as a Guile port object.
3561 @deffn {Scheme Procedure} stdio-port? object
3562 Return @code{#t} if @var{object} is a @value{GDBN} stdio port.
3563 Otherwise return @code{#f}.
3566 @node Memory Ports in Guile
3567 @subsubsection Memory Ports in Guile
3569 @value{GDBN} provides a @code{port} interface to target memory.
3570 This allows Guile code to read/write target memory using Guile's port and
3571 bytevector functionality. The main routine is @code{open-memory} which
3572 returns a port object. One can then read/write memory using that object.
3574 @deffn {Scheme Procedure} open-memory @w{@r{[}#:mode mode@r{]}} @
3575 @w{@r{[}#:start address@r{]}} @w{@r{[}#:size size@r{]}}
3576 Return a port object that can be used for reading and writing memory.
3577 The port will be open according to @var{mode}, which is the standard
3578 mode argument to Guile port open routines, except that the @samp{"a"}
3579 and @samp{"l"} modes are not supported.
3580 @xref{File Ports,,, guile, GNU Guile Reference Manual}.
3581 The @samp{"b"} (binary) character may be present, but is ignored:
3582 memory ports are binary only. If @samp{"0"} is appended then
3583 the port is marked as unbuffered.
3584 The default is @samp{"r"}, read-only and buffered.
3586 The chunk of memory that can be accessed can be bounded.
3587 If both @var{start} and @var{size} are unspecified, all of memory can be
3588 accessed. If only @var{start} is specified, all of memory from that point
3589 on can be accessed. If only @var{size} if specified, all memory in the
3590 range [0,@var{size}) can be accessed. If both are specified, all memory
3591 in the rane [@var{start},@var{start}+@var{size}) can be accessed.
3594 @deffn {Scheme Procedure} memory-port?
3595 Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
3596 Otherwise return @code{#f}.
3599 @deffn {Scheme Procedure} memory-port-range memory-port
3600 Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
3601 of two elements: @code{(start end)}. The range is @var{start} to @var{end}
3605 @deffn {Scheme Procedure} memory-port-read-buffer-size memory-port
3606 Return the size of the read buffer of @code{<gdb:memory-port>}
3609 This procedure is deprecated and will be removed in @value{GDBN} 11.
3610 It returns 0 when using Guile 2.2 or later.
3613 @deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
3614 Set the size of the read buffer of @code{<gdb:memory-port>}
3615 @var{memory-port} to @var{size}. The result is unspecified.
3617 This procedure is deprecated and will be removed in @value{GDBN} 11.
3618 When @value{GDBN} is built with Guile 2.2 or later, you can call
3619 @code{setvbuf} instead (@pxref{Buffering, @code{setvbuf},, guile, GNU
3620 Guile Reference Manual}).
3623 @deffn {Scheme Procedure} memory-port-write-buffer-size memory-port
3624 Return the size of the write buffer of @code{<gdb:memory-port>}
3627 This procedure is deprecated and will be removed in @value{GDBN} 11.
3628 It returns 0 when @value{GDBN} is built with Guile 2.2 or later.
3631 @deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
3632 Set the size of the write buffer of @code{<gdb:memory-port>}
3633 @var{memory-port} to @var{size}. The result is unspecified.
3635 This procedure is deprecated and will be removed in @value{GDBN} 11.
3636 When @value{GDBN} is built with Guile 2.2 or later, you can call
3637 @code{setvbuf} instead.
3640 A memory port is closed like any other port, with @code{close-port}.
3642 Combined with Guile's @code{bytevectors}, memory ports provide a lot
3643 of utility. For example, to fill a buffer of 10 integers in memory,
3644 one can do something like the following.
3647 ;; In the program: int buffer[10];
3648 (use-modules (rnrs bytevectors))
3649 (use-modules (rnrs io ports))
3650 (define addr (parse-and-eval "buffer"))
3652 (define byte-size (* n 4))
3653 (define mem-port (open-memory #:mode "r+" #:start
3654 (value->integer addr) #:size byte-size))
3655 (define byte-vec (make-bytevector byte-size))
3658 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
3659 (put-bytevector mem-port byte-vec)
3660 (close-port mem-port)
3663 @node Iterators In Guile
3664 @subsubsection Iterators In Guile
3666 @cindex guile iterators
3667 @tindex <gdb:iterator>
3669 A simple iterator facility is provided to allow, for example,
3670 iterating over the set of program symbols without having to first
3671 construct a list of all of them. A useful contribution would be
3672 to add support for SRFI 41 and SRFI 45.
3674 @deffn {Scheme Procedure} make-iterator object progress next!
3675 A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
3676 procedure. It takes three arguments: the object to be iterated over,
3677 an object to record the progress of the iteration, and a procedure to
3678 return the next element in the iteration, or an implementation chosen value
3679 to denote the end of iteration.
3681 By convention, end of iteration is marked with @code{(end-of-iteration)},
3682 and may be tested with the @code{end-of-iteration?} predicate.
3683 The result of @code{(end-of-iteration)} is chosen so that it is not
3684 otherwise used by the @code{(gdb)} module. If you are using
3685 @code{<gdb:iterator>} in your own code it is your responsibility to
3686 maintain this invariant.
3688 A trivial example for illustration's sake:
3691 (use-modules (gdb iterator))
3692 (define my-list (list 1 2 3))
3694 (make-iterator my-list my-list
3696 (let ((l (iterator-progress iter)))
3700 (set-iterator-progress! iter (cdr l))
3704 Here is a slightly more realistic example, which computes a list of all the
3705 functions in @code{my-global-block}.
3708 (use-modules (gdb iterator))
3709 (define this-sal (find-pc-line (frame-pc (selected-frame))))
3710 (define this-symtab (sal-symtab this-sal))
3711 (define this-global-block (symtab-global-block this-symtab))
3712 (define syms-iter (make-block-symbols-iterator this-global-block))
3713 (define functions (iterator-filter symbol-function? syms-iter))
3717 @deffn {Scheme Procedure} iterator? object
3718 Return @code{#t} if @var{object} is a @code{<gdb:iterator>} object.
3719 Otherwise return @code{#f}.
3722 @deffn {Scheme Procedure} iterator-object iterator
3723 Return the first argument that was passed to @code{make-iterator}.
3724 This is the object being iterated over.
3727 @deffn {Scheme Procedure} iterator-progress iterator
3728 Return the object tracking iteration progress.
3731 @deffn {Scheme Procedure} set-iterator-progress! iterator new-value
3732 Set the object tracking iteration progress.
3735 @deffn {Scheme Procedure} iterator-next! iterator
3736 Invoke the procedure that was the third argument to @code{make-iterator},
3737 passing it one argument, the @code{<gdb:iterator>} object.
3738 The result is either the next element in the iteration, or an end
3739 marker as implemented by the @code{next!} procedure.
3740 By convention the end marker is the result of @code{(end-of-iteration)}.
3743 @deffn {Scheme Procedure} end-of-iteration
3744 Return the Scheme object that denotes end of iteration.
3747 @deffn {Scheme Procedure} end-of-iteration? object
3748 Return @code{#t} if @var{object} is the end of iteration marker.
3749 Otherwise return @code{#f}.
3752 These functions are provided by the @code{(gdb iterator)} module to
3753 assist in using iterators.
3755 @deffn {Scheme Procedure} make-list-iterator list
3756 Return a @code{<gdb:iterator>} object that will iterate over @var{list}.
3759 @deffn {Scheme Procedure} iterator->list iterator
3760 Return the elements pointed to by @var{iterator} as a list.
3763 @deffn {Scheme Procedure} iterator-map proc iterator
3764 Return the list of objects obtained by applying @var{proc} to the object
3765 pointed to by @var{iterator} and to each subsequent object.
3768 @deffn {Scheme Procedure} iterator-for-each proc iterator
3769 Apply @var{proc} to each element pointed to by @var{iterator}.
3770 The result is unspecified.
3773 @deffn {Scheme Procedure} iterator-filter pred iterator
3774 Return the list of elements pointed to by @var{iterator} that satisfy
3778 @deffn {Scheme Procedure} iterator-until pred iterator
3779 Run @var{iterator} until the result of @code{(pred element)} is true
3780 and return that as the result. Otherwise return @code{#f}.
3783 @node Guile Auto-loading
3784 @subsection Guile Auto-loading
3785 @cindex guile auto-loading
3787 When a new object file is read (for example, due to the @code{file}
3788 command, or because the inferior has loaded a shared library),
3789 @value{GDBN} will look for Guile support scripts in two ways:
3790 @file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
3791 @xref{Auto-loading extensions}.
3793 The auto-loading feature is useful for supplying application-specific
3794 debugging commands and scripts.
3796 Auto-loading can be enabled or disabled,
3797 and the list of auto-loaded scripts can be printed.
3800 @anchor{set auto-load guile-scripts}
3801 @kindex set auto-load guile-scripts
3802 @item set auto-load guile-scripts [on|off]
3803 Enable or disable the auto-loading of Guile scripts.
3805 @anchor{show auto-load guile-scripts}
3806 @kindex show auto-load guile-scripts
3807 @item show auto-load guile-scripts
3808 Show whether auto-loading of Guile scripts is enabled or disabled.
3810 @anchor{info auto-load guile-scripts}
3811 @kindex info auto-load guile-scripts
3812 @cindex print list of auto-loaded Guile scripts
3813 @item info auto-load guile-scripts [@var{regexp}]
3814 Print the list of all Guile scripts that @value{GDBN} auto-loaded.
3816 Also printed is the list of Guile scripts that were mentioned in
3817 the @code{.debug_gdb_scripts} section and were not found.
3818 This is useful because their names are not printed when @value{GDBN}
3819 tries to load them and fails. There may be many of them, and printing
3820 an error message for each one is problematic.
3822 If @var{regexp} is supplied only Guile scripts with matching names are printed.
3827 (gdb) info auto-load guile-scripts
3829 Yes scm-section-script.scm
3830 full name: /tmp/scm-section-script.scm
3831 No my-foo-pretty-printers.scm
3835 When reading an auto-loaded file, @value{GDBN} sets the
3836 @dfn{current objfile}. This is available via the @code{current-objfile}
3837 procedure (@pxref{Objfiles In Guile}). This can be useful for
3838 registering objfile-specific pretty-printers.
3841 @subsection Guile Modules
3842 @cindex guile modules
3844 @value{GDBN} comes with several modules to assist writing Guile code.
3847 * Guile Printing Module:: Building and registering pretty-printers
3848 * Guile Types Module:: Utilities for working with types
3851 @node Guile Printing Module
3852 @subsubsection Guile Printing Module
3854 This module provides a collection of utilities for working with
3860 (use-modules (gdb printing))
3863 @deffn {Scheme Procedure} prepend-pretty-printer! object printer
3864 Add @var{printer} to the front of the list of pretty-printers for
3865 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3866 or @code{#f} in which case @var{printer} is added to the global list of
3870 @deffn {Scheme Procecure} append-pretty-printer! object printer
3871 Add @var{printer} to the end of the list of pretty-printers for
3872 @var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
3873 or @code{#f} in which case @var{printer} is added to the global list of
3877 @node Guile Types Module
3878 @subsubsection Guile Types Module
3880 This module provides a collection of utilities for working with
3881 @code{<gdb:type>} objects.
3886 (use-modules (gdb types))
3889 @deffn {Scheme Procedure} get-basic-type type
3890 Return @var{type} with const and volatile qualifiers stripped,
3891 and with typedefs and C@t{++} references converted to the underlying type.
3896 typedef const int const_int;
3898 const_int& foo_ref (foo);
3899 int main () @{ return 0; @}
3906 (gdb) guile (use-modules (gdb) (gdb types))
3907 (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
3908 (gdb) guile (get-basic-type (value-type foo-ref))
3913 @deffn {Scheme Procedure} type-has-field-deep? type field
3914 Return @code{#t} if @var{type}, assumed to be a type with fields
3915 (e.g., a structure or union), has field @var{field}.
3916 Otherwise return @code{#f}.
3917 This searches baseclasses, whereas @code{type-has-field?} does not.
3920 @deffn {Scheme Procedure} make-enum-hashtable enum-type
3921 Return a Guile hash table produced from @var{enum-type}.
3922 Elements in the hash table are referenced with @code{hashq-ref}.