1 //===-- SBValue.h -----------------------------------------------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 10 #ifndef LLDB_SBValue_h_ 11 #define LLDB_SBValue_h_ 12 13 #include "lldb/API/SBData.h" 14 #include "lldb/API/SBDefines.h" 15 #include "lldb/API/SBType.h" 16 17 class ValueImpl; 18 class ValueLocker; 19 20 namespace lldb { 21 22 class SBValue 23 { 24 friend class ValueLocker; 25 26 public: 27 SBValue (); 28 29 SBValue (const lldb::SBValue &rhs); 30 31 lldb::SBValue & 32 operator =(const lldb::SBValue &rhs); 33 34 ~SBValue (); 35 36 bool 37 IsValid(); 38 39 void 40 Clear(); 41 42 SBError 43 GetError(); 44 45 lldb::user_id_t 46 GetID (); 47 48 const char * 49 GetName(); 50 51 const char * 52 GetTypeName (); 53 54 size_t 55 GetByteSize (); 56 57 bool 58 IsInScope (); 59 60 lldb::Format 61 GetFormat (); 62 63 void 64 SetFormat (lldb::Format format); 65 66 const char * 67 GetValue (); 68 69 int64_t 70 GetValueAsSigned (lldb::SBError& error, int64_t fail_value=0); 71 72 uint64_t 73 GetValueAsUnsigned (lldb::SBError& error, uint64_t fail_value=0); 74 75 int64_t 76 GetValueAsSigned(int64_t fail_value=0); 77 78 uint64_t 79 GetValueAsUnsigned(uint64_t fail_value=0); 80 81 ValueType 82 GetValueType (); 83 84 bool 85 GetValueDidChange (); 86 87 const char * 88 GetSummary (); 89 90 const char * 91 GetObjectDescription (); 92 93 lldb::SBValue 94 GetDynamicValue (lldb::DynamicValueType use_dynamic); 95 96 lldb::SBValue 97 GetStaticValue (); 98 99 lldb::SBValue 100 GetNonSyntheticValue (); 101 102 lldb::DynamicValueType 103 GetPreferDynamicValue (); 104 105 void 106 SetPreferDynamicValue (lldb::DynamicValueType use_dynamic); 107 108 bool 109 GetPreferSyntheticValue (); 110 111 void 112 SetPreferSyntheticValue (bool use_synthetic); 113 114 bool 115 IsDynamic (); 116 117 bool 118 IsSynthetic (); 119 120 const char * 121 GetLocation (); 122 123 // Deprecated - use the one that takes SBError& 124 bool 125 SetValueFromCString (const char *value_str); 126 127 bool 128 SetValueFromCString (const char *value_str, lldb::SBError& error); 129 130 lldb::SBTypeFormat 131 GetTypeFormat (); 132 133 #ifndef LLDB_DISABLE_PYTHON 134 lldb::SBTypeSummary 135 GetTypeSummary (); 136 #endif 137 138 lldb::SBTypeFilter 139 GetTypeFilter (); 140 141 #ifndef LLDB_DISABLE_PYTHON 142 lldb::SBTypeSynthetic 143 GetTypeSynthetic (); 144 #endif 145 146 lldb::SBValue 147 GetChildAtIndex (uint32_t idx); 148 149 lldb::SBValue 150 CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type); 151 152 lldb::SBValue 153 Cast (lldb::SBType type); 154 155 lldb::SBValue 156 CreateValueFromExpression (const char *name, const char* expression); 157 158 lldb::SBValue 159 CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options); 160 161 lldb::SBValue 162 CreateValueFromAddress (const char* name, 163 lldb::addr_t address, 164 lldb::SBType type); 165 166 // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf() 167 // on the return of this call all return invalid 168 lldb::SBValue 169 CreateValueFromData (const char* name, 170 lldb::SBData data, 171 lldb::SBType type); 172 173 //------------------------------------------------------------------ 174 /// Get a child value by index from a value. 175 /// 176 /// Structs, unions, classes, arrays and and pointers have child 177 /// values that can be access by index. 178 /// 179 /// Structs and unions access child members using a zero based index 180 /// for each child member. For 181 /// 182 /// Classes reserve the first indexes for base classes that have 183 /// members (empty base classes are omitted), and all members of the 184 /// current class will then follow the base classes. 185 /// 186 /// Pointers differ depending on what they point to. If the pointer 187 /// points to a simple type, the child at index zero 188 /// is the only child value available, unless \a synthetic_allowed 189 /// is \b true, in which case the pointer will be used as an array 190 /// and can create 'synthetic' child values using positive or 191 /// negative indexes. If the pointer points to an aggregate type 192 /// (an array, class, union, struct), then the pointee is 193 /// transparently skipped and any children are going to be the indexes 194 /// of the child values within the aggregate type. For example if 195 /// we have a 'Point' type and we have a SBValue that contains a 196 /// pointer to a 'Point' type, then the child at index zero will be 197 /// the 'x' member, and the child at index 1 will be the 'y' member 198 /// (the child at index zero won't be a 'Point' instance). 199 /// 200 /// Arrays have a preset number of children that can be accessed by 201 /// index and will returns invalid child values for indexes that are 202 /// out of bounds unless the \a synthetic_allowed is \b true. In this 203 /// case the array can create 'synthetic' child values for indexes 204 /// that aren't in the array bounds using positive or negative 205 /// indexes. 206 /// 207 /// @param[in] idx 208 /// The index of the child value to get 209 /// 210 /// @param[in] use_dynamic 211 /// An enumeration that specifies wether to get dynamic values, 212 /// and also if the target can be run to figure out the dynamic 213 /// type of the child value. 214 /// 215 /// @param[in] synthetic_allowed 216 /// If \b true, then allow child values to be created by index 217 /// for pointers and arrays for indexes that normally wouldn't 218 /// be allowed. 219 /// 220 /// @return 221 /// A new SBValue object that represents the child member value. 222 //------------------------------------------------------------------ 223 lldb::SBValue 224 GetChildAtIndex (uint32_t idx, 225 lldb::DynamicValueType use_dynamic, 226 bool can_create_synthetic); 227 228 // Matches children of this object only and will match base classes and 229 // member names if this is a clang typed object. 230 uint32_t 231 GetIndexOfChildWithName (const char *name); 232 233 // Matches child members of this object and child members of any base 234 // classes. 235 lldb::SBValue 236 GetChildMemberWithName (const char *name); 237 238 // Matches child members of this object and child members of any base 239 // classes. 240 lldb::SBValue 241 GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic); 242 243 // Expands nested expressions like .a->b[0].c[1]->d 244 lldb::SBValue 245 GetValueForExpressionPath(const char* expr_path); 246 247 lldb::SBValue 248 AddressOf(); 249 250 lldb::addr_t 251 GetLoadAddress(); 252 253 lldb::SBAddress 254 GetAddress(); 255 256 //------------------------------------------------------------------ 257 /// Get an SBData wrapping what this SBValue points to. 258 /// 259 /// This method will dereference the current SBValue, if its 260 /// data type is a T* or T[], and extract item_count elements 261 /// of type T from it, copying their contents in an SBData. 262 /// 263 /// @param[in] item_idx 264 /// The index of the first item to retrieve. For an array 265 /// this is equivalent to array[item_idx], for a pointer 266 /// to *(pointer + item_idx). In either case, the measurement 267 /// unit for item_idx is the sizeof(T) rather than the byte 268 /// 269 /// @param[in] item_count 270 /// How many items should be copied into the output. By default 271 /// only one item is copied, but more can be asked for. 272 /// 273 /// @return 274 /// An SBData with the contents of the copied items, on success. 275 /// An empty SBData otherwise. 276 //------------------------------------------------------------------ 277 lldb::SBData 278 GetPointeeData (uint32_t item_idx = 0, 279 uint32_t item_count = 1); 280 281 //------------------------------------------------------------------ 282 /// Get an SBData wrapping the contents of this SBValue. 283 /// 284 /// This method will read the contents of this object in memory 285 /// and copy them into an SBData for future use. 286 /// 287 /// @return 288 /// An SBData with the contents of this SBValue, on success. 289 /// An empty SBData otherwise. 290 //------------------------------------------------------------------ 291 lldb::SBData 292 GetData (); 293 294 bool 295 SetData (lldb::SBData &data, lldb::SBError& error); 296 297 lldb::SBDeclaration 298 GetDeclaration (); 299 300 //------------------------------------------------------------------ 301 /// Find out if a SBValue might have children. 302 /// 303 /// This call is much more efficient than GetNumChildren() as it 304 /// doesn't need to complete the underlying type. This is designed 305 /// to be used in a UI environment in order to detect if the 306 /// disclosure triangle should be displayed or not. 307 /// 308 /// This function returns true for class, union, structure, 309 /// pointers, references, arrays and more. Again, it does so without 310 /// doing any expensive type completion. 311 /// 312 /// @return 313 /// Returns \b true if the SBValue might have children, or \b 314 /// false otherwise. 315 //------------------------------------------------------------------ 316 bool 317 MightHaveChildren (); 318 319 uint32_t 320 GetNumChildren (); 321 322 void * 323 GetOpaqueType(); 324 325 lldb::SBTarget 326 GetTarget(); 327 328 lldb::SBProcess 329 GetProcess(); 330 331 lldb::SBThread 332 GetThread(); 333 334 lldb::SBFrame 335 GetFrame(); 336 337 lldb::SBValue 338 Dereference (); 339 340 bool 341 TypeIsPointerType (); 342 343 lldb::SBType 344 GetType(); 345 346 bool 347 GetDescription (lldb::SBStream &description); 348 349 bool 350 GetExpressionPath (lldb::SBStream &description); 351 352 bool 353 GetExpressionPath (lldb::SBStream &description, 354 bool qualify_cxx_base_classes); 355 356 SBValue (const lldb::ValueObjectSP &value_sp); 357 358 //------------------------------------------------------------------ 359 /// Watch this value if it resides in memory. 360 /// 361 /// Sets a watchpoint on the value. 362 /// 363 /// @param[in] resolve_location 364 /// Resolve the location of this value once and watch its address. 365 /// This value must currently be set to \b true as watching all 366 /// locations of a variable or a variable path is not yet supported, 367 /// though we plan to support it in the future. 368 /// 369 /// @param[in] read 370 /// Stop when this value is accessed. 371 /// 372 /// @param[in] write 373 /// Stop when this value is modified 374 /// 375 /// @param[out] 376 /// An error object. Contains the reason if there is some failure. 377 /// 378 /// @return 379 /// An SBWatchpoint object. This object might not be valid upon 380 /// return due to a value not being contained in memory, too 381 /// large, or watchpoint resources are not available or all in 382 /// use. 383 //------------------------------------------------------------------ 384 lldb::SBWatchpoint 385 Watch (bool resolve_location, bool read, bool write, SBError &error); 386 387 // Backward compatibility fix in the interim. 388 lldb::SBWatchpoint 389 Watch (bool resolve_location, bool read, bool write); 390 391 //------------------------------------------------------------------ 392 /// Watch this value that this value points to in memory 393 /// 394 /// Sets a watchpoint on the value. 395 /// 396 /// @param[in] resolve_location 397 /// Resolve the location of this value once and watch its address. 398 /// This value must currently be set to \b true as watching all 399 /// locations of a variable or a variable path is not yet supported, 400 /// though we plan to support it in the future. 401 /// 402 /// @param[in] read 403 /// Stop when this value is accessed. 404 /// 405 /// @param[in] write 406 /// Stop when this value is modified 407 /// 408 /// @param[out] 409 /// An error object. Contains the reason if there is some failure. 410 /// 411 /// @return 412 /// An SBWatchpoint object. This object might not be valid upon 413 /// return due to a value not being contained in memory, too 414 /// large, or watchpoint resources are not available or all in 415 /// use. 416 //------------------------------------------------------------------ 417 lldb::SBWatchpoint 418 WatchPointee (bool resolve_location, bool read, bool write, SBError &error); 419 420 //------------------------------------------------------------------ 421 /// Same as the protected version of GetSP that takes a locker, except that we make the 422 /// locker locally in the function. Since the Target API mutex is recursive, and the 423 /// StopLocker is a read lock, you can call this function even if you are already 424 /// holding the two above-mentioned locks. 425 /// 426 /// @return 427 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we 428 /// can cons up, in accordance with the SBValue's settings. 429 //------------------------------------------------------------------ 430 lldb::ValueObjectSP 431 GetSP () const; 432 433 protected: 434 friend class SBBlock; 435 friend class SBFrame; 436 friend class SBTarget; 437 friend class SBThread; 438 friend class SBValueList; 439 440 //------------------------------------------------------------------ 441 /// Get the appropriate ValueObjectSP from this SBValue, consulting the 442 /// use_dynamic and use_synthetic options passed in to SetSP when the 443 /// SBValue's contents were set. Since this often requires examining memory, 444 /// and maybe even running code, it needs to acquire the Target API and Process StopLock. 445 /// Those are held in an opaque class ValueLocker which is currently local to SBValue.cpp. 446 /// So you don't have to get these yourself just default construct a ValueLocker, and pass it into this. 447 /// If we need to make a ValueLocker and use it in some other .cpp file, we'll have to move it to 448 /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so far. 449 /// 450 /// @param[in] value_locker 451 /// An object that will hold the Target API, and Process RunLocks, and 452 /// auto-destroy them when it goes out of scope. Currently this is only useful in 453 /// SBValue.cpp. 454 /// 455 /// @return 456 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we 457 /// can cons up, in accordance with the SBValue's settings. 458 //------------------------------------------------------------------ 459 lldb::ValueObjectSP 460 GetSP (ValueLocker &value_locker) const; 461 462 // these calls do the right thing WRT adjusting their settings according to the target's preferences 463 void 464 SetSP (const lldb::ValueObjectSP &sp); 465 466 void 467 SetSP (const lldb::ValueObjectSP &sp, bool use_synthetic); 468 469 void 470 SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic); 471 472 void 473 SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic); 474 475 void 476 SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic, const char *name); 477 478 private: 479 typedef std::shared_ptr<ValueImpl> ValueImplSP; 480 ValueImplSP m_opaque_sp; 481 482 void 483 SetSP (ValueImplSP impl_sp); 484 }; 485 486 } // namespace lldb 487 488 #endif // LLDB_SBValue_h_ 489
