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

source code of lldb/include/lldb/API/SBDebugger.h