IPC::Run::IO(3)

🦋 hey bestie, welcome to IPC::Run::IO 🦋

okay so real talk — this page is part of the User Contributed Perl Documentation for Perl, and it's all about IPC::Run::IO, the little module that handles I/O channels for IPC::Run. it's giving plumbing but make it cute. let's get into it 💅

---

✨ NAME ✨

IPC::Run::IO — I/O channels for IPC::Run. that's the whole vibe. no cap. 💖

---

🌸 SYNOPSIS 🌸

NOT IMPLEMENTED YET ON Win32! Win32 does not allow select() on normal file descriptors; IPC::RUN::IO needs to use IPC::Run::Win32Helper to do this.

okay so like, fair warning before you fall in love: Win32 is not the moment here yet. moving on to the actual code, which is iconic and stays exactly as it is:

use IPC::Run qw( io );

## The sense of '>' and '<' is opposite of perl's open(),
## but agrees with IPC::Run.
$io = io( "filename", '>',  \$recv );
$io = io( "filename", 'r',  \$recv );

## Append to $recv:
$io = io( "filename", '>>', \$recv );
$io = io( "filename", 'ra', \$recv );

$io = io( "filename", '<',  \$send );
$io = io( "filename", 'w',  \$send );

$io = io( "filename", '<<', \$send );
$io = io( "filename", 'wa', \$send );

## Handles / IO objects that the caller opens:
$io = io( \*HANDLE,   '<',  \$send );

$f = IO::Handle->new( ... ); # Any subclass of IO::Handle
$io = io( $f, '<', \$send );

require IPC::Run::IO;
$io = IPC::Run::IO->new( ... );

## Then run(), harness(), or start():
run $io, ...;

## You can, of course, use io() or IPC::Run::IO->new() as an
## argument to run(), harness, or start():
run io( ... );

yes the > and < are flipped from what you'd expect from perl's open() — they agree with IPC::Run instead. it's a whole thing, iykyk. 🙈

---

🎀 DESCRIPTION 🎀

so basically this class and module lets filehandles and filenames get harnessed for I/O when you're using IPC::Run. and it does that independently of anything else IPC::Run is doing — except that errors & exceptions can affect all things that IPC::Run is doing. so like, the drama is shared. 😭💀

---

💜 SUBCLASSING 💜

INCOMPATIBLE CHANGE: due to the awkwardness introduced in ripping pseudohashes out of Perl, this class no longer uses the fields pragma.

periodt. that's the tea. 🍓

---

🔥 SUBROUTINES 🔥

👑 new

I think it takes >> or << along with some other data.

TODO: Needs more thorough documentation. Patches welcome.

literally the author said "patches welcome" — bestie if you know, you know, and if you know, share 🫶

filename

Gets/sets the filename. Returns the value after the name change, if any.

init

Does initialization required before this can be run. This includes open()ing the file, if necessary, and clearing the destination scalar if necessary.

open

If a filename was passed in, opens it. Determines if the handle is open via fileno(). Throws an exception on error.

open_pipe

If this is a redirection IO object, this opens the pipe in a platform independent manner.

close

Closes the handle. Throws an exception on failure.

fileno

Returns the fileno of the handle. Throws an exception on failure.

mode

Returns the operator in terms of 'r', 'w', and 'a'. There is a state 'ra', unlike Perl's open(), which indicates that data read from the handle or file will be appended to the output if the output is a scalar. This is only meaningful if the output is a scalar, it has no effect if the output is a subroutine.

The redirection operators can be a little confusing, so here's a reference table:

>      r      Read from handle in to process
<      w      Write from process out to handle
>>     ra     Read from handle in to process, appending it to existing
             data if the destination is a scalar.
<<     wa     Write from process out to handle, appending to existing
             data if IPC::Run::IO opened a named file.

save this table, it WILL save you 🌈

op

Returns the operation: '<', '>', '<<', '>>'. See "mode" if you want to spell these 'r', 'w', etc.

binmode

Sets/gets whether this pipe is in binmode or not. No effect off of Win32 OSs, of course, and on Win32, no effect after the harness is start()ed.

dir

Returns the first character of $self->op. This is either < or >.

poll

TODO: Needs confirmation that this is correct. Was previously undocumented.

I believe this is polling the IO for new input and then returns undef if there will never be any more input, 0 if there is none now, but there might be in the future, and TRUE if more input was gotten.

note the "I believe" bestie — even the docs are like "idk, probably?" 💀

---

💖 AUTHOR 💖

Barrie Slaymaker <barries@slaysys.com>

---

🎀 TODO 🎀

Implement bidirectionality.

bestie. BIDIRECTIONALITY. it's not there yet. manifesting it for you tho 🙏✨

---

and that's the whole page, no notes. this documentation shipped with perl v5.42.0, dated 2025-08-11 — so like, vintage-ish but still slaying. go open a filehandle and be the main character. 💅💜🦋