LLDB API Documentation

- Main Page
- Namespaces
- Classes
- Files

- File List

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