From 06fc020f10ddb58fc73d9d2a20cde274f14111e4 Mon Sep 17 00:00:00 2001 From: Siva Chandra Reddy Date: Wed, 11 Apr 2012 05:50:44 +0000 Subject: 2012-04-02 Siva Chandra Reddy New command 'explore' which helps explore values and types in scope. * NEWS: Add an entry about the new 'explore' command. * data-directory/Makefile.in: Add gdb/command/explore.py * python/lib/gdb/command/explore.py: Implemention of the 'explore' command using the GDB Python API. * doc/gdb.texinfo (Examining Data): Document the 'explore' command. * testsuite/gdb.python/Makefile.in: Add py-explore to EXECUTABLES. * testsuite/gdb.python/py-explore.c: C program used for testing the new 'explore' command on C constructs. * testsuite/gdb.python/py-explore.cc: C++ program used for testing the new 'explore' command on C++ constructs. * testsuite/gdb-python/py-explore.exp: Tests for the new 'explore' command on C constructs. * testsuite/gdb-python/py-explore-cc.exp: Tests for the new 'explore' command on C++ constructs. --- gdb/doc/ChangeLog | 4 ++ gdb/doc/gdb.texinfo | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) (limited to 'gdb/doc') diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 885b46b..ecb3409 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +2012-04-11 Siva Chandra Reddy + + * gdb.texinfo (Examining Data): Document the 'explore' command. + 2012-03-28 Joel Brobecker * gdb.texinfo (GDB/MI Variable Objects): Document what happens diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 8002429..37ffbb1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -7198,6 +7198,153 @@ fields of a struct or a class are declared, use the @code{ptype @var{exp}} command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}. +@cindex exploring hierarchical data structures +@kindex explore +Another way of examining values of expressions and type information is +through the Python extension command @code{explore} (available only if +the @value{GDBN} build is configured with @code{--with-python}). It +offers an interactive way to start at the highest level (or, the most +abstract level) of the data type of an expression (or, the data type +itself) and explore all the way down to leaf scalar values/fields +embedded in the higher level data types. + +@table @code +@item explore @var{arg} +@var{arg} is either an expression (in the source language), or a type +visible in the current context of the program being debugged. +@end table + +The working of the @code{explore} command can be illustrated with an +example. If a data type @code{struct ComplexStruct} is defined in your +C program as + +@smallexample +struct SimpleStruct +@{ + int i; + double d; +@}; + +struct ComplexStruct +@{ + struct SimpleStruct *ss_p; + int arr[10]; +@}; +@end smallexample + +@noindent +followed by variable declarations as + +@smallexample +struct SimpleStruct ss = @{ 10, 1.11 @}; +struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @}; +@end smallexample + +@noindent +then, the value of the variable @code{cs} can be explored using the +@code{explore} command as follows. + +@smallexample +(gdb) explore cs +The value of `cs' is a struct/class of type `struct ComplexStruct' with +the following fields: + + ss_p = + arr = + +Enter the field number of choice: +@end smallexample + +@noindent +Since the fields of @code{cs} are not scalar values, you are being +prompted to chose the field you want to explore. Let's say you choose +the field @code{ss_p} by entering @code{0}. Then, since this field is a +pointer, you will be asked if it is pointing to a single value. From +the declaration of @code{cs} above, it is indeed pointing to a single +value, hence you enter @code{y}. If you enter @code{n}, then you will +be asked if it were pointing to an array of values, in which case this +field will be explored as if it were an array. + +@smallexample +`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' +Continue exploring it as a pointer to a single value [y/n]: y +The value of `*(cs.ss_p)' is a struct/class of type `struct +SimpleStruct' with the following fields: + + i = 10 .. (Value of type `int') + d = 1.1100000000000001 .. (Value of type `double') + +Press enter to return to parent value: +@end smallexample + +@noindent +If the field @code{arr} of @code{cs} was chosen for exploration by +entering @code{1} earlier, then since it is as array, you will be +prompted to enter the index of the element in the array that you want +to explore. + +@smallexample +`cs.arr' is an array of `int'. +Enter the index of the element you want to explore in `cs.arr': 5 + +`(cs.arr)[5]' is a scalar value of type `int'. + +(cs.arr)[5] = 4 + +Press enter to return to parent value: +@end smallexample + +In general, at any stage of exploration, you can go deeper towards the +leaf values by responding to the prompts appropriately, or hit the +return key to return to the enclosing data structure (the @i{higher} +level data structure). + +Similar to exploring values, you can use the @code{explore} command to +explore types. Instead of specifying a value (which is typically a +variable name or an expression valid in the current context of the +program being debugged), you specify a type name. If you consider the +same example as above, your can explore the type +@code{struct ComplexStruct} by passing the argument +@code{struct ComplexStruct} to the @code{explore} command. + +@smallexample +(gdb) explore struct ComplexStruct +@end smallexample + +@noindent +By responding to the prompts appropriately in the subsequent interactive +session, you can explore the type @code{struct ComplexStruct} in a +manner similar to how the value @code{cs} was explored in the above +example. + +The @code{explore} command also has two sub-commands, +@code{explore value} and @code{explore type}. The former sub-command is +a way to explicitly specify that value exploration of the argument is +being invoked, while the latter is a way to explicitly specify that type +exploration of the argument is being invoked. + +@table @code +@item explore value @var{expr} +@cindex explore value +This sub-command of @code{explore} explores the value of the +expression @var{expr} (if @var{expr} is an expression valid in the +current context of the program being debugged). The behavior of this +command is identical to that of the behavior of the @code{explore} +command being passed the argument @var{expr}. + +@item explore type @var{arg} +@cindex explore type +This sub-command of @code{explore} explores the type of @var{arg} (if +@var{arg} is a type visible in the current context of program being +debugged), or the type of the value/expression @var{arg} (if @var{arg} +is an expression valid in the current context of the program being +debugged). If @var{arg} is a type, then the behavior of this command is +identical to that of the @code{explore} command being passed the +argument @var{arg}. If @var{arg} is an expression, then the behavior of +this command will be identical to that of the @code{explore} command +being passed the type of @var{arg} as the argument. +@end table + @menu * Expressions:: Expressions * Ambiguous Expressions:: Ambiguous Expressions -- cgit v1.1