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 reliable
38 at catching the callstack and memory state than using an "END" block.
39 $ perl -MDevel::MAT::Dumper=-dump_at_DIE ...
41 -dump_at_WARN
43 Installs a handler for the special "__WARN__" signal to write a dump
44 file when perl prints a warning.
45 $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...
47 It is likely useful to combine this with the "NNN" numbering feature of
49 the "-file" argument, to ensure that later warnings don't overwrite a
50 particular file.
51 -dump_at_END
53 Installs an "END" block which writes a dump file at "END" time, just
54 before the interpreter exits.
55 $ perl -MDevel::MAT::Dumper=-dump_at_END ...
57 -dump_at_SIGQUIT
59 Installs a handler for "SIGQUIT" to write a dump file if the signal is
60 received. The signal handler will remain in place and can be used
61 several times.
62 $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...
64 Take care if you are using the "<Ctrl-\>" key combination on a terminal
66 to send this signal to a foreground process, because if it has fork()ed
67 any background workers or similar, the signal will also be delivered to
68 those as well.
69 -dump_at_SIGNAME
71 Installs a handler for the named signal (e.g. "SIGABRT", "SIGINT") to
72 write a dump file if the signal is received. After dumping the file,
73 the signal handler is removed and the signal re-raised.
74 $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...
76 Note that "SIGABRT" uses an "unsafe" signal handler (i.e. not deferred
78 until the next perl op), so it can capture the full context of any
79 ongoing XS or C library operations.
80 -file $PATH
82 Sets the name of the file which is automatically dumped; defaults to
83 basename $0.pmat if not supplied.
84 $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...
86 In the special case that $0 is exactly the string "-e" or "-E", the
88 filename will be prefixed with "perl" so as not to create files whose
89 names begin with a leading hyphen, as this confuses some commandline
90 parsers.
91 $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
93 hello
94 Dumping to perl-e.pmat because of END
95 If the pattern contains "NNN", this will be replaced by a unique serial
97 number per written file, starting from 0. This may be helpful in the
98 case of "DIE", "WARN" or "SIGQUIT" handlers, which could be invoked
99 multiple times.
100 The file name is converted to an absolute path immediately, so if the
102 running program later calls chdir(), it will still be generated in the
103 directory the program started from rather than the one it happens to be
104 in at the time.
105 -max_string
107 Sets the maximum length of string buffer to dump from PVs; defaults to
108 256 if not supplied. Use a negative size to dump the entire buffer of
109 every PV regardless of size.
110 -eager_open
112 Opens the dump file immediately at "import" time, instead of waiting
113 until the time it actually writes the heap dump. This may be useful if
114 the process changes user ID, or to debug problems involving too many
115 open filehandles.
116
118 These functions are not exported, they must be called fully-qualified.
119 dump
121 dump( $path )
122 Writes a heap dump to the named file
124 dumpfh
126 dumpfh( $fh )
127 Writes a heap dump to the given filehandle (which must be a plain OS-
129 level filehandle, though does not need to be a regular file, or
130 seekable).
131
133 Paul Evans <leonerd@leonerd.org.uk>
134perl v5.36.0 2023-01-20 Devel::MAT::Dumper(3)