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 | |
16 | class ValueImpl; |
17 | class ValueLocker; |
18 | |
19 | namespace lldb_private { |
20 | namespace python { |
21 | class SWIGBridge; |
22 | } |
23 | } // namespace lldb_private |
24 | |
25 | namespace lldb { |
26 | |
27 | class LLDB_API SBValue { |
28 | public: |
29 | SBValue(); |
30 | |
31 | SBValue(const lldb::SBValue &rhs); |
32 | |
33 | lldb::SBValue &operator=(const lldb::SBValue &rhs); |
34 | |
35 | ~SBValue(); |
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, |
80 | lldb::SBTypeSummaryOptions &options); |
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 | |
377 | /// If this value represents a C++ class that has a vtable, return an value |
378 | /// that represents the virtual function table. |
379 | /// |
380 | /// SBValue::GetError() will be in the success state if this value represents |
381 | /// a C++ class with a vtable, or an appropriate error describing that the |
382 | /// object isn't a C++ class with a vtable or not a C++ class. |
383 | /// |
384 | /// SBValue::GetName() will be the demangled symbol name for the virtual |
385 | /// function table like "vtable for <classname>". |
386 | /// |
387 | /// SBValue::GetValue() will be the address of the first vtable entry if the |
388 | /// current SBValue is a class with a vtable, or nothing the current SBValue |
389 | /// is not a C++ class or not a C++ class that has a vtable. |
390 | /// |
391 | /// SBValue::GetValueAtUnsigned(...) will return the address of the first |
392 | /// vtable entry. |
393 | /// |
394 | /// SBValue::GetLoadAddress() will return the address of the vtable pointer |
395 | /// found in the parent SBValue. |
396 | /// |
397 | /// SBValue::GetNumChildren() will return the number of virtual function |
398 | /// pointers in the vtable, or zero on error. |
399 | /// |
400 | /// SBValue::GetChildAtIndex(...) will return each virtual function pointer |
401 | /// as a SBValue object. |
402 | /// |
403 | /// The child SBValue objects will have the following values: |
404 | /// |
405 | /// SBValue::GetError() will indicate success if the vtable entry was |
406 | /// successfully read from memory, or an error if not. |
407 | /// |
408 | /// SBValue::GetName() will be the vtable function index in the form "[%u]" |
409 | /// where %u is the index. |
410 | /// |
411 | /// SBValue::GetValue() will be the virtual function pointer value as a |
412 | /// string. |
413 | /// |
414 | /// SBValue::GetValueAtUnsigned(...) will return the virtual function |
415 | /// pointer value. |
416 | /// |
417 | /// SBValue::GetLoadAddress() will return the address of the virtual function |
418 | /// pointer. |
419 | /// |
420 | /// SBValue::GetNumChildren() returns 0 |
421 | lldb::SBValue GetVTable(); |
422 | |
423 | protected: |
424 | friend class SBBlock; |
425 | friend class SBFrame; |
426 | friend class SBModule; |
427 | friend class SBTarget; |
428 | friend class SBThread; |
429 | friend class SBTypeSummary; |
430 | friend class SBValueList; |
431 | |
432 | friend class lldb_private::python::SWIGBridge; |
433 | |
434 | SBValue(const lldb::ValueObjectSP &value_sp); |
435 | |
436 | /// Same as the protected version of GetSP that takes a locker, except that we |
437 | /// make the |
438 | /// locker locally in the function. Since the Target API mutex is recursive, |
439 | /// and the |
440 | /// StopLocker is a read lock, you can call this function even if you are |
441 | /// already |
442 | /// holding the two above-mentioned locks. |
443 | /// |
444 | /// \return |
445 | /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we |
446 | /// can cons up, in accordance with the SBValue's settings. |
447 | lldb::ValueObjectSP GetSP() const; |
448 | |
449 | /// Get the appropriate ValueObjectSP from this SBValue, consulting the |
450 | /// use_dynamic and use_synthetic options passed in to SetSP when the |
451 | /// SBValue's contents were set. Since this often requires examining memory, |
452 | /// and maybe even running code, it needs to acquire the Target API and |
453 | /// Process StopLock. |
454 | /// Those are held in an opaque class ValueLocker which is currently local to |
455 | /// SBValue.cpp. |
456 | /// So you don't have to get these yourself just default construct a |
457 | /// ValueLocker, and pass it into this. |
458 | /// If we need to make a ValueLocker and use it in some other .cpp file, we'll |
459 | /// have to move it to |
460 | /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so |
461 | /// far. |
462 | /// |
463 | /// \param[in] value_locker |
464 | /// An object that will hold the Target API, and Process RunLocks, and |
465 | /// auto-destroy them when it goes out of scope. Currently this is only |
466 | /// useful in |
467 | /// SBValue.cpp. |
468 | /// |
469 | /// \return |
470 | /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we |
471 | /// can cons up, in accordance with the SBValue's settings. |
472 | lldb::ValueObjectSP GetSP(ValueLocker &value_locker) const; |
473 | |
474 | // these calls do the right thing WRT adjusting their settings according to |
475 | // the target's preferences |
476 | void SetSP(const lldb::ValueObjectSP &sp); |
477 | |
478 | void SetSP(const lldb::ValueObjectSP &sp, bool use_synthetic); |
479 | |
480 | void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic); |
481 | |
482 | void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, |
483 | bool use_synthetic); |
484 | |
485 | void SetSP(const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, |
486 | bool use_synthetic, const char *name); |
487 | |
488 | private: |
489 | typedef std::shared_ptr<ValueImpl> ValueImplSP; |
490 | ValueImplSP m_opaque_sp; |
491 | |
492 | void SetSP(ValueImplSP impl_sp); |
493 | }; |
494 | |
495 | } // namespace lldb |
496 | |
497 | #endif // LLDB_API_SBVALUE_H |
498 | |