SBTarget.h revision 23b8abbe214c252028f6e09f79169529c846409d
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/SBType.h" 19 20namespace lldb { 21 22class SBBreakpoint; 23 24class SBTarget 25{ 26public: 27 //------------------------------------------------------------------ 28 // Broadcaster bits. 29 //------------------------------------------------------------------ 30 enum 31 { 32 eBroadcastBitBreakpointChanged = (1 << 0), 33 eBroadcastBitModulesLoaded = (1 << 1), 34 eBroadcastBitModulesUnloaded = (1 << 2) 35 }; 36 37 //------------------------------------------------------------------ 38 // Constructors 39 //------------------------------------------------------------------ 40 SBTarget (); 41 42 SBTarget (const lldb::SBTarget& rhs); 43 44#ifndef SWIG 45 const lldb::SBTarget& 46 operator = (const lldb::SBTarget& rhs); 47#endif 48 49 //------------------------------------------------------------------ 50 // Destructor 51 //------------------------------------------------------------------ 52 ~SBTarget(); 53 54 bool 55 IsValid() const; 56 57 lldb::SBProcess 58 GetProcess (); 59 60 //------------------------------------------------------------------ 61 /// Launch a new process. 62 /// 63 /// Launch a new process by spawning a new process using the 64 /// target object's executable module's file as the file to launch. 65 /// Arguments are given in \a argv, and the environment variables 66 /// are in \a envp. Standard input and output files can be 67 /// optionally re-directed to \a stdin_path, \a stdout_path, and 68 /// \a stderr_path. 69 /// 70 /// @param[in] listener 71 /// An optional listener that will receive all process events. 72 /// If \a listener is valid then \a listener will listen to all 73 /// process events. If not valid, then this target's debugger 74 /// (SBTarget::GetDebugger()) will listen to all process events. 75 /// 76 /// @param[in] argv 77 /// The argument array. 78 /// 79 /// @param[in] envp 80 /// The environment array. 81 /// 82 /// @param[in] launch_flags 83 /// Flags to modify the launch (@see lldb::LaunchFlags) 84 /// 85 /// @param[in] stdin_path 86 /// The path to use when re-directing the STDIN of the new 87 /// process. If all stdXX_path arguments are NULL, a pseudo 88 /// terminal will be used. 89 /// 90 /// @param[in] stdout_path 91 /// The path to use when re-directing the STDOUT of the new 92 /// process. If all stdXX_path arguments are NULL, a pseudo 93 /// terminal will be used. 94 /// 95 /// @param[in] stderr_path 96 /// The path to use when re-directing the STDERR of the new 97 /// process. If all stdXX_path arguments are NULL, a pseudo 98 /// terminal will be used. 99 /// 100 /// @param[in] working_directory 101 /// The working directory to have the child process run in 102 /// 103 /// @param[in] launch_flags 104 /// Some launch options specified by logical OR'ing 105 /// lldb::LaunchFlags enumeration values together. 106 /// 107 /// @param[in] stop_at_endtry 108 /// If false do not stop the inferior at the entry point. 109 /// 110 /// @param[out] 111 /// An error object. Contains the reason if there is some failure. 112 /// 113 /// @return 114 /// A process object for the newly created process. 115 //------------------------------------------------------------------ 116 lldb::SBProcess 117 Launch (SBListener &listener, 118 char const **argv, 119 char const **envp, 120 const char *stdin_path, 121 const char *stdout_path, 122 const char *stderr_path, 123 const char *working_directory, 124 uint32_t launch_flags, // See LaunchFlags 125 bool stop_at_entry, 126 lldb::SBError& error); 127 128 129 //------------------------------------------------------------------ 130 /// Launch a new process with sensible defaults. 131 /// 132 /// @param[in] argv 133 /// The argument array. 134 /// 135 /// @param[in] envp 136 /// The environment array. 137 /// 138 /// @param[in] working_directory 139 /// The working directory to have the child process run in 140 /// 141 /// Default: listener 142 /// Set to the target's debugger (SBTarget::GetDebugger()) 143 /// 144 /// Default: launch_flags 145 /// Empty launch flags 146 /// 147 /// Default: stdin_path 148 /// Default: stdout_path 149 /// Default: stderr_path 150 /// A pseudo terminal will be used. 151 /// 152 /// @return 153 /// A process object for the newly created process. 154 //------------------------------------------------------------------ 155 lldb::SBProcess 156 LaunchSimple (const char **argv, 157 const char **envp, 158 const char *working_directory); 159 160 //------------------------------------------------------------------ 161 /// Attach to process with pid. 162 /// 163 /// @param[in] listener 164 /// An optional listener that will receive all process events. 165 /// If \a listener is valid then \a listener will listen to all 166 /// process events. If not valid, then this target's debugger 167 /// (SBTarget::GetDebugger()) will listen to all process events. 168 /// 169 /// @param[in] pid 170 /// The process ID to attach to. 171 /// 172 /// @param[out] 173 /// An error explaining what went wrong if attach fails. 174 /// 175 /// @return 176 /// A process object for the attached process. 177 //------------------------------------------------------------------ 178 lldb::SBProcess 179 AttachToProcessWithID (SBListener &listener, 180 lldb::pid_t pid, 181 lldb::SBError& error); 182 183 //------------------------------------------------------------------ 184 /// Attach to process with name. 185 /// 186 /// @param[in] listener 187 /// An optional listener that will receive all process events. 188 /// If \a listener is valid then \a listener will listen to all 189 /// process events. If not valid, then this target's debugger 190 /// (SBTarget::GetDebugger()) will listen to all process events. 191 /// 192 /// @param[in] name 193 /// Basename of process to attach to. 194 /// 195 /// @param[in] wait_for 196 /// If true wait for a new instance of 'name' to be launched. 197 /// 198 /// @param[out] 199 /// An error explaining what went wrong if attach fails. 200 /// 201 /// @return 202 /// A process object for the attached process. 203 //------------------------------------------------------------------ 204 lldb::SBProcess 205 AttachToProcessWithName (SBListener &listener, 206 const char *name, 207 bool wait_for, 208 lldb::SBError& error); 209 210 //------------------------------------------------------------------ 211 /// Connect to a remote debug server with url. 212 /// 213 /// @param[in] listener 214 /// An optional listener that will receive all process events. 215 /// If \a listener is valid then \a listener will listen to all 216 /// process events. If not valid, then this target's debugger 217 /// (SBTarget::GetDebugger()) will listen to all process events. 218 /// 219 /// @param[in] url 220 /// The url to connect to, e.g., 'connect://localhost:12345'. 221 /// 222 /// @param[in] plugin_name 223 /// The plugin name to be used; can be NULL. 224 /// 225 /// @param[out] 226 /// An error explaining what went wrong if the connect fails. 227 /// 228 /// @return 229 /// A process object for the connected process. 230 //------------------------------------------------------------------ 231 lldb::SBProcess 232 ConnectRemote (SBListener &listener, 233 const char *url, 234 const char *plugin_name, 235 SBError& error); 236 237 lldb::SBFileSpec 238 GetExecutable (); 239 240 bool 241 AddModule (lldb::SBModule &module); 242 243 lldb::SBModule 244 AddModule (const char *path, 245 const char *triple, 246 const char *uuid); 247 248 uint32_t 249 GetNumModules () const; 250 251 lldb::SBModule 252 GetModuleAtIndex (uint32_t idx); 253 254 bool 255 RemoveModule (lldb::SBModule module); 256 257 lldb::SBDebugger 258 GetDebugger() const; 259 260 lldb::SBModule 261 FindModule (const lldb::SBFileSpec &file_spec); 262 263 //------------------------------------------------------------------ 264 /// Set the base load address for a module section. 265 /// 266 /// @param[in] section 267 /// The section whose base load address will be set within this 268 /// target. 269 /// 270 /// @param[in] section_base_addr 271 /// The base address for the section. 272 /// 273 /// @return 274 /// An error to indicate success, fail, and any reason for 275 /// failure. 276 //------------------------------------------------------------------ 277 lldb::SBError 278 SetSectionLoadAddress (lldb::SBSection section, 279 lldb::addr_t section_base_addr); 280 281 //------------------------------------------------------------------ 282 /// Clear the base load address for a module section. 283 /// 284 /// @param[in] section 285 /// The section whose base load address will be cleared within 286 /// this target. 287 /// 288 /// @return 289 /// An error to indicate success, fail, and any reason for 290 /// failure. 291 //------------------------------------------------------------------ 292 lldb::SBError 293 ClearSectionLoadAddress (lldb::SBSection section); 294 295 //------------------------------------------------------------------ 296 /// Slide all file addresses for all module sections so that \a module 297 /// appears to loaded at these slide addresses. 298 /// 299 /// When you need all sections within a module to be loaded at a 300 /// rigid slide from the addresses found in the module object file, 301 /// this function will allow you to easily and quickly slide all 302 /// module sections. 303 /// 304 /// @param[in] module 305 /// The module to load. 306 /// 307 /// @param[in] sections_offset 308 /// An offset that will be applied to all section file addresses 309 /// (the virtual addresses found in the object file itself). 310 /// 311 /// @return 312 /// An error to indicate success, fail, and any reason for 313 /// failure. 314 //------------------------------------------------------------------ 315 lldb::SBError 316 SetModuleLoadAddress (lldb::SBModule module, 317 int64_t sections_offset); 318 319 320 //------------------------------------------------------------------ 321 /// The the section base load addresses for all sections in a module. 322 /// 323 /// @param[in] module 324 /// The module to unload. 325 /// 326 /// @return 327 /// An error to indicate success, fail, and any reason for 328 /// failure. 329 //------------------------------------------------------------------ 330 lldb::SBError 331 ClearModuleLoadAddress (lldb::SBModule module); 332 333 //------------------------------------------------------------------ 334 /// Find functions by name. 335 /// 336 /// @param[in] name 337 /// The name of the function we are looking for. 338 /// 339 /// @param[in] name_type_mask 340 /// A logical OR of one or more FunctionNameType enum bits that 341 /// indicate what kind of names should be used when doing the 342 /// lookup. Bits include fully qualified names, base names, 343 /// C++ methods, or ObjC selectors. 344 /// See FunctionNameType for more details. 345 /// 346 /// @param[in] append 347 /// If true, any matches will be appended to \a sc_list, else 348 /// matches replace the contents of \a sc_list. 349 /// 350 /// @param[out] sc_list 351 /// A symbol context list that gets filled in with all of the 352 /// matches. 353 /// 354 /// @return 355 /// The number of matches added to \a sc_list. 356 //------------------------------------------------------------------ 357 uint32_t 358 FindFunctions (const char *name, 359 uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits 360 bool append, 361 lldb::SBSymbolContextList& sc_list); 362 363 //------------------------------------------------------------------ 364 /// Find global and static variables by name. 365 /// 366 /// @param[in] name 367 /// The name of the global or static variable we are looking 368 /// for. 369 /// 370 /// @param[in] max_matches 371 /// Allow the number of matches to be limited to \a max_matches. 372 /// 373 /// @return 374 /// A list of matched variables in an SBValueList. 375 //------------------------------------------------------------------ 376 lldb::SBValueList 377 FindGlobalVariables (const char *name, 378 uint32_t max_matches); 379 380 void 381 Clear (); 382 383 lldb::SBAddress 384 ResolveLoadAddress (lldb::addr_t vm_addr); 385 386 SBSymbolContext 387 ResolveSymbolContextForAddress (const SBAddress& addr, 388 uint32_t resolve_scope); 389 390 lldb::SBBreakpoint 391 BreakpointCreateByLocation (const char *file, uint32_t line); 392 393 lldb::SBBreakpoint 394 BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line); 395 396 lldb::SBBreakpoint 397 BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); 398 399 lldb::SBBreakpoint 400 BreakpointCreateByName (const char *symbol_name, 401 const SBFileSpecList &module_list, 402 const SBFileSpecList &comp_unit_list); 403 404 lldb::SBBreakpoint 405 BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL); 406 407 lldb::SBBreakpoint 408 BreakpointCreateByRegex (const char *symbol_name_regex, 409 const SBFileSpecList &module_list, 410 const SBFileSpecList &comp_unit_list); 411 412 lldb::SBBreakpoint 413 BreakpointCreateBySourceRegex (const char *source_regex, 414 const lldb::SBFileSpec &source_file, 415 const char *module_name = NULL); 416 417 lldb::SBBreakpoint 418 BreakpointCreateBySourceRegex (const char *source_regex, 419 const SBFileSpecList &module_list, 420 const lldb::SBFileSpecList &source_file); 421 422 lldb::SBBreakpoint 423 BreakpointCreateByAddress (addr_t address); 424 425 uint32_t 426 GetNumBreakpoints () const; 427 428 lldb::SBBreakpoint 429 GetBreakpointAtIndex (uint32_t idx) const; 430 431 bool 432 BreakpointDelete (break_id_t break_id); 433 434 lldb::SBBreakpoint 435 FindBreakpointByID (break_id_t break_id); 436 437 bool 438 EnableAllBreakpoints (); 439 440 bool 441 DisableAllBreakpoints (); 442 443 bool 444 DeleteAllBreakpoints (); 445 446 lldb::SBBroadcaster 447 GetBroadcaster () const; 448 449 lldb::SBType 450 FindFirstType (const char* type); 451 452 lldb::SBTypeList 453 FindTypes (const char* type); 454 455 SBSourceManager 456 GetSourceManager(); 457 458#ifndef SWIG 459 bool 460 operator == (const lldb::SBTarget &rhs) const; 461 462 bool 463 operator != (const lldb::SBTarget &rhs) const; 464 465#endif 466 467#ifndef SWIG 468 bool 469 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level); 470#endif 471 472 bool 473 GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level) const; 474 475protected: 476 friend class SBAddress; 477 friend class SBDebugger; 478 friend class SBFunction; 479 friend class SBInstruction; 480 friend class SBProcess; 481 friend class SBSymbol; 482 friend class SBModule; 483 friend class SBValue; 484 friend class SBSourceManager_impl; 485 486 //------------------------------------------------------------------ 487 // Constructors are private, use static Target::Create function to 488 // create an instance of this class. 489 //------------------------------------------------------------------ 490 491 SBTarget (const lldb::TargetSP& target_sp); 492 493 void 494 reset (const lldb::TargetSP& target_sp); 495 496 lldb_private::Target * 497 operator ->() const; 498 499 lldb_private::Target * 500 get() const; 501 502private: 503 //------------------------------------------------------------------ 504 // For Target only 505 //------------------------------------------------------------------ 506 507 lldb::TargetSP m_opaque_sp; 508}; 509 510} // namespace lldb 511 512#endif // LLDB_SBTarget_h_ 513