1 "{ Package: 'jv:libgdbs' }"

     2 

     3 GDBMICommand subclass:#GDBMI_var_update

     4 	instanceVariableNames:''

     5 	classVariableNames:''

     6 	poolDictionaries:''

     7 	category:'GDB-Core-Commands-MI'

     8 !

     9 

    10 !GDBMI_var_update class methodsFor:'documentation'!

    11 

    12 documentation

    13 "

    14 The `-var-update' Command

    15 -------------------------

    16 

    17 Synopsis

    18 ........

    19 

    20       -var-update [PRINT-VALUES] {NAME | '*'}

    21 

    22    Reevaluate the expressions corresponding to the variable object NAME

    23 and all its direct and indirect children, and return the list of

    24 variable objects whose values have changed; NAME must be a root

    25 variable object.  Here, 'changed' means that the result of

    26 `-var-evaluate-expression' before and after the `-var-update' is

    27 different.  If `*' is used as the variable object names, all existing

    28 variable objects are updated, except for frozen ones (*note

    29 -var-set-frozen::).  The option PRINT-VALUES determines whether both

    30 names and values, or just names are printed.  The possible values of

    31 this option are the same as for `-var-list-children' (*note

    32 -var-list-children::).  It is recommended to use the `--all-values'

    33 option, to reduce the number of MI commands needed on each program stop.

    34 

    35    With the `*' parameter, if a variable object is bound to a currently

    36 running thread, it will not be updated, without any diagnostic.

    37 

    38    If `-var-set-update-range' was previously used on a varobj, then

    39 only the selected range of children will be reported.

    40 

    41    `-var-update' reports all the changed varobjs in a tuple named

    42 `changelist'.

    43 

    44    Each item in the change list is itself a tuple holding:

    45 

    46 `name'

    47      The name of the varobj.

    48 

    49 `value'

    50      If values were requested for this update, then this field will be

    51      present and will hold the value of the varobj.

    52 

    53 `in_scope'

    54      This field is a string which may take one of three values:

    55 

    56     `'true''

    57           The variable object's current value is valid.

    58 

    59     `'false''

    60           The variable object does not currently hold a valid value but

    61           it may hold one in the future if its associated expression

    62           comes back into scope.

    63 

    64     `'invalid''

    65           The variable object no longer holds a valid value.  This can

    66           occur when the executable file being debugged has changed,

    67           either through recompilation or by using the {No value for

    68           `GDBN'} `file' command.  The front end should normally choose

    69           to delete these variable objects.

    70 

    71      In the future new values may be added to this list so the front

    72      should be prepared for this possibility.  *Note GDB/MI Development

    73      and Front Ends: GDB/MI Development and Front Ends.

    74 

    75 `type_changed'

    76      This is only present if the varobj is still valid.  If the type

    77      changed, then this will be the string `true'; otherwise it will be

    78      `false'.

    79 

    80      When a varobj's type changes, its children are also likely to have

    81      become incorrect.  Therefore, the varobj's children are

    82      automatically deleted when this attribute is `true'.  Also, the

    83      varobj's update range, when set using the `-var-set-update-range'

    84      command, is unset.

    85 

    86 `new_type'

    87      If the varobj's type changed, then this field will be present and

    88      will hold the new type.

    89 

    90 `new_num_children'

    91      For a dynamic varobj, if the number of children changed, or if the

    92      type changed, this will be the new number of children.

    93 

    94      The `numchild' field in other varobj responses is generally not

    95      valid for a dynamic varobj - it will show the number of children

    96      that {No value for `GDBN'} knows about, but because dynamic

    97      varobjs lazily instantiate their children, this will not reflect

    98      the number of children which may be available.

    99 

   100      The `new_num_children' attribute only reports changes to the

   101      number of children known by {No value for `GDBN'}.  This is the

   102      only way to detect whether an update has removed children (which

   103      necessarily can only happen at the end of the update range).

   104 

   105 `displayhint'

   106      The display hint, if any.

   107 

   108 `has_more'

   109      This is an integer value, which will be 1 if there are more

   110      children available outside the varobj's update range.

   111 

   112 `dynamic'

   113      This attribute will be present and have the value `1' if the

   114      varobj is a dynamic varobj.  If the varobj is not a dynamic varobj,

   115      then this attribute will not be present.

   116 

   117 `new_children'

   118      If new children were added to a dynamic varobj within the selected

   119      update range (as set by `-var-set-update-range'), then they will

   120      be listed in this attribute.

   121 

   122 Example

   123 .......

   124 

   125      (gdb)

   126      -var-assign var1 3

   127      ^done,value='3'

   128      (gdb)

   129      -var-update --all-values var1

   130      ^done,changelist=[{name='var1',value='3',in_scope='true',

   131      type_changed='false'}]

   132      (gdb)

   133 

   134 

   135 "

   136 ! !

   137 

   138 !GDBMI_var_update methodsFor:'accessing'!

   139 

   140 operation

   141 	^ 'var-update'

   142 ! !

   143