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