Run::IO(3)

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

SYNOPSIS
   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, independant of anything else IPC::Run is doing (except that errors & exceptions can affect all things that IPC::Run is doing).

SUBCLASSING
This class uses the fields pragma, so you need to be aware of the contraints and strengths that this confers upon subclasses. See the the base manpage and the fields manpage pragmas for more information.

TODO
Implement bidirectionality.

AUTHOR
Barrie Slaymaker <barries@slaysys.com> Gets/sets the filename. Returns the value after the name change, if any. Does initialization required before this can be run. This includes open()ing the file, if necessary, and clearing the destination scalar if necessary. If a filename was passed in, opens it. Determines if the handle is open via fileno(). Throws an exception on error. Closes the handle. Throws an exception on failure. Returns the fileno of the handle. Throws an exception on failure. 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.
Returns the operation: '<', '>', '<<', '>>'. See the mode entry elsewhere in this document if you want to spell these 'r', 'w', etc.