Values From Inferior In Guile (Debugging with GDB)
Next: Arithmetic In Guile, Previous: Guile Exception Handling, Up: Guile API [Contents][Index]
23.4.3.5 Values From Inferior In Guile
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.
- Scheme Procedure
- value? object
- Return
#t
ifobject
is a<gdb:value>
object. Otherwise return#f
.
- Scheme Procedure: make-value value [#:type type]
Many Scheme values can be converted directly to a
<gdb:value>
with this procedure. Iftype
is specified, the result is a value of this type, and ifvalue
can’t be represented with this type an exception is thrown. Otherwise the type of the result is determined fromvalue
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 tomake-value
is not specified:- Scheme boolean
A Scheme boolean is converted the boolean type for the current language.
- Scheme integer
A Scheme integer is converted to the first of a C
int
,unsigned int
,long
,unsigned long
,long long
orunsigned 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.- Scheme real
A Scheme real is converted to the C
double
type for the current architecture.- Scheme string
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 awrong-type-arg
exception is thrown.<gdb:lazy-string>
If
value
is a<gdb:lazy-string>
object (see Lazy Strings In Guile), then thelazy-string->value
procedure is called, and its result is used.Passing
type
is not supported in this case, if it is provided awrong-type-arg
exception is thrown.- Scheme bytevector
If
value
is a Scheme bytevector andtype
is provided,value
must be the same size, in bytes, of values of typetype
, and the result is essentially created by usingmemcpy
.If
value
is a Scheme bytevector andtype
is not provided, the result is an array of typeuint8
of the same length.
- Scheme Procedure
- value-optimized-out? value
- Return
#t
if the compiler optimized outvalue
, thus it is not available for fetching from the inferior. Otherwise return#f
.
- Scheme Procedure
- value-address value
- If
value
is addressable, returns a<gdb:value>
object representing the address. Otherwise,#f
is returned.
- Scheme Procedure
- value-type value
- Return the type of
value
as a<gdb:type>
object (see Types In Guile).
- Scheme Procedure: value-dynamic-type value
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.
- Scheme Procedure
- value-cast value type
- Return a new instance of
<gdb:value>
that is the result of castingvalue
to the type described bytype
, which must be a<gdb:type>
object. If the cast cannot be performed for some reason, this method throws an exception.
- Scheme Procedure
- value-dynamic-cast value type
- Like
value-cast
, but works as if the C++dynamic_cast
operator were used. Consult a C++ reference for details.
- Scheme Procedure
- value-reinterpret-cast value type
- Like
value-cast
, but works as if the C++reinterpret_cast
operator were used. Consult a C++ reference for details.
- Scheme Procedure: value-dereference value
For pointer data types, this method returns a new
<gdb:value>
object whose contents is the object pointed to byvalue
. For example, iffoo
is a C pointer to anint
, declared in your C program asint *foo;
then you can use the corresponding
<gdb:value>
to access whatfoo
points to like this:(define bar (value-dereference foo))
The result
bar
will be a<gdb:value>
object holding the value pointed to byfoo
.A similar function
value-referenced-value
exists which also returns<gdb:value>
objects corresponding to the values pointed to by pointer values (and additionally, values referenced by reference values). However, the behavior ofvalue-dereference
differs fromvalue-referenced-value
by the fact that the behavior ofvalue-dereference
is identical to applying the C unary operator*
on a given value. For example, consider a reference to a pointerptrref
, declared in your C++ program astypedef int *intptr; ... int val = 10; intptr ptr = &val; intptr &ptrref = ptr;
Though
ptrref
is a reference value, one can apply the methodvalue-dereference
to the<gdb:value>
object corresponding to it and obtain a<gdb:value>
which is identical to that corresponding toval
. However, if you apply the methodvalue-referenced-value
, the result would be a<gdb:value>
object identical to that corresponding toptr
.(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>
objectscm-val
is identical to that corresponding toval
, andscm-ptr
is identical to that corresponding toptr
. 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 bothvalue-dereference
andvalue-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 codeTYPE_CODE_PTR
) in a C/C++ program.
- Scheme Procedure: value-referenced-value value
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
andvalue-referenced-value
produce identical results. The difference between these methods is thatvalue-dereference
cannot get the values referenced by reference values. For example, consider a reference to anint
, declared in your C++ program asint val = 10; int &ref = val;
then applying
value-dereference
to the<gdb:value>
object corresponding toref
will result in an error, while applyingvalue-referenced-value
will result in a<gdb:value>
object identical to that corresponding toval
.(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>
objectscm-val
is identical to that corresponding toval
.
- Scheme Procedure
- value-reference-value value
- Return a new
<gdb:value>
object which is a reference to the value encapsulated by<gdb:value>
objectvalue
.
- Scheme Procedure
- value-rvalue-reference-value value
- Return a new
<gdb:value>
object which is an rvalue reference to the value encapsulated by<gdb:value>
objectvalue
.
- Scheme Procedure
- value-const-value value
- Return a new
<gdb:value>
object which is a ‘const
’ version of<gdb:value>
objectvalue
.
- Scheme Procedure
- value-field value field-name
- Return field
field-name
from<gdb:value>
objectvalue
.
- Scheme Procedure
- value-subscript value index
- Return the value of array
value
at indexindex
. Thevalue
argument must be a subscriptable<gdb:value>
object.
- Scheme Procedure
- value-call value arg-list
- Perform an inferior function call, taking
value
as a pointer to the function to call. Each element of listarg-list
must be a object or an object that can be converted to a value. The result is the value returned by the function.
- Scheme Procedure
- value->bool value
- Return the Scheme boolean representing
<gdb:value>
value
. The value must be “integer like”. Pointers are ok.
- Scheme Procedure
- value->integer
- Return the Scheme integer representing
<gdb:value>
value
. The value must be “integer like”. Pointers are ok.
- Scheme Procedure
- value->real
- Return the Scheme real number representing
<gdb:value>
value
. The value must be a number.
- Scheme Procedure
- value->bytevector
- Return a Scheme bytevector with the raw contents of
<gdb:value>
value
. No transformation, endian or otherwise, is performed.
- Scheme Procedure: value->string value [#:encoding encoding] [#:errors errors] [#:length length]
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
, orchar32_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’sscm_from_stringn
function, and the Guile codec machinery will be used to convert the string. Ifencoding
is not given, or ifencoding
is the empty string, then either thetarget-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
orsubstitute
.error
andsubstitute
must be symbols. Iferrors
is not specified, or if its value is#f
, then the default conversion strategy is used, which is set with the Scheme functionset-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.
- Scheme Procedure: value->lazy-string value [#:encoding encoding] [#:length length]
If this
<gdb:value>
represents a string, then this method convertsvalue
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 theencoding
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 thelength
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.
- Scheme Procedure: value-lazy? value
Return
#t
ifvalue
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 thefetch-lazy
procedure is invoked.
- Scheme Procedure
- make-lazy-value type address
- 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 itstype
and its target memoryaddress
, which is a Scheme integer.
- Scheme Procedure: value-fetch-lazy! value
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.
- Scheme Procedure
- value-print value
- Return the string representation (print form) of
<gdb:value>
value
.
Next: Arithmetic In Guile, Previous: Guile Exception Handling, Up: Guile API [Contents][Index]