1254721Semaste//===-- SBValue.h -----------------------------------------------*- C++ -*-===// 2254721Semaste// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6254721Semaste// 7254721Semaste//===----------------------------------------------------------------------===// 8254721Semaste 9254721Semaste#ifndef LLDB_SBValue_h_ 10254721Semaste#define LLDB_SBValue_h_ 11254721Semaste 12254721Semaste#include "lldb/API/SBData.h" 13254721Semaste#include "lldb/API/SBDefines.h" 14254721Semaste#include "lldb/API/SBType.h" 15254721Semaste 16254721Semasteclass ValueImpl; 17254721Semasteclass ValueLocker; 18254721Semaste 19254721Semastenamespace lldb { 20254721Semaste 21314564Sdimclass LLDB_API SBValue { 22254721Semastepublic: 23314564Sdim SBValue(); 24254721Semaste 25314564Sdim SBValue(const lldb::SBValue &rhs); 26254721Semaste 27314564Sdim lldb::SBValue &operator=(const lldb::SBValue &rhs); 28254721Semaste 29314564Sdim ~SBValue(); 30254721Semaste 31353358Sdim explicit operator bool() const; 32353358Sdim 33314564Sdim bool IsValid(); 34254721Semaste 35314564Sdim void Clear(); 36254721Semaste 37314564Sdim SBError GetError(); 38254721Semaste 39314564Sdim lldb::user_id_t GetID(); 40254721Semaste 41314564Sdim const char *GetName(); 42254721Semaste 43314564Sdim const char *GetTypeName(); 44254721Semaste 45314564Sdim const char *GetDisplayTypeName(); 46254721Semaste 47314564Sdim size_t GetByteSize(); 48254721Semaste 49314564Sdim bool IsInScope(); 50254721Semaste 51314564Sdim lldb::Format GetFormat(); 52254721Semaste 53314564Sdim void SetFormat(lldb::Format format); 54254721Semaste 55314564Sdim const char *GetValue(); 56254721Semaste 57314564Sdim int64_t GetValueAsSigned(lldb::SBError &error, int64_t fail_value = 0); 58254721Semaste 59314564Sdim uint64_t GetValueAsUnsigned(lldb::SBError &error, uint64_t fail_value = 0); 60314564Sdim 61314564Sdim int64_t GetValueAsSigned(int64_t fail_value = 0); 62314564Sdim 63314564Sdim uint64_t GetValueAsUnsigned(uint64_t fail_value = 0); 64314564Sdim 65314564Sdim ValueType GetValueType(); 66314564Sdim 67314564Sdim // If you call this on a newly created ValueObject, it will always return 68314564Sdim // false. 69314564Sdim bool GetValueDidChange(); 70314564Sdim 71314564Sdim const char *GetSummary(); 72314564Sdim 73314564Sdim const char *GetSummary(lldb::SBStream &stream, 74314564Sdim lldb::SBTypeSummaryOptions &options); 75314564Sdim 76314564Sdim const char *GetObjectDescription(); 77314564Sdim 78314564Sdim lldb::SBValue GetDynamicValue(lldb::DynamicValueType use_dynamic); 79314564Sdim 80314564Sdim lldb::SBValue GetStaticValue(); 81314564Sdim 82314564Sdim lldb::SBValue GetNonSyntheticValue(); 83314564Sdim 84314564Sdim lldb::DynamicValueType GetPreferDynamicValue(); 85314564Sdim 86314564Sdim void SetPreferDynamicValue(lldb::DynamicValueType use_dynamic); 87314564Sdim 88314564Sdim bool GetPreferSyntheticValue(); 89314564Sdim 90314564Sdim void SetPreferSyntheticValue(bool use_synthetic); 91314564Sdim 92314564Sdim bool IsDynamic(); 93314564Sdim 94314564Sdim bool IsSynthetic(); 95314564Sdim 96314564Sdim bool IsSyntheticChildrenGenerated(); 97314564Sdim 98314564Sdim void SetSyntheticChildrenGenerated(bool); 99314564Sdim 100314564Sdim const char *GetLocation(); 101314564Sdim 102314564Sdim // Deprecated - use the one that takes SBError& 103314564Sdim bool SetValueFromCString(const char *value_str); 104314564Sdim 105314564Sdim bool SetValueFromCString(const char *value_str, lldb::SBError &error); 106314564Sdim 107314564Sdim lldb::SBTypeFormat GetTypeFormat(); 108314564Sdim 109314564Sdim lldb::SBTypeSummary GetTypeSummary(); 110314564Sdim 111314564Sdim lldb::SBTypeFilter GetTypeFilter(); 112314564Sdim 113314564Sdim lldb::SBTypeSynthetic GetTypeSynthetic(); 114254721Semaste 115314564Sdim lldb::SBValue GetChildAtIndex(uint32_t idx); 116254721Semaste 117314564Sdim lldb::SBValue CreateChildAtOffset(const char *name, uint32_t offset, 118314564Sdim lldb::SBType type); 119254721Semaste 120314564Sdim // Deprecated - use the expression evaluator to perform type casting 121314564Sdim lldb::SBValue Cast(lldb::SBType type); 122254721Semaste 123314564Sdim lldb::SBValue CreateValueFromExpression(const char *name, 124314564Sdim const char *expression); 125254721Semaste 126314564Sdim lldb::SBValue CreateValueFromExpression(const char *name, 127314564Sdim const char *expression, 128314564Sdim SBExpressionOptions &options); 129254721Semaste 130314564Sdim lldb::SBValue CreateValueFromAddress(const char *name, lldb::addr_t address, 131314564Sdim lldb::SBType type); 132254721Semaste 133314564Sdim // this has no address! GetAddress() and GetLoadAddress() as well as 134341825Sdim // AddressOf() on the return of this call all return invalid 135314564Sdim lldb::SBValue CreateValueFromData(const char *name, lldb::SBData data, 136314564Sdim lldb::SBType type); 137254721Semaste 138314564Sdim /// Get a child value by index from a value. 139314564Sdim /// 140314564Sdim /// Structs, unions, classes, arrays and pointers have child 141314564Sdim /// values that can be access by index. 142314564Sdim /// 143314564Sdim /// Structs and unions access child members using a zero based index 144314564Sdim /// for each child member. For 145314564Sdim /// 146314564Sdim /// Classes reserve the first indexes for base classes that have 147314564Sdim /// members (empty base classes are omitted), and all members of the 148314564Sdim /// current class will then follow the base classes. 149314564Sdim /// 150314564Sdim /// Pointers differ depending on what they point to. If the pointer 151314564Sdim /// points to a simple type, the child at index zero 152314564Sdim /// is the only child value available, unless \a synthetic_allowed 153314564Sdim /// is \b true, in which case the pointer will be used as an array 154314564Sdim /// and can create 'synthetic' child values using positive or 155314564Sdim /// negative indexes. If the pointer points to an aggregate type 156314564Sdim /// (an array, class, union, struct), then the pointee is 157314564Sdim /// transparently skipped and any children are going to be the indexes 158314564Sdim /// of the child values within the aggregate type. For example if 159314564Sdim /// we have a 'Point' type and we have a SBValue that contains a 160314564Sdim /// pointer to a 'Point' type, then the child at index zero will be 161314564Sdim /// the 'x' member, and the child at index 1 will be the 'y' member 162314564Sdim /// (the child at index zero won't be a 'Point' instance). 163314564Sdim /// 164314564Sdim /// If you actually need an SBValue that represents the type pointed 165314564Sdim /// to by a SBValue for which GetType().IsPointeeType() returns true, 166314564Sdim /// regardless of the pointee type, you can do that with SBValue::Dereference. 167314564Sdim /// 168314564Sdim /// Arrays have a preset number of children that can be accessed by 169314564Sdim /// index and will returns invalid child values for indexes that are 170314564Sdim /// out of bounds unless the \a synthetic_allowed is \b true. In this 171314564Sdim /// case the array can create 'synthetic' child values for indexes 172314564Sdim /// that aren't in the array bounds using positive or negative 173314564Sdim /// indexes. 174314564Sdim /// 175353358Sdim /// \param[in] idx 176314564Sdim /// The index of the child value to get 177314564Sdim /// 178353358Sdim /// \param[in] use_dynamic 179314564Sdim /// An enumeration that specifies whether to get dynamic values, 180314564Sdim /// and also if the target can be run to figure out the dynamic 181314564Sdim /// type of the child value. 182314564Sdim /// 183353358Sdim /// \param[in] can_create_synthetic 184314564Sdim /// If \b true, then allow child values to be created by index 185314564Sdim /// for pointers and arrays for indexes that normally wouldn't 186314564Sdim /// be allowed. 187314564Sdim /// 188353358Sdim /// \return 189314564Sdim /// A new SBValue object that represents the child member value. 190314564Sdim lldb::SBValue GetChildAtIndex(uint32_t idx, 191314564Sdim lldb::DynamicValueType use_dynamic, 192314564Sdim bool can_create_synthetic); 193296417Sdim 194314564Sdim // Matches children of this object only and will match base classes and 195314564Sdim // member names if this is a clang typed object. 196314564Sdim uint32_t GetIndexOfChildWithName(const char *name); 197254721Semaste 198314564Sdim // Matches child members of this object and child members of any base 199314564Sdim // classes. 200314564Sdim lldb::SBValue GetChildMemberWithName(const char *name); 201254721Semaste 202314564Sdim // Matches child members of this object and child members of any base 203314564Sdim // classes. 204314564Sdim lldb::SBValue GetChildMemberWithName(const char *name, 205314564Sdim lldb::DynamicValueType use_dynamic); 206254721Semaste 207314564Sdim // Expands nested expressions like .a->b[0].c[1]->d 208314564Sdim lldb::SBValue GetValueForExpressionPath(const char *expr_path); 209254721Semaste 210314564Sdim lldb::SBValue AddressOf(); 211254721Semaste 212314564Sdim lldb::addr_t GetLoadAddress(); 213254721Semaste 214314564Sdim lldb::SBAddress GetAddress(); 215254721Semaste 216314564Sdim /// Get an SBData wrapping what this SBValue points to. 217314564Sdim /// 218314564Sdim /// This method will dereference the current SBValue, if its 219314564Sdim /// data type is a T* or T[], and extract item_count elements 220314564Sdim /// of type T from it, copying their contents in an SBData. 221314564Sdim /// 222353358Sdim /// \param[in] item_idx 223314564Sdim /// The index of the first item to retrieve. For an array 224314564Sdim /// this is equivalent to array[item_idx], for a pointer 225314564Sdim /// to *(pointer + item_idx). In either case, the measurement 226314564Sdim /// unit for item_idx is the sizeof(T) rather than the byte 227314564Sdim /// 228353358Sdim /// \param[in] item_count 229314564Sdim /// How many items should be copied into the output. By default 230314564Sdim /// only one item is copied, but more can be asked for. 231314564Sdim /// 232353358Sdim /// \return 233314564Sdim /// An SBData with the contents of the copied items, on success. 234314564Sdim /// An empty SBData otherwise. 235314564Sdim lldb::SBData GetPointeeData(uint32_t item_idx = 0, uint32_t item_count = 1); 236254721Semaste 237314564Sdim /// Get an SBData wrapping the contents of this SBValue. 238314564Sdim /// 239314564Sdim /// This method will read the contents of this object in memory 240314564Sdim /// and copy them into an SBData for future use. 241314564Sdim /// 242353358Sdim /// \return 243314564Sdim /// An SBData with the contents of this SBValue, on success. 244314564Sdim /// An empty SBData otherwise. 245314564Sdim lldb::SBData GetData(); 246254721Semaste 247314564Sdim bool SetData(lldb::SBData &data, lldb::SBError &error); 248254721Semaste 249314564Sdim lldb::SBDeclaration GetDeclaration(); 250254721Semaste 251314564Sdim /// Find out if a SBValue might have children. 252314564Sdim /// 253314564Sdim /// This call is much more efficient than GetNumChildren() as it 254314564Sdim /// doesn't need to complete the underlying type. This is designed 255314564Sdim /// to be used in a UI environment in order to detect if the 256314564Sdim /// disclosure triangle should be displayed or not. 257314564Sdim /// 258314564Sdim /// This function returns true for class, union, structure, 259314564Sdim /// pointers, references, arrays and more. Again, it does so without 260314564Sdim /// doing any expensive type completion. 261314564Sdim /// 262353358Sdim /// \return 263314564Sdim /// Returns \b true if the SBValue might have children, or \b 264314564Sdim /// false otherwise. 265314564Sdim bool MightHaveChildren(); 266314564Sdim 267314564Sdim bool IsRuntimeSupportValue(); 268314564Sdim 269314564Sdim uint32_t GetNumChildren(); 270314564Sdim 271314564Sdim uint32_t GetNumChildren(uint32_t max); 272314564Sdim 273314564Sdim void *GetOpaqueType(); 274314564Sdim 275314564Sdim lldb::SBTarget GetTarget(); 276314564Sdim 277314564Sdim lldb::SBProcess GetProcess(); 278314564Sdim 279314564Sdim lldb::SBThread GetThread(); 280314564Sdim 281314564Sdim lldb::SBFrame GetFrame(); 282314564Sdim 283314564Sdim lldb::SBValue Dereference(); 284314564Sdim 285314564Sdim // Deprecated - please use GetType().IsPointerType() instead. 286314564Sdim bool TypeIsPointerType(); 287314564Sdim 288314564Sdim lldb::SBType GetType(); 289314564Sdim 290314564Sdim lldb::SBValue Persist(); 291314564Sdim 292314564Sdim bool GetDescription(lldb::SBStream &description); 293314564Sdim 294314564Sdim bool GetExpressionPath(lldb::SBStream &description); 295314564Sdim 296314564Sdim bool GetExpressionPath(lldb::SBStream &description, 297314564Sdim bool qualify_cxx_base_classes); 298314564Sdim 299353358Sdim lldb::SBValue EvaluateExpression(const char *expr) const; 300353358Sdim lldb::SBValue EvaluateExpression(const char *expr, 301353358Sdim const SBExpressionOptions &options) const; 302353358Sdim lldb::SBValue EvaluateExpression(const char *expr, 303353358Sdim const SBExpressionOptions &options, 304353358Sdim const char *name) const; 305353358Sdim 306314564Sdim SBValue(const lldb::ValueObjectSP &value_sp); 307314564Sdim 308314564Sdim /// Watch this value if it resides in memory. 309314564Sdim /// 310314564Sdim /// Sets a watchpoint on the value. 311314564Sdim /// 312353358Sdim /// \param[in] resolve_location 313314564Sdim /// Resolve the location of this value once and watch its address. 314314564Sdim /// This value must currently be set to \b true as watching all 315314564Sdim /// locations of a variable or a variable path is not yet supported, 316314564Sdim /// though we plan to support it in the future. 317314564Sdim /// 318353358Sdim /// \param[in] read 319314564Sdim /// Stop when this value is accessed. 320314564Sdim /// 321353358Sdim /// \param[in] write 322314564Sdim /// Stop when this value is modified 323314564Sdim /// 324353358Sdim /// \param[out] error 325314564Sdim /// An error object. Contains the reason if there is some failure. 326314564Sdim /// 327353358Sdim /// \return 328314564Sdim /// An SBWatchpoint object. This object might not be valid upon 329314564Sdim /// return due to a value not being contained in memory, too 330314564Sdim /// large, or watchpoint resources are not available or all in 331314564Sdim /// use. 332314564Sdim lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write, 333314564Sdim SBError &error); 334314564Sdim 335314564Sdim // Backward compatibility fix in the interim. 336314564Sdim lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write); 337314564Sdim 338314564Sdim /// Watch this value that this value points to in memory 339314564Sdim /// 340314564Sdim /// Sets a watchpoint on the value. 341314564Sdim /// 342353358Sdim /// \param[in] resolve_location 343314564Sdim /// Resolve the location of this value once and watch its address. 344314564Sdim /// This value must currently be set to \b true as watching all 345314564Sdim /// locations of a variable or a variable path is not yet supported, 346314564Sdim /// though we plan to support it in the future. 347314564Sdim /// 348353358Sdim /// \param[in] read 349314564Sdim /// Stop when this value is accessed. 350314564Sdim /// 351353358Sdim /// \param[in] write 352314564Sdim /// Stop when this value is modified 353314564Sdim /// 354353358Sdim /// \param[out] error 355314564Sdim /// An error object. Contains the reason if there is some failure. 356314564Sdim /// 357353358Sdim /// \return 358314564Sdim /// An SBWatchpoint object. This object might not be valid upon 359314564Sdim /// return due to a value not being contained in memory, too 360314564Sdim /// large, or watchpoint resources are not available or all in 361314564Sdim /// use. 362314564Sdim lldb::SBWatchpoint WatchPointee(bool resolve_location, bool read, bool write, 363314564Sdim SBError &error); 364314564Sdim 365314564Sdim /// Same as the protected version of GetSP that takes a locker, except that we 366314564Sdim /// make the 367314564Sdim /// locker locally in the function. Since the Target API mutex is recursive, 368314564Sdim /// and the 369314564Sdim /// StopLocker is a read lock, you can call this function even if you are 370314564Sdim /// already 371314564Sdim /// holding the two above-mentioned locks. 372314564Sdim /// 373353358Sdim /// \return 374314564Sdim /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we 375314564Sdim /// can cons up, in accordance with the SBValue's settings. 376314564Sdim lldb::ValueObjectSP GetSP() const; 377314564Sdim 378254721Semasteprotected: 379314564Sdim friend class SBBlock; 380314564Sdim friend class SBFrame; 381314564Sdim friend class SBTarget; 382314564Sdim friend class SBThread; 383314564Sdim friend class SBValueList; 384254721Semaste 385314564Sdim /// Get the appropriate ValueObjectSP from this SBValue, consulting the 386314564Sdim /// use_dynamic and use_synthetic options passed in to SetSP when the 387314564Sdim /// SBValue's contents were set. Since this often requires examining memory, 388314564Sdim /// and maybe even running code, it needs to acquire the Target API and 389314564Sdim /// Process StopLock. 390314564Sdim /// Those are held in an opaque class ValueLocker which is currently local to 391314564Sdim /// SBValue.cpp. 392314564Sdim /// So you don't have to get these yourself just default construct a 393314564Sdim /// ValueLocker, and pass it into this. 394314564Sdim /// If we need to make a ValueLocker and use it in some other .cpp file, we'll 395314564Sdim /// have to move it to 396314564Sdim /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so 397314564Sdim /// far. 398314564Sdim /// 399353358Sdim /// \param[in] value_locker 400314564Sdim /// An object that will hold the Target API, and Process RunLocks, and 401314564Sdim /// auto-destroy them when it goes out of scope. Currently this is only 402314564Sdim /// useful in 403314564Sdim /// SBValue.cpp. 404314564Sdim /// 405353358Sdim /// \return 406314564Sdim /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we 407314564Sdim /// can cons up, in accordance with the SBValue's settings. 408314564Sdim lldb::ValueObjectSP GetSP(ValueLocker &value_locker) const; 409254721Semaste 410314564Sdim // these calls do the right thing WRT adjusting their settings according to 411314564Sdim // the target's preferences 412314564Sdim void SetSP(const lldb::ValueObjectSP &sp); 413254721Semaste 414314564Sdim void SetSP(const lldb::ValueObjectSP &sp, bool use_synthetic); 415314564Sdim 416314564Sdim void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic); 417314564Sdim 418314564Sdim void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, 419314564Sdim bool use_synthetic); 420314564Sdim 421314564Sdim void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, 422314564Sdim bool use_synthetic, const char *name); 423314564Sdim 424254721Semasteprivate: 425314564Sdim typedef std::shared_ptr<ValueImpl> ValueImplSP; 426314564Sdim ValueImplSP m_opaque_sp; 427314564Sdim 428314564Sdim void SetSP(ValueImplSP impl_sp); 429254721Semaste}; 430254721Semaste 431254721Semaste} // namespace lldb 432254721Semaste 433314564Sdim#endif // LLDB_SBValue_h_ 434