1Devel::Peek(3pm) Perl Programmers Reference Guide Devel::Peek(3pm)
2
6 Devel::Peek - A data debugging tool for the XS programmer
7
9 use Devel::Peek;
10 Dump( $a );
11 Dump( $a, 5 );
12 DumpArray( 5, $a, $b, ... );
13 mstat "Point 5";
14 use Devel::Peek ':opd=st';
16
18 Devel::Peek contains functions which allows raw Perl datatypes to be
19 manipulated from a Perl script. This is used by those who do XS
20 programming to check that the data they are sending from C to Perl
21 looks as they think it should look. The trick, then, is to know what
22 the raw datatype is supposed to look like when it gets to Perl. This
23 document offers some tips and hints to describe good and bad raw data.
24 It is very possible that this document will fall far short of being
26 useful to the casual reader. The reader is expected to understand the
27 material in the first few sections of perlguts.
28 Devel::Peek supplies a "Dump()" function which can dump a raw Perl
30 datatype, and "mstat("marker")" function to report on memory usage (if
31 perl is compiled with corresponding option). The function DeadCode()
32 provides statistics on the data "frozen" into inactive "CV".
33 Devel::Peek also supplies "SvREFCNT()", "SvREFCNT_inc()", and
34 "SvREFCNT_dec()" which can query, increment, and decrement reference
35 counts on SVs. This document will take a passive, and safe, approach
36 to data debugging and for that it will describe only the "Dump()"
37 function.
38 Function "DumpArray()" allows dumping of multiple values (useful when
40 you need to analyze returns of functions).
41 The global variable $Devel::Peek::pv_limit can be set to limit the
43 number of character printed in various string values. Setting it to 0
44 means no limit.
45 If "use Devel::Peek" directive has a ":opd=FLAGS" argument, this
47 switches on debugging of opcode dispatch. "FLAGS" should be a
48 combination of "s", "t", and "P" (see -D flags in perlrun). ":opd" is
49 a shortcut for ":opd=st".
50 Runtime debugging
52 "CvGV($cv)" return one of the globs associated to a subroutine
53 reference $cv.
54 debug_flags() returns a string representation of $^D (similar to what
56 is allowed for -D flag). When called with a numeric argument, sets $^D
57 to the corresponding value. When called with an argument of the form
58 "flags-flags", set on/off bits of $^D corresponding to letters
59 before/after "-". (The returned value is for $^D before the
60 modification.)
61 runops_debug() returns true if the current opcode dispatcher is the
63 debugging one. When called with an argument, switches to debugging or
64 non-debugging dispatcher depending on the argument (active for newly-
65 entered subs/etc only). (The returned value is for the dispatcher
66 before the modification.)
67 Memory footprint debugging
69 When perl is compiled with support for memory footprint debugging
70 (default with Perl's malloc()), Devel::Peek provides an access to this
71 API.
72 Use mstat() function to emit a memory state statistic to the terminal.
74 For more information on the format of output of mstat() see "Using
75 $ENV{PERL_DEBUG_MSTATS}" in perldebguts.
76 Three additional functions allow access to this statistic from Perl.
78 First, use "mstats_fillhash(%hash)" to get the information contained in
79 the output of mstat() into %hash. The field of this hash are
80 minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
82 topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree
83 Two additional fields "free", "used" contain array references which
85 provide per-bucket count of free and used chunks. Two other fields
86 "mem_size", "available_size" contain array references which provide the
87 information about the allocated size and usable size of chunks in each
88 bucket. Again, see "Using $ENV{PERL_DEBUG_MSTATS}" in perldebguts for
89 details.
90 Keep in mind that only the first several "odd-numbered" buckets are
92 used, so the information on size of the "odd-numbered" buckets which
93 are not used is probably meaningless.
94 The information in
96 mem_size available_size minbucket nbuckets
98 is the property of a particular build of perl, and does not depend on
100 the current process. If you do not provide the optional argument to
101 the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then the
102 information in fields "mem_size", "available_size" is not updated.
103 "fill_mstats($buf)" is a much cheaper call (both speedwise and memory-
105 wise) which collects the statistic into $buf in machine-readable form.
106 At a later moment you may need to call "mstats2hash($buf, %hash)" to
107 use this information to fill %hash.
108 All three APIs "fill_mstats($buf)", "mstats_fillhash(%hash)", and
110 "mstats2hash($buf, %hash)" are designed to allocate no memory if used
111 the second time on the same $buf and/or %hash.
112 So, if you want to collect memory info in a cycle, you may call
114 $#buf = 999;
116 fill_mstats($_) for @buf;
117 mstats_fillhash(%report, 1); # Static info too
118 foreach (@buf) {
120 # Do something...
121 fill_mstats $_; # Collect statistic
122 }
123 foreach (@buf) {
124 mstats2hash($_, %report); # Preserve static info
125 # Do something with %report
126 }
127
129 The following examples don't attempt to show everything as that would
130 be a monumental task, and, frankly, we don't want this manpage to be an
131 internals document for Perl. The examples do demonstrate some basics
132 of the raw Perl datatypes, and should suffice to get most determined
133 people on their way. There are no guidewires or safety nets, nor
134 blazed trails, so be prepared to travel alone from this point and on
135 and, if at all possible, don't fall into the quicksand (it's bad for
136 business).
137 Oh, one final bit of advice: take perlguts with you. When you return
139 we expect to see it well-thumbed.
140 A simple scalar string
142 Let's begin by looking a simple scalar which is holding a string.
143 use Devel::Peek;
145 $a = 42; $a = "hello";
146 Dump $a;
147 The output:
149 SV = PVIV(0xbc288) at 0xbe9a8
151 REFCNT = 1
152 FLAGS = (POK,pPOK)
153 IV = 42
154 PV = 0xb2048 "hello"\0
155 CUR = 5
156 LEN = 8
157 This says $a is an SV, a scalar. The scalar type is a PVIV, which is
159 capable of holding an integer (IV) and/or a string (PV) value. The
160 scalar's head is allocated at address 0xbe9a8, while the body is at
161 0xbc288. Its reference count is 1. It has the "POK" flag set, meaning
162 its current PV field is valid. Because POK is set we look at the PV
163 item to see what is in the scalar. The \0 at the end indicate that
164 this PV is properly NUL-terminated. Note that the IV field still
165 contains its old numeric value, but because FLAGS doesn't have IOK set,
166 we must ignore the IV item. CUR indicates the number of characters in
167 the PV. LEN indicates the number of bytes allocated for the PV (at
168 least one more than CUR, because LEN includes an extra byte for the
169 end-of-string marker, then usually rounded up to some efficient
170 allocation unit).
171 A simple scalar number
173 If the scalar contains a number the raw SV will be leaner.
174 use Devel::Peek;
176 $a = 42;
177 Dump $a;
178 The output:
180 SV = IV(0xbc818) at 0xbe9a8
182 REFCNT = 1
183 FLAGS = (IOK,pIOK)
184 IV = 42
185 This says $a is an SV, a scalar. The scalar is an IV, a number. Its
187 reference count is 1. It has the "IOK" flag set, meaning it is
188 currently being evaluated as a number. Because IOK is set we look at
189 the IV item to see what is in the scalar.
190 A simple scalar with an extra reference
192 If the scalar from the previous example had an extra reference:
193 use Devel::Peek;
195 $a = 42;
196 $b = \$a;
197 Dump $a;
198 The output:
200 SV = IV(0xbe860) at 0xbe9a8
202 REFCNT = 2
203 FLAGS = (IOK,pIOK)
204 IV = 42
205 Notice that this example differs from the previous example only in its
207 reference count. Compare this to the next example, where we dump $b
208 instead of $a.
209 A reference to a simple scalar
211 This shows what a reference looks like when it references a simple
212 scalar.
213 use Devel::Peek;
215 $a = 42;
216 $b = \$a;
217 Dump $b;
218 The output:
220 SV = IV(0xf041c) at 0xbe9a0
222 REFCNT = 1
223 FLAGS = (ROK)
224 RV = 0xbab08
225 SV = IV(0xbe860) at 0xbe9a8
226 REFCNT = 2
227 FLAGS = (IOK,pIOK)
228 IV = 42
229 Starting from the top, this says $b is an SV. The scalar is an IV,
231 which is capable of holding an integer or reference value. It has the
232 "ROK" flag set, meaning it is a reference (rather than an integer or
233 string). Notice that Dump follows the reference and shows us what $b
234 was referencing. We see the same $a that we found in the previous
235 example.
236 Note that the value of "RV" coincides with the numbers we see when we
238 stringify $b. The addresses inside IV() are addresses of "X***"
239 structures which hold the current state of an "SV". This address may
240 change during lifetime of an SV.
241 A reference to an array
243 This shows what a reference to an array looks like.
244 use Devel::Peek;
246 $a = [42];
247 Dump $a;
248 The output:
250 SV = IV(0xc85998) at 0xc859a8
252 REFCNT = 1
253 FLAGS = (ROK)
254 RV = 0xc70de8
255 SV = PVAV(0xc71e10) at 0xc70de8
256 REFCNT = 1
257 FLAGS = ()
258 ARRAY = 0xc7e820
259 FILL = 0
260 MAX = 0
261 ARYLEN = 0x0
262 FLAGS = (REAL)
263 Elt No. 0
264 SV = IV(0xc70f88) at 0xc70f98
265 REFCNT = 1
266 FLAGS = (IOK,pIOK)
267 IV = 42
268 This says $a is a reference (ROK), which points to another SV which is
270 a PVAV, an array. The array has one element, element zero, which is
271 another SV. The field "FILL" above indicates the last element in the
272 array, similar to "$#$a".
273 If $a pointed to an array of two elements then we would see the
275 following.
276 use Devel::Peek 'Dump';
278 $a = [42,24];
279 Dump $a;
280 The output:
282 SV = IV(0x158c998) at 0x158c9a8
284 REFCNT = 1
285 FLAGS = (ROK)
286 RV = 0x1577de8
287 SV = PVAV(0x1578e10) at 0x1577de8
288 REFCNT = 1
289 FLAGS = ()
290 ARRAY = 0x1585820
291 FILL = 1
292 MAX = 1
293 ARYLEN = 0x0
294 FLAGS = (REAL)
295 Elt No. 0
296 SV = IV(0x1577f88) at 0x1577f98
297 REFCNT = 1
298 FLAGS = (IOK,pIOK)
299 IV = 42
300 Elt No. 1
301 SV = IV(0x158be88) at 0x158be98
302 REFCNT = 1
303 FLAGS = (IOK,pIOK)
304 IV = 24
305 Note that "Dump" will not report all the elements in the array, only
307 several first (depending on how deep it already went into the report
308 tree).
309 A reference to a hash
311 The following shows the raw form of a reference to a hash.
312 use Devel::Peek;
314 $a = {hello=>42};
315 Dump $a;
316 The output:
318 SV = IV(0x8177858) at 0x816a618
320 REFCNT = 1
321 FLAGS = (ROK)
322 RV = 0x814fc10
323 SV = PVHV(0x8167768) at 0x814fc10
324 REFCNT = 1
325 FLAGS = (SHAREKEYS)
326 ARRAY = 0x816c5b8 (0:7, 1:1)
327 hash quality = 100.0%
328 KEYS = 1
329 FILL = 1
330 MAX = 7
331 RITER = -1
332 EITER = 0x0
333 Elt "hello" HASH = 0xc8fd181b
334 SV = IV(0x816c030) at 0x814fcf4
335 REFCNT = 1
336 FLAGS = (IOK,pIOK)
337 IV = 42
338 This shows $a is a reference pointing to an SV. That SV is a PVHV, a
340 hash. Fields RITER and EITER are used by ""each" in perlfunc".
341 The "quality" of a hash is defined as the total number of comparisons
343 needed to access every element once, relative to the expected number
344 needed for a random hash. The value can go over 100%.
345 The total number of comparisons is equal to the sum of the squares of
347 the number of entries in each bucket. For a random hash of "<n"> keys
348 into "<k"> buckets, the expected value is:
349 n + n(n-1)/2k
351 Dumping a large array or hash
353 The "Dump()" function, by default, dumps up to 4 elements from a
354 toplevel array or hash. This number can be increased by supplying a
355 second argument to the function.
356 use Devel::Peek;
358 $a = [10,11,12,13,14];
359 Dump $a;
360 Notice that "Dump()" prints only elements 10 through 13 in the above
362 code. The following code will print all of the elements.
363 use Devel::Peek 'Dump';
365 $a = [10,11,12,13,14];
366 Dump $a, 5;
367 A reference to an SV which holds a C pointer
369 This is what you really need to know as an XS programmer, of course.
370 When an XSUB returns a pointer to a C structure that pointer is stored
371 in an SV and a reference to that SV is placed on the XSUB stack. So
372 the output from an XSUB which uses something like the T_PTROBJ map
373 might look something like this:
374 SV = IV(0xf381c) at 0xc859a8
376 REFCNT = 1
377 FLAGS = (ROK)
378 RV = 0xb8ad8
379 SV = PVMG(0xbb3c8) at 0xc859a0
380 REFCNT = 1
381 FLAGS = (OBJECT,IOK,pIOK)
382 IV = 729160
383 NV = 0
384 PV = 0
385 STASH = 0xc1d10 "CookBookB::Opaque"
386 This shows that we have an SV which is a reference, which points at
388 another SV. In this case that second SV is a PVMG, a blessed scalar.
389 Because it is blessed it has the "OBJECT" flag set. Note that an SV
390 which holds a C pointer also has the "IOK" flag set. The "STASH" is
391 set to the package name which this SV was blessed into.
392 The output from an XSUB which uses something like the T_PTRREF map,
394 which doesn't bless the object, might look something like this:
395 SV = IV(0xf381c) at 0xc859a8
397 REFCNT = 1
398 FLAGS = (ROK)
399 RV = 0xb8ad8
400 SV = PVMG(0xbb3c8) at 0xc859a0
401 REFCNT = 1
402 FLAGS = (IOK,pIOK)
403 IV = 729160
404 NV = 0
405 PV = 0
406 A reference to a subroutine
408 Looks like this:
409 SV = IV(0x24d2dd8) at 0x24d2de8
411 REFCNT = 1
412 FLAGS = (TEMP,ROK)
413 RV = 0x24e79d8
414 SV = PVCV(0x24e5798) at 0x24e79d8
415 REFCNT = 2
416 FLAGS = ()
417 COMP_STASH = 0x22c9c50 "main"
418 START = 0x22eed60 ===> 0
419 ROOT = 0x22ee490
420 GVGV::GV = 0x22de9d8 "MY" :: "top_targets"
421 FILE = "(eval 5)"
422 DEPTH = 0
423 FLAGS = 0x0
424 OUTSIDE_SEQ = 93
425 PADLIST = 0x22e9ed8
426 PADNAME = 0x22e9ec0(0x22eed00) PAD = 0x22e9ea8(0x22eecd0)
427 OUTSIDE = 0x22c9fb0 (MAIN)
428 This shows that
430 · the subroutine is not an XSUB (since "START" and "ROOT" are non-
432 zero, and "XSUB" is not listed, and is thus null);
433 · that it was compiled in the package "main";
435 · under the name "MY::top_targets";
437 · inside a 5th eval in the program;
439 · it is not currently executed (see "DEPTH");
441 · it has no prototype ("PROTOTYPE" field is missing).
443
445 "Dump", "mstat", "DeadCode", "DumpArray", "DumpWithOP" and "DumpProg",
446 "fill_mstats", "mstats_fillhash", "mstats2hash" by default.
447 Additionally available "SvREFCNT", "SvREFCNT_inc" and "SvREFCNT_dec".
448
450 Readers have been known to skip important parts of perlguts, causing
451 much frustration for all.
452
454 Ilya Zakharevich ilya@math.ohio-state.edu
455 Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. This
457 program is free software; you can redistribute it and/or modify it
458 under the same terms as Perl itself.
459 Author of this software makes no claim whatsoever about suitability,
461 reliability, edability, editability or usability of this product, and
462 should not be kept liable for any damage resulting from the use of it.
463 If you can use it, you are in luck, if not, I should not be kept
464 responsible. Keep a handy copy of your backup tape at hand.
465
467 perlguts, and perlguts, again.
468perl v5.16.3 2013-03-04 Devel::Peek(3pm)