LLDB mainline
SBTarget.h
Go to the documentation of this file.
1//===-- SBTarget.h ----------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_API_SBTARGET_H
10#define LLDB_API_SBTARGET_H
11
12#include "lldb/API/SBAddress.h"
16#include "lldb/API/SBDefines.h"
17#include "lldb/API/SBFileSpec.h"
22#include "lldb/API/SBType.h"
23#include "lldb/API/SBValue.h"
26
27namespace lldb_private {
28namespace python {
29class SWIGBridge;
30}
31} // namespace lldb_private
32
33namespace lldb {
34
35class SBPlatform;
36
38public:
39 // Broadcaster bits.
40 enum {
47 };
48
49 // Constructors
50 SBTarget();
51
52 SBTarget(const lldb::SBTarget &rhs);
53
54 // Destructor
56
57 const lldb::SBTarget &operator=(const lldb::SBTarget &rhs);
58
59 explicit operator bool() const;
60
61 bool IsValid() const;
62
63 static bool EventIsTargetEvent(const lldb::SBEvent &event);
64
66
67 static uint32_t GetNumModulesFromEvent(const lldb::SBEvent &event);
68
69 static lldb::SBModule GetModuleAtIndexFromEvent(const uint32_t idx,
70 const lldb::SBEvent &event);
71
72 static const char *GetBroadcasterClassName();
73
75
76 /// Sets whether we should collect statistics on lldb or not.
77 ///
78 /// \param[in] v
79 /// A boolean to control the collection.
80 void SetCollectingStats(bool v);
81
82 /// Returns whether statistics collection are enabled.
83 ///
84 /// \return
85 /// true if statistics are currently being collected, false
86 /// otherwise.
87 bool GetCollectingStats();
88
89 /// Returns a dump of the collected statistics.
90 ///
91 /// \return
92 /// A SBStructuredData with the statistics collected.
94
95 /// Returns a dump of the collected statistics.
96 ///
97 /// \param[in] options
98 /// An objects object that contains all options for the statistics dumping.
99 ///
100 /// \return
101 /// A SBStructuredData with the statistics collected.
103
104 /// Reset the statistics collected for this target.
105 /// This includes clearing symbol table and debug info parsing/index time for
106 /// all modules, breakpoint resolve time and target statistics.
107 void ResetStatistics();
108
109 /// Return the platform object associated with the target.
110 ///
111 /// After return, the platform object should be checked for
112 /// validity.
113 ///
114 /// \return
115 /// A platform object.
117
118 /// Return the environment variables that would be used to launch a new
119 /// process.
120 ///
121 /// \return
122 /// An lldb::SBEnvironment object which is a copy of the target's
123 /// environment.
124
126
127 /// Install any binaries that need to be installed.
128 ///
129 /// This function does nothing when debugging on the host system.
130 /// When connected to remote platforms, the target's main executable
131 /// and any modules that have their remote install path set will be
132 /// installed on the remote platform. If the main executable doesn't
133 /// have an install location set, it will be installed in the remote
134 /// platform's working directory.
135 ///
136 /// \return
137 /// An error describing anything that went wrong during
138 /// installation.
140
141 /// Launch a new process.
142 ///
143 /// Launch a new process by spawning a new process using the
144 /// target object's executable module's file as the file to launch.
145 /// Arguments are given in \a argv, and the environment variables
146 /// are in \a envp. Standard input and output files can be
147 /// optionally re-directed to \a stdin_path, \a stdout_path, and
148 /// \a stderr_path.
149 ///
150 /// \param[in] listener
151 /// An optional listener that will receive all process events.
152 /// If \a listener is valid then \a listener will listen to all
153 /// process events. If not valid, then this target's debugger
154 /// (SBTarget::GetDebugger()) will listen to all process events.
155 ///
156 /// \param[in] argv
157 /// The argument array.
158 ///
159 /// \param[in] envp
160 /// The environment array. If this is null, the default
161 /// environment values (provided through `settings set
162 /// target.env-vars`) will be used.
163 ///
164 /// \param[in] stdin_path
165 /// The path to use when re-directing the STDIN of the new
166 /// process. If all stdXX_path arguments are nullptr, a pseudo
167 /// terminal will be used.
168 ///
169 /// \param[in] stdout_path
170 /// The path to use when re-directing the STDOUT of the new
171 /// process. If all stdXX_path arguments are nullptr, a pseudo
172 /// terminal will be used.
173 ///
174 /// \param[in] stderr_path
175 /// The path to use when re-directing the STDERR of the new
176 /// process. If all stdXX_path arguments are nullptr, a pseudo
177 /// terminal will be used.
178 ///
179 /// \param[in] working_directory
180 /// The working directory to have the child process run in
181 ///
182 /// \param[in] launch_flags
183 /// Some launch options specified by logical OR'ing
184 /// lldb::LaunchFlags enumeration values together.
185 ///
186 /// \param[in] stop_at_entry
187 /// If false do not stop the inferior at the entry point.
188 ///
189 /// \param[out] error
190 /// An error object. Contains the reason if there is some failure.
191 ///
192 /// \return
193 /// A process object for the newly created process.
194 lldb::SBProcess Launch(SBListener &listener, char const **argv,
195 char const **envp, const char *stdin_path,
196 const char *stdout_path, const char *stderr_path,
197 const char *working_directory,
198 uint32_t launch_flags, // See LaunchFlags
199 bool stop_at_entry, lldb::SBError &error);
200
201 SBProcess LoadCore(const char *core_file);
202 SBProcess LoadCore(const char *core_file, lldb::SBError &error);
203
204 /// Launch a new process with sensible defaults.
205 ///
206 /// \param[in] argv
207 /// The argument array.
208 ///
209 /// \param[in] envp
210 /// The environment array. If this isn't provided, the default
211 /// environment values (provided through `settings set
212 /// target.env-vars`) will be used.
213 ///
214 /// \param[in] working_directory
215 /// The working directory to have the child process run in
216 ///
217 /// Default: listener
218 /// Set to the target's debugger (SBTarget::GetDebugger())
219 ///
220 /// Default: launch_flags
221 /// Empty launch flags
222 ///
223 /// Default: stdin_path
224 /// Default: stdout_path
225 /// Default: stderr_path
226 /// A pseudo terminal will be used.
227 ///
228 /// \return
229 /// A process object for the newly created process.
230 SBProcess LaunchSimple(const char **argv, const char **envp,
231 const char *working_directory);
232
233 SBProcess Launch(SBLaunchInfo &launch_info, SBError &error);
234
235 SBProcess Attach(SBAttachInfo &attach_info, SBError &error);
236
237 /// Attach to process with pid.
238 ///
239 /// \param[in] listener
240 /// An optional listener that will receive all process events.
241 /// If \a listener is valid then \a listener will listen to all
242 /// process events. If not valid, then this target's debugger
243 /// (SBTarget::GetDebugger()) will listen to all process events.
244 ///
245 /// \param[in] pid
246 /// The process ID to attach to.
247 ///
248 /// \param[out] error
249 /// An error explaining what went wrong if attach fails.
250 ///
251 /// \return
252 /// A process object for the attached process.
255
256 /// Attach to process with name.
257 ///
258 /// \param[in] listener
259 /// An optional listener that will receive all process events.
260 /// If \a listener is valid then \a listener will listen to all
261 /// process events. If not valid, then this target's debugger
262 /// (SBTarget::GetDebugger()) will listen to all process events.
263 ///
264 /// \param[in] name
265 /// Basename of process to attach to.
266 ///
267 /// \param[in] wait_for
268 /// If true wait for a new instance of 'name' to be launched.
269 ///
270 /// \param[out] error
271 /// An error explaining what went wrong if attach fails.
272 ///
273 /// \return
274 /// A process object for the attached process.
276 const char *name, bool wait_for,
278
279 /// Connect to a remote debug server with url.
280 ///
281 /// \param[in] listener
282 /// An optional listener that will receive all process events.
283 /// If \a listener is valid then \a listener will listen to all
284 /// process events. If not valid, then this target's debugger
285 /// (SBTarget::GetDebugger()) will listen to all process events.
286 ///
287 /// \param[in] url
288 /// The url to connect to, e.g., 'connect://localhost:12345'.
289 ///
290 /// \param[in] plugin_name
291 /// The plugin name to be used; can be nullptr.
292 ///
293 /// \param[out] error
294 /// An error explaining what went wrong if the connect fails.
295 ///
296 /// \return
297 /// A process object for the connected process.
298 lldb::SBProcess ConnectRemote(SBListener &listener, const char *url,
299 const char *plugin_name, SBError &error);
300
302
303 // Append the path mapping (from -> to) to the target's paths mapping list.
304 void AppendImageSearchPath(const char *from, const char *to,
306
307 bool AddModule(lldb::SBModule &module);
308
309 lldb::SBModule AddModule(const char *path, const char *triple,
310 const char *uuid);
311
312 lldb::SBModule AddModule(const char *path, const char *triple,
313 const char *uuid_cstr, const char *symfile);
314
315 lldb::SBModule AddModule(const SBModuleSpec &module_spec);
316
317 uint32_t GetNumModules() const;
318
319 lldb::SBModule GetModuleAtIndex(uint32_t idx);
320
321 bool RemoveModule(lldb::SBModule module);
322
324
326
327 /// Find a module with the given module specification.
328 ///
329 /// \param[in] module_spec
330 /// A lldb::SBModuleSpec object that contains module specification.
331 ///
332 /// \return
333 /// A lldb::SBModule object that represents the found module, or an
334 /// invalid SBModule object if no module was found.
335 lldb::SBModule FindModule(const lldb::SBModuleSpec &module_spec);
336
337 /// Find compile units related to *this target and passed source
338 /// file.
339 ///
340 /// \param[in] sb_file_spec
341 /// A lldb::SBFileSpec object that contains source file
342 /// specification.
343 ///
344 /// \return
345 /// A lldb::SBSymbolContextList that gets filled in with all of
346 /// the symbol contexts for all the matches.
348 FindCompileUnits(const lldb::SBFileSpec &sb_file_spec);
349
351
352 uint32_t GetAddressByteSize();
353
354 const char *GetTriple();
355
356 const char *GetABIName();
357
358 const char *GetLabel() const;
359
360 /// Get the globally unique ID for this target. This ID is unique
361 /// across all debugger instances within the same lldb process.
362 ///
363 /// \return
364 /// The globally unique ID for this target, or
365 /// LLDB_INVALID_GLOBALLY_UNIQUE_TARGET_ID if the target is invalid.
367
368 SBError SetLabel(const char *label);
369
370 /// Architecture opcode byte size width accessor
371 ///
372 /// \return
373 /// The minimum size in 8-bit (host) bytes of an opcode.
374 uint32_t GetMinimumOpcodeByteSize() const;
375
376 /// Architecture opcode byte size width accessor
377 ///
378 /// \return
379 /// The maximum size in 8-bit (host) bytes of an opcode.
380 uint32_t GetMaximumOpcodeByteSize() const;
381
382 /// Architecture data byte width accessor
383 ///
384 /// \return
385 /// The size in 8-bit (host) bytes of a minimum addressable
386 /// unit from the Architecture's data bus
387 uint32_t GetDataByteSize();
388
389 /// Architecture code byte width accessor
390 ///
391 /// \return
392 /// The size in 8-bit (host) bytes of a minimum addressable
393 /// unit from the Architecture's code bus
394 uint32_t GetCodeByteSize();
395
396 /// Gets the target.max-children-count value
397 /// It should be used to limit the number of
398 /// children of large data structures to be displayed.
400
401 /// Set the base load address for a module section.
402 ///
403 /// \param[in] section
404 /// The section whose base load address will be set within this
405 /// target.
406 ///
407 /// \param[in] section_base_addr
408 /// The base address for the section.
409 ///
410 /// \return
411 /// An error to indicate success, fail, and any reason for
412 /// failure.
414 lldb::addr_t section_base_addr);
415
416 /// Clear the base load address for a module section.
417 ///
418 /// \param[in] section
419 /// The section whose base load address will be cleared within
420 /// this target.
421 ///
422 /// \return
423 /// An error to indicate success, fail, and any reason for
424 /// failure.
426
427#ifndef SWIG
428 /// Slide all file addresses for all module sections so that \a module
429 /// appears to loaded at these slide addresses.
430 ///
431 /// When you need all sections within a module to be loaded at a
432 /// rigid slide from the addresses found in the module object file,
433 /// this function will allow you to easily and quickly slide all
434 /// module sections.
435 ///
436 /// \param[in] module
437 /// The module to load.
438 ///
439 /// \param[in] sections_offset
440 /// An offset that will be applied to all section file addresses
441 /// (the virtual addresses found in the object file itself).
442 ///
443 /// \return
444 /// An error to indicate success, fail, and any reason for
445 /// failure.
446 LLDB_DEPRECATED_FIXME("Use SetModuleLoadAddress(lldb::SBModule, uint64_t)",
447 "SetModuleLoadAddress(lldb::SBModule, uint64_t)")
449 int64_t sections_offset);
450#endif
451
452 /// Slide all file addresses for all module sections so that \a module
453 /// appears to loaded at these slide addresses.
454 ///
455 /// When you need all sections within a module to be loaded at a
456 /// rigid slide from the addresses found in the module object file,
457 /// this function will allow you to easily and quickly slide all
458 /// module sections.
459 ///
460 /// \param[in] module
461 /// The module to load.
462 ///
463 /// \param[in] sections_offset
464 /// An offset that will be applied to all section file addresses
465 /// (the virtual addresses found in the object file itself).
466 ///
467 /// \return
468 /// An error to indicate success, fail, and any reason for
469 /// failure.
471 uint64_t sections_offset);
472
473 /// Clear the section base load addresses for all sections in a module.
474 ///
475 /// \param[in] module
476 /// The module to unload.
477 ///
478 /// \return
479 /// An error to indicate success, fail, and any reason for
480 /// failure.
482
483 /// Find functions by name.
484 ///
485 /// \param[in] name
486 /// The name of the function we are looking for.
487 ///
488 /// \param[in] name_type_mask
489 /// A logical OR of one or more FunctionNameType enum bits that
490 /// indicate what kind of names should be used when doing the
491 /// lookup. Bits include fully qualified names, base names,
492 /// C++ methods, or ObjC selectors.
493 /// See FunctionNameType for more details.
494 ///
495 /// \return
496 /// A lldb::SBSymbolContextList that gets filled in with all of
497 /// the symbol contexts for all the matches.
499 FindFunctions(const char *name,
500 uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
501
502 /// Find global and static variables by name.
503 ///
504 /// \param[in] name
505 /// The name of the global or static variable we are looking
506 /// for.
507 ///
508 /// \param[in] max_matches
509 /// Allow the number of matches to be limited to \a max_matches.
510 ///
511 /// \return
512 /// A list of matched variables in an SBValueList.
513 lldb::SBValueList FindGlobalVariables(const char *name, uint32_t max_matches);
514
515 /// Find the first global (or static) variable by name.
516 ///
517 /// \param[in] name
518 /// The name of the global or static variable we are looking
519 /// for.
520 ///
521 /// \return
522 /// An SBValue that gets filled in with the found variable (if any).
523 lldb::SBValue FindFirstGlobalVariable(const char *name);
524
525 /// Find global and static variables by pattern.
526 ///
527 /// \param[in] name
528 /// The pattern to search for global or static variables
529 ///
530 /// \param[in] max_matches
531 /// Allow the number of matches to be limited to \a max_matches.
532 ///
533 /// \param[in] matchtype
534 /// The match type to use.
535 ///
536 /// \return
537 /// A list of matched variables in an SBValueList.
538 lldb::SBValueList FindGlobalVariables(const char *name, uint32_t max_matches,
539 MatchType matchtype);
540
541 /// Find global functions by their name with pattern matching.
542 ///
543 /// \param[in] name
544 /// The pattern to search for global or static variables
545 ///
546 /// \param[in] max_matches
547 /// Allow the number of matches to be limited to \a max_matches.
548 ///
549 /// \param[in] matchtype
550 /// The match type to use.
551 ///
552 /// \return
553 /// A list of matched variables in an SBValueList.
555 uint32_t max_matches,
556 MatchType matchtype);
557
558 void Clear();
559
560 /// Resolve a current file address into a section offset address.
561 ///
562 /// \param[in] file_addr
563 /// The file address to resolve.
564 ///
565 /// \return
566 /// An SBAddress which will be valid if...
568
569 /// Resolve a current load address into a section offset address.
570 ///
571 /// \param[in] vm_addr
572 /// A virtual address from the current process state that is to
573 /// be translated into a section offset address.
574 ///
575 /// \return
576 /// An SBAddress which will be valid if \a vm_addr was
577 /// successfully resolved into a section offset address, or an
578 /// invalid SBAddress if \a vm_addr doesn't resolve to a section
579 /// in a module.
581
582 /// Resolve a current load address into a section offset address
583 /// using the process stop ID to identify a time in the past.
584 ///
585 /// \param[in] stop_id
586 /// Each time a process stops, the process stop ID integer gets
587 /// incremented. These stop IDs are used to identify past times
588 /// and can be used in history objects as a cheap way to store
589 /// the time at which the sample was taken. Specifying
590 /// UINT32_MAX will always resolve the address using the
591 /// currently loaded sections.
592 ///
593 /// \param[in] vm_addr
594 /// A virtual address from the current process state that is to
595 /// be translated into a section offset address.
596 ///
597 /// \return
598 /// An SBAddress which will be valid if \a vm_addr was
599 /// successfully resolved into a section offset address, or an
600 /// invalid SBAddress if \a vm_addr doesn't resolve to a section
601 /// in a module.
603 lldb::addr_t vm_addr);
604
606 uint32_t resolve_scope);
607
608 /// Read target memory. If a target process is running then memory
609 /// is read from here. Otherwise the memory is read from the object
610 /// files. For a target whose bytes are sized as a multiple of host
611 /// bytes, the data read back will preserve the target's byte order.
612 ///
613 /// \param[in] addr
614 /// A target address to read from.
615 ///
616 /// \param[out] buf
617 /// The buffer to read memory into.
618 ///
619 /// \param[in] size
620 /// The maximum number of host bytes to read in the buffer passed
621 /// into this call
622 ///
623 /// \param[out] error
624 /// Status information is written here if the memory read fails.
625 ///
626 /// \return
627 /// The amount of data read in host bytes.
628 size_t ReadMemory(const SBAddress addr, void *buf, size_t size,
630
632 uint32_t line);
633
635 BreakpointCreateByLocation(const lldb::SBFileSpec &file_spec, uint32_t line);
636
638 BreakpointCreateByLocation(const lldb::SBFileSpec &file_spec, uint32_t line,
639 lldb::addr_t offset);
640
642 BreakpointCreateByLocation(const lldb::SBFileSpec &file_spec, uint32_t line,
643 lldb::addr_t offset, SBFileSpecList &module_list);
644
646 BreakpointCreateByLocation(const lldb::SBFileSpec &file_spec, uint32_t line,
647 uint32_t column, lldb::addr_t offset,
648 SBFileSpecList &module_list);
649
651 BreakpointCreateByLocation(const lldb::SBFileSpec &file_spec, uint32_t line,
652 uint32_t column, lldb::addr_t offset,
653 SBFileSpecList &module_list,
654 bool move_to_nearest_code);
655
656 lldb::SBBreakpoint BreakpointCreateByName(const char *symbol_name,
657 const char *module_name = nullptr);
658
659 // This version uses name_type_mask = eFunctionNameTypeAuto
661 BreakpointCreateByName(const char *symbol_name,
662 const SBFileSpecList &module_list,
663 const SBFileSpecList &comp_unit_list);
664
666 const char *symbol_name,
667 uint32_t
668 name_type_mask, // Logical OR one or more FunctionNameType enum bits
669 const SBFileSpecList &module_list,
670 const SBFileSpecList &comp_unit_list);
671
673 const char *symbol_name,
674 uint32_t
675 name_type_mask, // Logical OR one or more FunctionNameType enum bits
676 lldb::LanguageType symbol_language,
677 const SBFileSpecList &module_list, const SBFileSpecList &comp_unit_list);
678
680 const char *symbol_name,
681 uint32_t
682 name_type_mask, // Logical OR one or more FunctionNameType enum bits
683 lldb::LanguageType symbol_language, lldb::addr_t offset,
684 bool offset_is_insn_count, const SBFileSpecList &module_list,
685 const SBFileSpecList &comp_unit_list);
686
687#ifdef SWIG
689 const char **symbol_name, uint32_t num_names,
690 uint32_t
691 name_type_mask, // Logical OR one or more FunctionNameType enum bits
692 const SBFileSpecList &module_list,
693 const SBFileSpecList &comp_unit_list);
694
696 const char **symbol_name, uint32_t num_names,
697 uint32_t
698 name_type_mask, // Logical OR one or more FunctionNameType enum bits
699 lldb::LanguageType symbol_language,
700 const SBFileSpecList &module_list, const SBFileSpecList &comp_unit_list);
701
703 const char **symbol_name, uint32_t num_names,
704 uint32_t
705 name_type_mask, // Logical OR one or more FunctionNameType enum bits
706 lldb::LanguageType symbol_language,
707 lldb::addr_t offset, const SBFileSpecList &module_list,
708 const SBFileSpecList &comp_unit_list);
709#else
711 const char *symbol_name[], uint32_t num_names,
712 uint32_t
713 name_type_mask, // Logical OR one or more FunctionNameType enum bits
714 const SBFileSpecList &module_list,
715 const SBFileSpecList &comp_unit_list);
716
718 const char *symbol_name[], uint32_t num_names,
719 uint32_t
720 name_type_mask, // Logical OR one or more FunctionNameType enum bits
721 lldb::LanguageType symbol_language,
722 const SBFileSpecList &module_list, const SBFileSpecList &comp_unit_list);
723
725 const char *symbol_name[], uint32_t num_names,
726 uint32_t
727 name_type_mask, // Logical OR one or more FunctionNameType enum bits
728 lldb::LanguageType symbol_language,
729 lldb::addr_t offset, const SBFileSpecList &module_list,
730 const SBFileSpecList &comp_unit_list);
731#endif
732
733 lldb::SBBreakpoint BreakpointCreateByRegex(const char *symbol_name_regex,
734 const char *module_name = nullptr);
735
737 BreakpointCreateByRegex(const char *symbol_name_regex,
738 const SBFileSpecList &module_list,
739 const SBFileSpecList &comp_unit_list);
740
742 const char *symbol_name_regex, lldb::LanguageType symbol_language,
743 const SBFileSpecList &module_list, const SBFileSpecList &comp_unit_list);
744
746 BreakpointCreateBySourceRegex(const char *source_regex,
747 const SBFileSpec &source_file,
748 const char *module_name = nullptr);
749
751 BreakpointCreateBySourceRegex(const char *source_regex,
752 const SBFileSpecList &module_list,
753 const SBFileSpecList &source_file);
754
756 const char *source_regex, const SBFileSpecList &module_list,
757 const SBFileSpecList &source_file, const SBStringList &func_names);
758
760 bool catch_bp, bool throw_bp);
761
763
765
766 /// Create a breakpoint using a scripted resolver.
767 ///
768 /// \param[in] class_name
769 /// This is the name of the class that implements a scripted resolver.
770 ///
771 /// \param[in] extra_args
772 /// This is an SBStructuredData object that will get passed to the
773 /// constructor of the class in class_name. You can use this to
774 /// reuse the same class, parametrizing with entries from this
775 /// dictionary.
776 ///
777 /// \param module_list
778 /// If this is non-empty, this will be used as the module filter in the
779 /// SearchFilter created for this breakpoint.
780 ///
781 /// \param file_list
782 /// If this is non-empty, this will be used as the comp unit filter in the
783 /// SearchFilter created for this breakpoint.
784 ///
785 /// \return
786 /// An SBBreakpoint that will set locations based on the logic in the
787 /// resolver's search callback.
789 const char *class_name,
790 SBStructuredData &extra_args,
791 const SBFileSpecList &module_list,
792 const SBFileSpecList &file_list,
793 bool request_hardware = false);
794
795 /// Read breakpoints from source_file and return the newly created
796 /// breakpoints in bkpt_list.
797 ///
798 /// \param[in] source_file
799 /// The file from which to read the breakpoints.
800 ///
801 /// \param[out] new_bps
802 /// A list of the newly created breakpoints.
803 ///
804 /// \return
805 /// An SBError detailing any errors in reading in the breakpoints.
807 SBBreakpointList &new_bps);
808
809 /// Read breakpoints from source_file and return the newly created
810 /// breakpoints in bkpt_list.
811 ///
812 /// \param[in] source_file
813 /// The file from which to read the breakpoints.
814 ///
815 /// \param[in] matching_names
816 /// Only read in breakpoints whose names match one of the names in this
817 /// list.
818 ///
819 /// \param[out] new_bps
820 /// A list of the newly created breakpoints.
821 ///
822 /// \return
823 /// An SBError detailing any errors in reading in the breakpoints.
825 SBStringList &matching_names,
826 SBBreakpointList &new_bps);
827
828 /// Write breakpoints to dest_file.
829 ///
830 /// \param[in] dest_file
831 /// The file to which to write the breakpoints.
832 ///
833 /// \return
834 /// An SBError detailing any errors in writing in the breakpoints.
836
837 /// Write breakpoints listed in bkpt_list to dest_file.
838 ///
839 /// \param[in] dest_file
840 /// The file to which to write the breakpoints.
841 ///
842 /// \param[in] bkpt_list
843 /// Only write breakpoints from this list.
844 ///
845 /// \param[in] append
846 /// If \b true, append the breakpoints in bkpt_list to the others
847 /// serialized in dest_file. If dest_file doesn't exist, then a new
848 /// file will be created and the breakpoints in bkpt_list written to it.
849 ///
850 /// \return
851 /// An SBError detailing any errors in writing in the breakpoints.
853 SBBreakpointList &bkpt_list,
854 bool append = false);
855
856 uint32_t GetNumBreakpoints() const;
857
858 lldb::SBBreakpoint GetBreakpointAtIndex(uint32_t idx) const;
859
860 bool BreakpointDelete(break_id_t break_id);
861
863
864 // Finds all breakpoints by name, returning the list in bkpt_list. Returns
865 // false if the name is not a valid breakpoint name, true otherwise.
866 bool FindBreakpointsByName(const char *name, SBBreakpointList &bkpt_list);
867
868 void GetBreakpointNames(SBStringList &names);
869
870 void DeleteBreakpointName(const char *name);
871
873
875
877
878 uint32_t GetNumWatchpoints() const;
879
880 lldb::SBWatchpoint GetWatchpointAtIndex(uint32_t idx) const;
881
882 bool DeleteWatchpoint(lldb::watch_id_t watch_id);
883
885
886 LLDB_DEPRECATED("WatchAddress deprecated, use WatchpointCreateByAddress")
887 lldb::SBWatchpoint WatchAddress(lldb::addr_t addr, size_t size, bool read,
888 bool modify, SBError &error);
889
891 WatchpointCreateByAddress(lldb::addr_t addr, size_t size,
893
895
897
899
901
902 lldb::SBType FindFirstType(const char *type);
903
904 lldb::SBTypeList FindTypes(const char *type);
905
907
908 lldb::SBValue CreateValueFromAddress(const char *name, lldb::SBAddress addr,
909 lldb::SBType type);
910
911 lldb::SBValue CreateValueFromData(const char *name, lldb::SBData data,
912 lldb::SBType type);
913
914 lldb::SBValue CreateValueFromExpression(const char *name, const char *expr);
915
917
919 uint32_t count);
920
922 uint32_t count,
923 const char *flavor_string);
924
926 lldb::SBAddress end_addr,
927 const char *flavor_string);
928
930 const void *buf, size_t size);
931
932 // The "WithFlavor" is necessary to keep SWIG from getting confused about
933 // overloaded arguments when using the buf + size -> Python Object magic.
934
936 const char *flavor_string,
937 const void *buf,
938 size_t size);
939
940#ifndef SWIG
942 const void *buf, size_t size);
944 const char *flavor_string,
945 const void *buf,
946 size_t size);
947#endif
948
949 lldb::SBSymbolContextList FindSymbols(const char *name,
951
952 bool operator==(const lldb::SBTarget &rhs) const;
953
954 bool operator!=(const lldb::SBTarget &rhs) const;
955
956 bool GetDescription(lldb::SBStream &description,
957 lldb::DescriptionLevel description_level);
958
959 lldb::SBValue EvaluateExpression(const char *expr);
960
961 lldb::SBValue EvaluateExpression(const char *expr,
962 const SBExpressionOptions &options);
963
965
966 bool IsLoaded(const lldb::SBModule &module) const;
967
969
970 void SetLaunchInfo(const lldb::SBLaunchInfo &launch_info);
971
972 /// Get a \a SBTrace object the can manage the processor trace information of
973 /// this target.
974 ///
975 /// \return
976 /// The trace object. The returned SBTrace object might not be valid, so it
977 /// should be checked with a call to "bool SBTrace::IsValid()".
979
980 /// Create a \a Trace object for the current target using the using the
981 /// default supported tracing technology for this process.
982 ///
983 /// \param[out] error
984 /// An error if a Trace already exists or the trace couldn't be created.
986
988
989protected:
990 friend class SBAddress;
991 friend class SBAddressRange;
992 friend class SBBlock;
993 friend class SBBreakpoint;
994 friend class SBBreakpointList;
996 friend class SBDebugger;
997 friend class SBExecutionContext;
998 friend class SBFrame;
999 friend class SBFunction;
1000 friend class SBInstruction;
1001 friend class SBModule;
1002 friend class SBPlatform;
1003 friend class SBProcess;
1004 friend class SBSection;
1005 friend class SBSourceManager;
1006 friend class SBSymbol;
1007 friend class SBType;
1008 friend class SBTypeStaticField;
1009 friend class SBValue;
1011
1012 friend class lldb_private::python::SWIGBridge;
1013
1014 // Constructors are private, use static Target::Create function to create an
1015 // instance of this class.
1016
1017 SBTarget(const lldb::TargetSP &target_sp);
1018
1019 lldb::TargetSP GetSP() const;
1020
1021 void SetSP(const lldb::TargetSP &target_sp);
1022
1023private:
1025};
1026
1027} // namespace lldb
1028
1029#endif // LLDB_API_SBTARGET_H
static llvm::Expected< ValueObjectSP > EvaluateExpression(llvm::StringRef expression, StackFrame &frame, Process &process)
static llvm::raw_ostream & error(Stream &strm)
static llvm::Expected< lldb::addr_t > ResolveLoadAddress(ExecutionContext *exe_ctx, lldb::ModuleSP &module_sp, const char *dw_op_type, lldb::addr_t file_addr, Address &so_addr, bool check_sectionoffset=false)
Helper function to move common code used to resolve a file address and turn into a load address.
#define LLDB_API
Definition SBDefines.h:28
#define LLDB_DEPRECATED_FIXME(MSG, FIX)
Definition SBDefines.h:39
#define LLDB_DEPRECATED(MSG)
Definition SBDefines.h:38
This class handles the verbosity when dumping statistics.
SBSourceManager GetSourceManager()
bool AddModule(lldb::SBModule &module)
bool DisableAllBreakpoints()
uint32_t GetNumWatchpoints() const
bool GetDescription(lldb::SBStream &description, lldb::DescriptionLevel description_level)
lldb::SBError ClearSectionLoadAddress(lldb::SBSection section)
Clear the base load address for a module section.
bool DeleteWatchpoint(lldb::watch_id_t watch_id)
lldb::ByteOrder GetByteOrder()
uint32_t GetNumBreakpoints() const
lldb::SBInstructionList GetInstructionsWithFlavor(lldb::SBAddress base_addr, const char *flavor_string, const void *buf, size_t size)
void SetCollectingStats(bool v)
Sets whether we should collect statistics on lldb or not.
Definition SBTarget.cpp:226
bool BreakpointDelete(break_id_t break_id)
void SetSP(const lldb::TargetSP &target_sp)
Definition SBTarget.cpp:581
bool IsLoaded(const lldb::SBModule &module) const
const char * GetTriple()
static lldb::SBModule GetModuleAtIndexFromEvent(const uint32_t idx, const lldb::SBEvent &event)
Definition SBTarget.cpp:139
bool GetCollectingStats()
Returns whether statistics collection are enabled.
Definition SBTarget.cpp:233
lldb::SBBreakpoint BreakpointCreateByAddress(addr_t address)
Definition SBTarget.cpp:938
lldb::SBValue CreateValueFromExpression(const char *name, const char *expr)
lldb::SBSymbolContextList FindGlobalFunctions(const char *name, uint32_t max_matches, MatchType matchtype)
Find global functions by their name with pattern matching.
lldb::SBBreakpoint BreakpointCreateByRegex(const char *symbol_name_regex, const char *module_name=nullptr)
Definition SBTarget.cpp:892
lldb::SBTrace GetTrace()
Get a SBTrace object the can manage the processor trace information of this target.
@ eBroadcastBitModulesUnloaded
Definition SBTarget.h:43
@ eBroadcastBitSymbolsChanged
Definition SBTarget.h:46
@ eBroadcastBitSymbolsLoaded
Definition SBTarget.h:45
@ eBroadcastBitBreakpointChanged
Definition SBTarget.h:41
@ eBroadcastBitWatchpointChanged
Definition SBTarget.h:44
@ eBroadcastBitModulesLoaded
Definition SBTarget.h:42
const lldb::SBTarget & operator=(const lldb::SBTarget &rhs)
Definition SBTarget.cpp:108
const char * GetLabel() const
friend class SBProcess
Definition SBTarget.h:1003
static bool EventIsTargetEvent(const lldb::SBEvent &event)
Definition SBTarget.cpp:119
lldb::SBAddress ResolvePastLoadAddress(uint32_t stop_id, lldb::addr_t vm_addr)
Resolve a current load address into a section offset address using the process stop ID to identify a ...
Definition SBTarget.cpp:617
bool DisableAllWatchpoints()
lldb::addr_t GetStackRedZoneSize()
lldb::SBBreakpoint GetBreakpointAtIndex(uint32_t idx) const
SBError Install()
Install any binaries that need to be installed.
Definition SBTarget.cpp:295
lldb::SBSymbolContextList FindCompileUnits(const lldb::SBFileSpec &sb_file_spec)
Find compile units related to *this target and passed source file.
lldb::SBWatchpoint WatchpointCreateByAddress(lldb::addr_t addr, size_t size, lldb::SBWatchpointOptions options, SBError &error)
friend class SBInstruction
Definition SBTarget.h:1000
lldb::SBMutex GetAPIMutex() const
lldb::SBStructuredData GetStatistics()
Returns a dump of the collected statistics.
Definition SBTarget.cpp:197
lldb::SBModule GetModuleAtIndex(uint32_t idx)
SBError SetLabel(const char *label)
lldb::SBValueList FindGlobalVariables(const char *name, uint32_t max_matches)
Find global and static variables by name.
lldb::SBType GetBasicType(lldb::BasicType type)
lldb::SBFileSpec GetExecutable()
Definition SBTarget.cpp:554
const char * GetABIName()
friend class SBSymbol
Definition SBTarget.h:1006
friend class SBDebugger
Definition SBTarget.h:996
lldb::SBError SetSectionLoadAddress(lldb::SBSection section, lldb::addr_t section_base_addr)
Set the base load address for a module section.
friend class SBAddressRange
Definition SBTarget.h:991
friend class SBModule
Definition SBTarget.h:1001
lldb::SBProcess ConnectRemote(SBListener &listener, const char *url, const char *plugin_name, SBError &error)
Connect to a remote debug server with url.
Definition SBTarget.cpp:524
friend class SBBreakpoint
Definition SBTarget.h:993
lldb::SBBreakpoint BreakpointCreateByName(const char *symbol_name, const char *module_name=nullptr)
Definition SBTarget.cpp:758
friend class SBTypeStaticField
Definition SBTarget.h:1008
void DeleteBreakpointName(const char *name)
lldb::SBWatchpoint WatchAddress(lldb::addr_t addr, size_t size, bool read, bool modify, SBError &error)
SBProcess Attach(SBAttachInfo &attach_info, SBError &error)
Definition SBTarget.cpp:433
bool EnableAllWatchpoints()
lldb::SBBreakpoint BreakpointCreateBySBAddress(SBAddress &address)
Definition SBTarget.cpp:951
friend class SBValue
Definition SBTarget.h:1009
friend class SBAddress
Definition SBTarget.h:990
bool IsValid() const
Definition SBTarget.cpp:154
LLDB_DEPRECATED_FIXME("Use SetModuleLoadAddress(lldb::SBModule, uint64_t)", "SetModuleLoadAddress(lldb::SBModule, uint64_t)") lldb lldb::SBError SetModuleLoadAddress(lldb::SBModule module, uint64_t sections_offset)
Slide all file addresses for all module sections so that module appears to loaded at these slide addr...
lldb::SBProcess GetProcess()
Definition SBTarget.cpp:164
SBSymbolContext ResolveSymbolContextForAddress(const SBAddress &addr, uint32_t resolve_scope)
Definition SBTarget.cpp:636
lldb::SBProcess AttachToProcessWithID(SBListener &listener, lldb::pid_t pid, lldb::SBError &error)
Attach to process with pid.
Definition SBTarget.cpp:465
lldb::SBPlatform GetPlatform()
Return the platform object associated with the target.
Definition SBTarget.cpp:177
lldb::SBBreakpoint BreakpointCreateByLocation(const char *file, uint32_t line)
Definition SBTarget.cpp:669
lldb::SBBreakpoint BreakpointCreateForException(lldb::LanguageType language, bool catch_bp, bool throw_bp)
uint32_t GetNumModules() const
lldb::TargetSP GetSP() const
Definition SBTarget.cpp:579
friend class SBExecutionContext
Definition SBTarget.h:997
uint32_t GetDataByteSize()
Architecture data byte width accessor.
uint32_t GetMaximumNumberOfChildrenToDisplay() const
Gets the target.max-children-count value It should be used to limit the number of children of large d...
bool DeleteAllWatchpoints()
lldb::SBInstructionList GetInstructions(lldb::SBAddress base_addr, const void *buf, size_t size)
lldb::SBProcess Launch(SBListener &listener, char const **argv, char const **envp, const char *stdin_path, const char *stdout_path, const char *stderr_path, const char *working_directory, uint32_t launch_flags, bool stop_at_entry, lldb::SBError &error)
Launch a new process.
Definition SBTarget.cpp:306
bool RemoveModule(lldb::SBModule module)
lldb::SBSymbolContextList FindFunctions(const char *name, uint32_t name_type_mask=lldb::eFunctionNameTypeAny)
Find functions by name.
lldb::SBValue FindFirstGlobalVariable(const char *name)
Find the first global (or static) variable by name.
friend class SBBlock
Definition SBTarget.h:992
friend class SBVariablesOptions
Definition SBTarget.h:1010
lldb::SBBreakpoint BreakpointCreateFromScript(const char *class_name, SBStructuredData &extra_args, const SBFileSpecList &module_list, const SBFileSpecList &file_list, bool request_hardware=false)
Create a breakpoint using a scripted resolver.
static const char * GetBroadcasterClassName()
Definition SBTarget.cpp:148
SBEnvironment GetEnvironment()
Return the environment variables that would be used to launch a new process.
lldb::SBTypeList FindTypes(const char *type)
lldb::SBValue CreateValueFromAddress(const char *name, lldb::SBAddress addr, lldb::SBType type)
static lldb::SBTarget GetTargetFromEvent(const lldb::SBEvent &event)
Definition SBTarget.cpp:125
lldb::SBError BreakpointsCreateFromFile(SBFileSpec &source_file, SBBreakpointList &new_bps)
Read breakpoints from source_file and return the newly created breakpoints in bkpt_list.
uint32_t GetAddressByteSize()
bool operator==(const lldb::SBTarget &rhs) const
Definition SBTarget.cpp:567
bool operator!=(const lldb::SBTarget &rhs) const
Definition SBTarget.cpp:573
lldb::TargetSP m_opaque_sp
Definition SBTarget.h:1024
lldb::SBWatchpoint GetWatchpointAtIndex(uint32_t idx) const
lldb::SBLaunchInfo GetLaunchInfo() const
lldb::SBSymbolContextList FindSymbols(const char *name, lldb::SymbolType type=eSymbolTypeAny)
lldb::user_id_t GetGloballyUniqueID() const
Get the globally unique ID for this target.
void AppendImageSearchPath(const char *from, const char *to, lldb::SBError &error)
friend class SBFrame
Definition SBTarget.h:998
friend class SBBreakpointList
Definition SBTarget.h:994
lldb::SBTrace CreateTrace(SBError &error)
Create a Trace object for the current target using the using the default supported tracing technology...
lldb::SBBreakpoint BreakpointCreateBySourceRegex(const char *source_regex, const SBFileSpec &source_file, const char *module_name=nullptr)
Definition SBTarget.cpp:969
bool DeleteAllBreakpoints()
friend class SBSection
Definition SBTarget.h:1004
lldb::SBValue CreateValueFromData(const char *name, lldb::SBData data, lldb::SBType type)
void ResetStatistics()
Reset the statistics collected for this target.
Definition SBTarget.cpp:219
lldb::SBBroadcaster GetBroadcaster() const
uint32_t GetMinimumOpcodeByteSize() const
Architecture opcode byte size width accessor.
bool FindBreakpointsByName(const char *name, SBBreakpointList &bkpt_list)
friend class SBFunction
Definition SBTarget.h:999
size_t ReadMemory(const SBAddress addr, void *buf, size_t size, lldb::SBError &error)
Read target memory.
Definition SBTarget.cpp:653
lldb::SBBreakpoint BreakpointCreateByNames(const char *symbol_name[], uint32_t num_names, uint32_t name_type_mask, const SBFileSpecList &module_list, const SBFileSpecList &comp_unit_list)
Definition SBTarget.cpp:847
uint32_t GetMaximumOpcodeByteSize() const
Architecture opcode byte size width accessor.
SBProcess LaunchSimple(const char **argv, const char **envp, const char *working_directory)
Launch a new process with sensible defaults.
Definition SBTarget.cpp:271
lldb::SBModule FindModule(const lldb::SBFileSpec &file_spec)
friend class SBSourceManager
Definition SBTarget.h:1005
lldb::SBBreakpoint FindBreakpointByID(break_id_t break_id)
friend class SBType
Definition SBTarget.h:1007
lldb::SBInstructionList ReadInstructions(lldb::SBAddress base_addr, uint32_t count)
void GetBreakpointNames(SBStringList &names)
lldb::SBDebugger GetDebugger() const
Definition SBTarget.cpp:188
friend class SBPlatform
Definition SBTarget.h:1002
lldb::SBError BreakpointsWriteToFile(SBFileSpec &dest_file)
Write breakpoints to dest_file.
lldb::SBWatchpoint FindWatchpointByID(lldb::watch_id_t watch_id)
lldb::SBAddress ResolveFileAddress(lldb::addr_t file_addr)
Resolve a current file address into a section offset address.
Definition SBTarget.cpp:602
friend class SBBreakpointNameImpl
Definition SBTarget.h:995
void SetLaunchInfo(const lldb::SBLaunchInfo &launch_info)
lldb::SBError ClearModuleLoadAddress(lldb::SBModule module)
Clear the section base load addresses for all sections in a module.
lldb::SBType FindFirstType(const char *type)
uint32_t GetCodeByteSize()
Architecture code byte width accessor.
lldb::SBProcess AttachToProcessWithName(SBListener &listener, const char *name, bool wait_for, lldb::SBError &error)
Attach to process with name.
Definition SBTarget.cpp:492
SBProcess LoadCore(const char *core_file)
Definition SBTarget.cpp:241
static uint32_t GetNumModulesFromEvent(const lldb::SBEvent &event)
Definition SBTarget.cpp:131
bool EnableAllBreakpoints()
A class that represents a running process on the host machine.
MatchType
String matching algorithm used by SBTarget.
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
BasicType
Basic types enumeration for the public API SBType::GetBasicType().
LanguageType
Programming language type.
int32_t break_id_t
Definition lldb-types.h:86
SymbolType
Symbol types.
uint64_t pid_t
Definition lldb-types.h:83
ByteOrder
Byte ordering definitions.
int32_t watch_id_t
Definition lldb-types.h:87
uint64_t user_id_t
Definition lldb-types.h:82
uint64_t addr_t
Definition lldb-types.h:80
std::shared_ptr< lldb_private::Target > TargetSP