//===-- SBValue.h -----------------------------------------------*- C++ -*-===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// #ifndef LLDB_SBValue_h_ #define LLDB_SBValue_h_ #include "lldb/API/SBData.h" #include "lldb/API/SBDefines.h" #include "lldb/API/SBType.h" class ValueImpl; class ValueLocker; namespace lldb { class SBValue { friend class ValueLocker; public: SBValue (); SBValue (const lldb::SBValue &rhs); lldb::SBValue & operator =(const lldb::SBValue &rhs); ~SBValue (); bool IsValid(); void Clear(); SBError GetError(); lldb::user_id_t GetID (); const char * GetName(); const char * GetTypeName (); size_t GetByteSize (); bool IsInScope (); lldb::Format GetFormat (); void SetFormat (lldb::Format format); const char * GetValue (); int64_t GetValueAsSigned (lldb::SBError& error, int64_t fail_value=0); uint64_t GetValueAsUnsigned (lldb::SBError& error, uint64_t fail_value=0); int64_t GetValueAsSigned(int64_t fail_value=0); uint64_t GetValueAsUnsigned(uint64_t fail_value=0); ValueType GetValueType (); bool GetValueDidChange (); const char * GetSummary (); const char * GetObjectDescription (); lldb::SBValue GetDynamicValue (lldb::DynamicValueType use_dynamic); lldb::SBValue GetStaticValue (); lldb::SBValue GetNonSyntheticValue (); lldb::DynamicValueType GetPreferDynamicValue (); void SetPreferDynamicValue (lldb::DynamicValueType use_dynamic); bool GetPreferSyntheticValue (); void SetPreferSyntheticValue (bool use_synthetic); bool IsDynamic (); bool IsSynthetic (); const char * GetLocation (); // Deprecated - use the one that takes SBError& bool SetValueFromCString (const char *value_str); bool SetValueFromCString (const char *value_str, lldb::SBError& error); lldb::SBTypeFormat GetTypeFormat (); #ifndef LLDB_DISABLE_PYTHON lldb::SBTypeSummary GetTypeSummary (); #endif lldb::SBTypeFilter GetTypeFilter (); #ifndef LLDB_DISABLE_PYTHON lldb::SBTypeSynthetic GetTypeSynthetic (); #endif lldb::SBValue GetChildAtIndex (uint32_t idx); lldb::SBValue CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type); lldb::SBValue Cast (lldb::SBType type); lldb::SBValue CreateValueFromExpression (const char *name, const char* expression); lldb::SBValue CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options); lldb::SBValue CreateValueFromAddress (const char* name, lldb::addr_t address, lldb::SBType type); // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf() // on the return of this call all return invalid lldb::SBValue CreateValueFromData (const char* name, lldb::SBData data, lldb::SBType type); //------------------------------------------------------------------ /// Get a child value by index from a value. /// /// Structs, unions, classes, arrays and and pointers have child /// values that can be access by index. /// /// Structs and unions access child members using a zero based index /// for each child member. For /// /// Classes reserve the first indexes for base classes that have /// members (empty base classes are omitted), and all members of the /// current class will then follow the base classes. /// /// Pointers differ depending on what they point to. If the pointer /// points to a simple type, the child at index zero /// is the only child value available, unless \a synthetic_allowed /// is \b true, in which case the pointer will be used as an array /// and can create 'synthetic' child values using positive or /// negative indexes. If the pointer points to an aggregate type /// (an array, class, union, struct), then the pointee is /// transparently skipped and any children are going to be the indexes /// of the child values within the aggregate type. For example if /// we have a 'Point' type and we have a SBValue that contains a /// pointer to a 'Point' type, then the child at index zero will be /// the 'x' member, and the child at index 1 will be the 'y' member /// (the child at index zero won't be a 'Point' instance). /// /// Arrays have a preset number of children that can be accessed by /// index and will returns invalid child values for indexes that are /// out of bounds unless the \a synthetic_allowed is \b true. In this /// case the array can create 'synthetic' child values for indexes /// that aren't in the array bounds using positive or negative /// indexes. /// /// @param[in] idx /// The index of the child value to get /// /// @param[in] use_dynamic /// An enumeration that specifies wether to get dynamic values, /// and also if the target can be run to figure out the dynamic /// type of the child value. /// /// @param[in] synthetic_allowed /// If \b true, then allow child values to be created by index /// for pointers and arrays for indexes that normally wouldn't /// be allowed. /// /// @return /// A new SBValue object that represents the child member value. //------------------------------------------------------------------ lldb::SBValue GetChildAtIndex (uint32_t idx, lldb::DynamicValueType use_dynamic, bool can_create_synthetic); // Matches children of this object only and will match base classes and // member names if this is a clang typed object. uint32_t GetIndexOfChildWithName (const char *name); // Matches child members of this object and child members of any base // classes. lldb::SBValue GetChildMemberWithName (const char *name); // Matches child members of this object and child members of any base // classes. lldb::SBValue GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic); // Expands nested expressions like .a->b[0].c[1]->d lldb::SBValue GetValueForExpressionPath(const char* expr_path); lldb::SBValue AddressOf(); lldb::addr_t GetLoadAddress(); lldb::SBAddress GetAddress(); //------------------------------------------------------------------ /// Get an SBData wrapping what this SBValue points to. /// /// This method will dereference the current SBValue, if its /// data type is a T* or T[], and extract item_count elements /// of type T from it, copying their contents in an SBData. /// /// @param[in] item_idx /// The index of the first item to retrieve. For an array /// this is equivalent to array[item_idx], for a pointer /// to *(pointer + item_idx). In either case, the measurement /// unit for item_idx is the sizeof(T) rather than the byte /// /// @param[in] item_count /// How many items should be copied into the output. By default /// only one item is copied, but more can be asked for. /// /// @return /// An SBData with the contents of the copied items, on success. /// An empty SBData otherwise. //------------------------------------------------------------------ lldb::SBData GetPointeeData (uint32_t item_idx = 0, uint32_t item_count = 1); //------------------------------------------------------------------ /// Get an SBData wrapping the contents of this SBValue. /// /// This method will read the contents of this object in memory /// and copy them into an SBData for future use. /// /// @return /// An SBData with the contents of this SBValue, on success. /// An empty SBData otherwise. //------------------------------------------------------------------ lldb::SBData GetData (); bool SetData (lldb::SBData &data, lldb::SBError& error); lldb::SBDeclaration GetDeclaration (); //------------------------------------------------------------------ /// Find out if a SBValue might have children. /// /// This call is much more efficient than GetNumChildren() as it /// doesn't need to complete the underlying type. This is designed /// to be used in a UI environment in order to detect if the /// disclosure triangle should be displayed or not. /// /// This function returns true for class, union, structure, /// pointers, references, arrays and more. Again, it does so without /// doing any expensive type completion. /// /// @return /// Returns \b true if the SBValue might have children, or \b /// false otherwise. //------------------------------------------------------------------ bool MightHaveChildren (); uint32_t GetNumChildren (); void * GetOpaqueType(); lldb::SBTarget GetTarget(); lldb::SBProcess GetProcess(); lldb::SBThread GetThread(); lldb::SBFrame GetFrame(); lldb::SBValue Dereference (); bool TypeIsPointerType (); lldb::SBType GetType(); bool GetDescription (lldb::SBStream &description); bool GetExpressionPath (lldb::SBStream &description); bool GetExpressionPath (lldb::SBStream &description, bool qualify_cxx_base_classes); SBValue (const lldb::ValueObjectSP &value_sp); //------------------------------------------------------------------ /// Watch this value if it resides in memory. /// /// Sets a watchpoint on the value. /// /// @param[in] resolve_location /// Resolve the location of this value once and watch its address. /// This value must currently be set to \b true as watching all /// locations of a variable or a variable path is not yet supported, /// though we plan to support it in the future. /// /// @param[in] read /// Stop when this value is accessed. /// /// @param[in] write /// Stop when this value is modified /// /// @param[out] /// An error object. Contains the reason if there is some failure. /// /// @return /// An SBWatchpoint object. This object might not be valid upon /// return due to a value not being contained in memory, too /// large, or watchpoint resources are not available or all in /// use. //------------------------------------------------------------------ lldb::SBWatchpoint Watch (bool resolve_location, bool read, bool write, SBError &error); // Backward compatibility fix in the interim. lldb::SBWatchpoint Watch (bool resolve_location, bool read, bool write); //------------------------------------------------------------------ /// Watch this value that this value points to in memory /// /// Sets a watchpoint on the value. /// /// @param[in] resolve_location /// Resolve the location of this value once and watch its address. /// This value must currently be set to \b true as watching all /// locations of a variable or a variable path is not yet supported, /// though we plan to support it in the future. /// /// @param[in] read /// Stop when this value is accessed. /// /// @param[in] write /// Stop when this value is modified /// /// @param[out] /// An error object. Contains the reason if there is some failure. /// /// @return /// An SBWatchpoint object. This object might not be valid upon /// return due to a value not being contained in memory, too /// large, or watchpoint resources are not available or all in /// use. //------------------------------------------------------------------ lldb::SBWatchpoint WatchPointee (bool resolve_location, bool read, bool write, SBError &error); //------------------------------------------------------------------ /// Same as the protected version of GetSP that takes a locker, except that we make the /// locker locally in the function. Since the Target API mutex is recursive, and the /// StopLocker is a read lock, you can call this function even if you are already /// holding the two above-mentioned locks. /// /// @return /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we /// can cons up, in accordance with the SBValue's settings. //------------------------------------------------------------------ lldb::ValueObjectSP GetSP () const; protected: friend class SBBlock; friend class SBFrame; friend class SBTarget; friend class SBThread; friend class SBValueList; //------------------------------------------------------------------ /// Get the appropriate ValueObjectSP from this SBValue, consulting the /// use_dynamic and use_synthetic options passed in to SetSP when the /// SBValue's contents were set. Since this often requires examining memory, /// and maybe even running code, it needs to acquire the Target API and Process StopLock. /// Those are held in an opaque class ValueLocker which is currently local to SBValue.cpp. /// So you don't have to get these yourself just default construct a ValueLocker, and pass it into this. /// If we need to make a ValueLocker and use it in some other .cpp file, we'll have to move it to /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so far. /// /// @param[in] value_locker /// An object that will hold the Target API, and Process RunLocks, and /// auto-destroy them when it goes out of scope. Currently this is only useful in /// SBValue.cpp. /// /// @return /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we /// can cons up, in accordance with the SBValue's settings. //------------------------------------------------------------------ lldb::ValueObjectSP GetSP (ValueLocker &value_locker) const; // these calls do the right thing WRT adjusting their settings according to the target's preferences void SetSP (const lldb::ValueObjectSP &sp); void SetSP (const lldb::ValueObjectSP &sp, bool use_synthetic); void SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic); void SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic); void SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic, const char *name); private: typedef std::shared_ptr ValueImplSP; ValueImplSP m_opaque_sp; void SetSP (ValueImplSP impl_sp); }; } // namespace lldb #endif // LLDB_SBValue_h_