While you may already have guessed a lot about the format of
summary strings from the above example, a detailed description
of their format follows.
Summary strings can contain plain text, control characters and
special symbols that have access to information about
the current object and the overall program state.
Normal characters are any text that doesn't contain a '{',
'}', '$', or '\'
character.
Variable names are found in between a "${"
prefix, and end with a "}" suffix.
In other words, a variable looks like "${frame.pc}".
Basically, all the variables described in Frame and Thread Formatting
are accepted. Also acceptable are the control characters
and scoping features described in that page.
Additionally, ${var and ${*var
become acceptable symbols in this scenario.
The simplest thing you can do is grab a member variable
of a class or structure by typing its expression
path. In the previous example, the expression path
for the floating member is simply .floating.
Thus, to ask the summary string to display floating
you would type ${var.floating} (${var
is a placeholder token replaced with whatever variable
is being displayed).
If you have code like the following:
struct A {
int x;
int y;
};
struct B {
A x;
A y;
int z;
};
the expression path for the y
member of the x member of an object of
type B would be .x.y and you
would type ${var.x.y} to display it in a
summary string for type B.
As you could be using a summary string for both
displaying objects of type T or T*
(unless -p is used to prevent this), the
expression paths do not differentiate between .
and ->, and the above expression path .x.y
would be just as good if you were displaying a B*,
or even if the actual definition of B
were:
struct B {
A *x;
A y;
int z;
};
This is unlike the behaviour of frame variable
which, on the contrary, will enforce the distinction. As
hinted above, the rationale for this choice is that
waiving this distinction enables one to write a summary
string once for type T and use it for both
T and T* instances. As a
summary string is mostly about extracting nested
members' information, a pointer to an object is just as
good as the object itself for the purpose.
Of course, you can have multiple entries in one summary
string, as shown in the previous example.
As you can see, the last expression path also contains
a %u symbol which is nowhere to be found
in the actual member variable name. The symbol is
reminding of a printf() format symbol, and
in fact it has a similar effect. If you add a % sign
followed by any one format name or abbreviation from the
above table after an expression path, the resulting
object will be displyed using the chosen format (this is
applicable to non-aggregate types only, with a few
special exceptions discussed below).
There are two more special format symbols that you can
use only as part of a summary string: %V
and %@. The first one tells LLDB to ignore
summary strings for the type of the object referred by
the expression path and instead print the object's
value. The second is only applicable to Objective-C
classes, and tells LLDB to get the object's description
from the Objective-C runtime. By default, if no format
is provided, LLDB will try to get the object's summary,
and if empty the object's value. If neither can be
obtained, nothing will be displayed.
As previously said, pointers and values are treated the
same way when getting to their members in an expression
path. However, if your expression path leads to a
pointer, LLDB will not automatically dereference it. In
order to obtain The deferenced value for a pointer, your
expression path must start with ${*var
instead of ${var. Because there is no need
to dereference pointers along your way, the
dereferencing symbol only applies to the result of the
whole expression path traversing.
e.g.
(lldb) fr var -T c
(Couple) c = {
(SimpleWithPointers) sp = {
(int *) x = 0x00000001001000b0
(float *) y = 0x00000001001000c0
(char *) z = 0x00000001001000d0 "X"
}
(Simple *) s = 0x00000001001000e0
}
If one types the following commands:
(lldb) type summary add -f "int = ${*var.sp.x},
float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =
${*var.s}" Couple
(lldb) type summary add -c -p Simple
|
the output becomes:
(lldb) fr var c
(Couple) c = int = 9, float = 9.99, char = 88, Simple
= (x=9, y=9.99, z='X')
Option -c to type summary add
tells LLDB not to look for a summary string, but instead
to just print a listing of all the object's children on
one line, as shown in the summary for object Simple.
We are using the -p flag here to show that
aggregate types can be dereferenced as well as basic types.
The following command sequence would work just as well and
produce the same output:
(lldb) type summary add -f "int = ${*var.sp.x},
float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =
${var.s}" Couple
(lldb) type summary add -c Simple
|
Sometimes, a basic type's value actually represents
several different values packed together in a bitfield.
With the classical view, there is no way to look at
them. Hexadecimal display can help, but if the bits
actually span byte boundaries, the help is limited.
Binary view would show it all without ambiguity, but is
often too detailed and hard to read for real-life
scenarios. To cope with the issue, LLDB supports native
bitfield formatting in summary strings. If your
expression paths leads to a so-called scalar type
(the usual int, float, char, double, short, long, long
long, double, long double and unsigned variants), you
can ask LLDB to only grab some bits out of the value and
display them in any format you like. The syntax is
similar to that used for arrays, just you can also give
a pair of indices separated by a -.
e.g.
(lldb) fr var float_point
(float) float_point = -3.14159
|
(lldb) type summary add -f "Sign: ${var[31]%B}
Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"
float
|
(lldb) fr var float_point
(float) float_point = -3.14159 Sign: true Exponent:
0x00000080 Mantissa: 4788184
In this example, LLDB shows the internal
representation of a float variable by
extracting bitfields out of a float object.
As far as the syntax is concerned, it looks
much like the normal C array syntax, but also allows you
to specify 2 indices, separated by a - symbol (a range).
Ranges can be given either with the lower or the higher index
first, and range extremes are always included in the bits extracted.
LLDB also allows to use a similar syntax to display
array members inside a summary string. For instance, you
may want to display all arrays of a given type using a
more compact notation than the default, and then just
delve into individual array members that prove
interesting to your debugging task. You can tell
LLDB to format arrays in special ways, possibly
independent of the way the array members' datatype is formatted.
e.g.
(lldb) fr var sarray
(Simple [3]) sarray = {
[0] = {
x = 1
y = 2
z = '\x03'
}
[1] = {
x = 4
y = 5
z = '\x06'
}
[2] = {
x = 7
y = 8
z = '\t'
}
}
|
(lldb) type summary add -f "${var[].x}" "Simple
[3]"
|
(lldb) fr var sarray
(Simple [3]) sarray = [1,4,7]
The [] symbol amounts to: if var
is an array and I knows its size, apply this summary
string to every element of the array. Here, we are
asking LLDB to display .x for every
element of the array, and in fact this is what happens.
If you find some of those integers anomalous, you can
then inspect that one item in greater detail, without
the array format getting in the way:
(lldb) fr var sarray[1]
(Simple) sarray[1] = {
x = 4
y = 5
z = '\x06'
}
You can also ask LLDB to only print a subset of the
array range by using the same syntax used to extract bit
for bitfields:
|
(lldb) type summary add -f "${var[1-2].x}" "Simple
[3]"
|
(lldb) fr var sarray
(Simple [3]) sarray = [4,7]
The same logic works if you are printing a pointer
instead of an array, however in this latter case, the empty
square brackets operator []
cannot be used and you need to give exact range limits.
In general, LLDB needs the square brackets operator [] in
order to handle arrays and pointers correctly, and for pointers it also
needs a range. However, a few special cases are defined to make your life easier:
- you can print a 0-terminated string (C-string) using the %s format,
omitting square brackets, as in:
|
(lldb) type summary add -f "${var%s}" "char *"
|
This works for char* and char[] objects, and uses the
\0 terminator
when possible to terminate the string, instead of relying on array length.
- anyone of the array formats (
int8_t[],
float32{}, ...), and the y, Y
and a formats
work to print an array of a non-aggregate
type, even if square brackets are omitted.
|
(lldb) type summary add -f "${var%int32_t[]}" "int [10]"
|
This feature, however, is not enabled for pointers because there is no
way for LLDB to detect the end of the pointed data.
This also does not work for other formats (e.g. boolean), and you must
specify the square brackets operator to get the expected output.
As you noticed, in order to associate the custom
summary string to the array types, one must give the
array size as part of the typename. This can long become
tiresome when using arrays of different sizes, Simple
[3], Simple [9], Simple
[12], ...
If you use the -x option, type names are
treated as regular expressions instead of type names.
This would let you rephrase the above example
for arrays of type Simple [3] as:
|
(lldb) type summary add -f "${var[].x}"
-x "Simple \[[0-9]+\]"
|
(lldb) fr var sarray
(Simple [3]) sarray = [1,4,7]
The above scenario works for Simple [3]
as well as for any other array of Simple
objects.
While this feature is mostly useful for arrays, you
could also use regular expressions to catch other type
sets grouped by name. However, as regular expression
matching is slower than normal name matching, LLDB will
first try to match by name in any way it can, and only
when this fails, will it resort to regular expression
matching. Thus, if your type has a base class with a
cascading summary, this will be preferred over any
regular expression match for your type itself.
For a given datatype, there may be different meaningful summary
representations. However, currently, only one summary can be associated
to a given datatype. If you need to temporarily override the association
for a variable, without changing the summary string bound to the datatype,
you can use named summaries.
Named summaries work by attaching a name to a summary string when creating
it. Then, when there is a need to attach the summary string to a variable, the
frame variable command, supports a --summary option
that tells LLDB to use the named summary given instead of the default one.
|
(lldb) type summary add -f "x=${var.integer}" --name NamedSummary
|
(lldb) fr var one
(i_am_cool) one = int = 3, float = 3.14159, char = 69
(lldb) fr var one --summary NamedSummary
(i_am_cool) one = x=3
When defining a named summmary, binding it to one or more types becomes optional.
Even if you bind the named summary to a type, and later change the summary string
for that type, the named summary will not be changed by that. You can delete
named summaries by using the type summary delete command, as if the
summary name was the datatype that the summary is applied to
A summary attached to a variable using the --summary option,
has the same semantics that a custom format attached using the -f
option has: it stays attached till you attach a new one, or till you let
your program run again.
While the rules for finding an appropriate format for a
type are relatively simple (just go through typedef
hierarchies), summaries follow a more complicated
process in finding the right summary string for a
variable. Namely, what happens is:
- If there is a summary for the type of the variable,
use it
- If this object is a pointer, and there is a summary
for the pointee type that does not skip pointers, use
it
- If this object is a reference, and there is a
summary for the pointee type that does not skip
references, use it
- If this object is an Objective-C class with a parent
class, look at the parent class (and parent of parent,
...)
- If this object is a C++ class with base classes,
look at base classes (and bases of bases, ...)
- If this object is a C++ class with virtual base
classes, look at the virtual base classes (and bases
of bases, ...)
- If this object's type is a typedef, go through
typedef hierarchy (LLDB might not be able to do this if
the compiler has not emitted enough information. If the
required information to traverse typedef hierarchies is
missing, type cascading will not work. The
clang compiler,
part of the LLVM project, emits the correct debugging
information for LLDB to cascade)
- If everything has failed, repeat the above search,
looking for regular expressions instead of exact
matches
- There's no way to do multiple dereferencing, and you
need to be careful what the dereferencing operation is
binding to in complicated scenarios
- There is no way to call functions inside summary
strings, not even
const ones
type format add does not support the -x
option- Object location cannot be printed in the summary
string