LLDB API Documentation

- Main Page
- Namespaces
- Classes
- Files

- File List

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,
73 lldb::SBTypeSummaryOptions &options);
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_
lldb::SBThread
Definition: SBThread.h:21
lldb::SBData
Definition: SBData.h:17
lldb::SBTypeSummary
Definition: SBTypeSummary.h:56
lldb::SBType
Definition: SBType.h:101
lldb::SBFrame
Definition: SBFrame.h:18
SBDefines.h
SBData.h
lldb::SBValue
Definition: SBValue.h:22
lldb::SBTypeSynthetic
Definition: SBTypeSynthetic.h:20
lldb::SBExpressionOptions
Definition: SBExpressionOptions.h:19
lldb::SBBlock
Definition: SBBlock.h:20
lldb::SBValue
class LLDB_API SBValue
Definition: SBDefines.h:94
lldb::SBDeclaration
Definition: SBDeclaration.h:19
lldb::SBAddress
Definition: SBAddress.h:18
lldb::SBTypeFilter
Definition: SBTypeFilter.h:18
lldb::SBTypeSummaryOptions
Definition: SBTypeSummary.h:17
lldb::SBProcess
Definition: SBProcess.h:23
lldb::SBValueList
Definition: SBValueList.h:19
lldb::SBError
Definition: SBError.h:17
SBType.h
lldb::SBStream
Definition: SBStream.h:19
lldb::SBTypeFormat
Definition: SBTypeFormat.h:18
lldb::SBTarget
Definition: SBTarget.h:34
lldb::SBWatchpoint
Definition: SBWatchpoint.h:17