LLDB API Documentation

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