This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 12/12] NEWS and Doc on --available-children-only
- From: Yao Qi <yao at codesourcery dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: <gdb-patches at sourceware dot org>
- Date: Tue, 18 Feb 2014 15:12:43 +0800
- Subject: Re: [PATCH 12/12] NEWS and Doc on --available-children-only
- Authentication-results: sourceware.org; auth=none
- References: <1392367471-13527-1-git-send-email-yao at codesourcery dot com> <1392367471-13527-13-git-send-email-yao at codesourcery dot com> <83ha82c9rf dot fsf at gnu dot org> <5301D9F4 dot 5010306 at codesourcery dot com> <83zjlp93vz dot fsf at gnu dot org> <5302BE78 dot 10400 at codesourcery dot com> <83ppml6m4r dot fsf at gnu dot org>
On 02/18/2014 01:11 PM, Eli Zaretskii wrote:
> OK, thanks. I think I understand. I suggest, instead of this:
>
> If the @samp{--available-children-only} option is specified, then only
> value available or collected children of the varobj are considered.
>
> to say this:
>
> If the @samp{--available-children-only} option is specified, then
> @value(GDBN) considers only those children of the varobj whose
> values were collected.
>
> And in general, use "collected values" and "children whose values were
> collected" or "children with collected values" in other places.
>
> Does this correctly capture your intent?
Yes, that is good to me. Here is the updated one.
--
Yao (éå)
gdb/doc:
2014-02-18 Pedro Alves <pedro@codesourcery.com>
Yao Qi <yao@codesourcery.com>
* gdb.texinfo (GDB/MI Variable Objects): Update doc of MI
commands "-var-create", "-var-info-num-children" and
"-var-list-children".
(GDB/MI Support Commands): Document the new
"available-children-only" entry in the output of the
"-list-features" command.
gdb:
2014-02-18 Yao Qi <yao@codesourcery.com>
* NEWS: Mention new option "--available-children-only".
---
gdb/NEWS | 7 +++++++
gdb/doc/gdb.texinfo | 51 +++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 52 insertions(+), 6 deletions(-)
diff --git a/gdb/NEWS b/gdb/NEWS
index 7fc3669..06d7634 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -90,6 +90,13 @@ PowerPC64 GNU/Linux little-endian powerpc64le-*-linux*
** The commands -break-passcount and -break-commands accept convenience
variable as breakpoint number.
+ ** The commands -var-create, -var-info-num-children and
+ -var-list-children now accept an option
+ "--available-children-only". When used, only the children with
+ collected values are displayed. Support for this feature can be
+ verified using the "-list-features" command, which should contain
+ "available-children-only".
+
*** Changes in GDB 7.7
* Improved support for process record-replay and reverse debugging on
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 035573e..87cb26f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -32504,7 +32504,7 @@ may work differently in future versions of @value{GDBN}.
@subsubheading Synopsis
@smallexample
- -var-create @{@var{name} | "-"@}
+ -var-create [--available-children-only] @{@var{name} | "-"@}
@{@var{frame-addr} | "*" | "@@"@} @var{expression}
@end smallexample
@@ -32526,6 +32526,13 @@ object must be created.
@var{expression} is any expression valid on the current language set (must not
begin with a @samp{*}), or one of the following:
+If the @samp{--available-children-only} option is specified, then
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
+This affects the @samp{numchild} and @samp{has_more} attributes in the
+output result.
+
@itemize @bullet
@item
@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
@@ -32557,7 +32564,8 @@ The name of the varobj.
@item numchild
The number of children of the varobj. This number is not necessarily
reliable for a dynamic varobj. Instead, you must examine the
-@samp{has_more} attribute.
+@samp{has_more} attribute. If the @samp{--available-children-only}
+option was specified, this number is not reliable for any varobj.
@item value
The varobj's scalar value. For a varobj whose type is some sort of
@@ -32577,7 +32585,9 @@ thread's identifier.
@item has_more
For a dynamic varobj, this indicates whether there appear to be any
-children available. For a non-dynamic varobj, this will be 0.
+children available. When the @samp{--available-children-only} option
+is specified, this indicates whether there appear to be more children
+that haven't been listed yet. For the other cases, this will be 0.
@item dynamic
This attribute will be present and have the value @samp{1} if the
@@ -32663,7 +32673,7 @@ Returns the format used to display the value of the object @var{name}.
@subsubheading Synopsis
@smallexample
- -var-info-num-children @var{name}
+ -var-info-num-children [--available-children-only] @var{name}
@end smallexample
Returns the number of children of a variable object @var{name}:
@@ -32672,10 +32682,21 @@ Returns the number of children of a variable object @var{name}:
numchild=@var{n}
@end smallexample
+If the @samp{--available-children-only} option is specified, then
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
Note that this number is not completely reliable for a dynamic varobj.
+When the @samp{--available-children-only} option is specified, this
+number is not reliable for any varobj.
It will return the current number of children, but more children may
be available.
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
@subheading The @code{-var-list-children} Command
@findex -var-list-children
@@ -32683,7 +32704,7 @@ be available.
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
+ -var-list-children [--available-children-only] [@var{print-values}] @var{name} [@var{from} @var{to}]
@end smallexample
@anchor{-var-list-children}
@@ -32712,6 +32733,16 @@ then the front end could call @code{-var-set-update-range} with a
different range to ensure that future updates are restricted to just
the visible items.
+If the @samp{--available-children-only} option is specified, then
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
+
For each child the following results are returned:
@table @var
@@ -33022,7 +33053,10 @@ hold the new type.
@item new_num_children
For a dynamic varobj, if the number of children changed, or if the
-type changed, this will be the new number of children.
+type changed, this will be the new number of children. Similarly
+for a non-dynamic varobj that was created as result of the
+@samp{--available-children-only} option to the @code{-var-create},
+@code{-var-list-children} or @code{-var-info-num-children} commands.
The @samp{numchild} field in other varobj responses is generally not
valid for a dynamic varobj -- it will show the number of children that
@@ -35296,6 +35330,11 @@ records, produced when trying to execute an undefined @sc{gdb/mi} command
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
+@item available-children-only
+Indicates that the @code{-var-create}, @code{-var-info-num-children}
+and @code{-var-list-children} commands support the
+@option{--available-children-only}.
+
@end ftable
@subheading The @code{-list-target-features} Command
--
1.7.7.6