1PERLDEBTUT(1) Perl Programmers Reference Guide PERLDEBTUT(1)
2
6 perldebtut - Perl debugging tutorial
7
9 A (very) lightweight introduction in the use of the perl debugger, and
10 a pointer to existing, deeper sources of information on the subject of
11 debugging perl programs.
12 There's an extraordinary number of people out there who don't appear to
14 know anything about using the perl debugger, though they use the
15 language every day. This is for them.
16
18 First of all, there's a few things you can do to make your life a lot
19 more straightforward when it comes to debugging perl programs, without
20 using the debugger at all. To demonstrate, here's a simple script,
21 named "hello", with a problem:
22 #!/usr/bin/perl
24 $var1 = 'Hello World'; # always wanted to do that :-)
26 $var2 = "$varl\n";
27 print $var2;
29 exit;
30 While this compiles and runs happily, it probably won't do what's
32 expected, namely it doesn't print "Hello World\n" at all; It will on
33 the other hand do exactly what it was told to do, computers being a bit
34 that way inclined. That is, it will print out a newline character, and
35 you'll get what looks like a blank line. It looks like there's 2
36 variables when (because of the typo) there's really 3:
37 $var1 = 'Hello World';
39 $varl = undef;
40 $var2 = "\n";
41 To catch this kind of problem, we can force each variable to be
43 declared before use by pulling in the strict module, by putting 'use
44 strict;' after the first line of the script.
45 Now when you run it, perl complains about the 3 undeclared variables
47 and we get four error messages because one variable is referenced
48 twice:
49 Global symbol "$var1" requires explicit package name at ./t1 line 4.
51 Global symbol "$var2" requires explicit package name at ./t1 line 5.
52 Global symbol "$varl" requires explicit package name at ./t1 line 5.
53 Global symbol "$var2" requires explicit package name at ./t1 line 7.
54 Execution of ./hello aborted due to compilation errors.
55 Luvverly! and to fix this we declare all variables explicitly and now
57 our script looks like this:
58 #!/usr/bin/perl
60 use strict;
61 my $var1 = 'Hello World';
63 my $varl = undef;
64 my $var2 = "$varl\n";
65 print $var2;
67 exit;
68 We then do (always a good idea) a syntax check before we try to run it
70 again:
71 > perl -c hello
73 hello syntax OK
74 And now when we run it, we get "\n" still, but at least we know why.
76 Just getting this script to compile has exposed the '$varl' (with the
77 letter 'l') variable, and simply changing $varl to $var1 solves the
78 problem.
79
81 Ok, but how about when you want to really see your data, what's in that
82 dynamic variable, just before using it?
83 #!/usr/bin/perl
85 use strict;
86 my $key = 'welcome';
88 my %data = (
89 'this' => qw(that),
90 'tom' => qw(and jerry),
91 'welcome' => q(Hello World),
92 'zip' => q(welcome),
93 );
94 my @data = keys %data;
95 print "$data{$key}\n";
97 exit;
98 Looks OK, after it's been through the syntax check (perl -c
100 scriptname), we run it and all we get is a blank line again! Hmmmm.
101 One common debugging approach here, would be to liberally sprinkle a
103 few print statements, to add a check just before we print out our data,
104 and another just after:
105 print "All OK\n" if grep($key, keys %data);
107 print "$data{$key}\n";
108 print "done: '$data{$key}'\n";
109 And try again:
111 > perl data
113 All OK
114 done: ''
116 After much staring at the same piece of code and not seeing the wood
118 for the trees for some time, we get a cup of coffee and try another
119 approach. That is, we bring in the cavalry by giving perl the '-d'
120 switch on the command line:
121 > perl -d data
123 Default die handler restored.
124 Loading DB routines from perl5db.pl version 1.07
126 Editor support available.
127 Enter h or `h h' for help, or `man perldebug' for more help.
129 main::(./data:4): my $key = 'welcome';
131 Now, what we've done here is to launch the built-in perl debugger on
133 our script. It's stopped at the first line of executable code and is
134 waiting for input.
135 Before we go any further, you'll want to know how to quit the debugger:
137 use just the letter 'q', not the words 'quit' or 'exit':
138 DB<1> q
140 >
141 That's it, you're back on home turf again.
143
145 Fire the debugger up again on your script and we'll look at the help
146 menu. There's a couple of ways of calling help: a simple 'h' will get
147 the summary help list, '|h' (pipe-h) will pipe the help through your
148 pager (which is (probably 'more' or 'less'), and finally, 'h h'
149 (h-space-h) will give you the entire help screen. Here is the summary
150 page:
151 D1h
153 List/search source lines: Control script execution:
155 l [ln|sub] List source code T Stack trace
156 - or . List previous/current line s [expr] Single step [in expr]
157 v [line] View around line n [expr] Next, steps over subs
158 f filename View source in file <CR/Enter> Repeat last n or s
159 /pattern/ ?patt? Search forw/backw r Return from subroutine
160 M Show module versions c [ln|sub] Continue until position
161 Debugger controls: L List break/watch/actions
162 o [...] Set debugger options t [expr] Toggle trace [trace expr]
163 <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
164 ! [N|pat] Redo a previous command B ln|* Delete a/all breakpoints
165 H [-num] Display last num commands a [ln] cmd Do cmd before line
166 = [a val] Define/list an alias A ln|* Delete a/all actions
167 h [db_cmd] Get help on command w expr Add a watch expression
168 h h Complete help page W expr|* Delete a/all watch exprs
169 |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
170 q or ^D Quit R Attempt a restart
171 Data Examination: expr Execute perl code, also see: s,n,t expr
172 x|m expr Evals expr in list context, dumps the result or lists methods.
173 p expr Print expression (uses script's current package).
174 S [[!]pat] List subroutine names [not] matching pattern
175 V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
176 X [Vars] Same as "V current_package [Vars]".
177 y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
178 For more help, type h cmd_letter, or run man perldebug for all docs.
179 More confusing options than you can shake a big stick at! It's not as
181 bad as it looks and it's very useful to know more about all of it, and
182 fun too!
183 There's a couple of useful ones to know about straight away. You
185 wouldn't think we're using any libraries at all at the moment, but 'M'
186 will show which modules are currently loaded, and their version number,
187 while 'm' will show the methods, and 'S' shows all subroutines (by
188 pattern) as shown below. 'V' and 'X' show variables in the program by
189 package scope and can be constrained by pattern.
190 DB<2>S str
192 dumpvar::stringify
193 strict::bits
194 strict::import
195 strict::unimport
196 Using 'X' and cousins requires you not to use the type identifiers
198 ($@%), just the 'name':
199 DM<3>X ~err
201 FileHandle(stderr) => fileno(2)
202 Remember we're in our tiny program with a problem, we should have a
204 look at where we are, and what our data looks like. First of all let's
205 view some code at our present position (the first line of code in this
206 case), via 'v':
207 DB<4> v
209 1 #!/usr/bin/perl
210 2: use strict;
211 3
212 4==> my $key = 'welcome';
213 5: my %data = (
214 6 'this' => qw(that),
215 7 'tom' => qw(and jerry),
216 8 'welcome' => q(Hello World),
217 9 'zip' => q(welcome),
218 10 );
219 At line number 4 is a helpful pointer, that tells you where you are
221 now. To see more code, type 'v' again:
222 DB<4> v
224 8 'welcome' => q(Hello World),
225 9 'zip' => q(welcome),
226 10 );
227 11: my @data = keys %data;
228 12: print "All OK\n" if grep($key, keys %data);
229 13: print "$data{$key}\n";
230 14: print "done: '$data{$key}'\n";
231 15: exit;
232 And if you wanted to list line 5 again, type 'l 5', (note the space):
234 DB<4> l 5
236 5: my %data = (
237 In this case, there's not much to see, but of course normally there's
239 pages of stuff to wade through, and 'l' can be very useful. To reset
240 your view to the line we're about to execute, type a lone period '.':
241 DB<5> .
243 main::(./data_a:4): my $key = 'welcome';
244 The line shown is the one that is about to be executed next, it hasn't
246 happened yet. So while we can print a variable with the letter 'p', at
247 this point all we'd get is an empty (undefined) value back. What we
248 need to do is to step through the next executable statement with an
249 's':
250 DB<6> s
252 main::(./data_a:5): my %data = (
253 main::(./data_a:6): 'this' => qw(that),
254 main::(./data_a:7): 'tom' => qw(and jerry),
255 main::(./data_a:8): 'welcome' => q(Hello World),
256 main::(./data_a:9): 'zip' => q(welcome),
257 main::(./data_a:10): );
258 Now we can have a look at that first ($key) variable:
260 DB<7> p $key
262 welcome
263 line 13 is where the action is, so let's continue down to there via the
265 letter 'c', which by the way, inserts a 'one-time-only' breakpoint at
266 the given line or sub routine:
267 DB<8> c 13
269 All OK
270 main::(./data_a:13): print "$data{$key}\n";
271 We've gone past our check (where 'All OK' was printed) and have stopped
273 just before the meat of our task. We could try to print out a couple
274 of variables to see what is happening:
275 DB<9> p $data{$key}
277 Not much in there, lets have a look at our hash:
279 DB<10> p %data
281 Hello Worldziptomandwelcomejerrywelcomethisthat
282 DB<11> p keys %data
284 Hello Worldtomwelcomejerrythis
285 Well, this isn't very easy to read, and using the helpful manual (h h),
287 the 'x' command looks promising:
288 DB<12> x %data
290 0 'Hello World'
291 1 'zip'
292 2 'tom'
293 3 'and'
294 4 'welcome'
295 5 undef
296 6 'jerry'
297 7 'welcome'
298 8 'this'
299 9 'that'
300 That's not much help, a couple of welcomes in there, but no indication
302 of which are keys, and which are values, it's just a listed array dump
303 and, in this case, not particularly helpful. The trick here, is to use
304 a reference to the data structure:
305 DB<13> x \%data
307 0 HASH(0x8194bc4)
308 'Hello World' => 'zip'
309 'jerry' => 'welcome'
310 'this' => 'that'
311 'tom' => 'and'
312 'welcome' => undef
313 The reference is truly dumped and we can finally see what we're dealing
315 with. Our quoting was perfectly valid but wrong for our purposes, with
316 'and jerry' being treated as 2 separate words rather than a phrase,
317 thus throwing the evenly paired hash structure out of alignment.
318 The '-w' switch would have told us about this, had we used it at the
320 start, and saved us a lot of trouble:
321 > perl -w data
323 Odd number of elements in hash assignment at ./data line 5.
324 We fix our quoting: 'tom' => q(and jerry), and run it again, this time
326 we get our expected output:
327 > perl -w data
329 Hello World
330 While we're here, take a closer look at the 'x' command, it's really
332 useful and will merrily dump out nested references, complete objects,
333 partial objects - just about whatever you throw at it:
334 Let's make a quick object and x-plode it, first we'll start the
336 debugger: it wants some form of input from STDIN, so we give it
337 something non-committal, a zero:
338 > perl -de 0
340 Default die handler restored.
341 Loading DB routines from perl5db.pl version 1.07
343 Editor support available.
344 Enter h or `h h' for help, or `man perldebug' for more help.
346 main::(-e:1): 0
348 Now build an on-the-fly object over a couple of lines (note the
350 backslash):
351 DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
353 cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
354 And let's have a look at it:
356 DB<2> x $obj
358 0 MY_class=HASH(0x828ad98)
359 'attr' => HASH(0x828ad68)
360 'col' => 'black'
361 'things' => ARRAY(0x828abb8)
362 0 'this'
363 1 'that'
364 2 'etc'
365 'unique_id' => 123
366 DB<3>
367 Useful, huh? You can eval nearly anything in there, and experiment
369 with bits of code or regexes until the cows come home:
370 DB<3> @data = qw(this that the other atheism leather theory scythe)
372 DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
374 atheism
375 leather
376 other
377 scythe
378 the
379 theory
380 saw -> 6
381 If you want to see the command History, type an 'H':
383 DB<5> H
385 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
386 3: @data = qw(this that the other atheism leather theory scythe)
387 2: x $obj
388 1: $obj = bless({'unique_id'=>'123', 'attr'=>
389 {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
390 DB<5>
391 And if you want to repeat any previous command, use the exclamation:
393 '!':
394 DB<5> !4
396 p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
397 atheism
398 leather
399 other
400 scythe
401 the
402 theory
403 saw -> 12
404 For more on references see perlref and perlreftut
406
408 Here's a simple program which converts between Celsius and Fahrenheit,
409 it too has a problem:
410 #!/usr/bin/perl -w
412 use strict;
413 my $arg = $ARGV[0] || '-c20';
415 if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
417 my ($deg, $num) = ($1, $2);
418 my ($in, $out) = ($num, $num);
419 if ($deg eq 'c') {
420 $deg = 'f';
421 $out = &c2f($num);
422 } else {
423 $deg = 'c';
424 $out = &f2c($num);
425 }
426 $out = sprintf('%0.2f', $out);
427 $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
428 print "$out $deg\n";
429 } else {
430 print "Usage: $0 -[c|f] num\n";
431 }
432 exit;
433 sub f2c {
435 my $f = shift;
436 my $c = 5 * $f - 32 / 9;
437 return $c;
438 }
439 sub c2f {
441 my $c = shift;
442 my $f = 9 * $c / 5 + 32;
443 return $f;
444 }
445 For some reason, the Fahrenheit to Celsius conversion fails to return
447 the expected output. This is what it does:
448 > temp -c0.72
450 33.30 f
451 > temp -f33.3
453 162.94 c
454 Not very consistent! We'll set a breakpoint in the code manually and
456 run it under the debugger to see what's going on. A breakpoint is a
457 flag, to which the debugger will run without interruption, when it
458 reaches the breakpoint, it will stop execution and offer a prompt for
459 further interaction. In normal use, these debugger commands are
460 completely ignored, and they are safe - if a little messy, to leave in
461 production code.
462 my ($in, $out) = ($num, $num);
464 $DB::single=2; # insert at line 9!
465 if ($deg eq 'c')
466 ...
467 > perl -d temp -f33.3
469 Default die handler restored.
470 Loading DB routines from perl5db.pl version 1.07
472 Editor support available.
473 Enter h or `h h' for help, or `man perldebug' for more help.
475 main::(temp:4): my $arg = $ARGV[0] || '-c100';
477 We'll simply continue down to our pre-set breakpoint with a 'c':
479 DB<1> c
481 main::(temp:10): if ($deg eq 'c') {
482 Followed by a view command to see where we are:
484 DB<1> v
486 7: my ($deg, $num) = ($1, $2);
487 8: my ($in, $out) = ($num, $num);
488 9: $DB::single=2;
489 10==> if ($deg eq 'c') {
490 11: $deg = 'f';
491 12: $out = &c2f($num);
492 13 } else {
493 14: $deg = 'c';
494 15: $out = &f2c($num);
495 16 }
496 And a print to show what values we're currently using:
498 DB<1> p $deg, $num
500 f33.3
501 We can put another break point on any line beginning with a colon,
503 we'll use line 17 as that's just as we come out of the subroutine, and
504 we'd like to pause there later on:
505 DB<2> b 17
507 There's no feedback from this, but you can see what breakpoints are set
509 by using the list 'L' command:
510 DB<3> L
512 temp:
513 17: print "$out $deg\n";
514 break if (1)
515 Note that to delete a breakpoint you use 'B'.
517 Now we'll continue down into our subroutine, this time rather than by
519 line number, we'll use the subroutine name, followed by the now
520 familiar 'v':
521 DB<3> c f2c
523 main::f2c(temp:30): my $f = shift;
524 DB<4> v
526 24: exit;
527 25
528 26 sub f2c {
529 27==> my $f = shift;
530 28: my $c = 5 * $f - 32 / 9;
531 29: return $c;
532 30 }
533 31
534 32 sub c2f {
535 33: my $c = shift;
536 Note that if there was a subroutine call between us and line 29, and we
538 wanted to single-step through it, we could use the 's' command, and to
539 step over it we would use 'n' which would execute the sub, but not
540 descend into it for inspection. In this case though, we simply
541 continue down to line 29:
542 DB<4> c 29
544 main::f2c(temp:29): return $c;
545 And have a look at the return value:
547 DB<5> p $c
549 162.944444444444
550 This is not the right answer at all, but the sum looks correct. I
552 wonder if it's anything to do with operator precedence? We'll try a
553 couple of other possibilities with our sum:
554 DB<6> p (5 * $f - 32 / 9)
556 162.944444444444
557 DB<7> p 5 * $f - (32 / 9)
559 162.944444444444
560 DB<8> p (5 * $f) - 32 / 9
562 162.944444444444
563 DB<9> p 5 * ($f - 32) / 9
565 0.722222222222221
566 :-) that's more like it! Ok, now we can set our return variable and
568 we'll return out of the sub with an 'r':
569 DB<10> $c = 5 * ($f - 32) / 9
571 DB<11> r
573 scalar context return from main::f2c: 0.722222222222221
574 Looks good, let's just continue off the end of the script:
576 DB<12> c
578 0.72 c
579 Debugged program terminated. Use q to quit or R to restart,
580 use O inhibit_exit to avoid stopping after program termination,
581 h q, h R or h O to get additional info.
582 A quick fix to the offending line (insert the missing parentheses) in
584 the actual program and we're finished.
585
587 Actions, watch variables, stack traces etc.: on the TODO list.
588 a
590 w
592 t
594 T
596
598 Ever wanted to know what a regex looked like? You'll need perl
599 compiled with the DEBUGGING flag for this one:
600 > perl -Dr -e '/^pe(a)*rl$/i'
602 Compiling REx `^pe(a)*rl$'
603 size 17 first at 2
604 rarest char
605 at 0
606 1: BOL(2)
607 2: EXACTF <pe>(4)
608 4: CURLYN[1] {0,32767}(14)
609 6: NOTHING(8)
610 8: EXACTF <a>(0)
611 12: WHILEM(0)
612 13: NOTHING(14)
613 14: EXACTF <rl>(16)
614 16: EOL(17)
615 17: END(0)
616 floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
617 anchored(BOL) minlen 4
618 Omitting $` $& $' support.
619 EXECUTING...
621 Freeing REx: `^pe(a)*rl$'
623 Did you really want to know? :-) For more gory details on getting
625 regular expressions to work, have a look at perlre, perlretut, and to
626 decode the mysterious labels (BOL and CURLYN, etc. above), see
627 perldebguts.
628
630 To get all the output from your error log, and not miss any messages
631 via helpful operating system buffering, insert a line like this, at the
632 start of your script:
633 $|=1;
635 To watch the tail of a dynamically growing logfile, (from the command
637 line):
638 tail -f $error_log
640 Wrapping all die calls in a handler routine can be useful to see how,
642 and from where, they're being called, perlvar has more information:
643 BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
645 Various useful techniques for the redirection of STDOUT and STDERR
647 filehandles are explained in perlopentut and perlfaq8.
648
650 Just a quick hint here for all those CGI programmers who can't figure
651 out how on earth to get past that 'waiting for input' prompt, when
652 running their CGI script from the command-line, try something like
653 this:
654 > perl -d my_cgi.pl -nodebug
656 Of course CGI and perlfaq9 will tell you more.
658
660 The command line interface is tightly integrated with an emacs
661 extension and there's a vi interface too.
662 You don't have to do this all on the command line, though, there are a
664 few GUI options out there. The nice thing about these is you can wave
665 a mouse over a variable and a dump of its data will appear in an
666 appropriate window, or in a popup balloon, no more tiresome typing of
667 'x $varname' :-)
668 In particular have a hunt around for the following:
670 ptkdb perlTK based wrapper for the built-in debugger
672 ddd data display debugger
674 PerlDevKit and PerlBuilder are NT specific
676 NB. (more info on these and others would be appreciated).
678
680 We've seen how to encourage good coding practices with use strict and
681 -w. We can run the perl debugger perl -d scriptname to inspect your
682 data from within the perl debugger with the p and x commands. You can
683 walk through your code, set breakpoints with b and step through that
684 code with s or n, continue with c and return from a sub with r. Fairly
685 intuitive stuff when you get down to it.
686 There is of course lots more to find out about, this has just scratched
688 the surface. The best way to learn more is to use perldoc to find out
689 more about the language, to read the on-line help (perldebug is
690 probably the next place to go), and of course, experiment.
691
693 perldebug, perldebguts, perldiag, perlrun
694
696 Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
697
699 Various people have made helpful suggestions and contributions, in
700 particular:
701 Ronald J Kimball <rjk@linguist.dartmouth.edu>
703 Hugo van der Sanden <hv@crypt0.demon.co.uk>
705 Peter Scott <Peter@PSDT.com>
707perl v5.16.3 2013-03-04 PERLDEBTUT(1)