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