X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fguile.texi;h=c0bff7972f7d3810bb6f9bd55ac8050ac80ce477;hb=65c574f6dd066a239a94c2df0e1e12d50eae06c9;hp=7082ef9d1825f783e830d0805a71578cad317547;hpb=9eaa4c1ed5fba66876aa1e491121e16250f6bd1f;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index 7082ef9d18..c0bff7972f 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2008-2014 Free Software Foundation, Inc. +@c Copyright (C) 2008--2020 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.3 or @c any later version published by the Free Software Foundation; with the @@ -141,6 +141,9 @@ from the Guile interactive prompt. * Guile Pretty Printing API:: Pretty-printing values with Guile * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer * Writing a Guile Pretty-Printer:: Writing a pretty-printer +* Commands In Guile:: Implementing new commands in Guile +* Parameters In Guile:: Adding new @value{GDBN} parameters +* Progspaces In Guile:: Program spaces * Objfiles In Guile:: Object files in Guile * Frames In Guile:: Accessing inferior stack frames from Guile * Blocks In Guile:: Accessing blocks from Guile @@ -292,16 +295,14 @@ Parse @var{expression} as an expression in the current language, evaluate it, and return the result as a @code{}. The @var{expression} must be a string. -This function is useful when computing values. +This function can be useful when implementing a new command +(@pxref{Commands In Guile}), as it provides a way to parse the +command's arguments as an expression. +It is also is useful when computing values. For example, it is the only way to get the value of a convenience variable (@pxref{Convenience Vars}) as a @code{}. @end deffn -@deffn {Scheme Procedure} string->argv string -Convert a string to a list of strings split up according to -@value{GDBN}'s argv parsing rules. -@end deffn - @node Guile Configuration @subsubsection Guile Configuration @cindex guile configuration @@ -311,8 +312,12 @@ parameters. @deffn {Scheme Procedure} data-directory Return a string containing @value{GDBN}'s data directory. -This directory contains @value{GDBN}'s ancillary files, including -the Guile modules provided by @value{GDBN}. +This directory contains @value{GDBN}'s ancillary files. +@end deffn + +@deffn {Scheme Procedure} guile-data-directory +Return a string containing @value{GDBN}'s Guile data directory. +This directory contains the Guile modules provided by @value{GDBN}. @end deffn @deffn {Scheme Procedure} gdb-version @@ -331,46 +336,18 @@ This is the string passed to @code{--target} when @value{GDBN} was configured. @node GDB Scheme Data Types @subsubsection GDB Scheme Data Types -@cindex gdb smobs +@cindex gdb objects -@value{GDBN} uses Guile's @dfn{smob} (small object) -data type for all @value{GDBN} objects -(@pxref{Defining New Types (Smobs),,, guile, GNU Guile Reference Manual}). -The smobs that @value{GDBN} provides are called @dfn{gsmobs}. +The values exposed by @value{GDBN} to Guile are known as +@dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN} +object, and each is disjoint from all other types known to Guile. -@deffn {Scheme Procedure} gsmob-kind gsmob -Return the kind of the gsmob, e.g., @code{}, +@deffn {Scheme Procedure} gdb-object-kind object +Return the kind of the @value{GDBN} object, e.g., @code{}, as a symbol. @end deffn -Every @code{gsmob} provides a common set of functions for extending -them in simple ways. Each @code{gsmob} has a list of properties, -initially empty. These properties are akin to Guile's object properties, -but are stored with the @code{gsmob} -(@pxref{Object Properties,,, guile, GNU Guile Reference Manual}). -Property names can be any @code{eq?}-able value, but it is recommended -that they be symbols. - -@deffn {Scheme Procedure} set-gsmob-property! gsmob property-name value -Set the value of property @code{property-name} to value @code{value}. -The result is unspecified. -@end deffn - -@deffn {Scheme Procedure} gsmob-property gsmob property-name -Return the value of property @code{property-name}. -If the property isn't present then @code{#f} is returned. -@end deffn - -@deffn {Scheme Procedure} gsmob-has-property? gsmob property-name -Return @code{#t} if @code{gsmob} has property @code{property-name}. -Otherwise return @code{#f}. -@end deffn - -@deffn {Scheme Procedure} gsmob-properties gsmob -Return an unsorted list of names of properties. -@end deffn - -@value{GDBN} defines the following Scheme smobs: +@value{GDBN} defines the following object types: @table @code @item @@ -385,6 +362,9 @@ Return an unsorted list of names of properties. @item @xref{Breakpoints In Guile}. +@item +@xref{Commands In Guile}. + @item @xref{Guile Exception Handling}. @@ -400,12 +380,18 @@ Return an unsorted list of names of properties. @item @xref{Objfiles In Guile}. +@item +@xref{Parameters In Guile}. + @item @xref{Guile Pretty Printing API}. @item @xref{Guile Pretty Printing API}. +@item +@xref{Progspaces In Guile}. + @item @xref{Symbols In Guile}. @@ -425,8 +411,8 @@ Return an unsorted list of names of properties. @xref{Values From Inferior In Guile}. @end table -The following gsmobs are managed internally so that the Scheme function -@code{eq?} may be applied to them. +The following @value{GDBN} objects are managed internally so that the +Scheme function @code{eq?} may be applied to them. @table @code @item @@ -434,6 +420,7 @@ The following gsmobs are managed internally so that the Scheme function @item @item @item +@item @item @item @item @@ -742,7 +729,7 @@ The result @code{bar} will be a @code{} object holding the value pointed to by @code{foo}. A similar function @code{value-referenced-value} exists which also -returns @code{} objects corresonding to the values pointed to +returns @code{} objects corresponding to the values pointed to by pointer values (and additionally, values referenced by reference values). However, the behavior of @code{value-dereference} differs from @code{value-referenced-value} by the fact that the @@ -1271,7 +1258,7 @@ A string of bits. It is deprecated. An unknown or erroneous type. @item TYPE_CODE_METHOD -A method type, as found in C@t{++} or Java. +A method type, as found in C@t{++}. @item TYPE_CODE_METHODPTR A pointer-to-member-function. @@ -1335,7 +1322,7 @@ Return the enum value represented by @code{} @var{field}. @deffn {Scheme Procedure} field-bitpos field Return the bit position of @code{} @var{field}. This attribute is not available for @code{static} fields (as in -C@t{++} or Java). +C@t{++}). @end deffn @deffn {Scheme Procedure} field-bitsize field @@ -1390,7 +1377,16 @@ Otherwise return @code{#f}. @deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag Set the enabled flag of @var{pretty-printer} to @var{flag}. -The value returned in unspecified. +The value returned is unspecified. +@end deffn + +@deffn {Scheme Procedure} pretty-printers +Return the list of global pretty-printers. +@end deffn + +@deffn {Scheme Procedure} set-pretty-printers! pretty-printers +Set the list of global pretty-printers to @var{pretty-printers}. +The value returned is unspecified. @end deffn @deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children @@ -1473,6 +1469,9 @@ object which is convertible to a @value{GDBN} value. If @var{children} is @code{#f}, @value{GDBN} will act as though the value has no children. + +Children may be hidden from display based on the value of @samp{set +print max-depth} (@pxref{Print Settings}). @end table @end deffn @@ -1489,27 +1488,36 @@ printer exists, then this returns @code{#f}. @subsubsection Selecting Guile Pretty-Printers @cindex selecting guile pretty-printers -The Guile list @code{*pretty-printers*} contains a set of -@code{} registered objects. -Printers in this list are called @code{global} -printers, they're available when debugging any inferior. -In addition to this, each @code{} object contains its -own set of pretty-printers (@pxref{Objfiles In Guile}). +There are three sets of pretty-printers that @value{GDBN} searches: + +@itemize @bullet +@item +Per-objfile list of pretty-printers (@pxref{Objfiles In Guile}). +@item +Per-progspace list of pretty-printers (@pxref{Progspaces In Guile}). +@item +The global list of pretty-printers (@pxref{Guile Pretty Printing API}). +These printers are available when debugging any inferior. +@end itemize Pretty-printer lookup is done by passing the value to be printed to the lookup function of each enabled object in turn. Lookup stops when a lookup function returns a non-@code{#f} value or when the list is exhausted. +Lookup functions must return either a @code{} +object or @code{#f}. Otherwise an exception is thrown. @value{GDBN} first checks the result of @code{objfile-pretty-printers} of each @code{} in the current program space and iteratively calls each enabled lookup function in the list for that @code{} until a non-@code{#f} object is returned. -Lookup functions must return either a @code{} -object or @code{#f}. Otherwise an exception is thrown. If no pretty-printer is found in the objfile lists, @value{GDBN} then -searches the global pretty-printer list, calling each enabled function -until a non-@code{#f} object is returned. +searches the result of @code{progspace-pretty-printers} of the current +program space, calling each enabled function until a non-@code{#f} object +is returned. +After these lists have been exhausted, it tries the global pretty-printers +list, obtained with @code{pretty-printers}, again calling each enabled +function until a non-@code{#f} object is returned. The order in which the objfiles are searched is not specified. For a given list, functions are always invoked from the head of the list, @@ -1688,6 +1696,529 @@ my_library.so: bar @end smallexample +@node Commands In Guile +@subsubsection Commands In Guile + +@cindex commands in guile +@cindex guile commands +You can implement new @value{GDBN} CLI commands in Guile. A CLI +command object is created with the @code{make-command} Guile function, +and added to @value{GDBN} with the @code{register-command!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the command to @value{GDBN} from @code{make-command}. + +There is no support for multi-line commands, that is commands that +consist of multiple lines and are terminated with @code{end}. + +@c TODO: line length +@deffn {Scheme Procedure} (make-command name @r{[}#:invoke invoke{]} @r{[}#:command-class command-class@r{]} @r{[}#:completer-class completer{]} @r{[}#:prefix? prefix@r{]} @r{[}#:doc doc-string{]}) + +The argument @var{name} is the name of the command. If @var{name} consists of +multiple words, then the initial words are looked for as prefix +commands. In this case, if one of the prefix commands does not exist, +an exception is raised. + +The result is the @code{} object representing the command. +The command is not usable until it has been registered with @value{GDBN} +with @code{register-command!}. + +The rest of the arguments are optional. + +The argument @var{invoke} is a procedure of three arguments: @var{self}, +@var{args} and @var{from-tty}. The argument @var{self} is the +@code{} object representing the command. +The argument @var{args} is a string representing the arguments passed to +the command, after leading and trailing whitespace has been stripped. +The argument @var{from-tty} is a boolean flag and specifies whether the +command should consider itself to have been originated from the user +invoking it interactively. If this function throws an exception, +it is turned into a @value{GDBN} @code{error} call. +Otherwise, the return value is ignored. + +The argument @var{command-class} is one of the @samp{COMMAND_} constants +defined below. This argument tells @value{GDBN} how to categorize the +new command in the help system. The default is @code{COMMAND_NONE}. + +The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_} +constants defined below, or a procedure, also defined below. +This argument tells @value{GDBN} how to perform completion +for this command. If not provided or if the value is @code{#f}, +then no completion is performed on the command. + +The argument @var{prefix} is a boolean flag indicating whether the new +command is a prefix command; sub-commands of this command may be +registered. + +The argument @var{doc-string} is help text for the new command. +If no documentation string is provided, the default value ``This command is +not documented.'' is used. +@end deffn + +@deffn {Scheme Procedure} register-command! command +Add @var{command}, a @code{} object, to @value{GDBN}'s +list of commands. +It is an error to register a command more than once. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} command? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@cindex don't repeat Guile command +@deffn {Scheme Procedure} dont-repeat +By default, a @value{GDBN} command is repeated when the user enters a +blank line at the command prompt. A command can suppress this +behavior by invoking the @code{dont-repeat} function. This is similar +to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. +@end deffn + +@deffn {Scheme Procedure} string->argv string +Convert a string to a list of strings split up according to +@value{GDBN}'s argv parsing rules. +It is recommended to use this for consistency. +Arguments are separated by spaces and may be quoted. +Example: + +@smallexample +scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") +$1 = ("1" "2 \"3" "4 \"5" "6 '7") +@end smallexample +@end deffn + +@deffn {Scheme Procedure} throw-user-error message . args +Throw a @code{gdb:user-error} exception. +The argument @var{message} is the error message as a format string, like the +@var{fmt} argument to the @code{format} Scheme function. +@xref{Formatted Output,,, guile, GNU Guile Reference Manual}. +The argument @var{args} is a list of the optional arguments of @var{message}. + +This is used when the command detects a user error of some kind, +say a bad command argument. + +@smallexample +(gdb) guile (use-modules (gdb)) +(gdb) guile +(register-command! (make-command "test-user-error" + #:command-class COMMAND_OBSCURE + #:invoke (lambda (self arg from-tty) + (throw-user-error "Bad argument ~a" arg)))) +end +(gdb) test-user-error ugh +ERROR: Bad argument ugh +@end smallexample +@end deffn + +@cindex completion of Guile commands +@deffn completer self text word +If the @var{completer} option to @code{make-command} is a procedure, +it takes three arguments: @var{self} which is the @code{} +object, and @var{text} and @var{word} which are both strings. +The argument @var{text} holds the complete command line up to the cursor's +location. The argument @var{word} holds the last word of the command line; +this is computed using a word-breaking heuristic. + +All forms of completion are handled by this function, that is, +the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}), +and the @code{complete} command (@pxref{Help, complete}). + +This procedure can return several kinds of values: + +@itemize @bullet +@item +If the return value is a list, the contents of the list are used as the +completions. It is up to @var{completer} to ensure that the +contents actually do complete the word. An empty list is +allowed, it means that there were no completions available. Only +string elements of the list are used; other elements in the +list are ignored. + +@item +If the return value is a @code{} object, it is iterated over to +obtain the completions. It is up to @code{completer-procedure} to ensure +that the results actually do complete the word. Only +string elements of the result are used; other elements in the +sequence are ignored. + +@item +All other results are treated as though there were no available +completions. +@end itemize +@end deffn + +When a new command is registered, it will have been declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the @code{gdb} module: + +@vtable @code +@item COMMAND_NONE +The command does not belong to any particular class. A command in +this category will not be displayed in any of the help categories. +This is the default. + +@item COMMAND_RUNNING +The command is related to running the inferior. For example, +@code{start}, @code{step}, and @code{continue} are in this category. +Type @kbd{help running} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_DATA +The command is related to data or variables. For example, +@code{call}, @code{find}, and @code{print} are in this category. Type +@kbd{help data} at the @value{GDBN} prompt to see a list of commands +in this category. + +@item COMMAND_STACK +The command has to do with manipulation of the stack. For example, +@code{backtrace}, @code{frame}, and @code{return} are in this +category. Type @kbd{help stack} at the @value{GDBN} prompt to see a +list of commands in this category. + +@item COMMAND_FILES +This class is used for file-related commands. For example, +@code{file}, @code{list} and @code{section} are in this category. +Type @kbd{help files} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_SUPPORT +This should be used for ``support facilities'', generally meaning +things that are useful to the user when interacting with @value{GDBN}, +but not related to the state of the inferior. For example, +@code{help}, @code{make}, and @code{shell} are in this category. Type +@kbd{help support} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_STATUS +The command is an @samp{info}-related command, that is, related to the +state of @value{GDBN} itself. For example, @code{info}, @code{macro}, +and @code{show} are in this category. Type @kbd{help status} at the +@value{GDBN} prompt to see a list of commands in this category. + +@item COMMAND_BREAKPOINTS +The command has to do with breakpoints. For example, @code{break}, +@code{clear}, and @code{delete} are in this category. Type @kbd{help +breakpoints} at the @value{GDBN} prompt to see a list of commands in +this category. + +@item COMMAND_TRACEPOINTS +The command has to do with tracepoints. For example, @code{trace}, +@code{actions}, and @code{tfind} are in this category. Type +@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_USER +The command is a general purpose command for the user, and typically +does not fit in one of the other categories. +Type @kbd{help user-defined} at the @value{GDBN} prompt to see +a list of commands in this category, as well as the list of gdb macros +(@pxref{Sequences}). + +@item COMMAND_OBSCURE +The command is only used in unusual circumstances, or is not of +general interest to users. For example, @code{checkpoint}, +@code{fork}, and @code{stop} are in this category. Type @kbd{help +obscure} at the @value{GDBN} prompt to see a list of commands in this +category. + +@item COMMAND_MAINTENANCE +The command is only useful to @value{GDBN} maintainers. The +@code{maintenance} and @code{flushregs} commands are in this category. +Type @kbd{help internals} at the @value{GDBN} prompt to see a list of +commands in this category. +@end vtable + +A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it +from the @code{completer} procedure. These predefined completion +constants are all defined in the @code{gdb} module: + +@vtable @code +@item COMPLETE_NONE +This constant means that no completion should be done. + +@item COMPLETE_FILENAME +This constant means that filename completion should be performed. + +@item COMPLETE_LOCATION +This constant means that location completion should be done. +@xref{Specify Location}. + +@item COMPLETE_COMMAND +This constant means that completion should examine @value{GDBN} +command names. + +@item COMPLETE_SYMBOL +This constant means that completion should be done using symbol names +as the source. + +@item COMPLETE_EXPRESSION +This constant means that completion should be done on expressions. +Often this means completing on symbol names, but some language +parsers also have support for completing on field names. +@end vtable + +The following code snippet shows how a trivial CLI command can be +implemented in Guile: + +@smallexample +(gdb) guile +(register-command! (make-command "hello-world" + #:command-class COMMAND_USER + #:doc "Greet the whole world." + #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) +end +(gdb) hello-world +Hello, World! +@end smallexample + +@node Parameters In Guile +@subsubsection Parameters In Guile + +@cindex parameters in guile +@cindex guile parameters +@tindex Parameter +You can implement new @value{GDBN} @dfn{parameters} using Guile +@footnote{Note that @value{GDBN} parameters must not be confused with +Guile’s parameter objects (@pxref{Parameters,,, guile, GNU Guile +Reference Manual}).}. + +There are many parameters that already exist and can be set in +@value{GDBN}. Two examples are: @code{set follow-fork} and +@code{set charset}. Setting these parameters influences certain +behavior in @value{GDBN}. Similarly, you can define parameters that +can be used to influence behavior in custom Guile scripts and commands. + +A new parameter is defined with the @code{make-parameter} Guile function, +and added to @value{GDBN} with the @code{register-parameter!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the parameter to @value{GDBN} from @code{make-parameter}. + +Parameters are exposed to the user via the @code{set} and +@code{show} commands. @xref{Help}. + +@c TODO line length +@deffn {Scheme Procedure} (make-parameter name @r{[}#:command-class command-class@r{]} @r{[}#:parameter-type parameter-type{]} @r{[}#:enum-list enum-list@r{]} @r{[}#:set-func set-func{]} @r{[}#:show-func show-func{]} @r{[}#:doc doc{]} @r{[}#:set-doc set-doc{]} @r{[}#:show-doc show-doc{]} @r{[}#:initial-value initial-value{]}) + +The argument @var{name} is the name of the new parameter. If @var{name} +consists of multiple words, then the initial words are looked for as prefix +parameters. An example of this can be illustrated with the +@code{set print} set of parameters. If @var{name} is +@code{print foo}, then @code{print} will be searched as the prefix +parameter. In this case the parameter can subsequently be accessed in +@value{GDBN} as @code{set print foo}. +If @var{name} consists of multiple words, and no prefix parameter group +can be found, an exception is raised. + +The result is the @code{} object representing the parameter. +The parameter is not usable until it has been registered with @value{GDBN} +with @code{register-parameter!}. + +The rest of the arguments are optional. + +The argument @var{command-class} should be one of the @samp{COMMAND_} constants +(@pxref{Commands In Guile}). This argument tells @value{GDBN} how to +categorize the new parameter in the help system. +The default is @code{COMMAND_NONE}. + +The argument @var{parameter-type} should be one of the @samp{PARAM_} constants +defined below. This argument tells @value{GDBN} the type of the new +parameter; this information is used for input validation and +completion. The default is @code{PARAM_BOOLEAN}. + +If @var{parameter-type} is @code{PARAM_ENUM}, then +@var{enum-list} must be a list of strings. These strings +represent the possible values for the parameter. + +If @var{parameter-type} is not @code{PARAM_ENUM}, then the presence +of @var{enum-list} will cause an exception to be thrown. + +The argument @var{set-func} is a function of one argument: @var{self} which +is the @code{} object representing the parameter. +@value{GDBN} will call this function when a @var{parameter}'s value has +been changed via the @code{set} API (for example, @kbd{set foo off}). +The value of the parameter has already been set to the new value. +This function must return a string to be displayed to the user. +@value{GDBN} will add a trailing newline if the string is non-empty. +@value{GDBN} generally doesn't print anything when a parameter is set, +thus typically this function should return @samp{""}. +A non-empty string result should typically be used for displaying warnings +and errors. + +The argument @var{show-func} is a function of two arguments: @var{self} which +is the @code{} object representing the parameter, and +@var{svalue} which is the string representation of the current value. +@value{GDBN} will call this function when a @var{parameter}'s +@code{show} API has been invoked (for example, @kbd{show foo}). +This function must return a string, and will be displayed to the user. +@value{GDBN} will add a trailing newline. + +The argument @var{doc} is the help text for the new parameter. +If there is no documentation string, a default value is used. + +The argument @var{set-doc} is the help text for this parameter's +@code{set} command. + +The argument @var{show-doc} is the help text for this parameter's +@code{show} command. + +The argument @var{initial-value} specifies the initial value of the parameter. +If it is a function, it takes one parameter, the @code{} +object and its result is used as the initial value of the parameter. +The initial value must be valid for the parameter type, +otherwise an exception is thrown. +@end deffn + +@deffn {Scheme Procedure} register-parameter! parameter +Add @var{parameter}, a @code{} object, to @value{GDBN}'s +list of parameters. +It is an error to register a parameter more than once. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} parameter? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} parameter-value parameter +Return the value of @var{parameter} which may either be +a @code{} object or a string naming the parameter. +@end deffn + +@deffn {Scheme Procedure} set-parameter-value! parameter new-value +Assign @var{parameter} the value of @var{new-value}. +The argument @var{parameter} must be an object of type @code{}. +@value{GDBN} does validation when assignments are made. +@end deffn + +When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the @code{gdb} +module: + +@vtable @code +@item PARAM_BOOLEAN +The value is a plain boolean. The Guile boolean values, @code{#t} +and @code{#f} are the only valid values. + +@item PARAM_AUTO_BOOLEAN +The value has three possible states: true, false, and @samp{auto}. In +Guile, true and false are represented using boolean constants, and +@samp{auto} is represented using @code{#:auto}. + +@item PARAM_UINTEGER +The value is an unsigned integer. The value of 0 should be +interpreted to mean ``unlimited''. + +@item PARAM_ZINTEGER +The value is an integer. + +@item PARAM_ZUINTEGER +The value is an unsigned integer. + +@item PARAM_ZUINTEGER_UNLIMITED +The value is an integer in the range @samp{[0, INT_MAX]}. +A value of @samp{-1} means ``unlimited'', and other negative +numbers are not allowed. + +@item PARAM_STRING +The value is a string. When the user modifies the string, any escape +sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are +translated into corresponding characters and encoded into the current +host charset. + +@item PARAM_STRING_NOESCAPE +The value is a string. When the user modifies the string, escapes are +passed through untranslated. + +@item PARAM_OPTIONAL_FILENAME +The value is a either a filename (a string), or @code{#f}. + +@item PARAM_FILENAME +The value is a filename. This is just like +@code{PARAM_STRING_NOESCAPE}, but uses file names for completion. + +@item PARAM_ENUM +The value is a string, which must be one of a collection of string +constants provided when the parameter is created. +@end vtable + +@node Progspaces In Guile +@subsubsection Program Spaces In Guile + +@cindex progspaces in guile +@tindex +A program space, or @dfn{progspace}, represents a symbolic view +of an address space. +It consists of all of the objfiles of the program. +@xref{Objfiles In Guile}. +@xref{Inferiors Connections and Programs, program spaces}, for more details +about program spaces. + +Each progspace is represented by an instance of the @code{} +smob. @xref{GDB Scheme Data Types}. + +The following progspace-related functions are available in the +@code{(gdb)} module: + +@deffn {Scheme Procedure} progspace? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} progspace-valid? progspace +Return @code{#t} if @var{progspace} is valid, @code{#f} if not. +A @code{} object can become invalid +if the program it refers to is not loaded in @value{GDBN} any longer. +@end deffn + +@deffn {Scheme Procedure} current-progspace +This function returns the program space of the currently selected inferior. +There is always a current progspace, this never returns @code{#f}. +@xref{Inferiors Connections and Programs}. +@end deffn + +@deffn {Scheme Procedure} progspaces +Return a list of all the progspaces currently known to @value{GDBN}. +@end deffn + +@deffn {Scheme Procedure} progspace-filename progspace +Return the absolute file name of @var{progspace} as a string. +This is the name of the file passed as the argument to the @code{file} +or @code{symbol-file} commands. +If the program space does not have an associated file name, +then @code{#f} is returned. This occurs, for example, when @value{GDBN} +is started without a program to debug. + +A @code{gdb:invalid-object-error} exception is thrown if @var{progspace} +is invalid. +@end deffn + +@deffn {Scheme Procedure} progspace-objfiles progspace +Return the list of objfiles of @var{progspace}. +The order of objfiles in the result is arbitrary. +Each element is an object of type @code{}. +@xref{Objfiles In Guile}. + +A @code{gdb:invalid-object-error} exception is thrown if @var{progspace} +is invalid. +@end deffn + +@deffn {Scheme Procedure} progspace-pretty-printers progspace +Return the list of pretty-printers of @var{progspace}. +Each element is an object of type @code{}. +@xref{Guile Pretty Printing API}, for more information. +@end deffn + +@deffn {Scheme Procedure} set-progspace-pretty-printers! progspace printer-list +Set the list of registered @code{} objects for +@var{progspace} to @var{printer-list}. +@xref{Guile Pretty Printing API}, for more information. +@end deffn + @node Objfiles In Guile @subsubsection Objfiles In Guile @@ -1718,7 +2249,13 @@ if it is invalid at the time the procedure is called. @end deffn @deffn {Scheme Procedure} objfile-filename objfile -Return the file name of @var{objfile} as a string. +Return the file name of @var{objfile} as a string, +with symbolic links resolved. +@end deffn + +@deffn {Scheme Procedure} objfile-progspace objfile +Return the @code{} that this object file lives in. +@xref{Progspaces In Guile}, for more on progspaces. @end deffn @deffn {Scheme Procedure} objfile-pretty-printers objfile @@ -1855,6 +2392,9 @@ stack corruption. The frame unwinder did not find any saved PC, but we needed one to unwind further. +@item FRAME_UNWIND_MEMORY_ERROR +The frame unwinder caused an error while trying to access memory. + @item FRAME_UNWIND_FIRST_ERROR Any stop reason greater or equal to this value indicates some kind of error. This special value facilitates writing code that tests @@ -1899,6 +2439,11 @@ Return the frame's @code{} (symtab and line) object. @xref{Symbol Tables In Guile}. @end deffn +@deffn {Scheme Procedure} frame-read-register frame register +Return the value of @var{register} in @var{frame}. @var{register} +should be a string, like @samp{pc}. +@end deffn + @deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]} Return the value of @var{variable} in @var{frame}. If the optional argument @var{block} is provided, search for the variable from that @@ -2227,7 +2772,7 @@ This domain contains names of labels (for gotos). This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it contains everything minus functions and types. -@item SYMBOL_FUNCTION_DOMAIN +@item SYMBOL_FUNCTIONS_DOMAIN This domain contains all functions. @item SYMBOL_TYPES_DOMAIN @@ -2390,18 +2935,30 @@ object will be @code{#f} and 0 respectively. @tindex Breakpoints in Guile are represented by objects of type -@code{}. +@code{}. New breakpoints can be created with the +@code{make-breakpoint} Guile function, and then added to @value{GDBN} with the +@code{register-breakpoint!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the breakpoint to @value{GDBN} from @code{make-breakpoint}. + +Support is also provided to view and manipulate breakpoints created +outside of Guile. The following breakpoint-related procedures are provided by the @code{(gdb)} module: @c TODO: line length -@deffn {Scheme Procedure} create-breakpoint! location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]} -Create a new breakpoint according to @var{spec}, a string naming the +@deffn {Scheme Procedure} make-breakpoint location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]} +Create a new breakpoint at @var{location}, a string naming the location of the breakpoint, or an expression that defines a watchpoint. The contents can be any location recognized by the @code{break} command, or in the case of a watchpoint, by the @code{watch} command. +The breakpoint is initially marked as @samp{invalid}. +The breakpoint is not usable until it has been registered with @value{GDBN} +with @code{register-breakpoint!}, at which point it becomes @samp{valid}. +The result is the @code{} object representing the breakpoint. + The optional @var{type} denotes the breakpoint to create. This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}, and defaults to @code{BP_BREAKPOINT}. @@ -2412,7 +2969,7 @@ not provided, it is assumed to be a @code{WP_WRITE} class. The optional @var{internal} argument allows the breakpoint to become invisible to the user. The breakpoint will neither be reported when -created, nor will it be listed in the output from @code{info breakpoints} +registered, nor will it be listed in the output from @code{info breakpoints} (but will be listed with the @code{maint info breakpoints} command). If an internal flag is not provided, the breakpoint is visible (non-internal). @@ -2463,10 +3020,24 @@ Read/Write watchpoint. @end deffn -@deffn {Scheme Procedure} breakpoint-delete! breakpoint -Permanently delete @var{breakpoint}. This also invalidates the -Guile @var{breakpoint} object. Any further attempt to access the -object will throw an exception. +@deffn {Scheme Procedure} register-breakpoint! breakpoint +Add @var{breakpoint}, a @code{} object, to @value{GDBN}'s +list of breakpoints. The breakpoint must have been created with +@code{make-breakpoint}. One cannot register breakpoints that have been +created outside of Guile. Once a breakpoint is registered it becomes +@samp{valid}. +It is an error to register an already registered breakpoint. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} delete-breakpoint! breakpoint +Remove @var{breakpoint} from @value{GDBN}'s list of breakpoints. +This also invalidates the Guile @var{breakpoint} object. +Any further attempt to access the object will throw an exception. + +If @var{breakpoint} was created from Guile with @code{make-breakpoint} +it may be re-registered with @value{GDBN}, in which case the breakpoint +becomes valid again. @end deffn @deffn {Scheme Procedure} breakpoints @@ -2481,6 +3052,8 @@ and @code{#f} otherwise. @deffn {Scheme Procedure} breakpoint-valid? breakpoint Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise. +Breakpoints created with @code{make-breakpoint} are marked as invalid +until they are registered with @value{GDBN} with @code{register-breakpoint!}. A @code{} object can become invalid if the user deletes the breakpoint. In this case, the object still exists, but the underlying breakpoint does not. In the cases of @@ -2557,13 +3130,14 @@ At present, @var{count} must be zero. @end deffn @deffn {Scheme Procedure} breakpoint-thread breakpoint -Return the thread-id for thread-specific breakpoint @var{breakpoint}. -Return #f if @var{breakpoint} is not thread-specific. +Return the global-thread-id for thread-specific breakpoint +@var{breakpoint}. Return #f if @var{breakpoint} is not +thread-specific. @end deffn -@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f -Set the thread-id for @var{breakpoint} to @var{thread-id}. -If set to @code{#f}, the breakpoint is no longer thread-specific. +@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint global-thread-id|#f +Set the thread-id for @var{breakpoint} to @var{global-thread-id} If +set to @code{#f}, the breakpoint is no longer thread-specific. @end deffn @deffn {Scheme Procedure} breakpoint-task breakpoint @@ -2620,7 +3194,8 @@ Example @code{stop} implementation: (define (my-stop? bkpt) (let ((int-val (parse-and-eval "foo"))) (value=? int-val 3))) -(define bkpt (create-breakpoint! "main.c:42")) +(define bkpt (make-breakpoint "main.c:42")) +(register-breakpoint! bkpt) (set-breakpoint-stop! bkpt my-stop?) @end smallexample @end deffn @@ -2676,7 +3251,7 @@ most appropriate encoding when the string is printed. @deffn {Scheme Procedure} lazy-string-type lazy-string Return the type that is represented by @var{lazy-string}'s type. -For a lazy string this will always be a pointer type. To +For a lazy string this is a pointer or array type. To resolve this to the lazy string's character type, use @code{type-target-type}. @xref{Types In Guile}. @end deffn @@ -2954,11 +3529,13 @@ returns a port object. One can then read/write memory using that object. @deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]} Return a port object that can be used for reading and writing memory. The port will be open according to @var{mode}, which is the standard -mode argument to Guile port open routines, except that it is -restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For -compatibility @samp{"b"} (binary) may also be present, but we ignore -it: memory ports are binary only. The default is @samp{"r"}, -read-only. +mode argument to Guile port open routines, except that the @samp{"a"} +and @samp{"l"} modes are not supported. +@xref{File Ports,,, guile, GNU Guile Reference Manual}. +The @samp{"b"} (binary) character may be present, but is ignored: +memory ports are binary only. If @samp{"0"} is appended then +the port is marked as unbuffered. +The default is @samp{"r"}, read-only and buffered. The chunk of memory that can be accessed can be bounded. If both @var{start} and @var{size} are unspecified, all of memory can be