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