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