23.2.2.3 Values From Inferior

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:

— Instance Variable of Value: address

If this object is addressable, this read-only attribute holds a gdb.Value object representing the address. Otherwise, this attribute holds None.

— Instance Variable of Value: is_optimized_out

This read-only boolean attribute is true if the compiler optimized out this value, thus it is not available for fetching from the inferior.

— Instance Variable of Value: type

The type of this gdb.Value. The value of this attribute is a gdb.Type object.

— Instance Variable of Value: dynamic_type

The dynamic type of this gdb.Value. This uses C++ run-time type information 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.

The following methods are provided:

— Method on Value: cast type

Return a new instance of gdb.Value that is the result of casting this instance 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.

— Method on Value: dereference

For pointer data types, this method returns a new gdb.Value object whose contents is the object pointed to by the pointer. 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:

               bar = foo.dereference ()

The result bar will be a gdb.Value object holding the value pointed to by foo.

— Method on Value: dynamic_cast type

Like Value.cast, but works as if the C++ dynamic_cast operator were used. Consult a C++ reference for details.

— Method on Value: reinterpret_cast type

Like Value.cast, but works as if the C++ reinterpret_cast operator were used. Consult a C++ reference for details.

— Method on Value: string [encoding] [errors] [length]

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's string.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 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 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.

— Method on Value: lazy_string [encoding] [length]

If this gdb.Value represents a string, then this method converts the contents to a gdb.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.