Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Devel::MAT::Dumper(3) User Contributed Perl DocumentationDevel::MAT::Dumper(3)

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

	use Devel::MAT::Dumper;

	Devel::MAT::Dumper::dump( "path/to/the/file.pmat" );

       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.

       The dump	file will contain a representation of every SV 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

       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.

       The following "import" options control the behaviour of the module.
       They may	primarily be useful when used in the "-M" perl option:

       Installs	a handler for the special "__DIE__" signal to write a dump
       file when "die()" is about to cause a fatal signal. This	is more
       reliable	at catching the	callstack and memory state than	using an "END"

	  $ perl -MDevel::MAT::Dumper=-dump_at_DIE ...

       Installs	a handler for the special "__WARN__" signal to write a dump
       file when perl prints a warning.

	  $ perl -MDevel::MAT::Dumper=-dump_at_WARN ...

       It is likely useful to combine this with	the "NNN" numbering feature of
       the "-file" argument, to	ensure that later warnings don't overwrite a
       particular file.

       Installs	an "END" block which writes a dump file	at "END" time, just
       before the interpreter exits.

	  $ perl -MDevel::MAT::Dumper=-dump_at_END ...

       Installs	a handler for "SIGQUIT"	to write a dump	file if	the signal is
       received. The signal handler will remain	in place and can be used
       several times.

	  $ perl -MDevel::MAT::Dumper=-dump_at_SIGQUIT ...

       Take care if you	are using the "<Ctrl-\>" key combination on a terminal
       to send this signal to a	foreground process, because if it has
       "fork()"ed any background workers or similar, the signal	will also be
       delivered to those as well.

       Installs	a handler for the named	signal (e.g. "SIGABRT",	"SIGINT") to
       write a dump file if the	signal is received. After dumping the file,
       the signal handler is removed and the signal re-raised.

	  $ perl -MDevel::MAT::Dumper=-dump_at_SIGABRT ...

       Note that "SIGABRT" uses	an "unsafe" signal handler (i.e. not deferred
       until the next perl op),	so it can capture the full context of any
       ongoing XS or C library operations.

   -file $PATH
       Sets the	name of	the file which is automatically	dumped;	defaults to
       basename	$0.pmat	if not supplied.

	  $ perl -MDevel::MAT::Dumper=-file,foo.pmat ...

       In the special case that	$0 is exactly the string "-e" or "-E", the
       filename	will be	prefixed with "perl" so	as not to create files whose
       names begin with	a leading hyphen, as this confuses some	commandline

	  $ perl -MDevel::MAT::Dumper=-dump_at_END -E 'say "hello"'
	  Dumping to perl-e.pmat because of END

       If the pattern contains "NNN", this will	be replaced by a unique	serial
       number per written file,	starting from 0. This may be helpful in	the
       case of "DIE", "WARN" or	"SIGQUIT" handlers, which could	be invoked
       multiple	times.

       The file	name is	converted to an	absolute path immediately, so if the
       running program later calls "chdir()", it will still be generated in
       the directory the program started from rather than the one it happens
       to be in	at the time.

       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 PV	regardless of size.

       Opens the dump file immediately at "import" time, instead of waiting
       until the time it actually writes the heap dump.	This may be useful if
       the process changes user	ID, or to debug	problems involving too many
       open filehandles.

       These functions are not exported, they must be called fully-qualified.

	  dump(	$path )

       Writes a	heap dump to the named file

	  dumpfh( $fh )

       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

       Paul Evans <>

perl v5.32.0			  2020-08-08		 Devel::MAT::Dumper(3)


Want to link to this manual page? Use this URL:

home | help