contrib/llvm-project/lldb/bindings/interface/SBDebugger.i

   1 //===-- SWIG Interface for SBDebugger ---------------------------*- 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 namespace lldb {
  10
  11 %feature("docstring",
  12 "SBDebugger is the primordial object that creates SBTargets and provides
  13 access to them.  It also manages the overall debugging experiences.
  14
  15 For example (from example/disasm.py),
  16
  17 import lldb
  18 import os
  19 import sys
  20
  21 def disassemble_instructions (insts):
  22     for i in insts:
  23         print i
  24
  25 ...
  26
  27 # Create a new debugger instance
  28 debugger = lldb.SBDebugger.Create()
  29
  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)
  33
  34 # Create a target from a file and arch
  35 print('Creating a target for \'%s\'' % exe)
  36
  37 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
  38
  39 if target:
  40     # If the target is valid set a breakpoint at main
  41     main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());
  42
  43     print main_bp
  44
  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())
  48
  49     # Make sure the launch went ok
  50     if process:
  51         # Print some simple process info
  52         state = process.GetState ()
  53         print process
  54         if state == lldb.eStateStopped:
  55             # Get the first thread
  56             thread = process.GetThreadAtIndex (0)
  57             if thread:
  58                 # Print some simple thread info
  59                 print thread
  60                 # Get the first frame
  61                 frame = thread.GetFrameAtIndex (0)
  62                 if frame:
  63                     # Print some simple frame info
  64                     print frame
  65                     function = frame.GetFunction()
  66                     # See if we have debug info (a function)
  67                     if function:
  68                         # We do have a function, print some info for the function
  69                         print function
  70                         # Now get all instructions for this function and print them
  71                         insts = function.GetInstructions(target)
  72                         disassemble_instructions (insts)
  73                     else:
  74                         # See if we have a symbol in the symbol table for where we stopped
  75                         symbol = frame.GetSymbol();
  76                         if symbol:
  77                             # We do have a symbol, print some info for the symbol
  78                             print symbol
  79                             # Now get all instructions for this symbol and print them
  80                             insts = symbol.GetInstructions(target)
  81                             disassemble_instructions (insts)
  82
  83                     registerList = frame.GetRegisters()
  84                     print('Frame registers (size of register set = %d):' % registerList.GetSize())
  85                     for value in registerList:
  86                         #print value
  87                         print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren()))
  88                         for child in value:
  89                             print('Name: ', child.GetName(), ' Value: ', child.GetValue())
  90
  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...')
  95                 process.Kill()
  96             else:
  97                 # Now continue to the program exit
  98                 process.Continue()
  99                 # When we return from the above function we will hopefully be at the
 100                 # program exit. Print out some process info
 101                 print process
 102         elif state == lldb.eStateExited:
 103             print('Didn\'t hit the breakpoint at main, program has exited...')
 104         else:
 105             print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state))
 106             process.Kill()
 107
 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
 110 to do this is:
 111
 112 target = debugger.CreateTarget('')
 113 error = lldb.SBError()
 114 process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error)
 115
 116 or the equivalent arguments for AttachToProcessWithID.") SBDebugger;
 117 class SBDebugger
 118 {
 119 public:
 120
 121     static void
 122     Initialize();
 123
 124     static SBError
 125     InitializeWithErrorHandling();
 126
 127     static void
 128     Terminate();
 129
 130     static lldb::SBDebugger
 131     Create();
 132
 133     static lldb::SBDebugger
 134     Create(bool source_init_files);
 135
 136     static lldb::SBDebugger
 137     Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton);
 138
 139     static void
 140     Destroy (lldb::SBDebugger &debugger);
 141
 142     static void
 143     MemoryPressureDetected();
 144
 145     SBDebugger();
 146
 147     SBDebugger(const lldb::SBDebugger &rhs);
 148
 149     ~SBDebugger();
 150
 151     bool
 152     IsValid() const;
 153
 154     explicit operator bool() const;
 155
 156     void
 157     Clear ();
 158
 159     void
 160     SetAsync (bool b);
 161
 162     bool
 163     GetAsync ();
 164
 165     void
 166     SkipLLDBInitFiles (bool b);
 167
 168 #ifdef SWIGPYTHON
 169     %pythoncode %{
 170         def SetOutputFileHandle(self, file, transfer_ownership):
 171             "DEPRECATED, use SetOutputFile"
 172             if file is None:
 173                 import sys
 174                 file = sys.stdout
 175             self.SetOutputFile(SBFile.Create(file, borrow=True))
 176
 177         def SetInputFileHandle(self, file, transfer_ownership):
 178             "DEPRECATED, use SetInputFile"
 179             if file is None:
 180                 import sys
 181                 file = sys.stdin
 182             self.SetInputFile(SBFile.Create(file, borrow=True))
 183
 184         def SetErrorFileHandle(self, file, transfer_ownership):
 185             "DEPRECATED, use SetErrorFile"
 186             if file is None:
 187                 import sys
 188                 file = sys.stderr
 189             self.SetErrorFile(SBFile.Create(file, borrow=True))
 190     %}
 191 #endif
 192
 193
 194     %extend {
 195
 196         lldb::FileSP GetInputFileHandle() {
 197             return self->GetInputFile().GetFile();
 198         }
 199
 200         lldb::FileSP GetOutputFileHandle() {
 201             return self->GetOutputFile().GetFile();
 202         }
 203
 204         lldb::FileSP GetErrorFileHandle() {
 205             return self->GetErrorFile().GetFile();
 206         }
 207     }
 208
 209     SBError
 210     SetInputFile (SBFile file);
 211
 212     SBError
 213     SetOutputFile (SBFile file);
 214
 215     SBError
 216     SetErrorFile (SBFile file);
 217
 218     SBError
 219     SetInputFile (FileSP file);
 220
 221     SBError
 222     SetOutputFile (FileSP file);
 223
 224     SBError
 225     SetErrorFile (FileSP file);
 226
 227     SBFile
 228     GetInputFile ();
 229
 230     SBFile
 231     GetOutputFile ();
 232
 233     SBFile
 234     GetErrorFile ();
 235
 236     lldb::SBCommandInterpreter
 237     GetCommandInterpreter ();
 238
 239     void
 240     HandleCommand (const char *command);
 241
 242     lldb::SBListener
 243     GetListener ();
 244
 245     void
 246     HandleProcessEvent (const lldb::SBProcess &process,
 247                         const lldb::SBEvent &event,
 248                         SBFile out,
 249                         SBFile err);
 250
 251     void
 252     HandleProcessEvent (const lldb::SBProcess &process,
 253                         const lldb::SBEvent &event,
 254                         FileSP BORROWED,
 255                         FileSP BORROWED);
 256
 257     lldb::SBTarget
 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);
 263
 264     lldb::SBTarget
 265     CreateTargetWithFileAndTargetTriple (const char *filename,
 266                                          const char *target_triple);
 267
 268     lldb::SBTarget
 269     CreateTargetWithFileAndArch (const char *filename,
 270                                  const char *archname);
 271
 272     lldb::SBTarget
 273     CreateTarget (const char *filename);
 274
 275     %feature("docstring",
 276     "The dummy target holds breakpoints and breakpoint names that will prime newly created targets."
 277     ) GetDummyTarget;
 278     lldb::SBTarget GetDummyTarget();
 279
 280     %feature("docstring",
 281     "Return true if target is deleted from the target list of the debugger."
 282     ) DeleteTarget;
 283     bool
 284     DeleteTarget (lldb::SBTarget &target);
 285
 286     lldb::SBTarget
 287     GetTargetAtIndex (uint32_t idx);
 288
 289     uint32_t
 290     GetIndexOfTarget (lldb::SBTarget target);
 291
 292     lldb::SBTarget
 293     FindTargetWithProcessID (pid_t pid);
 294
 295     lldb::SBTarget
 296     FindTargetWithFileAndArch (const char *filename,
 297                                const char *arch);
 298
 299     uint32_t
 300     GetNumTargets ();
 301
 302     lldb::SBTarget
 303     GetSelectedTarget ();
 304
 305     void
 306     SetSelectedTarget (lldb::SBTarget &target);
 307
 308     lldb::SBPlatform
 309     GetSelectedPlatform();
 310
 311     void
 312     SetSelectedPlatform(lldb::SBPlatform &platform);
 313
 314     %feature("docstring",
 315     "Get the number of currently active platforms."
 316     ) GetNumPlatforms;
 317     uint32_t
 318     GetNumPlatforms ();
 319
 320     %feature("docstring",
 321     "Get one of the currently active platforms."
 322     ) GetPlatformAtIndex;
 323     lldb::SBPlatform
 324     GetPlatformAtIndex (uint32_t idx);
 325
 326     %feature("docstring",
 327     "Get the number of available platforms."
 328     ) GetNumAvailablePlatforms;
 329     uint32_t
 330     GetNumAvailablePlatforms ();
 331
 332     %feature("docstring", "
 333     Get the name and description of one of the available platforms.
 334
 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);
 340
 341     lldb::SBSourceManager
 342     GetSourceManager ();
 343
 344     // REMOVE: just for a quick fix, need to expose platforms through
 345     // SBPlatform from this class.
 346     lldb::SBError
 347     SetCurrentPlatform (const char *platform_name);
 348
 349     bool
 350     SetCurrentPlatformSDKRoot (const char *sysroot);
 351
 352     // FIXME: Once we get the set show stuff in place, the driver won't need
 353     // an interface to the Set/Get UseExternalEditor.
 354     bool
 355     SetUseExternalEditor (bool input);
 356
 357     bool
 358     GetUseExternalEditor ();
 359
 360     bool
 361     SetUseColor (bool use_color);
 362
 363     bool
 364     GetUseColor () const;
 365
 366     static bool
 367     GetDefaultArchitecture (char *arch_name, size_t arch_name_len);
 368
 369     static bool
 370     SetDefaultArchitecture (const char *arch_name);
 371
 372     lldb::ScriptLanguage
 373     GetScriptingLanguage (const char *script_language_name);
 374
 375     static const char *
 376     GetVersionString ();
 377
 378     static const char *
 379     StateAsCString (lldb::StateType state);
 380
 381     static SBStructuredData GetBuildConfiguration();
 382
 383     static bool
 384     StateIsRunningState (lldb::StateType state);
 385
 386     static bool
 387     StateIsStoppedState (lldb::StateType state);
 388
 389     bool
 390     EnableLog (const char *channel, const char ** types);
 391
 392     void
 393     SetLoggingCallback (lldb::LogOutputCallback log_callback, void *baton);
 394
 395     void
 396     DispatchInput (const void *data, size_t data_len);
 397
 398     void
 399     DispatchInputInterrupt ();
 400
 401     void
 402     DispatchInputEndOfFile ();
 403
 404     const char *
 405     GetInstanceName  ();
 406
 407     static SBDebugger
 408     FindDebuggerWithID (int id);
 409
 410     static lldb::SBError
 411     SetInternalVariable (const char *var_name, const char *value, const char *debugger_instance_name);
 412
 413     static lldb::SBStringList
 414     GetInternalVariableValue (const char *var_name, const char *debugger_instance_name);
 415
 416     bool
 417     GetDescription (lldb::SBStream &description);
 418
 419     uint32_t
 420     GetTerminalWidth () const;
 421
 422     void
 423     SetTerminalWidth (uint32_t term_width);
 424
 425     lldb::user_id_t
 426     GetID ();
 427
 428     const char *
 429     GetPrompt() const;
 430
 431     void
 432     SetPrompt (const char *prompt);
 433
 434     const char *
 435     GetReproducerPath() const;
 436
 437     lldb::ScriptLanguage
 438     GetScriptLanguage() const;
 439
 440     void
 441     SetScriptLanguage (lldb::ScriptLanguage script_lang);
 442
 443     bool
 444     GetCloseInputOnEOF () const;
 445
 446     void
 447     SetCloseInputOnEOF (bool b);
 448
 449     lldb::SBTypeCategory
 450     GetCategory (const char* category_name);
 451
 452     SBTypeCategory
 453     GetCategory (lldb::LanguageType lang_type);
 454
 455     lldb::SBTypeCategory
 456     CreateCategory (const char* category_name);
 457
 458     bool
 459     DeleteCategory (const char* category_name);
 460
 461     uint32_t
 462     GetNumCategories ();
 463
 464     lldb::SBTypeCategory
 465     GetCategoryAtIndex (uint32_t);
 466
 467     lldb::SBTypeCategory
 468     GetDefaultCategory();
 469
 470     lldb::SBTypeFormat
 471     GetFormatForType (lldb::SBTypeNameSpecifier);
 472
 473     lldb::SBTypeSummary
 474     GetSummaryForType (lldb::SBTypeNameSpecifier);
 475
 476     lldb::SBTypeFilter
 477     GetFilterForType (lldb::SBTypeNameSpecifier);
 478
 479     lldb::SBTypeSynthetic
 480     GetSyntheticForType (lldb::SBTypeNameSpecifier);
 481
 482     STRING_EXTENSION(SBDebugger)
 483
 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.
 488
 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.
 495
 496 @return
 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.
 500
 501 Example:
 502
 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 };
 510     void
 511     RunCommandInterpreter (bool auto_handle_events,
 512                            bool spawn_thread,
 513                            SBCommandInterpreterRunOptions &options,
 514                            int  &num_errors,
 515                            bool &quit_requested,
 516                            bool &stopped_for_crash);
 517
 518     lldb::SBError
 519     RunREPL (lldb::LanguageType language, const char *repl_options);
 520
 521 #ifdef SWIGPYTHON
 522     %pythoncode%{
 523     def __iter__(self):
 524         '''Iterate over all targets in a lldb.SBDebugger object.'''
 525         return lldb_iter(self, 'GetNumTargets', 'GetTargetAtIndex')
 526
 527     def __len__(self):
 528         '''Return the number of targets in a lldb.SBDebugger object.'''
 529         return self.GetNumTargets()
 530     %}
 531 #endif
 532
 533 }; // class SBDebugger
 534
 535 } // namespace lldb