Penguin
Recent Changes
Blame: perldebug(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of perldebug(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLDEBUG
2 !!!PERLDEBUG
3 NAME
4 DESCRIPTION
5 The Perl Debugger
6 Debugging regular expressions
7 Debugging memory usage
8 SEE ALSO
9 BUGS
10 ----
11 !!NAME
12
13
14 perldebug - Perl debugging
15 !!DESCRIPTION
16
17
18 First of all, have you tried using the __-w__
19 switch?
20 !!The Perl Debugger
21
22
23 If you invoke Perl with the __-d__ switch, your script
24 runs under the Perl source debugger. This works like an
25 interactive Perl environment, prompting for debugger
26 commands that let you examine source code, set breakpoints,
27 get stack backtraces, change the values of variables, etc.
28 This is so convenient that you often fire up the debugger
29 all by itself just to test out Perl constructs interactively
30 to see what they do. For example:
31
32
33 $ perl -d -e 42
34 In Perl, the debugger is not a separate program the way it usually is in the typical compiled environment. Instead, the __-d__ flag tells the compiler to insert source information into the parse trees it's about to hand off to the interpreter. That means your code must first compile correctly for the debugger to work on it. Then when the interpreter starts up, it preloads a special Perl library file containing the debugger.
35
36
37 The program will halt ''right before'' the first run-time
38 executable statement (but see below regarding compile-time
39 statements) and ask you to enter a debugger command.
40 Contrary to popular expectations, whenever the debugger
41 halts and shows you a line of code, it always displays the
42 line it's ''about'' to execute, rather than the one it
43 has just executed.
44
45
46 Any command not recognized by the debugger is directly
47 executed (eval'd) as Perl code in the current
48 package. (The debugger uses the DB package
49 for keeping its own state information.)
50
51
52 For any text entered at the debugger prompt, leading and
53 trailing whitespace is first stripped before further
54 processing. If a debugger command coincides with some
55 function in your own program, merely precede the function
56 with something that doesn't look like a debugger command,
57 such as a leading ; or perhaps a +, or by
58 wrapping it with parentheses or braces.
59
60
61 __Debugger Commands__
62
63
64 The debugger understands the following
65 commands:
66
67
68 h [[command]
69
70
71 Prints out a help message.
72
73
74 If you supply another debugger command as an argument to the
75 h command, it prints out the description for just
76 that command. The special argument of h h produces
77 a more compact help listing, designed to fit together on one
78 screen.
79
80
81 If the output of the h command (or any command, for
82 that matter) scrolls past your screen, precede the command
83 with a leading pipe symbol so that it's run through your
84 pager, as in
85
86
87 DB
88 You may change the pager which is used via O pager=... command.
89
90
91 p expr
92
93
94 Same as print {$DB::OUT} expr in the current
95 package. In particular, because this is just Perl's own
96 print function, this means that nested data
97 structures and objects are not dumped, unlike with the
98 x command.
99
100
101 The DB::OUT filehandle is opened to
102 ''/dev/tty'', regardless of where STDOUT
103 may be redirected to.
104
105
106 x expr
107
108
109 Evaluates its expression in list context and dumps out the
110 result in a pretty-printed fashion. Nested data structures
111 are printed out recursively, unlike the real print
112 function in Perl. See Dumpvalue if you'd like to do this
113 yourself.
114
115
116 The output format is governed by multiple options described
117 under ``Configurable Options''.
118
119
120 V [[pkg [[vars]]
121
122
123 Display all (or some) variables in package (defaulting to
124 main) using a data pretty-printer (hashes show
125 their keys and values so you see what's what, control
126 characters are made printable, etc.). Make sure you don't
127 put the type specifier (like $) there, just the
128 symbol names, like this:
129
130
131 V DB filename line
132 Use ~pattern and !pattern for positive and negative regexes.
133
134
135 This is similar to calling the x command on each
136 applicable var.
137
138
139 X [[vars]
140
141
142 Same as V currentpackage [[vars].
143
144
145 T Produce a stack backtrace. See below for details on its
146 output.
147
148
149 s [[expr]
150
151
152 Single step. Executes until the beginning of another
153 statement, descending into subroutine calls. If an
154 expression is supplied that includes function calls, it too
155 will be single-stepped.
156
157
158 n [[expr]
159
160
161 Next. Executes over subroutine calls, until the beginning of
162 the next statement. If an expression is supplied that
163 includes function calls, those functions will be executed
164 with stops before each statement.
165
166
167 r Continue until the return from the current subroutine.
2 perry 168 Dump the return value if the !PrintRet option is set
1 perry 169 (default).
170
171
172 CR n or
173 s command.
174
175
176 c [[linesub]
177
178
179 Continue, optionally inserting a one-time-only breakpoint at
180 the specified line or subroutine.
181
182
183 l List next window of lines.
184
185
186 l min+incr
187
188
189 List incr+1 lines starting at
190 min.
191
192
193 l min-max
194
195
196 List lines min through max. l -
197 is synonymous to -.
198
199
200 l line
201
202
203 List a single line.
204
205
206 l subname
207
208
209 List first window of lines from subroutine. ''subname''
210 may be a variable that contains a code
211 reference.
212
213
214 - List previous window of lines.
215
216
217 w [[line]
218
219
220 List window (a few lines) around the current
221 line.
222
223
224 . Return the internal debugger pointer to the line last
225 executed, and print out that line.
226
227
228 f filename
229
230
231 Switch to viewing a different file or eval
232 statement. If ''filename'' is not a full pathname found
233 in the values of %INC, it is considered a
234 regex.
235
236
237 evaled strings (when accessible) are considered to
238 be filenames: f (eval 7) and f eval 7b
239 access the body of the 7th evaled string (in the
240 order of execution). The bodies of the currently executed
241 eval and of evaled strings that define
242 subroutines are saved and thus accessible.
243
244
245 /pattern/
246
247
248 Search forwards for pattern (a Perl regex); final / is
249 optional.
250
251
252 ?pattern?
253
254
255 Search backwards for pattern; final ? is
256 optional.
257
258
259 L List all breakpoints and actions.
260
261
262 S [[[[!]regex]
263
264
265 List subroutine names [[not] matching the regex.
266
267
2 perry 268 t Toggle trace mode (see also the !AutoTrace
1 perry 269 option).
270
271
272 t expr
273
274
275 Trace through execution of expr. See ``Frame
276 Listing Output Examples'' in perldebguts for
277 examples.
278
279
280 b [[line] [[condition]
281
282
283 Set a breakpoint before the given line. If ''line'' is
284 omitted, set a breakpoint on the line about to be executed.
285 If a condition is specified, it's evaluated each time the
286 statement is reached: a breakpoint is taken only if the
287 condition is true. Breakpoints may only be set on lines that
288 begin an executable statement. Conditions don't use
289 if:
290
291
292 b 237 $x
293
294
295 b subname [[condition]
296
297
298 Set a breakpoint before the first line of the named
299 subroutine. ''subname'' may be a variable containing a
300 code reference (in this case ''condition'' is not
301 supported).
302
303
304 b postpone subname [[condition]
305
306
307 Set a breakpoint at first line of subroutine after it is
308 compiled.
309
310
311 b load filename
312
313
314 Set a breakpoint before the first executed line of the
315 ''filename'', which should be a full pathname found
316 amongst the %INC values.
317
318
319 b compile subname
320
321
322 Sets a breakpoint before the first statement executed after
323 the specified subroutine is compiled.
324
325
326 d [[line]
327
328
329 Delete a breakpoint from the specified ''line''. If
330 ''line'' is omitted, deletes the breakpoint from the line
331 about to be executed.
332
333
334 D Delete all installed breakpoints.
335
336
337 a [[line] command
338
339
340 Set an action to be done before the line is executed. If
341 ''line'' is omitted, set an action on the line about to
342 be executed. The sequence of steps taken by the debugger
343 is
344
345
346 1. check for a breakpoint at this line
347 2. print the line if necessary (tracing)
348 3. do any actions associated with that line
349 4. prompt user if at a breakpoint or in single-step
350 5. evaluate line
351 For example, this will print out $foo every time line 53 is passed:
352
353
354 a 53 print
355
356
357 a [[line]
358
359
360 Delete an action from the specified line. If ''line'' is
361 omitted, delete the action on the line that is about to be
362 executed.
363
364
365 A Delete all installed actions.
366
367
368 W expr
369
370
371 Add a global watch-expression. We hope you know what one of
372 these is, because they're supposed to be obvious.
373 __WARNING__ : It is far too easy to
374 destroy your watch expressions by accidentally omitting the
375 ''expr''.
376
377
378 W Delete all watch-expressions.
379
380
381 O booloption ...
382
383
384 Set each listed Boolean option to the value
385 1.
386
387
388 O anyoption? ...
389
390
391 Print out the value of one or more options.
392
393
394 O option=value ...
395
396
397 Set the value of one or more options. If the value has
398 internal whitespace, it should be quoted. For example, you
399 could set O pager= to
400 call __less__ with those specific options. You may use
401 either single or double quotes, but if you do, you must
402 escape any embedded instances of same sort of quote you
403 began with, as well as any escaping any escapes that
404 immediately precede that quote but which are not meant to
405 escape the quote itself. In other words, you follow
406 single-quoting rules irrespective of the quote; eg: O
407 option='this isn't bad' or O option=
408 .
409
410
411 For historical reasons, the =value is optional, but
412 defaults to 1 only where it is safe to do so--that is,
413 mostly for Boolean options. It is always better to assign a
414 specific value using =. The option can be
415 abbreviated, but for clarity probably should not be. Several
416 options can be set together. See ``Configurable Options''
417 for a list of these.
418
419
420
421
422
423
424 Set an action (Perl command) to happen before every debugger
425 prompt. A multi-line command may be entered by backslashing
426 the newlines. __WARNING__ If
427 command is missing, all actions are wiped
428 out!
429
430
431
432
433 Add an action (Perl command) to happen before every debugger
434 prompt. A multi-line command may be entered by backwhacking
435 the newlines.
436
437
438
439
440
441
442 Set an action (Perl command) to happen after the prompt when
443 you've just given a command to return to executing the
444 script. A multi-line command may be entered by backslashing
445 the newlines (we bet you couldn't've guessed this by now).
446 __WARNING__ If command is
447 missing, all actions are wiped out!
448
449
450
451
452 Adds an action (Perl command) to happen after the prompt
453 when you've just given a command to return to executing the
454 script. A multi-line command may be entered by backslashing
455 the newlines.
456
457
458 { ? List out pre-prompt debugger commands.
459
460
461 { [[ command ]
462
463
464 Set an action (debugger command) to happen before every
465 debugger prompt. A multi-line command may be entered in the
466 customary fashion. __WARNING__ If
467 command is missing, all actions are wiped
468 out!
469
470
471 Because this command is in some senses new, a warning is
472 issued if you appear to have accidentally entered a block
473 instead. If that's what you mean to do, write it as with
474 ;{ ... } or even do { ... }.
475
476
477 {{ command
478
479
480 Add an action (debugger command) to happen before every
481 debugger prompt. A multi-line command may be entered, if you
482 can guess how: see above.
483
484
485 ! number
486
487
488 Redo a previous command (defaults to the previous
489 command).
490
491
492 ! -number
493
494
495 Redo number'th previous command.
496
497
498 ! pattern
499
500
501 Redo last command that started with pattern. See O
502 recallCommand, too.
503
504
505 !! cmd
506
507
508 Run cmd in a subprocess (reads from DB::IN ,
509 writes to DB::OUT ) See O shellBang,
510 also. Note that the user's current shell (well, their
511 $ENV{SHELL} variable) will be used, which can
512 interfere with proper interpretation of exit status or
513 signal and coredump information.
514
515
516 H -number
517
518
519 Display last n commands. Only commands longer than one
520 character are listed. If ''number'' is omitted, list them
521 all.
522
523
524 q or ^D
525
526
527 Quit. (``quit'' doesn't work for this, unless you've made an
528 alias) This is the only supported way to exit the debugger,
529 though typing exit twice might work.
530
531
532 Set the inhibit_exit option to 0 if you want to be
533 able to step off the end the script. You may also need to
534 set $finished to 0 if you want to step through
535 global destruction.
536
537
538 R Restart the debugger by exec()ing a new session.
539 We try to maintain your history across this, but internal
540 settings and command-line options may be lost.
541
542
543 The following setting are currently preserved: history,
544 breakpoints, actions, debugger options, and the Perl
545 command-line options __-w__, __-I__, and
546 __-e__.
547
548
549 dbcmd
550
551
552 Run the debugger command, piping DB::OUT into
553 your current pager.
554
555
556 dbcmd
557
558
559 Same as dbcmd but DB::OUT is
560 temporarily selected as well.
561
562
563 = [[alias value]
564
565
566 Define a command alias, like
567
568
569 = quit q
570 or list current aliases.
571
572
573 command
574
575
576 Execute command as a Perl statement. A trailing semicolon
577 will be supplied. If the Perl statement would otherwise be
578 confused for a Perl debugger, use a leading semicolon,
579 too.
580
581
582 m expr
583
584
585 List which methods may be called on the result of the
586 evaluated expression. The expression may evaluated to a
587 reference to a blessed object, or to a package
588 name.
589
590
591 man [[manpage]
592
593
594 Despite its name, this calls your system's default
595 documentation viewer on the given page, or on the viewer
596 itself if ''manpage'' is omitted. If that viewer is
597 __man__, the current Config information is used
598 to invoke __man__ using the proper MANPATH
599 or __-M__ ''manpath'' option. Failed lookups of the
600 form XXX that match known manpages of the form
601 ''perlXXX'' will be retried. This lets you type man
602 debug or man op from the
603 debugger.
604
605
606 On systems traditionally bereft of a usable __man__
607 command, the debugger invokes __perldoc__. Occasionally
608 this determination is incorrect due to recalcitrant vendors
609 or rather more felicitously, to enterprising users. If you
610 fall into either category, just manually set the
611 $DB::doccmd variable to whatever viewer to view the
612 Perl documentation on your system. This may be set in an rc
613 file, or through direct assignment. We're still waiting for
614 a working example of something along the lines
615 of:
616
617
618 $DB::doccmd = 'netscape -remote http://something.here/';
619
620
621 __Configurable Options__
622
623
624 The debugger has numerous options settable using the
625 O command, either interactively or from the
626 environment or an rc file. (./.perldb or ~/.perldb under
627 Unix.)
628
629
2 perry 630 recallCommand, !ShellBang
1 perry 631
632
633 The characters used to recall command or spawn shell. By
634 default, both are set to !, which is
635 unfortunate.
636
637
638 pager
639
640
641 Program to use for output of pager-piped commands (those
642 beginning with a character.) By default,
643 $ENV{PAGER} will be used. Because the debugger uses
644 your current terminal characteristics for bold and
645 underlining, if the chosen pager does not pass escape
646 sequences through unchanged, the output of some debugger
647 commands will not be readable when sent through the
648 pager.
649
650
651 tkRunning
652
653
2 perry 654 Run Tk while prompting (with !ReadLine).
1 perry 655
656
657 signalLevel, warnLevel,
658 dieLevel
659
660
661 Level of verbosity. By default, the debugger leaves your
662 exceptions and warnings alone, because altering them can
663 break correctly running programs. It will attempt to print a
664 message when uncaught INT ,
665 BUS , or SEGV signals arrive.
666 (But see the mention of signals in BUGS
667 below.)
668
669
670 To disable this default safe mode, set these values to
671 something higher than 0. At a level of 1, you get backtraces
672 upon receiving any kind of warning (this is often annoying)
673 or exception (this is often valuable). Unfortunately, the
674 debugger cannot discern fatal exceptions from non-fatal
675 ones. If dieLevel is even 1, then your non-fatal
676 exceptions are also traced and unceremoniously altered if
677 they came from eval'd strings or from any kind of
678 eval within modules you're attempting to load. If
679 dieLevel is 2, the debugger doesn't care where they
680 came from: It usurps your exception handler and prints out a
681 trace, then modifies all exceptions with its own
682 embellishments. This may perhaps be useful for some tracing
683 purposes, but tends to hopelessly destroy any program that
684 takes its exception handling seriously.
685
686
2 perry 687 !AutoTrace
1 perry 688
689
690 Trace mode (similar to t command, but can be put
691 into PERLDB_OPTS).
692
693
2 perry 694 !LineInfo
1 perry 695
696
697 File or pipe to print line number info to. If it is a pipe
698 (say, visual_perl_db), then a short message is
699 used. This is the mechanism used to interact with a slave
700 editor or visual debugger, such as the special vi
701 or emacs hooks, or the ddd graphical
702 debugger.
703
704
705 inhibit_exit
706
707
708 If 0, allows ''stepping off'' the end of the
709 script.
710
711
2 perry 712 !PrintRet
1 perry 713
714
715 Print return value after r command if set
716 (default).
717
718
719 ornaments
720
721
722 Affects screen appearance of the command line (see
2 perry 723 Term::!ReadLine). There is currently no way to disable these,
1 perry 724 which can render some output illegible on some displays, or
725 with some pagers. This is considered a bug.
726
727
728 frame
729
730
731 Affects the printing of messages upon entry and exit from
732 subroutines. If frame is false, messages
733 are printed on entry only. (Printing on exit might be useful
734 if interspersed with other messages.)
735
736
737 If frame , arguments to functions are
738 printed, plus context and caller info. If frame
739 , overloaded stringify and tied
740 FETCH is enabled on the printed arguments. If
741 frame , the return value from the
742 subroutine is printed.
743
744
745 The length at which the argument list is truncated is
746 governed by the next option:
747
748
749 maxTraceLen
750
751
752 Length to truncate the argument list when the frame
753 option's bit 4 is set.
754
755
756 The following options affect what happens with V,
757 X, and x commands:
758
759
760 arrayDepth, hashDepth
761
762
763 Print only first N elements ('' for all).
764
765
766 compactDump, veryCompact
767
768
769 Change the style of array and hash output. If
770 compactDump, short array may be printed on one
771 line.
772
773
774 globPrint
775
776
777 Whether to print contents of globs.
778
779
780 DumpDBFiles
781
782
783 Dump arrays holding debugged files.
784
785
2 perry 786 !DumpPackages
1 perry 787
788
789 Dump symbol tables of packages.
790
791
2 perry 792 !DumpReused
1 perry 793
794
795 Dump contents of ``reused'' addresses.
796
797
2 perry 798 quote, !HighBit,
1 perry 799 undefPrint
800
801
802 Change the style of string dump. The default value for
803 quote is auto; one can enable
804 double-quotish or single-quotish format by setting it to
805 or ', respectively. By default,
806 characters with their high bit set are printed
807 verbatim.
808
809
2 perry 810 !UsageOnly
1 perry 811
812
813 Rudimentary per-package memory usage dump. Calculates total
814 size of strings found in variables in the package. This does
815 not include lexicals in a module's file scope, or lost in
816 closures.
817
818
819 After the rc file is read, the debugger reads the
820 $ENV{PERLDB_OPTS} environment variable and parses
821 this as the remainder of a `O ...' line as one might enter
822 at the debugger prompt. You may place the initialization
2 perry 823 options TTY, noTTY, !ReadLine, and
824 !NonStop there.
1 perry 825
826
827 If your rc file contains:
828
829
830 parse_options(
2 perry 831 then your script will run without human intervention, putting trace information into the file ''db.out''. (If you interrupt it, you'd better reset !LineInfo to ''/dev/tty'' if you expect to see anything.)
1 perry 832
833
834 TTY The TTY to use for debugging
835 I/O.
836
837
838 noTTY
839
840
2 perry 841 If set, the debugger goes into !NonStop mode and
1 perry 842 will not connect to a TTY . If interrupted
843 (or if control goes to the debugger via explicit setting of
844 $DB::signal or $DB::single from the Perl
845 script), it connects to a TTY specified in
846 the TTY option at startup, or to a tty found at
847 runtime using the Term::Rendezvous module of your
848 choice.
849
850
851 This module should implement a method named new
852 that returns an object with two methods: IN and
853 OUT. These should return filehandles to use for
854 debugging input and output correspondingly. The new
855 method should inspect an argument containing the value of
856 $ENV{PERLDB_NOTTY} at startup, or
857 otherwise. This file
858 is not inspected for proper ownership, so security hazards
859 are theoretically possible.
860
861
2 perry 862 !ReadLine
1 perry 863
864
865 If false, readline support in the debugger is disabled in
866 order to debug applications that themselves use
2 perry 867 !ReadLine.
1 perry 868
869
2 perry 870 !NonStop
1 perry 871
872
873 If set, the debugger goes into non-interactive mode until
874 interrupted, or programmatically by setting
875 $DB::signal or $DB::single.
876
877
878 Here's an example of using the $ENV{PERLDB_OPTS}
879 variable:
880
881
882 $ PERLDB_OPTS=
2 perry 883 That will run the script __myprogram__ without human intervention, printing out the call tree with entry and exit points. Note that !NonStop=1 frame=2 is equivalent to N f=2, and that originally, options could be uniquely abbreviated by the first letter (modulo the Dump* options). It is nevertheless recommended that you always spell them out in full for legibility and future compatibility.
1 perry 884
885
886 Other examples include
887
888
889 $ PERLDB_OPTS=
2 perry 890 which runs script non-interactively, printing info on each entry into a subroutine and each executed line into the file named ''listing''. (If you interrupt it, you would better reset !LineInfo to something ``interactive''!)
1 perry 891
892
893 Other examples include (using standard shell syntax to show
894 environment variable settings):
895
896
897 $ ( PERLDB_OPTS=
2 perry 898 which may be useful for debugging a program that uses Term::!ReadLine itself. Do not forget to detach your shell from the TTY in the window that corresponds to ''/dev/ttyXX'', say, by issuing a command like
1 perry 899
900
901 $ sleep 1000000
902 See ``Debugger Internals'' in perldebguts for details.
903
904
905 __Debugger input/output__
906
907
908 Prompt
909
910
911 The debugger prompt is something like
912
913
914 DB
915 or even
916
917
918 DB
919 where that number is the command number, and which you'd use to access with the built-in __csh__-like history mechanism. For example, !17 would repeat command number 17. The depth of the angle brackets indicates the nesting depth of the debugger. You could get more than one set of brackets, for example, if you'd already at a breakpoint and then printed the result of a function call that itself has a breakpoint, or you step into an expression via s/n/t expression command.
920
921
922 Multiline commands
923
924
925 If you want to enter a multi-line command, such as a
926 subroutine definition with several statements or a format,
927 escape the newline that would normally end the debugger
928 command with a backslash. Here's an example:
929
930
931 DB
932 Note that this business of escaping a newline is specific to interactive commands typed into the debugger.
933
934
935 Stack backtrace
936
937
938 Here's an example of what a stack backtrace via T
939 command might look like:
940
941
942 $ = main::infested called from file `Ambulation.pm' line 10
943 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
944 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
945 The left-hand character up there indicates the context in which the function was called, with $ and @ meaning scalar or list contexts respectively, and . meaning void context (which is actually a sort of scalar context). The display above says that you were in the function main::infested when you ran the stack dump, and that it was called in scalar context from line 10 of the file ''Ambulation.pm'', but without any arguments at all, meaning it was called as . The next stack frame shows that the function Ambulation::legs was called in list context from the ''camel_flea'' file with four arguments. The last stack frame shows that main::pests was called in scalar context, also from ''camel_flea'', but from line 4.
946
947
948 If you execute the T command from inside an active
949 use statement, the backtrace will contain both a
950 require frame and an eval)
951 frame.
952
953
954 Line Listing Format
955
956
957 This shows the sorts of output the l command can
958 produce:
959
960
961 DB
962 Breakable lines are marked with :. Lines with breakpoints are marked by b and those with actions by a. The line that's about to be executed is marked by ==.
963
964
965 Please be aware that code in debugger listings may not look
966 the same as your original source code. Line directives and
967 external source filters can alter the code before Perl sees
968 it, causing code to move from its original positions or take
969 on entirely different forms.
970
971
972 Frame listing
973
974
975 When the frame option is set, the debugger would
976 print entered (and optionally exited) subroutines in
977 different styles. See perldebguts for incredibly long
978 examples of these.
979
980
981 __Debugging compile-time statements__
982
983
984 If you have compile-time executable statements (such as code
985 within BEGIN and CHECK blocks
986 or use statements), these will ''not'' be
987 stopped by debugger, although requires and
988 INIT blocks will, and compile-time statements
2 perry 989 can be traced with !AutoTrace option set in
1 perry 990 PERLDB_OPTS). From your own Perl code, however, you
991 can transfer control back to the debugger using the
992 following statement, which is harmless if the debugger is
993 not running:
994
995
996 $DB::single = 1;
997 If you set $DB::single to 2, it's equivalent to having just typed the n command, whereas a value of 1 means the s command. The $DB::trace variable should be set to 1 to simulate having typed the t command.
998
999
1000 Another way to debug compile-time code is to start the
1001 debugger, set a breakpoint on the ''load'' of some
1002 module:
1003
1004
1005 DB
1006 and then restart the debugger using the R command (if possible). One can use b compile subname for the same purpose.
1007
1008
1009 __Debugger Customization__
1010
1011
1012 The debugger probably contains enough configuration hooks
1013 that you won't ever have to modify it yourself. You may
1014 change the behaviour of debugger from within the debugger
1015 using its O command, from the command line via the
1016 PERLDB_OPTS environment variable, and from
1017 customization files.
1018
1019
1020 You can do some customization by setting up a ''.perldb''
1021 file, which contains initialization code. For instance, you
1022 could make aliases like these (the last one is one people
1023 expect to be there):
1024
1025
1026 $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
1027 $DB::alias{'stop'} = 's/^stop (atin)/b/';
1028 $DB::alias{'ps'} = 's/^psb/p scalar /';
1029 $DB::alias{'quit'} = 's/^quit(s*)/exit/';
1030 You can change options from ''.perldb'' by using calls like this one;
1031
1032
1033 parse_options(
1034 The code is executed in the package DB. Note that ''.perldb'' is processed before processing PERLDB_OPTS. If ''.perldb'' defines the subroutine afterinit, that function is called after debugger initialization ends. ''.perldb'' may be contained in the current directory, or in the home directory. Because this file is sourced in by Perl and may contain arbitrary commands, for security reasons, it must be owned by the superuser or the current user, and writable by no one but its owner.
1035
1036
1037 If you want to modify the debugger, copy ''perl5db.pl''
1038 from the Perl library to another name and hack it to your
1039 heart's content. You'll then want to set your
1040 PERL5DB environment variable to say something like
1041 this:
1042
1043
1044 BEGIN { require
1045 As a last resort, you could also use PERL5DB to customize the debugger by directly setting internal variables or calling debugger functions.
1046
1047
1048 Note that any variables and functions that are not
1049 documented in this document (or in perldebguts) are
1050 considered for internal use only, and as such are subject to
1051 change without notice.
1052
1053
1054 __Readline Support__
1055
1056
1057 As shipped, the only command-line history supplied is a
1058 simplistic one that checks for leading exclamation points.
2 perry 1059 However, if you install the Term::!ReadKey and Term::!ReadLine
1 perry 1060 modules from CPAN , you will have full
1061 editing capabilities much like GNU
1062 readline(3) provides. Look for these in the
1063 ''modules/by-module/Term'' directory on
1064 CPAN . These do not support normal __vi__
1065 command-line editing, however.
1066
1067
1068 A rudimentary command-line completion is also available.
1069 Unfortunately, the names of lexical variables are not
1070 available for completion.
1071
1072
1073 __Editor Support for Debugging__
1074
1075
1076 If you have the FSF 's version of
1077 __emacs__ installed on your system, it can interact with
1078 the Perl debugger to provide an integrated software
1079 development environment reminiscent of its interactions with
1080 C debuggers.
1081
1082
1083 Perl comes with a start file for making __emacs__ act
1084 like a syntax-directed editor that understands (some of)
1085 Perl's syntax. Look in the ''emacs'' directory of the
1086 Perl source distribution.
1087
1088
1089 A similar setup by Tom Christiansen for interacting with any
1090 vendor-shipped __vi__ and the X11 window system is also
1091 available. This works similarly to the integrated
1092 multiwindow support that __emacs__ provides, where the
1093 debugger drives the editor. At the time of this writing,
1094 however, that tool's eventual location in the Perl
1095 distribution was uncertain.
1096
1097
1098 Users of __vi__ should also look into __vim__ and
1099 __gvim__, the mousey and windy version, for coloring of
1100 Perl keywords.
1101
1102
1103 Note that only perl can truly parse Perl, so all such
1104 CASE tools fall somewhat short of the mark,
1105 especially if you don't program your Perl as a C programmer
1106 might.
1107
1108
1109 __The Perl Profiler__
1110
1111
1112 If you wish to supply an alternative debugger for Perl to
1113 run, just invoke your script with a colon and a package
1114 argument given to the __-d__ flag. The most popular
1115 alternative debuggers for Perl is the Perl profiler.
1116 Devel::DProf is now included with the standard Perl
1117 distribution. To profile your Perl program in the file
1118 ''mycode.pl'', just type:
1119
1120
1121 $ perl -d:DProf mycode.pl
1122 When the script terminates the profiler will dump the profile information to a file called ''tmon.out''. A tool like __dprofpp__, also supplied with the standard Perl distribution, can be used to interpret the information in that profile.
1123 !!Debugging regular expressions
1124
1125
1126 use re 'debug' enables you to see the gory details
1127 of how the Perl regular expression engine works. In order to
1128 understand this typically voluminous output, one must not
1129 only have some idea about about how regular expression
1130 matching works in general, but also know how Perl's regular
1131 expressions are internally compiled into an automaton. These
1132 matters are explored in some detail in ``Debugging regular
1133 expressions'' in perldebguts.
1134 !!Debugging memory usage
1135
1136
1137 Perl contains internal support for reporting its own memory
1138 usage, but this is a fairly advanced concept that requires
1139 some understanding of how memory allocation works. See
1140 ``Debugging Perl memory usage'' in perldebguts for the
1141 details.
1142 !!SEE ALSO
1143
1144
1145 You did try the __-w__ switch, didn't you?
1146
1147
1148 perldebguts, re, DB , Devel::Dprof, dprofpp,
1149 Dumpvalue, and perlrun.
1150 !!BUGS
1151
1152
1153 You cannot get stack frame information or in any fashion
1154 debug functions that were not compiled by Perl, such as
1155 those from C or C ++ extensions.
1156
1157
1158 If you alter your @_ arguments in a subroutine
1159 (such as with shift or pop, the stack
1160 backtrace will not show the original values.
1161
1162
1163 The debugger does not currently work in conjunction with the
1164 __-W__ command-line switch, because it itself is not free
1165 of warnings.
1166
1167
1168 If you're in a slow syscall (like waiting,
1169 accepting, or reading from your keyboard
1170 or a socket) and haven't set up your own $SIG{INT}
1171 handler, then you won't be able to CTRL-C your way back to
1172 the debugger, because the debugger's own $SIG{INT}
1173 handler doesn't understand that it needs to raise an
1174 exception to longjmp(3) out of slow
1175 syscalls.
1176 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.