WaitStat(3pm)

💖 WaitStat — the manual, but make it make sense 💖

okay bestie, gather round, because this is <rainbow>Proc::WaitStat</rainbow> and it is literally the module that translates those cursed wait() status numbers into something your brain can actually process. no cap. it's giving "small module, huge slay." ✨

---

🌸 NAME 🌸

Proc::WaitStat — interpret and act on wait() status values. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

$description = waitstat $?;
exit waitstat_reuse $?;
waitstat_die $?, 'program-name';
close_die COMMAND, 'program-name';

look at her. four lines. main character energy fr fr. 🎀

---

🦋 DESCRIPTION 🦋

so this module is a lil collection of functions for interpreting and acting on wait status values. that's it, that's the job, and she does it beautifully. 💖

heads up: nothing is exported by default. you gotta ask for what you want, no freeloaders. 🙈

💫 waitstat wait-status

returns a string representation of the wait() status value wait-status. the values it hands back look like "0" and "64" and "killed (SIGHUP)". so like, sometimes it's a number, sometimes it's a whole dramatic announcement that something got murked by a signal. iconic. 💀

this function is prototyped to take a single scalar argument.

💫 waitstat_reuse wait-status

turns wait-status into a value you can pass straight to exit, converted the same way the shell does it. here's the tea:

• if wait-status says it was a normal exit → it returns the exit value. 🫶
• if wait-status instead says death by signal → it returns 128 plus the signal number. (yes, the classic shell math. iykyk. 🔥)

this function is prototyped to take a single scalar argument.

💫 waitstat_die wait-status program-name

calls die() if wait-status is non-zero, and it name-drops program-name as the source of the error, so you know exactly who to blame. 😭

this function is prototyped to take two scalar arguments.

💫 close_die filehandle name

closes filehandle, and if that close fails, it calls die() with an appropriate message that refers to name. and bestie, the important part: this handles failed closings of both programs and files properly. both! it's not out here playing favourites. 👑

this function is prototyped to take a filehandle (actually, a glob ref) and a scalar.

---

🔥 EXAMPLES 🔥

okay this is the part where it all clicks, watch:

close SENDMAIL;
exit if $? == 0;
log "sendmail failure: ", waitstat $?;
exit EX_TEMPFAIL;

$pid == waitpid $pid, 0 or croak "Failed to reap $pid: $!";
exit waitstat_reuse $?;

$output = `some-program -with args`;
waitstat_die $?, 'some-program';
print "Output from some-process:\n", $output;

open PROGRAM, '| post-processor' or die "Can't fork: $!";
while (<IN>) {
    print PROGRAM pre_process $_
        or die "Error writing to post-processor: $!";
}
# This handles both flush failures at close time and a non-zero exit
# from the subprocess.
close_die PROGRAM, 'post-processor';

see how the last one is doing the absolute most? it handles both the flush failures that happen at close time and a non-zero exit from the subprocess. one function, two problems, zero stress. periodt. 💅✨

---

👑 AUTHOR 👑

Roderick Schertler <roderick@argon.org> — thank you king, we owe you one. 🫶

---

🌈 SEE ALSO 🌈

• perl(1)
• IPC::Signal(3pm)

go read those too, you'll be unstoppable. 💜

---

and that's the whole page, bestie!! this lil slice of documentation ships as part of perl v5.36.0, dated 2022-11-27 — so yeah, vintage but still eating. 🌸🎀 go waitstat something and slay. 💖🦋✨