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