-@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
* 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
evaluate it, and return the result as a @code{<gdb:value>}.
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{<gdb:value>}.
@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
@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
@item <gdb:breakpoint>
@xref{Breakpoints In Guile}.
+@item <gdb:command>
+@xref{Commands In Guile}.
+
@item <gdb:exception>
@xref{Guile Exception Handling}.
@item <gdb:objfile>
@xref{Objfiles In Guile}.
+@item <gdb:parameter>
+@xref{Parameters In Guile}.
+
@item <gdb:pretty-printer>
@xref{Guile Pretty Printing API}.
value pointed to by @code{foo}.
A similar function @code{value-referenced-value} exists which also
-returns @code{<gdb:value>} objects corresonding to the values pointed to
+returns @code{<gdb:value>} 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
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.
@deffn {Scheme Procedure} field-bitpos field
Return the bit position of @code{<gdb:field>} @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
@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
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
@subsubsection Selecting Guile Pretty-Printers
@cindex selecting guile pretty-printers
-The Guile list @code{*pretty-printers*} contains a set of
-@code{<gdb:pretty-printer>} registered objects.
-Printers in this list are called @code{global}
-printers, they're available when debugging any inferior.
-In addition to this, each @code{<gdb:objfile>} 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{<gdb:pretty-printer-worker>}
+object or @code{#f}. Otherwise an exception is thrown.
@value{GDBN} first checks the result of @code{objfile-pretty-printers}
of each @code{<gdb:objfile>} in the current program space and iteratively
calls each enabled lookup function in the list for that @code{<gdb:objfile>}
until a non-@code{#f} object is returned.
-Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
-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,
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{<gdb:command>} 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{<gdb:command>} 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{<gdb:command>} 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{<gdb:command>} 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{<gdb:command>}
+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{<gdb:iterator>} 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{<gdb:parameter>} 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{<gdb:parameter>} 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{<gdb:parameter>} 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{<gdb:parameter>}
+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{<gdb:parameter>} 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{<gdb:parameter>} 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{<gdb:parameter>} 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{<gdb:parameter>}.
+@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
of an address space.
It consists of all of the objfiles of the program.
@xref{Objfiles In Guile}.
-@xref{Inferiors and Programs, program spaces}, for more details
+@xref{Inferiors Connections and Programs, program spaces}, for more details
about program spaces.
Each progspace is represented by an instance of the @code{<gdb:progspace>}
@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 and Programs}.
+@xref{Inferiors Connections and Programs}.
@end deffn
@deffn {Scheme Procedure} progspaces
@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{<gdb:progspace>} that this object file lives in.
+@xref{Progspaces In Guile}, for more on progspaces.
@end deffn
@deffn {Scheme Procedure} objfile-pretty-printers objfile
@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
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
@tindex <gdb:breakpoint>
Breakpoints in Guile are represented by objects of type
-@code{<gdb:breakpoint>}.
+@code{<gdb:breakpoint>}. 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{<gdb:breakpoint>} 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}.
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).
@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{<gdb:breakpoint>} 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
@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{<gdb:breakpoint>} 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
@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
(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
@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
@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
projects / deliverable / binutils-gdb.git / blobdiff