gdb smob cleanups
[deliverable/binutils-gdb.git] / gdb / doc / guile.texi
CommitLineData
ed3ef339
DE
1@c Copyright (C) 2008-2014 Free Software Foundation, Inc.
2@c Permission is granted to copy, distribute and/or modify this document
3@c under the terms of the GNU Free Documentation License, Version 1.3 or
4@c any later version published by the Free Software Foundation; with the
5@c Invariant Sections being ``Free Software'' and ``Free Software Needs
6@c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7@c and with the Back-Cover Texts as in (a) below.
8@c
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.''
12
13@node Guile
14@section Extending @value{GDBN} using Guile
15@cindex guile scripting
16@cindex scripting with guile
17
18You can extend @value{GDBN} using the @uref{http://www.gnu.org/software/guile/,
19Guile implementation of the Scheme programming language}.
20This feature is available only if @value{GDBN} was configured using
21@option{--with-guile}.
22
23@menu
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}
29@end menu
30
31@node Guile Introduction
32@subsection Guile Introduction
33
34Guile is an implementation of the Scheme programming language
35and is the GNU project's official extension language.
36
37Guile support in @value{GDBN} follows the Python support in @value{GDBN}
38reasonably closely, so concepts there should carry over.
39However, some things are done differently where it makes sense.
40
41@value{GDBN} requires Guile version 2.0 or greater.
42Older versions are not supported.
43
44@cindex guile scripts directory
45Guile scripts used by @value{GDBN} should be installed in
46@file{@var{data-directory}/guile}, where @var{data-directory} is
47the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
48This directory, known as the @dfn{guile directory},
49is automatically added to the Guile Search Path in order to allow
50the Guile interpreter to locate all scripts installed at this location.
51
52@node Guile Commands
53@subsection Guile Commands
54@cindex guile commands
55@cindex commands to access guile
56
57@value{GDBN} provides two commands for accessing the Guile interpreter:
58
59@table @code
60@kindex guile-repl
61@kindex gr
62@item guile-repl
63@itemx gr
64The @code{guile-repl} command can be used to start an interactive
65Guile prompt or @dfn{repl}. To return to @value{GDBN},
66type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on
67an empty prompt). These commands do not take any arguments.
68
69@kindex guile
70@kindex gu
71@item guile @r{[}@var{scheme-expression}@r{]}
72@itemx gu @r{[}@var{scheme-expression}@r{]}
73The @code{guile} command can be used to evaluate a Scheme expression.
74
75If given an argument, @value{GDBN} will pass the argument to the Guile
76interpreter for evaluation.
77
78@smallexample
79(@value{GDBP}) guile (display (+ 20 3)) (newline)
8023
81@end smallexample
82
83The result of the Scheme expression is displayed using normal Guile rules.
84
85@smallexample
86(@value{GDBP}) guile (+ 20 3)
8723
88@end smallexample
89
90If you do not provide an argument to @code{guile}, it will act as a
91multi-line command, like @code{define}. In this case, the Guile
92script is made up of subsequent command lines, given after the
93@code{guile} command. This command list is terminated using a line
94containing @code{end}. For example:
95
96@smallexample
97(@value{GDBP}) guile
98>(display 23)
99>(newline)
100>end
10123
102@end smallexample
103@end table
104
105It is also possible to execute a Guile script from the @value{GDBN}
106interpreter:
107
108@table @code
109@item source @file{script-name}
110The script name must end with @samp{.scm} and @value{GDBN} must be configured
111to recognize the script language based on filename extension using
112the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
113
114@item guile (load "script-name")
115This method uses the @code{load} Guile function.
116It takes a string argument that is the name of the script to load.
117See the Guile documentation for a description of this function.
118(@pxref{Loading,,, guile, GNU Guile Reference Manual}).
119@end table
120
121@node Guile API
122@subsection Guile API
123@cindex guile api
124@cindex programming in guile
125
126You can get quick online help for @value{GDBN}'s Guile API by issuing
127the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help}
128from an interactive Guile session. Furthermore, most Guile procedures
129provided by @value{GDBN} have doc strings which can be obtained with
130@kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}}
131from the Guile interactive prompt.
132
133@menu
134* Basic Guile:: Basic Guile Functions
135* Guile Configuration:: Guile configuration variables
136* GDB Scheme Data Types:: Scheme representations of GDB objects
137* Guile Exception Handling:: How Guile exceptions are translated
138* Values From Inferior In Guile:: Guile representation of values
139* Arithmetic In Guile:: Arithmetic in Guile
140* Types In Guile:: Guile representation of types
141* Guile Pretty Printing API:: Pretty-printing values with Guile
142* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
143* Writing a Guile Pretty-Printer:: Writing a pretty-printer
144* Objfiles In Guile:: Object files in Guile
145* Frames In Guile:: Accessing inferior stack frames from Guile
146* Blocks In Guile:: Accessing blocks from Guile
147* Symbols In Guile:: Guile representation of symbols
148* Symbol Tables In Guile:: Guile representation of symbol tables
149* Breakpoints In Guile:: Manipulating breakpoints using Guile
150* Lazy Strings In Guile:: Guile representation of lazy strings
151* Architectures In Guile:: Guile representation of architectures
152* Disassembly In Guile:: Disassembling instructions from Guile
153* I/O Ports in Guile:: GDB I/O ports
154* Memory Ports in Guile:: Accessing memory through ports and bytevectors
155* Iterators In Guile:: Basic iterator support
156@end menu
157
158@node Basic Guile
159@subsubsection Basic Guile
160
161@cindex guile stdout
162@cindex guile pagination
163At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
164@code{current-error-port} to print using @value{GDBN}'s output-paging streams.
165A Guile program which outputs to one of these streams may have its
166output interrupted by the user (@pxref{Screen Size}). In this
167situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
168
169Guile's history mechanism uses the same naming as @value{GDBN}'s,
170namely the user of dollar-variables (e.g., $1, $2, etc.).
171The results of evaluations in Guile and in GDB are counted separately,
172@code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}.
173
174@value{GDBN} is not thread-safe. If your Guile program uses multiple
175threads, you must be careful to only call @value{GDBN}-specific
176functions in the @value{GDBN} thread.
177
178Some care must be taken when writing Guile code to run in
179@value{GDBN}. Two things are worth noting in particular:
180
181@itemize @bullet
182@item
183@value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
184Guile code must not override these, or even change the options using
185@code{sigaction}. If your program changes the handling of these
186signals, @value{GDBN} will most likely stop working correctly. Note
187that it is unfortunately common for GUI toolkits to install a
188@code{SIGCHLD} handler.
189
190@item
191@value{GDBN} takes care to mark its internal file descriptors as
192close-on-exec. However, this cannot be done in a thread-safe way on
193all platforms. Your Guile programs should be aware of this and
194should both create new file descriptors with the close-on-exec flag
195set and arrange to close unneeded file descriptors before starting a
196child process.
197@end itemize
198
199@cindex guile gdb module
200@value{GDBN} introduces a new Guile module, named @code{gdb}. All
201methods and classes added by @value{GDBN} are placed in this module.
202@value{GDBN} does not automatically @code{import} the @code{gdb} module,
203scripts must do this themselves. There are various options for how to
204import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
205module is imported to the user.
206To simplify interactive use, it is recommended to add one of the following
207to your ~/.gdbinit.
208
209@smallexample
210guile (use-modules (gdb))
211@end smallexample
212
213@smallexample
214guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
215@end smallexample
216
217Which one to choose depends on your preference.
218The second one adds @code{gdb:} as a prefix to all module functions
219and variables.
220
221The rest of this manual assumes the @code{gdb} module has been imported
222without any prefix. See the Guile documentation for @code{use-modules}
223for more information
224(@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}).
225
226Example:
227
228@smallexample
229(gdb) guile (value-type (make-value 1))
230ERROR: Unbound variable: value-type
231Error while executing Scheme code.
232(gdb) guile (use-modules (gdb))
233(gdb) guile (value-type (make-value 1))
234int
235(gdb)
236@end smallexample
237
238The @code{(gdb)} module provides these basic Guile functions.
239
240@c TODO: line length
9eaa4c1e 241@deffn {Scheme Procedure} execute command @r{[}#:from-tty boolean@r{]} @r{[}#:to-string boolean@r{]}
ed3ef339
DE
242Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
243If a @value{GDBN} exception happens while @var{command} runs, it is
244translated as described in
245@ref{Guile Exception Handling,,Guile Exception Handling}.
246
247@var{from-tty} specifies whether @value{GDBN} ought to consider this
248command as having originated from the user invoking it interactively.
249It must be a boolean value. If omitted, it defaults to @code{#f}.
250
251By default, any output produced by @var{command} is sent to
252@value{GDBN}'s standard output (and to the log output if logging is
253turned on). If the @var{to-string} parameter is
9eaa4c1e 254@code{#t}, then output will be collected by @code{execute} and
ed3ef339
DE
255returned as a string. The default is @code{#f}, in which case the
256return value is unspecified. If @var{to-string} is @code{#t}, the
257@value{GDBN} virtual terminal will be temporarily set to unlimited width
258and height, and its pagination will be disabled; @pxref{Screen Size}.
259@end deffn
260
261@deffn {Scheme Procedure} history-ref number
262Return a value from @value{GDBN}'s value history (@pxref{Value
697aa1b7 263History}). The @var{number} argument indicates which history element to return.
ed3ef339
DE
264If @var{number} is negative, then @value{GDBN} will take its absolute value
265and count backward from the last element (i.e., the most recent element) to
266find the value to return. If @var{number} is zero, then @value{GDBN} will
267return the most recent element. If the element specified by @var{number}
268doesn't exist in the value history, a @code{gdb:error} exception will be
269raised.
270
271If no exception is raised, the return value is always an instance of
272@code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
273
274@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
275@code{$1} in @value{GDBN}'s value history contains the result of evaluating
276an expression from @value{GDBN}'s command line and @code{$1} from Guile's
277history contains the result of evaluating an expression from Guile's
278command line.
279@end deffn
280
7a5a839f
LC
281@deffn {Scheme Procedure} history-append! value
282Append @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
283value history. Return its index in the history.
284
285Putting into history values returned by Guile extensions will allow
286the user convenient access to those values via CLI history
287facilities.
288@end deffn
289
ed3ef339
DE
290@deffn {Scheme Procedure} parse-and-eval expression
291Parse @var{expression} as an expression in the current language,
292evaluate it, and return the result as a @code{<gdb:value>}.
697aa1b7 293The @var{expression} must be a string.
ed3ef339
DE
294
295This function is useful when computing values.
296For example, it is the only way to get the value of a
297convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
298@end deffn
299
300@deffn {Scheme Procedure} string->argv string
301Convert a string to a list of strings split up according to
302@value{GDBN}'s argv parsing rules.
303@end deffn
304
305@node Guile Configuration
306@subsubsection Guile Configuration
307@cindex guile configuration
308
309@value{GDBN} provides these Scheme functions to access various configuration
310parameters.
311
312@deffn {Scheme Procedure} data-directory
313Return a string containing @value{GDBN}'s data directory.
314This directory contains @value{GDBN}'s ancillary files, including
315the Guile modules provided by @value{GDBN}.
316@end deffn
317
318@deffn {Scheme Procedure} gdb-version
319Return a string containing the @value{GDBN} version.
320@end deffn
321
322@deffn {Scheme Procedure} host-config
323Return a string containing the host configuration.
324This is the string passed to @code{--host} when @value{GDBN} was configured.
325@end deffn
326
327@deffn {Scheme Procedure} target-config
328Return a string containing the target configuration.
329This is the string passed to @code{--target} when @value{GDBN} was configured.
330@end deffn
331
332@node GDB Scheme Data Types
333@subsubsection GDB Scheme Data Types
b2715b27 334@cindex gdb objects
ed3ef339 335
b2715b27
AW
336The values exposed by @value{GDBN} to Guile are known as
337@dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN}
338object, and each is disjoint from all other types known to Guile.
ed3ef339 339
b2715b27
AW
340@deffn {Scheme Procedure} gdb-object-kind object
341Return the kind of the @value{GDBN} object, e.g., @code{<gdb:breakpoint>},
ed3ef339
DE
342as a symbol.
343@end deffn
344
b2715b27 345@value{GDBN} defines the following object types:
ed3ef339
DE
346
347@table @code
348@item <gdb:arch>
349@xref{Architectures In Guile}.
350
351@item <gdb:block>
352@xref{Blocks In Guile}.
353
354@item <gdb:block-symbols-iterator>
355@xref{Blocks In Guile}.
356
357@item <gdb:breakpoint>
358@xref{Breakpoints In Guile}.
359
360@item <gdb:exception>
361@xref{Guile Exception Handling}.
362
363@item <gdb:frame>
364@xref{Frames In Guile}.
365
366@item <gdb:iterator>
367@xref{Iterators In Guile}.
368
369@item <gdb:lazy-string>
370@xref{Lazy Strings In Guile}.
371
372@item <gdb:objfile>
373@xref{Objfiles In Guile}.
374
375@item <gdb:pretty-printer>
376@xref{Guile Pretty Printing API}.
377
378@item <gdb:pretty-printer-worker>
379@xref{Guile Pretty Printing API}.
380
381@item <gdb:symbol>
382@xref{Symbols In Guile}.
383
384@item <gdb:symtab>
385@xref{Symbol Tables In Guile}.
386
387@item <gdb:sal>
388@xref{Symbol Tables In Guile}.
389
390@item <gdb:type>
391@xref{Types In Guile}.
392
393@item <gdb:field>
394@xref{Types In Guile}.
395
396@item <gdb:value>
397@xref{Values From Inferior In Guile}.
398@end table
399
b2715b27
AW
400The following @value{GDBN} objects are managed internally so that the
401Scheme function @code{eq?} may be applied to them.
ed3ef339
DE
402
403@table @code
404@item <gdb:arch>
405@item <gdb:block>
406@item <gdb:breakpoint>
407@item <gdb:frame>
408@item <gdb:objfile>
409@item <gdb:symbol>
410@item <gdb:symtab>
411@item <gdb:type>
412@end table
413
414@node Guile Exception Handling
415@subsubsection Guile Exception Handling
416@cindex guile exceptions
417@cindex exceptions, guile
418@kindex set guile print-stack
419
420When executing the @code{guile} command, Guile exceptions
421uncaught within the Guile code are translated to calls to the
422@value{GDBN} error-reporting mechanism. If the command that called
423@code{guile} does not handle the error, @value{GDBN} will
424terminate it and report the error according to the setting of
425the @code{guile print-stack} parameter.
426
427The @code{guile print-stack} parameter has three settings:
428
429@table @code
430@item none
431Nothing is printed.
432
433@item message
434An error message is printed containing the Guile exception name,
435the associated value, and the Guile call stack backtrace at the
436point where the exception was raised. Example:
437
438@smallexample
439(@value{GDBP}) guile (display foo)
440ERROR: In procedure memoize-variable-access!:
441ERROR: Unbound variable: foo
442Error while executing Scheme code.
443@end smallexample
444
445@item full
446In addition to an error message a full backtrace is printed.
447
448@smallexample
449(@value{GDBP}) set guile print-stack full
450(@value{GDBP}) guile (display foo)
451Guile Backtrace:
452In ice-9/boot-9.scm:
453 157: 10 [catch #t #<catch-closure 2c76e20> ...]
454In unknown file:
455 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
456In ice-9/boot-9.scm:
457 157: 8 [catch #t #<catch-closure 2c76d20> ...]
458In unknown file:
459 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
460 ?: 6 [call-with-input-string "(display foo)" ...]
461In ice-9/boot-9.scm:
4622320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
463In ice-9/eval-string.scm:
464 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
465 37: 3 [lp (display foo)]
466In ice-9/eval.scm:
467 387: 2 [eval # ()]
468 393: 1 [eval #<memoized foo> ()]
469In unknown file:
470 ?: 0 [memoize-variable-access! #<memoized foo> ...]
471
472ERROR: In procedure memoize-variable-access!:
473ERROR: Unbound variable: foo
474Error while executing Scheme code.
475@end smallexample
476@end table
477
478@value{GDBN} errors that happen in @value{GDBN} commands invoked by
479Guile code are converted to Guile exceptions. The type of the
480Guile exception depends on the error.
481
482Guile procedures provided by @value{GDBN} can throw the standard
483Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
484
485User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
486prompt) is translated to a Guile @code{signal} exception with value
487@code{SIGINT}.
488
489@value{GDBN} Guile procedures can also throw these exceptions:
490
491@vtable @code
492@item gdb:error
493This exception is a catch-all for errors generated from within @value{GDBN}.
494
495@item gdb:invalid-object
496This exception is thrown when accessing Guile objects that wrap underlying
497@value{GDBN} objects have become invalid. For example, a
498@code{<gdb:breakpoint>} object becomes invalid if the user deletes it
499from the command line. The object still exists in Guile, but the
500object it represents is gone. Further operations on this breakpoint
501will throw this exception.
502
503@item gdb:memory-error
504This exception is thrown when an operation tried to access invalid
505memory in the inferior.
506
507@item gdb:pp-type-error
508This exception is thrown when a Guile pretty-printer passes a bad object
509to @value{GDBN}.
510@end vtable
511
512The following exception-related procedures are provided by the
513@code{(gdb)} module.
514
515@deffn {Scheme Procedure} make-exception key args
697aa1b7
EZ
516Return a @code{<gdb:exception>} object given by its @var{key} and
517@var{args}, which are the standard Guile parameters of an exception.
518See the Guile documentation for more information (@pxref{Exceptions,,,
519guile, GNU Guile Reference Manual}).
ed3ef339
DE
520@end deffn
521
522@deffn {Scheme Procedure} exception? object
523Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
524Otherwise return @code{#f}.
525@end deffn
526
527@deffn {Scheme Procedure} exception-key exception
528Return the @var{args} field of a @code{<gdb:exception>} object.
529@end deffn
530
531@deffn {Scheme Procedure} exception-args exception
532Return the @var{args} field of a @code{<gdb:exception>} object.
533@end deffn
534
535@node Values From Inferior In Guile
536@subsubsection Values From Inferior In Guile
537@cindex values from inferior, in guile
538@cindex guile, working with values from inferior
539
540@tindex @code{<gdb:value>}
541@value{GDBN} provides values it obtains from the inferior program in
542an object of type @code{<gdb:value>}. @value{GDBN} uses this object
543for its internal bookkeeping of the inferior's values, and for
544fetching values when necessary.
545
546@value{GDBN} does not memoize @code{<gdb:value>} objects.
547@code{make-value} always returns a fresh object.
548
549@smallexample
550(gdb) guile (eq? (make-value 1) (make-value 1))
551$1 = #f
552(gdb) guile (equal? (make-value 1) (make-value 1))
553$1 = #t
554@end smallexample
555
556A @code{<gdb:value>} that represents a function can be executed via
557inferior function call with @code{value-call}.
558Any arguments provided to the call must match the function's prototype,
559and must be provided in the order specified by that prototype.
560
561For example, @code{some-val} is a @code{<gdb:value>} instance
562representing a function that takes two integers as arguments. To
563execute this function, call it like so:
564
565@smallexample
566(define result (value-call some-val 10 20))
567@end smallexample
568
569Any values returned from a function call are @code{<gdb:value>} objects.
570
571Note: Unlike Python scripting in @value{GDBN},
572inferior values that are simple scalars cannot be used directly in
573Scheme expressions that are valid for the value's data type.
574For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
575And inferior values that are structures or instances of some class cannot
576be accessed using any special syntax, instead @code{value-field} must be used.
577
578The following value-related procedures are provided by the
579@code{(gdb)} module.
580
581@deffn {Scheme Procedure} value? object
582Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
583Otherwise return @code{#f}.
584@end deffn
585
586@deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]}
587Many Scheme values can be converted directly to a @code{<gdb:value>}
588with this procedure. If @var{type} is specified, the result is a value
589of this type, and if @var{value} can't be represented with this type
590an exception is thrown. Otherwise the type of the result is determined from
591@var{value} as described below.
592
593@xref{Architectures In Guile}, for a list of the builtin
594types for an architecture.
595
596Here's how Scheme values are converted when @var{type} argument to
597@code{make-value} is not specified:
598
599@table @asis
600@item Scheme boolean
601A Scheme boolean is converted the boolean type for the current language.
602
603@item Scheme integer
604A Scheme integer is converted to the first of a C @code{int},
605@code{unsigned int}, @code{long}, @code{unsigned long},
606@code{long long} or @code{unsigned long long} type
607for the current architecture that can represent the value.
608
609If the Scheme integer cannot be represented as a target integer
610an @code{out-of-range} exception is thrown.
611
612@item Scheme real
613A Scheme real is converted to the C @code{double} type for the
614current architecture.
615
616@item Scheme string
617A Scheme string is converted to a string in the current target
618language using the current target encoding.
619Characters that cannot be represented in the current target encoding
620are replaced with the corresponding escape sequence. This is Guile's
621@code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy
622(@pxref{Strings,,, guile, GNU Guile Reference Manual}).
623
624Passing @var{type} is not supported in this case,
625if it is provided a @code{wrong-type-arg} exception is thrown.
626
627@item @code{<gdb:lazy-string>}
628If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
629Guile}), then the @code{lazy-string->value} procedure is called, and
630its result is used.
631
632Passing @var{type} is not supported in this case,
633if it is provided a @code{wrong-type-arg} exception is thrown.
634
635@item Scheme bytevector
636If @var{value} is a Scheme bytevector and @var{type} is provided,
637@var{value} must be the same size, in bytes, of values of type @var{type},
638and the result is essentially created by using @code{memcpy}.
639
640If @var{value} is a Scheme bytevector and @var{type} is not provided,
641the result is an array of type @code{uint8} of the same length.
642@end table
643@end deffn
644
645@cindex optimized out value in guile
646@deffn {Scheme Procedure} value-optimized-out? value
647Return @code{#t} if the compiler optimized out @var{value},
648thus it is not available for fetching from the inferior.
649Otherwise return @code{#f}.
650@end deffn
651
652@deffn {Scheme Procedure} value-address value
653If @var{value} is addressable, returns a
654@code{<gdb:value>} object representing the address.
655Otherwise, @code{#f} is returned.
656@end deffn
657
658@deffn {Scheme Procedure} value-type value
659Return the type of @var{value} as a @code{<gdb:type>} object
660(@pxref{Types In Guile}).
661@end deffn
662
663@deffn {Scheme Procedure} value-dynamic-type value
664Return the dynamic type of @var{value}. This uses C@t{++} run-time
665type information (@acronym{RTTI}) to determine the dynamic type of the
666value. If the value is of class type, it will return the class in
667which the value is embedded, if any. If the value is of pointer or
668reference to a class type, it will compute the dynamic type of the
669referenced object, and return a pointer or reference to that type,
670respectively. In all other cases, it will return the value's static
671type.
672
673Note that this feature will only work when debugging a C@t{++} program
674that includes @acronym{RTTI} for the object in question. Otherwise,
675it will just return the static type of the value as in @kbd{ptype foo}.
676@xref{Symbols, ptype}.
677@end deffn
678
679@deffn {Scheme Procedure} value-cast value type
680Return a new instance of @code{<gdb:value>} that is the result of
681casting @var{value} to the type described by @var{type}, which must
682be a @code{<gdb:type>} object. If the cast cannot be performed for some
683reason, this method throws an exception.
684@end deffn
685
686@deffn {Scheme Procedure} value-dynamic-cast value type
687Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
688operator were used. Consult a C@t{++} reference for details.
689@end deffn
690
691@deffn {Scheme Procedure} value-reinterpret-cast value type
692Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
693operator were used. Consult a C@t{++} reference for details.
694@end deffn
695
696@deffn {Scheme Procedure} value-dereference value
697For pointer data types, this method returns a new @code{<gdb:value>} object
698whose contents is the object pointed to by @var{value}. For example, if
699@code{foo} is a C pointer to an @code{int}, declared in your C program as
700
701@smallexample
702int *foo;
703@end smallexample
704
705@noindent
706then you can use the corresponding @code{<gdb:value>} to access what
707@code{foo} points to like this:
708
709@smallexample
710(define bar (value-dereference foo))
711@end smallexample
712
713The result @code{bar} will be a @code{<gdb:value>} object holding the
714value pointed to by @code{foo}.
715
716A similar function @code{value-referenced-value} exists which also
717returns @code{<gdb:value>} objects corresonding to the values pointed to
718by pointer values (and additionally, values referenced by reference
719values). However, the behavior of @code{value-dereference}
720differs from @code{value-referenced-value} by the fact that the
721behavior of @code{value-dereference} is identical to applying the C
722unary operator @code{*} on a given value. For example, consider a
723reference to a pointer @code{ptrref}, declared in your C@t{++} program
724as
725
726@smallexample
727typedef int *intptr;
728...
729int val = 10;
730intptr ptr = &val;
731intptr &ptrref = ptr;
732@end smallexample
733
734Though @code{ptrref} is a reference value, one can apply the method
735@code{value-dereference} to the @code{<gdb:value>} object corresponding
736to it and obtain a @code{<gdb:value>} which is identical to that
737corresponding to @code{val}. However, if you apply the method
738@code{value-referenced-value}, the result would be a @code{<gdb:value>}
739object identical to that corresponding to @code{ptr}.
740
741@smallexample
742(define scm-ptrref (parse-and-eval "ptrref"))
743(define scm-val (value-dereference scm-ptrref))
744(define scm-ptr (value-referenced-value scm-ptrref))
745@end smallexample
746
747The @code{<gdb:value>} object @code{scm-val} is identical to that
748corresponding to @code{val}, and @code{scm-ptr} is identical to that
749corresponding to @code{ptr}. In general, @code{value-dereference} can
750be applied whenever the C unary operator @code{*} can be applied
751to the corresponding C value. For those cases where applying both
752@code{value-dereference} and @code{value-referenced-value} is allowed,
753the results obtained need not be identical (as we have seen in the above
754example). The results are however identical when applied on
755@code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
756objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
757@end deffn
758
759@deffn {Scheme Procedure} value-referenced-value value
760For pointer or reference data types, this method returns a new
761@code{<gdb:value>} object corresponding to the value referenced by the
762pointer/reference value. For pointer data types,
763@code{value-dereference} and @code{value-referenced-value} produce
764identical results. The difference between these methods is that
765@code{value-dereference} cannot get the values referenced by reference
766values. For example, consider a reference to an @code{int}, declared
767in your C@t{++} program as
768
769@smallexample
770int val = 10;
771int &ref = val;
772@end smallexample
773
774@noindent
775then applying @code{value-dereference} to the @code{<gdb:value>} object
776corresponding to @code{ref} will result in an error, while applying
777@code{value-referenced-value} will result in a @code{<gdb:value>} object
778identical to that corresponding to @code{val}.
779
780@smallexample
781(define scm-ref (parse-and-eval "ref"))
782(define err-ref (value-dereference scm-ref)) ;; error
783(define scm-val (value-referenced-value scm-ref)) ;; ok
784@end smallexample
785
786The @code{<gdb:value>} object @code{scm-val} is identical to that
787corresponding to @code{val}.
788@end deffn
789
790@deffn {Scheme Procedure} value-field value field-name
791Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
792@end deffn
793
794@deffn {Scheme Procedure} value-subscript value index
795Return the value of array @var{value} at index @var{index}.
697aa1b7 796The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
ed3ef339
DE
797@end deffn
798
799@deffn {Scheme Procedure} value-call value arg-list
800Perform an inferior function call, taking @var{value} as a pointer
801to the function to call.
802Each element of list @var{arg-list} must be a <gdb:value> object or an object
803that can be converted to a value.
804The result is the value returned by the function.
805@end deffn
806
807@deffn {Scheme Procedure} value->bool value
808Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
809The value must be ``integer like''. Pointers are ok.
810@end deffn
811
812@deffn {Scheme Procedure} value->integer
813Return the Scheme integer representing @code{<gdb:value>} @var{value}.
814The value must be ``integer like''. Pointers are ok.
815@end deffn
816
817@deffn {Scheme Procedure} value->real
818Return the Scheme real number representing @code{<gdb:value>} @var{value}.
819The value must be a number.
820@end deffn
821
822@deffn {Scheme Procedure} value->bytevector
823Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
824@var{value}. No transformation, endian or otherwise, is performed.
825@end deffn
826
827@c TODO: line length
828@deffn {Scheme Procedure} value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
829If @var{value>} represents a string, then this method
830converts the contents to a Guile string. Otherwise, this method will
831throw an exception.
832
833Values are interpreted as strings according to the rules of the
834current language. If the optional length argument is given, the
835string will be converted to that length, and will include any embedded
836zeroes that the string may contain. Otherwise, for languages
837where the string is zero-terminated, the entire string will be
838converted.
839
840For example, in C-like languages, a value is a string if it is a pointer
841to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
842or @code{char32_t}.
843
844If the optional @var{encoding} argument is given, it must be a string
845naming the encoding of the string in the @code{<gdb:value>}, such as
846@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
847the same encodings as the corresponding argument to Guile's
848@code{scm_from_stringn} function, and the Guile codec machinery will be used
849to convert the string. If @var{encoding} is not given, or if
850@var{encoding} is the empty string, then either the @code{target-charset}
851(@pxref{Character Sets}) will be used, or a language-specific encoding
852will be used, if the current language is able to supply one.
853
854The optional @var{errors} argument is one of @code{#f}, @code{error} or
855@code{substitute}. @code{error} and @code{substitute} must be symbols.
856If @var{errors} is not specified, or if its value is @code{#f}, then the
857default conversion strategy is used, which is set with the Scheme function
858@code{set-port-conversion-strategy!}.
859If the value is @code{'error} then an exception is thrown if there is any
860conversion error. If the value is @code{'substitute} then any conversion
861error is replaced with question marks.
862@xref{Strings,,, guile, GNU Guile Reference Manual}.
863
864If the optional @var{length} argument is given, the string will be
865fetched and converted to the given length.
866The length must be a Scheme integer and not a @code{<gdb:value>} integer.
867@end deffn
868
869@c TODO: line length
6fb526ee 870@deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]}
ed3ef339
DE
871If this @code{<gdb:value>} represents a string, then this method
872converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
873In Guile}). Otherwise, this method will throw an exception.
874
875If the optional @var{encoding} argument is given, it must be a string
876naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
877@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
878@var{encoding} argument is an encoding that @value{GDBN} does not
879recognize, @value{GDBN} will raise an error.
880
881When a lazy string is printed, the @value{GDBN} encoding machinery is
882used to convert the string during printing. If the optional
883@var{encoding} argument is not provided, or is an empty string,
884@value{GDBN} will automatically select the encoding most suitable for
885the string type. For further information on encoding in @value{GDBN}
886please see @ref{Character Sets}.
887
888If the optional @var{length} argument is given, the string will be
889fetched and encoded to the length of characters specified. If
890the @var{length} argument is not provided, the string will be fetched
891and encoded until a null of appropriate width is found.
892The length must be a Scheme integer and not a @code{<gdb:value>} integer.
893@end deffn
894
895@deffn {Scheme Procedure} value-lazy? value
896Return @code{#t} if @var{value} has not yet been fetched
697aa1b7 897from the inferior.
ed3ef339 898Otherwise return @code{#f}.
697aa1b7 899@value{GDBN} does not fetch values until necessary, for efficiency.
ed3ef339
DE
900For example:
901
902@smallexample
903(define myval (parse-and-eval "somevar"))
904@end smallexample
905
697aa1b7 906The value of @code{somevar} is not fetched at this time. It will be
ed3ef339 907fetched when the value is needed, or when the @code{fetch-lazy}
697aa1b7 908procedure is invoked.
ed3ef339
DE
909@end deffn
910
911@deffn {Scheme Procedure} make-lazy-value type address
697aa1b7
EZ
912Return a @code{<gdb:value>} that will be lazily fetched from the
913target. The object of type @code{<gdb:type>} whose value to fetch is
914specified by its @var{type} and its target memory @var{address}, which
915is a Scheme integer.
ed3ef339
DE
916@end deffn
917
918@deffn {Scheme Procedure} value-fetch-lazy! value
919If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
920then the value is fetched from the inferior.
921Any errors that occur in the process will produce a Guile exception.
922
923If @var{value} is not a lazy value, this method has no effect.
924
925The result of this function is unspecified.
926@end deffn
927
928@deffn {Scheme Procedure} value-print value
929Return the string representation (print form) of @code{<gdb:value>}
930@var{value}.
931@end deffn
932
933@node Arithmetic In Guile
934@subsubsection Arithmetic In Guile
935
936The @code{(gdb)} module provides several functions for performing
937arithmetic on @code{<gdb:value>} objects.
938The arithmetic is performed as if it were done by the target,
939and therefore has target semantics which are not necessarily
940those of Scheme. For example operations work with a fixed precision,
941not the arbitrary precision of Scheme.
942
943Wherever a function takes an integer or pointer as an operand,
944@value{GDBN} will convert appropriate Scheme values to perform
945the operation.
946
947@deffn {Scheme Procedure} value-add a b
948@end deffn
949
950@deffn {Scheme Procedure} value-sub a b
951@end deffn
952
953@deffn {Scheme Procedure} value-mul a b
954@end deffn
955
956@deffn {Scheme Procedure} value-div a b
957@end deffn
958
959@deffn {Scheme Procedure} value-rem a b
960@end deffn
961
962@deffn {Scheme Procedure} value-mod a b
963@end deffn
964
965@deffn {Scheme Procedure} value-pow a b
966@end deffn
967
968@deffn {Scheme Procedure} value-not a
969@end deffn
970
971@deffn {Scheme Procedure} value-neg a
972@end deffn
973
974@deffn {Scheme Procedure} value-pos a
975@end deffn
976
977@deffn {Scheme Procedure} value-abs a
978@end deffn
979
980@deffn {Scheme Procedure} value-lsh a b
981@end deffn
982
983@deffn {Scheme Procedure} value-rsh a b
984@end deffn
985
986@deffn {Scheme Procedure} value-min a b
987@end deffn
988
989@deffn {Scheme Procedure} value-max a b
990@end deffn
991
992@deffn {Scheme Procedure} value-lognot a
993@end deffn
994
995@deffn {Scheme Procedure} value-logand a b
996@end deffn
997
998@deffn {Scheme Procedure} value-logior a b
999@end deffn
1000
1001@deffn {Scheme Procedure} value-logxor a b
1002@end deffn
1003
1004@deffn {Scheme Procedure} value=? a b
1005@end deffn
1006
1007@deffn {Scheme Procedure} value<? a b
1008@end deffn
1009
1010@deffn {Scheme Procedure} value<=? a b
1011@end deffn
1012
1013@deffn {Scheme Procedure} value>? a b
1014@end deffn
1015
1016@deffn {Scheme Procedure} value>=? a b
1017@end deffn
1018
1019Scheme does not provide a @code{not-equal} function,
1020and thus Guile support in @value{GDBN} does not either.
1021
1022@node Types In Guile
1023@subsubsection Types In Guile
1024@cindex types in guile
1025@cindex guile, working with types
1026
1027@tindex <gdb:type>
1028@value{GDBN} represents types from the inferior in objects of type
1029@code{<gdb:type>}.
1030
1031The following type-related procedures are provided by the
1032@code{(gdb)} module.
1033
1034@deffn {Scheme Procedure} type? object
1035Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
1036Otherwise return @code{#f}.
1037@end deffn
1038
1039@deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
697aa1b7 1040This function looks up a type by its @var{name}, which must be a string.
ed3ef339
DE
1041
1042If @var{block} is given, it is an object of type @code{<gdb:block>},
1043and @var{name} is looked up in that scope.
1044Otherwise, it is searched for globally.
1045
1046Ordinarily, this function will return an instance of @code{<gdb:type>}.
1047If the named type cannot be found, it will throw an exception.
1048@end deffn
1049
1050@deffn {Scheme Procedure} type-code type
1051Return the type code of @var{type}. The type code will be one of the
1052@code{TYPE_CODE_} constants defined below.
1053@end deffn
1054
1055@deffn {Scheme Procedure} type-tag type
1056Return the tag name of @var{type}. The tag name is the name after
1057@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1058languages have this concept. If this type has no tag name, then
1059@code{#f} is returned.
1060@end deffn
1061
1062@deffn {Scheme Procedure} type-name type
1063Return the name of @var{type}.
1064If this type has no name, then @code{#f} is returned.
1065@end deffn
1066
1067@deffn {Scheme Procedure} type-print-name type
1068Return the print name of @var{type}.
1069This returns something even for anonymous types.
1070For example, for an anonymous C struct @code{"struct @{...@}"} is returned.
1071@end deffn
1072
1073@deffn {Scheme Procedure} type-sizeof type
1074Return the size of this type, in target @code{char} units. Usually, a
1075target's @code{char} type will be an 8-bit byte. However, on some
1076unusual platforms, this type may have a different size.
1077@end deffn
1078
1079@deffn {Scheme Procedure} type-strip-typedefs type
1080Return a new @code{<gdb:type>} that represents the real type of @var{type},
1081after removing all layers of typedefs.
1082@end deffn
1083
1084@deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]}
1085Return a new @code{<gdb:type>} object which represents an array of this
1086type. If one argument is given, it is the inclusive upper bound of
1087the array; in this case the lower bound is zero. If two arguments are
1088given, the first argument is the lower bound of the array, and the
1089second argument is the upper bound of the array. An array's length
1090must not be negative, but the bounds can be.
1091@end deffn
1092
1093@deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]}
1094Return a new @code{<gdb:type>} object which represents a vector of this
1095type. If one argument is given, it is the inclusive upper bound of
1096the vector; in this case the lower bound is zero. If two arguments are
1097given, the first argument is the lower bound of the vector, and the
1098second argument is the upper bound of the vector. A vector's length
1099must not be negative, but the bounds can be.
1100
1101The difference between an @code{array} and a @code{vector} is that
1102arrays behave like in C: when used in expressions they decay to a pointer
1103to the first element whereas vectors are treated as first class values.
1104@end deffn
1105
1106@deffn {Scheme Procedure} type-pointer type
1107Return a new @code{<gdb:type>} object which represents a pointer to
1108@var{type}.
1109@end deffn
1110
1111@deffn {Scheme Procedure} type-range type
1112Return a list of two elements: the low bound and high bound of @var{type}.
1113If @var{type} does not have a range, an exception is thrown.
1114@end deffn
1115
1116@deffn {Scheme Procedure} type-reference type
1117Return a new @code{<gdb:type>} object which represents a reference to
1118@var{type}.
1119@end deffn
1120
1121@deffn {Scheme Procedure} type-target type
1122Return a new @code{<gdb:type>} object which represents the target type
1123of @var{type}.
1124
1125For a pointer type, the target type is the type of the pointed-to
1126object. For an array type (meaning C-like arrays), the target type is
1127the type of the elements of the array. For a function or method type,
1128the target type is the type of the return value. For a complex type,
1129the target type is the type of the elements. For a typedef, the
1130target type is the aliased type.
1131
1132If the type does not have a target, this method will throw an
1133exception.
1134@end deffn
1135
1136@deffn {Scheme Procedure} type-const type
1137Return a new @code{<gdb:type>} object which represents a
1138@code{const}-qualified variant of @var{type}.
1139@end deffn
1140
1141@deffn {Scheme Procedure} type-volatile type
1142Return a new @code{<gdb:type>} object which represents a
1143@code{volatile}-qualified variant of @var{type}.
1144@end deffn
1145
1146@deffn {Scheme Procedure} type-unqualified type
1147Return a new @code{<gdb:type>} object which represents an unqualified
1148variant of @var{type}. That is, the result is neither @code{const} nor
1149@code{volatile}.
1150@end deffn
1151
1152@deffn {Scheme Procedure} type-num-fields
1153Return the number of fields of @code{<gdb:type>} @var{type}.
1154@end deffn
1155
1156@deffn {Scheme Procedure} type-fields type
1157Return the fields of @var{type} as a list.
1158For structure and union types, @code{fields} has the usual meaning.
1159Range types have two fields, the minimum and maximum values. Enum types
1160have one field per enum constant. Function and method types have one
1161field per parameter. The base types of C@t{++} classes are also
1162represented as fields. If the type has no fields, or does not fit
1163into one of these categories, an empty list will be returned.
1164@xref{Fields of a type in Guile}.
1165@end deffn
1166
1167@deffn {Scheme Procedure} make-field-iterator type
1168Return the fields of @var{type} as a <gdb:iterator> object.
1169@xref{Iterators In Guile}.
1170@end deffn
1171
1172@deffn {Scheme Procedure} type-field type field-name
1173Return field named @var{field-name} in @var{type}.
1174The result is an object of type @code{<gdb:field>}.
1175@xref{Fields of a type in Guile}.
1176If the type does not have fields, or @var{field-name} is not a field
1177of @var{type}, an exception is thrown.
1178
1179For example, if @code{some-type} is a @code{<gdb:type>} instance holding
1180a structure type, you can access its @code{foo} field with:
1181
1182@smallexample
1183(define bar (type-field some-type "foo"))
1184@end smallexample
1185
1186@code{bar} will be a @code{<gdb:field>} object.
1187@end deffn
1188
1189@deffn {Scheme Procedure} type-has-field? type name
1190Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
1191Otherwise return @code{#f}.
1192@end deffn
1193
1194Each type has a code, which indicates what category this type falls
1195into. The available type categories are represented by constants
1196defined in the @code{(gdb)} module:
1197
1198@vtable @code
1199@item TYPE_CODE_PTR
1200The type is a pointer.
1201
1202@item TYPE_CODE_ARRAY
1203The type is an array.
1204
1205@item TYPE_CODE_STRUCT
1206The type is a structure.
1207
1208@item TYPE_CODE_UNION
1209The type is a union.
1210
1211@item TYPE_CODE_ENUM
1212The type is an enum.
1213
1214@item TYPE_CODE_FLAGS
1215A bit flags type, used for things such as status registers.
1216
1217@item TYPE_CODE_FUNC
1218The type is a function.
1219
1220@item TYPE_CODE_INT
1221The type is an integer type.
1222
1223@item TYPE_CODE_FLT
1224A floating point type.
1225
1226@item TYPE_CODE_VOID
1227The special type @code{void}.
1228
1229@item TYPE_CODE_SET
1230A Pascal set type.
1231
1232@item TYPE_CODE_RANGE
1233A range type, that is, an integer type with bounds.
1234
1235@item TYPE_CODE_STRING
1236A string type. Note that this is only used for certain languages with
1237language-defined string types; C strings are not represented this way.
1238
1239@item TYPE_CODE_BITSTRING
1240A string of bits. It is deprecated.
1241
1242@item TYPE_CODE_ERROR
1243An unknown or erroneous type.
1244
1245@item TYPE_CODE_METHOD
1246A method type, as found in C@t{++} or Java.
1247
1248@item TYPE_CODE_METHODPTR
1249A pointer-to-member-function.
1250
1251@item TYPE_CODE_MEMBERPTR
1252A pointer-to-member.
1253
1254@item TYPE_CODE_REF
1255A reference type.
1256
1257@item TYPE_CODE_CHAR
1258A character type.
1259
1260@item TYPE_CODE_BOOL
1261A boolean type.
1262
1263@item TYPE_CODE_COMPLEX
1264A complex float type.
1265
1266@item TYPE_CODE_TYPEDEF
1267A typedef to some other type.
1268
1269@item TYPE_CODE_NAMESPACE
1270A C@t{++} namespace.
1271
1272@item TYPE_CODE_DECFLOAT
1273A decimal floating point type.
1274
1275@item TYPE_CODE_INTERNAL_FUNCTION
1276A function internal to @value{GDBN}. This is the type used to represent
1277convenience functions (@pxref{Convenience Funs}).
1278@end vtable
1279
1280Further support for types is provided in the @code{(gdb types)}
1281Guile module (@pxref{Guile Types Module}).
1282
1283@anchor{Fields of a type in Guile}
1284Each field is represented as an object of type @code{<gdb:field>}.
1285
1286The following field-related procedures are provided by the
1287@code{(gdb)} module:
1288
1289@deffn {Scheme Procedure} field? object
1290Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
1291Otherwise return @code{#f}.
1292@end deffn
1293
1294@deffn {Scheme Procedure} field-name field
1295Return the name of the field, or @code{#f} for anonymous fields.
1296@end deffn
1297
1298@deffn {Scheme Procedure} field-type field
1299Return the type of the field. This is usually an instance of
1300@code{<gdb:type>}, but it can be @code{#f} in some situations.
1301@end deffn
1302
1303@deffn {Scheme Procedure} field-enumval field
1304Return the enum value represented by @code{<gdb:field>} @var{field}.
1305@end deffn
1306
1307@deffn {Scheme Procedure} field-bitpos field
1308Return the bit position of @code{<gdb:field>} @var{field}.
1309This attribute is not available for @code{static} fields (as in
1310C@t{++} or Java).
1311@end deffn
1312
1313@deffn {Scheme Procedure} field-bitsize field
1314If the field is packed, or is a bitfield, return the size of
1315@code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
1316in which case the field's size is given by its type.
1317@end deffn
1318
1319@deffn {Scheme Procedure} field-artificial? field
1320Return @code{#t} if the field is artificial, usually meaning that
1321it was provided by the compiler and not the user.
1322Otherwise return @code{#f}.
1323@end deffn
1324
1325@deffn {Scheme Procedure} field-base-class? field
1326Return @code{#t} if the field represents a base class of a C@t{++}
1327structure.
1328Otherwise return @code{#f}.
1329@end deffn
1330
1331@node Guile Pretty Printing API
1332@subsubsection Guile Pretty Printing API
1333@cindex guile pretty printing api
1334
1335An example output is provided (@pxref{Pretty Printing}).
1336
1337A pretty-printer is represented by an object of type <gdb:pretty-printer>.
1338Pretty-printer objects are created with @code{make-pretty-printer}.
1339
1340The following pretty-printer-related procedures are provided by the
1341@code{(gdb)} module:
1342
1343@deffn {Scheme Procedure} make-pretty-printer name lookup-function
1344Return a @code{<gdb:pretty-printer>} object named @var{name}.
1345
1346@var{lookup-function} is a function of one parameter: the value to
1347be printed. If the value is handled by this pretty-printer, then
1348@var{lookup-function} returns an object of type
1349<gdb:pretty-printer-worker> to perform the actual pretty-printing.
1350Otherwise @var{lookup-function} returns @code{#f}.
1351@end deffn
1352
1353@deffn {Scheme Procedure} pretty-printer? object
1354Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
1355Otherwise return @code{#f}.
1356@end deffn
1357
1358@deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer
1359Return @code{#t} if @var{pretty-printer} is enabled.
1360Otherwise return @code{#f}.
1361@end deffn
1362
1363@deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag
1364Set the enabled flag of @var{pretty-printer} to @var{flag}.
1365The value returned in unspecified.
1366@end deffn
1367
1368@deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children
1369Return an object of type @code{<gdb:pretty-printer-worker>}.
1370
1371This function takes three parameters:
1372
1373@table @samp
1374@item display-hint
1375@var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
1376front end via MI to change the formatting of the value being printed.
1377The value must be a string or @code{#f} (meaning there is no hint).
1378Several values for @var{display-hint}
1379are predefined by @value{GDBN}:
1380
1381@table @samp
1382@item array
1383Indicate that the object being printed is ``array-like''. The CLI
1384uses this to respect parameters such as @code{set print elements} and
1385@code{set print array}.
1386
1387@item map
1388Indicate that the object being printed is ``map-like'', and that the
1389children of this value can be assumed to alternate between keys and
1390values.
1391
1392@item string
1393Indicate that the object being printed is ``string-like''. If the
1394printer's @code{to-string} function returns a Guile string of some
1395kind, then @value{GDBN} will call its internal language-specific
1396string-printing function to format the string. For the CLI this means
1397adding quotation marks, possibly escaping some characters, respecting
1398@code{set print elements}, and the like.
1399@end table
1400
1401@item to-string
1402@var{to-string} is either a function of one parameter, the
1403@code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1404
1405When printing from the CLI, if the @code{to-string} method exists,
1406then @value{GDBN} will prepend its result to the values returned by
1407@code{children}. Exactly how this formatting is done is dependent on
1408the display hint, and may change as more hints are added. Also,
1409depending on the print settings (@pxref{Print Settings}), the CLI may
1410print just the result of @code{to-string} in a stack trace, omitting
1411the result of @code{children}.
1412
1413If this method returns a string, it is printed verbatim.
1414
1415Otherwise, if this method returns an instance of @code{<gdb:value>},
1416then @value{GDBN} prints this value. This may result in a call to
1417another pretty-printer.
1418
1419If instead the method returns a Guile value which is convertible to a
1420@code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
1421the resulting value. Again, this may result in a call to another
1422pretty-printer. Guile scalars (integers, floats, and booleans) and
1423strings are convertible to @code{<gdb:value>}; other types are not.
1424
1425Finally, if this method returns @code{#f} then no further operations
1426are peformed in this method and nothing is printed.
1427
1428If the result is not one of these types, an exception is raised.
1429
1430@var{to-string} may also be @code{#f} in which case it is left to
1431@var{children} to print the value.
1432
1433@item children
1434@var{children} is either a function of one parameter, the
1435@code{<gdb:pretty-printer-worker>} object, or @code{#f}.
1436
1437@value{GDBN} will call this function on a pretty-printer to compute the
1438children of the pretty-printer's value.
1439
1440This function must return a <gdb:iterator> object.
1441Each item returned by the iterator must be a tuple holding
1442two elements. The first element is the ``name'' of the child; the
1443second element is the child's value. The value can be any Guile
1444object which is convertible to a @value{GDBN} value.
1445
1446If @var{children} is @code{#f}, @value{GDBN} will act
1447as though the value has no children.
1448@end table
1449@end deffn
1450
1451@value{GDBN} provides a function which can be used to look up the
1452default pretty-printer for a @code{<gdb:value>}:
1453
1454@deffn {Scheme Procedure} default-visualizer value
1455This function takes a @code{<gdb:value>} object as an argument. If a
1456pretty-printer for this value exists, then it is returned. If no such
1457printer exists, then this returns @code{#f}.
1458@end deffn
1459
1460@node Selecting Guile Pretty-Printers
1461@subsubsection Selecting Guile Pretty-Printers
1462@cindex selecting guile pretty-printers
1463
1464The Guile list @code{*pretty-printers*} contains a set of
1465@code{<gdb:pretty-printer>} registered objects.
1466Printers in this list are called @code{global}
1467printers, they're available when debugging any inferior.
1468In addition to this, each @code{<gdb:objfile>} object contains its
1469own set of pretty-printers (@pxref{Objfiles In Guile}).
1470
1471Pretty-printer lookup is done by passing the value to be printed to the
1472lookup function of each enabled object in turn.
1473Lookup stops when a lookup function returns a non-@code{#f} value
1474or when the list is exhausted.
1475
1476@value{GDBN} first checks the result of @code{objfile-pretty-printers}
1477of each @code{<gdb:objfile>} in the current program space and iteratively
1478calls each enabled lookup function in the list for that @code{<gdb:objfile>}
1479until a non-@code{#f} object is returned.
1480Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
1481object or @code{#f}. Otherwise an exception is thrown.
1482If no pretty-printer is found in the objfile lists, @value{GDBN} then
1483searches the global pretty-printer list, calling each enabled function
1484until a non-@code{#f} object is returned.
1485
1486The order in which the objfiles are searched is not specified. For a
1487given list, functions are always invoked from the head of the list,
1488and iterated over sequentially until the end of the list, or a
1489@code{<gdb:pretty-printer-worker>} object is returned.
1490
1491For various reasons a pretty-printer may not work.
1492For example, the underlying data structure may have changed and
1493the pretty-printer is out of date.
1494
1495The consequences of a broken pretty-printer are severe enough that
1496@value{GDBN} provides support for enabling and disabling individual
1497printers. For example, if @code{print frame-arguments} is on,
1498a backtrace can become highly illegible if any argument is printed
1499with a broken printer.
1500
1501Pretty-printers are enabled and disabled from Scheme by calling
1502@code{set-pretty-printer-enabled!}.
1503@xref{Guile Pretty Printing API}.
1504
1505@node Writing a Guile Pretty-Printer
1506@subsubsection Writing a Guile Pretty-Printer
1507@cindex writing a Guile pretty-printer
1508
1509A pretty-printer consists of two basic parts: a lookup function to determine
1510if the type is supported, and the printer itself.
1511
1512Here is an example showing how a @code{std::string} printer might be
1513written. @xref{Guile Pretty Printing API}, for details.
1514
1515@smallexample
1516(define (make-my-string-printer value)
1517 "Print a my::string string"
1518 (make-pretty-printer-worker
1519 "string"
1520 (lambda (printer)
1521 (value-field value "_data"))
1522 #f))
1523@end smallexample
1524
1525And here is an example showing how a lookup function for the printer
1526example above might be written.
1527
1528@smallexample
6e7a66c1 1529(define (str-lookup-function pretty-printer value)
ed3ef339
DE
1530 (let ((tag (type-tag (value-type value))))
1531 (and tag
6e7a66c1
LC
1532 (string-prefix? "std::string<" tag)
1533 (make-my-string-printer value))))
ed3ef339
DE
1534@end smallexample
1535
1536Then to register this printer in the global printer list:
1537
1538@smallexample
1539(append-pretty-printer!
1540 (make-pretty-printer "my-string" str-lookup-function))
1541@end smallexample
1542
1543The example lookup function extracts the value's type, and attempts to
1544match it to a type that it can pretty-print. If it is a type the
1545printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
1546If not, it returns @code{#f}.
1547
1548We recommend that you put your core pretty-printers into a Guile
1549package. If your pretty-printers are for use with a library, we
1550further recommend embedding a version number into the package name.
1551This practice will enable @value{GDBN} to load multiple versions of
1552your pretty-printers at the same time, because they will have
1553different names.
1554
1555You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
1556can be evaluated multiple times without changing its meaning. An
1557ideal auto-load file will consist solely of @code{import}s of your
1558printer modules, followed by a call to a register pretty-printers with
1559the current objfile.
1560
1561Taken as a whole, this approach will scale nicely to multiple
1562inferiors, each potentially using a different library version.
1563Embedding a version number in the Guile package name will ensure that
1564@value{GDBN} is able to load both sets of printers simultaneously.
1565Then, because the search for pretty-printers is done by objfile, and
1566because your auto-loaded code took care to register your library's
1567printers with a specific objfile, @value{GDBN} will find the correct
1568printers for the specific version of the library used by each
1569inferior.
1570
1571To continue the @code{my::string} example,
1572this code might appear in @code{(my-project my-library v1)}:
1573
1574@smallexample
0f1e8403 1575(use-modules (gdb))
ed3ef339
DE
1576(define (register-printers objfile)
1577 (append-objfile-pretty-printer!
1578 (make-pretty-printer "my-string" str-lookup-function)))
1579@end smallexample
1580
1581@noindent
1582And then the corresponding contents of the auto-load file would be:
1583
1584@smallexample
0f1e8403 1585(use-modules (gdb) (my-project my-library v1))
ed3ef339
DE
1586(register-printers (current-objfile))
1587@end smallexample
1588
1589The previous example illustrates a basic pretty-printer.
1590There are a few things that can be improved on.
1591The printer only handles one type, whereas a library typically has
1592several types. One could install a lookup function for each desired type
1593in the library, but one could also have a single lookup function recognize
1594several types. The latter is the conventional way this is handled.
1595If a pretty-printer can handle multiple data types, then its
1596@dfn{subprinters} are the printers for the individual data types.
1597
1598The @code{(gdb printing)} module provides a formal way of solving this
1599problem (@pxref{Guile Printing Module}).
1600Here is another example that handles multiple types.
1601
1602These are the types we are going to pretty-print:
1603
1604@smallexample
1605struct foo @{ int a, b; @};
1606struct bar @{ struct foo x, y; @};
1607@end smallexample
1608
1609Here are the printers:
1610
1611@smallexample
1612(define (make-foo-printer value)
1613 "Print a foo object"
1614 (make-pretty-printer-worker
1615 "foo"
1616 (lambda (printer)
1617 (format #f "a=<~a> b=<~a>"
1618 (value-field value "a") (value-field value "a")))
1619 #f))
1620
1621(define (make-bar-printer value)
1622 "Print a bar object"
1623 (make-pretty-printer-worker
1624 "foo"
1625 (lambda (printer)
1626 (format #f "x=<~a> y=<~a>"
1627 (value-field value "x") (value-field value "y")))
1628 #f))
1629@end smallexample
1630
1631This example doesn't need a lookup function, that is handled by the
1632@code{(gdb printing)} module. Instead a function is provided to build up
1633the object that handles the lookup.
1634
1635@smallexample
0f1e8403 1636(use-modules (gdb printing))
ed3ef339
DE
1637
1638(define (build-pretty-printer)
1639 (let ((pp (make-pretty-printer-collection "my-library")))
1640 (pp-collection-add-tag-printer "foo" make-foo-printer)
1641 (pp-collection-add-tag-printer "bar" make-bar-printer)
1642 pp))
1643@end smallexample
1644
1645And here is the autoload support:
1646
1647@smallexample
0f1e8403 1648(use-modules (gdb) (my-library))
ed3ef339
DE
1649(append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
1650@end smallexample
1651
1652Finally, when this printer is loaded into @value{GDBN}, here is the
1653corresponding output of @samp{info pretty-printer}:
1654
1655@smallexample
1656(gdb) info pretty-printer
1657my_library.so:
1658 my-library
1659 foo
1660 bar
1661@end smallexample
1662
1663@node Objfiles In Guile
1664@subsubsection Objfiles In Guile
1665
1666@cindex objfiles in guile
1667@tindex <gdb:objfile>
1668@value{GDBN} loads symbols for an inferior from various
1669symbol-containing files (@pxref{Files}). These include the primary
1670executable file, any shared libraries used by the inferior, and any
1671separate debug info files (@pxref{Separate Debug Files}).
1672@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
1673
1674Each objfile is represented as an object of type @code{<gdb:objfile>}.
1675
1676The following objfile-related procedures are provided by the
1677@code{(gdb)} module:
1678
1679@deffn {Scheme Procedure} objfile? object
1680Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
1681Otherwise return @code{#f}.
1682@end deffn
1683
1684@deffn {Scheme Procedure} objfile-valid? objfile
1685Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
1686A @code{<gdb:objfile>} object can become invalid
1687if the object file it refers to is not loaded in @value{GDBN} any
1688longer. All other @code{<gdb:objfile>} procedures will throw an exception
1689if it is invalid at the time the procedure is called.
1690@end deffn
1691
1692@deffn {Scheme Procedure} objfile-filename objfile
1693Return the file name of @var{objfile} as a string.
1694@end deffn
1695
1696@deffn {Scheme Procedure} objfile-pretty-printers objfile
1697Return the list of registered @code{<gdb:pretty-printer>} objects for
1698@var{objfile}. @xref{Guile Pretty Printing API}, for more information.
1699@end deffn
1700
1701@deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
1702Set the list of registered @code{<gdb:pretty-printer>} objects for
697aa1b7 1703@var{objfile} to @var{printer-list}. The
ed3ef339
DE
1704@var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
1705@xref{Guile Pretty Printing API}, for more information.
1706@end deffn
1707
1708@deffn {Scheme Procedure} current-objfile
1709When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
1710sets the ``current objfile'' to the corresponding objfile. This
1711function returns the current objfile. If there is no current objfile,
1712this function returns @code{#f}.
1713@end deffn
1714
1715@deffn {Scheme Procedure} objfiles
1716Return a list of all the objfiles in the current program space.
1717@end deffn
1718
1719@node Frames In Guile
1720@subsubsection Accessing inferior stack frames from Guile.
1721
1722@cindex frames in guile
1723When the debugged program stops, @value{GDBN} is able to analyze its call
1724stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
1725represents a frame in the stack. A @code{<gdb:frame>} object is only valid
1726while its corresponding frame exists in the inferior's stack. If you try
1727to use an invalid frame object, @value{GDBN} will throw a
1728@code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
1729
1730Two @code{<gdb:frame>} objects can be compared for equality with the
1731@code{equal?} function, like:
1732
1733@smallexample
1734(@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
1735#t
1736@end smallexample
1737
1738The following frame-related procedures are provided by the
1739@code{(gdb)} module:
1740
1741@deffn {Scheme Procedure} frame? object
1742Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
1743Otherwise return @code{#f}.
1744@end deffn
1745
1746@deffn {Scheme Procedure} frame-valid? frame
1747Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
1748A frame object can become invalid if the frame it refers to doesn't
1749exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
1750an exception if the frame is invalid at the time the procedure is called.
1751@end deffn
1752
1753@deffn {Scheme Procedure} frame-name frame
1754Return the function name of @var{frame}, or @code{#f} if it can't be
1755obtained.
1756@end deffn
1757
1758@deffn {Scheme Procedure} frame-arch frame
1759Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
1760architecture. @xref{Architectures In Guile}.
1761@end deffn
1762
1763@deffn {Scheme Procedure} frame-type frame
1764Return the type of @var{frame}. The value can be one of:
1765
1766@table @code
1767@item NORMAL_FRAME
1768An ordinary stack frame.
1769
1770@item DUMMY_FRAME
1771A fake stack frame that was created by @value{GDBN} when performing an
1772inferior function call.
1773
1774@item INLINE_FRAME
1775A frame representing an inlined function. The function was inlined
1776into a @code{NORMAL_FRAME} that is older than this one.
1777
1778@item TAILCALL_FRAME
1779A frame representing a tail call. @xref{Tail Call Frames}.
1780
1781@item SIGTRAMP_FRAME
1782A signal trampoline frame. This is the frame created by the OS when
1783it calls into a signal handler.
1784
1785@item ARCH_FRAME
1786A fake stack frame representing a cross-architecture call.
1787
1788@item SENTINEL_FRAME
1789This is like @code{NORMAL_FRAME}, but it is only used for the
1790newest frame.
1791@end table
1792@end deffn
1793
1794@deffn {Scheme Procedure} frame-unwind-stop-reason frame
1795Return an integer representing the reason why it's not possible to find
1796more frames toward the outermost frame. Use
1797@code{unwind-stop-reason-string} to convert the value returned by this
1798function to a string. The value can be one of:
1799
1800@table @code
1801@item FRAME_UNWIND_NO_REASON
1802No particular reason (older frames should be available).
1803
1804@item FRAME_UNWIND_NULL_ID
1805The previous frame's analyzer returns an invalid result.
1806
1807@item FRAME_UNWIND_OUTERMOST
1808This frame is the outermost.
1809
1810@item FRAME_UNWIND_UNAVAILABLE
1811Cannot unwind further, because that would require knowing the
1812values of registers or memory that have not been collected.
1813
1814@item FRAME_UNWIND_INNER_ID
1815This frame ID looks like it ought to belong to a NEXT frame,
1816but we got it for a PREV frame. Normally, this is a sign of
1817unwinder failure. It could also indicate stack corruption.
1818
1819@item FRAME_UNWIND_SAME_ID
1820This frame has the same ID as the previous one. That means
1821that unwinding further would almost certainly give us another
1822frame with exactly the same ID, so break the chain. Normally,
1823this is a sign of unwinder failure. It could also indicate
1824stack corruption.
1825
1826@item FRAME_UNWIND_NO_SAVED_PC
1827The frame unwinder did not find any saved PC, but we needed
1828one to unwind further.
1829
1830@item FRAME_UNWIND_FIRST_ERROR
1831Any stop reason greater or equal to this value indicates some kind
1832of error. This special value facilitates writing code that tests
1833for errors in unwinding in a way that will work correctly even if
1834the list of the other values is modified in future @value{GDBN}
1835versions. Using it, you could write:
1836
1837@smallexample
1838(define reason (frame-unwind-stop-readon (selected-frame)))
1839(define reason-str (unwind-stop-reason-string reason))
1840(if (>= reason FRAME_UNWIND_FIRST_ERROR)
1841 (format #t "An error occured: ~s\n" reason-str))
1842@end smallexample
1843@end table
1844@end deffn
1845
1846@deffn {Scheme Procedure} frame-pc frame
1847Return the frame's resume address.
1848@end deffn
1849
1850@deffn {Scheme Procedure} frame-block frame
1851Return the frame's code block as a @code{<gdb:block>} object.
1852@xref{Blocks In Guile}.
1853@end deffn
1854
1855@deffn {Scheme Procedure} frame-function frame
1856Return the symbol for the function corresponding to this frame
1857as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
1858@xref{Symbols In Guile}.
1859@end deffn
1860
1861@deffn {Scheme Procedure} frame-older frame
1862Return the frame that called @var{frame}.
1863@end deffn
1864
1865@deffn {Scheme Procedure} frame-newer frame
1866Return the frame called by @var{frame}.
1867@end deffn
1868
1869@deffn {Scheme Procedure} frame-sal frame
1870Return the frame's @code{<gdb:sal>} (symtab and line) object.
1871@xref{Symbol Tables In Guile}.
1872@end deffn
1873
6e7a66c1
LC
1874@deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]}
1875Return the value of @var{variable} in @var{frame}. If the optional
ed3ef339
DE
1876argument @var{block} is provided, search for the variable from that
1877block; otherwise start at the frame's current block (which is
697aa1b7
EZ
1878determined by the frame's current program counter). The
1879@var{variable} must be given as a string or a @code{<gdb:symbol>}
1880object, and @var{block} must be a @code{<gdb:block>} object.
ed3ef339
DE
1881@end deffn
1882
1883@deffn {Scheme Procedure} frame-select frame
1884Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
1885Stack}.
1886@end deffn
1887
1888@deffn {Scheme Procedure} selected-frame
1889Return the selected frame object. @xref{Selection,,Selecting a Frame}.
1890@end deffn
1891
1892@deffn {Scheme Procedure} newest-frame
1893Return the newest frame object for the selected thread.
1894@end deffn
1895
1896@deffn {Scheme Procedure} unwind-stop-reason-string reason
1897Return a string explaining the reason why @value{GDBN} stopped unwinding
1898frames, as expressed by the given @var{reason} code (an integer, see the
1899@code{frame-unwind-stop-reason} procedure above in this section).
1900@end deffn
1901
1902@node Blocks In Guile
1903@subsubsection Accessing blocks from Guile.
1904
1905@cindex blocks in guile
1906@tindex <gdb:block>
1907
1908In @value{GDBN}, symbols are stored in blocks. A block corresponds
1909roughly to a scope in the source code. Blocks are organized
1910hierarchically, and are represented individually in Guile as an object
1911of type @code{<gdb:block>}. Blocks rely on debugging information being
1912available.
1913
1914A frame has a block. Please see @ref{Frames In Guile}, for a more
1915in-depth discussion of frames.
1916
1917The outermost block is known as the @dfn{global block}. The global
1918block typically holds public global variables and functions.
1919
1920The block nested just inside the global block is the @dfn{static
1921block}. The static block typically holds file-scoped variables and
1922functions.
1923
1924@value{GDBN} provides a method to get a block's superblock, but there
1925is currently no way to examine the sub-blocks of a block, or to
1926iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
1927Guile}).
1928
1929Here is a short example that should help explain blocks:
1930
1931@smallexample
1932/* This is in the global block. */
1933int global;
1934
1935/* This is in the static block. */
1936static int file_scope;
1937
1938/* 'function' is in the global block, and 'argument' is
1939 in a block nested inside of 'function'. */
1940int function (int argument)
1941@{
1942 /* 'local' is in a block inside 'function'. It may or may
1943 not be in the same block as 'argument'. */
1944 int local;
1945
1946 @{
1947 /* 'inner' is in a block whose superblock is the one holding
1948 'local'. */
1949 int inner;
1950
1951 /* If this call is expanded by the compiler, you may see
1952 a nested block here whose function is 'inline_function'
1953 and whose superblock is the one holding 'inner'. */
1954 inline_function ();
1955 @}
1956@}
1957@end smallexample
1958
1959The following block-related procedures are provided by the
1960@code{(gdb)} module:
1961
1962@deffn {Scheme Procedure} block? object
1963Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
1964Otherwise return @code{#f}.
1965@end deffn
1966
1967@deffn {Scheme Procedure} block-valid? block
1968Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
1969@code{#f} if not. A block object can become invalid if the block it
1970refers to doesn't exist anymore in the inferior. All other
1971@code{<gdb:block>} methods will throw an exception if it is invalid at
1972the time the procedure is called. The block's validity is also checked
1973during iteration over symbols of the block.
1974@end deffn
1975
1976@deffn {Scheme Procedure} block-start block
1977Return the start address of @code{<gdb:block>} @var{block}.
1978@end deffn
1979
1980@deffn {Scheme Procedure} block-end block
1981Return the end address of @code{<gdb:block>} @var{block}.
1982@end deffn
1983
1984@deffn {Scheme Procedure} block-function block
1985Return the name of @code{<gdb:block>} @var{block} represented as a
1986@code{<gdb:symbol>} object.
1987If the block is not named, then @code{#f} is returned.
1988
1989For ordinary function blocks, the superblock is the static block.
1990However, you should note that it is possible for a function block to
1991have a superblock that is not the static block -- for instance this
1992happens for an inlined function.
1993@end deffn
1994
1995@deffn {Scheme Procedure} block-superblock block
1996Return the block containing @code{<gdb:block>} @var{block}.
1997If the parent block does not exist, then @code{#f} is returned.
1998@end deffn
1999
2000@deffn {Scheme Procedure} block-global-block block
2001Return the global block associated with @code{<gdb:block>} @var{block}.
2002@end deffn
2003
2004@deffn {Scheme Procedure} block-static-block block
2005Return the static block associated with @code{<gdb:block>} @var{block}.
2006@end deffn
2007
2008@deffn {Scheme Procedure} block-global? block
2009Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
2010Otherwise return @code{#f}.
2011@end deffn
2012
2013@deffn {Scheme Procedure} block-static? block
2014Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
2015Otherwise return @code{#f}.
2016@end deffn
2017
2018@deffn {Scheme Procedure} block-symbols
2019Return a list of all symbols (as <gdb:symbol> objects) in
2020@code{<gdb:block>} @var{block}.
2021@end deffn
2022
2023@deffn {Scheme Procedure} make-block-symbols-iterator block
2024Return an object of type @code{<gdb:iterator>} that will iterate
2025over all symbols of the block.
2026Guile programs should not assume that a specific block object will
2027always contain a given symbol, since changes in @value{GDBN} features and
2028infrastructure may cause symbols move across blocks in a symbol table.
2029@xref{Iterators In Guile}.
2030@end deffn
2031
2032@deffn {Scheme Procedure} block-symbols-progress?
2033Return #t if the object is a <gdb:block-symbols-progress> object.
2034This object would be obtained from the @code{progress} element of the
2035@code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
2036@end deffn
2037
2038@deffn {Scheme Procedure} lookup-block pc
2039Return the innermost @code{<gdb:block>} containing the given @var{pc}
2040value. If the block cannot be found for the @var{pc} value specified,
2041the function will return @code{#f}.
2042@end deffn
2043
2044@node Symbols In Guile
2045@subsubsection Guile representation of Symbols.
2046
2047@cindex symbols in guile
2048@tindex <gdb:symbol>
2049
2050@value{GDBN} represents every variable, function and type as an
2051entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
2052Guile represents these symbols in @value{GDBN} with the
2053@code{<gdb:symbol>} object.
2054
2055The following symbol-related procedures are provided by the
2056@code{(gdb)} module:
2057
2058@deffn {Scheme Procedure} symbol? object
2059Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
2060Otherwise return @code{#f}.
2061@end deffn
2062
2063@deffn {Scheme Procedure} symbol-valid? symbol
2064Return @code{#t} if the @code{<gdb:symbol>} object is valid,
2065@code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
2066the symbol it refers to does not exist in @value{GDBN} any longer.
2067All other @code{<gdb:symbol>} procedures will throw an exception if it is
2068invalid at the time the procedure is called.
2069@end deffn
2070
2071@deffn {Scheme Procedure} symbol-type symbol
2072Return the type of @var{symbol} or @code{#f} if no type is recorded.
2073The result is an object of type @code{<gdb:type>}.
2074@xref{Types In Guile}.
2075@end deffn
2076
2077@deffn {Scheme Procedure} symbol-symtab symbol
2078Return the symbol table in which @var{symbol} appears.
2079The result is an object of type @code{<gdb:symtab>}.
2080@xref{Symbol Tables In Guile}.
2081@end deffn
2082
2083@deffn {Scheme Procedure} symbol-line symbol
2084Return the line number in the source code at which @var{symbol} was defined.
2085This is an integer.
2086@end deffn
2087
2088@deffn {Scheme Procedure} symbol-name symbol
2089Return the name of @var{symbol} as a string.
2090@end deffn
2091
2092@deffn {Scheme Procedure} symbol-linkage-name symbol
2093Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
2094@end deffn
2095
2096@deffn {Scheme Procedure} symbol-print-name symbol
2097Return the name of @var{symbol} in a form suitable for output. This is either
2098@code{name} or @code{linkage_name}, depending on whether the user
2099asked @value{GDBN} to display demangled or mangled names.
2100@end deffn
2101
2102@deffn {Scheme Procedure} symbol-addr-class symbol
2103Return the address class of the symbol. This classifies how to find the value
2104of a symbol. Each address class is a constant defined in the
2105@code{(gdb)} module and described later in this chapter.
2106@end deffn
2107
2108@deffn {Scheme Procedure} symbol-needs-frame? symbol
2109Return @code{#t} if evaluating @var{symbol}'s value requires a frame
2110(@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
2111local variables will require a frame, but other symbols will not.
2112@end deffn
2113
2114@deffn {Scheme Procedure} symbol-argument? symbol
2115Return @code{#t} if @var{symbol} is an argument of a function.
2116Otherwise return @code{#f}.
2117@end deffn
2118
2119@deffn {Scheme Procedure} symbol-constant? symbol
2120Return @code{#t} if @var{symbol} is a constant.
2121Otherwise return @code{#f}.
2122@end deffn
2123
2124@deffn {Scheme Procedure} symbol-function? symbol
2125Return @code{#t} if @var{symbol} is a function or a method.
2126Otherwise return @code{#f}.
2127@end deffn
2128
2129@deffn {Scheme Procedure} symbol-variable? symbol
2130Return @code{#t} if @var{symbol} is a variable.
2131Otherwise return @code{#f}.
2132@end deffn
2133
2134@deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]}
2135Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
2136functions, this computes the address of the function, cast to the
2137appropriate type. If the symbol requires a frame in order to compute
2138its value, then @var{frame} must be given. If @var{frame} is not
2139given, or if @var{frame} is invalid, then an exception is thrown.
2140@end deffn
2141
2142@c TODO: line length
2143@deffn {Scheme Procedure} lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]}
2144This function searches for a symbol by name. The search scope can be
2145restricted to the parameters defined in the optional domain and block
2146arguments.
2147
2148@var{name} is the name of the symbol. It must be a string. The
2149optional @var{block} argument restricts the search to symbols visible
2150in that @var{block}. The @var{block} argument must be a
2151@code{<gdb:block>} object. If omitted, the block for the current frame
2152is used. The optional @var{domain} argument restricts
2153the search to the domain type. The @var{domain} argument must be a
2154domain constant defined in the @code{(gdb)} module and described later
2155in this chapter.
2156
2157The result is a list of two elements.
2158The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2159is not found.
2160If the symbol is found, the second element is @code{#t} if the symbol
2161is a field of a method's object (e.g., @code{this} in C@t{++}),
2162otherwise it is @code{#f}.
2163If the symbol is not found, the second element is @code{#f}.
2164@end deffn
2165
2166@deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]}
2167This function searches for a global symbol by name.
2168The search scope can be restricted by the domain argument.
2169
2170@var{name} is the name of the symbol. It must be a string.
2171The optional @var{domain} argument restricts the search to the domain type.
2172The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
2173module and described later in this chapter.
2174
2175The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
2176is not found.
2177@end deffn
2178
2179The available domain categories in @code{<gdb:symbol>} are represented
2180as constants in the @code{(gdb)} module:
2181
2182@vtable @code
2183@item SYMBOL_UNDEF_DOMAIN
2184This is used when a domain has not been discovered or none of the
2185following domains apply. This usually indicates an error either
2186in the symbol information or in @value{GDBN}'s handling of symbols.
2187
2188@item SYMBOL_VAR_DOMAIN
2189This domain contains variables, function names, typedef names and enum
2190type values.
2191
2192@item SYMBOL_STRUCT_DOMAIN
2193This domain holds struct, union and enum type names.
2194
2195@item SYMBOL_LABEL_DOMAIN
2196This domain contains names of labels (for gotos).
2197
2198@item SYMBOL_VARIABLES_DOMAIN
2199This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
2200contains everything minus functions and types.
2201
2202@item SYMBOL_FUNCTION_DOMAIN
2203This domain contains all functions.
2204
2205@item SYMBOL_TYPES_DOMAIN
2206This domain contains all types.
2207@end vtable
2208
2209The available address class categories in @code{<gdb:symbol>} are represented
2210as constants in the @code{gdb} module:
2211
2212@vtable @code
2213@item SYMBOL_LOC_UNDEF
2214If this is returned by address class, it indicates an error either in
2215the symbol information or in @value{GDBN}'s handling of symbols.
2216
2217@item SYMBOL_LOC_CONST
2218Value is constant int.
2219
2220@item SYMBOL_LOC_STATIC
2221Value is at a fixed address.
2222
2223@item SYMBOL_LOC_REGISTER
2224Value is in a register.
2225
2226@item SYMBOL_LOC_ARG
2227Value is an argument. This value is at the offset stored within the
2228symbol inside the frame's argument list.
2229
2230@item SYMBOL_LOC_REF_ARG
2231Value address is stored in the frame's argument list. Just like
2232@code{LOC_ARG} except that the value's address is stored at the
2233offset, not the value itself.
2234
2235@item SYMBOL_LOC_REGPARM_ADDR
2236Value is a specified register. Just like @code{LOC_REGISTER} except
2237the register holds the address of the argument instead of the argument
2238itself.
2239
2240@item SYMBOL_LOC_LOCAL
2241Value is a local variable.
2242
2243@item SYMBOL_LOC_TYPEDEF
2244Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
2245have this class.
2246
2247@item SYMBOL_LOC_BLOCK
2248Value is a block.
2249
2250@item SYMBOL_LOC_CONST_BYTES
2251Value is a byte-sequence.
2252
2253@item SYMBOL_LOC_UNRESOLVED
2254Value is at a fixed address, but the address of the variable has to be
2255determined from the minimal symbol table whenever the variable is
2256referenced.
2257
2258@item SYMBOL_LOC_OPTIMIZED_OUT
2259The value does not actually exist in the program.
2260
2261@item SYMBOL_LOC_COMPUTED
2262The value's address is a computed location.
2263@end vtable
2264
2265@node Symbol Tables In Guile
2266@subsubsection Symbol table representation in Guile.
2267
2268@cindex symbol tables in guile
2269@tindex <gdb:symtab>
2270@tindex <gdb:sal>
2271
2272Access to symbol table data maintained by @value{GDBN} on the inferior
2273is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
2274@code{<gdb:symtab>}. Symbol table and line data for a frame is returned
2275from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
2276@xref{Frames In Guile}.
2277
2278For more information on @value{GDBN}'s symbol table management, see
2279@ref{Symbols, ,Examining the Symbol Table}.
2280
2281The following symtab-related procedures are provided by the
2282@code{(gdb)} module:
2283
2284@deffn {Scheme Procedure} symtab? object
2285Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
2286Otherwise return @code{#f}.
2287@end deffn
2288
2289@deffn {Scheme Procedure} symtab-valid? symtab
2290Return @code{#t} if the @code{<gdb:symtab>} object is valid,
2291@code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
2292the symbol table it refers to no longer exists in @value{GDBN}.
2293All other @code{<gdb:symtab>} procedures will throw an exception
2294if it is invalid at the time the procedure is called.
2295@end deffn
2296
2297@deffn {Scheme Procedure} symtab-filename symtab
2298Return the symbol table's source filename.
2299@end deffn
2300
2301@deffn {Scheme Procedure} symtab-fullname symtab
2302Return the symbol table's source absolute file name.
2303@end deffn
2304
2305@deffn {Scheme Procedure} symtab-objfile symtab
2306Return the symbol table's backing object file. @xref{Objfiles In Guile}.
2307@end deffn
2308
2309@deffn {Scheme Procedure} symtab-global-block symtab
2310Return the global block of the underlying symbol table.
2311@xref{Blocks In Guile}.
2312@end deffn
2313
2314@deffn {Scheme Procedure} symtab-static-block symtab
2315Return the static block of the underlying symbol table.
2316@xref{Blocks In Guile}.
2317@end deffn
2318
2319The following symtab-and-line-related procedures are provided by the
2320@code{(gdb)} module:
2321
2322@deffn {Scheme Procedure} sal? object
2323Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
2324Otherwise return @code{#f}.
2325@end deffn
2326
2327@deffn {Scheme Procedure} sal-valid? sal
2328Return @code{#t} if @var{sal} is valid, @code{#f} if not.
2329A @code{<gdb:sal>} object becomes invalid when the Symbol table object
2330it refers to no longer exists in @value{GDBN}. All other
2331@code{<gdb:sal>} procedures will throw an exception if it is
2332invalid at the time the procedure is called.
2333@end deffn
2334
2335@deffn {Scheme Procedure} sal-symtab sal
2336Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
2337@end deffn
2338
2339@deffn {Scheme Procedure} sal-line sal
2340Return the line number for @var{sal}.
2341@end deffn
2342
2343@deffn {Scheme Procedure} sal-pc sal
2344Return the start of the address range occupied by code for @var{sal}.
2345@end deffn
2346
2347@deffn {Scheme Procedure} sal-last sal
2348Return the end of the address range occupied by code for @var{sal}.
2349@end deffn
2350
2351@deffn {Scheme Procedure} find-pc-line pc
2352Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
2353If an invalid value of @var{pc} is passed as an argument, then the
2354@code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
2355object will be @code{#f} and 0 respectively.
2356@end deffn
2357
2358@node Breakpoints In Guile
2359@subsubsection Manipulating breakpoints using Guile
2360
2361@cindex breakpoints in guile
2362@tindex <gdb:breakpoint>
2363
2364Breakpoints in Guile are represented by objects of type
2365@code{<gdb:breakpoint>}.
2366
2367The following breakpoint-related procedures are provided by the
2368@code{(gdb)} module:
2369
2370@c TODO: line length
2371@deffn {Scheme Procedure} create-breakpoint! location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
697aa1b7 2372Create a new breakpoint according to @var{spec}, a string naming the
ed3ef339
DE
2373location of the breakpoint, or an expression that defines a watchpoint.
2374The contents can be any location recognized by the @code{break} command,
2375or in the case of a watchpoint, by the @code{watch} command.
2376
2377The optional @var{type} denotes the breakpoint to create.
697aa1b7
EZ
2378This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
2379and defaults to @code{BP_BREAKPOINT}.
ed3ef339
DE
2380
2381The optional @var{wp-class} argument defines the class of watchpoint to
2382create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
2383not provided, it is assumed to be a @code{WP_WRITE} class.
2384
2385The optional @var{internal} argument allows the breakpoint to become
2386invisible to the user. The breakpoint will neither be reported when
2387created, nor will it be listed in the output from @code{info breakpoints}
2388(but will be listed with the @code{maint info breakpoints} command).
2389If an internal flag is not provided, the breakpoint is visible
2390(non-internal).
2391
2392When a watchpoint is created, @value{GDBN} will try to create a
2393hardware assisted watchpoint. If successful, the type of the watchpoint
2394is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
2395for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
2396and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
2397If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
2398
2399The available types are represented by constants defined in the @code{gdb}
2400module:
2401
2402@vtable @code
2403@item BP_BREAKPOINT
2404Normal code breakpoint.
2405
2406@item BP_WATCHPOINT
2407Watchpoint breakpoint.
2408
2409@item BP_HARDWARE_WATCHPOINT
2410Hardware assisted watchpoint.
2411This value cannot be specified when creating the breakpoint.
2412
2413@item BP_READ_WATCHPOINT
2414Hardware assisted read watchpoint.
2415This value cannot be specified when creating the breakpoint.
2416
2417@item BP_ACCESS_WATCHPOINT
2418Hardware assisted access watchpoint.
2419This value cannot be specified when creating the breakpoint.
2420@end vtable
2421
2422The available watchpoint types represented by constants are defined in the
2423@code{(gdb)} module:
2424
2425@vtable @code
2426@item WP_READ
2427Read only watchpoint.
2428
2429@item WP_WRITE
2430Write only watchpoint.
2431
2432@item WP_ACCESS
2433Read/Write watchpoint.
2434@end vtable
2435
2436@end deffn
2437
2438@deffn {Scheme Procedure} breakpoint-delete! breakpoint
2439Permanently delete @var{breakpoint}. This also invalidates the
2440Guile @var{breakpoint} object. Any further attempt to access the
2441object will throw an exception.
2442@end deffn
2443
2444@deffn {Scheme Procedure} breakpoints
2445Return a list of all breakpoints.
2446Each element of the list is a @code{<gdb:breakpoint>} object.
2447@end deffn
2448
2449@deffn {Scheme Procedure} breakpoint? object
2450Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
2451and @code{#f} otherwise.
2452@end deffn
2453
2454@deffn {Scheme Procedure} breakpoint-valid? breakpoint
2455Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
2456A @code{<gdb:breakpoint>} object can become invalid
2457if the user deletes the breakpoint. In this case, the object still
2458exists, but the underlying breakpoint does not. In the cases of
2459watchpoint scope, the watchpoint remains valid even if execution of the
2460inferior leaves the scope of that watchpoint.
2461@end deffn
2462
2463@deffn {Scheme Procedure} breakpoint-number breakpoint
2464Return the breakpoint's number --- the identifier used by
2465the user to manipulate the breakpoint.
2466@end deffn
2467
2468@deffn {Scheme Procedure} breakpoint-type breakpoint
2469Return the breakpoint's type --- the identifier used to
2470determine the actual breakpoint type or use-case.
2471@end deffn
2472
2473@deffn {Scheme Procedure} breakpoint-visible? breakpoint
2474Return @code{#t} if the breakpoint is visible to the user
2475when hit, or when the @samp{info breakpoints} command is run.
2476Otherwise return @code{#f}.
2477@end deffn
2478
2479@deffn {Scheme Procedure} breakpoint-location breakpoint
2480Return the location of the breakpoint, as specified by
2481the user. It is a string. If the breakpoint does not have a location
2482(that is, it is a watchpoint) return @code{#f}.
2483@end deffn
2484
2485@deffn {Scheme Procedure} breakpoint-expression breakpoint
2486Return the breakpoint expression, as specified by the user. It is a string.
2487If the breakpoint does not have an expression (the breakpoint is not a
2488watchpoint) return @code{#f}.
2489@end deffn
2490
2491@deffn {Scheme Procedure} breakpoint-enabled? breakpoint
2492Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
2493@end deffn
2494
2495@deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag
2496Set the enabled state of @var{breakpoint} to @var{flag}.
2497If flag is @code{#f} it is disabled, otherwise it is enabled.
2498@end deffn
2499
2500@deffn {Scheme Procedure} breakpoint-silent? breakpoint
2501Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
2502
2503Note that a breakpoint can also be silent if it has commands and the
2504first command is @code{silent}. This is not reported by the
2505@code{silent} attribute.
2506@end deffn
2507
2508@deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag
2509Set the silent state of @var{breakpoint} to @var{flag}.
2510If flag is @code{#f} the breakpoint is made silent,
2511otherwise it is made non-silent (or noisy).
2512@end deffn
2513
2514@deffn {Scheme Procedure} breakpoint-ignore-count breakpoint
2515Return the ignore count for @var{breakpoint}.
2516@end deffn
2517
2518@deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count
2519Set the ignore count for @var{breakpoint} to @var{count}.
2520@end deffn
2521
2522@deffn {Scheme Procedure} breakpoint-hit-count breakpoint
2523Return hit count of @var{breakpoint}.
2524@end deffn
2525
2526@deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count
2527Set the hit count of @var{breakpoint} to @var{count}.
2528At present, @var{count} must be zero.
2529@end deffn
2530
2531@deffn {Scheme Procedure} breakpoint-thread breakpoint
2532Return the thread-id for thread-specific breakpoint @var{breakpoint}.
2533Return #f if @var{breakpoint} is not thread-specific.
2534@end deffn
2535
2536@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f
2537Set the thread-id for @var{breakpoint} to @var{thread-id}.
2538If set to @code{#f}, the breakpoint is no longer thread-specific.
2539@end deffn
2540
2541@deffn {Scheme Procedure} breakpoint-task breakpoint
2542If the breakpoint is Ada task-specific, return the Ada task id.
2543If the breakpoint is not task-specific (or the underlying
2544language is not Ada), return @code{#f}.
2545@end deffn
2546
2547@deffn {Scheme Procedure} set-breakpoint-task! breakpoint task
2548Set the Ada task of @var{breakpoint} to @var{task}.
2549If set to @code{#f}, the breakpoint is no longer task-specific.
2550@end deffn
2551
2552@deffn {Scheme Procedure} breakpoint-condition breakpoint
2553Return the condition of @var{breakpoint}, as specified by the user.
2554It is a string. If there is no condition, return @code{#f}.
2555@end deffn
2556
2557@deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition
2558Set the condition of @var{breakpoint} to @var{condition},
2559which must be a string. If set to @code{#f} then the breakpoint
2560becomes unconditional.
2561@end deffn
2562
2563@deffn {Scheme Procedure} breakpoint-stop breakpoint
2564Return the stop predicate of @var{breakpoint}.
2565See @code{set-breakpoint-stop!} below in this section.
2566@end deffn
2567
2568@deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
697aa1b7 2569Set the stop predicate of @var{breakpoint}. The predicate
ed3ef339
DE
2570@var{procedure} takes one argument: the <gdb:breakpoint> object.
2571If this predicate is set to a procedure then it is invoked whenever
2572the inferior reaches this breakpoint. If it returns @code{#t},
2573or any non-@code{#f} value, then the inferior is stopped,
2574otherwise the inferior will continue.
2575
2576If there are multiple breakpoints at the same location with a
2577@code{stop} predicate, each one will be called regardless of the
2578return status of the previous. This ensures that all @code{stop}
2579predicates have a chance to execute at that location. In this scenario
2580if one of the methods returns @code{#t} but the others return
2581@code{#f}, the inferior will still be stopped.
2582
2583You should not alter the execution state of the inferior (i.e.@:, step,
2584next, etc.), alter the current frame context (i.e.@:, change the current
2585active frame), or alter, add or delete any breakpoint. As a general
2586rule, you should not alter any data within @value{GDBN} or the inferior
2587at this time.
2588
2589Example @code{stop} implementation:
2590
2591@smallexample
2592(define (my-stop? bkpt)
2593 (let ((int-val (parse-and-eval "foo")))
2594 (value=? int-val 3)))
2595(define bkpt (create-breakpoint! "main.c:42"))
2596(set-breakpoint-stop! bkpt my-stop?)
2597@end smallexample
2598@end deffn
2599
2600@deffn {Scheme Procedure} breakpoint-commands breakpoint
2601Return the commands attached to @var{breakpoint} as a string,
2602or @code{#f} if there are none.
2603@end deffn
2604
2605@node Lazy Strings In Guile
2606@subsubsection Guile representation of lazy strings.
2607
2608@cindex lazy strings in guile
2609@tindex <gdb:lazy-string>
2610
2611A @dfn{lazy string} is a string whose contents is not retrieved or
2612encoded until it is needed.
2613
2614A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
2615@code{address} that points to a region of memory, an @code{encoding}
2616that will be used to encode that region of memory, and a @code{length}
2617to delimit the region of memory that represents the string. The
2618difference between a @code{<gdb:lazy-string>} and a string wrapped within
2619a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
2620differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
2621retrieved and encoded during printing, while a @code{<gdb:value>}
2622wrapping a string is immediately retrieved and encoded on creation.
2623
2624The following lazy-string-related procedures are provided by the
2625@code{(gdb)} module:
2626
2627@deffn {Scheme Procedure} lazy-string? object
2628Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
2629Otherwise return @code{#f}.
2630@end deffn
2631
2632@deffn {Scheme Procedure} lazy-string-address lazy-sring
2633Return the address of @var{lazy-string}.
2634@end deffn
2635
2636@deffn {Scheme Procedure} lazy-string-length lazy-string
2637Return the length of @var{lazy-string} in characters. If the
2638length is -1, then the string will be fetched and encoded up to the
2639first null of appropriate width.
2640@end deffn
2641
2642@deffn {Scheme Procedure} lazy-string-encoding lazy-string
2643Return the encoding that will be applied to @var{lazy-string}
2644when the string is printed by @value{GDBN}. If the encoding is not
2645set, or contains an empty string, then @value{GDBN} will select the
2646most appropriate encoding when the string is printed.
2647@end deffn
2648
2649@deffn {Scheme Procedure} lazy-string-type lazy-string
2650Return the type that is represented by @var{lazy-string}'s type.
2651For a lazy string this will always be a pointer type. To
2652resolve this to the lazy string's character type, use @code{type-target-type}.
2653@xref{Types In Guile}.
2654@end deffn
2655
2656@deffn {Scheme Procedure} lazy-string->value lazy-string
2657Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
2658will point to the string in memory, but will lose all the delayed
2659retrieval, encoding and handling that @value{GDBN} applies to a
2660@code{<gdb:lazy-string>}.
2661@end deffn
2662
2663@node Architectures In Guile
2664@subsubsection Guile representation of architectures
2665
2666@cindex guile architectures
2667@tindex <gdb:arch>
2668
2669@value{GDBN} uses architecture specific parameters and artifacts in a
2670number of its various computations. An architecture is represented
2671by an instance of the @code{<gdb:arch>} class.
2672
2673The following architecture-related procedures are provided by the
2674@code{(gdb)} module:
2675
2676@deffn {Scheme Procedure} arch? object
2677Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
2678Otherwise return @code{#f}.
2679@end deffn
2680
2681@deffn {Scheme Procedure} current-arch
2682Return the current architecture as a @code{<gdb:arch>} object.
2683@end deffn
2684
2685@deffn {Scheme Procedure} arch-name arch
2686Return the name (string value) of @code{<gdb:arch>} @var{arch}.
2687@end deffn
2688
2689@deffn {Scheme Procedure} arch-charset arch
2690Return name of target character set of @code{<gdb:arch>} @var{arch}.
2691@end deffn
2692
2693@deffn {Scheme Procedure} arch-wide-charset
2694Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
2695@end deffn
2696
2697Each architecture provides a set of predefined types, obtained by
2698the following functions.
2699
2700@deffn {Scheme Procedure} arch-void-type arch
2701Return the @code{<gdb:type>} object for a @code{void} type
2702of architecture @var{arch}.
2703@end deffn
2704
2705@deffn {Scheme Procedure} arch-char-type arch
2706Return the @code{<gdb:type>} object for a @code{char} type
2707of architecture @var{arch}.
2708@end deffn
2709
2710@deffn {Scheme Procedure} arch-short-type arch
2711Return the @code{<gdb:type>} object for a @code{short} type
2712of architecture @var{arch}.
2713@end deffn
2714
2715@deffn {Scheme Procedure} arch-int-type arch
2716Return the @code{<gdb:type>} object for an @code{int} type
2717of architecture @var{arch}.
2718@end deffn
2719
2720@deffn {Scheme Procedure} arch-long-type arch
2721Return the @code{<gdb:type>} object for a @code{long} type
2722of architecture @var{arch}.
2723@end deffn
2724
2725@deffn {Scheme Procedure} arch-schar-type arch
2726Return the @code{<gdb:type>} object for a @code{signed char} type
2727of architecture @var{arch}.
2728@end deffn
2729
2730@deffn {Scheme Procedure} arch-uchar-type arch
2731Return the @code{<gdb:type>} object for an @code{unsigned char} type
2732of architecture @var{arch}.
2733@end deffn
2734
2735@deffn {Scheme Procedure} arch-ushort-type arch
2736Return the @code{<gdb:type>} object for an @code{unsigned short} type
2737of architecture @var{arch}.
2738@end deffn
2739
2740@deffn {Scheme Procedure} arch-uint-type arch
2741Return the @code{<gdb:type>} object for an @code{unsigned int} type
2742of architecture @var{arch}.
2743@end deffn
2744
2745@deffn {Scheme Procedure} arch-ulong-type arch
2746Return the @code{<gdb:type>} object for an @code{unsigned long} type
2747of architecture @var{arch}.
2748@end deffn
2749
2750@deffn {Scheme Procedure} arch-float-type arch
2751Return the @code{<gdb:type>} object for a @code{float} type
2752of architecture @var{arch}.
2753@end deffn
2754
2755@deffn {Scheme Procedure} arch-double-type arch
2756Return the @code{<gdb:type>} object for a @code{double} type
2757of architecture @var{arch}.
2758@end deffn
2759
2760@deffn {Scheme Procedure} arch-longdouble-type arch
2761Return the @code{<gdb:type>} object for a @code{long double} type
2762of architecture @var{arch}.
2763@end deffn
2764
2765@deffn {Scheme Procedure} arch-bool-type arch
2766Return the @code{<gdb:type>} object for a @code{bool} type
2767of architecture @var{arch}.
2768@end deffn
2769
2770@deffn {Scheme Procedure} arch-longlong-type arch
2771Return the @code{<gdb:type>} object for a @code{long long} type
2772of architecture @var{arch}.
2773@end deffn
2774
2775@deffn {Scheme Procedure} arch-ulonglong-type arch
2776Return the @code{<gdb:type>} object for an @code{unsigned long long} type
2777of architecture @var{arch}.
2778@end deffn
2779
2780@deffn {Scheme Procedure} arch-int8-type arch
2781Return the @code{<gdb:type>} object for an @code{int8} type
2782of architecture @var{arch}.
2783@end deffn
2784
2785@deffn {Scheme Procedure} arch-uint8-type arch
2786Return the @code{<gdb:type>} object for a @code{uint8} type
2787of architecture @var{arch}.
2788@end deffn
2789
2790@deffn {Scheme Procedure} arch-int16-type arch
2791Return the @code{<gdb:type>} object for an @code{int16} type
2792of architecture @var{arch}.
2793@end deffn
2794
2795@deffn {Scheme Procedure} arch-uint16-type arch
2796Return the @code{<gdb:type>} object for a @code{uint16} type
2797of architecture @var{arch}.
2798@end deffn
2799
2800@deffn {Scheme Procedure} arch-int32-type arch
2801Return the @code{<gdb:type>} object for an @code{int32} type
2802of architecture @var{arch}.
2803@end deffn
2804
2805@deffn {Scheme Procedure} arch-uint32-type arch
2806Return the @code{<gdb:type>} object for a @code{uint32} type
2807of architecture @var{arch}.
2808@end deffn
2809
2810@deffn {Scheme Procedure} arch-int64-type arch
2811Return the @code{<gdb:type>} object for an @code{int64} type
2812of architecture @var{arch}.
2813@end deffn
2814
2815@deffn {Scheme Procedure} arch-uint64-type arch
2816Return the @code{<gdb:type>} object for a @code{uint64} type
2817of architecture @var{arch}.
2818@end deffn
2819
2820Example:
2821
2822@smallexample
2823(gdb) guile (type-name (arch-uchar-type (current-arch)))
2824"unsigned char"
2825@end smallexample
2826
2827@node Disassembly In Guile
2828@subsubsection Disassembly In Guile
2829
2830The disassembler can be invoked from Scheme code.
2831Furthermore, the disassembler can take a Guile port as input,
2832allowing one to disassemble from any source, and not just target memory.
2833
2834@c TODO: line length
6fb526ee 2835@deffn {Scheme Procedure} arch-disassemble arch start-pc @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size size@r{]} @r{[}#:count count@r{]}
ed3ef339
DE
2836Return a list of disassembled instructions starting from the memory
2837address @var{start-pc}.
2838
2839The optional argument @var{port} specifies the input port to read bytes from.
2840If @var{port} is @code{#f} then bytes are read from target memory.
2841
2842The optional argument @var{offset} specifies the address offset of the
2843first byte in @var{port}. This is useful, for example, when @var{port}
2844specifies a @samp{bytevector} and you want the bytevector to be disassembled
2845as if it came from that address. The @var{start-pc} passed to the reader
2846for @var{port} is offset by the same amount.
2847
2848Example:
2849@smallexample
2850(gdb) guile (use-modules (rnrs io ports))
2851(gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
2852(gdb) guile (define mem (open-memory #:start pc))
2853(gdb) guile (define bv (get-bytevector-n mem 10))
2854(gdb) guile (define bv-port (open-bytevector-input-port bv))
2855(gdb) guile (define arch (current-arch))
2856(gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
2857(((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
2858@end smallexample
2859
2860The optional arguments @var{size} and
2861@var{count} determine the number of instructions in the returned list.
2862If either @var{size} or @var{count} is specified as zero, then
2863no instructions are disassembled and an empty list is returned.
2864If both the optional arguments @var{size} and @var{count} are
2865specified, then a list of at most @var{count} disassembled instructions
2866whose start address falls in the closed memory address interval from
2867@var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
2868If @var{size} is not specified, but @var{count} is specified,
2869then @var{count} number of instructions starting from the address
2870@var{start-pc} are returned. If @var{count} is not specified but
2871@var{size} is specified, then all instructions whose start address
2872falls in the closed memory address interval from @var{start-pc} to
2873(@var{start-pc} + @var{size} - 1) are returned.
2874If neither @var{size} nor @var{count} are specified, then a single
2875instruction at @var{start-pc} is returned.
2876
2877Each element of the returned list is an alist (associative list)
2878with the following keys:
2879
2880@table @code
2881
2882@item address
2883The value corresponding to this key is a Guile integer of
2884the memory address of the instruction.
2885
2886@item asm
2887The value corresponding to this key is a string value which represents
2888the instruction with assembly language mnemonics. The assembly
2889language flavor used is the same as that specified by the current CLI
2890variable @code{disassembly-flavor}. @xref{Machine Code}.
2891
2892@item length
2893The value corresponding to this key is the length of the instruction in bytes.
2894
2895@end table
2896@end deffn
2897
2898@node I/O Ports in Guile
2899@subsubsection I/O Ports in Guile
2900
2901@deffn {Scheme Procedure} input-port
2902Return @value{GDBN}'s input port as a Guile port object.
2903@end deffn
2904
2905@deffn {Scheme Procedure} output-port
2906Return @value{GDBN}'s output port as a Guile port object.
2907@end deffn
2908
2909@deffn {Scheme Procedure} error-port
2910Return @value{GDBN}'s error port as a Guile port object.
2911@end deffn
2912
2913@deffn {Scheme Procedure} stdio-port? object
2914Return @code{#t} if @var{object} is a @value{GDBN} stdio port.
2915Otherwise return @code{#f}.
2916@end deffn
2917
2918@node Memory Ports in Guile
2919@subsubsection Memory Ports in Guile
2920
2921@value{GDBN} provides a @code{port} interface to target memory.
2922This allows Guile code to read/write target memory using Guile's port and
2923bytevector functionality. The main routine is @code{open-memory} which
2924returns a port object. One can then read/write memory using that object.
2925
2926@deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
2927Return a port object that can be used for reading and writing memory.
697aa1b7
EZ
2928The port will be open according to @var{mode}, which is the standard
2929mode argument to Guile port open routines, except that it is
2930restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For
2931compatibility @samp{"b"} (binary) may also be present, but we ignore
2932it: memory ports are binary only. The default is @samp{"r"},
2933read-only.
ed3ef339
DE
2934
2935The chunk of memory that can be accessed can be bounded.
2936If both @var{start} and @var{size} are unspecified, all of memory can be
2937accessed. If only @var{start} is specified, all of memory from that point
2938on can be accessed. If only @var{size} if specified, all memory in the
2939range [0,@var{size}) can be accessed. If both are specified, all memory
2940in the rane [@var{start},@var{start}+@var{size}) can be accessed.
2941@end deffn
2942
2943@deffn {Scheme Procedure} memory-port?
2944Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
2945Otherwise return @code{#f}.
2946@end deffn
2947
2948@deffn {Scheme Procedure} memory-port-range memory-port
2949Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
2950of two elements: @code{(start end)}. The range is @var{start} to @var{end}
2951inclusive.
2952@end deffn
2953
2954@deffn {Scheme Procedure} memory-port-read-buffer-size memory-port
2955Return the size of the read buffer of @code{<gdb:memory-port>}
2956@var{memory-port}.
2957@end deffn
2958
2959@deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
2960Set the size of the read buffer of @code{<gdb:memory-port>}
2961@var{memory-port} to @var{size}. The result is unspecified.
2962@end deffn
2963
2964@deffn {Scheme Procedure} memory-port-write-buffer-size memory-port
2965Return the size of the write buffer of @code{<gdb:memory-port>}
2966@var{memory-port}.
2967@end deffn
2968
2969@deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
2970Set the size of the write buffer of @code{<gdb:memory-port>}
2971@var{memory-port} to @var{size}. The result is unspecified.
2972@end deffn
2973
2974A memory port is closed like any other port, with @code{close-port}.
2975
2976Combined with Guile's @code{bytevectors}, memory ports provide a lot
2977of utility. For example, to fill a buffer of 10 integers in memory,
2978one can do something like the following.
2979
2980@smallexample
2981;; In the program: int buffer[10];
2982(use-modules (rnrs bytevectors))
2983(use-modules (rnrs io ports))
2984(define addr (parse-and-eval "buffer"))
2985(define n 10)
2986(define byte-size (* n 4))
2987(define mem-port (open-memory #:mode "r+" #:start
2988 (value->integer addr) #:size byte-size))
2989(define byte-vec (make-bytevector byte-size))
2990(do ((i 0 (+ i 1)))
2991 ((>= i n))
2992 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
2993(put-bytevector mem-port byte-vec)
2994(close-port mem-port)
2995@end smallexample
2996
2997@node Iterators In Guile
2998@subsubsection Iterators In Guile
2999
3000@cindex guile iterators
3001@tindex <gdb:iterator>
3002
3003A simple iterator facility is provided to allow, for example,
3004iterating over the set of program symbols without having to first
3005construct a list of all of them. A useful contribution would be
3006to add support for SRFI 41 and SRFI 45.
3007
3008@deffn {Scheme Procedure} make-iterator object progress next!
3009A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
3010procedure. It takes three arguments: the object to be iterated over,
3011an object to record the progress of the iteration, and a procedure to
3012return the next element in the iteration, or an implementation chosen value
3013to denote the end of iteration.
3014
3015By convention, end of iteration is marked with @code{(end-of-iteration)},
3016and may be tested with the @code{end-of-iteration?} predicate.
3017The result of @code{(end-of-iteration)} is chosen so that it is not
3018otherwise used by the @code{(gdb)} module. If you are using
3019@code{<gdb:iterator>} in your own code it is your responsibility to
3020maintain this invariant.
3021
3022A trivial example for illustration's sake:
3023
3024@smallexample
3025(use-modules (gdb iterator))
3026(define my-list (list 1 2 3))
3027(define iter
3028 (make-iterator my-list my-list
3029 (lambda (iter)
3030 (let ((l (iterator-progress iter)))
3031 (if (eq? l '())
3032 (end-of-iteration)
3033 (begin
3034 (set-iterator-progress! iter (cdr l))
3035 (car l)))))))
3036@end smallexample
3037
3038Here is a slightly more realistic example, which computes a list of all the
3039functions in @code{my-global-block}.
3040
3041@smallexample
3042(use-modules (gdb iterator))
3043(define this-sal (find-pc-line (frame-pc (selected-frame))))
3044(define this-symtab (sal-symtab this-sal))
3045(define this-global-block (symtab-global-block this-symtab))
3046(define syms-iter (make-block-symbols-iterator this-global-block))
3047(define functions (iterator-filter symbol-function? syms-iter))
3048@end smallexample
3049@end deffn
3050
3051@deffn {Scheme Procedure} iterator? object
3052Return @code{#t} if @var{object} is a @code{<gdb:iterator>} object.
3053Otherwise return @code{#f}.
3054@end deffn
3055
3056@deffn {Scheme Procedure} iterator-object iterator
3057Return the first argument that was passed to @code{make-iterator}.
3058This is the object being iterated over.
3059@end deffn
3060
3061@deffn {Scheme Procedure} iterator-progress iterator
3062Return the object tracking iteration progress.
3063@end deffn
3064
3065@deffn {Scheme Procedure} set-iterator-progress! iterator new-value
3066Set the object tracking iteration progress.
3067@end deffn
3068
3069@deffn {Scheme Procedure} iterator-next! iterator
3070Invoke the procedure that was the third argument to @code{make-iterator},
3071passing it one argument, the @code{<gdb:iterator>} object.
3072The result is either the next element in the iteration, or an end
3073marker as implemented by the @code{next!} procedure.
3074By convention the end marker is the result of @code{(end-of-iteration)}.
3075@end deffn
3076
3077@deffn {Scheme Procedure} end-of-iteration
3078Return the Scheme object that denotes end of iteration.
3079@end deffn
3080
3081@deffn {Scheme Procedure} end-of-iteration? object
3082Return @code{#t} if @var{object} is the end of iteration marker.
3083Otherwise return @code{#f}.
3084@end deffn
3085
3086These functions are provided by the @code{(gdb iterator)} module to
3087assist in using iterators.
3088
3089@deffn {Scheme Procedure} make-list-iterator list
3090Return a @code{<gdb:iterator>} object that will iterate over @var{list}.
3091@end deffn
3092
3093@deffn {Scheme Procedure} iterator->list iterator
3094Return the elements pointed to by @var{iterator} as a list.
3095@end deffn
3096
3097@deffn {Scheme Procedure} iterator-map proc iterator
3098Return the list of objects obtained by applying @var{proc} to the object
3099pointed to by @var{iterator} and to each subsequent object.
3100@end deffn
3101
3102@deffn {Scheme Procedure} iterator-for-each proc iterator
3103Apply @var{proc} to each element pointed to by @var{iterator}.
3104The result is unspecified.
3105@end deffn
3106
3107@deffn {Scheme Procedure} iterator-filter pred iterator
3108Return the list of elements pointed to by @var{iterator} that satisfy
3109@var{pred}.
3110@end deffn
3111
3112@deffn {Scheme Procedure} iterator-until pred iterator
3113Run @var{iterator} until the result of @code{(pred element)} is true
3114and return that as the result. Otherwise return @code{#f}.
3115@end deffn
3116
3117@node Guile Auto-loading
3118@subsection Guile Auto-loading
3119@cindex guile auto-loading
3120
3121When a new object file is read (for example, due to the @code{file}
3122command, or because the inferior has loaded a shared library),
3123@value{GDBN} will look for Guile support scripts in two ways:
3124@file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
3125@xref{Auto-loading extensions}.
3126
3127The auto-loading feature is useful for supplying application-specific
3128debugging commands and scripts.
3129
3130Auto-loading can be enabled or disabled,
3131and the list of auto-loaded scripts can be printed.
3132
3133@table @code
3134@anchor{set auto-load guile-scripts}
3135@kindex set auto-load guile-scripts
3136@item set auto-load guile-scripts [on|off]
3137Enable or disable the auto-loading of Guile scripts.
3138
3139@anchor{show auto-load guile-scripts}
3140@kindex show auto-load guile-scripts
3141@item show auto-load guile-scripts
3142Show whether auto-loading of Guile scripts is enabled or disabled.
3143
3144@anchor{info auto-load guile-scripts}
3145@kindex info auto-load guile-scripts
3146@cindex print list of auto-loaded Guile scripts
3147@item info auto-load guile-scripts [@var{regexp}]
3148Print the list of all Guile scripts that @value{GDBN} auto-loaded.
3149
3150Also printed is the list of Guile scripts that were mentioned in
3151the @code{.debug_gdb_scripts} section and were not found.
3152This is useful because their names are not printed when @value{GDBN}
3153tries to load them and fails. There may be many of them, and printing
3154an error message for each one is problematic.
3155
3156If @var{regexp} is supplied only Guile scripts with matching names are printed.
3157
3158Example:
3159
3160@smallexample
3161(gdb) info auto-load guile-scripts
3162Loaded Script
3163Yes scm-section-script.scm
3164 full name: /tmp/scm-section-script.scm
3165No my-foo-pretty-printers.scm
3166@end smallexample
3167@end table
3168
3169When reading an auto-loaded file, @value{GDBN} sets the
3170@dfn{current objfile}. This is available via the @code{current-objfile}
3171procedure (@pxref{Objfiles In Guile}). This can be useful for
3172registering objfile-specific pretty-printers.
3173
3174@node Guile Modules
3175@subsection Guile Modules
3176@cindex guile modules
3177
3178@value{GDBN} comes with several modules to assist writing Guile code.
3179
3180@menu
3181* Guile Printing Module:: Building and registering pretty-printers
3182* Guile Types Module:: Utilities for working with types
3183@end menu
3184
3185@node Guile Printing Module
3186@subsubsection Guile Printing Module
3187
3188This module provides a collection of utilities for working with
3189pretty-printers.
3190
3191Usage:
3192
3193@smallexample
3194(use-modules (gdb printing))
3195@end smallexample
3196
3197@deffn {Scheme Procedure} prepend-pretty-printer! object printer
3198Add @var{printer} to the front of the list of pretty-printers for
697aa1b7 3199@var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
ed3ef339
DE
3200or @code{#f} in which case @var{printer} is added to the global list of
3201printers.
3202@end deffn
3203
3204@deffn {Scheme Procecure} append-pretty-printer! object printer
3205Add @var{printer} to the end of the list of pretty-printers for
697aa1b7 3206@var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
ed3ef339
DE
3207or @code{#f} in which case @var{printer} is added to the global list of
3208printers.
3209@end deffn
3210
3211@node Guile Types Module
3212@subsubsection Guile Types Module
3213
3214This module provides a collection of utilities for working with
3215@code{<gdb:type>} objects.
3216
3217Usage:
3218
3219@smallexample
3220(use-modules (gdb types))
3221@end smallexample
3222
3223@deffn {Scheme Procedure} get-basic-type type
3224Return @var{type} with const and volatile qualifiers stripped,
3225and with typedefs and C@t{++} references converted to the underlying type.
3226
3227C@t{++} example:
3228
3229@smallexample
3230typedef const int const_int;
3231const_int foo (3);
3232const_int& foo_ref (foo);
3233int main () @{ return 0; @}
3234@end smallexample
3235
3236Then in gdb:
3237
3238@smallexample
3239(gdb) start
0f1e8403 3240(gdb) guile (use-modules (gdb) (gdb types))
ed3ef339
DE
3241(gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
3242(gdb) guile (get-basic-type (value-type foo-ref))
3243int
3244@end smallexample
3245@end deffn
3246
3247@deffn {Scheme Procedure} type-has-field-deep? type field
3248Return @code{#t} if @var{type}, assumed to be a type with fields
3249(e.g., a structure or union), has field @var{field}.
3250Otherwise return @code{#f}.
3251This searches baseclasses, whereas @code{type-has-field?} does not.
3252@end deffn
3253
3254@deffn {Scheme Procedure} make-enum-hashtable enum-type
3255Return a Guile hash table produced from @var{enum-type}.
3256Elements in the hash table are referenced with @code{hashq-ref}.
3257@end deffn
This page took 0.211892 seconds and 4 git commands to generate.