IPC::Run::IO(3) User Contributed Perl Documentation IPC::Run::IO(3)

# [NAME](#NAME)

IPC::Run::IO -- I/O channels for IPC::Run.

# [SYNOPSIS](#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.**

```
   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( ... );
```

# [DESCRIPTION](#DESCRIPTION)

This class and module allows filehandles and filenames to be harnessed for I/O when used IPC::Run, independent of anything else IPC::Run is doing (except that errors & exceptions can affect all things that IPC::Run is doing).

# [SUBCLASSING](#SUBCLASSING)

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

# [SUBROUTINES](#SUBROUTINES)

[new](#new)

I think it takes &gt;&gt; or &lt;&lt; along with some other data.

TODO: Needs more thorough documentation. Patches welcome.

[filename](#filename)

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

[init](#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](#open)

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

[open\_pipe](#open_pipe)

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

[close](#close)

Closes the handle. Throws an exception on failure.

[fileno](#fileno)

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

[mode](#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.
    
```

[op](#op)

Returns the operation: '&lt;', '&gt;', '&lt;&lt;', '&gt;&gt;'. See "mode" if you want to spell these 'r', 'w', etc.

[binmode](#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](#dir)

Returns the first character of $self-&gt;op. This is either "&lt;" or "&gt;".

[poll](#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.

# [AUTHOR](#AUTHOR)

Barrie Slaymaker &lt;barries@slaysys.com&gt;

# [TODO](#TODO)

Implement bidirectionality.

2026-10-09 perl v5.44.0

---

Document: IPC::Run::IO(3pm) from perl-ipc-run 20260402.0-r2 (Chainguard OS)
Source: https://github.com/cpan-authors/IPC-Run