| #!/usr/bin/env python |
| |
| # ---------------------------------------------------------------------- |
| # Be sure to add the python path that points to the LLDB shared library. |
| # On MacOSX csh, tcsh: |
| # setenv PYTHONPATH /Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Resources/Python |
| # On MacOSX sh, bash: |
| # export PYTHONPATH=/Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Resources/Python |
| # ---------------------------------------------------------------------- |
| |
| import optparse |
| import os |
| import platform |
| import sys |
| import subprocess |
| |
| # ---------------------------------------------------------------------- |
| # Code that auto imports LLDB |
| # ---------------------------------------------------------------------- |
| try: |
| # Just try for LLDB in case PYTHONPATH is already correctly setup |
| import lldb |
| except ImportError: |
| lldb_python_dirs = list() |
| # lldb is not in the PYTHONPATH, try some defaults for the current platform |
| platform_system = platform.system() |
| if platform_system == "Darwin": |
| # On Darwin, try the currently selected Xcode directory |
| xcode_dir = subprocess.check_output("xcode-select --print-path", shell=True) |
| if xcode_dir: |
| lldb_python_dirs.append( |
| os.path.realpath( |
| xcode_dir + "/../SharedFrameworks/LLDB.framework/Resources/Python" |
| ) |
| ) |
| lldb_python_dirs.append( |
| xcode_dir + "/Library/PrivateFrameworks/LLDB.framework/Resources/Python" |
| ) |
| lldb_python_dirs.append( |
| "/System/Library/PrivateFrameworks/LLDB.framework/Resources/Python" |
| ) |
| success = False |
| for lldb_python_dir in lldb_python_dirs: |
| if os.path.exists(lldb_python_dir): |
| if not (sys.path.__contains__(lldb_python_dir)): |
| sys.path.append(lldb_python_dir) |
| try: |
| import lldb |
| except ImportError: |
| pass |
| else: |
| print('imported lldb from: "%s"' % (lldb_python_dir)) |
| success = True |
| break |
| if not success: |
| print( |
| "error: couldn't locate the 'lldb' module, please set PYTHONPATH correctly" |
| ) |
| sys.exit(1) |
| |
| |
| def print_threads(process, options): |
| if options.show_threads: |
| for thread in process: |
| print("%s %s" % (thread, thread.GetFrameAtIndex(0))) |
| |
| |
| def run_commands(command_interpreter, commands): |
| return_obj = lldb.SBCommandReturnObject() |
| for command in commands: |
| command_interpreter.HandleCommand(command, return_obj) |
| if return_obj.Succeeded(): |
| print(return_obj.GetOutput()) |
| else: |
| print(return_obj) |
| if options.stop_on_error: |
| break |
| |
| |
| def main(argv): |
| description = """Debugs a program using the LLDB python API and uses asynchronous broadcast events to watch for process state changes.""" |
| epilog = """Examples: |
| |
| #---------------------------------------------------------------------- |
| # Run "/bin/ls" with the arguments "-lAF /tmp/", and set a breakpoint |
| # at "malloc" and backtrace and read all registers each time we stop |
| #---------------------------------------------------------------------- |
| % ./process_events.py --breakpoint malloc --stop-command bt --stop-command 'register read' -- /bin/ls -lAF /tmp/ |
| |
| """ |
| optparse.OptionParser.format_epilog = lambda self, formatter: self.epilog |
| parser = optparse.OptionParser( |
| description=description, |
| prog="process_events", |
| usage="usage: process_events [options] program [arg1 arg2]", |
| epilog=epilog, |
| ) |
| parser.add_option( |
| "-v", |
| "--verbose", |
| action="store_true", |
| dest="verbose", |
| help="Enable verbose logging.", |
| default=False, |
| ) |
| 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.', |
| ) |
| parser.add_option( |
| "-a", |
| "--arch", |
| type="string", |
| dest="arch", |
| help="The architecture to use when creating the debug target.", |
| default=None, |
| ) |
| 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, |
| ) |
| 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=[], |
| ) |
| 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=[], |
| ) |
| 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=[], |
| ) |
| 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=[], |
| ) |
| parser.add_option( |
| "-T", |
| "--no-threads", |
| action="store_false", |
| dest="show_threads", |
| help="Don't show threads when process stops.", |
| default=True, |
| ) |
| 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, |
| ) |
| 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, |
| ) |
| 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, |
| ) |
| 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.", |
| ) |
| parser.add_option( |
| "-d", |
| "--working-dir", |
| type="string", |
| metavar="DIR", |
| dest="working_dir", |
| help="The current working directory when launching a process.", |
| default=None, |
| ) |
| 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, |
| ) |
| parser.add_option( |
| "-P", |
| "--attach-name", |
| type="string", |
| dest="attach_name", |
| metavar="PROCESSNAME", |
| help="Specify a process to attach to by name.", |
| default=None, |
| ) |
| 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, |
| ) |
| try: |
| (options, args) = parser.parse_args(argv) |
| except: |
| return |
| |
| attach_info = None |
| launch_info = None |
| exe = None |
| if args: |
| exe = args.pop(0) |
| launch_info = lldb.SBLaunchInfo(args) |
| if options.env_vars: |
| launch_info.SetEnvironmentEntries(options.env_vars, True) |
| if options.working_dir: |
| launch_info.SetWorkingDirectory(options.working_dir) |
| elif options.attach_pid != -1: |
| if options.run_count == 1: |
| attach_info = lldb.SBAttachInfo(options.attach_pid) |
| else: |
| print("error: --run-count can't be used with the --attach-pid option") |
| sys.exit(1) |
| elif not options.attach_name is None: |
| if options.run_count == 1: |
| attach_info = lldb.SBAttachInfo(options.attach_name, options.attach_wait) |
| else: |
| print("error: --run-count can't be used with the --attach-name option") |
| sys.exit(1) |
| else: |
| print( |
| "error: a program path for a program to debug and its arguments are required" |
| ) |
| sys.exit(1) |
| |
| # Create a new debugger instance |
| debugger = lldb.SBDebugger.Create() |
| debugger.SetAsync(True) |
| command_interpreter = debugger.GetCommandInterpreter() |
| # Create a target from a file and arch |
| |
| if exe: |
| print("Creating a target for '%s'" % exe) |
| error = lldb.SBError() |
| target = debugger.CreateTarget(exe, options.arch, options.platform, True, error) |
| |
| if target: |
| # Set any breakpoints that were specified in the args if we are launching. We use the |
| # command line command to take advantage of the shorthand breakpoint |
| # creation |
| if launch_info and options.breakpoints: |
| for bp in options.breakpoints: |
| debugger.HandleCommand("_regexp-break %s" % (bp)) |
| run_commands(command_interpreter, ["breakpoint list"]) |
| |
| for run_idx in range(options.run_count): |
| # Launch the process. Since we specified synchronous mode, we won't return |
| # from this function until we hit the breakpoint at main |
| error = lldb.SBError() |
| |
| if launch_info: |
| if options.run_count == 1: |
| print('Launching "%s"...' % (exe)) |
| else: |
| print( |
| 'Launching "%s"... (launch %u of %u)' |
| % (exe, run_idx + 1, options.run_count) |
| ) |
| |
| process = target.Launch(launch_info, error) |
| else: |
| if options.attach_pid != -1: |
| print("Attaching to process %i..." % (options.attach_pid)) |
| else: |
| if options.attach_wait: |
| print( |
| 'Waiting for next to process named "%s" to launch...' |
| % (options.attach_name) |
| ) |
| else: |
| print( |
| 'Attaching to existing process named "%s"...' |
| % (options.attach_name) |
| ) |
| process = target.Attach(attach_info, error) |
| |
| # Make sure the launch went ok |
| if process and process.GetProcessID() != lldb.LLDB_INVALID_PROCESS_ID: |
| pid = process.GetProcessID() |
| print("Process is %i" % (pid)) |
| if attach_info: |
| # continue process if we attached as we won't get an |
| # initial event |
| process.Continue() |
| |
| listener = debugger.GetListener() |
| # sign up for process state change events |
| stop_idx = 0 |
| done = False |
| while not done: |
| event = lldb.SBEvent() |
| if listener.WaitForEvent(options.event_timeout, event): |
| if lldb.SBProcess.EventIsProcessEvent(event): |
| state = lldb.SBProcess.GetStateFromEvent(event) |
| if state == lldb.eStateInvalid: |
| # Not a state event |
| print("process event = %s" % (event)) |
| else: |
| print( |
| "process state changed event: %s" |
| % (lldb.SBDebugger.StateAsCString(state)) |
| ) |
| if state == lldb.eStateStopped: |
| if stop_idx == 0: |
| if launch_info: |
| print("process %u launched" % (pid)) |
| run_commands( |
| command_interpreter, ["breakpoint list"] |
| ) |
| else: |
| print("attached to process %u" % (pid)) |
| for m in target.modules: |
| print(m) |
| if options.breakpoints: |
| for bp in options.breakpoints: |
| debugger.HandleCommand( |
| "_regexp-break %s" % (bp) |
| ) |
| run_commands( |
| command_interpreter, |
| ["breakpoint list"], |
| ) |
| run_commands( |
| command_interpreter, options.launch_commands |
| ) |
| else: |
| if options.verbose: |
| print("process %u stopped" % (pid)) |
| run_commands( |
| command_interpreter, options.stop_commands |
| ) |
| stop_idx += 1 |
| print_threads(process, options) |
| print("continuing process %u" % (pid)) |
| process.Continue() |
| elif state == lldb.eStateExited: |
| exit_desc = process.GetExitDescription() |
| if exit_desc: |
| print( |
| "process %u exited with status %u: %s" |
| % (pid, process.GetExitStatus(), exit_desc) |
| ) |
| else: |
| print( |
| "process %u exited with status %u" |
| % (pid, process.GetExitStatus()) |
| ) |
| run_commands( |
| command_interpreter, options.exit_commands |
| ) |
| done = True |
| elif state == lldb.eStateCrashed: |
| print("process %u crashed" % (pid)) |
| print_threads(process, options) |
| run_commands( |
| command_interpreter, options.crash_commands |
| ) |
| done = True |
| elif state == lldb.eStateDetached: |
| print("process %u detached" % (pid)) |
| done = True |
| elif state == lldb.eStateRunning: |
| # process is running, don't say anything, |
| # we will always get one of these after |
| # resuming |
| if options.verbose: |
| print("process %u resumed" % (pid)) |
| elif state == lldb.eStateUnloaded: |
| print( |
| "process %u unloaded, this shouldn't happen" |
| % (pid) |
| ) |
| done = True |
| elif state == lldb.eStateConnected: |
| print("process connected") |
| elif state == lldb.eStateAttaching: |
| print("process attaching") |
| elif state == lldb.eStateLaunching: |
| print("process launching") |
| else: |
| print("event = %s" % (event)) |
| else: |
| # timeout waiting for an event |
| print( |
| "no process event for %u seconds, killing the process..." |
| % (options.event_timeout) |
| ) |
| done = True |
| # Now that we are done dump the stdout and stderr |
| process_stdout = process.GetSTDOUT(1024) |
| if process_stdout: |
| print("Process STDOUT:\n%s" % (process_stdout)) |
| while process_stdout: |
| process_stdout = process.GetSTDOUT(1024) |
| print(process_stdout) |
| process_stderr = process.GetSTDERR(1024) |
| if process_stderr: |
| print("Process STDERR:\n%s" % (process_stderr)) |
| while process_stderr: |
| process_stderr = process.GetSTDERR(1024) |
| print(process_stderr) |
| process.Kill() # kill the process |
| else: |
| if error: |
| print(error) |
| else: |
| if launch_info: |
| print("error: launch failed") |
| else: |
| print("error: attach failed") |
| |
| lldb.SBDebugger.Terminate() |
| |
| |
| if __name__ == "__main__": |
| main(sys.argv[1:]) |
