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