SBValue.h revision ab8e00e51475b9148626bfdf99549b7ffc3d046d
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 bool 294 SetData (lldb::SBData &data, lldb::SBError& error); 295 296 lldb::SBDeclaration 297 GetDeclaration (); 298 299 //------------------------------------------------------------------ 300 /// Find out if a SBValue might have children. 301 /// 302 /// This call is much more efficient than GetNumChildren() as it 303 /// doesn't need to complete the underlying type. This is designed 304 /// to be used in a UI environment in order to detect if the 305 /// disclosure triangle should be displayed or not. 306 /// 307 /// This function returns true for class, union, structure, 308 /// pointers, references, arrays and more. Again, it does so without 309 /// doing any expensive type completion. 310 /// 311 /// @return 312 /// Returns \b true if the SBValue might have children, or \b 313 /// false otherwise. 314 //------------------------------------------------------------------ 315 bool 316 MightHaveChildren (); 317 318 uint32_t 319 GetNumChildren (); 320 321 void * 322 GetOpaqueType(); 323 324 lldb::SBTarget 325 GetTarget(); 326 327 lldb::SBProcess 328 GetProcess(); 329 330 lldb::SBThread 331 GetThread(); 332 333 lldb::SBFrame 334 GetFrame(); 335 336 lldb::SBValue 337 Dereference (); 338 339 bool 340 TypeIsPointerType (); 341 342 lldb::SBType 343 GetType(); 344 345 bool 346 GetDescription (lldb::SBStream &description); 347 348 bool 349 GetExpressionPath (lldb::SBStream &description); 350 351 bool 352 GetExpressionPath (lldb::SBStream &description, 353 bool qualify_cxx_base_classes); 354 355 SBValue (const lldb::ValueObjectSP &value_sp); 356 357 //------------------------------------------------------------------ 358 /// Watch this value if it resides in memory. 359 /// 360 /// Sets a watchpoint on the value. 361 /// 362 /// @param[in] resolve_location 363 /// Resolve the location of this value once and watch its address. 364 /// This value must currently be set to \b true as watching all 365 /// locations of a variable or a variable path is not yet supported, 366 /// though we plan to support it in the future. 367 /// 368 /// @param[in] read 369 /// Stop when this value is accessed. 370 /// 371 /// @param[in] write 372 /// Stop when this value is modified 373 /// 374 /// @param[out] 375 /// An error object. Contains the reason if there is some failure. 376 /// 377 /// @return 378 /// An SBWatchpoint object. This object might not be valid upon 379 /// return due to a value not being contained in memory, too 380 /// large, or watchpoint resources are not available or all in 381 /// use. 382 //------------------------------------------------------------------ 383 lldb::SBWatchpoint 384 Watch (bool resolve_location, bool read, bool write, SBError &error); 385 386 // Backward compatibility fix in the interim. 387 lldb::SBWatchpoint 388 Watch (bool resolve_location, bool read, bool write); 389 390 //------------------------------------------------------------------ 391 /// Watch this value that this value points to in memory 392 /// 393 /// Sets a watchpoint on the value. 394 /// 395 /// @param[in] resolve_location 396 /// Resolve the location of this value once and watch its address. 397 /// This value must currently be set to \b true as watching all 398 /// locations of a variable or a variable path is not yet supported, 399 /// though we plan to support it in the future. 400 /// 401 /// @param[in] read 402 /// Stop when this value is accessed. 403 /// 404 /// @param[in] write 405 /// Stop when this value is modified 406 /// 407 /// @param[out] 408 /// An error object. Contains the reason if there is some failure. 409 /// 410 /// @return 411 /// An SBWatchpoint object. This object might not be valid upon 412 /// return due to a value not being contained in memory, too 413 /// large, or watchpoint resources are not available or all in 414 /// use. 415 //------------------------------------------------------------------ 416 lldb::SBWatchpoint 417 WatchPointee (bool resolve_location, bool read, bool write, SBError &error); 418 419 lldb::ValueObjectSP 420 GetSP () const; 421 422protected: 423 friend class SBBlock; 424 friend class SBFrame; 425 friend class SBTarget; 426 friend class SBThread; 427 friend class SBValueList; 428 429 // these calls do the right thing WRT adjusting their settings according to the target's preferences 430 void 431 SetSP (const lldb::ValueObjectSP &sp); 432 433 void 434 SetSP (const lldb::ValueObjectSP &sp, bool use_synthetic); 435 436 void 437 SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic); 438 439 void 440 SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic); 441 442private: 443 typedef STD_SHARED_PTR(ValueImpl) ValueImplSP; 444 ValueImplSP m_opaque_sp; 445 446 void 447 SetSP (ValueImplSP impl_sp); 448}; 449 450} // namespace lldb 451 452#endif // LLDB_SBValue_h_ 453