1Devel::MAT::Dumper(3) User Contributed Perl DocumentationDevel::MAT::Dumper(3)
2
6 "Devel::MAT::Dumper" - write a heap dump file for later analysis
7
9 use Devel::MAT::Dumper;
10 Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );
12
14 This module provides the memory-dumping function that creates a heap
15 dump file which can later be read by Devel::MAT::Dumpfile. It provides
16 a single function which is not exported, which writes a file to the
17 given path.
18 The dump file will contain a representation of every SV in Perl's
20 arena, providing information about pointers between them, as well as
21 other information about the state of the process at the time it was
22 created. It contains a snapshot of the process at that moment in time,
23 which can later be loaded and analysed by various tools using
24 "Devel::MAT::Dumpfile".
25 This module used to be part of the main Devel::MAT distribution but is
27 now in its own one so that it can be installed independently on servers
28 or other locations where perl processes need to inspected but analysis
29 tools can be run elsewhere.
30
32 The following "import" options control the behaviour of the module.
33 They may primarily be useful when used in the "-M" perl option:
34 -dump_at_DIE
36 Installs a handler for the special "__DIE__" signal to write a dump
37 file when "die()" is about to cause a fatal signal. This is more
38 reliable at catching the callstack and memory state than using an "END"
39 block.
40 $ perl -MDevel::MAT::Dumper=-dump_at_DIE ...
42 -dump_at_WARN
44 Installs a handler for the special "__WARN__" signal to write a dump
45 file when perl prints a warning.
46 $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...
48 It is likely useful to combine this with the "NNN" numbering feature of
50 the "-file" argument, to ensure that later warnings don't overwrite a
51 particular file.
52 -dump_at_END
54 Installs an "END" block which writes a dump file at "END" time, just
55 before the interpreter exits.
56 $ perl -MDevel::MAT::Dumper=-dump_at_END ...
58 -dump_at_SIGQUIT
60 Installs a handler for "SIGQUIT" to write a dump file if the signal is
61 received. The signal handler will remain in place and can be used
62 several times.
63 $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...
65 Take care if you are using the "<Ctrl-\>" key combination on a terminal
67 to send this signal to a foreground process, because if it has
68 "fork()"ed any background workers or similar, the signal will also be
69 delivered to those as well.
70 -dump_at_SIGNAME
72 Installs a handler for the named signal (e.g. "SIGABRT", "SIGINT") to
73 write a dump file if the signal is received. After dumping the file,
74 the signal handler is removed and the signal re-raised.
75 $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...
77 Note that "SIGABRT" uses an "unsafe" signal handler (i.e. not deferred
79 until the next perl op), so it can capture the full context of any
80 ongoing XS or C library operations.
81 -file $PATH
83 Sets the name of the file which is automatically dumped; defaults to
84 basename $0.pmat if not supplied.
85 $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...
87 In the special case that $0 is exactly the string "-e" or "-E", the
89 filename will be prefixed with "perl" so as not to create files whose
90 names begin with a leading hyphen, as this confuses some commandline
91 parsers.
92 $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
94 hello
95 Dumping to perl-e.pmat because of END
96 If the pattern contains "NNN", this will be replaced by a unique serial
98 number per written file, starting from 0. This may be helpful in the
99 case of "DIE", "WARN" or "SIGQUIT" handlers, which could be invoked
100 multiple times.
101 The file name is converted to an absolute path immediately, so if the
103 running program later calls "chdir()", it will still be generated in
104 the directory the program started from rather than the one it happens
105 to be in at the time.
106 -max_string
108 Sets the maximum length of string buffer to dump from PVs; defaults to
109 256 if not supplied. Use a negative size to dump the entire buffer of
110 every PV regardless of size.
111 -eager_open
113 Opens the dump file immediately at "import" time, instead of waiting
114 until the time it actually writes the heap dump. This may be useful if
115 the process changes user ID, or to debug problems involving too many
116 open filehandles.
117
119 These functions are not exported, they must be called fully-qualified.
120 dump
122 dump( $path )
123 Writes a heap dump to the named file
125 dumpfh
127 dumpfh( $fh )
128 Writes a heap dump to the given filehandle (which must be a plain OS-
130 level filehandle, though does not need to be a regular file, or
131 seekable).
132
134 Paul Evans <leonerd@leonerd.org.uk>
135perl v5.34.0 2022-01-21 Devel::MAT::Dumper(3)