LLDB API Documentation

- Main Page
- Namespaces
- Classes
- Files

- File List

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