sigtrap(3perl)

💖 sigtrap — the Perl pragma from the Perl Programmers Reference Guide 💖

okay bestie, so this is sigtrap(3perl), and no cap, it's genuinely the easiest way to do signal handling in Perl. we're talking simple. we're talking cute little pragma energy. let's get into it 🫶

---

✨ NAME ✨

sigtrap — a Perl pragma that turns on simple signal handling, like, without you having to hand-write a single %SIG assignment.

---

🌸 SYNOPSIS 🌸

use sigtrap;
use sigtrap qw(stack-trace old-interface-signals);  # equivalent
use sigtrap qw(BUS SEGV PIPE ABRT);
use sigtrap qw(die INT QUIT);
use sigtrap qw(die normal-signals);
use sigtrap qw(die untrapped normal-signals);
use sigtrap qw(die untrapped normal-signals
                stack-trace any error-signals);
use sigtrap 'handler' => \&my_handler, 'normal-signals';
use sigtrap qw(handler my_handler normal-signals
                stack-trace error-signals);

look at that, use sigtrap; on its own and you're already cookin' 💅

---

🎀 DESCRIPTION 🎀

so the sigtrap pragma is basically a lil baby interface for installing signal handlers. you've got options, bestie:

• let it install one of the two handlers it ships with itself — one that gives you a Perl stack trace 🧚, and one that just plain die()s 💀
• OR supply your own handler and have sigtrap install that instead

and here's the fun part: you can tell it to install a handler only for signals that are either untrapped or ignored. like, "don't touch what's already handled, i'm not trying to be messy 🙈"

it has three lists of signals ready to go, plus you can absolutely pass your own list. main character energy, truly.

the arguments you pass to the use statement that invokes sigtrap are processed in order. so:

• when a signal name or the name of one of sigtrap's signal lists comes up → a handler gets installed immediately ⚡
• when an option comes up → it affects all the handlers installed after it

order matters, periodt.

---

👑 OPTIONS 👑

💖 SIGNAL HANDLERS

these options decide which handler gets used for the signals installed after them.

• stack-trace — the handler used for subsequently installed signals writes a Perl stack trace to STDERR and then tries to dump core. this is the default signal handler, iykyk.
• die — the handler used for subsequently installed signals calls die (well, actually croak) with a message telling you which signal got caught. dramatic AND informative.
• handler your-handler — your-handler becomes the handler for subsequently installed signals. your-handler can be any value that's valid as an assignment to an element of %SIG. wanna see examples of handler functions? go look at perlvar, bestie.

🦋 SIGNAL LISTS

sigtrap comes with a few built-in lists of signals to trap. here they are:

• normal-signals — the signals a program might normally expect to run into, and which by default cause it to terminate. they are HUP, INT, PIPE and TERM. very "this is just life" of them 🌈
• error-signals — these ones usually mean something has gone seriously wrong with the Perl interpreter or with your script. they are ABRT, BUS, EMT, FPE, ILL, QUIT, SEGV, SYS and TRAP. 😭
• old-interface-signals — the signals that the old sigtrap interface trapped by default. they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT, SEGV, SYS, TERM, and TRAP. and here's the tea: if you pass sigtrap no signals and no signal lists at all, this is the list it uses. no notes.

⚠️ for each of these three lists, the collection of signals set to be trapped is checked before trapping. so if your architecture doesn't implement a particular signal, it will not be trapped — it'll just be silently ignored. no error, no drama, it just doesn't happen 🙈

⭐ OTHER

• untrapped — this token tells sigtrap to install handlers only for the signals listed after it which aren't already trapped or ignored. respect the boundaries 💅
• any — this token tells sigtrap to install handlers for all signals listed after it. this is the default behavior.
• signal — any argument that looks like a signal name (that is, matching the regex /^[A-Z][A-Z0-9]*$/) means sigtrap should install a handler for that name. yes bestie, that's the whole check, look at the regex.
• number — requires that at least version number of sigtrap is being used. vibe check on the version fr fr.

---

🔥 EXAMPLES 🔥

give a stack trace for the old-interface-signals:

use sigtrap;

ditto (same thing, just spelled out):

use sigtrap qw(stack-trace old-interface-signals);

give a stack trace on the 4 listed signals only:

use sigtrap qw(BUS SEGV PIPE ABRT);

die on INT or QUIT:

use sigtrap qw(die INT QUIT);

die on HUP, INT, PIPE or TERM:

use sigtrap qw(die normal-signals);

die on HUP, INT, PIPE or TERM — except don't change the behavior for signals that are already trapped or ignored:

use sigtrap qw(die untrapped normal-signals);

die on receipt of any of the normal-signals that's currently untrapped, and provide a stack trace on receipt of any of the error-signals:

use sigtrap qw(die untrapped normal-signals
                stack-trace any error-signals);

install my_handler() as the handler for the normal-signals:

use sigtrap 'handler', \&my_handler, 'normal-signals';

install my_handler() as the handler for the normal-signals, and provide a Perl stack trace on receipt of one of the error-signals:

use sigtrap qw(handler my_handler normal-signals
                stack-trace error-signals);

---

🌈 SEE ALSO 🌈

okay so, technically this page didn't hand me a SEE ALSO section, so i'm not gonna invent one — but the DESCRIPTION does point you at perlvar for examples of handler functions, so go peek at that if you want the full handler inspo 💜

---

and that's the whole thing, bestie! you ate that 🍓

this was sigtrap(3perl) from perl v5.44.0, dated 2026-10-17. iconic behavior, honestly 👑✨💖