1 //===-- SWIG Interface for SBDebugger ---------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
12 "SBDebugger is the primordial object that creates SBTargets and provides
13 access to them. It also manages the overall debugging experiences.
15 For example (from example/disasm.py),
21 def disassemble_instructions (insts):
27 # Create a new debugger instance
28 debugger = lldb.SBDebugger.Create()
30 # When we step or continue, don't return from the function until the process
31 # stops. We do this by setting the async mode to false.
32 debugger.SetAsync (False)
34 # Create a target from a file and arch
35 print('Creating a target for \'%s\'' % exe)
37 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
40 # If the target is valid set a breakpoint at main
41 main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());
45 # Launch the process. Since we specified synchronous mode, we won't return
46 # from this function until we hit the breakpoint at main
47 process = target.LaunchSimple (None, None, os.getcwd())
49 # Make sure the launch went ok
51 # Print some simple process info
52 state = process.GetState ()
54 if state == lldb.eStateStopped:
55 # Get the first thread
56 thread = process.GetThreadAtIndex (0)
58 # Print some simple thread info
61 frame = thread.GetFrameAtIndex (0)
63 # Print some simple frame info
65 function = frame.GetFunction()
66 # See if we have debug info (a function)
68 # We do have a function, print some info for the function
70 # Now get all instructions for this function and print them
71 insts = function.GetInstructions(target)
72 disassemble_instructions (insts)
74 # See if we have a symbol in the symbol table for where we stopped
75 symbol = frame.GetSymbol();
77 # We do have a symbol, print some info for the symbol
79 # Now get all instructions for this symbol and print them
80 insts = symbol.GetInstructions(target)
81 disassemble_instructions (insts)
83 registerList = frame.GetRegisters()
84 print('Frame registers (size of register set = %d):' % registerList.GetSize())
85 for value in registerList:
87 print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren()))
89 print('Name: ', child.GetName(), ' Value: ', child.GetValue())
91 print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program')
92 next = sys.stdin.readline()
93 if not next or next.rstrip('\n') == 'quit':
94 print('Terminating the inferior process...')
97 # Now continue to the program exit
99 # When we return from the above function we will hopefully be at the
100 # program exit. Print out some process info
102 elif state == lldb.eStateExited:
103 print('Didn\'t hit the breakpoint at main, program has exited...')
105 print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state))
108 Sometimes you need to create an empty target that will get filled in later. The most common use for this
109 is to attach to a process by name or pid where you don't know the executable up front. The most convenient way
112 target = debugger.CreateTarget('')
113 error = lldb.SBError()
114 process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error)
116 or the equivalent arguments for AttachToProcessWithID.") SBDebugger;
125 InitializeWithErrorHandling();
130 static lldb::SBDebugger
133 static lldb::SBDebugger
134 Create(bool source_init_files);
136 static lldb::SBDebugger
137 Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton);
140 Destroy (lldb::SBDebugger &debugger);
143 MemoryPressureDetected();
147 SBDebugger(const lldb::SBDebugger &rhs);
154 explicit operator bool() const;
166 SkipLLDBInitFiles (bool b);
170 def SetOutputFileHandle(self, file, transfer_ownership):
171 "DEPRECATED, use SetOutputFile"
175 self.SetOutputFile(SBFile.Create(file, borrow=True))
177 def SetInputFileHandle(self, file, transfer_ownership):
178 "DEPRECATED, use SetInputFile"
182 self.SetInputFile(SBFile.Create(file, borrow=True))
184 def SetErrorFileHandle(self, file, transfer_ownership):
185 "DEPRECATED, use SetErrorFile"
189 self.SetErrorFile(SBFile.Create(file, borrow=True))
196 lldb::FileSP GetInputFileHandle() {
197 return self->GetInputFile().GetFile();
200 lldb::FileSP GetOutputFileHandle() {
201 return self->GetOutputFile().GetFile();
204 lldb::FileSP GetErrorFileHandle() {
205 return self->GetErrorFile().GetFile();
210 SetInputFile (SBFile file);
213 SetOutputFile (SBFile file);
216 SetErrorFile (SBFile file);
219 SetInputFile (FileSP file);
222 SetOutputFile (FileSP file);
225 SetErrorFile (FileSP file);
236 lldb::SBCommandInterpreter
237 GetCommandInterpreter ();
240 HandleCommand (const char *command);
246 HandleProcessEvent (const lldb::SBProcess &process,
247 const lldb::SBEvent &event,
252 HandleProcessEvent (const lldb::SBProcess &process,
253 const lldb::SBEvent &event,
258 CreateTarget (const char *filename,
259 const char *target_triple,
260 const char *platform_name,
261 bool add_dependent_modules,
262 lldb::SBError& sb_error);
265 CreateTargetWithFileAndTargetTriple (const char *filename,
266 const char *target_triple);
269 CreateTargetWithFileAndArch (const char *filename,
270 const char *archname);
273 CreateTarget (const char *filename);
275 %feature("docstring",
276 "The dummy target holds breakpoints and breakpoint names that will prime newly created targets."
278 lldb::SBTarget GetDummyTarget();
280 %feature("docstring",
281 "Return true if target is deleted from the target list of the debugger."
284 DeleteTarget (lldb::SBTarget &target);
287 GetTargetAtIndex (uint32_t idx);
290 GetIndexOfTarget (lldb::SBTarget target);
293 FindTargetWithProcessID (pid_t pid);
296 FindTargetWithFileAndArch (const char *filename,
303 GetSelectedTarget ();
306 SetSelectedTarget (lldb::SBTarget &target);
309 GetSelectedPlatform();
312 SetSelectedPlatform(lldb::SBPlatform &platform);
314 %feature("docstring",
315 "Get the number of currently active platforms."
320 %feature("docstring",
321 "Get one of the currently active platforms."
322 ) GetPlatformAtIndex;
324 GetPlatformAtIndex (uint32_t idx);
326 %feature("docstring",
327 "Get the number of available platforms."
328 ) GetNumAvailablePlatforms;
330 GetNumAvailablePlatforms ();
332 %feature("docstring", "
333 Get the name and description of one of the available platforms.
335 @param idx Zero-based index of the platform for which info should be
336 retrieved, must be less than the value returned by
337 GetNumAvailablePlatforms().") GetAvailablePlatformInfoAtIndex;
338 lldb::SBStructuredData
339 GetAvailablePlatformInfoAtIndex (uint32_t idx);
341 lldb::SBSourceManager
344 // REMOVE: just for a quick fix, need to expose platforms through
345 // SBPlatform from this class.
347 SetCurrentPlatform (const char *platform_name);
350 SetCurrentPlatformSDKRoot (const char *sysroot);
352 // FIXME: Once we get the set show stuff in place, the driver won't need
353 // an interface to the Set/Get UseExternalEditor.
355 SetUseExternalEditor (bool input);
358 GetUseExternalEditor ();
361 SetUseColor (bool use_color);
364 GetUseColor () const;
367 GetDefaultArchitecture (char *arch_name, size_t arch_name_len);
370 SetDefaultArchitecture (const char *arch_name);
373 GetScriptingLanguage (const char *script_language_name);
379 StateAsCString (lldb::StateType state);
381 static SBStructuredData GetBuildConfiguration();
384 StateIsRunningState (lldb::StateType state);
387 StateIsStoppedState (lldb::StateType state);
390 EnableLog (const char *channel, const char ** types);
393 SetLoggingCallback (lldb::LogOutputCallback log_callback, void *baton);
396 DispatchInput (const void *data, size_t data_len);
399 DispatchInputInterrupt ();
402 DispatchInputEndOfFile ();
408 FindDebuggerWithID (int id);
411 SetInternalVariable (const char *var_name, const char *value, const char *debugger_instance_name);
413 static lldb::SBStringList
414 GetInternalVariableValue (const char *var_name, const char *debugger_instance_name);
417 GetDescription (lldb::SBStream &description);
420 GetTerminalWidth () const;
423 SetTerminalWidth (uint32_t term_width);
432 SetPrompt (const char *prompt);
435 GetReproducerPath() const;
438 GetScriptLanguage() const;
441 SetScriptLanguage (lldb::ScriptLanguage script_lang);
444 GetCloseInputOnEOF () const;
447 SetCloseInputOnEOF (bool b);
450 GetCategory (const char* category_name);
453 GetCategory (lldb::LanguageType lang_type);
456 CreateCategory (const char* category_name);
459 DeleteCategory (const char* category_name);
465 GetCategoryAtIndex (uint32_t);
468 GetDefaultCategory();
471 GetFormatForType (lldb::SBTypeNameSpecifier);
474 GetSummaryForType (lldb::SBTypeNameSpecifier);
477 GetFilterForType (lldb::SBTypeNameSpecifier);
479 lldb::SBTypeSynthetic
480 GetSyntheticForType (lldb::SBTypeNameSpecifier);
482 STRING_EXTENSION(SBDebugger)
484 %feature("docstring",
485 "Launch a command interpreter session. Commands are read from standard input or
486 from the input handle specified for the debugger object. Output/errors are
487 similarly redirected to standard output/error or the configured handles.
489 @param[in] auto_handle_events If true, automatically handle resulting events.
490 @param[in] spawn_thread If true, start a new thread for IO handling.
491 @param[in] options Parameter collection of type SBCommandInterpreterRunOptions.
492 @param[in] num_errors Initial error counter.
493 @param[in] quit_requested Initial quit request flag.
494 @param[in] stopped_for_crash Initial crash flag.
497 A tuple with the number of errors encountered by the interpreter, a boolean
498 indicating whether quitting the interpreter was requested and another boolean
499 set to True in case of a crash.
503 # Start an interactive lldb session from a script (with a valid debugger object
504 # created beforehand):
505 n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True,
506 False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter;
507 %apply int& INOUT { int& num_errors };
508 %apply bool& INOUT { bool& quit_requested };
509 %apply bool& INOUT { bool& stopped_for_crash };
511 RunCommandInterpreter (bool auto_handle_events,
513 SBCommandInterpreterRunOptions &options,
515 bool &quit_requested,
516 bool &stopped_for_crash);
519 RunREPL (lldb::LanguageType language, const char *repl_options);
524 '''Iterate over all targets in a lldb.SBDebugger object.'''
525 return lldb_iter(self, 'GetNumTargets', 'GetTargetAtIndex')
528 '''Return the number of targets in a lldb.SBDebugger object.'''
529 return self.GetNumTargets()
533 }; // class SBDebugger