scripts/interface/SBDebugger.i

   1 //===-- SWIG Interface for SBDebugger ---------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 namespace lldb {
  11
  12 %feature("docstring",
  13 "SBDebugger is the primordial object that creates SBTargets and provides
  14 access to them.  It also manages the overall debugging experiences.
  15
  16 For example (from example/disasm.py),
  17
  18 import lldb
  19 import os
  20 import sys
  21
  22 def disassemble_instructions (insts):
  23     for i in insts:
  24         print i
  25
  26 ...
  27
  28 # Create a new debugger instance
  29 debugger = lldb.SBDebugger.Create()
  30
  31 # When we step or continue, don't return from the function until the process
  32 # stops. We do this by setting the async mode to false.
  33 debugger.SetAsync (False)
  34
  35 # Create a target from a file and arch
  36 print('Creating a target for \'%s\'' % exe)
  37
  38 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
  39
  40 if target:
  41     # If the target is valid set a breakpoint at main
  42     main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());
  43
  44     print main_bp
  45
  46     # Launch the process. Since we specified synchronous mode, we won't return
  47     # from this function until we hit the breakpoint at main
  48     process = target.LaunchSimple (None, None, os.getcwd())
  49
  50     # Make sure the launch went ok
  51     if process:
  52         # Print some simple process info
  53         state = process.GetState ()
  54         print process
  55         if state == lldb.eStateStopped:
  56             # Get the first thread
  57             thread = process.GetThreadAtIndex (0)
  58             if thread:
  59                 # Print some simple thread info
  60                 print thread
  61                 # Get the first frame
  62                 frame = thread.GetFrameAtIndex (0)
  63                 if frame:
  64                     # Print some simple frame info
  65                     print frame
  66                     function = frame.GetFunction()
  67                     # See if we have debug info (a function)
  68                     if function:
  69                         # We do have a function, print some info for the function
  70                         print function
  71                         # Now get all instructions for this function and print them
  72                         insts = function.GetInstructions(target)
  73                         disassemble_instructions (insts)
  74                     else:
  75                         # See if we have a symbol in the symbol table for where we stopped
  76                         symbol = frame.GetSymbol();
  77                         if symbol:
  78                             # We do have a symbol, print some info for the symbol
  79                             print symbol
  80                             # Now get all instructions for this symbol and print them
  81                             insts = symbol.GetInstructions(target)
  82                             disassemble_instructions (insts)
  83
  84                     registerList = frame.GetRegisters()
  85                     print('Frame registers (size of register set = %d):' % registerList.GetSize())
  86                     for value in registerList:
  87                         #print value
  88                         print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren()))
  89                         for child in value:
  90                             print('Name: ', child.GetName(), ' Value: ', child.GetValue())
  91
  92             print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program')
  93             next = sys.stdin.readline()
  94             if not next or next.rstrip('\n') == 'quit':
  95                 print('Terminating the inferior process...')
  96                 process.Kill()
  97             else:
  98                 # Now continue to the program exit
  99                 process.Continue()
 100                 # When we return from the above function we will hopefully be at the
 101                 # program exit. Print out some process info
 102                 print process
 103         elif state == lldb.eStateExited:
 104             print('Didn\'t hit the breakpoint at main, program has exited...')
 105         else:
 106             print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state))
 107             process.Kill()
 108
 109 Sometimes you need to create an empty target that will get filled in later.  The most common use for this
 110 is to attach to a process by name or pid where you don't know the executable up front.  The most convenient way
 111 to do this is:
 112
 113 target = debugger.CreateTarget('')
 114 error = lldb.SBError()
 115 process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error)
 116
 117 or the equivalent arguments for AttachToProcessWithID.
 118 ") SBDebugger;
 119 class SBDebugger
 120 {
 121 public:
 122
 123     static void
 124     Initialize();
 125
 126     static void
 127     Terminate();
 128
 129     static lldb::SBDebugger
 130     Create();
 131
 132     static lldb::SBDebugger
 133     Create(bool source_init_files);
 134
 135     static lldb::SBDebugger
 136     Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton);
 137
 138     static void
 139     Destroy (lldb::SBDebugger &debugger);
 140
 141     static void
 142     MemoryPressureDetected();
 143
 144     SBDebugger();
 145
 146     SBDebugger(const lldb::SBDebugger &rhs);
 147
 148     ~SBDebugger();
 149
 150     bool
 151     IsValid() const;
 152
 153     void
 154     Clear ();
 155
 156     void
 157     SetAsync (bool b);
 158
 159     bool
 160     GetAsync ();
 161
 162     void
 163     SkipLLDBInitFiles (bool b);
 164
 165     void
 166     SetInputFileHandle (FILE *f, bool transfer_ownership);
 167
 168     void
 169     SetOutputFileHandle (FILE *f, bool transfer_ownership);
 170
 171     void
 172     SetErrorFileHandle (FILE *f, bool transfer_ownership);
 173
 174     FILE *
 175     GetInputFileHandle ();
 176
 177     FILE *
 178     GetOutputFileHandle ();
 179
 180     FILE *
 181     GetErrorFileHandle ();
 182
 183     lldb::SBCommandInterpreter
 184     GetCommandInterpreter ();
 185
 186     void
 187     HandleCommand (const char *command);
 188
 189     lldb::SBListener
 190     GetListener ();
 191
 192     void
 193     HandleProcessEvent (const lldb::SBProcess &process,
 194                         const lldb::SBEvent &event,
 195                         FILE *out,
 196                         FILE *err);
 197
 198     lldb::SBTarget
 199     CreateTarget (const char *filename,
 200                   const char *target_triple,
 201                   const char *platform_name,
 202                   bool add_dependent_modules,
 203                   lldb::SBError& sb_error);
 204
 205     lldb::SBTarget
 206     CreateTargetWithFileAndTargetTriple (const char *filename,
 207                                          const char *target_triple);
 208
 209     lldb::SBTarget
 210     CreateTargetWithFileAndArch (const char *filename,
 211                                  const char *archname);
 212
 213     lldb::SBTarget
 214     CreateTarget (const char *filename);
 215
 216     %feature("docstring",
 217     "Return true if target is deleted from the target list of the debugger."
 218     ) DeleteTarget;
 219     bool
 220     DeleteTarget (lldb::SBTarget &target);
 221
 222     lldb::SBTarget
 223     GetTargetAtIndex (uint32_t idx);
 224
 225     uint32_t
 226     GetIndexOfTarget (lldb::SBTarget target);
 227
 228     lldb::SBTarget
 229     FindTargetWithProcessID (pid_t pid);
 230
 231     lldb::SBTarget
 232     FindTargetWithFileAndArch (const char *filename,
 233                                const char *arch);
 234
 235     uint32_t
 236     GetNumTargets ();
 237
 238     lldb::SBTarget
 239     GetSelectedTarget ();
 240
 241     void
 242     SetSelectedTarget (lldb::SBTarget &target);
 243
 244     lldb::SBPlatform
 245     GetSelectedPlatform();
 246
 247     void
 248     SetSelectedPlatform(lldb::SBPlatform &platform);
 249
 250     lldb::SBSourceManager
 251     GetSourceManager ();
 252
 253     // REMOVE: just for a quick fix, need to expose platforms through
 254     // SBPlatform from this class.
 255     lldb::SBError
 256     SetCurrentPlatform (const char *platform_name);
 257
 258     bool
 259     SetCurrentPlatformSDKRoot (const char *sysroot);
 260
 261     // FIXME: Once we get the set show stuff in place, the driver won't need
 262     // an interface to the Set/Get UseExternalEditor.
 263     bool
 264     SetUseExternalEditor (bool input);
 265
 266     bool
 267     GetUseExternalEditor ();
 268
 269     bool
 270     SetUseColor (bool use_color);
 271
 272     bool
 273     GetUseColor () const;
 274
 275     static bool
 276     GetDefaultArchitecture (char *arch_name, size_t arch_name_len);
 277
 278     static bool
 279     SetDefaultArchitecture (const char *arch_name);
 280
 281     lldb::ScriptLanguage
 282     GetScriptingLanguage (const char *script_language_name);
 283
 284     static const char *
 285     GetVersionString ();
 286
 287     static const char *
 288     StateAsCString (lldb::StateType state);
 289
 290     static bool
 291     StateIsRunningState (lldb::StateType state);
 292
 293     static bool
 294     StateIsStoppedState (lldb::StateType state);
 295
 296     bool
 297     EnableLog (const char *channel, const char ** types);
 298
 299     void
 300     SetLoggingCallback (lldb::LogOutputCallback log_callback, void *baton);
 301
 302     void
 303     DispatchInput (const void *data, size_t data_len);
 304
 305     void
 306     DispatchInputInterrupt ();
 307
 308     void
 309     DispatchInputEndOfFile ();
 310
 311     const char *
 312     GetInstanceName  ();
 313
 314     static SBDebugger
 315     FindDebuggerWithID (int id);
 316
 317     static lldb::SBError
 318     SetInternalVariable (const char *var_name, const char *value, const char *debugger_instance_name);
 319
 320     static lldb::SBStringList
 321     GetInternalVariableValue (const char *var_name, const char *debugger_instance_name);
 322
 323     bool
 324     GetDescription (lldb::SBStream &description);
 325
 326     uint32_t
 327     GetTerminalWidth () const;
 328
 329     void
 330     SetTerminalWidth (uint32_t term_width);
 331
 332     lldb::user_id_t
 333     GetID ();
 334
 335     const char *
 336     GetPrompt() const;
 337
 338     void
 339     SetPrompt (const char *prompt);
 340
 341     lldb::ScriptLanguage
 342     GetScriptLanguage() const;
 343
 344     void
 345     SetScriptLanguage (lldb::ScriptLanguage script_lang);
 346
 347     bool
 348     GetCloseInputOnEOF () const;
 349
 350     void
 351     SetCloseInputOnEOF (bool b);
 352
 353     lldb::SBTypeCategory
 354     GetCategory (const char* category_name);
 355
 356     SBTypeCategory
 357     GetCategory (lldb::LanguageType lang_type);
 358
 359     lldb::SBTypeCategory
 360     CreateCategory (const char* category_name);
 361
 362     bool
 363     DeleteCategory (const char* category_name);
 364
 365     uint32_t
 366     GetNumCategories ();
 367
 368     lldb::SBTypeCategory
 369     GetCategoryAtIndex (uint32_t);
 370
 371     lldb::SBTypeCategory
 372     GetDefaultCategory();
 373
 374     lldb::SBTypeFormat
 375     GetFormatForType (lldb::SBTypeNameSpecifier);
 376
 377     lldb::SBTypeSummary
 378     GetSummaryForType (lldb::SBTypeNameSpecifier);
 379
 380     lldb::SBTypeFilter
 381     GetFilterForType (lldb::SBTypeNameSpecifier);
 382
 383     lldb::SBTypeSynthetic
 384     GetSyntheticForType (lldb::SBTypeNameSpecifier);
 385
 386     void
 387     RunCommandInterpreter (bool auto_handle_events,
 388                            bool spawn_thread,
 389                            SBCommandInterpreterRunOptions &options,
 390                            int  &num_errors,
 391                            bool &quit_requested,
 392                            bool &stopped_for_crash);
 393
 394     lldb::SBError
 395     RunREPL (lldb::LanguageType language, const char *repl_options);
 396 }; // class SBDebugger
 397
 398 } // namespace lldb