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 23 namespace lldb { 24 25 class SBLaunchInfo 26 { 27 public: 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 113 protected: 114 friend class SBTarget; 115 116 lldb_private::ProcessLaunchInfo & 117 ref (); 118 119 ProcessLaunchInfoSP m_opaque_sp; 120 }; 121 122 class SBAttachInfo 123 { 124 public: 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 220 protected: 221 friend class SBTarget; 222 223 lldb_private::ProcessAttachInfo & 224 ref (); 225 226 ProcessAttachInfoSP m_opaque_sp; 227 }; 228 229 class SBTarget 230 { 231 public: 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 /// Launch a new process. 272 /// 273 /// Launch a new process by spawning a new process using the 274 /// target object's executable module's file as the file to launch. 275 /// Arguments are given in \a argv, and the environment variables 276 /// are in \a envp. Standard input and output files can be 277 /// optionally re-directed to \a stdin_path, \a stdout_path, and 278 /// \a stderr_path. 279 /// 280 /// @param[in] listener 281 /// An optional listener that will receive all process events. 282 /// If \a listener is valid then \a listener will listen to all 283 /// process events. If not valid, then this target's debugger 284 /// (SBTarget::GetDebugger()) will listen to all process events. 285 /// 286 /// @param[in] argv 287 /// The argument array. 288 /// 289 /// @param[in] envp 290 /// The environment array. 291 /// 292 /// @param[in] launch_flags 293 /// Flags to modify the launch (@see lldb::LaunchFlags) 294 /// 295 /// @param[in] stdin_path 296 /// The path to use when re-directing the STDIN of the new 297 /// process. If all stdXX_path arguments are NULL, a pseudo 298 /// terminal will be used. 299 /// 300 /// @param[in] stdout_path 301 /// The path to use when re-directing the STDOUT of the new 302 /// process. If all stdXX_path arguments are NULL, a pseudo 303 /// terminal will be used. 304 /// 305 /// @param[in] stderr_path 306 /// The path to use when re-directing the STDERR of the new 307 /// process. If all stdXX_path arguments are NULL, a pseudo 308 /// terminal will be used. 309 /// 310 /// @param[in] working_directory 311 /// The working directory to have the child process run in 312 /// 313 /// @param[in] launch_flags 314 /// Some launch options specified by logical OR'ing 315 /// lldb::LaunchFlags enumeration values together. 316 /// 317 /// @param[in] stop_at_endtry 318 /// If false do not stop the inferior at the entry point. 319 /// 320 /// @param[out] 321 /// An error object. Contains the reason if there is some failure. 322 /// 323 /// @return 324 /// A process object for the newly created process. 325 //------------------------------------------------------------------ 326 lldb::SBProcess 327 Launch (SBListener &listener, 328 char const **argv, 329 char const **envp, 330 const char *stdin_path, 331 const char *stdout_path, 332 const char *stderr_path, 333 const char *working_directory, 334 uint32_t launch_flags, // See LaunchFlags 335 bool stop_at_entry, 336 lldb::SBError& error); 337 338 339 //------------------------------------------------------------------ 340 /// Launch a new process with sensible defaults. 341 /// 342 /// @param[in] argv 343 /// The argument array. 344 /// 345 /// @param[in] envp 346 /// The environment array. 347 /// 348 /// @param[in] working_directory 349 /// The working directory to have the child process run in 350 /// 351 /// Default: listener 352 /// Set to the target's debugger (SBTarget::GetDebugger()) 353 /// 354 /// Default: launch_flags 355 /// Empty launch flags 356 /// 357 /// Default: stdin_path 358 /// Default: stdout_path 359 /// Default: stderr_path 360 /// A pseudo terminal will be used. 361 /// 362 /// @return 363 /// A process object for the newly created process. 364 //------------------------------------------------------------------ 365 SBProcess 366 LaunchSimple (const char **argv, 367 const char **envp, 368 const char *working_directory); 369 370 SBProcess 371 Launch (SBLaunchInfo &launch_info, SBError& error); 372 373 SBProcess 374 LoadCore (const char *core_file); 375 376 SBProcess 377 Attach (SBAttachInfo &attach_info, SBError& error); 378 379 //------------------------------------------------------------------ 380 /// Attach to process with pid. 381 /// 382 /// @param[in] listener 383 /// An optional listener that will receive all process events. 384 /// If \a listener is valid then \a listener will listen to all 385 /// process events. If not valid, then this target's debugger 386 /// (SBTarget::GetDebugger()) will listen to all process events. 387 /// 388 /// @param[in] pid 389 /// The process ID to attach to. 390 /// 391 /// @param[out] 392 /// An error explaining what went wrong if attach fails. 393 /// 394 /// @return 395 /// A process object for the attached process. 396 //------------------------------------------------------------------ 397 lldb::SBProcess 398 AttachToProcessWithID (SBListener &listener, 399 lldb::pid_t pid, 400 lldb::SBError& error); 401 402 #if defined(__APPLE__) 403 // We need to keep this around for a build or two since Xcode links 404 // to the 32 bit version of this function. We will take it out soon. 405 lldb::SBProcess 406 AttachToProcessWithID (SBListener &listener, 407 ::pid_t pid, // 32 bit int process ID 408 lldb::SBError& error); // DEPRECATED 409 #endif 410 //------------------------------------------------------------------ 411 /// Attach to process with name. 412 /// 413 /// @param[in] listener 414 /// An optional listener that will receive all process events. 415 /// If \a listener is valid then \a listener will listen to all 416 /// process events. If not valid, then this target's debugger 417 /// (SBTarget::GetDebugger()) will listen to all process events. 418 /// 419 /// @param[in] name 420 /// Basename of process to attach to. 421 /// 422 /// @param[in] wait_for 423 /// If true wait for a new instance of 'name' to be launched. 424 /// 425 /// @param[out] 426 /// An error explaining what went wrong if attach fails. 427 /// 428 /// @return 429 /// A process object for the attached process. 430 //------------------------------------------------------------------ 431 lldb::SBProcess 432 AttachToProcessWithName (SBListener &listener, 433 const char *name, 434 bool wait_for, 435 lldb::SBError& error); 436 437 //------------------------------------------------------------------ 438 /// Connect to a remote debug server with url. 439 /// 440 /// @param[in] listener 441 /// An optional listener that will receive all process events. 442 /// If \a listener is valid then \a listener will listen to all 443 /// process events. If not valid, then this target's debugger 444 /// (SBTarget::GetDebugger()) will listen to all process events. 445 /// 446 /// @param[in] url 447 /// The url to connect to, e.g., 'connect://localhost:12345'. 448 /// 449 /// @param[in] plugin_name 450 /// The plugin name to be used; can be NULL. 451 /// 452 /// @param[out] 453 /// An error explaining what went wrong if the connect fails. 454 /// 455 /// @return 456 /// A process object for the connected process. 457 //------------------------------------------------------------------ 458 lldb::SBProcess 459 ConnectRemote (SBListener &listener, 460 const char *url, 461 const char *plugin_name, 462 SBError& error); 463 464 lldb::SBFileSpec 465 GetExecutable (); 466 467 bool 468 AddModule (lldb::SBModule &module); 469 470 lldb::SBModule 471 AddModule (const char *path, 472 const char *triple, 473 const char *uuid); 474 475 lldb::SBModule 476 AddModule (const char *path, 477 const char *triple, 478 const char *uuid_cstr, 479 const char *symfile); 480 481 lldb::SBModule 482 AddModule (const SBModuleSpec &module_spec); 483 484 uint32_t 485 GetNumModules () const; 486 487 lldb::SBModule 488 GetModuleAtIndex (uint32_t idx); 489 490 bool 491 RemoveModule (lldb::SBModule module); 492 493 lldb::SBDebugger 494 GetDebugger() const; 495 496 lldb::SBModule 497 FindModule (const lldb::SBFileSpec &file_spec); 498 499 lldb::ByteOrder 500 GetByteOrder (); 501 502 uint32_t 503 GetAddressByteSize(); 504 505 const char * 506 GetTriple (); 507 508 //------------------------------------------------------------------ 509 /// Set the base load address for a module section. 510 /// 511 /// @param[in] section 512 /// The section whose base load address will be set within this 513 /// target. 514 /// 515 /// @param[in] section_base_addr 516 /// The base address for the section. 517 /// 518 /// @return 519 /// An error to indicate success, fail, and any reason for 520 /// failure. 521 //------------------------------------------------------------------ 522 lldb::SBError 523 SetSectionLoadAddress (lldb::SBSection section, 524 lldb::addr_t section_base_addr); 525 526 //------------------------------------------------------------------ 527 /// Clear the base load address for a module section. 528 /// 529 /// @param[in] section 530 /// The section whose base load address will be cleared within 531 /// this target. 532 /// 533 /// @return 534 /// An error to indicate success, fail, and any reason for 535 /// failure. 536 //------------------------------------------------------------------ 537 lldb::SBError 538 ClearSectionLoadAddress (lldb::SBSection section); 539 540 //------------------------------------------------------------------ 541 /// Slide all file addresses for all module sections so that \a module 542 /// appears to loaded at these slide addresses. 543 /// 544 /// When you need all sections within a module to be loaded at a 545 /// rigid slide from the addresses found in the module object file, 546 /// this function will allow you to easily and quickly slide all 547 /// module sections. 548 /// 549 /// @param[in] module 550 /// The module to load. 551 /// 552 /// @param[in] sections_offset 553 /// An offset that will be applied to all section file addresses 554 /// (the virtual addresses found in the object file itself). 555 /// 556 /// @return 557 /// An error to indicate success, fail, and any reason for 558 /// failure. 559 //------------------------------------------------------------------ 560 lldb::SBError 561 SetModuleLoadAddress (lldb::SBModule module, 562 int64_t sections_offset); 563 564 565 //------------------------------------------------------------------ 566 /// The the section base load addresses for all sections in a module. 567 /// 568 /// @param[in] module 569 /// The module to unload. 570 /// 571 /// @return 572 /// An error to indicate success, fail, and any reason for 573 /// failure. 574 //------------------------------------------------------------------ 575 lldb::SBError 576 ClearModuleLoadAddress (lldb::SBModule module); 577 578 //------------------------------------------------------------------ 579 /// Find functions by name. 580 /// 581 /// @param[in] name 582 /// The name of the function we are looking for. 583 /// 584 /// @param[in] name_type_mask 585 /// A logical OR of one or more FunctionNameType enum bits that 586 /// indicate what kind of names should be used when doing the 587 /// lookup. Bits include fully qualified names, base names, 588 /// C++ methods, or ObjC selectors. 589 /// See FunctionNameType for more details. 590 /// 591 /// @return 592 /// A lldb::SBSymbolContextList that gets filled in with all of 593 /// the symbol contexts for all the matches. 594 //------------------------------------------------------------------ 595 lldb::SBSymbolContextList 596 FindFunctions (const char *name, 597 uint32_t name_type_mask = lldb::eFunctionNameTypeAny); 598 599 //------------------------------------------------------------------ 600 /// Find global and static variables by name. 601 /// 602 /// @param[in] name 603 /// The name of the global or static variable we are looking 604 /// for. 605 /// 606 /// @param[in] max_matches 607 /// Allow the number of matches to be limited to \a max_matches. 608 /// 609 /// @return 610 /// A list of matched variables in an SBValueList. 611 //------------------------------------------------------------------ 612 lldb::SBValueList 613 FindGlobalVariables (const char *name, 614 uint32_t max_matches); 615 616 //------------------------------------------------------------------ 617 /// Find the first global (or static) variable by name. 618 /// 619 /// @param[in] name 620 /// The name of the global or static variable we are looking 621 /// for. 622 /// 623 /// @return 624 /// An SBValue that gets filled in with the found variable (if any). 625 //------------------------------------------------------------------ 626 lldb::SBValue 627 FindFirstGlobalVariable (const char* name); 628 629 void 630 Clear (); 631 632 lldb::SBAddress 633 ResolveLoadAddress (lldb::addr_t vm_addr); 634 635 SBSymbolContext 636 ResolveSymbolContextForAddress (const SBAddress& addr, 637 uint32_t resolve_scope); 638 639 lldb::SBBreakpoint 640 BreakpointCreateByLocation (const char *file, uint32_t line); 641 642 lldb::SBBreakpoint 643 BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line); 644 645 lldb::SBBreakpoint 646 BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); 647 648 // This version uses name_type_mask = eFunctionNameTypeAuto 649 lldb::SBBreakpoint 650 BreakpointCreateByName (const char *symbol_name, 651 const SBFileSpecList &module_list, 652 const SBFileSpecList &comp_unit_list); 653 654 lldb::SBBreakpoint 655 BreakpointCreateByName (const char *symbol_name, 656 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 657 const SBFileSpecList &module_list, 658 const SBFileSpecList &comp_unit_list); 659 660 lldb::SBBreakpoint 661 BreakpointCreateByNames (const char *symbol_name[], 662 uint32_t num_names, 663 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 664 const SBFileSpecList &module_list, 665 const SBFileSpecList &comp_unit_list); 666 667 lldb::SBBreakpoint 668 BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL); 669 670 lldb::SBBreakpoint 671 BreakpointCreateByRegex (const char *symbol_name_regex, 672 const SBFileSpecList &module_list, 673 const SBFileSpecList &comp_unit_list); 674 675 lldb::SBBreakpoint 676 BreakpointCreateBySourceRegex (const char *source_regex, 677 const lldb::SBFileSpec &source_file, 678 const char *module_name = NULL); 679 680 lldb::SBBreakpoint 681 BreakpointCreateBySourceRegex (const char *source_regex, 682 const SBFileSpecList &module_list, 683 const lldb::SBFileSpecList &source_file); 684 685 lldb::SBBreakpoint 686 BreakpointCreateForException (lldb::LanguageType language, 687 bool catch_bp, 688 bool throw_bp); 689 690 lldb::SBBreakpoint 691 BreakpointCreateByAddress (addr_t address); 692 693 uint32_t 694 GetNumBreakpoints () const; 695 696 lldb::SBBreakpoint 697 GetBreakpointAtIndex (uint32_t idx) const; 698 699 bool 700 BreakpointDelete (break_id_t break_id); 701 702 lldb::SBBreakpoint 703 FindBreakpointByID (break_id_t break_id); 704 705 bool 706 EnableAllBreakpoints (); 707 708 bool 709 DisableAllBreakpoints (); 710 711 bool 712 DeleteAllBreakpoints (); 713 714 uint32_t 715 GetNumWatchpoints () const; 716 717 lldb::SBWatchpoint 718 GetWatchpointAtIndex (uint32_t idx) const; 719 720 bool 721 DeleteWatchpoint (lldb::watch_id_t watch_id); 722 723 lldb::SBWatchpoint 724 FindWatchpointByID (lldb::watch_id_t watch_id); 725 726 lldb::SBWatchpoint 727 WatchAddress (lldb::addr_t addr, size_t size, bool read, bool write, SBError& error); 728 729 bool 730 EnableAllWatchpoints (); 731 732 bool 733 DisableAllWatchpoints (); 734 735 bool 736 DeleteAllWatchpoints (); 737 738 lldb::SBBroadcaster 739 GetBroadcaster () const; 740 741 lldb::SBType 742 FindFirstType (const char* type); 743 744 lldb::SBTypeList 745 FindTypes (const char* type); 746 747 lldb::SBType 748 GetBasicType(lldb::BasicType type); 749 750 SBSourceManager 751 GetSourceManager(); 752 753 lldb::SBInstructionList 754 ReadInstructions (lldb::SBAddress base_addr, uint32_t count); 755 756 lldb::SBInstructionList 757 ReadInstructions (lldb::SBAddress base_addr, uint32_t count, const char *flavor_string); 758 759 lldb::SBInstructionList 760 GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); 761 762 // The "WithFlavor" is necessary to keep SWIG from getting confused about overloaded arguments when 763 // using the buf + size -> Python Object magic. 764 765 lldb::SBInstructionList 766 GetInstructionsWithFlavor (lldb::SBAddress base_addr, const char *flavor_string, const void *buf, size_t size); 767 768 lldb::SBInstructionList 769 GetInstructions (lldb::addr_t base_addr, const void *buf, size_t size); 770 771 lldb::SBInstructionList 772 GetInstructionsWithFlavor (lldb::addr_t base_addr, const char *flavor_string, const void *buf, size_t size); 773 774 lldb::SBSymbolContextList 775 FindSymbols (const char *name, 776 lldb::SymbolType type = eSymbolTypeAny); 777 778 bool 779 operator == (const lldb::SBTarget &rhs) const; 780 781 bool 782 operator != (const lldb::SBTarget &rhs) const; 783 784 bool 785 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level); 786 787 lldb::SBValue 788 EvaluateExpression (const char *expr, const SBExpressionOptions &options); 789 790 lldb::addr_t 791 GetStackRedZoneSize(); 792 793 protected: 794 friend class SBAddress; 795 friend class SBBlock; 796 friend class SBDebugger; 797 friend class SBFunction; 798 friend class SBInstruction; 799 friend class SBModule; 800 friend class SBProcess; 801 friend class SBSection; 802 friend class SBSourceManager; 803 friend class SBSymbol; 804 friend class SBValue; 805 806 //------------------------------------------------------------------ 807 // Constructors are private, use static Target::Create function to 808 // create an instance of this class. 809 //------------------------------------------------------------------ 810 811 lldb::TargetSP 812 GetSP () const; 813 814 void 815 SetSP (const lldb::TargetSP& target_sp); 816 817 818 private: 819 //------------------------------------------------------------------ 820 // For Target only 821 //------------------------------------------------------------------ 822 823 lldb::TargetSP m_opaque_sp; 824 }; 825 826 } // namespace lldb 827 828 #endif // LLDB_SBTarget_h_ 829