From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30830 invoked by alias); 14 Feb 2014 08:46:55 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 30774 invoked by uid 89); 14 Feb 2014 08:46:54 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.6 required=5.0 tests=AWL,BAYES_00 autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 14 Feb 2014 08:46:53 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1WEEQ6-0006mT-4G from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Fri, 14 Feb 2014 00:46:50 -0800 Received: from SVR-ORW-FEM-04.mgc.mentorg.com ([147.34.97.41]) by svr-orw-fem-01.mgc.mentorg.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.4675); Fri, 14 Feb 2014 00:46:49 -0800 Received: from qiyao.dyndns.org.dyndns.org (147.34.91.1) by svr-orw-fem-04.mgc.mentorg.com (147.34.97.41) with Microsoft SMTP Server id 14.2.247.3; Fri, 14 Feb 2014 00:46:49 -0800 From: Yao Qi To: Subject: [PATCH 12/12] NEWS and Doc on --available-children-only Date: Fri, 14 Feb 2014 08:46:00 -0000 Message-ID: <1392367471-13527-13-git-send-email-yao@codesourcery.com> In-Reply-To: <1392367471-13527-1-git-send-email-yao@codesourcery.com> References: <1392367471-13527-1-git-send-email-yao@codesourcery.com> MIME-Version: 1.0 Content-Type: text/plain X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00498.txt.bz2 gdb/doc: 2014-02-14 Pedro Alves Yao Qi * 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-14 Yao Qi * NEWS: Mention new option "--available-children-only". --- gdb/NEWS | 7 +++++ gdb/doc/gdb.texinfo | 62 +++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 57 insertions(+), 12 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index 7fc3669..d77f75f 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 available + children 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..0c9bfd9 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,11 @@ 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 only +available or collected children of the varobj are considered. 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 @@ -32556,8 +32561,9 @@ 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. +reliable for a dynamic varobj or for a non-dynamic varobj if the +@samp{--available-children-only} option was specified. Instead, you +must examine the @samp{has_more} attribute. @item value The varobj's scalar value. For a varobj whose type is some sort of @@ -32576,8 +32582,11 @@ If a variable object is bound to a specific thread, then this is the 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. +For a dynamic varobj, or for a non-dynamic varobj when the +@samp{--available-children-only} option is specified, this indicates +whether there appear to be more children that haven't been listed yet, +which can be listed with a following @code{-var-list-children} +command. 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 +32672,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 +32681,19 @@ Returns the number of children of a variable object @var{name}: numchild=@var{n} @end smallexample -Note that this number is not completely reliable for a dynamic varobj. -It will return the current number of children, but more children may -be available. +If the @samp{--available-children-only} option is specified, then only +available or collected children of the varobj are considered. + +Note that this number is not completely reliable for a dynamic varobj +or for a non-dynamic varobj that is listing only available or +collected children. It will return the current number of children, +but more children may be available. +If for a given varobj, the presence of the +@samp{--available-children-only} option changes between invocations of +the @code{-var-create}, @code{-var-list-children} or +@code{-var-info-num-children} commands, the list of children is +reinitialized. @subheading The @code{-var-list-children} Command @findex -var-list-children @@ -32683,7 +32701,9 @@ 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 +32732,15 @@ 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 only +available or collected children of the varobj are considered. + +If for a given varobj, the presence of the +@samp{--available-children-only} option changes between invocations of +the @code{-var-create}, @code{-var-list-children} or +@code{-var-info-num-children} commands, the list of children is +reinitialized. + For each child the following results are returned: @table @var @@ -33021,8 +33050,12 @@ If the varobj's type changed, then this field will be present and will 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. +For a dynamic varobj, or non-dynamic varobj that had been created as +consequence of the @samp{--available-children-only} option to the +@code{-var-create}, @code{-var-list-children} or +@code{-var-info-num-children} commands, if the number of children +changed, or if the type changed, this will be the new number of +children. 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 +35329,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