This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.003_01: pod/perldata.pod
[perl5.git] / pod / perldebug.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perldebug - Perl debugging
4
5=head1 DESCRIPTION
6
7First of all, have you tried using the B<-w> switch?
8
9=head2 Debugging
10
11If you invoke Perl with a B<-d> switch, your script will be run under the
12debugger. However, the Perl debugger is not a separate program as it is
13in a C environment. Instead, the B<-d> flag tells the compiler to insert
14source information into the pseudocode it's about to hand to the
15interpreter. (That means your code must compile correctly for the
16debugger to work on it.) Then when the interpreter starts up, it
17pre-loads a Perl library file containing the debugger itself. The program
18will halt before the first executable statement (but see below) and ask
19you for one of the following commands:
20
21=over 12
22
23=item h
24
25Prints out a help message.
26
27=item T
28
29Stack trace.
30If you do bizarre things to your @_ arguments in a subroutine, the stack
31backtrace will not always show the original values.
32
33=item s
34
35Single step. Executes until it reaches the beginning of another
36statement.
37
38=item n
39
40Next. Executes over subroutine calls, until it reaches the beginning
41of the next statement.
42
43=item f
44
45Finish. Executes statements until it has finished the current
46subroutine.
47
48=item c
49
50Continue. Executes until the next breakpoint is reached.
51
52=item c line
53
54Continue to the specified line. Inserts a one-time-only breakpoint at
55the specified line.
56
57=item <CR>
58
59Repeat last n or s.
60
61=item l min+incr
62
63List incr+1 lines starting at min. If min is omitted, starts where
64last listing left off. If incr is omitted, previous value of incr is
65used.
66
67=item l min-max
68
69List lines in the indicated range.
70
71=item l line
72
73List just the indicated line.
74
75=item l
76
77List next window.
78
79=item -
80
81List previous window.
82
83=item w line
84
85List window (a few lines worth of code) around line.
86
87=item l subname
88
89List subroutine. If it's a long subroutine it just lists the
90beginning. Use "l" to list more.
91
92=item /pattern/
93
94Regular expression search forward in the source code for pattern; the
95final / is optional.
96
97=item ?pattern?
98
99Regular expression search backward in the source code for pattern; the
100final ? is optional.
101
102=item L
103
104List lines that have breakpoints or actions.
105
106=item S
107
108Lists the names of all subroutines.
109
110=item t
111
112Toggle trace mode on or off.
113
114=item b line [ condition ]
115
116Set a breakpoint. If line is omitted, sets a breakpoint on the line
117that is about to be executed. If a condition is specified, it is
118evaluated each time the statement is reached and a breakpoint is taken
119only if the condition is true. Breakpoints may only be set on lines
120that begin an executable statement. Conditions don't use C<if>:
121
122 b 237 $x > 30
123 b 33 /pattern/i
124
125=item b subname [ condition ]
126
127Set breakpoint at first executable line of subroutine.
128
129=item d line
130
131Delete breakpoint. If line is omitted, deletes the breakpoint on the
132line that is about to be executed.
133
134=item D
135
136Delete all breakpoints.
137
138=item a line command
139
140Set an action for line. A multiline command may be entered by
141backslashing the newlines. This command is Perl code, not another
142debugger command.
143
144=item A
145
146Delete all line actions.
147
148=item < command
149
150Set an action to happen before every debugger prompt. A multiline
151command may be entered by backslashing the newlines.
152
153=item > command
154
155Set an action to happen after the prompt when you've just given a
156command to return to executing the script. A multiline command may be
157entered by backslashing the newlines.
158
159=item V package [symbols]
160
161Display all (or some) variables in package (defaulting to the C<main>
162package) using a data pretty-printer (hashes show their keys and values so
163you see what's what, control characters are made printable, etc.). Make
164sure you don't put the type specifier (like $) there, just the symbol
165names, like this:
166
167 V DB filename line
168
169=item X [symbols]
170
171Same as as "V" command, but within the current package.
172
173=item ! number
174
175Redo a debugging command. If number is omitted, redoes the previous
176command.
177
178=item ! -number
179
180Redo the command that was that many commands ago.
181
182=item H -number
183
184Display last n commands. Only commands longer than one character are
185listed. If number is omitted, lists them all.
186
187=item q or ^D
188
189Quit. ("quit" doesn't work for this.)
190
191=item command
192
193Execute command as a Perl statement. A missing semicolon will be
194supplied.
195
196=item p expr
197
198Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
199/dev/tty, regardless of where STDOUT may be redirected to.
200
201=back
202
203Any command you type in that isn't recognized by the debugger will be
204directly executed (C<eval>'d) as Perl code. Leading white space will
205cause the debugger to think it's C<NOT> a debugger command.
206
207If you have any compile-time executable statements (code within a BEGIN
208block or a C<use> statement), these will I<NOT> be stopped by debugger,
209although C<require>s will. From your own code, however, you can transfer
210control back to the debugger using the following statement, which is harmless
211if the debugger is not running:
212
213 $DB::single = 1;
214
215=head2 Customization
216
217If you want to modify the debugger, copy F<perl5db.pl> from the Perl
218library to another name and modify it as necessary. You'll also want
219to set environment variable PERL5DB to say something like this:
220
221 BEGIN { require "myperl5db.pl" }
222
223You can do some customization by setting up a F<.perldb> file which
224contains initialization code. For instance, you could make aliases
225like these (the last one in particular most people seem to expect to
226be there):
227
228 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
229 $DB::alias{'stop'} = 's/^stop (at|in)/b/';
230 $DB::alias{'.'} = 's/^\./p '
231 . '"\$DB::sub(\$DB::filename:\$DB::line):\t"'
232 . ',\$DB::dbline[\$DB::line]/' ;
233
234
235=head2 Other resources
236
237You did try the B<-w> switch, didn't you?
238
239=head1 BUGS
240
241If your program exit()s or die()s, so does the debugger.
242
243There's no builtin way to restart the debugger without exiting and coming back
244into it. You could use an alias like this:
245
246 $DB::alias{'rerun'} = 'exec "perl -d $DB::filename"';
247
248But you'd lose any pending breakpoint information, and that might not
249be the right path, etc.