aboutsummaryrefslogtreecommitdiff
path: root/include/lldb/API/SBValue.h
blob: 93b869ba9c5c4234532d654a35abc4a90f1d7f97 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
//===-- SBValue.h -----------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_SBValue_h_
#define LLDB_SBValue_h_

#include "lldb/API/SBData.h"
#include "lldb/API/SBDefines.h"
#include "lldb/API/SBType.h"

class ValueImpl;
class ValueLocker;

namespace lldb {

class SBValue
{
friend class ValueLocker;

public:
    SBValue ();

    SBValue (const lldb::SBValue &rhs);

    lldb::SBValue &
    operator =(const lldb::SBValue &rhs);
    
    ~SBValue ();

    bool
    IsValid();
    
    void
    Clear();
    
    SBError
    GetError();

    lldb::user_id_t
    GetID ();
    
    const char *
    GetName();

    const char *
    GetTypeName ();
    
    const char *
    GetDisplayTypeName ();

    size_t
    GetByteSize ();

    bool
    IsInScope ();

    lldb::Format
    GetFormat ();
    
    void
    SetFormat (lldb::Format format);

    const char *
    GetValue ();

    int64_t
    GetValueAsSigned (lldb::SBError& error, int64_t fail_value=0);
    
    uint64_t
    GetValueAsUnsigned (lldb::SBError& error, uint64_t fail_value=0);
    
    int64_t
    GetValueAsSigned(int64_t fail_value=0);
    
    uint64_t
    GetValueAsUnsigned(uint64_t fail_value=0);

    ValueType
    GetValueType ();

    bool
    GetValueDidChange ();

    const char *
    GetSummary ();
    
    const char *
    GetObjectDescription ();
    
    lldb::SBValue
    GetDynamicValue (lldb::DynamicValueType use_dynamic);
    
    lldb::SBValue
    GetStaticValue ();
    
    lldb::SBValue
    GetNonSyntheticValue ();
    
    lldb::DynamicValueType
    GetPreferDynamicValue ();
    
    void
    SetPreferDynamicValue (lldb::DynamicValueType use_dynamic);
    
    bool
    GetPreferSyntheticValue ();
    
    void
    SetPreferSyntheticValue (bool use_synthetic);
    
    bool
    IsDynamic ();
    
    bool
    IsSynthetic ();

    const char *
    GetLocation ();

    // Deprecated - use the one that takes SBError&
    bool
    SetValueFromCString (const char *value_str);

    bool
    SetValueFromCString (const char *value_str, lldb::SBError& error);
    
    lldb::SBTypeFormat
    GetTypeFormat ();
    
#ifndef LLDB_DISABLE_PYTHON
    lldb::SBTypeSummary
    GetTypeSummary ();
#endif

    lldb::SBTypeFilter
    GetTypeFilter ();
    
#ifndef LLDB_DISABLE_PYTHON
    lldb::SBTypeSynthetic
    GetTypeSynthetic ();
#endif

    lldb::SBValue
    GetChildAtIndex (uint32_t idx);
    
    lldb::SBValue
    CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type);
    
    lldb::SBValue
    Cast (lldb::SBType type);
    
    lldb::SBValue
    CreateValueFromExpression (const char *name, const char* expression);
    
