-@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
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,
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
@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
@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