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 {
20
22public:
23 SBValue();
24
25 SBValue(const lldb::SBValue &rhs);
26
27 lldb::SBValue &operator=(const lldb::SBValue &rhs);
28
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 /// Creates a copy of the SBValue with a new name and setting the current
250 /// SBValue as its parent. It should be used when we want to change the
251 /// name of a SBValue without modifying the actual SBValue itself
252 /// (e.g. sythetic child provider).
253 lldb::SBValue Clone(const char *new_name);
254
255 lldb::SBDeclaration GetDeclaration();
256
257 /// Find out if a SBValue might have children.
258 ///
259 /// This call is much more efficient than GetNumChildren() as it
260 /// doesn't need to complete the underlying type. This is designed
261 /// to be used in a UI environment in order to detect if the
262 /// disclosure triangle should be displayed or not.
263 ///
264 /// This function returns true for class, union, structure,
265 /// pointers, references, arrays and more. Again, it does so without
266 /// doing any expensive type completion.
267 ///
268 /// \return
269 /// Returns \b true if the SBValue might have children, or \b
270 /// false otherwise.
271 bool MightHaveChildren();
272
273 bool IsRuntimeSupportValue();
274
275 uint32_t GetNumChildren();
276
277 uint32_t GetNumChildren(uint32_t max);
278
279 void *GetOpaqueType();
280
281 lldb::SBTarget GetTarget();
282
283 lldb::SBProcess GetProcess();
284
285 lldb::SBThread GetThread();
286
287 lldb::SBFrame GetFrame();
288
289 lldb::SBValue Dereference();
290
291 // Deprecated - please use GetType().IsPointerType() instead.
292 bool TypeIsPointerType();
293
294 lldb::SBType GetType();
295
296 lldb::SBValue Persist();
297
298 bool GetDescription(lldb::SBStream &description);
299
300 bool GetExpressionPath(lldb::SBStream &description);
301
302 bool GetExpressionPath(lldb::SBStream &description,
303 bool qualify_cxx_base_classes);
304
305 lldb::SBValue EvaluateExpression(const char *expr) const;
306 lldb::SBValue EvaluateExpression(const char *expr,
307 const SBExpressionOptions &options) const;
308 lldb::SBValue EvaluateExpression(const char *expr,
309 const SBExpressionOptions &options,
310 const char *name) const;
311
312#ifndef SWIG
313 SBValue(const lldb::ValueObjectSP &value_sp);
314#endif
315
316 /// Watch this value if it resides in memory.
317 ///
318 /// Sets a watchpoint on the value.
319 ///
320 /// \param[in] resolve_location
321 /// Resolve the location of this value once and watch its address.
322 /// This value must currently be set to \b true as watching all
323 /// locations of a variable or a variable path is not yet supported,
324 /// though we plan to support it in the future.
325 ///
326 /// \param[in] read
327 /// Stop when this value is accessed.
328 ///
329 /// \param[in] write
330 /// Stop when this value is modified
331 ///
332 /// \param[out] error
333 /// An error object. Contains the reason if there is some failure.
334 ///
335 /// \return
336 /// An SBWatchpoint object. This object might not be valid upon
337 /// return due to a value not being contained in memory, too
338 /// large, or watchpoint resources are not available or all in
339 /// use.
340 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write,
341 SBError &error);
342
343 // Backward compatibility fix in the interim.
344 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write);
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 lldb::SBWatchpoint WatchPointee(bool resolve_location, bool read, bool write,
371 SBError &error);
372
373#ifndef SWIG
374 /// Same as the protected version of GetSP that takes a locker, except that we
375 /// make the
376 /// locker locally in the function. Since the Target API mutex is recursive,
377 /// and the
378 /// StopLocker is a read lock, you can call this function even if you are
379 /// already
380 /// holding the two above-mentioned locks.
381 ///
382 /// \return
383 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
384 /// can cons up, in accordance with the SBValue's settings.
385 lldb::ValueObjectSP GetSP() const;
386#endif
387
388protected:
389 friend class SBBlock;
390 friend class SBFrame;
391 friend class SBTarget;
392 friend class SBThread;
393 friend class SBValueList;
394
395 /// Get the appropriate ValueObjectSP from this SBValue, consulting the
396 /// use_dynamic and use_synthetic options passed in to SetSP when the
397 /// SBValue's contents were set. Since this often requires examining memory,
398 /// and maybe even running code, it needs to acquire the Target API and
399 /// Process StopLock.
400 /// Those are held in an opaque class ValueLocker which is currently local to
401 /// SBValue.cpp.
402 /// So you don't have to get these yourself just default construct a
403 /// ValueLocker, and pass it into this.
404 /// If we need to make a ValueLocker and use it in some other .cpp file, we'll
405 /// have to move it to
406 /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so
407 /// far.
408 ///
409 /// \param[in] value_locker
410 /// An object that will hold the Target API, and Process RunLocks, and
411 /// auto-destroy them when it goes out of scope. Currently this is only
412 /// useful in
413 /// SBValue.cpp.
414 ///
415 /// \return
416 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
417 /// can cons up, in accordance with the SBValue's settings.
418 lldb::ValueObjectSP GetSP(ValueLocker &value_locker) const;
419
420 // these calls do the right thing WRT adjusting their settings according to
421 // the target's preferences
422 void SetSP(const lldb::ValueObjectSP &sp);
423
424 void SetSP(const lldb::ValueObjectSP &sp, bool use_synthetic);
425
426 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic);
427
428 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
429 bool use_synthetic);
430
431 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
432 bool use_synthetic, const char *name);
433
434private:
435 typedef std::shared_ptr<ValueImpl> ValueImplSP;
437
438 void SetSP(ValueImplSP impl_sp);
439};
440
441} // namespace lldb
442
443#endif // LLDB_API_SBVALUE_H
static llvm::raw_ostream & error(Stream &strm)
#define LLDB_API
Definition: SBDefines.h:26
static llvm::StringRef GetName(XcodeSDK::Type type)
Definition: XcodeSDK.cpp:21
std::shared_ptr< ValueImpl > ValueImplSP
Definition: SBValue.h:435
ValueImplSP m_opaque_sp
Definition: SBValue.h:436
Definition: SBAddress.h:15
Format
Display format definitions.
uint64_t user_id_t
Definition: lldb-types.h:80
uint64_t addr_t
Definition: lldb-types.h:79