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;
161