LLDB  mainline
SBDebugger.h
Go to the documentation of this file.
1 //===-- SBDebugger.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_SBDEBUGGER_H
10 #define LLDB_API_SBDEBUGGER_H
11 
12 #include <cstdio>
13 
14 #include "lldb/API/SBDefines.h"
15 #include "lldb/API/SBPlatform.h"
16 
17 namespace lldb {
18 
20 public:
21  SBInputReader() = default;
22  ~SBInputReader() = default;
23 
24  SBError Initialize(lldb::SBDebugger &sb_debugger,
25  unsigned long (*callback)(void *, lldb::SBInputReader *,
27  char const *, unsigned long),
28  void *a, lldb::InputReaderGranularity b, char const *c,
29  char const *d, bool e);
30  void SetIsDone(bool);
31  bool IsActive() const;
32 };
33 
35 public:
37  eBroadcastBitProgress = (1 << 0),
38  eBroadcastBitWarning = (1 << 1),
39  eBroadcastBitError = (1 << 2),
40  };
41 
42  SBDebugger();
43 
44  SBDebugger(const lldb::SBDebugger &rhs);
45 
46  SBDebugger(const lldb::DebuggerSP &debugger_sp);
47 
48  ~SBDebugger();
49 
50  static const char *GetBroadcasterClass();
51 
52  lldb::SBBroadcaster GetBroadcaster();
53 
54  /// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
55  ///
56  /// \param [in] event
57  /// The event to extract the progress information from.
58  ///
59  /// \param [out] progress_id
60  /// The unique integer identifier for the progress to report.
61  ///
62  /// \param [out] completed
63  /// The amount of work completed. If \a completed is zero, then this event
64  /// is a progress started event. If \a completed is equal to \a total, then
65  /// this event is a progress end event. Otherwise completed indicates the
66  /// current progress update.
67  ///
68  /// \param [out] total
69  /// The total amount of work units that need to be completed. If this value
70  /// is UINT64_MAX, then an indeterminate progress indicator should be
71  /// displayed.
72  ///
73  /// \param [out] is_debugger_specific
74  /// Set to true if this progress is specific to this debugger only. Many
75  /// progress events are not specific to a debugger instance, like any
76  /// progress events for loading information in modules since LLDB has a
77  /// global module cache that all debuggers use.
78  ///
79  /// \return The message for the progress. If the returned value is NULL, then
80  /// \a event was not a eBroadcastBitProgress event.
81  static const char *GetProgressFromEvent(const lldb::SBEvent &event,
82  uint64_t &progress_id,
83  uint64_t &completed, uint64_t &total,
84  bool &is_debugger_specific);
85 
87  GetDiagnosticFromEvent(const lldb::SBEvent &event);
88 
89  lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
90 
91  static void Initialize();
92 
93  static lldb::SBError InitializeWithErrorHandling();
94 
95  static void PrintStackTraceOnError();
96 
97  static void Terminate();
98 
99  // Deprecated, use the one that takes a source_init_files bool.
100  static lldb::SBDebugger Create();
101 
102  static lldb::SBDebugger Create(bool source_init_files);
103 
104  static lldb::SBDebugger Create(bool source_init_files,
105  lldb::LogOutputCallback log_callback,
106  void *baton);
107 
108  static void Destroy(lldb::SBDebugger &debugger);
109 
110  static void MemoryPressureDetected();
111 
112  explicit operator bool() const;
113 
114  bool IsValid() const;
115 
116  void Clear();
117 
118  void SetAsync(bool b);
119 
120  bool GetAsync();
121 
122  void SkipLLDBInitFiles(bool b);
123 
124  void SkipAppInitFiles(bool b);
125 
126  void SetInputFileHandle(FILE *f, bool transfer_ownership);
127 
128  void SetOutputFileHandle(FILE *f, bool transfer_ownership);
129 
130  void SetErrorFileHandle(FILE *f, bool transfer_ownership);
131 
132  FILE *GetInputFileHandle();
133 
134  FILE *GetOutputFileHandle();
135 
136  FILE *GetErrorFileHandle();
137 
138  SBError SetInputString(const char *data);
139 
140  SBError SetInputFile(SBFile file);
141 
142  SBError SetOutputFile(SBFile file);
143 
144  SBError SetErrorFile(SBFile file);
145 
146  SBError SetInputFile(FileSP file);
147 
148  SBError SetOutputFile(FileSP file);
149 
150  SBError SetErrorFile(FileSP file);
151 
152  SBFile GetInputFile();
153 
154  SBFile GetOutputFile();
155 
156  SBFile GetErrorFile();
157 
158  void SaveInputTerminalState();
159 
160  void RestoreInputTerminalState();
161 
162  lldb::SBCommandInterpreter GetCommandInterpreter();
163 
164  void HandleCommand(const char *command);
165 
166  lldb::SBListener GetListener();
167 
168  void HandleProcessEvent(const lldb::SBProcess &process,
169  const lldb::SBEvent &event, FILE *out,
170  FILE *err); // DEPRECATED
171 
172  void HandleProcessEvent(const lldb::SBProcess &process,
173  const lldb::SBEvent &event, SBFile out, SBFile err);
174 
175  void HandleProcessEvent(const lldb::SBProcess &process,
176  const lldb::SBEvent &event, FileSP out, FileSP err);
177 
178  lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
179  const char *platform_name,
180  bool add_dependent_modules, lldb::SBError &error);
181 
182  lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
183  const char *target_triple);
184 
185  lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
186  const char *archname);
187 
188  lldb::SBTarget CreateTarget(const char *filename);
189 
190  lldb::SBTarget GetDummyTarget();
191 
192  // Return true if target is deleted from the target list of the debugger.
193  bool DeleteTarget(lldb::SBTarget &target);
194 
195  lldb::SBTarget GetTargetAtIndex(uint32_t idx);
196 
197  uint32_t GetIndexOfTarget(lldb::SBTarget target);
198 
199  lldb::SBTarget FindTargetWithProcessID(pid_t pid);
200 
201  lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
202  const char *arch);
203 
204  uint32_t GetNumTargets();
205 
206  lldb::SBTarget GetSelectedTarget();
207 
208  void SetSelectedTarget(SBTarget &target);
209 
210  lldb::SBPlatform GetSelectedPlatform();
211 
212  void SetSelectedPlatform(lldb::SBPlatform &platform);
213 
214  /// Get the number of currently active platforms.
215  uint32_t GetNumPlatforms();
216 
217  /// Get one of the currently active platforms.
218  lldb::SBPlatform GetPlatformAtIndex(uint32_t idx);
219 
220  /// Get the number of available platforms.
221  ///
222  /// The return value should match the number of entries output by the
223  /// "platform list" command.
224  uint32_t GetNumAvailablePlatforms();
225 
226  /// Get the name and description of one of the available platforms.
227  ///
228  /// \param[in] idx
229  /// Zero-based index of the platform for which info should be retrieved,
230  /// must be less than the value returned by GetNumAvailablePlatforms().
231  lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
232 
233  lldb::SBSourceManager GetSourceManager();
234 
235  // REMOVE: just for a quick fix, need to expose platforms through
236  // SBPlatform from this class.
237  lldb::SBError SetCurrentPlatform(const char *platform_name);
238 
239  bool SetCurrentPlatformSDKRoot(const char *sysroot);
240 
241  // FIXME: Once we get the set show stuff in place, the driver won't need
242  // an interface to the Set/Get UseExternalEditor.
243  bool SetUseExternalEditor(bool input);
244 
245  bool GetUseExternalEditor();
246 
247  bool SetUseColor(bool use_color);
248 
249  bool GetUseColor() const;
250 
251  bool SetUseSourceCache(bool use_source_cache);
252 
253  bool GetUseSourceCache() const;
254 
255  static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len);
256 
257  static bool SetDefaultArchitecture(const char *arch_name);
258 
259  lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name);
260 
261  SBStructuredData GetScriptInterpreterInfo(ScriptLanguage);
262 
263  static const char *GetVersionString();
264 
265  static const char *StateAsCString(lldb::StateType state);
266 
267  static SBStructuredData GetBuildConfiguration();
268 
269  static bool StateIsRunningState(lldb::StateType state);
270 
271  static bool StateIsStoppedState(lldb::StateType state);
272 
273  bool EnableLog(const char *channel, const char **categories);
274 
275  void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
276 
277  // DEPRECATED
278  void DispatchInput(void *baton, const void *data, size_t data_len);
279 
280  void DispatchInput(const void *data, size_t data_len);
281 
282  void DispatchInputInterrupt();
283 
284  void DispatchInputEndOfFile();
285 
286  void PushInputReader(lldb::SBInputReader &reader);
287 
288  const char *GetInstanceName();
289 
290  static SBDebugger FindDebuggerWithID(int id);
291 
292  static lldb::SBError SetInternalVariable(const char *var_name,
293  const char *value,
294  const char *debugger_instance_name);
295 
296  static lldb::SBStringList
297  GetInternalVariableValue(const char *var_name,
298  const char *debugger_instance_name);
299 
300  bool GetDescription(lldb::SBStream &description);
301 
302  uint32_t GetTerminalWidth() const;
303 
304  void SetTerminalWidth(uint32_t term_width);
305 
306  lldb::user_id_t GetID();
307 
308  const char *GetPrompt() const;
309 
310  void SetPrompt(const char *prompt);
311 
312  const char *GetReproducerPath() const;
313 
314  lldb::ScriptLanguage GetScriptLanguage() const;
315 
316  void SetScriptLanguage(lldb::ScriptLanguage script_lang);
317 
318  lldb::LanguageType GetREPLLanguage() const;
319 
320  void SetREPLLanguage(lldb::LanguageType repl_lang);
321 
322  bool GetCloseInputOnEOF() const;
323 
324  void SetCloseInputOnEOF(bool b);
325 
326  SBTypeCategory GetCategory(const char *category_name);
327 
328  SBTypeCategory GetCategory(lldb::LanguageType lang_type);
329 
330  SBTypeCategory CreateCategory(const char *category_name);
331 
332  bool DeleteCategory(const char *category_name);
333 
334  uint32_t GetNumCategories();
335 
336  SBTypeCategory GetCategoryAtIndex(uint32_t);
337 
338  SBTypeCategory GetDefaultCategory();
339 
340  SBTypeFormat GetFormatForType(SBTypeNameSpecifier);
341 
342  SBTypeSummary GetSummaryForType(SBTypeNameSpecifier);
343 
344  SBTypeFilter GetFilterForType(SBTypeNameSpecifier);
345 
346  SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier);
347 
348  /// Run the command interpreter.
349  ///
350  /// \param[in] auto_handle_events
351  /// If true, automatically handle resulting events. This takes precedence
352  /// and overrides the corresponding option in
353  /// SBCommandInterpreterRunOptions.
354  ///
355  /// \param[in] spawn_thread
356  /// If true, start a new thread for IO handling. This takes precedence
357  /// and overrides the corresponding option in
358  /// SBCommandInterpreterRunOptions.
359  void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread);
360 
361  /// Run the command interpreter.
362  ///
363  /// \param[in] auto_handle_events
364  /// If true, automatically handle resulting events. This takes precedence
365  /// and overrides the corresponding option in
366  /// SBCommandInterpreterRunOptions.
367  ///
368  /// \param[in] spawn_thread
369  /// If true, start a new thread for IO handling. This takes precedence
370  /// and overrides the corresponding option in
371  /// SBCommandInterpreterRunOptions.
372  ///
373  /// \param[in] options
374  /// Parameter collection of type SBCommandInterpreterRunOptions.
375  ///
376  /// \param[out] num_errors
377  /// The number of errors.
378  ///
379  /// \param[out] quit_requested
380  /// Whether a quit was requested.
381  ///
382  /// \param[out] stopped_for_crash
383  /// Whether the interpreter stopped for a crash.
384  void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread,
386  int &num_errors, bool &quit_requested,
387  bool &stopped_for_crash);
388 
390  RunCommandInterpreter(const SBCommandInterpreterRunOptions &options);
391 
392  SBError RunREPL(lldb::LanguageType language, const char *repl_options);
393 
394  /// Load a trace from a trace description file and create Targets,
395  /// Processes and Threads based on the contents of such file.
396  ///
397  /// \param[out] error
398  /// An error if the trace could not be created.
399  ///
400  /// \param[in] trace_description_file
401  /// The file containing the necessary information to load the trace.
402  SBTrace LoadTraceFromFile(SBError &error,
403  const SBFileSpec &trace_description_file);
404 
405 private:
406  friend class SBCommandInterpreter;
407  friend class SBInputReader;
408  friend class SBListener;
409  friend class SBProcess;
410  friend class SBSourceManager;
411  friend class SBTarget;
412  friend class SBTrace;
413 
414  lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
415 
416  void reset(const lldb::DebuggerSP &debugger_sp);
417 
418  lldb_private::Debugger *get() const;
419 
420  lldb_private::Debugger &ref() const;
421 
422  const lldb::DebuggerSP &get_sp() const;
423 
424  lldb::DebuggerSP m_opaque_sp;
425 
426 }; // class SBDebugger
427 
428 } // namespace lldb
429 
430 #endif // LLDB_API_SBDEBUGGER_H
lldb::SBStringList
Definition: SBStringList.h:16
lldb::SBCommandInterpreterRunResult
Definition: SBCommandInterpreterRunOptions.h:85
lldb::SBTypeNameSpecifier
Definition: SBTypeNameSpecifier.h:17
lldb::ScriptLanguage
ScriptLanguage
Script interpreter types.
Definition: lldb-enumerations.h:216
lldb::SBTypeFilter
Definition: SBTypeFilter.h:17
SBDefines.h
lldb::LogOutputCallback
void(* LogOutputCallback)(const char *, void *baton)
Definition: lldb-types.h:70
lldb::SBError
Definition: SBError.h:20
lldb::SBCommandInterpreter
Definition: SBCommandInterpreter.h:19
lldb::SBInputReader
Definition: SBDebugger.h:19
lldb::SBDebugger
class LLDB_API SBDebugger
Definition: SBDefines.h:49
lldb_private::StateAsCString
const char * StateAsCString(lldb::StateType state)
Converts a StateType to a C string.
Definition: State.cpp:14
lldb::LanguageType
LanguageType
Programming language type.
Definition: lldb-enumerations.h:436
lldb_private::StateIsRunningState
bool StateIsRunningState(lldb::StateType state)
Check if a state represents a state where the process or thread is running.
Definition: State.cpp:68
lldb::SBEvent
Definition: SBEvent.h:21
lldb::SBProcess
Definition: SBProcess.h:23
lldb::SBTypeSummary
Definition: SBTypeSummary.h:55
lldb::SBTrace
Definition: SBTrace.h:17
lldb::SBTarget
Definition: SBTarget.h:29
error
static llvm::raw_ostream & error(Stream &strm)
Definition: CommandReturnObject.cpp:17
lldb::SBFile
Definition: SBFile.h:16
lldb::SBDebugger::FLAGS_ANONYMOUS_ENUM
FLAGS_ANONYMOUS_ENUM()
Definition: SBDebugger.h:36
lldb::InputReaderAction
InputReaderAction
Definition: lldb-enumerations.h:385
lldb_private::StateIsStoppedState
bool StateIsStoppedState(lldb::StateType state, bool must_exist)
Check if a state represents a state where the process or thread is stopped.
Definition: State.cpp:89
lldb::SBDebugger
Definition: SBDebugger.h:34
lldb::SBTypeFormat
Definition: SBTypeFormat.h:17
lldb_private::Debugger
Definition: Debugger.h:74
lldb::SBListener
Definition: SBListener.h:16
uint32_t
lldb::SBStructuredData
Definition: SBStructuredData.h:17
lldb::pid_t
uint64_t pid_t
Definition: lldb-types.h:85
lldb::SBTypeSynthetic
Definition: SBTypeSynthetic.h:17
lldb::SBFileSpec
Definition: SBFileSpec.h:16
lldb::user_id_t
uint64_t user_id_t
Definition: lldb-types.h:84
lldb::SBBroadcaster
Definition: SBBroadcaster.h:16
lldb::SBCommandInterpreterRunOptions
Definition: SBCommandInterpreterRunOptions.h:23
lldb::InputReaderGranularity
InputReaderGranularity
Token size/granularities for Input Readers.
Definition: lldb-enumerations.h:329
lldb::StateType
StateType
Process and Thread States.
Definition: lldb-enumerations.h:73
lldb::SBDebugger::m_opaque_sp
lldb::DebuggerSP m_opaque_sp
Definition: SBDebugger.h:424
lldb::SBStream
Definition: SBStream.h:18
lldb::SBPlatform
Definition: SBPlatform.h:93
lldb::SBTypeCategory
Definition: SBTypeCategory.h:17
lldb
Definition: SBAddress.h:15
SBPlatform.h
LLDB_API
#define LLDB_API
Definition: SBDefines.h:26
lldb::SBSourceManager
Definition: SBSourceManager.h:18