X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fguile.texi;h=c0bff7972f7d3810bb6f9bd55ac8050ac80ce477;hb=65c574f6dd066a239a94c2df0e1e12d50eae06c9;hp=bd1040c9eee1696544123dbd4d5427b47f3b95c6;hpb=16f691fb2ebac790fccf04c29a7027cfab50589b;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index bd1040c9ee..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 @@ -312,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 @@ -725,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 @@ -1254,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. @@ -1318,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 @@ -1373,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 @@ -1456,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 @@ -1472,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, @@ -2130,7 +2155,7 @@ 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 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{} @@ -2153,7 +2178,7 @@ if the program it refers to is not loaded in @value{GDBN} any longer. @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 @@ -2224,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 @@ -2408,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 @@ -2736,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 @@ -3094,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 @@ -3214,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 @@ -3492,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