Next: Arithmetic In Guile, Previous: Guile Exception Handling, Up: Guile API [Contents][Index]
GDB provides values it obtains from the inferior program in
an object of type <gdb:value>. GDB uses this object
for its internal bookkeeping of the inferior’s values, and for
fetching values when necessary.
GDB does not memoize <gdb:value> objects.
make-value always returns a fresh object.
(gdb) guile (eq? (make-value 1) (make-value 1)) $1 = #f (gdb) guile (equal? (make-value 1) (make-value 1)) $1 = #t
A <gdb:value> that represents a function can be executed via
inferior function call with value-call.
Any arguments provided to the call must match the function’s prototype,
and must be provided in the order specified by that prototype.
For example, some-val is a <gdb:value> instance
representing a function that takes two integers as arguments. To
execute this function, call it like so:
(define result (value-call some-val 10 20))
Any values returned from a function call are <gdb:value> objects.
Note: Unlike Python scripting in GDB,
inferior values that are simple scalars cannot be used directly in
Scheme expressions that are valid for the value’s data type.
For example, (+ (parse-and-eval "int_variable") 2) does not work.
And inferior values that are structures or instances of some class cannot
be accessed using any special syntax, instead value-field must be used.
The following value-related procedures are provided by the
(gdb) module.
Return #t if object is a <gdb:value> object.
Otherwise return #f.
Many Scheme values can be converted directly to a <gdb:value>
with this procedure. If type is specified, the result is a value
of this type, and if value can’t be represented with this type
an exception is thrown. Otherwise the type of the result is determined from
value as described below.
See Architectures In Guile, for a list of the builtin types for an architecture.
Here’s how Scheme values are converted when type argument to
make-value is not specified:
A Scheme boolean is converted the boolean type for the current language.
A Scheme integer is converted to the first of a C int,
unsigned int, long, unsigned long,
long long or unsigned long long type
for the current architecture that can represent the value.
If the Scheme integer cannot be represented as a target integer
an out-of-range exception is thrown.
A Scheme real is converted to the C double type for the
current architecture.
A Scheme string is converted to a string in the current target
language using the current target encoding.
Characters that cannot be represented in the current target encoding
are replaced with the corresponding escape sequence. This is Guile’s
SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE conversion strategy
(see Strings in GNU Guile Reference Manual).
Passing type is not supported in this case,
if it is provided a wrong-type-arg exception is thrown.
<gdb:lazy-string>If value is a <gdb:lazy-string> object (see Lazy Strings In Guile), then the lazy-string->value procedure is called, and
its result is used.
Passing type is not supported in this case,
if it is provided a wrong-type-arg exception is thrown.
If value is a Scheme bytevector and type is provided,
value must be the same size, in bytes, of values of type type,
and the result is essentially created by using memcpy.
If value is a Scheme bytevector and type is not provided,
the result is an array of type uint8 of the same length.
Return #t if the compiler optimized out value,
thus it is not available for fetching from the inferior.
Otherwise return #f.
If value is addressable, returns a
<gdb:value> object representing the address.
Otherwise, #f is returned.
Return the type of value as a <gdb:type> object
(see Types In Guile).
Return the dynamic type of value. This uses C++ run-time type information (RTTI) to determine the dynamic type of the value. If the value is of class type, it will return the class in which the value is embedded, if any. If the value is of pointer or reference to a class type, it will compute the dynamic type of the referenced object, and return a pointer or reference to that type, respectively. In all other cases, it will return the value’s static type.
Note that this feature will only work when debugging a C++ program that includes RTTI for the object in question. Otherwise, it will just return the static type of the value as in ptype foo. See ptype.
Return a new instance of <gdb:value> that is the result of
casting value to the type described by type, which must
be a <gdb:type> object. If the cast cannot be performed for some
reason, this method throws an exception.
Like value-cast, but works as if the C++ dynamic_cast
operator were used. Consult a C++ reference for details.
Like value-cast, but works as if the C++ reinterpret_cast
operator were used. Consult a C++ reference for details.
For pointer data types, this method returns a new <gdb:value> object
whose contents is the object pointed to by value. For example, if
foo is a C pointer to an int, declared in your C program as
int *foo;
then you can use the corresponding <gdb:value> to access what
foo points to like this:
(define bar (value-dereference foo))
The result bar will be a <gdb:value> object holding the
value pointed to by foo.
A similar function value-referenced-value exists which also
returns <gdb:value> objects corresonding to the values pointed to
by pointer values (and additionally, values referenced by reference
values). However, the behavior of value-dereference
differs from value-referenced-value by the fact that the
behavior of value-dereference is identical to applying the C
unary operator * on a given value. For example, consider a
reference to a pointer ptrref, declared in your C++ program
as
typedef int *intptr; ... int val = 10; intptr ptr = &val; intptr &ptrref = ptr;
Though ptrref is a reference value, one can apply the method
value-dereference to the <gdb:value> object corresponding
to it and obtain a <gdb:value> which is identical to that
corresponding to val. However, if you apply the method
value-referenced-value, the result would be a <gdb:value>
object identical to that corresponding to ptr.
(define scm-ptrref (parse-and-eval "ptrref")) (define scm-val (value-dereference scm-ptrref)) (define scm-ptr (value-referenced-value scm-ptrref))
The <gdb:value> object scm-val is identical to that
corresponding to val, and scm-ptr is identical to that
corresponding to ptr. In general, value-dereference can
be applied whenever the C unary operator * can be applied
to the corresponding C value. For those cases where applying both
value-dereference and value-referenced-value is allowed,
the results obtained need not be identical (as we have seen in the above
example). The results are however identical when applied on
<gdb:value> objects corresponding to pointers (<gdb:value>
objects with type code TYPE_CODE_PTR) in a C/C++ program.
For pointer or reference data types, this method returns a new
<gdb:value> object corresponding to the value referenced by the
pointer/reference value. For pointer data types,
value-dereference and value-referenced-value produce
identical results. The difference between these methods is that
value-dereference cannot get the values referenced by reference
values. For example, consider a reference to an int, declared
in your C++ program as
int val = 10; int &ref = val;
then applying value-dereference to the <gdb:value> object
corresponding to ref will result in an error, while applying
value-referenced-value will result in a <gdb:value> object
identical to that corresponding to val.
(define scm-ref (parse-and-eval "ref")) (define err-ref (value-dereference scm-ref)) ;; error (define scm-val (value-referenced-value scm-ref)) ;; ok
The <gdb:value> object scm-val is identical to that
corresponding to val.
Return field field-name from <gdb:value> object value.
Return the value of array value at index index.
The value argument must be a subscriptable <gdb:value> object.
Perform an inferior function call, taking value as a pointer to the function to call. Each element of list arg-list must be a <gdb:value> object or an object that can be converted to a value. The result is the value returned by the function.
Return the Scheme boolean representing <gdb:value> value.
The value must be “integer like”. Pointers are ok.
Return the Scheme integer representing <gdb:value> value.
The value must be “integer like”. Pointers are ok.
Return the Scheme real number representing <gdb:value> value.
The value must be a number.
Return a Scheme bytevector with the raw contents of <gdb:value>
value. No transformation, endian or otherwise, is performed.
If value> represents a string, then this method converts the contents to a Guile string. Otherwise, this method will throw an exception.
Values are interpreted as strings according to the rules of the current language. If the optional length argument is given, the string will be converted to that length, and will include any embedded zeroes that the string may contain. Otherwise, for languages where the string is zero-terminated, the entire string will be converted.
For example, in C-like languages, a value is a string if it is a pointer
to or an array of characters or ints of type wchar_t, char16_t,
or char32_t.
If the optional encoding argument is given, it must be a string
naming the encoding of the string in the <gdb:value>, such as
"ascii", "iso-8859-6" or "utf-8". It accepts
the same encodings as the corresponding argument to Guile’s
scm_from_stringn function, and the Guile codec machinery will be used
to convert the string. If encoding is not given, or if
encoding is the empty string, then either the target-charset
(see Character Sets) will be used, or a language-specific encoding
will be used, if the current language is able to supply one.
The optional errors argument is one of #f, error or
substitute. error and substitute must be symbols.
If errors is not specified, or if its value is #f, then the
default conversion strategy is used, which is set with the Scheme function
set-port-conversion-strategy!.
If the value is 'error then an exception is thrown if there is any
conversion error. If the value is 'substitute then any conversion
error is replaced with question marks.
See Strings in GNU Guile Reference Manual.
If the optional length argument is given, the string will be
fetched and converted to the given length.
The length must be a Scheme integer and not a <gdb:value> integer.
If this <gdb:value> represents a string, then this method
converts value to a <gdb:lazy-string (see Lazy Strings In Guile). Otherwise, this method will throw an exception.
If the optional encoding argument is given, it must be a string
naming the encoding of the <gdb:lazy-string. Some examples are:
"ascii", "iso-8859-6" or "utf-8". If the
encoding argument is an encoding that GDB does not
recognize, GDB will raise an error.
When a lazy string is printed, the GDB encoding machinery is used to convert the string during printing. If the optional encoding argument is not provided, or is an empty string, GDB will automatically select the encoding most suitable for the string type. For further information on encoding in GDB please see Character Sets.
If the optional length argument is given, the string will be
fetched and encoded to the length of characters specified. If
the length argument is not provided, the string will be fetched
and encoded until a null of appropriate width is found.
The length must be a Scheme integer and not a <gdb:value> integer.
Return #t if value has not yet been fetched
from the inferior.
Otherwise return #f.
GDB does not fetch values until necessary, for efficiency.
For example:
(define myval (parse-and-eval "somevar"))
The value of somevar is not fetched at this time. It will be
fetched when the value is needed, or when the fetch-lazy
procedure is invoked.
Return a <gdb:value> that will be lazily fetched from the
target. The object of type <gdb:type> whose value to fetch is
specified by its type and its target memory address, which
is a Scheme integer.
If value is a lazy value ((value-lazy? value) is #t),
then the value is fetched from the inferior.
Any errors that occur in the process will produce a Guile exception.
If value is not a lazy value, this method has no effect.
The result of this function is unspecified.
Return the string representation (print form) of <gdb:value>
value.
Next: Arithmetic In Guile, Previous: Guile Exception Handling, Up: Guile API [Contents][Index]