SBValue.h revision 47beabb1386be44e3f90dbc30a0b22c23b93a4dc
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 CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options); 141 142 lldb::SBValue 143 CreateValueFromAddress (const char* name, 144 lldb::addr_t address, 145 lldb::SBType type); 146 147 // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf() 148 // on the return of this call all return invalid 149 lldb::SBValue 150 CreateValueFromData (const char* name, 151 lldb::SBData data, 152 lldb::SBType type); 153 154 //------------------------------------------------------------------ 155 /// Get a child value by index from a value. 156 /// 157 /// Structs, unions, classes, arrays and and pointers have child 158 /// values that can be access by index. 159 /// 160 /// Structs and unions access child members using a zero based index 161 /// for each child member. For 162 /// 163 /// Classes reserve the first indexes for base classes that have 164 /// members (empty base classes are omitted), and all members of the 165 /// current class will then follow the base classes. 166 /// 167 /// Pointers differ depending on what they point to. If the pointer 168 /// points to a simple type, the child at index zero 169 /// is the only child value available, unless \a synthetic_allowed 170 /// is \b true, in which case the pointer will be used as an array 171 /// and can create 'synthetic' child values using positive or 172 /// negative indexes. If the pointer points to an aggregate type 173 /// (an array, class, union, struct), then the pointee is 174 /// transparently skipped and any children are going to be the indexes 175 /// of the child values within the aggregate type. For example if 176 /// we have a 'Point' type and we have a SBValue that contains a 177 /// pointer to a 'Point' type, then the child at index zero will be 178 /// the 'x' member, and the child at index 1 will be the 'y' member 179 /// (the child at index zero won't be a 'Point' instance). 180 /// 181 /// Arrays have a preset number of children that can be accessed by 182 /// index and will returns invalid child values for indexes that are 183 /// out of bounds unless the \a synthetic_allowed is \b true. In this 184 /// case the array can create 'synthetic' child values for indexes 185 /// that aren't in the array bounds using positive or negative 186 /// indexes. 187 /// 188 /// @param[in] idx 189 /// The index of the child value to get 190 /// 191 /// @param[in] use_dynamic 192 /// An enumeration that specifies wether to get dynamic values, 193 /// and also if the target can be run to figure out the dynamic 194 /// type of the child value. 195 /// 196 /// @param[in] synthetic_allowed 197 /// If \b true, then allow child values to be created by index 198 /// for pointers and arrays for indexes that normally wouldn't 199 /// be allowed. 200 /// 201 /// @return 202 /// A new SBValue object that represents the child member value. 203 //------------------------------------------------------------------ 204 lldb::SBValue 205 GetChildAtIndex (uint32_t idx, 206 lldb::DynamicValueType use_dynamic, 207 bool can_create_synthetic); 208 209 // Matches children of this object only and will match base classes and 210 // member names if this is a clang typed object. 211 uint32_t 212 GetIndexOfChildWithName (const char *name); 213 214 // Matches child members of this object and child members of any base 215 // classes. 216 lldb::SBValue 217 GetChildMemberWithName (const char *name); 218 219 // Matches child members of this object and child members of any base 220 // classes. 221 lldb::SBValue 222 GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic); 223 224 // Expands nested expressions like .a->b[0].c[1]->d 225 lldb::SBValue 226 GetValueForExpressionPath(const char* expr_path); 227 228 lldb::SBValue 229 AddressOf(); 230 231 lldb::addr_t 232 GetLoadAddress(); 233 234 lldb::SBAddress 235 GetAddress(); 236 237 //------------------------------------------------------------------ 238 /// Get an SBData wrapping what this SBValue points to. 239 /// 240 /// This method will dereference the current SBValue, if its 241 /// data type is a T* or T[], and extract item_count elements 242 /// of type T from it, copying their contents in an SBData. 243 /// 244 /// @param[in] item_idx 245 /// The index of the first item to retrieve. For an array 246 /// this is equivalent to array[item_idx], for a pointer 247 /// to *(pointer + item_idx). In either case, the measurement 248 /// unit for item_idx is the sizeof(T) rather than the byte 249 /// 250 /// @param[in] item_count 251 /// How many items should be copied into the output. By default 252 /// only one item is copied, but more can be asked for. 253 /// 254 /// @return 255 /// An SBData with the contents of the copied items, on success. 256 /// An empty SBData otherwise. 257 //------------------------------------------------------------------ 258 lldb::SBData 259 GetPointeeData (uint32_t item_idx = 0, 260 uint32_t item_count = 1); 261 262 //------------------------------------------------------------------ 263 /// Get an SBData wrapping the contents of this SBValue. 264 /// 265 /// This method will read the contents of this object in memory 266 /// and copy them into an SBData for future use. 267 /// 268 /// @return 269 /// An SBData with the contents of this SBValue, on success. 270 /// An empty SBData otherwise. 271 //------------------------------------------------------------------ 272 lldb::SBData 273 GetData (); 274 275 lldb::SBDeclaration 276 GetDeclaration (); 277 278 uint32_t 279 GetNumChildren (); 280 281 void * 282 GetOpaqueType(); 283 284 lldb::SBTarget 285 GetTarget(); 286 287 lldb::SBProcess 288 GetProcess(); 289 290 lldb::SBThread 291 GetThread(); 292 293 lldb::SBFrame 294 GetFrame(); 295 296 lldb::SBValue 297 Dereference (); 298 299 bool 300 TypeIsPointerType (); 301 302 lldb::SBType 303 GetType(); 304 305 bool 306 GetDescription (lldb::SBStream &description); 307 308 bool 309 GetExpressionPath (lldb::SBStream &description); 310 311 bool 312 GetExpressionPath (lldb::SBStream &description, 313 bool qualify_cxx_base_classes); 314 315 SBValue (const lldb::ValueObjectSP &value_sp); 316 317 //------------------------------------------------------------------ 318 /// Watch this value if it resides in memory. 319 /// 320 /// Sets a watchpoint on the value. 321 /// 322 /// @param[in] resolve_location 323 /// Resolve the location of this value once and watch its address. 324 /// This value must currently be set to \b true as watching all 325 /// locations of a variable or a variable path is not yet supported, 326 /// though we plan to support it in the future. 327 /// 328 /// @param[in] read 329 /// Stop when this value is accessed. 330 /// 331 /// @param[in] write 332 /// Stop when this value is modified 333 /// 334 /// @param[out] 335 /// An error object. Contains the reason if there is some failure. 336 /// 337 /// @return 338 /// An SBWatchpoint object. This object might not be valid upon 339 /// return due to a value not being contained in memory, too 340 /// large, or watchpoint resources are not available or all in 341 /// use. 342 //------------------------------------------------------------------ 343 lldb::SBWatchpoint 344 Watch (bool resolve_location, bool read, bool write, SBError &error); 345 346 // Backward compatibility fix in the interim. 347 lldb::SBWatchpoint 348 Watch (bool resolve_location, bool read, bool write); 349 350 //------------------------------------------------------------------ 351 /// Watch this value that this value points to in memory 352 /// 353 /// Sets a watchpoint on the value. 354 /// 355 /// @param[in] resolve_location 356 /// Resolve the location of this value once and watch its address. 357 /// This value must currently be set to \b true as watching all 358 /// locations of a variable or a variable path is not yet supported, 359 /// though we plan to support it in the future. 360 /// 361 /// @param[in] read 362 /// Stop when this value is accessed. 363 /// 364 /// @param[in] write 365 /// Stop when this value is modified 366 /// 367 /// @param[out] 368 /// An error object. Contains the reason if there is some failure. 369 /// 370 /// @return 371 /// An SBWatchpoint object. This object might not be valid upon 372 /// return due to a value not being contained in memory, too 373 /// large, or watchpoint resources are not available or all in 374 /// use. 375 //------------------------------------------------------------------ 376 lldb::SBWatchpoint 377 WatchPointee (bool resolve_location, bool read, bool write, SBError &error); 378 379 // this must be defined in the .h file because synthetic children as implemented in the core 380 // currently rely on being able to extract the SharedPointer out of an SBValue. if the implementation 381 // is deferred to the .cpp file instead of being inlined here, the platform will fail to link 382 // correctly. however, this is temporary till a better general solution is found. FIXME 383 lldb::ValueObjectSP& 384 get_sp() 385 { 386 return m_opaque_sp; 387 } 388 389protected: 390 friend class SBValueList; 391 friend class SBFrame; 392 friend class SBThread; 393 394 lldb::ValueObjectSP 395 GetSP () const; 396 397 // anyone who needs to set the value of the SP on this SBValue should rely on SetSP() exclusively 398 // since this function contains logic to "do the right thing" with regard to providing to the user 399 // a synthetic value when possible - in the future the same should automatically occur with 400 // dynamic values 401 void 402 SetSP (const lldb::ValueObjectSP &sp); 403 404private: 405 lldb::ValueObjectSP m_opaque_sp; 406}; 407 408} // namespace lldb 409 410#endif // LLDB_SBValue_h_ 411