Next: Types In Python, Previous: Exception Handling, Up: Python API
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.
Inferior values that are simple scalars can be used directly in
Python expressions that are valid for the value's data type. Here's
an example for an integer or floating-point value some_val
:
bar = some_val + 2
As result of this, bar
will also be a gdb.Value
object
whose values are of the same type as those of some_val
.
Inferior values that are structures or instances of some class can
be accessed using the Python dictionary syntax. For example, if
some_val
is a gdb.Value
instance holding a structure, you
can access its foo
element with:
bar = some_val['foo']
Again, bar
will also be a gdb.Value
object.
A gdb.Value
that represents a function can be executed via
inferior function 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:
result = some_val (10,20)
Any values returned from a function call will be stored as a
gdb.Value
.
The following attributes are provided:
If this object is addressable, this read-only attribute holds a
gdb.Value
object representing the address. Otherwise, this attribute holdsNone
.
This read-only boolean attribute is true if the compiler optimized out this value, thus it is not available for fetching from the inferior.
The type of this
gdb.Value
. The value of this attribute is agdb.Type
object (see Types In Python).
The dynamic type of this
gdb.Value
. This uses C++ run-time type information (RTTI) to determine the dynamic type of the value. If this value is of class type, it will return the class in which the value is embedded, if any. If this 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).
The value of this read-only boolean attribute is
True
if thisgdb.Value
has not yet been fetched from the inferior. gdb does not fetch values until necessary, for efficiency. For example:myval = gdb.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
method is invoked.
The following methods are provided:
Many Python values can be converted directly to a
gdb.Value
via this object initializer. Specifically:
- Python boolean
- A Python boolean is converted to the boolean type from the current language.
- Python integer
- A Python integer is converted to the C
long
type for the current architecture.- Python long
- A Python long is converted to the C
long long
type for the current architecture.- Python float
- A Python float is converted to the C
double
type for the current architecture.- Python string
- A Python string is converted to a target string, using the current target encoding.
gdb.Value
- If
val
is agdb.Value
, then a copy of the value is made.gdb.LazyString
- If
val
is agdb.LazyString
(see Lazy Strings In Python), then the lazy string'svalue
method is called, and its result is used.
Return a new instance of
gdb.Value
that is the result of casting this instance to the type described by type, which must be agdb.Type
object. If the cast cannot be performed for some reason, this method throws an exception.
For pointer data types, this method returns a new
gdb.Value
object whose contents is the object pointed to by the pointer. 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:bar = foo.dereference ()The result
bar
will be agdb.Value
object holding the value pointed to byfoo
.A similar function
Value.referenced_value
exists which also returnsgdb.Value
objects corresonding 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 thegdb.Value
object corresponding to it and obtain agdb.Value
which is identical to that corresponding toval
. However, if you apply the methodValue.referenced_value
, the result would be agdb.Value
object identical to that corresponding toptr
.py_ptrref = gdb.parse_and_eval ("ptrref") py_val = py_ptrref.dereference () py_ptr = py_ptrref.referenced_value ()The
gdb.Value
objectpy_val
is identical to that corresponding toval
, andpy_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 ongdb.Value
objects corresponding to pointers (gdb.Value
objects with type codeTYPE_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
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 thegdb.Value
object corresponding toref
will result in an error, while applyingValue.referenced_value
will result in agdb.Value
object identical to that corresponding toval
.py_ref = gdb.parse_and_eval ("ref") er_ref = py_ref.dereference () # Results in error py_val = py_ref.referenced_value () # Returns the referenced valueThe
gdb.Value
objectpy_val
is identical to that corresponding toval
.
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.
If this
gdb.Value
represents a string, then this method converts the contents to a Python string. Otherwise, this method will throw an exception.Strings are recognized in a language-specific way; whether a given
gdb.Value
represents a string is determined by the current language.For C-like languages, a value is a string if it is a pointer to or an array of characters or ints. The string is assumed to be terminated by a zero of the appropriate width. However if the optional length argument is given, the string will be converted to that given length, ignoring any embedded zeros that the string may contain.
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 Python'sstring.decode
method, and the Python codec machinery will be used to convert the string. If encoding is not given, or if encoding 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 the same as the corresponding argument to Python's
string.decode
method.If the optional length argument is given, the string will be fetched and converted to the given length.
If this
gdb.Value
represents a string, then this method converts the contents to agdb.LazyString
(see Lazy Strings In Python). 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.LazyString
. Some examples are: `ascii', `iso-8859-6' or `utf-8'. If the encoding argument is an encoding that gdb does 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.
If the
gdb.Value
object is currently a lazy value (gdb.Value.is_lazy
isTrue
), then the value is fetched from the inferior. Any errors that occur in the process will produce a Python exception.If the
gdb.Value
object is not a lazy value, this method has no effect.This method does not return a value.