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