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