lldb/bindings/interface/SBValueDocstrings.i

   1 %feature("docstring",
   2 "Represents the value of a variable, a register, or an expression.
   3
   4 SBValue supports iteration through its child, which in turn is represented
   5 as an SBValue.  For example, we can get the general purpose registers of a
   6 frame as an SBValue, and iterate through all the registers,::
   7
   8     registerSet = frame.registers # Returns an SBValueList.
   9     for regs in registerSet:
  10         if 'general purpose registers' in regs.name.lower():
  11             GPRs = regs
  12             break
  13
  14     print('%s (number of children = %d):' % (GPRs.name, GPRs.num_children))
  15     for reg in GPRs:
  16         print('Name: ', reg.name, ' Value: ', reg.value)
  17
  18 produces the output: ::
  19
  20     General Purpose Registers (number of children = 21):
  21     Name:  rax  Value:  0x0000000100000c5c
  22     Name:  rbx  Value:  0x0000000000000000
  23     Name:  rcx  Value:  0x00007fff5fbffec0
  24     Name:  rdx  Value:  0x00007fff5fbffeb8
  25     Name:  rdi  Value:  0x0000000000000001
  26     Name:  rsi  Value:  0x00007fff5fbffea8
  27     Name:  rbp  Value:  0x00007fff5fbffe80
  28     Name:  rsp  Value:  0x00007fff5fbffe60
  29     Name:  r8  Value:  0x0000000008668682
  30     Name:  r9  Value:  0x0000000000000000
  31     Name:  r10  Value:  0x0000000000001200
  32     Name:  r11  Value:  0x0000000000000206
  33     Name:  r12  Value:  0x0000000000000000
  34     Name:  r13  Value:  0x0000000000000000
  35     Name:  r14  Value:  0x0000000000000000
  36     Name:  r15  Value:  0x0000000000000000
  37     Name:  rip  Value:  0x0000000100000dae
  38     Name:  rflags  Value:  0x0000000000000206
  39     Name:  cs  Value:  0x0000000000000027
  40     Name:  fs  Value:  0x0000000000000010
  41     Name:  gs  Value:  0x0000000000000048
  42
  43 See also linked_list_iter() for another perspective on how to iterate through an
  44 SBValue instance which interprets the value object as representing the head of a
  45 linked list."
  46 ) lldb::SBValue;
  47
  48 %feature("docstring", "
  49     Get a child value by index from a value.
  50
  51     Structs, unions, classes, arrays and pointers have child
  52     values that can be access by index.
  53
  54     Structs and unions access child members using a zero based index
  55     for each child member. For
  56
  57     Classes reserve the first indexes for base classes that have
  58     members (empty base classes are omitted), and all members of the
  59     current class will then follow the base classes.
  60
  61     Pointers differ depending on what they point to. If the pointer
  62     points to a simple type, the child at index zero
  63     is the only child value available, unless synthetic_allowed
  64     is true, in which case the pointer will be used as an array
  65     and can create 'synthetic' child values using positive or
  66     negative indexes. If the pointer points to an aggregate type
  67     (an array, class, union, struct), then the pointee is
  68     transparently skipped and any children are going to be the indexes
  69     of the child values within the aggregate type. For example if
  70     we have a 'Point' type and we have a SBValue that contains a
  71     pointer to a 'Point' type, then the child at index zero will be
  72     the 'x' member, and the child at index 1 will be the 'y' member
  73     (the child at index zero won't be a 'Point' instance).
  74
  75     If you actually need an SBValue that represents the type pointed
  76     to by a SBValue for which GetType().IsPointeeType() returns true,
  77     regardless of the pointee type, you can do that with the SBValue.Dereference
  78     method (or the equivalent deref property).
  79
  80     Arrays have a preset number of children that can be accessed by
  81     index and will returns invalid child values for indexes that are
  82     out of bounds unless the synthetic_allowed is true. In this
  83     case the array can create 'synthetic' child values for indexes
  84     that aren't in the array bounds using positive or negative
  85     indexes.
  86
  87     @param[in] idx
  88         The index of the child value to get
  89
  90     @param[in] use_dynamic
  91         An enumeration that specifies whether to get dynamic values,
  92         and also if the target can be run to figure out the dynamic
  93         type of the child value.
  94
  95     @param[in] synthetic_allowed
  96         If true, then allow child values to be created by index
  97         for pointers and arrays for indexes that normally wouldn't
  98         be allowed.
  99
 100     @return
 101         A new SBValue object that represents the child member value."
 102 ) lldb::SBValue::GetChildAtIndex;
 103
 104 %feature("docstring", "
 105     Returns the child member index.
 106
 107     Matches children of this object only and will match base classes and
 108     member names if this is a clang typed object.
 109
 110     @param[in] name
 111         The name of the child value to get
 112
 113     @return
 114         An index to the child member value."
 115 ) lldb::SBValue::GetIndexOfChildWithName;
 116
 117 %feature("docstring", "
 118     Returns the child member value.
 119
 120     Matches child members of this object and child members of any base
 121     classes.
 122
 123     @param[in] name
 124         The name of the child value to get
 125
 126     @param[in] use_dynamic
 127         An enumeration that specifies whether to get dynamic values,
 128         and also if the target can be run to figure out the dynamic
 129         type of the child value.
 130
 131     @return
 132         A new SBValue object that represents the child member value."
 133 ) lldb::SBValue::GetChildMemberWithName;
 134
 135 %feature("docstring", "Expands nested expressions like .a->b[0].c[1]->d."
 136 ) lldb::SBValue::GetValueForExpressionPath;
 137
 138 %feature("docstring", "
 139       Return the value as an address.  On failure, LLDB_INVALID_ADDRESS
 140       will be returned.  On architectures like AArch64, where the
 141       top (unaddressable) bits can be used for authentication,
 142       memory tagging, or top byte ignore,  this method will return
 143       the value with those top bits cleared.
 144
 145       GetValueAsUnsigned returns the actual value, with the
 146       authentication/Top Byte Ignore/Memory Tagging Extension bits.
 147
 148       Calling this on a random value which is not a pointer is
 149       incorrect.  Call GetType().IsPointerType() if in doubt.
 150
 151       An SB API program may want to show both the literal byte value
 152       and the address it refers to in memory.  These two SBValue
 153       methods allow SB API writers to behave appropriately for their
 154       interface."
 155 ) lldb::SBValue::GetValueAsAddress;
 156
 157
 158 %feature("doctstring", "
 159     Returns the number for children.
 160
 161     @param[in] max
 162         If max is less the lldb.UINT32_MAX, then the returned value is
 163         capped to max.
 164
 165     @return
 166         An integer value capped to the argument max."
 167 ) lldb::SBValue::GetNumChildren;
 168
 169 %feature("docstring", "
 170     Find and watch a variable.
 171     It returns an SBWatchpoint, which may be invalid."
 172 ) lldb::SBValue::Watch;
 173
 174 %feature("docstring", "
 175     Find and watch the location pointed to by a variable.
 176     It returns an SBWatchpoint, which may be invalid."
 177 ) lldb::SBValue::WatchPointee;
 178
 179 %feature("docstring", "
 180     Get an SBData wrapping what this SBValue points to.
 181
 182     This method will dereference the current SBValue, if its
 183     data type is a ``T\*`` or ``T[]``, and extract ``item_count`` elements
 184     of type ``T`` from it, copying their contents in an :py:class:`SBData`.
 185
 186     :param item_idx: The index of the first item to retrieve. For an array
 187         this is equivalent to array[item_idx], for a pointer
 188         to ``\*(pointer + item_idx)``. In either case, the measurement
 189         unit for item_idx is the ``sizeof(T)`` rather than the byte
 190     :param item_count: How many items should be copied into the output. By default
 191         only one item is copied, but more can be asked for.
 192     :return: The contents of the copied items on success. An empty :py:class:`SBData` otherwise.
 193     :rtype: SBData
 194     "
 195 ) lldb::SBValue::GetPointeeData;
 196
 197 %feature("docstring", "
 198     Get an SBData wrapping the contents of this SBValue.
 199
 200     This method will read the contents of this object in memory
 201     and copy them into an SBData for future use.
 202
 203     @return
 204         An SBData with the contents of this SBValue, on success.
 205         An empty SBData otherwise."
 206 ) lldb::SBValue::GetData;
 207
 208 %feature("docstring", "Returns an expression path for this value."
 209 ) lldb::SBValue::GetExpressionPath;