Devel:...Dumper(3pm)

💖 NAME 💖

Devel::MAT::Dumper — bestie, this is the module that writes you a heap dump file so you can snoop on it later ✨

---

🌸 SYNOPSIS 🌸

use Devel::MAT::Dumper;

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

---

🦋 DESCRIPTION 🦋

okay so listen. This module is the memory-dumping queen 👑 — it makes a heap dump file that Devel::MAT::Dumpfile can come along later and read. It gives you exactly one function, it is not exported, and all it does is write a file to whatever path you hand it.

And like, the dump file is not playing around. It has a representation of every single SV in Perl's arena — all the pointer tea between them ☕ plus other info about the state of the process at the moment the file was born. It is literally a snapshot of the process at that exact moment in time, which you can load up later and analyse with all the various tools via Devel::MAT::Dumpfile.

ngl this module used to be part of the main Devel::MAT distribution, but it has since moved out into its own whole thing so it can be installed independently — yes on servers, yes in other locations where perl processes need to be inspected while the analysis tools get to vibe somewhere else entirely. main character energy fr 💅

---

✨ IMPORT OPTIONS ✨

These import options control how the module behaves. They are highkey most useful when you're using the -M perl option:

🎀 -dump_at_DIE

Installs a handler for the special __DIE__ signal so a dump file gets written right when die() is about to cause a fatal signal. The way this one catches the callstack and memory state is more reliable than an END block, periodt.

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

🌈 -dump_at_WARN

Installs a handler for the special __WARN__ signal, so a dump file gets written whenever perl prints a warning.

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

You're probably gonna want to combine this with the NNN numbering feature of the -file argument, so that later warnings don't just roll up and overwrite some particular file. 🙈

⭐ -dump_at_END

Installs an END block that writes a dump file at END time, right before the interpreter exits.

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

💀 -dump_at_SIGQUIT

Installs a handler for SIGQUIT that writes a dump file if the signal comes through. This signal handler stays in place and can be used several times over.

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

⚠️ Take care if you're 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 is gonna get delivered to those too. 😭

🔥 -dump_at_SIGNAME

Installs a handler for the named signal (think SIGABRT, SIGINT) to write a dump file if that signal shows up. After dumping the file, the signal handler is removed and the signal is re-raised.

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

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

🍓 -file $PATH

Sets the name of the file that gets automatically dumped. If you don't supply it, it defaults to basename $0.pmat.

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

In the special case where $0 is exactly the string -e or -E, the filename gets prefixed with perl so we don't go creating files whose names start with a leading hyphen — because that confuses some commandline parsers, and we are not about that life.

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

If the pattern contains NNN, that gets replaced by a unique serial number per written file, starting from 0. This is a whole mood for DIE, WARN or SIGQUIT handlers, which could totally get invoked multiple times.

And 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 whatever one it happens to be in at the time. iconic. 💅

🧚 -max_string

Sets the maximum length of string buffer to dump from PVs. Defaults to 256 if you don't supply it. Use a negative size to dump the entire buffer of every PV, regardless of size. no cap.

💜 -eager_open

Opens the dump file immediately at import time, instead of waiting until the moment it actually writes the heap dump. This is lowkey useful if the process changes user ID, or for debugging problems involving too many open filehandles.

---

👑 FUNCTIONS 👑

These functions are not exported — you have to call them fully-qualified. sorry bestie, that's just the rules.

🌟 dump

dump( $path );

Writes a heap dump to the named file.

🌟 dumpfh

dumpfh( $fh );

Writes a heap dump to the given filehandle. It has to be a plain OS-level filehandle, though — doesn't need to be a regular file, and it doesn't need to be seekable. slay.

---

💖 AUTHOR 💖

Paul Evans <leonerd@leonerd.org.uk>

---

that's the whole page bestie, hope it ate 🫶✨

perl v5.42.3 · 2026-08-19 — yeah this doc is stamped from way back then, still going strong 💅🎀