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