Section: User Contributed Perl Documentation (3pm)
IPC::Run::IO -- I/O channels for IPC::Run.
NOT IMPLEMENTED YET ON Win32! Win32 does not allow
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 );
$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( ... );
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
due to the awkwardness introduced in ripping pseudohashes
out of Perl, this class no longer
uses the fields pragma.
I think it takes >> or << along with some other data.
TODO: Needs more thorough documentation. Patches welcome.
Gets/sets the filename. Returns the value after the name change, if
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.
If this is a redirection IO object, this opens the pipe in a platform
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
> 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 ``mode'' if you want
to spell these 'r', 'w', etc.
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.
Returns the first character of $self->op. This is either ``<'' or ``>''.
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.
Barrie Slaymaker <email@example.com