-@c Copyright (C) 2008-2014 Free Software Foundation, Inc.
+@c Copyright (C) 2008-2016 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
@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
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
@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,
@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
@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} 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