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