    lldb::SBValue
    CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options);
    
    lldb::SBValue
    CreateValueFromAddress (const char* name, 
                            lldb::addr_t address, 
                            lldb::SBType type);
    
    // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf()
    // on the return of this call all return invalid
    lldb::SBValue
    CreateValueFromData (const char* name,
                         lldb::SBData data,
                         lldb::SBType type);

    //------------------------------------------------------------------
    /// Get a child value by index from a value.
    ///
    /// Structs, unions, classes, arrays and pointers have child
    /// values that can be access by index. 
    ///
    /// Structs and unions access child members using a zero based index
    /// for each child member. For
    /// 
    /// Classes reserve the first indexes for base classes that have 
    /// members (empty base classes are omitted), and all members of the
    /// current class will then follow the base classes. 
    ///
    /// Pointers differ depending on what they point to. If the pointer
    /// points to a simple type, the child at index zero
    /// is the only child value available, unless \a synthetic_allowed 
    /// is \b true, in which case the pointer will be used as an array
    /// and can create 'synthetic' child values using positive or 
    /// negative indexes. If the pointer points to an aggregate type 
    /// (an array, class, union, struct), then the pointee is 
    /// transparently skipped and any children are going to be the indexes
    /// of the child values within the aggregate type. For example if
    /// we have a 'Point' type and we have a SBValue that contains a
    /// pointer to a 'Point' type, then the child at index zero will be
    /// the 'x' member, and the child at index 1 will be the 'y' member
    /// (the child at index zero won't be a 'Point' instance).
    /// 
    /// Arrays have a preset number of children that can be accessed by
    /// index and will returns invalid child values for indexes that are
    /// out of bounds unless the \a synthetic_allowed is \b true. In this
    /// case the array can create 'synthetic' child values for indexes 
    /// that aren't in the array bounds using positive or negative 
    /// indexes.
    ///
    /// @param[in] idx
    ///     The index of the child value to get
    ///
    /// @param[in] use_dynamic
    ///     An enumeration that specifies whether to get dynamic values,
    ///     and also if the target can be run to figure out the dynamic
    ///     type of the child value.
    ///
    /// @param[in] synthetic_allowed
    ///     If \b true, then allow child values to be created by index
    ///     for pointers and arrays for indexes that normally wouldn't
    ///     be allowed.
    ///
    /// @return
    ///     A new SBValue object that represents the child member value.
    //------------------------------------------------------------------
    lldb::SBValue
    GetChildAtIndex (uint32_t idx, 
                     lldb::DynamicValueType use_dynamic,
                     bool can_create_synthetic);

    // Matches children of this object only and will match base classes and
    // member names if this is a clang typed object.
    uint32_t
    GetIndexOfChildWithName (const char *name);

    // Matches child members of this object and child members of any base
    // classes.
    lldb::SBValue
    GetChildMemberWithName (const char *name);

    // Matches child members of this object and child members of any base
    // classes.
    lldb::SBValue
    GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic);
    
    // Expands nested expressions like .a->b[0].c[1]->d
    lldb::SBValue
    GetValueForExpressionPath(const char* expr_path);
    
    lldb::SBValue
    AddressOf();
    
    lldb::addr_t
    GetLoadAddress();
    
    lldb::SBAddress
    GetAddress();

    //------------------------------------------------------------------
    /// Get an SBData wrapping what this SBValue points to.
    ///
    /// This method will dereference the current SBValue, if its
    /// data type is a T* or T[], and extract item_count elements
    /// of type T from it, copying their contents in an SBData. 
    ///
    /// @param[in] item_idx
    ///     The index of the first item to retrieve. For an array
    ///     this is equivalent to array[item_idx], for a pointer
    ///     to *(pointer + item_idx). In either case, the measurement
    ///     unit for item_idx is the sizeof(T) rather than the byte
    ///
    /// @param[in] item_count
    ///     How many items should be copied into the output. By default
    ///     only one item is copied, but more can be asked for.
    ///
    /// @return
    ///     An SBData with the contents of the copied items, on success.
    ///     An empty SBData otherwise.
    //------------------------------------------------------------------
    lldb::SBData
    GetPointeeData (uint32_t item_idx = 0,
                    uint32_t item_count = 1);
    
    //------------------------------------------------------------------
    /// Get an SBData wrapping the contents of this SBValue.
    ///
    /// This method will read the contents of this object in memory
    /// and copy them into an SBData for future use. 
    ///
    /// @return
    ///     An SBData with the contents of this SBValue, on success.
    ///     An empty SBData otherwise.
    //------------------------------------------------------------------
    lldb::SBData
    GetData ();
    
    bool
    SetData (lldb::SBData &data, lldb::SBError& error);
    
    lldb::SBDeclaration
    GetDeclaration ();
    
    //------------------------------------------------------------------
    /// Find out if a SBValue might have children.
    ///
    /// This call is much more efficient than GetNumChildren() as it
    /// doesn't need to complete the underlying type. This is designed
    /// to be used in a UI environment in order to detect if the
    /// disclosure triangle should be displayed or not.
    ///
    /// This function returns true for class, union, structure,
    /// pointers, references, arrays and more. Again, it does so without
    /// doing any expensive type completion.
    ///
    /// @return
    ///     Returns \b true if the SBValue might have children, or \b
    ///     false otherwise.
    //------------------------------------------------------------------
    bool
    MightHaveChildren ();

    uint32_t
    GetNumChildren ();

    void *
    GetOpaqueType();

    lldb::SBTarget
    GetTarget();
    
    lldb::SBProcess
    GetProcess();
    
    lldb::SBThread
    GetThread();

    lldb::SBFrame
    GetFrame();
    
    lldb::SBValue
    Dereference ();

    bool
    TypeIsPointerType ();
    
    lldb::SBType
    GetType();

    bool
    GetDescription (lldb::SBStream &description);

    bool
    GetExpressionPath (lldb::SBStream &description);
    
    bool
    GetExpressionPath (lldb::SBStream &description, 
                       bool qualify_cxx_base_classes);

    SBValue (const lldb::ValueObjectSP &value_sp);

    //------------------------------------------------------------------
    /// Watch this value if it resides in memory.
    ///
    /// Sets a watchpoint on the value.
    ///
    /// @param[in] resolve_location
    ///     Resolve the location of this value once and watch its address.
    ///     This value must currently be set to \b true as watching all
    ///     locations of a variable or a variable path is not yet supported,
    ///     though we plan to support it in the future.
    ///
    /// @param[in] read
    ///     Stop when this value is accessed.
    ///
    /// @param[in] write
    ///     Stop when this value is modified
    ///
    /// @param[out]
    ///     An error object. Contains the reason if there is some failure.
    ///
    /// @return
    ///     An SBWatchpoint object. This object might not be valid upon
    ///     return due to a value not being contained in memory, too 
    ///     large, or watchpoint resources are not available or all in
    ///     use.
    //------------------------------------------------------------------
    lldb::SBWatchpoint
    Watch (bool resolve_location, bool read, bool write, SBError &error);

    // Backward compatibility fix in the interim.
    lldb::SBWatchpoint
    Watch (bool resolve_location, bool read, bool write);

    //------------------------------------------------------------------
    /// Watch this value that this value points to in memory
    ///
    /// Sets a watchpoint on the value.
    ///
    /// @param[in] resolve_location
    ///     Resolve the location of this value once and watch its address.
    ///     This value must currently be set to \b true as watching all
    ///     locations of a variable or a variable path is not yet supported,
    ///     though we plan to support it in the future.
    ///
    /// @param[in] read
    ///     Stop when this value is accessed.
    ///
    /// @param[in] write
    ///     Stop when this value is modified
    ///
    /// @param[out]
    ///     An error object. Contains the reason if there is some failure.
    ///
    /// @return
    ///     An SBWatchpoint object. This object might not be valid upon
    ///     return due to a value not being contained in memory, too 
    ///     large, or watchpoint resources are not available or all in
    ///     use.
    //------------------------------------------------------------------
    lldb::SBWatchpoint
    WatchPointee (bool resolve_location, bool read, bool write, SBError &error);

    //------------------------------------------------------------------
    /// Same as the protected version of GetSP that takes a locker, except that we make the
    /// locker locally in the function.  Since the Target API mutex is recursive, and the
    /// StopLocker is a read lock, you can call this function even if you are already
    /// holding the two above-mentioned locks.
    ///
    /// @return
    ///     A ValueObjectSP of the best kind (static, dynamic or synthetic) we
    ///     can cons up, in accordance with the SBValue's settings.
    //------------------------------------------------------------------
    lldb::ValueObjectSP
    GetSP () const;

