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