| 1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
| 6 | .br |
| 7 | .if t .Sp |
| 8 | .ne 5 |
| 9 | .PP |
| 10 | \fB\\$1\fR |
| 11 | .PP |
| 12 | .. |
| 13 | .de Sp \" Vertical space (when we can't use .PP) |
| 14 | .if t .sp .5v |
| 15 | .if n .sp |
| 16 | .. |
| 17 | .de Vb \" Begin verbatim text |
| 18 | .ft CW |
| 19 | .nf |
| 20 | .ne \\$1 |
| 21 | .. |
| 22 | .de Ve \" End verbatim text |
| 23 | .ft R |
| 24 | .fi |
| 25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
| 29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| 30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| 31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| 32 | .tr \(*W-|\(bv\*(Tr |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
| 36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 39 | . ds L" "" |
| 40 | . ds R" "" |
| 41 | . ds C` "" |
| 42 | . ds C' "" |
| 43 | 'br\} |
| 44 | .el\{\ |
| 45 | . ds -- \|\(em\| |
| 46 | . ds PI \(*p |
| 47 | . ds L" `` |
| 48 | . ds R" '' |
| 49 | 'br\} |
| 50 | .\" |
| 51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| 53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 54 | .\" output yourself in some meaningful fashion. |
| 55 | .if \nF \{\ |
| 56 | . de IX |
| 57 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 58 | .. |
| 59 | . nr % 0 |
| 60 | . rr F |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 64 | .\" way too many mistakes in technical documents. |
| 65 | .hy 0 |
| 66 | .if n .na |
| 67 | .\" |
| 68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 70 | . \" fudge factors for nroff and troff |
| 71 | .if n \{\ |
| 72 | . ds #H 0 |
| 73 | . ds #V .8m |
| 74 | . ds #F .3m |
| 75 | . ds #[ \f1 |
| 76 | . ds #] \fP |
| 77 | .\} |
| 78 | .if t \{\ |
| 79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 80 | . ds #V .6m |
| 81 | . ds #F 0 |
| 82 | . ds #[ \& |
| 83 | . ds #] \& |
| 84 | .\} |
| 85 | . \" simple accents for nroff and troff |
| 86 | .if n \{\ |
| 87 | . ds ' \& |
| 88 | . ds ` \& |
| 89 | . ds ^ \& |
| 90 | . ds , \& |
| 91 | . ds ~ ~ |
| 92 | . ds / |
| 93 | .\} |
| 94 | .if t \{\ |
| 95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 101 | .\} |
| 102 | . \" troff and (daisy-wheel) nroff accents |
| 103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 110 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 112 | . \" corrections for vroff |
| 113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 115 | . \" for low resolution devices (crt and lpr) |
| 116 | .if \n(.H>23 .if \n(.V>19 \ |
| 117 | \{\ |
| 118 | . ds : e |
| 119 | . ds 8 ss |
| 120 | . ds o a |
| 121 | . ds d- d\h'-1'\(ga |
| 122 | . ds D- D\h'-1'\(hy |
| 123 | . ds th \o'bp' |
| 124 | . ds Th \o'LP' |
| 125 | . ds ae ae |
| 126 | . ds Ae AE |
| 127 | .\} |
| 128 | .rm #[ #] #H #V #F C |
| 129 | .\" ======================================================================== |
| 130 | .\" |
| 131 | .IX Title "Devel::Peek 3" |
| 132 | .TH Devel::Peek 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide" |
| 133 | .SH "NAME" |
| 134 | Devel::Peek \- A data debugging tool for the XS programmer |
| 135 | .SH "SYNOPSIS" |
| 136 | .IX Header "SYNOPSIS" |
| 137 | .Vb 5 |
| 138 | \& use Devel::Peek; |
| 139 | \& Dump( $a ); |
| 140 | \& Dump( $a, 5 ); |
| 141 | \& DumpArray( 5, $a, $b, ... ); |
| 142 | \& mstat "Point 5"; |
| 143 | .Ve |
| 144 | .PP |
| 145 | .Vb 1 |
| 146 | \& use Devel::Peek ':opd=st'; |
| 147 | .Ve |
| 148 | .SH "DESCRIPTION" |
| 149 | .IX Header "DESCRIPTION" |
| 150 | Devel::Peek contains functions which allows raw Perl datatypes to be |
| 151 | manipulated from a Perl script. This is used by those who do \s-1XS\s0 programming |
| 152 | to check that the data they are sending from C to Perl looks as they think |
| 153 | it should look. The trick, then, is to know what the raw datatype is |
| 154 | supposed to look like when it gets to Perl. This document offers some tips |
| 155 | and hints to describe good and bad raw data. |
| 156 | .PP |
| 157 | It is very possible that this document will fall far short of being useful |
| 158 | to the casual reader. The reader is expected to understand the material in |
| 159 | the first few sections of perlguts. |
| 160 | .PP |
| 161 | Devel::Peek supplies a \f(CW\*(C`Dump()\*(C'\fR function which can dump a raw Perl |
| 162 | datatype, and \f(CW\*(C`mstat("marker")\*(C'\fR function to report on memory usage |
| 163 | (if perl is compiled with corresponding option). The function |
| 164 | \&\fIDeadCode()\fR provides statistics on the data \*(L"frozen\*(R" into inactive |
| 165 | \&\f(CW\*(C`CV\*(C'\fR. Devel::Peek also supplies \f(CW\*(C`SvREFCNT()\*(C'\fR, \f(CW\*(C`SvREFCNT_inc()\*(C'\fR, and |
| 166 | \&\f(CW\*(C`SvREFCNT_dec()\*(C'\fR which can query, increment, and decrement reference |
| 167 | counts on SVs. This document will take a passive, and safe, approach |
| 168 | to data debugging and for that it will describe only the \f(CW\*(C`Dump()\*(C'\fR |
| 169 | function. |
| 170 | .PP |
| 171 | Function \f(CW\*(C`DumpArray()\*(C'\fR allows dumping of multiple values (useful when you |
| 172 | need to analyze returns of functions). |
| 173 | .PP |
| 174 | The global variable \f(CW$Devel::Peek::pv_limit\fR can be set to limit the |
| 175 | number of character printed in various string values. Setting it to 0 |
| 176 | means no limit. |
| 177 | .PP |
| 178 | If \f(CW\*(C`use Devel::Peek\*(C'\fR directive has a \f(CW\*(C`:opd=FLAGS\*(C'\fR argument, |
| 179 | this switches on debugging of opcode dispatch. \f(CW\*(C`FLAGS\*(C'\fR should be a |
| 180 | combination of \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`t\*(C'\fR, and \f(CW\*(C`P\*(C'\fR (see \fB\-D\fR flags in perlrun). |
| 181 | \&\f(CW\*(C`:opd\*(C'\fR is a shortcut for \f(CW\*(C`:opd=st\*(C'\fR. |
| 182 | .Sh "Runtime debugging" |
| 183 | .IX Subsection "Runtime debugging" |
| 184 | \&\f(CW\*(C`CvGV($cv)\*(C'\fR return one of the globs associated to a subroutine reference \f(CW$cv\fR. |
| 185 | .PP |
| 186 | \&\fIdebug_flags()\fR returns a string representation of \f(CW$^D\fR (similar to |
| 187 | what is allowed for \fB\-D\fR flag). When called with a numeric argument, |
| 188 | sets $^D to the corresponding value. When called with an argument of |
| 189 | the form \f(CW"flags\-flags"\fR, set on/off bits of \f(CW$^D\fR corresponding to |
| 190 | letters before/after \f(CW\*(C`\-\*(C'\fR. (The returned value is for \f(CW$^D\fR before |
| 191 | the modification.) |
| 192 | .PP |
| 193 | \&\fIrunops_debug()\fR returns true if the current \fIopcode dispatcher\fR is the |
| 194 | debugging one. When called with an argument, switches to debugging or |
| 195 | non-debugging dispatcher depending on the argument (active for |
| 196 | newly-entered subs/etc only). (The returned value is for the dispatcher before the modification.) |
| 197 | .Sh "Memory footprint debugging" |
| 198 | .IX Subsection "Memory footprint debugging" |
| 199 | When perl is compiled with support for memory footprint debugging |
| 200 | (default with Perl's \fImalloc()\fR), Devel::Peek provides an access to this \s-1API\s0. |
| 201 | .PP |
| 202 | Use \fImstat()\fR function to emit a memory state statistic to the terminal. |
| 203 | For more information on the format of output of \fImstat()\fR see |
| 204 | "Using \f(CW$ENV{PERL_DEBUG_MSTATS}\fR" in perldebguts. |
| 205 | .PP |
| 206 | Three additional functions allow access to this statistic from Perl. |
| 207 | First, use \f(CW\*(C`mstats_fillhash(%hash)\*(C'\fR to get the information contained |
| 208 | in the output of \fImstat()\fR into \f(CW%hash\fR. The field of this hash are |
| 209 | .PP |
| 210 | .Vb 2 |
| 211 | \& minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack |
| 212 | \& topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree |
| 213 | .Ve |
| 214 | .PP |
| 215 | Two additional fields \f(CW\*(C`free\*(C'\fR, \f(CW\*(C`used\*(C'\fR contain array references which |
| 216 | provide per-bucket count of free and used chunks. Two other fields |
| 217 | \&\f(CW\*(C`mem_size\*(C'\fR, \f(CW\*(C`available_size\*(C'\fR contain array references which provide |
| 218 | the information about the allocated size and usable size of chunks in |
| 219 | each bucket. Again, see "Using \f(CW$ENV{PERL_DEBUG_MSTATS}\fR" in perldebguts |
| 220 | for details. |
| 221 | .PP |
| 222 | Keep in mind that only the first several \*(L"odd\-numbered\*(R" buckets are |
| 223 | used, so the information on size of the \*(L"odd\-numbered\*(R" buckets which are |
| 224 | not used is probably meaningless. |
| 225 | .PP |
| 226 | The information in |
| 227 | .PP |
| 228 | .Vb 1 |
| 229 | \& mem_size available_size minbucket nbuckets |
| 230 | .Ve |
| 231 | .PP |
| 232 | is the property of a particular build of perl, and does not depend on |
| 233 | the current process. If you do not provide the optional argument to |
| 234 | the functions \fImstats_fillhash()\fR, \fIfill_mstats()\fR, \fImstats2hash()\fR, then |
| 235 | the information in fields \f(CW\*(C`mem_size\*(C'\fR, \f(CW\*(C`available_size\*(C'\fR is not |
| 236 | updated. |
| 237 | .PP |
| 238 | \&\f(CW\*(C`fill_mstats($buf)\*(C'\fR is a much cheaper call (both speedwise and |
| 239 | memory\-wise) which collects the statistic into \f(CW$buf\fR in |
| 240 | machine-readable form. At a later moment you may need to call |
| 241 | \&\f(CW\*(C`mstats2hash($buf, %hash)\*(C'\fR to use this information to fill \f(CW%hash\fR. |
| 242 | .PP |
| 243 | All three APIs \f(CW\*(C`fill_mstats($buf)\*(C'\fR, \f(CW\*(C`mstats_fillhash(%hash)\*(C'\fR, and |
| 244 | \&\f(CW\*(C`mstats2hash($buf, %hash)\*(C'\fR are designed to allocate no memory if used |
| 245 | \&\fIthe second time\fR on the same \f(CW$buf\fR and/or \f(CW%hash\fR. |
| 246 | .PP |
| 247 | So, if you want to collect memory info in a cycle, you may call |
| 248 | .PP |
| 249 | .Vb 3 |
| 250 | \& $#buf = 999; |
| 251 | \& fill_mstats($_) for @buf; |
| 252 | \& mstats_fillhash(%report, 1); # Static info too |
| 253 | .Ve |
| 254 | .PP |
| 255 | .Vb 8 |
| 256 | \& foreach (@buf) { |
| 257 | \& # Do something... |
| 258 | \& fill_mstats $_; # Collect statistic |
| 259 | \& } |
| 260 | \& foreach (@buf) { |
| 261 | \& mstats2hash($_, %report); # Preserve static info |
| 262 | \& # Do something with %report |
| 263 | \& } |
| 264 | .Ve |
| 265 | .SH "EXAMPLES" |
| 266 | .IX Header "EXAMPLES" |
| 267 | The following examples don't attempt to show everything as that would be a |
| 268 | monumental task, and, frankly, we don't want this manpage to be an internals |
| 269 | document for Perl. The examples do demonstrate some basics of the raw Perl |
| 270 | datatypes, and should suffice to get most determined people on their way. |
| 271 | There are no guidewires or safety nets, nor blazed trails, so be prepared to |
| 272 | travel alone from this point and on and, if at all possible, don't fall into |
| 273 | the quicksand (it's bad for business). |
| 274 | .PP |
| 275 | Oh, one final bit of advice: take perlguts with you. When you return we |
| 276 | expect to see it well\-thumbed. |
| 277 | .Sh "A simple scalar string" |
| 278 | .IX Subsection "A simple scalar string" |
| 279 | Let's begin by looking a simple scalar which is holding a string. |
| 280 | .PP |
| 281 | .Vb 3 |
| 282 | \& use Devel::Peek; |
| 283 | \& $a = "hello"; |
| 284 | \& Dump $a; |
| 285 | .Ve |
| 286 | .PP |
| 287 | The output: |
| 288 | .PP |
| 289 | .Vb 7 |
| 290 | \& SV = PVIV(0xbc288) |
| 291 | \& REFCNT = 1 |
| 292 | \& FLAGS = (POK,pPOK) |
| 293 | \& IV = 0 |
| 294 | \& PV = 0xb2048 "hello"\e0 |
| 295 | \& CUR = 5 |
| 296 | \& LEN = 6 |
| 297 | .Ve |
| 298 | .PP |
| 299 | This says \f(CW$a\fR is an \s-1SV\s0, a scalar. The scalar is a \s-1PVIV\s0, a string. |
| 300 | Its reference count is 1. It has the \f(CW\*(C`POK\*(C'\fR flag set, meaning its |
| 301 | current \s-1PV\s0 field is valid. Because \s-1POK\s0 is set we look at the \s-1PV\s0 item |
| 302 | to see what is in the scalar. The \e0 at the end indicate that this |
| 303 | \&\s-1PV\s0 is properly NUL\-terminated. |
| 304 | If the \s-1FLAGS\s0 had been \s-1IOK\s0 we would look |
| 305 | at the \s-1IV\s0 item. \s-1CUR\s0 indicates the number of characters in the \s-1PV\s0. |
| 306 | \&\s-1LEN\s0 indicates the number of bytes requested for the \s-1PV\s0 (one more than |
| 307 | \&\s-1CUR\s0, in this case, because \s-1LEN\s0 includes an extra byte for the |
| 308 | end-of-string marker). |
| 309 | .Sh "A simple scalar number" |
| 310 | .IX Subsection "A simple scalar number" |
| 311 | If the scalar contains a number the raw \s-1SV\s0 will be leaner. |
| 312 | .PP |
| 313 | .Vb 3 |
| 314 | \& use Devel::Peek; |
| 315 | \& $a = 42; |
| 316 | \& Dump $a; |
| 317 | .Ve |
| 318 | .PP |
| 319 | The output: |
| 320 | .PP |
| 321 | .Vb 4 |
| 322 | \& SV = IV(0xbc818) |
| 323 | \& REFCNT = 1 |
| 324 | \& FLAGS = (IOK,pIOK) |
| 325 | \& IV = 42 |
| 326 | .Ve |
| 327 | .PP |
| 328 | This says \f(CW$a\fR is an \s-1SV\s0, a scalar. The scalar is an \s-1IV\s0, a number. Its |
| 329 | reference count is 1. It has the \f(CW\*(C`IOK\*(C'\fR flag set, meaning it is currently |
| 330 | being evaluated as a number. Because \s-1IOK\s0 is set we look at the \s-1IV\s0 item to |
| 331 | see what is in the scalar. |
| 332 | .Sh "A simple scalar with an extra reference" |
| 333 | .IX Subsection "A simple scalar with an extra reference" |
| 334 | If the scalar from the previous example had an extra reference: |
| 335 | .PP |
| 336 | .Vb 4 |
| 337 | \& use Devel::Peek; |
| 338 | \& $a = 42; |
| 339 | \& $b = \e$a; |
| 340 | \& Dump $a; |
| 341 | .Ve |
| 342 | .PP |
| 343 | The output: |
| 344 | .PP |
| 345 | .Vb 4 |
| 346 | \& SV = IV(0xbe860) |
| 347 | \& REFCNT = 2 |
| 348 | \& FLAGS = (IOK,pIOK) |
| 349 | \& IV = 42 |
| 350 | .Ve |
| 351 | .PP |
| 352 | Notice that this example differs from the previous example only in its |
| 353 | reference count. Compare this to the next example, where we dump \f(CW$b\fR |
| 354 | instead of \f(CW$a\fR. |
| 355 | .Sh "A reference to a simple scalar" |
| 356 | .IX Subsection "A reference to a simple scalar" |
| 357 | This shows what a reference looks like when it references a simple scalar. |
| 358 | .PP |
| 359 | .Vb 4 |
| 360 | \& use Devel::Peek; |
| 361 | \& $a = 42; |
| 362 | \& $b = \e$a; |
| 363 | \& Dump $b; |
| 364 | .Ve |
| 365 | .PP |
| 366 | The output: |
| 367 | .PP |
| 368 | .Vb 8 |
| 369 | \& SV = RV(0xf041c) |
| 370 | \& REFCNT = 1 |
| 371 | \& FLAGS = (ROK) |
| 372 | \& RV = 0xbab08 |
| 373 | \& SV = IV(0xbe860) |
| 374 | \& REFCNT = 2 |
| 375 | \& FLAGS = (IOK,pIOK) |
| 376 | \& IV = 42 |
| 377 | .Ve |
| 378 | .PP |
| 379 | Starting from the top, this says \f(CW$b\fR is an \s-1SV\s0. The scalar is an \s-1RV\s0, a |
| 380 | reference. It has the \f(CW\*(C`ROK\*(C'\fR flag set, meaning it is a reference. Because |
| 381 | \&\s-1ROK\s0 is set we have an \s-1RV\s0 item rather than an \s-1IV\s0 or \s-1PV\s0. Notice that Dump |
| 382 | follows the reference and shows us what \f(CW$b\fR was referencing. We see the |
| 383 | same \f(CW$a\fR that we found in the previous example. |
| 384 | .PP |
| 385 | Note that the value of \f(CW\*(C`RV\*(C'\fR coincides with the numbers we see when we |
| 386 | stringify \f(CW$b\fR. The addresses inside \s-1\fIRV\s0()\fR and \s-1\fIIV\s0()\fR are addresses of |
| 387 | \&\f(CW\*(C`X***\*(C'\fR structure which holds the current state of an \f(CW\*(C`SV\*(C'\fR. This |
| 388 | address may change during lifetime of an \s-1SV\s0. |
| 389 | .Sh "A reference to an array" |
| 390 | .IX Subsection "A reference to an array" |
| 391 | This shows what a reference to an array looks like. |
| 392 | .PP |
| 393 | .Vb 3 |
| 394 | \& use Devel::Peek; |
| 395 | \& $a = [42]; |
| 396 | \& Dump $a; |
| 397 | .Ve |
| 398 | .PP |
| 399 | The output: |
| 400 | .PP |
| 401 | .Vb 20 |
| 402 | \& SV = RV(0xf041c) |
| 403 | \& REFCNT = 1 |
| 404 | \& FLAGS = (ROK) |
| 405 | \& RV = 0xb2850 |
| 406 | \& SV = PVAV(0xbd448) |
| 407 | \& REFCNT = 1 |
| 408 | \& FLAGS = () |
| 409 | \& IV = 0 |
| 410 | \& NV = 0 |
| 411 | \& ARRAY = 0xb2048 |
| 412 | \& ALLOC = 0xb2048 |
| 413 | \& FILL = 0 |
| 414 | \& MAX = 0 |
| 415 | \& ARYLEN = 0x0 |
| 416 | \& FLAGS = (REAL) |
| 417 | \& Elt No. 0 0xb5658 |
| 418 | \& SV = IV(0xbe860) |
| 419 | \& REFCNT = 1 |
| 420 | \& FLAGS = (IOK,pIOK) |
| 421 | \& IV = 42 |
| 422 | .Ve |
| 423 | .PP |
| 424 | This says \f(CW$a\fR is an \s-1SV\s0 and that it is an \s-1RV\s0. That \s-1RV\s0 points to |
| 425 | another \s-1SV\s0 which is a \s-1PVAV\s0, an array. The array has one element, |
| 426 | element zero, which is another \s-1SV\s0. The field \f(CW\*(C`FILL\*(C'\fR above indicates |
| 427 | the last element in the array, similar to \f(CW\*(C`$#$a\*(C'\fR. |
| 428 | .PP |
| 429 | If \f(CW$a\fR pointed to an array of two elements then we would see the |
| 430 | following. |
| 431 | .PP |
| 432 | .Vb 3 |
| 433 | \& use Devel::Peek 'Dump'; |
| 434 | \& $a = [42,24]; |
| 435 | \& Dump $a; |
| 436 | .Ve |
| 437 | .PP |
| 438 | The output: |
| 439 | .PP |
| 440 | .Vb 25 |
| 441 | \& SV = RV(0xf041c) |
| 442 | \& REFCNT = 1 |
| 443 | \& FLAGS = (ROK) |
| 444 | \& RV = 0xb2850 |
| 445 | \& SV = PVAV(0xbd448) |
| 446 | \& REFCNT = 1 |
| 447 | \& FLAGS = () |
| 448 | \& IV = 0 |
| 449 | \& NV = 0 |
| 450 | \& ARRAY = 0xb2048 |
| 451 | \& ALLOC = 0xb2048 |
| 452 | \& FILL = 0 |
| 453 | \& MAX = 0 |
| 454 | \& ARYLEN = 0x0 |
| 455 | \& FLAGS = (REAL) |
| 456 | \& Elt No. 0 0xb5658 |
| 457 | \& SV = IV(0xbe860) |
| 458 | \& REFCNT = 1 |
| 459 | \& FLAGS = (IOK,pIOK) |
| 460 | \& IV = 42 |
| 461 | \& Elt No. 1 0xb5680 |
| 462 | \& SV = IV(0xbe818) |
| 463 | \& REFCNT = 1 |
| 464 | \& FLAGS = (IOK,pIOK) |
| 465 | \& IV = 24 |
| 466 | .Ve |
| 467 | .PP |
| 468 | Note that \f(CW\*(C`Dump\*(C'\fR will not report \fIall\fR the elements in the array, |
| 469 | only several first (depending on how deep it already went into the |
| 470 | report tree). |
| 471 | .Sh "A reference to a hash" |
| 472 | .IX Subsection "A reference to a hash" |
| 473 | The following shows the raw form of a reference to a hash. |
| 474 | .PP |
| 475 | .Vb 3 |
| 476 | \& use Devel::Peek; |
| 477 | \& $a = {hello=>42}; |
| 478 | \& Dump $a; |
| 479 | .Ve |
| 480 | .PP |
| 481 | The output: |
| 482 | .PP |
| 483 | .Vb 19 |
| 484 | \& SV = RV(0xf041c) |
| 485 | \& REFCNT = 1 |
| 486 | \& FLAGS = (ROK) |
| 487 | \& RV = 0xb2850 |
| 488 | \& SV = PVHV(0xbd448) |
| 489 | \& REFCNT = 1 |
| 490 | \& FLAGS = () |
| 491 | \& NV = 0 |
| 492 | \& ARRAY = 0xbd748 |
| 493 | \& KEYS = 1 |
| 494 | \& FILL = 1 |
| 495 | \& MAX = 7 |
| 496 | \& RITER = -1 |
| 497 | \& EITER = 0x0 |
| 498 | \& Elt "hello" => 0xbaaf0 |
| 499 | \& SV = IV(0xbe860) |
| 500 | \& REFCNT = 1 |
| 501 | \& FLAGS = (IOK,pIOK) |
| 502 | \& IV = 42 |
| 503 | .Ve |
| 504 | .PP |
| 505 | This shows \f(CW$a\fR is a reference pointing to an \s-1SV\s0. That \s-1SV\s0 is a \s-1PVHV\s0, a |
| 506 | hash. Fields \s-1RITER\s0 and \s-1EITER\s0 are used by \f(CW\*(C`each\*(C'\fR. |
| 507 | .Sh "Dumping a large array or hash" |
| 508 | .IX Subsection "Dumping a large array or hash" |
| 509 | The \f(CW\*(C`Dump()\*(C'\fR function, by default, dumps up to 4 elements from a |
| 510 | toplevel array or hash. This number can be increased by supplying a |
| 511 | second argument to the function. |
| 512 | .PP |
| 513 | .Vb 3 |
| 514 | \& use Devel::Peek; |
| 515 | \& $a = [10,11,12,13,14]; |
| 516 | \& Dump $a; |
| 517 | .Ve |
| 518 | .PP |
| 519 | Notice that \f(CW\*(C`Dump()\*(C'\fR prints only elements 10 through 13 in the above code. |
| 520 | The following code will print all of the elements. |
| 521 | .PP |
| 522 | .Vb 3 |
| 523 | \& use Devel::Peek 'Dump'; |
| 524 | \& $a = [10,11,12,13,14]; |
| 525 | \& Dump $a, 5; |
| 526 | .Ve |
| 527 | .Sh "A reference to an \s-1SV\s0 which holds a C pointer" |
| 528 | .IX Subsection "A reference to an SV which holds a C pointer" |
| 529 | This is what you really need to know as an \s-1XS\s0 programmer, of course. When |
| 530 | an \s-1XSUB\s0 returns a pointer to a C structure that pointer is stored in an \s-1SV\s0 |
| 531 | and a reference to that \s-1SV\s0 is placed on the \s-1XSUB\s0 stack. So the output from |
| 532 | an \s-1XSUB\s0 which uses something like the T_PTROBJ map might look something like |
| 533 | this: |
| 534 | .PP |
| 535 | .Vb 11 |
| 536 | \& SV = RV(0xf381c) |
| 537 | \& REFCNT = 1 |
| 538 | \& FLAGS = (ROK) |
| 539 | \& RV = 0xb8ad8 |
| 540 | \& SV = PVMG(0xbb3c8) |
| 541 | \& REFCNT = 1 |
| 542 | \& FLAGS = (OBJECT,IOK,pIOK) |
| 543 | \& IV = 729160 |
| 544 | \& NV = 0 |
| 545 | \& PV = 0 |
| 546 | \& STASH = 0xc1d10 "CookBookB::Opaque" |
| 547 | .Ve |
| 548 | .PP |
| 549 | This shows that we have an \s-1SV\s0 which is an \s-1RV\s0. That \s-1RV\s0 points at another |
| 550 | \&\s-1SV\s0. In this case that second \s-1SV\s0 is a \s-1PVMG\s0, a blessed scalar. Because it is |
| 551 | blessed it has the \f(CW\*(C`OBJECT\*(C'\fR flag set. Note that an \s-1SV\s0 which holds a C |
| 552 | pointer also has the \f(CW\*(C`IOK\*(C'\fR flag set. The \f(CW\*(C`STASH\*(C'\fR is set to the package |
| 553 | name which this \s-1SV\s0 was blessed into. |
| 554 | .PP |
| 555 | The output from an \s-1XSUB\s0 which uses something like the T_PTRREF map, which |
| 556 | doesn't bless the object, might look something like this: |
| 557 | .PP |
| 558 | .Vb 10 |
| 559 | \& SV = RV(0xf381c) |
| 560 | \& REFCNT = 1 |
| 561 | \& FLAGS = (ROK) |
| 562 | \& RV = 0xb8ad8 |
| 563 | \& SV = PVMG(0xbb3c8) |
| 564 | \& REFCNT = 1 |
| 565 | \& FLAGS = (IOK,pIOK) |
| 566 | \& IV = 729160 |
| 567 | \& NV = 0 |
| 568 | \& PV = 0 |
| 569 | .Ve |
| 570 | .Sh "A reference to a subroutine" |
| 571 | .IX Subsection "A reference to a subroutine" |
| 572 | Looks like this: |
| 573 | .PP |
| 574 | .Vb 18 |
| 575 | \& SV = RV(0x798ec) |
| 576 | \& REFCNT = 1 |
| 577 | \& FLAGS = (TEMP,ROK) |
| 578 | \& RV = 0x1d453c |
| 579 | \& SV = PVCV(0x1c768c) |
| 580 | \& REFCNT = 2 |
| 581 | \& FLAGS = () |
| 582 | \& IV = 0 |
| 583 | \& NV = 0 |
| 584 | \& COMP_STASH = 0x31068 "main" |
| 585 | \& START = 0xb20e0 |
| 586 | \& ROOT = 0xbece0 |
| 587 | \& XSUB = 0x0 |
| 588 | \& XSUBANY = 0 |
| 589 | \& GVGV::GV = 0x1d44e8 "MY" :: "top_targets" |
| 590 | \& FILE = "(eval 5)" |
| 591 | \& DEPTH = 0 |
| 592 | \& PADLIST = 0x1c9338 |
| 593 | .Ve |
| 594 | .PP |
| 595 | This shows that |
| 596 | .IP "\(bu" 4 |
| 597 | the subroutine is not an \s-1XSUB\s0 (since \f(CW\*(C`START\*(C'\fR and \f(CW\*(C`ROOT\*(C'\fR are |
| 598 | non\-zero, and \f(CW\*(C`XSUB\*(C'\fR is zero); |
| 599 | .IP "\(bu" 4 |
| 600 | that it was compiled in the package \f(CW\*(C`main\*(C'\fR; |
| 601 | .IP "\(bu" 4 |
| 602 | under the name \f(CW\*(C`MY::top_targets\*(C'\fR; |
| 603 | .IP "\(bu" 4 |
| 604 | inside a 5th eval in the program; |
| 605 | .IP "\(bu" 4 |
| 606 | it is not currently executed (see \f(CW\*(C`DEPTH\*(C'\fR); |
| 607 | .IP "\(bu" 4 |
| 608 | it has no prototype (\f(CW\*(C`PROTOTYPE\*(C'\fR field is missing). |
| 609 | .SH "EXPORTS" |
| 610 | .IX Header "EXPORTS" |
| 611 | \&\f(CW\*(C`Dump\*(C'\fR, \f(CW\*(C`mstat\*(C'\fR, \f(CW\*(C`DeadCode\*(C'\fR, \f(CW\*(C`DumpArray\*(C'\fR, \f(CW\*(C`DumpWithOP\*(C'\fR and |
| 612 | \&\f(CW\*(C`DumpProg\*(C'\fR, \f(CW\*(C`fill_mstats\*(C'\fR, \f(CW\*(C`mstats_fillhash\*(C'\fR, \f(CW\*(C`mstats2hash\*(C'\fR by |
| 613 | default. Additionally available \f(CW\*(C`SvREFCNT\*(C'\fR, \f(CW\*(C`SvREFCNT_inc\*(C'\fR and |
| 614 | \&\f(CW\*(C`SvREFCNT_dec\*(C'\fR. |
| 615 | .SH "BUGS" |
| 616 | .IX Header "BUGS" |
| 617 | Readers have been known to skip important parts of perlguts, causing much |
| 618 | frustration for all. |
| 619 | .SH "AUTHOR" |
| 620 | .IX Header "AUTHOR" |
| 621 | Ilya Zakharevich ilya@math.ohio\-state.edu |
| 622 | .PP |
| 623 | Copyright (c) 1995\-98 Ilya Zakharevich. All rights reserved. |
| 624 | This program is free software; you can redistribute it and/or |
| 625 | modify it under the same terms as Perl itself. |
| 626 | .PP |
| 627 | Author of this software makes no claim whatsoever about suitability, |
| 628 | reliability, edability, editability or usability of this product, and |
| 629 | should not be kept liable for any damage resulting from the use of |
| 630 | it. If you can use it, you are in luck, if not, I should not be kept |
| 631 | responsible. Keep a handy copy of your backup tape at hand. |
| 632 | .SH "SEE ALSO" |
| 633 | .IX Header "SEE ALSO" |
| 634 | perlguts, and perlguts, again. |