Test2:...il::IPC(3pm)

💖 NAME 💖

Test2::Harness::Util::IPC — bestie, it's literally just utilities for IPC management. That's the whole name, that's the whole job. (The page itself is filed under the manual name Test2:...il::IPC(3pm), which is just the long name getting squished by the terminal, iykyk.) 💅

---

🌸 DESCRIPTION 🌸

This package hands you the low-level IPC tools that Test2::Harness runs on. Like, the little plumbing bits under the sink of the whole operation. Not glamorous, but absolutely iconic. ✨

---

🦋 EXPORTS 🦋

Okay so listen — all exports are optional and you have to specify them at import time. No freebies, no auto-magic, you ask for what you want like a grown-up. 💖

• $bool = USE_P_GROUPS() — this is just a cute little shortcut for this exact thing right here:

use Config qw/%Config/;
$Config{'d_setpgrp'};

• swap_io($from, $to)
• swap_io($from, $to, \&die)

This one closes and re-opens the file handle designated by $from so it redirects to the handle in $to. The way it does this: it preserves the file descriptor in the process, and if it can't pull that off it throws an exception. Periodt.

swap_io(\*STDOUT, $fh);
# STDOUT now points to wherever $fh did, but maintains the file descriptor number '2'.

As long as the file descriptor is greater than 0 it opens for writing. If the descriptor is 0 it opens for reading instead, which means you can swap STDIN too. Slay. 🎀

Extra effort is genuinely made to make sure errors go to the real STDERR — especially when you're trying to swap out STDERR itself, which is the chaotic one. 🙈 If you have trouble with that, or you just don't trust it, you can hand it a custom coderef as the third argument, and that coderef gets used instead of die() to throw exceptions.

Not me warning you about this: the built-in custom die logic (the one you get when you don't provide your own) bypasses the exception catching mechanism and will exit your program. If that is not desirable, then bestie you need to provide a custom die subref. No cap. 💀

• $pid = run_cmd(command => [...], %params)

This function runs the command you specify and returns a pid to you. When possible it does this via fork() and exec(). When that is not possible it uses the system(1, ...) trick to spawn a new process instead. Heads up tho: some parameters do not work in the second case, and are silently ignored. They just vibe out and say nothing. 😭

⭐ Parameters ⭐

• command => [$command, sub { ... }, @args]
• command => sub { return ($command, @args) }

This parameter is required. No command, no party. 🚫🎉

It should either be an arrayref of arguments for exec(), or a coderef that returns a list of arguments for exec(). On systems without fork/exec, the arguments will be passed to system(1, $command, @args) instead.

And here's the fun bit: if the command arrayref has a coderef in it, that coderef will be run and its return value(s) will be inserted in its place. This replacement happens post-chroot. 🧚

• run_in_parent => [sub { ... }, sub { ... }] — an arrayref of callbacks to be run in the parent process, immediately after the child process is started.
• run_in_child => [sub { ... }, sub { ... }] — an arrayref of callbacks to be run in the child process, immediately after fork. This parameter is silently ignored on systems without fork/exec. 💅
• env => { ENVVAR => $VAL, ... } — a hashref of custom environment variables to set in the child process. In the fork/exec model this is done post-fork; in the spawn model this is done via local prior to the spawn. Same energy, different plumbing. 🌈
• no_set_pgrp => $bool, — normally setpgrp(0,0) is called on systems where it is supported. You can use this parameter to override the normal behavior. Fun fact: setpgrp() is not called in the spawn model at all, so this parameter is silently ignored there. 🙈
• chdir => 'path/to/dir'
• ch_dir => 'path/to/dir'

chdir() to the specified directory for the new process. In the fork/exec model this is done post-fork in the child. In the spawn model this is done before the spawn, and then a second chdir() puts the parent process back to its original dir after the spawn. Very "leave it how you found it" of it. 🫶

• stdout => $handle
• stderr => $handle
• stdin => $handle

These can be used to provide custom STDERR, STDOUT, and STDIN. In the fork/exec model these are swapped into place post-fork in the child. In the spawn model the swap occurs pre-spawn, then the old handles are swapped back post-spawn. Swap, slay, un-swap. ✨

---

👑 SOURCE 👑

The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/. Go look, it's giving open source main character energy. 🌟

---

🌈 MAINTAINERS 🌈

• Chad Granum <exodist@cpan.org>

---

🎀 AUTHORS 🎀

• Chad Granum <exodist@cpan.org>

---

💜 COPYRIGHT 💜

Copyright 2020 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/

---

okay that's the whole page bestie, you ate it, go forth and IPC responsibly 💖✨

perl v5.40.1 — 2026-05-10 — and yes, the manual name is literally Test2:...il::IPC(3pm), it got truncated by the terminal and we love it anyway 🦋