| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="debugger-hooks.html" /> |
| 13 | <link rel="prev" href="module-pdb.html" /> |
| 14 | <link rel="parent" href="module-pdb.html" /> |
| 15 | <link rel="next" href="debugger-hooks.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>9.1 Debugger Commands </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="9. The Python Debugger" |
| 25 | href="module-pdb.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="9. The Python Debugger" |
| 28 | href="module-pdb.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="9.2 How It Works" |
| 31 | href="debugger-hooks.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="module-pdb.html">9. The Python Debugger</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-pdb.html">9. The Python Debugger</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="debugger-hooks.html">9.2 How It Works</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION0011100000000000000000"></A><A NAME="debugger-commands"></A> |
| 56 | <BR> |
| 57 | 9.1 Debugger Commands |
| 58 | </H1> |
| 59 | |
| 60 | <P> |
| 61 | The debugger recognizes the following commands. Most commands can be |
| 62 | abbreviated to one or two letters; e.g. "<tt class="samp">h(elp)</tt>" means that |
| 63 | either "<tt class="samp">h</tt>" or "<tt class="samp">help</tt>" can be used to enter the help |
| 64 | command (but not "<tt class="samp">he</tt>" or "<tt class="samp">hel</tt>", nor "<tt class="samp">H</tt>" or |
| 65 | "<tt class="samp">Help</tt>" or "<tt class="samp">HELP</tt>"). Arguments to commands must be |
| 66 | separated by whitespace (spaces or tabs). Optional arguments are |
| 67 | enclosed in square brackets ("<tt class="samp">[]</tt>") in the command syntax; the |
| 68 | square brackets must not be typed. Alternatives in the command syntax |
| 69 | are separated by a vertical bar ("<tt class="samp">|</tt>"). |
| 70 | |
| 71 | <P> |
| 72 | Entering a blank line repeats the last command entered. Exception: if |
| 73 | the last command was a "<tt class="samp">list</tt>" command, the next 11 lines are |
| 74 | listed. |
| 75 | |
| 76 | <P> |
| 77 | Commands that the debugger doesn't recognize are assumed to be Python |
| 78 | statements and are executed in the context of the program being |
| 79 | debugged. Python statements can also be prefixed with an exclamation |
| 80 | point ("<tt class="samp">!</tt>"). This is a powerful way to inspect the program |
| 81 | being debugged; it is even possible to change a variable or call a |
| 82 | function. When an |
| 83 | exception occurs in such a statement, the exception name is printed |
| 84 | but the debugger's state is not changed. |
| 85 | |
| 86 | <P> |
| 87 | Multiple commands may be entered on a single line, separated by |
| 88 | "<tt class="samp">;;</tt>". (A single "<tt class="samp">;</tt>" is not used as it is |
| 89 | the separator for multiple commands in a line that is passed to |
| 90 | the Python parser.) |
| 91 | No intelligence is applied to separating the commands; |
| 92 | the input is split at the first "<tt class="samp">;;</tt>" pair, even if it is in |
| 93 | the middle of a quoted string. |
| 94 | |
| 95 | <P> |
| 96 | The debugger supports aliases. Aliases can have parameters which |
| 97 | allows one a certain level of adaptability to the context under |
| 98 | examination. |
| 99 | |
| 100 | <P> |
| 101 | If a file <span class="file">.pdbrc</span> |
| 102 | <a id='l2h-3102' xml:id='l2h-3102'></a><a id='l2h-3103' xml:id='l2h-3103'></a>exists in the user's home directory or in the current directory, it is |
| 103 | read in and executed as if it had been typed at the debugger prompt. |
| 104 | This is particularly useful for aliases. If both files exist, the one |
| 105 | in the home directory is read first and aliases defined there can be |
| 106 | overridden by the local file. |
| 107 | |
| 108 | <P> |
| 109 | <DL> |
| 110 | <DT><STRONG>h(elp) <big>[</big><var>command</var><big>]</big></STRONG></DT> |
| 111 | <DD><P> |
| 112 | Without argument, print the list of available commands. With a |
| 113 | <var>command</var> as argument, print help about that command. "<tt class="samp">help |
| 114 | pdb</tt>" displays the full documentation file; if the environment variable |
| 115 | <a class="envvar" id='l2h-3104' xml:id='l2h-3104'>PAGER</a> is defined, the file is piped through that command |
| 116 | instead. Since the <var>command</var> argument must be an identifier, |
| 117 | "<tt class="samp">help exec</tt>" must be entered to get help on the "<tt class="samp">!</tt>" command. |
| 118 | |
| 119 | <P> |
| 120 | </DD> |
| 121 | <DT><STRONG>w(here)</STRONG></DT> |
| 122 | <DD><P> |
| 123 | Print a stack trace, with the most recent frame at the bottom. An |
| 124 | arrow indicates the current frame, which determines the context of |
| 125 | most commands. |
| 126 | |
| 127 | <P> |
| 128 | </DD> |
| 129 | <DT><STRONG>d(own)</STRONG></DT> |
| 130 | <DD><P> |
| 131 | Move the current frame one level down in the stack trace |
| 132 | (to an newer frame). |
| 133 | |
| 134 | <P> |
| 135 | </DD> |
| 136 | <DT><STRONG>u(p)</STRONG></DT> |
| 137 | <DD><P> |
| 138 | Move the current frame one level up in the stack trace |
| 139 | (to a older frame). |
| 140 | |
| 141 | <P> |
| 142 | </DD> |
| 143 | <DT><STRONG>b(reak) <big>[</big><big>[</big><var>filename</var>:<big>]</big><var>lineno</var><code><BIG CLASS="XLARGE">|</BIG></code><var>function</var><big>[</big>, <var>condition</var><big>]</big><big>]</big></STRONG></DT> |
| 144 | <DD><P> |
| 145 | With a <var>lineno</var> argument, set a break there in the current |
| 146 | file. With a <var>function</var> argument, set a break at the first |
| 147 | executable statement within that function. |
| 148 | The line number may be prefixed with a filename and a colon, |
| 149 | to specify a breakpoint in another file (probably one that |
| 150 | hasn't been loaded yet). The file is searched on <code>sys.path</code>. |
| 151 | Note that each breakpoint is assigned a number to which all the other |
| 152 | breakpoint commands refer. |
| 153 | |
| 154 | <P> |
| 155 | If a second argument is present, it is an expression which must |
| 156 | evaluate to true before the breakpoint is honored. |
| 157 | |
| 158 | <P> |
| 159 | Without argument, list all breaks, including for each breakpoint, |
| 160 | the number of times that breakpoint has been hit, the current |
| 161 | ignore count, and the associated condition if any. |
| 162 | |
| 163 | <P> |
| 164 | </DD> |
| 165 | <DT><STRONG>tbreak <big>[</big><big>[</big><var>filename</var>:<big>]</big><var>lineno</var><code><BIG CLASS="XLARGE">|</BIG></code><var>function</var><big>[</big>, <var>condition</var><big>]</big><big>]</big></STRONG></DT> |
| 166 | <DD><P> |
| 167 | Temporary breakpoint, which is removed automatically when it is |
| 168 | first hit. The arguments are the same as break. |
| 169 | |
| 170 | <P> |
| 171 | </DD> |
| 172 | <DT><STRONG>cl(ear) <big>[</big><var>bpnumber</var> <big>[</big><var>bpnumber ...</var><big>]</big><big>]</big></STRONG></DT> |
| 173 | <DD><P> |
| 174 | With a space separated list of breakpoint numbers, clear those |
| 175 | breakpoints. Without argument, clear all breaks (but first |
| 176 | ask confirmation). |
| 177 | |
| 178 | <P> |
| 179 | </DD> |
| 180 | <DT><STRONG>disable <big>[</big><var>bpnumber</var> <big>[</big><var>bpnumber ...</var><big>]</big><big>]</big></STRONG></DT> |
| 181 | <DD><P> |
| 182 | Disables the breakpoints given as a space separated list of |
| 183 | breakpoint numbers. Disabling a breakpoint means it cannot cause |
| 184 | the program to stop execution, but unlike clearing a breakpoint, it |
| 185 | remains in the list of breakpoints and can be (re-)enabled. |
| 186 | |
| 187 | <P> |
| 188 | </DD> |
| 189 | <DT><STRONG>enable <big>[</big><var>bpnumber</var> <big>[</big><var>bpnumber ...</var><big>]</big><big>]</big></STRONG></DT> |
| 190 | <DD><P> |
| 191 | Enables the breakpoints specified. |
| 192 | |
| 193 | <P> |
| 194 | </DD> |
| 195 | <DT><STRONG>ignore <var>bpnumber</var> <big>[</big><var>count</var><big>]</big></STRONG></DT> |
| 196 | <DD><P> |
| 197 | Sets the ignore count for the given breakpoint number. If |
| 198 | count is omitted, the ignore count is set to 0. A breakpoint |
| 199 | becomes active when the ignore count is zero. When non-zero, |
| 200 | the count is decremented each time the breakpoint is reached |
| 201 | and the breakpoint is not disabled and any associated condition |
| 202 | evaluates to true. |
| 203 | |
| 204 | <P> |
| 205 | </DD> |
| 206 | <DT><STRONG>condition <var>bpnumber</var> <big>[</big><var>condition</var><big>]</big></STRONG></DT> |
| 207 | <DD><P> |
| 208 | Condition is an expression which must evaluate to true before |
| 209 | the breakpoint is honored. If condition is absent, any existing |
| 210 | condition is removed; i.e., the breakpoint is made unconditional. |
| 211 | |
| 212 | <P> |
| 213 | </DD> |
| 214 | <DT><STRONG>s(tep)</STRONG></DT> |
| 215 | <DD><P> |
| 216 | Execute the current line, stop at the first possible occasion |
| 217 | (either in a function that is called or on the next line in the |
| 218 | current function). |
| 219 | |
| 220 | <P> |
| 221 | </DD> |
| 222 | <DT><STRONG>n(ext)</STRONG></DT> |
| 223 | <DD><P> |
| 224 | Continue execution until the next line in the current function |
| 225 | is reached or it returns. (The difference between "<tt class="samp">next</tt>" and |
| 226 | "<tt class="samp">step</tt>" is that "<tt class="samp">step</tt>" stops inside a called function, while |
| 227 | "<tt class="samp">next</tt>" executes called functions at (nearly) full speed, only |
| 228 | stopping at the next line in the current function.) |
| 229 | |
| 230 | <P> |
| 231 | </DD> |
| 232 | <DT><STRONG>r(eturn)</STRONG></DT> |
| 233 | <DD><P> |
| 234 | Continue execution until the current function returns. |
| 235 | |
| 236 | <P> |
| 237 | </DD> |
| 238 | <DT><STRONG>c(ont(inue))</STRONG></DT> |
| 239 | <DD><P> |
| 240 | Continue execution, only stop when a breakpoint is encountered. |
| 241 | |
| 242 | <P> |
| 243 | </DD> |
| 244 | <DT><STRONG>j(ump) <var>lineno</var></STRONG></DT> |
| 245 | <DD><P> |
| 246 | Set the next line that will be executed. Only available in the |
| 247 | bottom-most frame. This lets you jump back and execute code |
| 248 | again, or jump forward to skip code that you don't want to run. |
| 249 | |
| 250 | <P> |
| 251 | It should be noted that not all jumps are allowed -- for instance it |
| 252 | is not possible to jump into the middle of a <tt class="keyword">for</tt> loop or out |
| 253 | of a <tt class="keyword">finally</tt> clause. |
| 254 | |
| 255 | <P> |
| 256 | </DD> |
| 257 | <DT><STRONG>l(ist) <big>[</big><var>first</var><big>[</big>, <var>last</var><big>]</big><big>]</big></STRONG></DT> |
| 258 | <DD><P> |
| 259 | List source code for the current file. Without arguments, list 11 |
| 260 | lines around the current line or continue the previous listing. With |
| 261 | one argument, list 11 lines around at that line. With two arguments, |
| 262 | list the given range; if the second argument is less than the first, |
| 263 | it is interpreted as a count. |
| 264 | |
| 265 | <P> |
| 266 | </DD> |
| 267 | <DT><STRONG>a(rgs)</STRONG></DT> |
| 268 | <DD><P> |
| 269 | Print the argument list of the current function. |
| 270 | |
| 271 | <P> |
| 272 | </DD> |
| 273 | <DT><STRONG>p <var>expression</var></STRONG></DT> |
| 274 | <DD><P> |
| 275 | Evaluate the <var>expression</var> in the current context and print its |
| 276 | value. <span class="note"><b class="label">Note:</b> |
| 277 | "<tt class="samp">print</tt>" can also be used, but is not a debugger |
| 278 | command -- this executes the Python <tt class="keyword">print</tt> statement.</span> |
| 279 | |
| 280 | <P> |
| 281 | </DD> |
| 282 | <DT><STRONG>pp <var>expression</var></STRONG></DT> |
| 283 | <DD><P> |
| 284 | Like the "<tt class="samp">p</tt>" command, except the value of the expression is |
| 285 | pretty-printed using the <tt class="module">pprint</tt> module. |
| 286 | |
| 287 | <P> |
| 288 | </DD> |
| 289 | <DT><STRONG>alias <big>[</big><var>name</var> <big>[</big>command<big>]</big><big>]</big></STRONG></DT> |
| 290 | <DD><P> |
| 291 | Creates an alias called <var>name</var> that executes <var>command</var>. The |
| 292 | command must <em>not</em> be enclosed in quotes. Replaceable parameters |
| 293 | can be indicated by "<tt class="samp">%1</tt>", "<tt class="samp">%2</tt>", and so on, while "<tt class="samp">%*</tt>" is |
| 294 | replaced by all the parameters. If no command is given, the current |
| 295 | alias for <var>name</var> is shown. If no arguments are given, all |
| 296 | aliases are listed. |
| 297 | |
| 298 | <P> |
| 299 | Aliases may be nested and can contain anything that can be |
| 300 | legally typed at the pdb prompt. Note that internal pdb commands |
| 301 | <em>can</em> be overridden by aliases. Such a command is |
| 302 | then hidden until the alias is removed. Aliasing is recursively |
| 303 | applied to the first word of the command line; all other words |
| 304 | in the line are left alone. |
| 305 | |
| 306 | <P> |
| 307 | As an example, here are two useful aliases (especially when placed |
| 308 | in the <span class="file">.pdbrc</span> file): |
| 309 | |
| 310 | <P> |
| 311 | <div class="verbatim"><pre> |
| 312 | #Print instance variables (usage "pi classInst") |
| 313 | alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] |
| 314 | #Print instance variables in self |
| 315 | alias ps pi self |
| 316 | </pre></div> |
| 317 | |
| 318 | <P> |
| 319 | </DD> |
| 320 | <DT><STRONG>unalias <var>name</var></STRONG></DT> |
| 321 | <DD><P> |
| 322 | Deletes the specified alias. |
| 323 | |
| 324 | <P> |
| 325 | </DD> |
| 326 | <DT><STRONG><big>[</big>!<big>]</big><var>statement</var></STRONG></DT> |
| 327 | <DD><P> |
| 328 | Execute the (one-line) <var>statement</var> in the context of |
| 329 | the current stack frame. |
| 330 | The exclamation point can be omitted unless the first word |
| 331 | of the statement resembles a debugger command. |
| 332 | To set a global variable, you can prefix the assignment |
| 333 | command with a "<tt class="samp">global</tt>" command on the same line, e.g.: |
| 334 | |
| 335 | <P> |
| 336 | <div class="verbatim"><pre> |
| 337 | (Pdb) global list_options; list_options = ['-l'] |
| 338 | (Pdb) |
| 339 | </pre></div> |
| 340 | |
| 341 | <P> |
| 342 | </DD> |
| 343 | <DT><STRONG>q(uit)</STRONG></DT> |
| 344 | <DD><P> |
| 345 | Quit from the debugger. |
| 346 | The program being executed is aborted. |
| 347 | |
| 348 | <P> |
| 349 | </DD> |
| 350 | </DL> |
| 351 | |
| 352 | <P> |
| 353 | |
| 354 | <DIV CLASS="navigation"> |
| 355 | <div class='online-navigation'> |
| 356 | <p></p><hr /> |
| 357 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 358 | <tr> |
| 359 | <td class='online-navigation'><a rel="prev" title="9. The Python Debugger" |
| 360 | href="module-pdb.html"><img src='../icons/previous.png' |
| 361 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 362 | <td class='online-navigation'><a rel="parent" title="9. The Python Debugger" |
| 363 | href="module-pdb.html"><img src='../icons/up.png' |
| 364 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 365 | <td class='online-navigation'><a rel="next" title="9.2 How It Works" |
| 366 | href="debugger-hooks.html"><img src='../icons/next.png' |
| 367 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 368 | <td align="center" width="100%">Python Library Reference</td> |
| 369 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 370 | href="contents.html"><img src='../icons/contents.png' |
| 371 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 372 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 373 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 374 | <td class='online-navigation'><a rel="index" title="Index" |
| 375 | href="genindex.html"><img src='../icons/index.png' |
| 376 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 377 | </tr></table> |
| 378 | <div class='online-navigation'> |
| 379 | <b class="navlabel">Previous:</b> |
| 380 | <a class="sectref" rel="prev" href="module-pdb.html">9. The Python Debugger</A> |
| 381 | <b class="navlabel">Up:</b> |
| 382 | <a class="sectref" rel="parent" href="module-pdb.html">9. The Python Debugger</A> |
| 383 | <b class="navlabel">Next:</b> |
| 384 | <a class="sectref" rel="next" href="debugger-hooks.html">9.2 How It Works</A> |
| 385 | </div> |
| 386 | </div> |
| 387 | <hr /> |
| 388 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 389 | </DIV> |
| 390 | <!--End of Navigation Panel--> |
| 391 | <ADDRESS> |
| 392 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 393 | </ADDRESS> |
| 394 | </BODY> |
| 395 | </HTML> |