SBTarget.h revision 4722b10307668368bf0f12fa6b8691e4f4cb5488
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 SBLaunchInfo 24{ 25public: 26 SBLaunchInfo (const char **argv); 27 28 uint32_t 29 GetUserID(); 30 31 uint32_t 32 GetGroupID(); 33 34 bool 35 UserIDIsValid (); 36 37 bool 38 GroupIDIsValid (); 39 40 void 41 SetUserID (uint32_t uid); 42 43 void 44 SetGroupID (uint32_t gid); 45 46 uint32_t 47 GetNumArguments (); 48 49 const char * 50 GetArgumentAtIndex (uint32_t idx); 51 52 void 53 SetArguments (const char **argv, bool append); 54 55 uint32_t 56 GetNumEnvironmentEntries (); 57 58 const char * 59 GetEnvironmentEntryAtIndex (uint32_t idx); 60 61 void 62 SetEnvironmentEntries (const char **envp, bool append); 63 64 void 65 Clear (); 66 67 const char * 68 GetWorkingDirectory () const; 69 70 void 71 SetWorkingDirectory (const char *working_dir); 72 73 uint32_t 74 GetLaunchFlags (); 75 76 void 77 SetLaunchFlags (uint32_t flags); 78 79 const char * 80 GetProcessPluginName (); 81 82 void 83 SetProcessPluginName (const char *plugin_name); 84 85 const char * 86 GetShell (); 87 88 void 89 SetShell (const char * path); 90 91 uint32_t 92 GetResumeCount (); 93 94 void 95 SetResumeCount (uint32_t c); 96 97 bool 98 AddCloseFileAction (int fd); 99 100 bool 101 AddDuplicateFileAction (int fd, int dup_fd); 102 103 bool 104 AddOpenFileAction (int fd, const char *path, bool read, bool write); 105 106 bool 107 AddSuppressFileAction (int fd, bool read, bool write); 108 109protected: 110 friend class SBTarget; 111 112 lldb_private::ProcessLaunchInfo & 113 ref () 114 { 115 return *m_opaque_sp; 116 } 117 118 ProcessLaunchInfoSP m_opaque_sp; 119}; 120 121class SBAttachInfo 122{ 123public: 124 SBAttachInfo (); 125 126 SBAttachInfo (lldb::pid_t pid); 127 128 SBAttachInfo (const char *path, bool wait_for); 129 130 SBAttachInfo (const SBAttachInfo &rhs); 131 132 SBAttachInfo & 133 operator = (const SBAttachInfo &rhs); 134 135 lldb::pid_t 136 GetProcessID (); 137 138 void 139 SetProcessID (lldb::pid_t pid); 140 141 void 142 SetExecutable (const char *path); 143 144 void 145 SetExecutable (lldb::SBFileSpec exe_file); 146 147 bool 148 GetWaitForLaunch (); 149 150 void 151 SetWaitForLaunch (bool b); 152 153 uint32_t 154 GetResumeCount (); 155 156 void 157 SetResumeCount (uint32_t c); 158 159 const char * 160 GetProcessPluginName (); 161 162 void 163 SetProcessPluginName (const char *plugin_name); 164 165 uint32_t 166 GetUserID(); 167 168 uint32_t 169 GetGroupID(); 170 171 bool 172 UserIDIsValid (); 173 174 bool 175 GroupIDIsValid (); 176 177 void 178 SetUserID (uint32_t uid); 179 180 void 181 SetGroupID (uint32_t gid); 182 183 uint32_t 184 GetEffectiveUserID(); 185 186 uint32_t 187 GetEffectiveGroupID(); 188 189 bool 190 EffectiveUserIDIsValid (); 191 192 bool 193 EffectiveGroupIDIsValid (); 194 195 void 196 SetEffectiveUserID (uint32_t uid); 197 198 void 199 SetEffectiveGroupID (uint32_t gid); 200 201 lldb::pid_t 202 GetParentProcessID (); 203 204 void 205 SetParentProcessID (lldb::pid_t pid); 206 207 bool 208 ParentProcessIDIsValid(); 209 210 211protected: 212 friend class SBTarget; 213 214 lldb_private::ProcessAttachInfo & 215 ref () 216 { 217 return *m_opaque_sp; 218 } 219 220 ProcessAttachInfoSP m_opaque_sp; 221}; 222 223class SBTarget 224{ 225public: 226 //------------------------------------------------------------------ 227 // Broadcaster bits. 228 //------------------------------------------------------------------ 229 enum 230 { 231 eBroadcastBitBreakpointChanged = (1 << 0), 232 eBroadcastBitModulesLoaded = (1 << 1), 233 eBroadcastBitModulesUnloaded = (1 << 2) 234 }; 235 236 //------------------------------------------------------------------ 237 // Constructors 238 //------------------------------------------------------------------ 239 SBTarget (); 240 241 SBTarget (const lldb::SBTarget& rhs); 242 243 const lldb::SBTarget& 244 operator = (const lldb::SBTarget& rhs); 245 246 //------------------------------------------------------------------ 247 // Destructor 248 //------------------------------------------------------------------ 249 ~SBTarget(); 250 251 bool 252 IsValid() const; 253 254 static const char * 255 GetBroadcasterClassName (); 256 257 lldb::SBProcess 258 GetProcess (); 259 260 //------------------------------------------------------------------ 261 /// Launch a new process. 262 /// 263 /// Launch a new process by spawning a new process using the 264 /// target object's executable module's file as the file to launch. 265 /// Arguments are given in \a argv, and the environment variables 266 /// are in \a envp. Standard input and output files can be 267 /// optionally re-directed to \a stdin_path, \a stdout_path, and 268 /// \a stderr_path. 269 /// 270 /// @param[in] listener 271 /// An optional listener that will receive all process events. 272 /// If \a listener is valid then \a listener will listen to all 273 /// process events. If not valid, then this target's debugger 274 /// (SBTarget::GetDebugger()) will listen to all process events. 275 /// 276 /// @param[in] argv 277 /// The argument array. 278 /// 279 /// @param[in] envp 280 /// The environment array. 281 /// 282 /// @param[in] launch_flags 283 /// Flags to modify the launch (@see lldb::LaunchFlags) 284 /// 285 /// @param[in] stdin_path 286 /// The path to use when re-directing the STDIN of the new 287 /// process. If all stdXX_path arguments are NULL, a pseudo 288 /// terminal will be used. 289 /// 290 /// @param[in] stdout_path 291 /// The path to use when re-directing the STDOUT of the new 292 /// process. If all stdXX_path arguments are NULL, a pseudo 293 /// terminal will be used. 294 /// 295 /// @param[in] stderr_path 296 /// The path to use when re-directing the STDERR of the new 297 /// process. If all stdXX_path arguments are NULL, a pseudo 298 /// terminal will be used. 299 /// 300 /// @param[in] working_directory 301 /// The working directory to have the child process run in 302 /// 303 /// @param[in] launch_flags 304 /// Some launch options specified by logical OR'ing 305 /// lldb::LaunchFlags enumeration values together. 306 /// 307 /// @param[in] stop_at_endtry 308 /// If false do not stop the inferior at the entry point. 309 /// 310 /// @param[out] 311 /// An error object. Contains the reason if there is some failure. 312 /// 313 /// @return 314 /// A process object for the newly created process. 315 //------------------------------------------------------------------ 316 lldb::SBProcess 317 Launch (SBListener &listener, 318 char const **argv, 319 char const **envp, 320 const char *stdin_path, 321 const char *stdout_path, 322 const char *stderr_path, 323 const char *working_directory, 324 uint32_t launch_flags, // See LaunchFlags 325 bool stop_at_entry, 326 lldb::SBError& error); 327 328 329 //------------------------------------------------------------------ 330 /// Launch a new process with sensible defaults. 331 /// 332 /// @param[in] argv 333 /// The argument array. 334 /// 335 /// @param[in] envp 336 /// The environment array. 337 /// 338 /// @param[in] working_directory 339 /// The working directory to have the child process run in 340 /// 341 /// Default: listener 342 /// Set to the target's debugger (SBTarget::GetDebugger()) 343 /// 344 /// Default: launch_flags 345 /// Empty launch flags 346 /// 347 /// Default: stdin_path 348 /// Default: stdout_path 349 /// Default: stderr_path 350 /// A pseudo terminal will be used. 351 /// 352 /// @return 353 /// A process object for the newly created process. 354 //------------------------------------------------------------------ 355 SBProcess 356 LaunchSimple (const char **argv, 357 const char **envp, 358 const char *working_directory); 359 360 SBProcess 361 Launch (SBLaunchInfo &launch_info, SBError& error); 362 363 SBProcess 364 Attach (SBAttachInfo &attach_info, SBError& error); 365 366 //------------------------------------------------------------------ 367 /// Attach to process with pid. 368 /// 369 /// @param[in] listener 370 /// An optional listener that will receive all process events. 371 /// If \a listener is valid then \a listener will listen to all 372 /// process events. If not valid, then this target's debugger 373 /// (SBTarget::GetDebugger()) will listen to all process events. 374 /// 375 /// @param[in] pid 376 /// The process ID to attach to. 377 /// 378 /// @param[out] 379 /// An error explaining what went wrong if attach fails. 380 /// 381 /// @return 382 /// A process object for the attached process. 383 //------------------------------------------------------------------ 384 lldb::SBProcess 385 AttachToProcessWithID (SBListener &listener, 386 lldb::pid_t pid, 387 lldb::SBError& error); 388 389#if defined(__APPLE__) 390 // We need to keep this around for a build or two since Xcode links 391 // to the 32 bit version of this function. We will take it out soon. 392 lldb::SBProcess 393 AttachToProcessWithID (SBListener &listener, 394 ::pid_t pid, // 32 bit int process ID 395 lldb::SBError& error); // DEPRECATED 396#endif 397 //------------------------------------------------------------------ 398 /// Attach to process with name. 399 /// 400 /// @param[in] listener 401 /// An optional listener that will receive all process events. 402 /// If \a listener is valid then \a listener will listen to all 403 /// process events. If not valid, then this target's debugger 404 /// (SBTarget::GetDebugger()) will listen to all process events. 405 /// 406 /// @param[in] name 407 /// Basename of process to attach to. 408 /// 409 /// @param[in] wait_for 410 /// If true wait for a new instance of 'name' to be launched. 411 /// 412 /// @param[out] 413 /// An error explaining what went wrong if attach fails. 414 /// 415 /// @return 416 /// A process object for the attached process. 417 //------------------------------------------------------------------ 418 lldb::SBProcess 419 AttachToProcessWithName (SBListener &listener, 420 const char *name, 421 bool wait_for, 422 lldb::SBError& error); 423 424 //------------------------------------------------------------------ 425 /// Connect to a remote debug server with url. 426 /// 427 /// @param[in] listener 428 /// An optional listener that will receive all process events. 429 /// If \a listener is valid then \a listener will listen to all 430 /// process events. If not valid, then this target's debugger 431 /// (SBTarget::GetDebugger()) will listen to all process events. 432 /// 433 /// @param[in] url 434 /// The url to connect to, e.g., 'connect://localhost:12345'. 435 /// 436 /// @param[in] plugin_name 437 /// The plugin name to be used; can be NULL. 438 /// 439 /// @param[out] 440 /// An error explaining what went wrong if the connect fails. 441 /// 442 /// @return 443 /// A process object for the connected process. 444 //------------------------------------------------------------------ 445 lldb::SBProcess 446 ConnectRemote (SBListener &listener, 447 const char *url, 448 const char *plugin_name, 449 SBError& error); 450 451 lldb::SBFileSpec 452 GetExecutable (); 453 454 bool 455 AddModule (lldb::SBModule &module); 456 457 lldb::SBModule 458 AddModule (const char *path, 459 const char *triple, 460 const char *uuid); 461 462 uint32_t 463 GetNumModules () const; 464 465 lldb::SBModule 466 GetModuleAtIndex (uint32_t idx); 467 468 bool 469 RemoveModule (lldb::SBModule module); 470 471 lldb::SBDebugger 472 GetDebugger() const; 473 474 lldb::SBModule 475 FindModule (const lldb::SBFileSpec &file_spec); 476 477 lldb::ByteOrder 478 GetByteOrder (); 479 480 uint32_t 481 GetAddressByteSize(); 482 483 const char * 484 GetTriple (); 485 486 //------------------------------------------------------------------ 487 /// Set the base load address for a module section. 488 /// 489 /// @param[in] section 490 /// The section whose base load address will be set within this 491 /// target. 492 /// 493 /// @param[in] section_base_addr 494 /// The base address for the section. 495 /// 496 /// @return 497 /// An error to indicate success, fail, and any reason for 498 /// failure. 499 //------------------------------------------------------------------ 500 lldb::SBError 501 SetSectionLoadAddress (lldb::SBSection section, 502 lldb::addr_t section_base_addr); 503 504 //------------------------------------------------------------------ 505 /// Clear the base load address for a module section. 506 /// 507 /// @param[in] section 508 /// The section whose base load address will be cleared within 509 /// this target. 510 /// 511 /// @return 512 /// An error to indicate success, fail, and any reason for 513 /// failure. 514 //------------------------------------------------------------------ 515 lldb::SBError 516 ClearSectionLoadAddress (lldb::SBSection section); 517 518 //------------------------------------------------------------------ 519 /// Slide all file addresses for all module sections so that \a module 520 /// appears to loaded at these slide addresses. 521 /// 522 /// When you need all sections within a module to be loaded at a 523 /// rigid slide from the addresses found in the module object file, 524 /// this function will allow you to easily and quickly slide all 525 /// module sections. 526 /// 527 /// @param[in] module 528 /// The module to load. 529 /// 530 /// @param[in] sections_offset 531 /// An offset that will be applied to all section file addresses 532 /// (the virtual addresses found in the object file itself). 533 /// 534 /// @return 535 /// An error to indicate success, fail, and any reason for 536 /// failure. 537 //------------------------------------------------------------------ 538 lldb::SBError 539 SetModuleLoadAddress (lldb::SBModule module, 540 int64_t sections_offset); 541 542 543 //------------------------------------------------------------------ 544 /// The the section base load addresses for all sections in a module. 545 /// 546 /// @param[in] module 547 /// The module to unload. 548 /// 549 /// @return 550 /// An error to indicate success, fail, and any reason for 551 /// failure. 552 //------------------------------------------------------------------ 553 lldb::SBError 554 ClearModuleLoadAddress (lldb::SBModule module); 555 556 //------------------------------------------------------------------ 557 /// Find functions by name. 558 /// 559 /// @param[in] name 560 /// The name of the function we are looking for. 561 /// 562 /// @param[in] name_type_mask 563 /// A logical OR of one or more FunctionNameType enum bits that 564 /// indicate what kind of names should be used when doing the 565 /// lookup. Bits include fully qualified names, base names, 566 /// C++ methods, or ObjC selectors. 567 /// See FunctionNameType for more details. 568 /// 569 /// @return 570 /// A lldb::SBSymbolContextList that gets filled in with all of 571 /// the symbol contexts for all the matches. 572 //------------------------------------------------------------------ 573 lldb::SBSymbolContextList 574 FindFunctions (const char *name, 575 uint32_t name_type_mask = lldb::eFunctionNameTypeAny); 576 577 //------------------------------------------------------------------ 578 /// Find global and static variables by name. 579 /// 580 /// @param[in] name 581 /// The name of the global or static variable we are looking 582 /// for. 583 /// 584 /// @param[in] max_matches 585 /// Allow the number of matches to be limited to \a max_matches. 586 /// 587 /// @return 588 /// A list of matched variables in an SBValueList. 589 //------------------------------------------------------------------ 590 lldb::SBValueList 591 FindGlobalVariables (const char *name, 592 uint32_t max_matches); 593 594 void 595 Clear (); 596 597 lldb::SBAddress 598 ResolveLoadAddress (lldb::addr_t vm_addr); 599 600 SBSymbolContext 601 ResolveSymbolContextForAddress (const SBAddress& addr, 602 uint32_t resolve_scope); 603 604 lldb::SBBreakpoint 605 BreakpointCreateByLocation (const char *file, uint32_t line); 606 607 lldb::SBBreakpoint 608 BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line); 609 610 lldb::SBBreakpoint 611 BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); 612 613 // This version uses name_type_mask = eFunctionNameTypeAuto 614 lldb::SBBreakpoint 615 BreakpointCreateByName (const char *symbol_name, 616 const SBFileSpecList &module_list, 617 const SBFileSpecList &comp_unit_list); 618 619 lldb::SBBreakpoint 620 BreakpointCreateByName (const char *symbol_name, 621 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 622 const SBFileSpecList &module_list, 623 const SBFileSpecList &comp_unit_list); 624 625 lldb::SBBreakpoint 626 BreakpointCreateByNames (const char *symbol_name[], 627 uint32_t num_names, 628 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 629 const SBFileSpecList &module_list, 630 const SBFileSpecList &comp_unit_list); 631 632 lldb::SBBreakpoint 633 BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL); 634 635 lldb::SBBreakpoint 636 BreakpointCreateByRegex (const char *symbol_name_regex, 637 const SBFileSpecList &module_list, 638 const SBFileSpecList &comp_unit_list); 639 640 lldb::SBBreakpoint 641 BreakpointCreateBySourceRegex (const char *source_regex, 642 const lldb::SBFileSpec &source_file, 643 const char *module_name = NULL); 644 645 lldb::SBBreakpoint 646 BreakpointCreateBySourceRegex (const char *source_regex, 647 const SBFileSpecList &module_list, 648 const lldb::SBFileSpecList &source_file); 649 650 lldb::SBBreakpoint 651 BreakpointCreateForException (lldb::LanguageType language, 652 bool catch_bp, 653 bool throw_bp); 654 655 lldb::SBBreakpoint 656 BreakpointCreateByAddress (addr_t address); 657 658 uint32_t 659 GetNumBreakpoints () const; 660 661 lldb::SBBreakpoint 662 GetBreakpointAtIndex (uint32_t idx) const; 663 664 bool 665 BreakpointDelete (break_id_t break_id); 666 667 lldb::SBBreakpoint 668 FindBreakpointByID (break_id_t break_id); 669 670 bool 671 EnableAllBreakpoints (); 672 673 bool 674 DisableAllBreakpoints (); 675 676 bool 677 DeleteAllBreakpoints (); 678 679 uint32_t 680 GetNumWatchpoints () const; 681 682 lldb::SBWatchpoint 683 GetWatchpointAtIndex (uint32_t idx) const; 684 685 bool 686 DeleteWatchpoint (lldb::watch_id_t watch_id); 687 688 lldb::SBWatchpoint 689 FindWatchpointByID (lldb::watch_id_t watch_id); 690 691 lldb::SBWatchpoint 692 WatchAddress (lldb::addr_t addr, size_t size, bool read, bool write); 693 694 bool 695 EnableAllWatchpoints (); 696 697 bool 698 DisableAllWatchpoints (); 699 700 bool 701 DeleteAllWatchpoints (); 702 703 lldb::SBBroadcaster 704 GetBroadcaster () const; 705 706 lldb::SBType 707 FindFirstType (const char* type); 708 709 lldb::SBTypeList 710 FindTypes (const char* type); 711 712 SBSourceManager 713 GetSourceManager(); 714 715 lldb::SBInstructionList 716 GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); 717 718 lldb::SBInstructionList 719 GetInstructions (lldb::addr_t base_addr, const void *buf, size_t size); 720 721 bool 722 operator == (const lldb::SBTarget &rhs) const; 723 724 bool 725 operator != (const lldb::SBTarget &rhs) const; 726 727 bool 728 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level); 729 730protected: 731 friend class SBAddress; 732 friend class SBBlock; 733 friend class SBDebugger; 734 friend class SBFunction; 735 friend class SBInstruction; 736 friend class SBModule; 737 friend class SBProcess; 738 friend class SBSourceManager; 739 friend class SBSymbol; 740 friend class SBValue; 741 742 //------------------------------------------------------------------ 743 // Constructors are private, use static Target::Create function to 744 // create an instance of this class. 745 //------------------------------------------------------------------ 746 747 SBTarget (const lldb::TargetSP& target_sp); 748 749 lldb::TargetSP 750 GetSP () const; 751 752 void 753 SetSP (const lldb::TargetSP& target_sp); 754 755 756private: 757 //------------------------------------------------------------------ 758 // For Target only 759 //------------------------------------------------------------------ 760 761 lldb::TargetSP m_opaque_sp; 762}; 763 764} // namespace lldb 765 766#endif // LLDB_SBTarget_h_ 767