diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py --- a/lldb/docs/conf.py +++ b/lldb/docs/conf.py @@ -29,12 +29,16 @@ sys.path.insert(0, os.path.abspath(".")) # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is # set by CMake. - sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) + if os.getenv("LLDB_SWIG_MODULE") is not None: + sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) # Put the generated Python API documentation in the 'python_api' folder. This # also defines the URL these files will have in the generated website. automodapi_toctreedirnm = 'python_api' +# Disable sphinx-tabs tab closing feature. +sphinx_tabs_disable_tab_closing = True + # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -42,7 +46,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx'] +extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx', 'sphinx_tabs.tabs'] # Unless we only generate the basic manpage we need the plugin for generating # the Python API documentation. @@ -58,19 +62,19 @@ } try: - import recommonmark + import recommonmark except ImportError: - # manpages do not use any .md sources - if not building_man_page: - raise + # manpages do not use any .md sources + if not building_man_page: + raise else: - import sphinx - if sphinx.version_info >= (3, 0): - # This requires 0.5 or later. - extensions.append('recommonmark') - else: - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} - source_suffix['.md'] = 'markdown' + import sphinx + if sphinx.version_info >= (3, 0): + # This requires 0.5 or later. + extensions.append('recommonmark') + else: + source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + source_suffix['.md'] = 'markdown' # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -173,11 +177,9 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_context = { - 'css_files': [ - '_static/lldb.css' - ], - } +# Add any extra stylesheets and scripts here. +html_css_files = ['lldb.css'] +html_js_files = [] html_extra_path = ['.htaccess'] @@ -245,8 +247,8 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'LLDB.tex', u'LLDB Documentation', - u'The LLDB Team', 'manual'), + ('index', 'LLDB.tex', u'LLDB Documentation', + u'The LLDB Team', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -301,9 +303,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'LLDB', u'LLDB Documentation', - u'The LLDB Team', 'LLDB', 'One line description of project.', - 'Miscellaneous'), + ('index', 'LLDB', u'LLDB Documentation', + u'The LLDB Team', 'LLDB', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -134,7 +134,7 @@ use/symbolication use/symbols use/python - use/python-reference + use/scripting-reference use/remote use/qemu-testing use/troubleshooting diff --git a/lldb/docs/use/lua-reference.rst b/lldb/docs/use/lua-reference.rst new file mode 100644 --- /dev/null +++ b/lldb/docs/use/lua-reference.rst @@ -0,0 +1,190 @@ +Lua Reference +================ + +.. default-role:: samp + +Lua is a lightweight but powerful language. At present, Lua is only serving as +an embedded interpreter in LLDB. + +.. contents:: + :local: + +Embedded Lua Interpreter +--------------------------- + +The embedded Lua interpreter can be accessed in a variety of ways from +within LLDB. The easiest way is to use the lldb command script with no +arguments at the lldb command prompt: + +:: + + (lldb) script + >>> t = { 1, 2, 3 } + >>> print(t[1]) + 1 + >>> print(t[1] + t[2]) + 3 + >>> + +This drops you into the embedded Lua interpreter. When running under the +script command, lldb sets some convenience variables that give you quick access +to the currently selected entities that characterize the program and debugger +state. In each case, if there is no currently selected entity of the +appropriate type, the variable's IsValid method will return false. These +variables are: + ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| Variable | Type | Equivalent | Description | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| `lldb.debugger` | `lldb.SBDebugger` | `SBTarget:GetDebugger` | Contains the debugger object whose `script` command was invoked. | +| | | | The `lldb.SBDebugger` object owns the command interpreter | +| | | | and all the targets in your debug session. There will always be a | +| | | | Debugger in the embedded interpreter. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| `lldb.target` | `lldb.SBTarget` | `SBDebugger:GetSelectedTarget` | Contains the currently selected target - for instance the one made with the | +| | | | `file` or selected by the `target select ` command. | +| | | `SBProcess:GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable | +| | | | and debug files for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| `lldb.process` | `lldb.SBProcess` | `SBTarget:GetProcess` | Contains the process of the currently selected target. | +| | | | The `lldb.SBProcess` object manages the threads and allows access to | +| | | `SBThread:GetProcess` | memory for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| `lldb.thread` | `lldb.SBThread` | `SBProcess:GetSelectedThread` | Contains the currently selected thread. | +| | | | The `lldb.SBThread` object manages the stack frames in that thread. | +| | | `SBFrame:GetThread` | A thread is always selected in the command interpreter when a target stops. | +| | | | The `thread select ` command can be used to change the | +| | | | currently selected thread. So as long as you have a stopped process, there will be | +| | | | some selected thread. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| `lldb.frame` | `lldb.SBFrame` | `SBThread:GetSelectedFrame` | Contains the currently selected stack frame. | +| | | | The `lldb.SBFrame` object manage the stack locals and the register set for | +| | | | that stack. | +| | | | A stack frame is always selected in the command interpreter when a target stops. | +| | | | The `frame select ` command can be used to change the | +| | | | currently selected frame. So as long as you have a stopped process, there will | +| | | | be some selected frame. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ + +While extremely convenient, these variables have a couple caveats that you +should be aware of. First of all, they hold the values of the selected objects +on entry to the embedded interpreter. They do not update as you use the LLDB +API's to change, for example, the currently selected stack frame or thread. + +Moreover, they are only defined and meaningful while in the interactive Lua +interpreter. There is no guarantee on their value in any other situation, hence +you should not use them when defining Lua formatters, breakpoint scripts and +commands (or any other Lua extension point that LLDB provides). For the +latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or +`SBframe` instance and you can use the functions from the "Equivalent" column +to navigate between them. + +As a rationale for such behavior, consider that lldb can run in a multithreaded +environment, and another thread might call the "script" command, changing the +value out from under you. + +To get started with these objects and LLDB scripting, please note that almost +all of the lldb Lua objects are able to briefly describe themselves when you +pass them to the Lua print function: + +:: + + (lldb) script + >>> print(lldb.debugger) + Debugger (instance: "debugger_1", id: 1) + >>> print(lldb.target) + a.out + >>> print(lldb.process) + SBProcess: pid = 3385871, state = stopped, threads = 1, executable = a.out + >>> print(lldb.thread) + thread #1: tid = 3385871, 0x000055555555514f a.out`main at test.c:5:3, name = 'a.out', stop reason = breakpoint 1.1 + >>> print(lldb.frame) + frame #0: 0x000055555555514f a.out`main at test.c:5:3 + + +Running a Lua script when a breakpoint gets hit +-------------------------------------------------- + +One very powerful use of the lldb Lua API is to have a Lua script run +when a breakpoint gets hit. Adding Lua scripts to breakpoints provides a way +to create complex breakpoint conditions and also allows for smart logging and +data gathering. + +When your process hits a breakpoint to which you have attached some Lua +code, the code is executed as the body of a function which takes three +arguments: + +:: + + function breakpoint_function_wrapper(frame, bp_loc, ...): + -- Your code goes here + + ++-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Argument | Type | Description | ++-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| `frame` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. | +| | | The object will always be valid. | +| | | This `frame` argument might *not* match the currently selected stack frame found in the `lldb` module global variable `lldb.frame`. | ++-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| `bp_loc` | `lldb.SBBreakpointLocation` | The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` | +| | | objects. These breakpoint objects can have one or more locations. These locations | +| | | are represented by `lldb.SBBreakpointLocation` objects. | ++-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| `extra_args` | `lldb.SBStructuredData` | `Optional` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its | +| | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", | +| | | you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options | +| | | to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. | ++-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ + +Optionally, a Lua breakpoint command can return a value. Returning `false` +tells LLDB that you do not want to stop at the breakpoint. Any other return +value (including None or leaving out the return statement altogether) is akin +to telling LLDB to actually stop at the breakpoint. This can be useful in +situations where a breakpoint only needs to stop the process when certain +conditions are met, and you do not want to inspect the program state manually +at every stop and then continue. + +An example will show how simple it is to write some Lua code and attach it +to a breakpoint. The following example will allow you to track the order in +which the functions in a given shared library are first executed during one run +of your program. This is a simple method to gather an order file which can be +used to optimize function placement within a binary for execution locality. + +We do this by setting a regular expression breakpoint that will match every +function in the shared library. The regular expression '.' will match any +string that has at least one character in it, so we will use that. This will +result in one lldb.SBBreakpoint object that contains an +lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit, +we use a counter to track the order in which the function at this particular +breakpoint location got hit. Since our code is passed the location that was +hit, we can get the name of the function from the location, disable the +location so we won't count this function again; then log some info and continue +the process. + +Note we also have to initialize our counter, which we do with the simple +one-line version of the script command. + +Here is the code: + +:: + + (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib + Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 + (lldb) script counter = 0 + (lldb) breakpoint command add -s lua 1 + Enter your Lua command(s). Type 'quit' to end. + The commands are compiled as the body of the following Lua function + function (frame, bp_loc, ...) end + ..> counter = counter + 1 + ..> name = frame:GetFunctionName() + ..> print(string.format('[%i] %s', counter, name)) + ..> bp_loc:SetEnabled(false) + ..> return false + ..> quit + +The breakpoint command add command above attaches a Lua script to breakpoint 1. To remove the breakpoint command: + +:: + + (lldb) breakpoint command delete 1 diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/scripting-reference.rst rename from lldb/docs/use/python-reference.rst rename to lldb/docs/use/scripting-reference.rst --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/scripting-reference.rst @@ -1,23 +1,30 @@ -Python Reference -================ +Scripting Reference +=================== -The entire LLDB API is available as Python functions through a script bridging -interface. This means the LLDB API's can be used directly from python either -interactively or to build python apps that provide debugger features. - -Additionally, Python can be used as a programmatic interface within the lldb -command interpreter (we refer to this for brevity as the embedded interpreter). +Python can be used as a programmatic interface within the LLDB command +interpreter (we refer to this for brevity as the embedded interpreter). Of course, in this context it has full access to the LLDB API - with some additional conveniences we will call out in the FAQ. +Additionally, the entire LLDB API is available as Python functions through +a script bridging interface. This means the LLDB API's can be used directly +from Python either interactively or to build Python apps that provide debugger +features. + +At present, Lua is experimentally available as an embedded interpreter in LLDB. +Since some scripting features are still unavailable in Lua, there is no language +switch tab on code blocks of unsupported features. If you want to use Lua +interpreter, you should ensure that your LLDB is compiled with Lua support. +See :doc:`Building ` for instructions. + .. contents:: :local: -Documentation --------------- +Built-in Documentation +---------------------- -The LLDB API is contained in a python module named lldb. A useful resource when -writing Python extensions is the lldb Python classes reference guide. +The LLDB API is contained in a Python module named ``lldb``. A useful resource +when writing Python extensions is the `lldb` Python classes reference guide. The documentation is also accessible in an interactive debugger session with the following command: @@ -54,7 +61,8 @@ | ... -Or you can get help using any python object, here we use the lldb.process + +Or you can get help using any Python object, here we use the lldb.process object which is a global variable in the lldb module which represents the currently selected process: @@ -74,25 +82,53 @@ | ... -Embedded Python Interpreter +Embedded Script Interpreter --------------------------- -The embedded python interpreter can be accessed in a variety of ways from -within LLDB. The easiest way is to use the lldb command script with no -arguments at the lldb command prompt: +The embedded script interpreter can be accessed in a variety of ways from +within LLDB. The easiest way is to use the LLDB command ``script`` with no +arguments at the LLDB command prompt. + +By default, the embedded script interpreter is Python. To choose the language +you prefer, you can specify default language via ``--script-language`` options +when launching LLDB: + +:: + + $ lldb --script-language lua + +or pass a parameter to LLDB command ``script``. :: - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> 2+3 - 5 - >>> hex(12345) - '0x3039' - >>> + (lldb) script -l lua -- + +Language features are all available in the embedded script interpreter: + +.. tabs:: + .. code-tab:: python + + (lldb) script + Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. + >>> 2+3 + 5 + >>> hex(12345) + '0x3039' + >>> + + .. code-tab:: lua + :emphasize-lines: 1 + + (lldb) script -l lua -- + >>> t = { 1, 2, 3 } + >>> print(t[1]) + 1 + >>> print(t[1] + t[2]) + 3 + >>> -This drops you into the embedded python interpreter. When running under the -script command, lldb sets some convenience variables that give you quick access +This drops you into the embedded script interpreter. When running under the +script command, LLDB sets some convenience variables that give you quick access to the currently selected entities that characterize the program and debugger state. In each case, if there is no currently selected entity of the appropriate type, the variable's IsValid method will return false. These @@ -138,60 +174,84 @@ Moreover, they are only defined and meaningful while in the interactive Python interpreter. There is no guarantee on their value in any other situation, hence -you should not use them when defining Python formatters, breakpoint scripts and -commands (or any other Python extension point that LLDB provides). For the +you should not use them when defining custom formatters, breakpoint scripts and +commands (or any other script extension point that LLDB provides). For the latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or `SBframe` instance and you can use the functions from the "Equivalent" column to navigate between them. -As a rationale for such behavior, consider that lldb can run in a multithreaded +As a rationale for such behavior, consider that LLDB can run in a multithreaded environment, and another thread might call the "script" command, changing the value out from under you. To get started with these objects and LLDB scripting, please note that almost -all of the lldb Python objects are able to briefly describe themselves when you -pass them to the Python print function: - -:: - - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> print lldb.debugger - Debugger (instance: "debugger_1", id: 1) - >>> print lldb.target - a.out - >>> print lldb.process - SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out - >>> print lldb.thread - SBThread: tid = 0x1f03 - >>> print lldb.frame - frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 - - -Running a python script when a breakpoint gets hit --------------------------------------------------- - -One very powerful use of the lldb Python API is to have a python script run -when a breakpoint gets hit. Adding python scripts to breakpoints provides a way -to create complex breakpoint conditions and also allows for smart logging and -data gathering. +all of the lldb objects are able to briefly describe themselves when you pass +them to ``print`` function: + +.. tabs:: + .. code-tab:: python + + (lldb) script + Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. + >>> print lldb.debugger + Debugger (instance: "debugger_1", id: 1) + >>> print lldb.target + a.out + >>> print lldb.process + SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out + >>> print lldb.thread + SBThread: tid = 0x1f03 + >>> print lldb.frame + frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 + + .. code-tab:: lua + + (lldb) script -l lua -- + >>> print(lldb.debugger) + Debugger (instance: "debugger_1", id: 1) + >>> print(lldb.target) + a.out + >>> print(lldb.process) + SBProcess: pid = 3385871, state = stopped, threads = 1, executable = a.out + >>> print(lldb.thread) + thread #1: tid = 3385871, name = 'a.out', stop reason = breakpoint 1.1 + >>> print(lldb.frame) + frame #0: 0x000055555555514f a.out main at test.c:5:3 + +Running a script when a breakpoint gets hit +------------------------------------------- + +One very powerful use of the LLDB API is to have a script run when a breakpoint +gets hit. Adding python scripts to breakpoints provides a way to create complex +breakpoint conditions and also allows for smart logging and data gathering. When your process hits a breakpoint to which you have attached some python code, the code is executed as the body of a function which takes three arguments: -:: +.. tabs:: + .. code-tab:: python - def breakpoint_function_wrapper(frame, bp_loc, internal_dict): - # Your code goes here + def breakpoint_function_wrapper(frame, bp_loc, internal_dict): + # Your code goes here + + .. code-tab:: lua + + function breakpoint_function_wrapper(frame, bp_loc) + -- Your code goes here or: -:: +.. tabs:: + .. code-tab:: python + + def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): + # Your code goes here - def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): - # Your code goes here + .. code-tab:: lua + function breakpoint_function_wrapper(frame, bp_loc, ...) + -- Your code goes here +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ | Argument | Type | Description | @@ -209,7 +269,7 @@ | | | you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options | | | | to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. | +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| `internal_dict` | `dict` | The python session dictionary as a standard python dictionary object. | +| `internal_dict` | `dict` | The Python session dictionary as a standard python dictionary object. | +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ Optionally, a Python breakpoint command can return a value. Returning False @@ -242,38 +302,60 @@ Here is the code: -:: - - (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib - Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 - (lldb) script counter = 0 - (lldb) breakpoint command add --script-type python 1 - Enter your Python command(s). Type 'DONE' to end. - > # Increment our counter. Since we are in a function, this must be a global python variable - > global counter - > counter += 1 - > # Get the name of the function - > name = frame.GetFunctionName() - > # Print the order and the function name - > print '[%i] %s' % (counter, name) - > # Disable the current breakpoint location so it doesn't get hit again - > bp_loc.SetEnabled(False) - > # No need to stop here - > return False - > DONE - -The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: +.. tabs:: + .. code-tab:: python + + (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib + Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 + (lldb) script counter = 0 + (lldb) breakpoint command add --script-type python 1 + Enter your Python command(s). Type 'DONE' to end. + > # Increment our counter. Since we are in a function, this must be a global python variable + > global counter + > counter += 1 + > # Get the name of the function + > name = frame.GetFunctionName() + > # Print the order and the function name + > print '[%i] %s' % (counter, name) + > # Disable the current breakpoint location so it doesn't get hit again + > bp_loc.SetEnabled(False) + > # No need to stop here + > return False + > DONE + + .. code-tab:: lua + + (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib + Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 + (lldb) script -l lua -- counter = 0 + (lldb) breakpoint command add -s lua 1 + Enter your Lua command(s). Type 'quit' to end. + The commands are compiled as the body of the following Lua function + function (frame, bp_loc, ...) end + ..> -- Increment our counter + ..> counter = counter + 1 + ..> -- Get the name of the function + ..> name = frame:GetFunctionName() + ..> -- Print the order and the function name + ..> print(string.format('[%i] %s', counter, name)) + ..> -- Disable the current breakpoint location so it doesn't get hit again + ..> bp_loc:SetEnabled(false) + ..> -- No need to stop here + ..> return false + ..> quit + +The breakpoint command add command above attaches a python script to +breakpoint 1. To remove the breakpoint command: :: (lldb) breakpoint command delete 1 -Using the python api's to create custom breakpoints ---------------------------------------------------- - +Create custom breakpoints +------------------------- -Another use of the Python API's in lldb is to create a custom breakpoint +Another use of the scripting API's in lldb is to create a custom breakpoint resolver. This facility was added in r342259. It allows you to provide the algorithm which will be used in the breakpoint's @@ -423,8 +505,8 @@ you pass in empty lists, the breakpoint will use the default "search everywhere,accept everything" filter. -Using the python API' to create custom stepping logic ------------------------------------------------------ +Create custom stepping logic +---------------------------- A slightly esoteric use of the Python API's is to construct custom stepping types. LLDB's stepping is driven by a stack of "thread plans" and a fairly @@ -486,8 +568,8 @@ while performing the step-over. -Create a new lldb command using a Python function -------------------------------------------------- +Create a new lldb command +------------------------- Python functions can be used to create new LLDB command interpreter commands, which will work like all the natively defined lldb commands. This provides a @@ -527,7 +609,7 @@ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ | `debugger` | `lldb.SBDebugger` | The current debugger object. | +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| `command` | `python string` | A python string containing all arguments for your command. If you need to chop up the arguments | +| `command` | `string` | A python string containing all arguments for your command. If you need to chop up the arguments | | | | try using the `shlex` module's shlex.split(command) to properly extract the | | | | arguments. | +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+