---
name: "IPC::Run::IO"
section: "3pm"
platform: "linux"
package: "perl-ipc-run"
version: "20260402.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/IPC::Run::IO"
---

# IPC::Run::IO(3pm)

## NAME

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

## 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

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

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

## SUBROUTINES

- new

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

  TODO: Needs more thorough documentation. Patches welcome.

- 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.
  ```

- 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.

## AUTHOR

Barrie Slaymaker \<barries@slaysys.com\>

## TODO

Implement bidirectionality.