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