[Lldb-commits] [lldb] r166789 - in /lldb/trunk: source/Commands/CommandObjectBreakpointCommand.cpp www/python-reference.html
Greg Clayton
gclayton at apple.com
Fri Oct 26 10:53:21 PDT 2012
Author: gclayton
Date: Fri Oct 26 12:53:21 2012
New Revision: 166789
URL: http://llvm.org/viewvc/llvm-project?rev=166789&view=rev
Log:
Updated the "breakpoint command add" documentation and fixed the web site docs for the signature of the python breakpoint callback functions.
Modified:
lldb/trunk/source/Commands/CommandObjectBreakpointCommand.cpp
lldb/trunk/www/python-reference.html
Modified: lldb/trunk/source/Commands/CommandObjectBreakpointCommand.cpp
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/source/Commands/CommandObjectBreakpointCommand.cpp?rev=166789&r1=166788&r2=166789&view=diff
==============================================================================
--- lldb/trunk/source/Commands/CommandObjectBreakpointCommand.cpp (original)
+++ lldb/trunk/source/Commands/CommandObjectBreakpointCommand.cpp Fri Oct 26 12:53:21 2012
@@ -44,71 +44,86 @@
m_options (interpreter)
{
SetHelpLong (
-"\nGeneral information about entering breakpoint commands \n\
------------------------------------------------------- \n\
- \n\
-This command will cause you to be prompted to enter the command or set \n\
-of commands you wish to be executed when the specified breakpoint is \n\
-hit. You will be told to enter your command(s), and will see a '> ' \n\
-prompt. Because you can enter one or many commands to be executed when \n\
-a breakpoint is hit, you will continue to be prompted after each \n\
-new-line that you enter, until you enter the word 'DONE', which will \n\
-cause the commands you have entered to be stored with the breakpoint \n\
-and executed when the breakpoint is hit. \n\
- \n\
-Syntax checking is not necessarily done when breakpoint commands are \n\
-entered. An improperly written breakpoint command will attempt to get \n\
-executed when the breakpoint gets hit, and usually silently fail. If \n\
-your breakpoint command does not appear to be getting executed, go \n\
-back and check your syntax. \n\
- \n\
- \n\
-Special information about PYTHON breakpoint commands \n\
----------------------------------------------------- \n\
- \n\
-You may enter either one line of Python or multiple lines of Python \n\
-(including defining whole functions, if desired). If you enter a \n\
-single line of Python, that will be passed to the Python interpreter \n\
-'as is' when the breakpoint gets hit. If you enter function \n\
-definitions, they will be passed to the Python interpreter as soon as \n\
-you finish entering the breakpoint command, and they can be called \n\
-later (don't forget to add calls to them, if you want them called when \n\
-the breakpoint is hit). If you enter multiple lines of Python that \n\
-are not function definitions, they will be collected into a new, \n\
-automatically generated Python function, and a call to the newly \n\
-generated function will be attached to the breakpoint. \n\
- \n\
-This auto-generated function is passed in two arguments: \n\
- \n\
- frame: an SBFrame object representing the frame which hit the breakpoint. \n\
- From the frame you can get back to the thread and process. \n\
- bp_loc: the number of the breakpoint location that was hit. \n\
- This is useful since one breakpoint can have many locations. \n\
- \n\
-Important Note: Because loose Python code gets collected into functions, \n\
-if you want to access global variables in the 'loose' code, you need to \n\
-specify that they are global, using the 'global' keyword. Be sure to \n\
-use correct Python syntax, including indentation, when entering Python \n\
-breakpoint commands. \n\
- \n\
-As a third option, you can pass the name of an already existing Python function \n\
-and that function will be attached to the breakpoint. It will get passed the \n\
-frame and bp_loc arguments mentioned above. \n\
- \n\
-Example Python one-line breakpoint command: \n\
- \n\
-(lldb) breakpoint command add -s python 1 \n\
-Enter your Python command(s). Type 'DONE' to end. \n\
-> print \"Hit this breakpoint!\" \n\
-> DONE \n\
- \n\
-As a convenience, this also works for a short Python one-liner: \n\
-(lldb) breakpoint command add -s python 1 -o \"import time; print time.asctime()\" \n\
-(lldb) run \n\
-Launching '.../a.out' (x86_64) \n\
-(lldb) Fri Sep 10 12:17:45 2010 \n\
-Process 21778 Stopped \n\
-* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread \n\
+"\nGeneral information about entering breakpoint commands\n\
+------------------------------------------------------\n\
+\n\
+This command will cause you to be prompted to enter the command or set of\n\
+commands you wish to be executed when the specified breakpoint is hit. You\n\
+will be told to enter your command(s), and will see a '> 'prompt. Because\n\
+you can enter one or many commands to be executed when a breakpoint is hit,\n\
+you will continue to be prompted after each new-line that you enter, until you\n\
+enter the word 'DONE', which will cause the commands you have entered to be\n\
+stored with the breakpoint and executed when the breakpoint is hit.\n\
+\n\
+Syntax checking is not necessarily done when breakpoint commands are entered.\n\
+An improperly written breakpoint command will attempt to get executed when the\n\
+breakpoint gets hit, and usually silently fail. If your breakpoint command does\n\
+not appear to be getting executed, go back and check your syntax.\n\
+\n\
+Special information about PYTHON breakpoint commands\n\
+----------------------------------------------------\n\
+\n\
+You may enter either one line of Python, multiple lines of Python (including\n\
+function definitions), or specify a Python function in a module that has already,\n\
+or will be imported. If you enter a single line of Python, that will be passed\n\
+to the Python interpreter 'as is' when the breakpoint gets hit. If you enter\n\
+function definitions, they will be passed to the Python interpreter as soon as\n\
+you finish entering the breakpoint command, and they can be called later (don't\n\
+forget to add calls to them, if you want them called when the breakpoint is\n\
+hit). If you enter multiple lines of Python that are not function definitions,\n\
+they will be collected into a new, automatically generated Python function, and\n\
+a call to the newly generated function will be attached to the breakpoint.\n\
+\n\
+\n\
+This auto-generated function is passed in three arguments:\n\
+\n\
+ frame: a lldb.SBFrame object for the frame which hit breakpoint.\n\
+ bp_loc: a lldb.SBBreakpointLocation object that represents the breakpoint\n\
+ location that was hit.\n\
+ dict: the python session dictionary hit.\n\
+\n\
+When specifying a python function with the --python-function option, you need\n\
+to supply the function name prepended by the module name. So if you import a\n\
+module named 'myutils' that contains a 'breakpoint_callback' function, you would\n\
+specify the option as:\n\
+\n\
+ --python-function myutils.breakpoint_callback\n\
+\n\
+The function itself must have the following prototype:\n\
+\n\
+def breakpoint_callback(frame, bp_loc, dict):\n\
+ # Your code goes here\n\
+\n\
+The arguments are the same as the 3 auto generation function arguments listed\n\
+above. Note that the global variable 'lldb.frame' will NOT be setup when this\n\
+function is called, so be sure to use the 'frame' argument. The 'frame' argument\n\
+can get you to the thread (frame.GetThread()), the thread can get you to the\n\
+process (thread.GetProcess()), and the process can get you back to the target\n\
+(process.GetTarget()).\n\
+\n\
+Important Note: Because loose Python code gets collected into functions, if you\n\
+want to access global variables in the 'loose' code, you need to specify that\n\
+they are global, using the 'global' keyword. Be sure to use correct Python\n\
+syntax, including indentation, when entering Python breakpoint commands.\n\
+\n\
+As a third option, you can pass the name of an already existing Python function\n\
+and that function will be attached to the breakpoint. It will get passed the\n\
+frame and bp_loc arguments mentioned above.\n\
+\n\
+Example Python one-line breakpoint command:\n\
+\n\
+(lldb) breakpoint command add -s python 1\n\
+Enter your Python command(s). Type 'DONE' to end.\n\
+> print \"Hit this breakpoint!\"\n\
+> DONE\n\
+\n\
+As a convenience, this also works for a short Python one-liner:\n\
+(lldb) breakpoint command add -s python 1 -o \"import time; print time.asctime()\"\n\
+(lldb) run\n\
+Launching '.../a.out' (x86_64)\n\
+(lldb) Fri Sep 10 12:17:45 2010\n\
+Process 21778 Stopped\n\
+* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread\n\
36 \n\
37 int c(int val)\n\
38 {\n\
@@ -116,50 +131,50 @@
40 }\n\
41 \n\
42 int main (int argc, char const *argv[])\n\
-(lldb) \n\
- \n\
-Example multiple line Python breakpoint command, using function definition: \n\
- \n\
-(lldb) breakpoint command add -s python 1 \n\
-Enter your Python command(s). Type 'DONE' to end. \n\
-> def breakpoint_output (bp_no): \n\
-> out_string = \"Hit breakpoint number \" + repr (bp_no) \n\
-> print out_string \n\
-> return True \n\
-> breakpoint_output (1) \n\
-> DONE \n\
- \n\
- \n\
-Example multiple line Python breakpoint command, using 'loose' Python: \n\
- \n\
-(lldb) breakpoint command add -s p 1 \n\
-Enter your Python command(s). Type 'DONE' to end. \n\
-> global bp_count \n\
-> bp_count = bp_count + 1 \n\
-> print \"Hit this breakpoint \" + repr(bp_count) + \" times!\" \n\
-> DONE \n\
- \n\
-In this case, since there is a reference to a global variable, \n\
-'bp_count', you will also need to make sure 'bp_count' exists and is \n\
-initialized: \n\
- \n\
-(lldb) script \n\
->>> bp_count = 0 \n\
->>> quit() \n\
- \n\
-(lldb) \n\
- \n\
- \n\
-Final Note: If you get a warning that no breakpoint command was generated, \n\
-but you did not get any syntax errors, you probably forgot to add a call \n\
-to your functions. \n\
- \n\
-Special information about debugger command breakpoint commands \n\
--------------------------------------------------------------- \n\
- \n\
-You may enter any debugger command, exactly as you would at the \n\
-debugger prompt. You may enter as many debugger commands as you like, \n\
-but do NOT enter more than one command per line. \n" );
+(lldb)\n\
+\n\
+Example multiple line Python breakpoint command, using function definition:\n\
+\n\
+(lldb) breakpoint command add -s python 1\n\
+Enter your Python command(s). Type 'DONE' to end.\n\
+> def breakpoint_output (bp_no):\n\
+> out_string = \"Hit breakpoint number \" + repr (bp_no)\n\
+> print out_string\n\
+> return True\n\
+> breakpoint_output (1)\n\
+> DONE\n\
+\n\
+\n\
+Example multiple line Python breakpoint command, using 'loose' Python:\n\
+\n\
+(lldb) breakpoint command add -s p 1\n\
+Enter your Python command(s). Type 'DONE' to end.\n\
+> global bp_count\n\
+> bp_count = bp_count + 1\n\
+> print \"Hit this breakpoint \" + repr(bp_count) + \" times!\"\n\
+> DONE\n\
+\n\
+In this case, since there is a reference to a global variable,\n\
+'bp_count', you will also need to make sure 'bp_count' exists and is\n\
+initialized:\n\
+\n\
+(lldb) script\n\
+>>> bp_count = 0\n\
+>>> quit()\n\
+\n\
+(lldb)\n\
+\n\
+\n\
+Final Note: If you get a warning that no breakpoint command was generated, but\n\
+you did not get any syntax errors, you probably forgot to add a call to your\n\
+functions.\n\
+\n\
+Special information about debugger command breakpoint commands\n\
+--------------------------------------------------------------\n\
+\n\
+You may enter any debugger command, exactly as you would at the debugger prompt.\n\
+You may enter as many debugger commands as you like, but do NOT enter more than\n\
+one command per line.\n" );
CommandArgumentEntry arg;
CommandArgumentData bp_id_arg;
Modified: lldb/trunk/www/python-reference.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/python-reference.html?rev=166789&r1=166788&r2=166789&view=diff
==============================================================================
--- lldb/trunk/www/python-reference.html (original)
+++ lldb/trunk/www/python-reference.html Fri Oct 26 12:53:21 2012
@@ -213,9 +213,9 @@
scripts to breakpoints provides a way to create complex breakpoint
conditions and also allows for smart logging and data gathering.</p>
<p>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 two arguments:</p>
+ body of a function which takes three arguments:</p>
<p>
-<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>):
+<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>):
<font color=green># Your code goes here</font>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
@@ -251,6 +251,17 @@
are represented by <b>lldb.SBBreakpointLocation</b> objects.
</td>
</tr>
+ <tr>
+ <td class="content">
+ <b>dict</b>
+ </td>
+ <td class="content">
+ <b>dict</b>
+ </td>
+ <td class="content">
+ The python session dictionary as a standard python dictionary object.
+ </td>
+ </tr>
</table>
<p>An example will show how simple it is to write some python 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
More information about the lldb-commits
mailing list