lldb/bindings/interface/SBDebuggerDocstrings.i

   1 %feature("docstring",
   2 "SBDebugger is the primordial object that creates SBTargets and provides
   3 access to them.  It also manages the overall debugging experiences.
   4
   5 For example (from example/disasm.py),::
   6
   7     import lldb
   8     import os
   9     import sys
  10
  11     def disassemble_instructions (insts):
  12         for i in insts:
  13             print i
  14
  15     ...
  16
  17     # Create a new debugger instance
  18     debugger = lldb.SBDebugger.Create()
  19
  20     # When we step or continue, don't return from the function until the process
  21     # stops. We do this by setting the async mode to false.
  22     debugger.SetAsync (False)
  23
  24     # Create a target from a file and arch
  25     print('Creating a target for \'%s\'' % exe)
  26
  27     target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
  28
  29     if target:
  30         # If the target is valid set a breakpoint at main
  31         main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());
  32
  33         print main_bp
  34
  35         # Launch the process. Since we specified synchronous mode, we won't return
  36         # from this function until we hit the breakpoint at main
  37         process = target.LaunchSimple (None, None, os.getcwd())
  38
  39         # Make sure the launch went ok
  40         if process:
  41             # Print some simple process info
  42             state = process.GetState ()
  43             print process
  44             if state == lldb.eStateStopped:
  45                 # Get the first thread
  46                 thread = process.GetThreadAtIndex (0)
  47                 if thread:
  48                     # Print some simple thread info
  49                     print thread
  50                     # Get the first frame
  51                     frame = thread.GetFrameAtIndex (0)
  52                     if frame:
  53                         # Print some simple frame info
  54                         print frame
  55                         function = frame.GetFunction()
  56                         # See if we have debug info (a function)
  57                         if function:
  58                             # We do have a function, print some info for the function
  59                             print function
  60                             # Now get all instructions for this function and print them
  61                             insts = function.GetInstructions(target)
  62                             disassemble_instructions (insts)
  63                         else:
  64                             # See if we have a symbol in the symbol table for where we stopped
  65                             symbol = frame.GetSymbol();
  66                             if symbol:
  67                                 # We do have a symbol, print some info for the symbol
  68                                 print symbol
  69                                 # Now get all instructions for this symbol and print them
  70                                 insts = symbol.GetInstructions(target)
  71                                 disassemble_instructions (insts)
  72
  73                         registerList = frame.GetRegisters()
  74                         print('Frame registers (size of register set = %d):' % registerList.GetSize())
  75                         for value in registerList:
  76                             #print value
  77                             print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren()))
  78                             for child in value:
  79                                 print('Name: ', child.GetName(), ' Value: ', child.GetValue())
  80
  81                 print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program')
  82                 next = sys.stdin.readline()
  83                 if not next or next.rstrip('\\n') == 'quit':
  84                     print('Terminating the inferior process...')
  85                     process.Kill()
  86                 else:
  87                     # Now continue to the program exit
  88                     process.Continue()
  89                     # When we return from the above function we will hopefully be at the
  90                     # program exit. Print out some process info
  91                     print process
  92             elif state == lldb.eStateExited:
  93                 print('Didn\'t hit the breakpoint at main, program has exited...')
  94             else:
  95                 print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state))
  96                 process.Kill()
  97
  98 Sometimes you need to create an empty target that will get filled in later.  The most common use for this
  99 is to attach to a process by name or pid where you don't know the executable up front.  The most convenient way
 100 to do this is: ::
 101
 102     target = debugger.CreateTarget('')
 103     error = lldb.SBError()
 104     process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error)
 105
 106 or the equivalent arguments for :py:class:`SBTarget.AttachToProcessWithID` ."
 107 ) lldb::SBDebugger;
 108
 109 %feature("docstring",
 110     "The dummy target holds breakpoints and breakpoint names that will prime newly created targets."
 111 ) lldb::SBDebugger::GetDummyTarget;
 112
 113 %feature("docstring",
 114     "Return true if target is deleted from the target list of the debugger."
 115 ) lldb::SBDebugger::DeleteTarget;
 116
 117 %feature("docstring",
 118     "Get the number of currently active platforms."
 119 ) lldb::SBDebugger::GetNumPlatforms;
 120
 121 %feature("docstring",
 122     "Get one of the currently active platforms."
 123 ) lldb::SBDebugger::GetPlatformAtIndex;
 124
 125 %feature("docstring",
 126     "Get the number of available platforms."
 127 ) lldb::SBDebugger::GetNumAvailablePlatforms;
 128
 129 %feature("docstring", "
 130     Get the name and description of one of the available platforms.
 131
 132     @param idx Zero-based index of the platform for which info should be
 133                retrieved, must be less than the value returned by
 134                GetNumAvailablePlatforms()."
 135 ) lldb::SBDebugger::GetAvailablePlatformInfoAtIndex;
 136
 137 %feature("docstring",
 138 "Launch a command interpreter session. Commands are read from standard input or
 139 from the input handle specified for the debugger object. Output/errors are
 140 similarly redirected to standard output/error or the configured handles.
 141
 142 @param[in] auto_handle_events If true, automatically handle resulting events.
 143 @param[in] spawn_thread If true, start a new thread for IO handling.
 144 @param[in] options Parameter collection of type SBCommandInterpreterRunOptions.
 145 @param[in] num_errors Initial error counter.
 146 @param[in] quit_requested Initial quit request flag.
 147 @param[in] stopped_for_crash Initial crash flag.
 148
 149 @return
 150 A tuple with the number of errors encountered by the interpreter, a boolean
 151 indicating whether quitting the interpreter was requested and another boolean
 152 set to True in case of a crash.
 153
 154 Example: ::
 155
 156     # Start an interactive lldb session from a script (with a valid debugger object
 157     # created beforehand):
 158     n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True,
 159         False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)"
 160 ) lldb::SBDebugger::RunCommandInterpreter;