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