SBTarget.h revision ef1f690aa23e81a14654d4a6fe9df7810f4eda06
1//===-- SBTarget.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_SBTarget_h_ 11#define LLDB_SBTarget_h_ 12 13#include "lldb/API/SBDefines.h" 14#include "lldb/API/SBAddress.h" 15#include "lldb/API/SBBroadcaster.h" 16#include "lldb/API/SBFileSpec.h" 17#include "lldb/API/SBFileSpecList.h" 18#include "lldb/API/SBType.h" 19#include "lldb/API/SBWatchpoint.h" 20 21namespace lldb { 22 23class SBBreakpoint; 24 25class SBTarget 26{ 27public: 28 //------------------------------------------------------------------ 29 // Broadcaster bits. 30 //------------------------------------------------------------------ 31 enum 32 { 33 eBroadcastBitBreakpointChanged = (1 << 0), 34 eBroadcastBitModulesLoaded = (1 << 1), 35 eBroadcastBitModulesUnloaded = (1 << 2) 36 }; 37 38 //------------------------------------------------------------------ 39 // Constructors 40 //------------------------------------------------------------------ 41 SBTarget (); 42 43 SBTarget (const lldb::SBTarget& rhs); 44 45#ifndef SWIG 46 const lldb::SBTarget& 47 operator = (const lldb::SBTarget& rhs); 48#endif 49 50 //------------------------------------------------------------------ 51 // Destructor 52 //------------------------------------------------------------------ 53 ~SBTarget(); 54 55 bool 56 IsValid() const; 57 58 lldb::SBProcess 59 GetProcess (); 60 61 //------------------------------------------------------------------ 62 /// Launch a new process. 63 /// 64 /// Launch a new process by spawning a new process using the 65 /// target object's executable module's file as the file to launch. 66 /// Arguments are given in \a argv, and the environment variables 67 /// are in \a envp. Standard input and output files can be 68 /// optionally re-directed to \a stdin_path, \a stdout_path, and 69 /// \a stderr_path. 70 /// 71 /// @param[in] listener 72 /// An optional listener that will receive all process events. 73 /// If \a listener is valid then \a listener will listen to all 74 /// process events. If not valid, then this target's debugger 75 /// (SBTarget::GetDebugger()) will listen to all process events. 76 /// 77 /// @param[in] argv 78 /// The argument array. 79 /// 80 /// @param[in] envp 81 /// The environment array. 82 /// 83 /// @param[in] launch_flags 84 /// Flags to modify the launch (@see lldb::LaunchFlags) 85 /// 86 /// @param[in] stdin_path 87 /// The path to use when re-directing the STDIN of the new 88 /// process. If all stdXX_path arguments are NULL, a pseudo 89 /// terminal will be used. 90 /// 91 /// @param[in] stdout_path 92 /// The path to use when re-directing the STDOUT of the new 93 /// process. If all stdXX_path arguments are NULL, a pseudo 94 /// terminal will be used. 95 /// 96 /// @param[in] stderr_path 97 /// The path to use when re-directing the STDERR of the new 98 /// process. If all stdXX_path arguments are NULL, a pseudo 99 /// terminal will be used. 100 /// 101 /// @param[in] working_directory 102 /// The working directory to have the child process run in 103 /// 104 /// @param[in] launch_flags 105 /// Some launch options specified by logical OR'ing 106 /// lldb::LaunchFlags enumeration values together. 107 /// 108 /// @param[in] stop_at_endtry 109 /// If false do not stop the inferior at the entry point. 110 /// 111 /// @param[out] 112 /// An error object. Contains the reason if there is some failure. 113 /// 114 /// @return 115 /// A process object for the newly created process. 116 //------------------------------------------------------------------ 117 lldb::SBProcess 118 Launch (SBListener &listener, 119 char const **argv, 120 char const **envp, 121 const char *stdin_path, 122 const char *stdout_path, 123 const char *stderr_path, 124 const char *working_directory, 125 uint32_t launch_flags, // See LaunchFlags 126 bool stop_at_entry, 127 lldb::SBError& error); 128 129 130 //------------------------------------------------------------------ 131 /// Launch a new process with sensible defaults. 132 /// 133 /// @param[in] argv 134 /// The argument array. 135 /// 136 /// @param[in] envp 137 /// The environment array. 138 /// 139 /// @param[in] working_directory 140 /// The working directory to have the child process run in 141 /// 142 /// Default: listener 143 /// Set to the target's debugger (SBTarget::GetDebugger()) 144 /// 145 /// Default: launch_flags 146 /// Empty launch flags 147 /// 148 /// Default: stdin_path 149 /// Default: stdout_path 150 /// Default: stderr_path 151 /// A pseudo terminal will be used. 152 /// 153 /// @return 154 /// A process object for the newly created process. 155 //------------------------------------------------------------------ 156 lldb::SBProcess 157 LaunchSimple (const char **argv, 158 const char **envp, 159 const char *working_directory); 160 161 //------------------------------------------------------------------ 162 /// Attach to process with pid. 163 /// 164 /// @param[in] listener 165 /// An optional listener that will receive all process events. 166 /// If \a listener is valid then \a listener will listen to all 167 /// process events. If not valid, then this target's debugger 168 /// (SBTarget::GetDebugger()) will listen to all process events. 169 /// 170 /// @param[in] pid 171 /// The process ID to attach to. 172 /// 173 /// @param[out] 174 /// An error explaining what went wrong if attach fails. 175 /// 176 /// @return 177 /// A process object for the attached process. 178 //------------------------------------------------------------------ 179 lldb::SBProcess 180 AttachToProcessWithID (SBListener &listener, 181 lldb::pid_t pid, 182 lldb::SBError& error); 183 184#if defined(__APPLE__) 185 // We need to keep this around for a build or two since Xcode links 186 // to the 32 bit version of this function. We will take it out soon. 187 lldb::SBProcess 188 AttachToProcessWithID (SBListener &listener, 189 ::pid_t pid, // 32 bit int process ID 190 lldb::SBError& error); // DEPRECATED 191#endif 192 //------------------------------------------------------------------ 193 /// Attach to process with name. 194 /// 195 /// @param[in] listener 196 /// An optional listener that will receive all process events. 197 /// If \a listener is valid then \a listener will listen to all 198 /// process events. If not valid, then this target's debugger 199 /// (SBTarget::GetDebugger()) will listen to all process events. 200 /// 201 /// @param[in] name 202 /// Basename of process to attach to. 203 /// 204 /// @param[in] wait_for 205 /// If true wait for a new instance of 'name' to be launched. 206 /// 207 /// @param[out] 208 /// An error explaining what went wrong if attach fails. 209 /// 210 /// @return 211 /// A process object for the attached process. 212 //------------------------------------------------------------------ 213 lldb::SBProcess 214 AttachToProcessWithName (SBListener &listener, 215 const char *name, 216 bool wait_for, 217 lldb::SBError& error); 218 219 //------------------------------------------------------------------ 220 /// Connect to a remote debug server with url. 221 /// 222 /// @param[in] listener 223 /// An optional listener that will receive all process events. 224 /// If \a listener is valid then \a listener will listen to all 225 /// process events. If not valid, then this target's debugger 226 /// (SBTarget::GetDebugger()) will listen to all process events. 227 /// 228 /// @param[in] url 229 /// The url to connect to, e.g., 'connect://localhost:12345'. 230 /// 231 /// @param[in] plugin_name 232 /// The plugin name to be used; can be NULL. 233 /// 234 /// @param[out] 235 /// An error explaining what went wrong if the connect fails. 236 /// 237 /// @return 238 /// A process object for the connected process. 239 //------------------------------------------------------------------ 240 lldb::SBProcess 241 ConnectRemote (SBListener &listener, 242 const char *url, 243 const char *plugin_name, 244 SBError& error); 245 246 lldb::SBFileSpec 247 GetExecutable (); 248 249 bool 250 AddModule (lldb::SBModule &module); 251 252 lldb::SBModule 253 AddModule (const char *path, 254 const char *triple, 255 const char *uuid); 256 257 uint32_t 258 GetNumModules () const; 259 260 lldb::SBModule 261 GetModuleAtIndex (uint32_t idx); 262 263 bool 264 RemoveModule (lldb::SBModule module); 265 266 lldb::SBDebugger 267 GetDebugger() const; 268 269 lldb::SBModule 270 FindModule (const lldb::SBFileSpec &file_spec); 271 272 //------------------------------------------------------------------ 273 /// Set the base load address for a module section. 274 /// 275 /// @param[in] section 276 /// The section whose base load address will be set within this 277 /// target. 278 /// 279 /// @param[in] section_base_addr 280 /// The base address for the section. 281 /// 282 /// @return 283 /// An error to indicate success, fail, and any reason for 284 /// failure. 285 //------------------------------------------------------------------ 286 lldb::SBError 287 SetSectionLoadAddress (lldb::SBSection section, 288 lldb::addr_t section_base_addr); 289 290 //------------------------------------------------------------------ 291 /// Clear the base load address for a module section. 292 /// 293 /// @param[in] section 294 /// The section whose base load address will be cleared within 295 /// this target. 296 /// 297 /// @return 298 /// An error to indicate success, fail, and any reason for 299 /// failure. 300 //------------------------------------------------------------------ 301 lldb::SBError 302 ClearSectionLoadAddress (lldb::SBSection section); 303 304 //------------------------------------------------------------------ 305 /// Slide all file addresses for all module sections so that \a module 306 /// appears to loaded at these slide addresses. 307 /// 308 /// When you need all sections within a module to be loaded at a 309 /// rigid slide from the addresses found in the module object file, 310 /// this function will allow you to easily and quickly slide all 311 /// module sections. 312 /// 313 /// @param[in] module 314 /// The module to load. 315 /// 316 /// @param[in] sections_offset 317 /// An offset that will be applied to all section file addresses 318 /// (the virtual addresses found in the object file itself). 319 /// 320 /// @return 321 /// An error to indicate success, fail, and any reason for 322 /// failure. 323 //------------------------------------------------------------------ 324 lldb::SBError 325 SetModuleLoadAddress (lldb::SBModule module, 326 int64_t sections_offset); 327 328 329 //------------------------------------------------------------------ 330 /// The the section base load addresses for all sections in a module. 331 /// 332 /// @param[in] module 333 /// The module to unload. 334 /// 335 /// @return 336 /// An error to indicate success, fail, and any reason for 337 /// failure. 338 //------------------------------------------------------------------ 339 lldb::SBError 340 ClearModuleLoadAddress (lldb::SBModule module); 341 342 //------------------------------------------------------------------ 343 /// Find functions by name. 344 /// 345 /// @param[in] name 346 /// The name of the function we are looking for. 347 /// 348 /// @param[in] name_type_mask 349 /// A logical OR of one or more FunctionNameType enum bits that 350 /// indicate what kind of names should be used when doing the 351 /// lookup. Bits include fully qualified names, base names, 352 /// C++ methods, or ObjC selectors. 353 /// See FunctionNameType for more details. 354 /// 355 /// @param[in] append 356 /// If true, any matches will be appended to \a sc_list, else 357 /// matches replace the contents of \a sc_list. 358 /// 359 /// @param[out] sc_list 360 /// A symbol context list that gets filled in with all of the 361 /// matches. 362 /// 363 /// @return 364 /// The number of matches added to \a sc_list. 365 //------------------------------------------------------------------ 366 uint32_t 367 FindFunctions (const char *name, 368 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 369 bool append, 370 lldb::SBSymbolContextList& sc_list); 371 372 //------------------------------------------------------------------ 373 /// Find global and static variables by name. 374 /// 375 /// @param[in] name 376 /// The name of the global or static variable we are looking 377 /// for. 378 /// 379 /// @param[in] max_matches 380 /// Allow the number of matches to be limited to \a max_matches. 381 /// 382 /// @return 383 /// A list of matched variables in an SBValueList. 384 //------------------------------------------------------------------ 385 lldb::SBValueList 386 FindGlobalVariables (const char *name, 387 uint32_t max_matches); 388 389 void 390 Clear (); 391 392 lldb::SBAddress 393 ResolveLoadAddress (lldb::addr_t vm_addr); 394 395 SBSymbolContext 396 ResolveSymbolContextForAddress (const SBAddress& addr, 397 uint32_t resolve_scope); 398 399 lldb::SBBreakpoint 400 BreakpointCreateByLocation (const char *file, uint32_t line); 401 402 lldb::SBBreakpoint 403 BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line); 404 405 lldb::SBBreakpoint 406 BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); 407 408 // This version uses name_type_mask = eFunctionNameTypeAuto 409 lldb::SBBreakpoint 410 BreakpointCreateByName (const char *symbol_name, 411 const SBFileSpecList &module_list, 412 const SBFileSpecList &comp_unit_list); 413 414 lldb::SBBreakpoint 415 BreakpointCreateByName (const char *symbol_name, 416 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 417 const SBFileSpecList &module_list, 418 const SBFileSpecList &comp_unit_list); 419 420 lldb::SBBreakpoint 421 BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL); 422 423 lldb::SBBreakpoint 424 BreakpointCreateByRegex (const char *symbol_name_regex, 425 const SBFileSpecList &module_list, 426 const SBFileSpecList &comp_unit_list); 427 428 lldb::SBBreakpoint 429 BreakpointCreateBySourceRegex (const char *source_regex, 430 const lldb::SBFileSpec &source_file, 431 const char *module_name = NULL); 432 433 lldb::SBBreakpoint 434 BreakpointCreateBySourceRegex (const char *source_regex, 435 const SBFileSpecList &module_list, 436 const lldb::SBFileSpecList &source_file); 437 438 lldb::SBBreakpoint 439 BreakpointCreateByAddress (addr_t address); 440 441 uint32_t 442 GetNumBreakpoints () const; 443 444 lldb::SBBreakpoint 445 GetBreakpointAtIndex (uint32_t idx) const; 446 447 bool 448 BreakpointDelete (break_id_t break_id); 449 450 lldb::SBBreakpoint 451 FindBreakpointByID (break_id_t break_id); 452 453 bool 454 EnableAllBreakpoints (); 455 456 bool 457 DisableAllBreakpoints (); 458 459 bool 460 DeleteAllBreakpoints (); 461 462 uint32_t 463 GetNumWatchpoints () const; 464 465 lldb::SBWatchpoint 466 GetWatchpointAtIndex (uint32_t idx) const; 467 468 bool 469 DeleteWatchpoint (lldb::watch_id_t watch_id); 470 471 lldb::SBWatchpoint 472 FindWatchpointByID (lldb::watch_id_t watch_id); 473 474 lldb::SBWatchpoint 475 WatchAddress (lldb::addr_t addr, size_t size, bool read, bool write); 476 477 bool 478 EnableAllWatchpoints (); 479 480 bool 481 DisableAllWatchpoints (); 482 483 bool 484 DeleteAllWatchpoints (); 485 486 lldb::SBBroadcaster 487 GetBroadcaster () const; 488 489 lldb::SBType 490 FindFirstType (const char* type); 491 492 lldb::SBTypeList 493 FindTypes (const char* type); 494 495 SBSourceManager 496 GetSourceManager(); 497 498 lldb::SBInstructionList 499 GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); 500 501 lldb::SBInstructionList 502 GetInstructions (lldb::addr_t base_addr, const void *buf, size_t size); 503 504#ifndef SWIG 505 bool 506 operator == (const lldb::SBTarget &rhs) const; 507 508 bool 509 operator != (const lldb::SBTarget &rhs) const; 510 511#endif 512 513 bool 514 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level); 515 516protected: 517 friend class SBAddress; 518 friend class SBDebugger; 519 friend class SBFunction; 520 friend class SBInstruction; 521 friend class SBModule; 522 friend class SBProcess; 523 friend class SBSourceManager; 524 friend class SBSymbol; 525 friend class SBValue; 526 527 //------------------------------------------------------------------ 528 // Constructors are private, use static Target::Create function to 529 // create an instance of this class. 530 //------------------------------------------------------------------ 531 532 SBTarget (const lldb::TargetSP& target_sp); 533 534 void 535 reset (const lldb::TargetSP& target_sp); 536 537 lldb_private::Target * 538 operator ->() const; 539 540 lldb_private::Target * 541 get() const; 542 543 const lldb::TargetSP & 544 get_sp () const; 545 546private: 547 //------------------------------------------------------------------ 548 // For Target only 549 //------------------------------------------------------------------ 550 551 lldb::TargetSP m_opaque_sp; 552}; 553 554} // namespace lldb 555 556#endif // LLDB_SBTarget_h_ 557