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