1 //===-- SBValue.h -----------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_SBValue_h_
10 #define LLDB_SBValue_h_
12 #include "lldb/API/SBData.h"
13 #include "lldb/API/SBDefines.h"
14 #include "lldb/API/SBType.h"
21 class LLDB_API SBValue {
25 SBValue(const lldb::SBValue &rhs);
27 lldb::SBValue &operator=(const lldb::SBValue &rhs);
31 explicit operator bool() const;
39 lldb::user_id_t GetID();
41 const char *GetName();
43 const char *GetTypeName();
45 const char *GetDisplayTypeName();
51 lldb::Format GetFormat();
53 void SetFormat(lldb::Format format);
55 const char *GetValue();
57 int64_t GetValueAsSigned(lldb::SBError &error, int64_t fail_value = 0);
59 uint64_t GetValueAsUnsigned(lldb::SBError &error, uint64_t fail_value = 0);
61 int64_t GetValueAsSigned(int64_t fail_value = 0);
63 uint64_t GetValueAsUnsigned(uint64_t fail_value = 0);
65 ValueType GetValueType();
67 // If you call this on a newly created ValueObject, it will always return
69 bool GetValueDidChange();
71 const char *GetSummary();
73 const char *GetSummary(lldb::SBStream &stream,
74 lldb::SBTypeSummaryOptions &options);
76 const char *GetObjectDescription();
78 lldb::SBValue GetDynamicValue(lldb::DynamicValueType use_dynamic);
80 lldb::SBValue GetStaticValue();
82 lldb::SBValue GetNonSyntheticValue();
84 lldb::DynamicValueType GetPreferDynamicValue();
86 void SetPreferDynamicValue(lldb::DynamicValueType use_dynamic);
88 bool GetPreferSyntheticValue();
90 void SetPreferSyntheticValue(bool use_synthetic);
96 bool IsSyntheticChildrenGenerated();
98 void SetSyntheticChildrenGenerated(bool);
100 const char *GetLocation();
102 // Deprecated - use the one that takes SBError&
103 bool SetValueFromCString(const char *value_str);
105 bool SetValueFromCString(const char *value_str, lldb::SBError &error);
107 lldb::SBTypeFormat GetTypeFormat();
109 lldb::SBTypeSummary GetTypeSummary();
111 lldb::SBTypeFilter GetTypeFilter();
113 lldb::SBTypeSynthetic GetTypeSynthetic();
115 lldb::SBValue GetChildAtIndex(uint32_t idx);
117 lldb::SBValue CreateChildAtOffset(const char *name, uint32_t offset,
120 // Deprecated - use the expression evaluator to perform type casting
121 lldb::SBValue Cast(lldb::SBType type);
123 lldb::SBValue CreateValueFromExpression(const char *name,
124 const char *expression);
126 lldb::SBValue CreateValueFromExpression(const char *name,
127 const char *expression,
128 SBExpressionOptions &options);
130 lldb::SBValue CreateValueFromAddress(const char *name, lldb::addr_t address,
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,
138 /// Get a child value by index from a value.
140 /// Structs, unions, classes, arrays and pointers have child
141 /// values that can be access by index.
143 /// Structs and unions access child members using a zero based index
144 /// for each child member. For
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.
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).
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.
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
176 /// The index of the child value to get
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.
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
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);
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);
198 // Matches child members of this object and child members of any base
200 lldb::SBValue GetChildMemberWithName(const char *name);
202 // Matches child members of this object and child members of any base
204 lldb::SBValue GetChildMemberWithName(const char *name,
205 lldb::DynamicValueType use_dynamic);
207 // Expands nested expressions like .a->b[0].c[1]->d
208 lldb::SBValue GetValueForExpressionPath(const char *expr_path);
210 lldb::SBValue AddressOf();
212 lldb::addr_t GetLoadAddress();
214 lldb::SBAddress GetAddress();
216 /// Get an SBData wrapping what this SBValue points to.
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.
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
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.
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);
237 /// Get an SBData wrapping the contents of this SBValue.
239 /// This method will read the contents of this object in memory
240 /// and copy them into an SBData for future use.
243 /// An SBData with the contents of this SBValue, on success.
244 /// An empty SBData otherwise.
245 lldb::SBData GetData();
247 bool SetData(lldb::SBData &data, lldb::SBError &error);
249 lldb::SBDeclaration GetDeclaration();
251 /// Find out if a SBValue might have children.
253 /// This call is much more efficient than GetNumChildren() as it
254 /// doesn't need to complete the underlying type. This is designed
255 /// to be used in a UI environment in order to detect if the
256 /// disclosure triangle should be displayed or not.
258 /// This function returns true for class, union, structure,
259 /// pointers, references, arrays and more. Again, it does so without
260 /// doing any expensive type completion.
263 /// Returns \b true if the SBValue might have children, or \b
265 bool MightHaveChildren();
267 bool IsRuntimeSupportValue();
269 uint32_t GetNumChildren();
271 uint32_t GetNumChildren(uint32_t max);
273 void *GetOpaqueType();
275 lldb::SBTarget GetTarget();
277 lldb::SBProcess GetProcess();
279 lldb::SBThread GetThread();
281 lldb::SBFrame GetFrame();
283 lldb::SBValue Dereference();
285 // Deprecated - please use GetType().IsPointerType() instead.
286 bool TypeIsPointerType();
288 lldb::SBType GetType();
290 lldb::SBValue Persist();
292 bool GetDescription(lldb::SBStream &description);
294 bool GetExpressionPath(lldb::SBStream &description);
296 bool GetExpressionPath(lldb::SBStream &description,
297 bool qualify_cxx_base_classes);
299 lldb::SBValue EvaluateExpression(const char *expr) const;
300 lldb::SBValue EvaluateExpression(const char *expr,
301 const SBExpressionOptions &options) const;
302 lldb::SBValue EvaluateExpression(const char *expr,
303 const SBExpressionOptions &options,
304 const char *name) const;
306 SBValue(const lldb::ValueObjectSP &value_sp);
308 /// Watch this value if it resides in memory.
310 /// Sets a watchpoint on the value.
312 /// \param[in] resolve_location
313 /// Resolve the location of this value once and watch its address.
314 /// This value must currently be set to \b true as watching all
315 /// locations of a variable or a variable path is not yet supported,
316 /// though we plan to support it in the future.
319 /// Stop when this value is accessed.
322 /// Stop when this value is modified
324 /// \param[out] error
325 /// An error object. Contains the reason if there is some failure.
328 /// An SBWatchpoint object. This object might not be valid upon
329 /// return due to a value not being contained in memory, too
330 /// large, or watchpoint resources are not available or all in
332 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write,
335 // Backward compatibility fix in the interim.
336 lldb::SBWatchpoint Watch(bool resolve_location, bool read, bool write);
338 /// Watch this value that this value points to in memory
340 /// Sets a watchpoint on the value.
342 /// \param[in] resolve_location
343 /// Resolve the location of this value once and watch its address.
344 /// This value must currently be set to \b true as watching all
345 /// locations of a variable or a variable path is not yet supported,
346 /// though we plan to support it in the future.
349 /// Stop when this value is accessed.
352 /// Stop when this value is modified
354 /// \param[out] error
355 /// An error object. Contains the reason if there is some failure.
358 /// An SBWatchpoint object. This object might not be valid upon
359 /// return due to a value not being contained in memory, too
360 /// large, or watchpoint resources are not available or all in
362 lldb::SBWatchpoint WatchPointee(bool resolve_location, bool read, bool write,
365 /// Same as the protected version of GetSP that takes a locker, except that we
367 /// locker locally in the function. Since the Target API mutex is recursive,
369 /// StopLocker is a read lock, you can call this function even if you are
371 /// holding the two above-mentioned locks.
374 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
375 /// can cons up, in accordance with the SBValue's settings.
376 lldb::ValueObjectSP GetSP() const;
379 friend class SBBlock;
380 friend class SBFrame;
381 friend class SBTarget;
382 friend class SBThread;
383 friend class SBValueList;
385 /// Get the appropriate ValueObjectSP from this SBValue, consulting the
386 /// use_dynamic and use_synthetic options passed in to SetSP when the
387 /// SBValue's contents were set. Since this often requires examining memory,
388 /// and maybe even running code, it needs to acquire the Target API and
389 /// Process StopLock.
390 /// Those are held in an opaque class ValueLocker which is currently local to
392 /// So you don't have to get these yourself just default construct a
393 /// ValueLocker, and pass it into this.
394 /// If we need to make a ValueLocker and use it in some other .cpp file, we'll
395 /// have to move it to
396 /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so
399 /// \param[in] value_locker
400 /// An object that will hold the Target API, and Process RunLocks, and
401 /// auto-destroy them when it goes out of scope. Currently this is only
406 /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
407 /// can cons up, in accordance with the SBValue's settings.
408 lldb::ValueObjectSP GetSP(ValueLocker &value_locker) const;
410 // these calls do the right thing WRT adjusting their settings according to
411 // the target's preferences
412 void SetSP(const lldb::ValueObjectSP &sp);
414 void SetSP(const lldb::ValueObjectSP &sp, bool use_synthetic);
416 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic);
418 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
421 void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic,
422 bool use_synthetic, const char *name);
425 typedef std::shared_ptr<ValueImpl> ValueImplSP;
426 ValueImplSP m_opaque_sp;
428 void SetSP(ValueImplSP impl_sp);
433 #endif // LLDB_SBValue_h_