1 //===-- SWIG Interface for SBValue ------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 namespace lldb { 10 11 %feature("docstring", 12 "Represents the value of a variable, a register, or an expression. 13 14 SBValue supports iteration through its child, which in turn is represented 15 as an SBValue. For example, we can get the general purpose registers of a 16 frame as an SBValue, and iterate through all the registers, 17 18 registerSet = frame.registers # Returns an SBValueList. 19 for regs in registerSet: 20 if 'general purpose registers' in regs.name.lower(): 21 GPRs = regs 22 break 23 24 print('%s (number of children = %d):' % (GPRs.name, GPRs.num_children)) 25 for reg in GPRs: 26 print('Name: ', reg.name, ' Value: ', reg.value) 27 28 produces the output: 29 30 General Purpose Registers (number of children = 21): 31 Name: rax Value: 0x0000000100000c5c 32 Name: rbx Value: 0x0000000000000000 33 Name: rcx Value: 0x00007fff5fbffec0 34 Name: rdx Value: 0x00007fff5fbffeb8 35 Name: rdi Value: 0x0000000000000001 36 Name: rsi Value: 0x00007fff5fbffea8 37 Name: rbp Value: 0x00007fff5fbffe80 38 Name: rsp Value: 0x00007fff5fbffe60 39 Name: r8 Value: 0x0000000008668682 40 Name: r9 Value: 0x0000000000000000 41 Name: r10 Value: 0x0000000000001200 42 Name: r11 Value: 0x0000000000000206 43 Name: r12 Value: 0x0000000000000000 44 Name: r13 Value: 0x0000000000000000 45 Name: r14 Value: 0x0000000000000000 46 Name: r15 Value: 0x0000000000000000 47 Name: rip Value: 0x0000000100000dae 48 Name: rflags Value: 0x0000000000000206 49 Name: cs Value: 0x0000000000000027 50 Name: fs Value: 0x0000000000000010 51 Name: gs Value: 0x0000000000000048 52 53 See also linked_list_iter() for another perspective on how to iterate through an 54 SBValue instance which interprets the value object as representing the head of a 55 linked list." 56 ) SBValue; 57 class SBValue 58 { 59 public: 60 SBValue (); 61 62 SBValue (const SBValue &rhs); 63 64 ~SBValue (); 65 66 bool 67 IsValid(); 68 69 explicit operator bool() const; 70 71 void 72 Clear(); 73 74 SBError 75 GetError(); 76 77 lldb::user_id_t 78 GetID (); 79 80 const char * 81 GetName(); 82 83 const char * 84 GetTypeName (); 85 86 const char * 87 GetDisplayTypeName (); 88 89 size_t 90 GetByteSize (); 91 92 bool 93 IsInScope (); 94 95 lldb::Format 96 GetFormat (); 97 98 void 99 SetFormat (lldb::Format format); 100 101 const char * 102 GetValue (); 103 104 int64_t 105 GetValueAsSigned(SBError& error, int64_t fail_value=0); 106 107 uint64_t 108 GetValueAsUnsigned(SBError& error, uint64_t fail_value=0); 109 110 int64_t 111 GetValueAsSigned(int64_t fail_value=0); 112 113 uint64_t 114 GetValueAsUnsigned(uint64_t fail_value=0); 115 116 ValueType 117 GetValueType (); 118 119 bool 120 GetValueDidChange (); 121 122 const char * 123 GetSummary (); 124 125 const char * 126 GetSummary (lldb::SBStream& stream, 127 lldb::SBTypeSummaryOptions& options); 128 129 const char * 130 GetObjectDescription (); 131 132 lldb::SBValue 133 GetDynamicValue (lldb::DynamicValueType use_dynamic); 134 135 lldb::SBValue 136 GetStaticValue (); 137 138 lldb::SBValue 139 GetNonSyntheticValue (); 140 141 lldb::DynamicValueType 142 GetPreferDynamicValue (); 143 144 void 145 SetPreferDynamicValue (lldb::DynamicValueType use_dynamic); 146 147 bool 148 GetPreferSyntheticValue (); 149 150 void 151 SetPreferSyntheticValue (bool use_synthetic); 152 153 bool 154 IsDynamic(); 155 156 bool 157 IsSynthetic (); 158 159 bool 160 IsSyntheticChildrenGenerated (); 161 162 void 163 SetSyntheticChildrenGenerated (bool); 164 165 const char * 166 GetLocation (); 167 168 bool 169 SetValueFromCString (const char *value_str); 170 171 bool 172 SetValueFromCString (const char *value_str, lldb::SBError& error); 173 174 lldb::SBTypeFormat 175 GetTypeFormat (); 176 177 lldb::SBTypeSummary 178 GetTypeSummary (); 179 180 lldb::SBTypeFilter 181 GetTypeFilter (); 182 183 lldb::SBTypeSynthetic 184 GetTypeSynthetic (); 185 186 lldb::SBValue 187 GetChildAtIndex (uint32_t idx); 188 189 %feature("docstring", " 190 Get a child value by index from a value. 191 192 Structs, unions, classes, arrays and pointers have child 193 values that can be access by index. 194 195 Structs and unions access child members using a zero based index 196 for each child member. For 197 198 Classes reserve the first indexes for base classes that have 199 members (empty base classes are omitted), and all members of the 200 current class will then follow the base classes. 201 202 Pointers differ depending on what they point to. If the pointer 203 points to a simple type, the child at index zero 204 is the only child value available, unless synthetic_allowed 205 is true, in which case the pointer will be used as an array 206 and can create 'synthetic' child values using positive or 207 negative indexes. If the pointer points to an aggregate type 208 (an array, class, union, struct), then the pointee is 209 transparently skipped and any children are going to be the indexes 210 of the child values within the aggregate type. For example if 211 we have a 'Point' type and we have a SBValue that contains a 212 pointer to a 'Point' type, then the child at index zero will be 213 the 'x' member, and the child at index 1 will be the 'y' member 214 (the child at index zero won't be a 'Point' instance). 215 216 If you actually need an SBValue that represents the type pointed 217 to by a SBValue for which GetType().IsPointeeType() returns true, 218 regardless of the pointee type, you can do that with the SBValue.Dereference 219 method (or the equivalent deref property). 220 221 Arrays have a preset number of children that can be accessed by 222 index and will returns invalid child values for indexes that are 223 out of bounds unless the synthetic_allowed is true. In this 224 case the array can create 'synthetic' child values for indexes 225 that aren't in the array bounds using positive or negative 226 indexes. 227 228 @param[in] idx 229 The index of the child value to get 230 231 @param[in] use_dynamic 232 An enumeration that specifies whether to get dynamic values, 233 and also if the target can be run to figure out the dynamic 234 type of the child value. 235 236 @param[in] synthetic_allowed 237 If true, then allow child values to be created by index 238 for pointers and arrays for indexes that normally wouldn't 239 be allowed. 240 241 @return 242 A new SBValue object that represents the child member value.") GetChildAtIndex; 243 lldb::SBValue 244 GetChildAtIndex (uint32_t idx, 245 lldb::DynamicValueType use_dynamic, 246 bool can_create_synthetic); 247 248 lldb::SBValue 249 CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type); 250 251 lldb::SBValue 252 SBValue::Cast (lldb::SBType type); 253 254 lldb::SBValue 255 CreateValueFromExpression (const char *name, const char* expression); 256 257 lldb::SBValue 258 CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options); 259 260 lldb::SBValue 261 CreateValueFromAddress(const char* name, lldb::addr_t address, lldb::SBType type); 262 263 lldb::SBValue 264 CreateValueFromData (const char* name, 265 lldb::SBData data, 266 lldb::SBType type); 267 268 lldb::SBType 269 GetType(); 270 271 %feature("docstring", " 272 Returns the child member index. 273 274 Matches children of this object only and will match base classes and 275 member names if this is a clang typed object. 276 277 @param[in] name 278 The name of the child value to get 279 280 @return 281 An index to the child member value.") GetIndexOfChildWithName; 282 uint32_t 283 GetIndexOfChildWithName (const char *name); 284 285 lldb::SBValue 286 GetChildMemberWithName (const char *name); 287 288 %feature("docstring", " 289 Returns the child member value. 290 291 Matches child members of this object and child members of any base 292 classes. 293 294 @param[in] name 295 The name of the child value to get 296 297 @param[in] use_dynamic 298 An enumeration that specifies whether to get dynamic values, 299 and also if the target can be run to figure out the dynamic 300 type of the child value. 301 302 @return 303 A new SBValue object that represents the child member value.") GetChildMemberWithName; 304 lldb::SBValue 305 GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic); 306 307 %feature("docstring", "Expands nested expressions like .a->b[0].c[1]->d." 308 ) GetValueForExpressionPath; 309 lldb::SBValue 310 GetValueForExpressionPath(const char* expr_path); 311 312 lldb::SBDeclaration 313 GetDeclaration (); 314 315 bool 316 MightHaveChildren (); 317 318 bool 319 IsRuntimeSupportValue (); 320 321 uint32_t 322 GetNumChildren (); 323 324 %feature("doctstring", " 325 Returns the number for children. 326 327 @param[in] max 328 If max is less the lldb.UINT32_MAX, then the returned value is 329 capped to max. 330 331 @return 332 An integer value capped to the argument max.") GetNumChildren; 333 uint32_t 334 GetNumChildren (uint32_t max); 335 336 void * 337 GetOpaqueType(); 338 339 lldb::SBValue 340 Dereference (); 341 342 lldb::SBValue 343 AddressOf(); 344 345 bool 346 TypeIsPointerType (); 347 348 lldb::SBTarget 349 GetTarget(); 350 351 lldb::SBProcess 352 GetProcess(); 353 354 lldb::SBThread 355 GetThread(); 356 357 lldb::SBFrame 358 GetFrame(); 359 360 %feature("docstring", " 361 Find and watch a variable. 362 It returns an SBWatchpoint, which may be invalid.") Watch; 363 lldb::SBWatchpoint 364 Watch (bool resolve_location, bool read, bool write, SBError &error); 365 366 %feature("docstring", " 367 Find and watch the location pointed to by a variable. 368 It returns an SBWatchpoint, which may be invalid.") WatchPointee; 369 lldb::SBWatchpoint 370 WatchPointee (bool resolve_location, bool read, bool write, SBError &error); 371 372 bool 373 GetDescription (lldb::SBStream &description); 374 375 bool 376 GetExpressionPath (lldb::SBStream &description); 377 378 %feature("docstring", " 379 Get an SBData wrapping what this SBValue points to. 380 381 This method will dereference the current SBValue, if its 382 data type is a T* or T[], and extract item_count elements 383 of type T from it, copying their contents in an SBData. 384 385 @param[in] item_idx 386 The index of the first item to retrieve. For an array 387 this is equivalent to array[item_idx], for a pointer 388 to *(pointer + item_idx). In either case, the measurement 389 unit for item_idx is the sizeof(T) rather than the byte 390 391 @param[in] item_count 392 How many items should be copied into the output. By default 393 only one item is copied, but more can be asked for. 394 395 @return 396 An SBData with the contents of the copied items, on success. 397 An empty SBData otherwise.") GetPointeeData; 398 lldb::SBData 399 GetPointeeData (uint32_t item_idx = 0, 400 uint32_t item_count = 1); 401 402 %feature("docstring", " 403 Get an SBData wrapping the contents of this SBValue. 404 405 This method will read the contents of this object in memory 406 and copy them into an SBData for future use. 407 408 @return 409 An SBData with the contents of this SBValue, on success. 410 An empty SBData otherwise.") GetData; 411 lldb::SBData 412 GetData (); 413 414 bool 415 SetData (lldb::SBData &data, lldb::SBError& error); 416 417 lldb::addr_t 418 GetLoadAddress(); 419 420 lldb::SBAddress 421 GetAddress(); 422 423 lldb::SBValue 424 Persist (); 425 426 %feature("docstring", "Returns an expression path for this value." 427 ) GetExpressionPath; 428 bool 429 GetExpressionPath (lldb::SBStream &description, bool qualify_cxx_base_classes); 430 431 lldb::SBValue 432 EvaluateExpression(const char *expr) const; 433 434 lldb::SBValue 435 EvaluateExpression(const char *expr, 436 const SBExpressionOptions &options) const; 437 438 lldb::SBValue 439 EvaluateExpression(const char *expr, 440 const SBExpressionOptions &options, 441 const char *name) const; 442 443 STRING_EXTENSION(SBValue) 444 445 #ifdef SWIGPYTHON 446 %pythoncode %{ 447 def __get_dynamic__ (self): 448 '''Helper function for the "SBValue.dynamic" property.''' 449 return self.GetDynamicValue (eDynamicCanRunTarget) 450 451 class children_access(object): 452 '''A helper object that will lazily hand out thread for a process when supplied an index.''' 453 454 def __init__(self, sbvalue): 455 self.sbvalue = sbvalue 456 457 def __len__(self): 458 if self.sbvalue: 459 return int(self.sbvalue.GetNumChildren()) 460 return 0 461 462 def __getitem__(self, key): 463 if type(key) is int and key < len(self): 464 return self.sbvalue.GetChildAtIndex(key) 465 return None 466 467 def get_child_access_object(self): 468 '''An accessor function that returns a children_access() object which allows lazy member variable access from a lldb.SBValue object.''' 469 return self.children_access (self) 470 471 def get_value_child_list(self): 472 '''An accessor function that returns a list() that contains all children in a lldb.SBValue object.''' 473 children = [] 474 accessor = self.get_child_access_object() 475 for idx in range(len(accessor)): 476 children.append(accessor[idx]) 477 return children 478 479 def __iter__(self): 480 '''Iterate over all child values of a lldb.SBValue object.''' 481 return lldb_iter(self, 'GetNumChildren', 'GetChildAtIndex') 482 483 def __len__(self): 484 '''Return the number of child values of a lldb.SBValue object.''' 485 return self.GetNumChildren() 486 487 children = property(get_value_child_list, None, doc='''A read only property that returns a list() of lldb.SBValue objects for the children of the value.''') 488 child = property(get_child_access_object, None, doc='''A read only property that returns an object that can access children of a variable by index (child_value = value.children[12]).''') 489 name = property(GetName, None, doc='''A read only property that returns the name of this value as a string.''') 490 type = property(GetType, None, doc='''A read only property that returns a lldb.SBType object that represents the type for this value.''') 491 size = property(GetByteSize, None, doc='''A read only property that returns the size in bytes of this value.''') 492 is_in_scope = property(IsInScope, None, doc='''A read only property that returns a boolean value that indicates whether this value is currently lexically in scope.''') 493 format = property(GetName, SetFormat, doc='''A read/write property that gets/sets the format used for lldb.SBValue().GetValue() for this value. See enumerations that start with "lldb.eFormat".''') 494 value = property(GetValue, SetValueFromCString, doc='''A read/write property that gets/sets value from a string.''') 495 value_type = property(GetValueType, None, doc='''A read only property that returns an lldb enumeration value (see enumerations that start with "lldb.eValueType") that represents the type of this value (local, argument, global, register, etc.).''') 496 changed = property(GetValueDidChange, None, doc='''A read only property that returns a boolean value that indicates if this value has changed since it was last updated.''') 497 data = property(GetData, None, doc='''A read only property that returns an lldb object (lldb.SBData) that represents the bytes that make up the value for this object.''') 498 load_addr = property(GetLoadAddress, None, doc='''A read only property that returns the load address of this value as an integer.''') 499 addr = property(GetAddress, None, doc='''A read only property that returns an lldb.SBAddress that represents the address of this value if it is in memory.''') 500 deref = property(Dereference, None, doc='''A read only property that returns an lldb.SBValue that is created by dereferencing this value.''') 501 address_of = property(AddressOf, None, doc='''A read only property that returns an lldb.SBValue that represents the address-of this value.''') 502 error = property(GetError, None, doc='''A read only property that returns the lldb.SBError that represents the error from the last time the variable value was calculated.''') 503 summary = property(GetSummary, None, doc='''A read only property that returns the summary for this value as a string''') 504 description = property(GetObjectDescription, None, doc='''A read only property that returns the language-specific description of this value as a string''') 505 dynamic = property(__get_dynamic__, None, doc='''A read only property that returns an lldb.SBValue that is created by finding the dynamic type of this value.''') 506 location = property(GetLocation, None, doc='''A read only property that returns the location of this value as a string.''') 507 target = property(GetTarget, None, doc='''A read only property that returns the lldb.SBTarget that this value is associated with.''') 508 process = property(GetProcess, None, doc='''A read only property that returns the lldb.SBProcess that this value is associated with, the returned value might be invalid and should be tested.''') 509 thread = property(GetThread, None, doc='''A read only property that returns the lldb.SBThread that this value is associated with, the returned value might be invalid and should be tested.''') 510 frame = property(GetFrame, None, doc='''A read only property that returns the lldb.SBFrame that this value is associated with, the returned value might be invalid and should be tested.''') 511 num_children = property(GetNumChildren, None, doc='''A read only property that returns the number of child lldb.SBValues that this value has.''') 512 unsigned = property(GetValueAsUnsigned, None, doc='''A read only property that returns the value of this SBValue as an usigned integer.''') 513 signed = property(GetValueAsSigned, None, doc='''A read only property that returns the value of this SBValue as a signed integer.''') 514 515 def get_expr_path(self): 516 s = SBStream() 517 self.GetExpressionPath (s) 518 return s.GetData() 519 520 path = property(get_expr_path, None, doc='''A read only property that returns the expression path that one can use to reach this value in an expression.''') 521 522 def synthetic_child_from_expression(self, name, expr, options=None): 523 if options is None: options = lldb.SBExpressionOptions() 524 child = self.CreateValueFromExpression(name, expr, options) 525 child.SetSyntheticChildrenGenerated(True) 526 return child 527 528 def synthetic_child_from_data(self, name, data, type): 529 child = self.CreateValueFromData(name, data, type) 530 child.SetSyntheticChildrenGenerated(True) 531 return child 532 533 def synthetic_child_from_address(self, name, addr, type): 534 child = self.CreateValueFromAddress(name, addr, type) 535 child.SetSyntheticChildrenGenerated(True) 536 return child 537 538 def __eol_test(val): 539 """Default function for end of list test takes an SBValue object. 540 541 Return True if val is invalid or it corresponds to a null pointer. 542 Otherwise, return False. 543 """ 544 if not val or val.GetValueAsUnsigned() == 0: 545 return True 546 else: 547 return False 548 549 # ================================================== 550 # Iterator for lldb.SBValue treated as a linked list 551 # ================================================== 552 def linked_list_iter(self, next_item_name, end_of_list_test=__eol_test): 553 """Generator adaptor to support iteration for SBValue as a linked list. 554 555 linked_list_iter() is a special purpose iterator to treat the SBValue as 556 the head of a list data structure, where you specify the child member 557 name which points to the next item on the list and you specify the 558 end-of-list test function which takes an SBValue for an item and returns 559 True if EOL is reached and False if not. 560 561 linked_list_iter() also detects infinite loop and bails out early. 562 563 The end_of_list_test arg, if omitted, defaults to the __eol_test 564 function above. 565 566 For example, 567 568 # Get Frame #0. 569 ... 570 571 # Get variable 'task_head'. 572 task_head = frame0.FindVariable('task_head') 573 ... 574 575 for t in task_head.linked_list_iter('next'): 576 print t 577 """ 578 if end_of_list_test(self): 579 return 580 item = self 581 visited = set() 582 try: 583 while not end_of_list_test(item) and not item.GetValueAsUnsigned() in visited: 584 visited.add(item.GetValueAsUnsigned()) 585 yield item 586 # Prepare for the next iteration. 587 item = item.GetChildMemberWithName(next_item_name) 588 except: 589 # Exception occurred. Stop the generator. 590 pass 591 592 return 593 %} 594 #endif 595 596 }; 597 598 } // namespace lldb 599