1 //===-- SBValue.h -----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLDB_SBValue_h_
11 #define LLDB_SBValue_h_
13 #include "lldb/API/SBData.h"
14 #include "lldb/API/SBDefines.h"
15 #include "lldb/API/SBType.h"
22 class LLDB_API SBValue {
26 SBValue(const lldb::SBValue &rhs);
28 lldb::SBValue &operator=(const lldb::SBValue &rhs);
38 lldb::user_id_t GetID();
40 const char *GetName();
42 const char *GetTypeName();
44 const char *GetDisplayTypeName();
50 lldb::Format GetFormat();
52 void SetFormat(lldb::Format format);
54 const char *GetValue();
56 int64_t GetValueAsSigned(lldb::SBError &error, int64_t fail_value = 0);
58 uint64_t GetValueAsUnsigned(lldb::SBError &error, uint64_t fail_value = 0);
60 int64_t GetValueAsSigned(int64_t fail_value = 0);
62 uint64_t GetValueAsUnsigned(uint64_t fail_value = 0);
64 ValueType GetValueType();
66 // If you call this on a newly created ValueObject, it will always return
68 bool GetValueDidChange();
70 const char *GetSummary();
72 const char *GetSummary(lldb::SBStream &stream,
73 lldb::SBTypeSummaryOptions &options);
75 const char *GetObjectDescription();
77 const char *GetTypeValidatorResult();
79 lldb::SBValue GetDynamicValue(lldb::DynamicValueType use_dynamic);
81 lldb::SBValue GetStaticValue();
83 lldb::SBValue GetNonSyntheticValue();
85 lldb::DynamicValueType GetPreferDynamicValue();
87 void SetPreferDynamicValue(lldb::DynamicValueType use_dynamic);
89 bool GetPreferSyntheticValue();
91 void SetPreferSyntheticValue(bool use_synthetic);
97 bool IsSyntheticChildrenGenerated();
99 void SetSyntheticChildrenGenerated(bool);
101 const char *GetLocation();
103 // Deprecated - use the one that takes SBError&
104 bool SetValueFromCString(const char *value_str);
106 bool SetValueFromCString(const char *value_str, lldb::SBError &error);
108 lldb::SBTypeFormat GetTypeFormat();
110 lldb::SBTypeSummary GetTypeSummary();
112 lldb::SBTypeFilter GetTypeFilter();
114 #ifndef LLDB_DISABLE_PYTHON
115 lldb::SBTypeSynthetic GetTypeSynthetic();
118 lldb::SBValue GetChildAtIndex(uint32_t idx);
120 lldb::SBValue CreateChildAtOffset(const char *name, uint32_t offset,
123 // Deprecated - use the expression evaluator to perform type casting
124 lldb::SBValue Cast(lldb::SBType type);
126 lldb::SBValue CreateValueFromExpression(const char *name,
127 const char *expression);
129 lldb::SBValue CreateValueFromExpression(const char *name,
130 const char *expression,
131 SBExpressionOptions &options);
133 lldb::SBValue CreateValueFromAddress(const char *name, lldb::addr_t address,
136 // this has no address! GetAddress() and GetLoadAddress() as well as
137 // AddressOf() on the return of this call all return invalid
138 lldb::SBValue CreateValueFromData(const char *name, lldb::SBData data,
141 //------------------------------------------------------------------
142 /// Get a child value by index from a value.
144 /// Structs, unions, classes, arrays and pointers have child
145 /// values that can be access by index.
147 /// Structs and unions access child members using a zero based index
148 /// for each child member. For
150 /// Classes reserve the first indexes for base classes that have
151 /// members (empty base classes are omitted), and all members of the
152 /// current class will then follow the base classes.
154 /// Pointers differ depending on what they point to. If the pointer
155 /// points to a simple type, the child at index zero
156 /// is the only child value available, unless \a synthetic_allowed
157 /// is \b true, in which case the pointer will be used as an array
158 /// and can create 'synthetic' child values using positive or
159 /// negative indexes. If the pointer points to an aggregate type
160 /// (an array, class, union, struct), then the pointee is
161 /// transparently skipped and any children are going to be the indexes
162 /// of the child values within the aggregate type. For example if
163 /// we have a 'Point' type and we have a SBValue that contains a
164 /// pointer to a 'Point' type, then the child at index zero will be
165 /// the 'x' member, and the child at index 1 will be the 'y' member
166 /// (the child at index zero won't be a 'Point' instance).
168 /// If you actually need an SBValue that represents the type pointed
169 /// to by a SBValue for which GetType().IsPointeeType() returns true,
170 /// regardless of the pointee type, you can do that with SBValue::Dereference.
172 /// Arrays have a preset number of children that can be accessed by
173 /// index and will returns invalid child values for indexes that are
174 /// out of bounds unless the \a synthetic_allowed is \b true. In this
175 /// case the array can create 'synthetic' child values for indexes
176 /// that aren't in the array bounds using positive or negative
180 /// The index of the child value to get
182 /// @param[in] use_dynamic
183 /// An enumeration that specifies whether to get dynamic values,
184 /// and also if the target can be run to figure out the dynamic
185 /// type of the child value.
187 /// @param[in] can_create_synthetic
188 /// If \b true, then allow child values to be created by index
189 /// for pointers and arrays for indexes that normally wouldn't
193 /// A new SBValue object that represents the child member value.
194 //------------------------------------------------------------------
195 lldb::SBValue GetChildAtIndex(uint32_t idx,
196 lldb::DynamicValueType use_dynamic,
197 bool can_create_synthetic);
199 // Matches children of this object only and will match base classes and
200 // member names if this is a clang typed object.
201 uint32_t GetIndexOfChildWithName(const char *name);
203 // Matches child members of this object and child members of any base
205 lldb::SBValue GetChildMemberWithName(const char *name);
207 // Matches child members of this object and child members of any base
209 lldb::SBValue GetChildMemberWithName(const char *name,
210 lldb::DynamicValueType use_dynamic);
212 // Expands nested expressions like .a->b[0].c[1]->d
213 lldb::SBValue GetValueForExpressionPath(const char *expr_path);
215 lldb::SBValue AddressOf();
217 lldb::addr_t GetLoadAddress();
219 lldb::SBAddress GetAddress();
221 //------------------------------------------------------------------
222 /// Get an SBData wrapping what this SBValue points to.
224 /// This method will dereference the current SBValue, if its
225 /// data type is a T* or T[], and extract item_count elements
226 /// of type T from it, copying their contents in an SBData.
228 /// @param[in] item_idx
229 /// The index of the first item to retrieve. For an array
230 /// this is equivalent to array[item_idx], for a pointer
231 /// to *(pointer + item_idx). In either case, the measurement
232 /// unit for item_idx is the sizeof(T) rather than the byte
234 /// @param[in] item_count
235 /// How many items should be copied into the output. By default
236 /// only one item is copied, but more can be asked for.
239 /// An SBData with the contents of the copied items, on success.
240 /// An empty SBData otherwise.
241 //------------------------------------------------------------------
242 lldb::SBData GetPointeeData(uint32_t item_idx = 0, uint32_t item_count = 1);
244 //------------------------------------------------------------------
245 /// Get an SBData wrapping the contents of this SBValue.
247 /// This method will read the contents of this object in memory
248 /// and copy them into an SBData for future use.
251 /// An SBData with the contents of this SBValue, on success.
252 /// An empty SBData otherwise.
253 //------------------------------------------------------------------
254 lldb::SBData GetData();
256 bool SetData(lldb::SBData &data, lldb::SBError &error);
258 lldb::SBDeclaration GetDeclaration();
260 //------------------------------------------------------------------
261 /// Find out if a SBValue might have children.
263 /// This call is much more efficient than GetNumChildren() as it
264 /// doesn't need to complete the underlying type. This is designed
265 /// to be used in a UI environment in order to detect if the
266 /// disclosure triangle should be displayed or not.
268 /// This function returns true for class, union, structure,
269 /// pointers, references, arrays and more. Again, it does so without
270 /// doing any expensive type completion.
273 /// Returns \b true if the SBValue might have children, or \b
275 //------------------------------------------------------------------
276 bool MightHaveChildren();
278 bool IsRuntimeSupportValue();
280 uint32_t GetNumChildren();
282 uint32_t GetNumChildren(uint32_t max);
284 void *GetOpaqueType();
286 lldb::SBTarget GetTarget();
288 lldb::SBProcess GetProcess();
290 lldb::SBThread GetThread();
292 lldb::SBFrame GetFrame();
294 lldb::SBValue Dereference();
296 // Deprecated - please use GetType().IsPointerType() instead.
297 bool TypeIsPointerType();
299 lldb::SBType GetType();
301 lldb::SBValue Persist();
303 bool GetDescription(lldb::SBStream &description);
305 bool GetExpressionPath(lldb::SBStream &description);
307 bool GetExpressionPath(lldb::SBStream &description,
308 bool qualify_cxx_base_classes);
310 SBValue(const lldb::ValueObjectSP &value_sp);
312 //------------------------------------------------------------------
313 /// Watch this value if it resides in memory.
315 /// Sets a watchpoint on the value.
317 /// @param[in] resolve_location
318 /// Resolve the location of this value once and watch its address.
319 /// This value must currently be set to \b true as watching all
320 /// locations of a variable or a variable path is not yet supported,
321 /// though we plan to support it in the future.
324 /// Stop when this value is accessed.
327 /// Stop when this value is modified
329 /// @param[out] error
330 /// An error object. Contains the reason if there is some failure.
333 /// An SBWatchpoint object. This object might not be valid upon
334 /// return due to a value not being contained in memory, too
335 /// large, or watchpoint resources are not available or all in
337 //------------------------------------------------------------------
338 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write,
341 // Backward compatibility fix in the interim.
342 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write);
344 //------------------------------------------------------------------
345 /// Watch this value that this value points to in memory
347 /// Sets a watchpoint on the value.
349 /// @param[in] resolve_location
350 /// Resolve the location of this value once and watch its address.
351 /// This value must currently be set to \b true as watching all
352 /// locations of a variable or a variable path is not yet supported,
353 /// though we plan to support it in the future.
356 /// Stop when this value is accessed.
359 /// Stop when this value is modified
361 /// @param[out] error
362 /// An error object. Contains the reason if there is some failure.
365 /// An SBWatchpoint object. This object might not be valid upon
366 /// return due to a value not being contained in memory, too
367 /// large, or watchpoint resources are not available or all in
369 //------------------------------------------------------------------
370 lldb::SBWatchpoint WatchPointee(bool resolve_location, bool read, bool write,
373 //------------------------------------------------------------------
374 /// Same as the protected version of GetSP that takes a locker, except that we
376 /// locker locally in the function. Since the Target API mutex is recursive,
378 /// StopLocker is a read lock, you can call this function even if you are
380 /// holding the two above-mentioned locks.
383 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
384 /// can cons up, in accordance with the SBValue's settings.
385 //------------------------------------------------------------------
386 lldb::ValueObjectSP GetSP() const;
389 friend class SBBlock;
390 friend class SBFrame;
391 friend class SBTarget;
392 friend class SBThread;
393 friend class SBValueList;
395 //------------------------------------------------------------------
396 /// Get the appropriate ValueObjectSP from this SBValue, consulting the
397 /// use_dynamic and use_synthetic options passed in to SetSP when the
398 /// SBValue's contents were set. Since this often requires examining memory,
399 /// and maybe even running code, it needs to acquire the Target API and
400 /// Process StopLock.
401 /// Those are held in an opaque class ValueLocker which is currently local to
403 /// So you don't have to get these yourself just default construct a
404 /// ValueLocker, and pass it into this.
405 /// If we need to make a ValueLocker and use it in some other .cpp file, we'll
406 /// have to move it to
407 /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so
410 /// @param[in] value_locker
411 /// An object that will hold the Target API, and Process RunLocks, and
412 /// auto-destroy them when it goes out of scope. Currently this is only
417 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
418 /// can cons up, in accordance with the SBValue's settings.
419 //------------------------------------------------------------------
420 lldb::ValueObjectSP GetSP(ValueLocker &value_locker) const;
422 // these calls do the right thing WRT adjusting their settings according to
423 // the target's preferences
424 void SetSP(const lldb::ValueObjectSP &sp);
426 void SetSP(const lldb::ValueObjectSP &sp, bool use_synthetic);
428 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic);
430 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
433 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
434 bool use_synthetic, const char *name);
437 typedef std::shared_ptr<ValueImpl> ValueImplSP;
438 ValueImplSP m_opaque_sp;
440 void SetSP(ValueImplSP impl_sp);
445 #endif // LLDB_SBValue_h_