1Devel::MAT::Dumper(3pm)User Contributed Perl DocumentatioDnevel::MAT::Dumper(3pm)
2
3
4

NAME

6       "Devel::MAT::Dumper" - write a heap dump file for later analysis
7

SYNOPSIS

9        use Devel::MAT::Dumper;
10
11        Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );
12

DESCRIPTION

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
19       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
26       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

IMPORT OPTIONS

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
35   -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
40          $ perl -MDevel::MAT::Dumper=-dump_at_DIE ...
41
42   -dump_at_WARN
43       Installs a handler for the special "__WARN__" signal to write a dump
44       file when perl prints a warning.
45
46          $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...
47
48       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
52   -dump_at_END
53       Installs an "END" block which writes a dump file at "END" time, just
54       before the interpreter exits.
55
56          $ perl -MDevel::MAT::Dumper=-dump_at_END ...
57
58   -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
63          $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...
64
65       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
70   -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
75          $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...
76
77       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
81   -file $PATH
82       Sets the name of the file which is automatically dumped; defaults to
83       basename $0.pmat if not supplied.
84
85          $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...
86
87       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
92          $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
93          hello
94          Dumping to perl-e.pmat because of END
95
96       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
101       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
106   -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
111   -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

FUNCTIONS

118       These functions are not exported, they must be called fully-qualified.
119
120   dump
121          dump( $path )
122
123       Writes a heap dump to the named file
124
125   dumpfh
126          dumpfh( $fh )
127
128       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

AUTHOR

133       Paul Evans <leonerd@leonerd.org.uk>
134
135
136
137perl v5.38.0                      2023-07-20           Devel::MAT::Dumper(3pm)
Impressum