pod/perldebug.pod

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