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