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
11import commands
12import optparse
13import os
14import platform
15import sys
16
17#----------------------------------------------------------------------
18# Code that auto imports LLDB
19#----------------------------------------------------------------------
20try:
21    # Just try for LLDB in case PYTHONPATH is already correctly setup
22    import lldb
23except 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
51def print_threads(process, options):
52    if options.show_threads:
53        for thread in process:
54            print '%s %s' % (thread, thread.GetFrameAtIndex(0))
55
56def 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
67def 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
271if __name__ == '__main__':
272    main(sys.argv[1:])