.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Devel::MAT::Dumper 3pm"
.TH Devel::MAT::Dumper 3pm "2022-10-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Devel::MAT::Dumper" \- write a heap dump file for later analysis
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Devel::MAT::Dumper;
\&
\& Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the memory-dumping function that creates a heap dump file
which can later be read by Devel::MAT::Dumpfile. It provides a single
function which is not exported, which writes a file to the given path.
.PP
The dump file will contain a representation of every \s-1SV\s0 in Perl's arena,
providing information about pointers between them, as well as other
information about the state of the process at the time it was created. It
contains a snapshot of the process at that moment in time, which can later be
loaded and analysed by various tools using \f(CW\*(C`Devel::MAT::Dumpfile\*(C'\fR.
.PP
This module used to be part of the main Devel::MAT distribution but is now
in its own one so that it can be installed independently on servers or other
locations where perl processes need to inspected but analysis tools can be run
elsewhere.
.SH "IMPORT OPTIONS"
.IX Header "IMPORT OPTIONS"
The following \f(CW\*(C`import\*(C'\fR options control the behaviour of the module. They may
primarily be useful when used in the \f(CW\*(C`\-M\*(C'\fR perl option:
.SS "\-dump_at_DIE"
.IX Subsection "-dump_at_DIE"
Installs a handler for the special \f(CW\*(C`_\|_DIE_\|_\*(C'\fR signal to write a dump file when
\&\f(CW\*(C`die()\*(C'\fR is about to cause a fatal signal. This is more reliable at catching
the callstack and memory state than using an \f(CW\*(C`END\*(C'\fR block.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_DIE ...
.Ve
.SS "\-dump_at_WARN"
.IX Subsection "-dump_at_WARN"
Installs a handler for the special \f(CW\*(C`_\|_WARN_\|_\*(C'\fR signal to write a dump file
when perl prints a warning.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_WARN ...
.Ve
.PP
It is likely useful to combine this with the \f(CW\*(C`NNN\*(C'\fR numbering feature of the
\&\f(CW\*(C`\-file\*(C'\fR argument, to ensure that later warnings don't overwrite a particular
file.
.SS "\-dump_at_END"
.IX Subsection "-dump_at_END"
Installs an \f(CW\*(C`END\*(C'\fR block which writes a dump file at \f(CW\*(C`END\*(C'\fR time, just before
the interpreter exits.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_END ...
.Ve
.SS "\-dump_at_SIGQUIT"
.IX Subsection "-dump_at_SIGQUIT"
Installs a handler for \f(CW\*(C`SIGQUIT\*(C'\fR to write a dump file if the signal is
received. The signal handler will remain in place and can be used several
times.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_SIGQUIT ...
.Ve
.PP
Take care if you are using the \f(CW\*(C`<Ctrl\-\e>\*(C'\fR key combination on a terminal
to send this signal to a foreground process, because if it has \f(CW\*(C`fork()\*(C'\fRed any
background workers or similar, the signal will also be delivered to those as
well.
.SS "\-dump_at_SIG\fI\s-1NAME\s0\fP"
.IX Subsection "-dump_at_SIGNAME"
Installs a handler for the named signal (e.g. \f(CW\*(C`SIGABRT\*(C'\fR, \f(CW\*(C`SIGINT\*(C'\fR) to write
a dump file if the signal is received. After dumping the file, the signal
handler is removed and the signal re-raised.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_SIGABRT ...
.Ve
.PP
Note that \f(CW\*(C`SIGABRT\*(C'\fR uses an \*(L"unsafe\*(R" signal handler (i.e. not deferred until
the next perl op), so it can capture the full context of any ongoing \s-1XS\s0 or C
library operations.
.ie n .SS "\-file $PATH"
.el .SS "\-file \f(CW$PATH\fP"
.IX Subsection "-file $PATH"
Sets the name of the file which is automatically dumped; defaults to basename
\&\fI\f(CI$0\fI.pmat\fR if not supplied.
.PP
.Vb 1
\&   $ perl \-MDevel::MAT::Dumper=\-file,foo.pmat ...
.Ve
.PP
In the special case that \f(CW$0\fR is exactly the string \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR, the
filename will be prefixed with \f(CW\*(C`perl\*(C'\fR so as not to create files whose names
begin with a leading hyphen, as this confuses some commandline parsers.
.PP
.Vb 3
\&   $ perl \-MDevel::MAT::Dumper=\-dump_at_END \-E \*(Aqsay "hello"\*(Aq
\&   hello
\&   Dumping to perl\-e.pmat because of END
.Ve
.PP
If the pattern contains \f(CW\*(C`NNN\*(C'\fR, this will be replaced by a unique serial
number per written file, starting from 0. This may be helpful in the case of
\&\f(CW\*(C`DIE\*(C'\fR, \f(CW\*(C`WARN\*(C'\fR or \f(CW\*(C`SIGQUIT\*(C'\fR handlers, which could be invoked multiple times.
.PP
The file name is converted to an absolute path immediately, so if the running
program later calls \f(CW\*(C`chdir()\*(C'\fR, it will still be generated in the directory
the program started from rather than the one it happens to be in at the time.
.SS "\-max_string"
.IX Subsection "-max_string"
Sets the maximum length of string buffer to dump from PVs; defaults to 256 if
not supplied. Use a negative size to dump the entire buffer of every \s-1PV\s0
regardless of size.
.SS "\-eager_open"
.IX Subsection "-eager_open"
Opens the dump file immediately at \f(CW\*(C`import\*(C'\fR time, instead of waiting until
the time it actually writes the heap dump. This may be useful if the process
changes user \s-1ID,\s0 or to debug problems involving too many open filehandles.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
These functions are not exported, they must be called fully-qualified.
.SS "dump"
.IX Subsection "dump"
.Vb 1
\&   dump( $path )
.Ve
.PP
Writes a heap dump to the named file
.SS "dumpfh"
.IX Subsection "dumpfh"
.Vb 1
\&   dumpfh( $fh )
.Ve
.PP
Writes a heap dump to the given filehandle (which must be a plain OS-level
filehandle, though does not need to be a regular file, or seekable).
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>