Commit | Line | Data |
---|---|---|
86530b38 AT |
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> |