IPC-Run
view release on metacpan or search on metacpan
$h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR;
$in = "hello world\n";
finish $h;
print <OUT>;
print <ERR>;
close OUT;
close ERR;
causes two pipe to be created, with one end attached to cat's stdout
and stderr, respectively, and the other left open on OUT and ERR, so
that the script can manually
read(), select(), etc. on them. This is like
the behavior of IPC::Open2 and IPC::Open3.
**Win32**: The handle returned is actually a socket handle, so you can
use select() on it.
- Duplicating output descriptors: >&m, n>&m
This duplicates output descriptor number n (default is 1 if n is omitted)
from descriptor number m.
- Duplicating input descriptors: <&m, n<&m
This duplicates input descriptor number n (default is 0 if n is omitted)
from descriptor number m
- Closing descriptors: <&-, 3<&-
This closes descriptor number n (default is 0 if n is omitted). The
following commands are equivalent:
run \@cmd, \undef;
run \@cmd, '<&-';
run \@cmd, '<in.txt', '<&-';
Doing
run \@cmd, \$in, '<&-'; ## SIGPIPE recipe.
is dangerous: the parent will get a SIGPIPE if $in is not empty.
- Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&
The following pairs of commands are equivalent:
run \@cmd, '>&', \$out; run \@cmd, '>', \$out, '2>&1';
run \@cmd, '>&', 'out.txt'; run \@cmd, '>', 'out.txt', '2>&1';
etc.
File descriptor numbers are not permitted to the left or the right of
these operators, and the '&' may occur on either end of the operator.
The '&>pipe' and '>pipe&' variants behave like the '>pipe' operator, except
that both stdout and stderr write to the created pipe.
- Redirection Filters
Both input redirections and output redirections that use scalars or
subs as endpoints may have an arbitrary number of filter subs placed
between them and the child process. This is useful if you want to
receive output in chunks, or if you want to massage each chunk of
data sent to the child. To use this feature, you must use operator
syntax:
run(
\@cmd
'<', \&in_filter_2, \&in_filter_1, $in,
'>', \&out_filter_1, \&in_filter_2, $out,
);
This capability is not provided for IO handles or named files.
Two filters are provided by IPC::Run: appender and chunker. Because
these may take an argument, you need to use the constructor functions
new\_appender() and new\_chunker() rather than using \\& syntax:
run(
\@cmd
'<', new_appender( "\n" ), $in,
'>', new_chunker, $out,
);
## Just doing I/O
If you just want to do I/O to a handle or file you open yourself, you
may specify a filehandle or filename instead of a command in the harness
specification:
run io( "filename", '>', \$recv );
$h = start io( $io, '>', \$recv );
$h = harness \@cmd, '&', io( "file", '<', \$send );
## Options
Options are passed in as name/value pairs:
run \@cat, \$in, debug => 1;
If you pass the debug option, you may want to pass it in first, so you
can see what parsing is going on:
run debug => 1, \@cat, \$in;
- debug
Enables debugging output in parent and child. Debugging info is emitted
to the STDERR that was present when IPC::Run was first `use()`ed (it's
`dup()`ed out of the way so that it can be redirected in children without
having debugging output emitted on it).
# RETURN VALUES
harness() and start() return a reference to an IPC::Run harness. This is
blessed in to the IPC::Run package, so you may make later calls to
functions as members if you like:
$h = harness( ... );
Returns a list of child process IDs. See ["pid"](#pid) to get the PID of a
specific child process.
PIDs are available as soon as the harness has been started with ["start"](#start).
- is\_running
$h->is_running;
Returns true if the harness is currently running (i.e. after ["start"](#start) and
before ["finish"](#finish)), false otherwise.
- full\_path
$h->full_path;
Returns the full path to the executable of the first child process, as
resolved by searching `PATH` when the harness is started with ["start"](#start).
Returns undef if the first child is a code reference (not an external
command), or if the harness has not been started yet.
To get the full path of a particular child, do:
$h->full_path( 0 ); # first child's executable path
$h->full_path( 1 ); # second child's executable path
or
($h->full_paths)[0]
($h->full_paths)[1]
- full\_paths
Returns a list of full paths to the executables of all child processes.
Children that are code references (not external commands) will have `undef`
in the corresponding position.
- finished
$h->finished;
Returns true if the harness has been started and all child processes have
finished (i.e. `finish` has been called or the harness has run to
completion). Returns false otherwise, including when the harness has not
yet been started.
Unlike ["result"](#result) and ["full\_result"](#full_result), `finished` does not throw an
exception when the harness has not yet run -- it simply returns false.
This makes it safe to call at any point to test completion status.
my $h = harness(\@cmd);
$h->start;
# ... do other work, pump $h as needed ...
if ( $h->finished ) {
print "Exit code: ", $h->result(0), "\n";
}
# FILTERS
These filters are used to modify input our output between a child
process and a scalar or subroutine endpoint.
- binary
run \@cmd, ">", binary, \$out;
run \@cmd, ">", binary, \$out; ## Any TRUE value to enable
run \@cmd, ">", binary 0, \$out; ## Any FALSE value to disable
This is a constructor for a "binmode" "filter" that tells IPC::Run to keep
the carriage returns that would ordinarily be edited out for you (binmode
is usually off). This is not a real filter, but an option masquerading as
a filter.
It's not named "binmode" because you're likely to want to call Perl's binmode
in programs that are piping binary data around.
- new\_chunker
This breaks a stream of data in to chunks, based on an optional
scalar or regular expression parameter. The default is the Perl
input record separator in $/, which is a newline be default.
run \@cmd, '>', new_chunker, \&lines_handler;
run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler;
Because this uses $/ by default, you should always pass in a parameter
if you are worried about other code (modules, etc) modifying $/.
If this filter is last in a filter chain that dumps in to a scalar,
the scalar must be set to '' before a new chunk will be written to it.
As an example of how a filter like this can be written, here's a
chunker that splits on newlines:
sub line_splitter {
my ( $in_ref, $out_ref ) = @_;
return 0 if length $$out_ref;
return input_avail && do {
while (1) {
if ( $$in_ref =~ s/\A(.*?\n)// ) {
$$out_ref .= $1;
return 1;
}
my $hmm = get_more_input;
unless ( defined $hmm ) {
$$out_ref = $$in_ref;
$$in_ref = '';
return length $$out_ref ? 1 : 0;
}
return 0 if $hmm eq 0;
}
}
};
- new\_appender
This appends a fixed string to each chunk of data read from the source
scalar or sub. This might be useful if you're writing commands to a
child process that always must end in a fixed string, like "\\n":
return input_avail && do {
## process the input just gotten
1;
};
This technique allows input\_avail to return the undef or 0 that a
filter normally returns when there's no input to process. If a filter
stores intermediate values, however, it will need to react to an
undef:
my $got = input_avail;
if ( ! defined $got ) {
## No more input ever, flush internal buffers to $out_ref
}
return $got unless $got;
## Got some input, move as much as need be
return 1 if $added_to_out_ref;
- get\_more\_input
This is used to fetch more input in to the input variable. It 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.
`get_more_input` is usually used as part of a return expression,
see ["input\_avail"](#input_avail) for more information.
# TODO
These will be addressed as needed and as time allows.
Stall timeout.
Expose a list of child process objects. When I do this,
each child process is likely to be blessed into IPC::Run::Proc.
$kid->abort(), $kid->kill(), $kid->signal( $num\_or\_name ).
Write tests for /(full\_)?results?/ subs.
Currently, pump() and run() only work on systems where select() works on the
filehandles returned by pipe(). This does \*not\* include ActiveState on Win32,
although it does work on cygwin under Win32 (thought the tests whine a bit).
I'd like to rectify that, suggestions and patches welcome.
Likewise start() only fully works on fork()/exec() machines (well, just
fork() if you only ever pass perl subs as subprocesses). There's
some scaffolding for calling Open3::spawn\_with\_handles(), but that's
untested, and not that useful with limited select().
Support for `\@sub_cmd` as an argument to a command which
gets replaced with /dev/fd or the name of a temporary file containing foo's
output. This is like <(sub\_cmd ...) found in bash and csh (IIRC).
Allow multiple harnesses to be combined as independent sets of processes
in to one 'meta-harness'.
Allow a harness to be passed in place of an \\@cmd. This would allow
multiple harnesses to be aggregated.
Ability to add external file descriptors w/ filter chains and endpoints.
Ability to add timeouts and timing generators (i.e. repeating timeouts).
High resolution timeouts.
# Win32 LIMITATIONS
- argument-passing rules are program-specific
Win32 programs receive all arguments in a single "command line" string.
IPC::Run assembles this string so programs using [standard command line parsing
rules](https://docs.microsoft.com/en-us/cpp/cpp/main-function-command-line-args#parsing-c-command-line-arguments)
will see an `argv` that matches the array reference specifying the command.
Some programs use different rules to parse their command line. Notable examples
include `cmd.exe`, `cscript.exe`, and Cygwin programs called from non-Cygwin
programs. Use [IPC::Run::Win32Process](https://metacpan.org/pod/IPC%3A%3ARun%3A%3AWin32Process) to call these and other nonstandard
programs.
- batch files
Properly escaping a batch file argument depends on how the script will use that
argument, because some uses experience multiple levels of caret (escape
character) removal. Avoid calling batch files with arguments, particularly when
the argument values originate outside your program or contain non-alphanumeric
characters. Perl scripts and PowerShell scripts are sound alternatives. If you
do use batch file arguments, IPC::Run escapes them so the batch file can pass
them, unquoted, to a program having standard command line parsing rules. If the
batch file enables delayed environment variable expansion, it must disable that
feature before expanding its arguments. For example, if `foo.cmd` contains
`perl %*`, `run ['foo.cmd', @list]` will create a Perl process in which
`@ARGV` matches `@list`. Prepending a `setlocal enabledelayedexpansion` line
would make the batch file malfunction, silently. Another silent-malfunction
example is `run ['outer.bat', @list]` for `outer.bat` containing `foo.cmd
%*`.
- Fails on Win9X
If you want Win9X support, you'll have to debug it or fund me because I
don't use that system any more. The Win32 subsysem has been extended to
use temporary files in simple run() invocations and these may actually
work on Win9X too, but I don't have time to work on it.
- May deadlock on Win2K (but not WinNT4 or WinXPPro)
Spawning more than one subprocess on Win2K causes a deadlock I haven't
figured out yet, but simple uses of run() often work. Passes all tests
on WinXPPro and WinNT.
- no support yet for <pty< and >pty>
These are likely to be implemented as "<" and ">" with binmode on, not
sure.
- no support for file descriptors higher than 2 (stderr)
Win32 only allows passing explicit fds 0, 1, and 2. If you really, really need to pass file handles, us Win32API:: GetOsFHandle() or ::FdGetOsFHandle() to
get the integer handle and pass it to the child process using the command
line, environment, stdin, intermediary file, or other IPC mechanism. Then
use that handle in the child (Win32API.pm provides ways to reconstitute
Perl file handles from Win32 file handles).
( run in 0.788 second using v1.01-cache-2.11-cpan-524268b4103 )