X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fguile.texi;h=c0bff7972f7d3810bb6f9bd55ac8050ac80ce477;hb=65c574f6dd066a239a94c2df0e1e12d50eae06c9;hp=70fbd16b5ec37b958d599f0f232d6686e37bba5a;hpb=e698b8c41cbb2648a11a2ae806922c44d1482aed;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index 70fbd16b5e..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 @@ -142,6 +142,7 @@ from the Guile interactive prompt. * 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 @@ -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 @@ -375,6 +380,9 @@ as a symbol. @item @xref{Objfiles In Guile}. +@item +@xref{Parameters In Guile}. + @item @xref{Guile Pretty Printing API}. @@ -721,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 @@ -1250,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. @@ -1314,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 @@ -1369,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 @@ -1452,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 @@ -1468,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, @@ -1946,6 +1975,177 @@ end 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 @@ -1955,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{} @@ -1978,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 @@ -2049,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 @@ -2233,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 @@ -2561,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 @@ -2724,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}. @@ -2746,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). @@ -2797,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 @@ -2815,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 @@ -2891,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 @@ -2954,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 @@ -3010,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 @@ -3288,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