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