protected:
    friend class SBBlock;
    friend class SBFrame;
    friend class SBTarget;
    friend class SBThread;
    friend class SBValueList;

    //------------------------------------------------------------------
    /// Get the appropriate ValueObjectSP from this SBValue, consulting the
    /// use_dynamic and use_synthetic options passed in to SetSP when the
    /// SBValue's contents were set.  Since this often requires examining memory,
    /// and maybe even running code, it needs to acquire the Target API and Process StopLock.
    /// Those are held in an opaque class ValueLocker which is currently local to SBValue.cpp.
    /// So you don't have to get these yourself just default construct a ValueLocker, and pass it into this.
    /// If we need to make a ValueLocker and use it in some other .cpp file, we'll have to move it to
    /// ValueObject.h/cpp or somewhere else convenient.  We haven't needed to so far.
    ///
    /// @param[in] value_locker
    ///     An object that will hold the Target API, and Process RunLocks, and
    ///     auto-destroy them when it goes out of scope.  Currently this is only useful in
    ///     SBValue.cpp.
    ///
    /// @return
    ///     A ValueObjectSP of the best kind (static, dynamic or synthetic) we
    ///     can cons up, in accordance with the SBValue's settings.
    //------------------------------------------------------------------
    lldb::ValueObjectSP
    GetSP (ValueLocker &value_locker) const;
    
    // these calls do the right thing WRT adjusting their settings according to the target's preferences
    void
    SetSP (const lldb::ValueObjectSP &sp);

    void
    SetSP (const lldb::ValueObjectSP &sp, bool use_synthetic);
    
    void
    SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic);

    void
    SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic);
    
    void
    SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic, const char *name);
    
private:
    typedef std::shared_ptr<ValueImpl> ValueImplSP;
    ValueImplSP m_opaque_sp;
    
    void
    SetSP (ValueImplSP impl_sp);
};

} // namespace lldb

#endif  // LLDB_SBValue_h_