From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25435 invoked by alias); 4 Apr 2008 09:26:15 -0000 Received: (qmail 25423 invoked by uid 22791); 4 Apr 2008 09:26:14 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 04 Apr 2008 09:25:57 +0000 Received: (qmail 10261 invoked from network); 4 Apr 2008 09:25:54 -0000 Received: from unknown (HELO localhost) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 4 Apr 2008 09:25:54 -0000 From: Vladimir Prus Date: Fri, 04 Apr 2008 09:32:00 -0000 Subject: [RFA] Document fixed/floating variable objects and thread-id. To: gdb-patches@sources.redhat.com X-TUID: 6cb020808425c65a X-Length: 3848 X-UID: 155 MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200804041320.00361.vladimir@codesourcery.com> 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 X-SW-Source: 2008-04/txt/msg00089.txt.bz2 This patch adds some more docs about variable objects. Even though floating variable objects have know bugs, I think their intended behaviour is sufficiently clear right now to document. - Volodya * gdb/doc/gdb.texinfo (gdb/mi Variable object): Document fixed and floating variable objects, and clarify that a variable object can also be found to a thread. Update -var-create example. --- gdb/doc/gdb.texinfo | 32 +++++++++++++++++++++++++------- 1 files changed, 25 insertions(+), 7 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index c73a6d9..4c0b3b9 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -19900,7 +19900,23 @@ relatively slow for embedded targets, so a frontend might want to disable automatic update for the variables that are either not visible on the screen, or ``closed''. This is possible using so called ``frozen variable objects''. Such variable objects are never -implicitly updated. +implicitly updated. + +Variable objects can be either ``fixed'' or ``floating''. For the +fixed variable object, the expression is parsed when the variable +object is created, including associating indentifiers to specific +variables. The meaning of expression never changes. A floating +variable object has its expression reparsed each time the variable +object is updated. In particular, the meaning of identifiers can +change every time. + +If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +frame the local variable belongs to. For multithreaded programs, the +variable object also becomes bound to the thread. When such variable +object is updated, @value{GDBN} makes sure that the thread/frame +combination the variable object is bound to still exists, and +re-evaluates the variable object in that thread/frame. The following is the complete set of @sc{gdb/mi} operations defined to access this functionality: @@ -19951,7 +19967,7 @@ how it can be used. @smallexample -var-create @{@var{name} | "-"@} - @{@var{frame-addr} | "*"@} @var{expression} + @{@var{frame-addr} | "*" | "@"@} @var{expression} @end smallexample This operation creates a variable object, which allows the monitoring of @@ -19961,12 +19977,13 @@ register. The @var{name} parameter is the string by which the object can be referenced. It must be unique. If @samp{-} is specified, the varobj system will generate a string ``varNNNNNN'' automatically. It will be -unique provided that one does not specify @var{name} on that format. -The command fails if a duplicate name is found. +unique provided that one does not explicitly specifies @var{name} of +that format. The command fails if a duplicate name is found. The frame under which the expression should be evaluated can be specified by @var{frame-addr}. A @samp{*} indicates that the current -frame should be used. +frame should be used. A @samp{*} indicates that a floating variable +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: @@ -19986,10 +20003,11 @@ begin with a @samp{*}), or one of the following: This operation returns the name, number of children and the type of the object created. Type is returned as a string as the ones generated by -the @value{GDBN} CLI: +the @value{GDBN} CLI. If a fixed variable object is bound to a +specific thread, the thread is is also printed: @smallexample - name="@var{name}",numchild="N",type="@var{type}" + name="@var{name}",numchild="N",type="@var{type}",thread-id="M" @end smallexample -- 1.5.3.5