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