1 #!/usr/bin/python 2 3 #---------------------------------------------------------------------- 4 # Be sure to add the python path that points to the LLDB shared library. 5 # On MacOSX csh, tcsh: 6 # setenv PYTHONPATH /Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Resources/Python 7 # On MacOSX sh, bash: 8 # export PYTHONPATH=/Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Resources/Python 9 #---------------------------------------------------------------------- 10 11 import commands 12 import optparse 13 import os 14 import platform 15 import sys 16 17 #---------------------------------------------------------------------- 18 # Code that auto imports LLDB 19 #---------------------------------------------------------------------- 20 try: 21 # Just try for LLDB in case PYTHONPATH is already correctly setup 22 import lldb 23 except ImportError: 24 lldb_python_dirs = list() 25 # lldb is not in the PYTHONPATH, try some defaults for the current platform 26 platform_system = platform.system() 27 if platform_system == 'Darwin': 28 # On Darwin, try the currently selected Xcode directory 29 xcode_dir = commands.getoutput("xcode-select --print-path") 30 if xcode_dir: 31 lldb_python_dirs.append(os.path.realpath(xcode_dir + '/../SharedFrameworks/LLDB.framework/Resources/Python')) 32 lldb_python_dirs.append(xcode_dir + '/Library/PrivateFrameworks/LLDB.framework/Resources/Python') 33 lldb_python_dirs.append('/System/Library/PrivateFrameworks/LLDB.framework/Resources/Python') 34 success = False 35 for lldb_python_dir in lldb_python_dirs: 36 if os.path.exists(lldb_python_dir): 37 if not (sys.path.__contains__(lldb_python_dir)): 38 sys.path.append(lldb_python_dir) 39 try: 40 import lldb 41 except ImportError: 42 pass 43 else: 44 print 'imported lldb from: "%s"' % (lldb_python_dir) 45 success = True 46 break 47 if not success: 48 print "error: couldn't locate the 'lldb' module, please set PYTHONPATH correctly" 49 sys.exit(1) 50 51 def print_threads(process, options): 52 if options.show_threads: 53 for thread in process: 54 print '%s %s' % (thread, thread.GetFrameAtIndex(0)) 55 56 def run_commands(command_interpreter, commands): 57 return_obj = lldb.SBCommandReturnObject() 58 for command in commands: 59 command_interpreter.HandleCommand( command, return_obj ) 60 if return_obj.Succeeded(): 61 print return_obj.GetOutput() 62 else: 63 print return_obj 64 if options.stop_on_error: 65 break 66 67 def main(argv): 68 description='''Debugs a program using the LLDB python API and uses asynchronous broadcast events to watch for process state changes.''' 69 epilog='''Examples: 70 71 #---------------------------------------------------------------------- 72 # Run "/bin/ls" with the arguments "-lAF /tmp/", and set a breakpoint 73 # at "malloc" and backtrace and read all registers each time we stop 74 #---------------------------------------------------------------------- 75 % ./process_events.py --breakpoint malloc --stop-command bt --stop-command 'register read' -- /bin/ls -lAF /tmp/ 76 77 ''' 78 optparse.OptionParser.format_epilog = lambda self, formatter: self.epilog 79 parser = optparse.OptionParser(description=description, prog='process_events',usage='usage: process_events [options] program [arg1 arg2]', epilog=epilog) 80 parser.add_option('-v', '--verbose', action='store_true', dest='verbose', help="Enable verbose logging.", default=False) 81 parser.add_option('-b', '--breakpoint', action='append', type='string', metavar='BPEXPR', dest='breakpoints', help='Breakpoint commands to create after the target has been created, the values will be sent to the "_regexp-break" command which supports breakpoints by name, file:line, and address.') 82 parser.add_option('-a', '--arch', type='string', dest='arch', help='The architecture to use when creating the debug target.', default=None) 83 parser.add_option('--platform', type='string', metavar='platform', dest='platform', help='Specify the platform to use when creating the debug target. Valid values include "localhost", "darwin-kernel", "ios-simulator", "remote-freebsd", "remote-macosx", "remote-ios", "remote-linux".', default=None) 84 parser.add_option('-l', '--launch-command', action='append', type='string', metavar='CMD', dest='launch_commands', help='LLDB command interpreter commands to run once after the process has launched. This option can be specified more than once.', default=[]) 85 parser.add_option('-s', '--stop-command', action='append', type='string', metavar='CMD', dest='stop_commands', help='LLDB command interpreter commands to run each time the process stops. This option can be specified more than once.', default=[]) 86 parser.add_option('-c', '--crash-command', action='append', type='string', metavar='CMD', dest='crash_commands', help='LLDB command interpreter commands to run in case the process crashes. This option can be specified more than once.', default=[]) 87 parser.add_option('-x', '--exit-command', action='append', type='string', metavar='CMD', dest='exit_commands', help='LLDB command interpreter commands to run once after the process has exited. This option can be specified more than once.', default=[]) 88 parser.add_option('-T', '--no-threads', action='store_false', dest='show_threads', help="Don't show threads when process stops.", default=True) 89 parser.add_option('--ignore-errors', action='store_false', dest='stop_on_error', help="Don't stop executing LLDB commands if the command returns an error. This applies to all of the LLDB command interpreter commands that get run for launch, stop, crash and exit.", default=True) 90 parser.add_option('-n', '--run-count', type='int', dest='run_count', metavar='N', help='How many times to run the process in case the process exits.', default=1) 91 parser.add_option('-t', '--event-timeout', type='int', dest='event_timeout', metavar='SEC', help='Specify the timeout in seconds to wait for process state change events.', default=lldb.UINT32_MAX) 92 parser.add_option('-e', '--environment', action='append', type='string', metavar='ENV', dest='env_vars', help='Environment variables to set in the inferior process when launching a process.') 93 parser.add_option('-d', '--working-dir', type='string', metavar='DIR', dest='working_dir', help='The the current working directory when launching a process.', default=None) 94 parser.add_option('-p', '--attach-pid', type='int', dest='attach_pid', metavar='PID', help='Specify a process to attach to by process ID.', default=-1) 95 parser.add_option('-P', '--attach-name', type='string', dest='attach_name', metavar='PROCESSNAME', help='Specify a process to attach to by name.', default=None) 96 parser.add_option('-w', '--attach-wait', action='store_true', dest='attach_wait', help='Wait for the next process to launch when attaching to a process by name.', default=False) 97 try: 98 (options, args) = parser.parse_args(argv) 99 except: 100 return 101 102 attach_info = None 103 launch_info = None 104 exe = None 105 if args: 106 exe = args.pop(0) 107 launch_info = lldb.SBLaunchInfo (args) 108 if options.env_vars: 109 launch_info.SetEnvironmentEntries(options.env_vars, True) 110 if options.working_dir: 111 launch_info.SetWorkingDirectory(options.working_dir) 112 elif options.attach_pid != -1: 113 if options.run_count == 1: 114 attach_info = lldb.SBAttachInfo (options.attach_pid) 115 else: 116 print "error: --run-count can't be used with the --attach-pid option" 117 sys.exit(1) 118 elif not options.attach_name is None: 119 if options.run_count == 1: 120 attach_info = lldb.SBAttachInfo (options.attach_name, options.attach_wait) 121 else: 122 print "error: --run-count can't be used with the --attach-name option" 123 sys.exit(1) 124 else: 125 print 'error: a program path for a program to debug and its arguments are required' 126 sys.exit(1) 127 128 129 130 # Create a new debugger instance 131 debugger = lldb.SBDebugger.Create() 132 debugger.SetAsync (True) 133 command_interpreter = debugger.GetCommandInterpreter() 134 # Create a target from a file and arch 135 136 if exe: 137 print "Creating a target for '%s'" % exe 138 error = lldb.SBError() 139 target = debugger.CreateTarget (exe, options.arch, options.platform, True, error) 140 141 if target: 142 143 # Set any breakpoints that were specified in the args if we are launching. We use the 144 # command line command to take advantage of the shorthand breakpoint creation 145 if launch_info and options.breakpoints: 146 for bp in options.breakpoints: 147 debugger.HandleCommand( "_regexp-break %s" % (bp)) 148 run_commands(command_interpreter, ['breakpoint list']) 149 150 for run_idx in range(options.run_count): 151 # Launch the process. Since we specified synchronous mode, we won't return 152 # from this function until we hit the breakpoint at main 153 error = lldb.SBError() 154 155 if launch_info: 156 if options.run_count == 1: 157 print 'Launching "%s"...' % (exe) 158 else: 159 print 'Launching "%s"... (launch %u of %u)' % (exe, run_idx + 1, options.run_count) 160 161 process = target.Launch (launch_info, error) 162 else: 163 if options.attach_pid != -1: 164 print 'Attaching to process %i...' % (options.attach_pid) 165 else: 166 if options.attach_wait: 167 print 'Waiting for next to process named "%s" to launch...' % (options.attach_name) 168 else: 169 print 'Attaching to existing process named "%s"...' % (options.attach_name) 170 process = target.Attach (attach_info, error) 171 172 # Make sure the launch went ok 173 if process and process.GetProcessID() != lldb.LLDB_INVALID_PROCESS_ID: 174 pid = process.GetProcessID() 175 listener = debugger.GetListener() 176 # sign up for process state change events 177 stop_idx = 0 178 done = False 179 while not done: 180 event = lldb.SBEvent() 181 if listener.WaitForEvent (options.event_timeout, event): 182 if lldb.SBProcess.EventIsProcessEvent(event): 183 state = lldb.SBProcess.GetStateFromEvent (event) 184 if state == lldb.eStateInvalid: 185 # Not a state event 186 print 'process event = %s' % (event) 187 else: 188 print "process state changed event: %s" % (lldb.SBDebugger.StateAsCString(state)) 189 if state == lldb.eStateStopped: 190 if stop_idx == 0: 191 if launch_info: 192 print "process %u launched" % (pid) 193 run_commands(command_interpreter, ['breakpoint list']) 194 else: 195 print "attached to process %u" % (pid) 196 for m in target.modules: 197 print m 198 if options.breakpoints: 199 for bp in options.breakpoints: 200 debugger.HandleCommand( "_regexp-break %s" % (bp)) 201 run_commands(command_interpreter, ['breakpoint list']) 202 run_commands (command_interpreter, options.launch_commands) 203 else: 204 if options.verbose: 205 print "process %u stopped" % (pid) 206 run_commands (command_interpreter, options.stop_commands) 207 stop_idx += 1 208 print_threads (process, options) 209 print "continuing process %u" % (pid) 210 process.Continue() 211 elif state == lldb.eStateExited: 212 exit_desc = process.GetExitDescription() 213 if exit_desc: 214 print "process %u exited with status %u: %s" % (pid, process.GetExitStatus (), exit_desc) 215 else: 216 print "process %u exited with status %u" % (pid, process.GetExitStatus ()) 217 run_commands (command_interpreter, options.exit_commands) 218 done = True 219 elif state == lldb.eStateCrashed: 220 print "process %u crashed" % (pid) 221 print_threads (process, options) 222 run_commands (command_interpreter, options.crash_commands) 223 done = True 224 elif state == lldb.eStateDetached: 225 print "process %u detached" % (pid) 226 done = True 227 elif state == lldb.eStateRunning: 228 # process is running, don't say anything, we will always get one of these after resuming 229 if options.verbose: 230 print "process %u resumed" % (pid) 231 elif state == lldb.eStateUnloaded: 232 print "process %u unloaded, this shouldn't happen" % (pid) 233 done = True 234 elif state == lldb.eStateConnected: 235 print "process connected" 236 elif state == lldb.eStateAttaching: 237 print "process attaching" 238 elif state == lldb.eStateLaunching: 239 print "process launching" 240 else: 241 print 'event = %s' % (event) 242 else: 243 # timeout waiting for an event 244 print "no process event for %u seconds, killing the process..." % (options.event_timeout) 245 done = True 246 # Now that we are done dump the stdout and stderr 247 process_stdout = process.GetSTDOUT(1024) 248 if process_stdout: 249 print "Process STDOUT:\n%s" % (process_stdout) 250 while process_stdout: 251 process_stdout = process.GetSTDOUT(1024) 252 print process_stdout 253 process_stderr = process.GetSTDERR(1024) 254 if process_stderr: 255 print "Process STDERR:\n%s" % (process_stderr) 256 while process_stderr: 257 process_stderr = process.GetSTDERR(1024) 258 print process_stderr 259 process.Kill() # kill the process 260 else: 261 if error: 262 print error 263 else: 264 if launch_info: 265 print 'error: launch failed' 266 else: 267 print 'error: attach failed' 268 269 lldb.SBDebugger.Terminate() 270 271 if __name__ == '__main__': 272 main(sys.argv[1:])
