SBTarget.h revision 001cd53e9d8d9e481ada536924ea7563b84ee9cf
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 /// 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 uint32_t 481 GetNumModules () const; 482 483 lldb::SBModule 484 GetModuleAtIndex (uint32_t idx); 485 486 bool 487 RemoveModule (lldb::SBModule module); 488 489 lldb::SBDebugger 490 GetDebugger() const; 491 492 lldb::SBModule 493 FindModule (const lldb::SBFileSpec &file_spec); 494 495 lldb::ByteOrder 496 GetByteOrder (); 497 498 uint32_t 499 GetAddressByteSize(); 500 501 const char * 502 GetTriple (); 503 504 //------------------------------------------------------------------ 505 /// Set the base load address for a module section. 506 /// 507 /// @param[in] section 508 /// The section whose base load address will be set within this 509 /// target. 510 /// 511 /// @param[in] section_base_addr 512 /// The base address for the section. 513 /// 514 /// @return 515 /// An error to indicate success, fail, and any reason for 516 /// failure. 517 //------------------------------------------------------------------ 518 lldb::SBError 519 SetSectionLoadAddress (lldb::SBSection section, 520 lldb::addr_t section_base_addr); 521 522 //------------------------------------------------------------------ 523 /// Clear the base load address for a module section. 524 /// 525 /// @param[in] section 526 /// The section whose base load address will be cleared within 527 /// this target. 528 /// 529 /// @return 530 /// An error to indicate success, fail, and any reason for 531 /// failure. 532 //------------------------------------------------------------------ 533 lldb::SBError 534 ClearSectionLoadAddress (lldb::SBSection section); 535 536 //------------------------------------------------------------------ 537 /// Slide all file addresses for all module sections so that \a module 538 /// appears to loaded at these slide addresses. 539 /// 540 /// When you need all sections within a module to be loaded at a 541 /// rigid slide from the addresses found in the module object file, 542 /// this function will allow you to easily and quickly slide all 543 /// module sections. 544 /// 545 /// @param[in] module 546 /// The module to load. 547 /// 548 /// @param[in] sections_offset 549 /// An offset that will be applied to all section file addresses 550 /// (the virtual addresses found in the object file itself). 551 /// 552 /// @return 553 /// An error to indicate success, fail, and any reason for 554 /// failure. 555 //------------------------------------------------------------------ 556 lldb::SBError 557 SetModuleLoadAddress (lldb::SBModule module, 558 int64_t sections_offset); 559 560 561 //------------------------------------------------------------------ 562 /// The the section base load addresses for all sections in a module. 563 /// 564 /// @param[in] module 565 /// The module to unload. 566 /// 567 /// @return 568 /// An error to indicate success, fail, and any reason for 569 /// failure. 570 //------------------------------------------------------------------ 571 lldb::SBError 572 ClearModuleLoadAddress (lldb::SBModule module); 573 574 //------------------------------------------------------------------ 575 /// Find functions by name. 576 /// 577 /// @param[in] name 578 /// The name of the function we are looking for. 579 /// 580 /// @param[in] name_type_mask 581 /// A logical OR of one or more FunctionNameType enum bits that 582 /// indicate what kind of names should be used when doing the 583 /// lookup. Bits include fully qualified names, base names, 584 /// C++ methods, or ObjC selectors. 585 /// See FunctionNameType for more details. 586 /// 587 /// @return 588 /// A lldb::SBSymbolContextList that gets filled in with all of 589 /// the symbol contexts for all the matches. 590 //------------------------------------------------------------------ 591 lldb::SBSymbolContextList 592 FindFunctions (const char *name, 593 uint32_t name_type_mask = lldb::eFunctionNameTypeAny); 594 595 //------------------------------------------------------------------ 596 /// Find global and static variables by name. 597 /// 598 /// @param[in] name 599 /// The name of the global or static variable we are looking 600 /// for. 601 /// 602 /// @param[in] max_matches 603 /// Allow the number of matches to be limited to \a max_matches. 604 /// 605 /// @return 606 /// A list of matched variables in an SBValueList. 607 //------------------------------------------------------------------ 608 lldb::SBValueList 609 FindGlobalVariables (const char *name, 610 uint32_t max_matches); 611 612 //------------------------------------------------------------------ 613 /// Find the first global (or static) variable by name. 614 /// 615 /// @param[in] name 616 /// The name of the global or static variable we are looking 617 /// for. 618 /// 619 /// @return 620 /// An SBValue that gets filled in with the found variable (if any). 621 //------------------------------------------------------------------ 622 lldb::SBValue 623 FindFirstGlobalVariable (const char* name); 624 625 void 626 Clear (); 627 628 lldb::SBAddress 629 ResolveLoadAddress (lldb::addr_t vm_addr); 630 631 SBSymbolContext 632 ResolveSymbolContextForAddress (const SBAddress& addr, 633 uint32_t resolve_scope); 634 635 lldb::SBBreakpoint 636 BreakpointCreateByLocation (const char *file, uint32_t line); 637 638 lldb::SBBreakpoint 639 BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line); 640 641 lldb::SBBreakpoint 642 BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); 643 644 // This version uses name_type_mask = eFunctionNameTypeAuto 645 lldb::SBBreakpoint 646 BreakpointCreateByName (const char *symbol_name, 647 const SBFileSpecList &module_list, 648 const SBFileSpecList &comp_unit_list); 649 650 lldb::SBBreakpoint 651 BreakpointCreateByName (const char *symbol_name, 652 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 653 const SBFileSpecList &module_list, 654 const SBFileSpecList &comp_unit_list); 655 656 lldb::SBBreakpoint 657 BreakpointCreateByNames (const char *symbol_name[], 658 uint32_t num_names, 659 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 660 const SBFileSpecList &module_list, 661 const SBFileSpecList &comp_unit_list); 662 663 lldb::SBBreakpoint 664 BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL); 665 666 lldb::SBBreakpoint 667 BreakpointCreateByRegex (const char *symbol_name_regex, 668 const SBFileSpecList &module_list, 669 const SBFileSpecList &comp_unit_list); 670 671 lldb::SBBreakpoint 672 BreakpointCreateBySourceRegex (const char *source_regex, 673 const lldb::SBFileSpec &source_file, 674 const char *module_name = NULL); 675 676 lldb::SBBreakpoint 677 BreakpointCreateBySourceRegex (const char *source_regex, 678 const SBFileSpecList &module_list, 679 const lldb::SBFileSpecList &source_file); 680 681 lldb::SBBreakpoint 682 BreakpointCreateForException (lldb::LanguageType language, 683 bool catch_bp, 684 bool throw_bp); 685 686 lldb::SBBreakpoint 687 BreakpointCreateByAddress (addr_t address); 688 689 uint32_t 690 GetNumBreakpoints () const; 691 692 lldb::SBBreakpoint 693 GetBreakpointAtIndex (uint32_t idx) const; 694 695 bool 696 BreakpointDelete (break_id_t break_id); 697 698 lldb::SBBreakpoint 699 FindBreakpointByID (break_id_t break_id); 700 701 bool 702 EnableAllBreakpoints (); 703 704 bool 705 DisableAllBreakpoints (); 706 707 bool 708 DeleteAllBreakpoints (); 709 710 uint32_t 711 GetNumWatchpoints () const; 712 713 lldb::SBWatchpoint 714 GetWatchpointAtIndex (uint32_t idx) const; 715 716 bool 717 DeleteWatchpoint (lldb::watch_id_t watch_id); 718 719 lldb::SBWatchpoint 720 FindWatchpointByID (lldb::watch_id_t watch_id); 721 722 lldb::SBWatchpoint 723 WatchAddress (lldb::addr_t addr, size_t size, bool read, bool write, SBError& error); 724 725 bool 726 EnableAllWatchpoints (); 727 728 bool 729 DisableAllWatchpoints (); 730 731 bool 732 DeleteAllWatchpoints (); 733 734 lldb::SBBroadcaster 735 GetBroadcaster () const; 736 737 lldb::SBType 738 FindFirstType (const char* type); 739 740 lldb::SBTypeList 741 FindTypes (const char* type); 742 743 lldb::SBType 744 GetBasicType(lldb::BasicType type); 745 746 SBSourceManager 747 GetSourceManager(); 748 749 lldb::SBInstructionList 750 ReadInstructions (lldb::SBAddress base_addr, uint32_t count); 751 752 lldb::SBInstructionList 753 ReadInstructions (lldb::SBAddress base_addr, uint32_t count, const char *flavor_string); 754 755 lldb::SBInstructionList 756 GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); 757 758 // The "WithFlavor" is necessary to keep SWIG from getting confused about overloaded arguments when 759 // using the buf + size -> Python Object magic. 760 761 lldb::SBInstructionList 762 GetInstructionsWithFlavor (lldb::SBAddress base_addr, const char *flavor_string, const void *buf, size_t size); 763 764 lldb::SBInstructionList 765 GetInstructions (lldb::addr_t base_addr, const void *buf, size_t size); 766 767 lldb::SBInstructionList 768 GetInstructionsWithFlavor (lldb::addr_t base_addr, const char *flavor_string, const void *buf, size_t size); 769 770 lldb::SBSymbolContextList 771 FindSymbols (const char *name, 772 lldb::SymbolType type = eSymbolTypeAny); 773 774 bool 775 operator == (const lldb::SBTarget &rhs) const; 776 777 bool 778 operator != (const lldb::SBTarget &rhs) const; 779 780 bool 781 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level); 782 783 lldb::SBValue 784 EvaluateExpression (const char *expr, const SBExpressionOptions &options); 785 786 lldb::addr_t 787 GetStackRedZoneSize(); 788 789protected: 790 friend class SBAddress; 791 friend class SBBlock; 792 friend class SBDebugger; 793 friend class SBFunction; 794 friend class SBInstruction; 795 friend class SBModule; 796 friend class SBProcess; 797 friend class SBSection; 798 friend class SBSourceManager; 799 friend class SBSymbol; 800 friend class SBValue; 801 802 //------------------------------------------------------------------ 803 // Constructors are private, use static Target::Create function to 804 // create an instance of this class. 805 //------------------------------------------------------------------ 806 807 lldb::TargetSP 808 GetSP () const; 809 810 void 811 SetSP (const lldb::TargetSP& target_sp); 812 813 814private: 815 //------------------------------------------------------------------ 816 // For Target only 817 //------------------------------------------------------------------ 818 819 lldb::TargetSP m_opaque_sp; 820}; 821 822} // namespace lldb 823 824#endif // LLDB_SBTarget_h_ 825