IPC-Run-20260402.0/000755 000765 000024 00000000000 15163535532 015022 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/LICENSE000644 000765 000024 00000001253 15163304337 016025 0ustar00todd.rinaldostaff000000 000000 This software is copyright (c) by Barrie Slaymaker, Eric Cholet, and Todd Rinaldo. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- References --- The full text of these licenses can be found in the following locations: GNU General Public License: https://www.gnu.org/licenses/gpl-1.0 Artistic License: https://opensource.org/licenses/Artistic-1.0 IPC-Run-20260402.0/Changelog000644 000765 000024 00000073103 15163534124 016634 0ustar00todd.rinaldostaff000000 000000 Revision history for Perl extension IPC::Run 20260402.0 Thu Apr 2 2026 Bug fixes: - GH #271, GH #164 - Detect undefined command in arrayref at harness parse time instead of deferring to start() (PR #272) - pipe_writer drops input when data is the string "0" due to redundant boolean test on input buffer (PR #264) - Callback filter evaluates return in list context to distinguish empty return from the string "0", preventing infinite loop on Win32 (PR #264) - GH #240 - Skip pty output assertions on BSD/Darwin due to known pty drain timing issues on short-lived children (PR #274) - Implement proper Windows command-line parsing per Microsoft C/C++ rules, fixing argument parsing failures with single-quoted strings containing whitespace (PR #273) Maintenance: - Add shebang to eg/synopsis_scripting (PR #275) 20260401.0 Wed Apr 1 2026 Bug fixes: - GH #240 - Require IO::Pty 1.25 which fixes stale pty slave fd after close_terminal in child, replacing defensive workarounds (PR #241, PR #266) - GH #237 - Close Win32IO socket/pipe handles explicitly in _cleanup to prevent handle leaks (PR #246) - GH #242 - Handle $SIG{PIPE} set to 'DEFAULT' in _select_loop instead of crashing (PR #244) - Handle $SIG{CHLD} set to '' or 'DEFAULT' in _select_loop (PR #262) - Fix PTYS typo in adopt() and missing TIMERS init in harness constructor (PR #260) - Handle PTY allocation failure gracefully in start() instead of dying with an unhelpful error (PR #267) - Correct Timer.pm POD typos, _parse_time error message, and remove redundant parse call (PR #251) - Prevent noexec probe from leaking TAP output in search_path_cache.t (PR #247) Improvements: - Correct broken POD links and code examples in documentation (PR #252) Maintenance: - Update GitHub URLs from toddr/IPC-Run to cpan-authors/IPC-Run (PR #263) - Replace GPL v2 full text with standard "same terms as Perl" license (PR #268) - Add AI policy document (PR #248) - Use File::Spec->devnull in autoflush.t for portability (PR #250) - Skip search_path_cache.t on noexec temp filesystems (PR #247) - Remove dead code from Run.pm (PR #266) 20260322.0 Sun Mar 22 2026 Bug fixes: - GH #126 - Handle EAGAIN in _write() for non-blocking pipe writes (PR #221) - GH #149 - Prevent fd leak in _do_kid_and_exit when TFD == KFD (PR #218) - GH #131 - Suppress spurious "Filehandle STDIN reopened" warnings in child when $^W=1 with pty redirection (PR #219) - GH #116 - Make binmode the default on Win32 to prevent newline mangling of binary data (PR #192) - GH #82 - Avoid undef warning in _cleanup when fork fails (PR #197) - GH #97 - Wrap coderef in eval in _do_kid_and_exit to prevent child process from escaping into parent code path on die() (PR #193) - GH #122 - Propagate CODE ref exceptions back to parent via error pipe (PR #224) - GH #57 - Close external input handles in parent after fork to prevent hangs when child exits early (PR #226) - GH #134 - Preserve $cur_kid when a Timer is encountered in harness(), fixing "No command before 'init'" errors (PR #187) - GH #124 - Restore compat for bare undef params in harness() (PR #190) - GH #141 - Passing undef as stdin/stdout/stderr no longer dies (PR #184) - GH #139 - Avoid "Modification of a read-only value" when passing undef stdin (PR #185) - GH #162 - Reject empty/undef command name in _search_path (PR #182) - GH #154 - Limit input buffer chunk size to prevent exponential memory growth when streaming data to slow consumers (PR #183) - GH #128 - Silently ignore undef arguments passed as timeout to harness() (PR #189) - GH #133 - Correct two minor documentation issues in Run.pm (PR #188) - GH #137 - Skip win32_compile.t when getprotobyname('tcp') is unavailable (PR #186) - GH #35 - Survive SIGPIPE when child exits before consuming all stdin (PR #204) - GH #92 - Handle EPIPE when child exits before consuming stdin (PR #195) - GH #93 - Handle tied STDERR without FILENO in _debug_fd (PR #194) - GH #85 - Invalidate path cache on $PATH change, add clearcache() (PR #196) - GH #50 - Support scalar ref for '>pipe' and '> 8, and full_result() was returning N. Programs having workarounds for this may need to condition those workarounds on $IPC::Run::VERSION. - #157 - On Windows, avoid hang under IPCRUNDEBUG. - Refresh "cpanfile" from Makefile.PL, to allow use on Windows. - #163 - Normalize shebangs to /usr/bin/perl - Fix or skip all tests recently seen to fail on Windows. - Include t/result.t in releases. - #168 - Make full_result() and result() Windows behavior match non-Windows. 20220807.0 Mon Aug 1 2022 If your applications rely on portability to Windows, see new documentation sections "argument-passing rules are program-specific" and "batch files". This release fixes bugs in runs of Windows programs that use standard command line parsing rules. Runs of non-standard programs may require changes. Notable non-standard programs include cmd.exe, cscript.exe, and Cygwin programs. - #140 - skip t/pty.t test on NetBSD too - Add strict/warnings - #142 - Follow Windows argument quoting rules - #146 - allow win32_newlines.t to actually run - #150 - Make t/pty.t test pass on OpenBSD. - #148 - Support Win32 commands having nonstandard command line parsing rules - Support executing Win32 batch files. - Add IPC::Run::Win32Process, for delivering nonstandard command lines. - Fix reporting of Win32::Process::Create() errors. - #156 - On Windows, avoid hang when closing read end of pipe. - #155 - Ignore known test failure on msys. - t/windows_search_path.t - Avoid warning with IPCRUNDEBUG, in Windows spawned children. - Use $^X, not 'perl', in tests. - Thanks to the New active developer: Noah Misch! 20200505.0 Tue May 5 2020 - #125 - Fix syntax errors in POD examples - #127 - Switch Readonly testing requirement to a recommends - #129 - Fix full_result to always return $? - #136 - kill_kill: Immediately KILL the child process as documented for Win32. - Switch to github actions for CI testing - Re-structure shipped files into eg - Move author tests into xt and test them separately. 20180523.0 Wed May 23 2018 - #99 - Fix using fd in child process when it happens to be the same number in the child as it was in the parent. 0.99 Fri Mar 30 2018 - Fixes for windows unit tests so they skip or pass. t/autoflush.t t/readonly.t t/run_stdin-callback-return-array.t 0.98 Thu Mar 29 2018 - Switch to using $!{EINTR} - Honor umask for user/group permissions on a +rw file - Remove commented code from RT 50739 - #63 - Patch for fixing _write on invalid objects - #54 - Make slave the controlling terminal so more programs can be called from IPC::Run reliably - #53 - Prevent Not a GLOB reference in close_terminal by untieing before close - #46 - '&' closing the stdin of the right process. - #41 - Do POSIX::_exit not ::exit - #40 - Assure child Win32 processes have same priority as parent - #38 - Add unit test for passing use of Readonly.pm - #39 - Fix GLOB test in IPC::Run::IO->new - #86 - Fix for memory leak [rt.cpan.org #57990] - MANIFEST was updated. New tests may start shipping now. 0.97 Mon Mar 26 2018 - Update meta and POD to point to GitHub issues not RT. - Update README with pod changes. - Fix variable name in synopsis - [Github #47] - Fix t/run.t to work on "perl in space" - [Github #100] 0.96 Fri May 12 2017 - Update bug tracker to https://github.com/toddr/IPC-Run/issues 0.95 Mon Apr 24 2017 - Spelling fixes - doc fix: full_result returns $?, not $? >> 8 - Fix check for reaped PID in reap_nb - Re-remove unnecessary use of UNIVERSAL 0.94_02 Thu Apr 14 2016 - Skip infinity test on perl below 5.8.9 0.94_01 Tue Apr 12 2016 - Enable Travis-CI integration for IPC::Run - Use q{} and qq{} to fix problems with quotation in cmd.exe - sync $VERSION across all files to address kwalitee - RT 109243 - Stop side affect of altering flushing of STDOUT and STDERR - CHILD_HANDLE should be closed with 'Close' to prevent a warning. - require Win32API::File on Windows - Better timer error message + an additional unit test - Catching previously non-detected malformed time strings - Let Timer accept all allowable perl numbers - allow the OS to choose the ephemeral port to use - Don't use version.pm to parse the perl version in Makefile.PL - perltidy - Do not import POSIX into local namespace (it's a memory hog) 0.94 Sun Dec 14 2014 - RT 100858 - Update License discrepancies. 0.93_01 Wed Dec 10 2014 - Many typo corrections from David Steinbrunner via github - RT 20105 - t/pty.t fails on Solaris 10 0.93 Wed Dec 10 2014 - RT 100711 - Add aggressive exit to t/signal.t after skip_all to prevent failures. - RT 97926 - Fix for run argument with spaces in path - skip t/win32_compile.t on Android - RT 86133 - TODO failing POD tests for IPC::Run 0.92 Thu Aug 30 2012 - Tests are good in dev version. Releasing to stable. 0.92_01 Wed 22 Aug 2012 - RT 59775 - Catching a signal during select() can lock up IPC::Run 0.91 Tue 14 Feb 2012 - Tests are good in dev version. Releasing to stable. 0.91_01 Mon 16 Jan 2012 - RT 57277 - Apply suggested 1 line fix for dev release to public. 0.90 Wed 29 Jun 2011 - RT 57277 - Add breaking test. No solution at present. - RT 68623 - disable parallel tests on windows - RT 43072 - Skip dragonfly platform on t/pty.t (hangs) - RT 14078 - run() miscalculates length of UTF-8 strings - RT 49693 - security patch for lib/IPC/Run/Win32IO.pm s/INADDR_ANY// - RT 38193 - Fix error detection on non-English operating systems - Add a blank doc entry for IPC::Run::Win32IO::poll to quiet windows pod parser errors - RT 57190 - handle PATH environment variable not being defined. WILL NOT default to '.' since UNIX would not do this and the program has been behaving the UNIX way to date. 0.89 Wed 31 Mar 2010 - Revert extended tests to require "oslo consensus" variables - http://use.perl.org/~Alias/journal/36128 - Add IO::Pty to META.yml requirement This has been inconsistently depended on over the years in META.yml 0.88 Tue 30 Mar 2010 - Missed dangling isa in IPC::Run::Debug - Fix retry for read of fh when I get "Resource temporarily unavailable." It was previously pounding on the file handle with no rest 200 times then giving up. On fast systems this wasn't long enough. I'm implementing select(undef, undef, 0.01) to provide a more consistent retry among hardware and os. - Fix POD indentation in IO.pm 0.87 Mon 29 Mar 2010 - Add doc type fixes - RT 56030 from carnil (Debian) - Remove recommends for AUTHOR only modules - add pod_coverage and simplify pod test. - document undocumented public subs with TODO and best guess as to what they do. - Explicitly recommend IO::Pty version number 1.08 0.86 Wed 24 Mar 2010 - Add all files to subversion for easier releases - bump version on ALL files to 86 0.85 Mon 22 Mar 2010 - Remove use UNIVERSAL. - RT 51509 - fix pod for Win32Helper - RT 51695 - Better PATHEXT logic bug if cmd_name contains periods - RT 50739 - Enhance tests for run.t for better diagnostics - RT 47630 0.84 Mon 13 Jul 2009 - Add darwin to the list of known-bad platforms 0.83 Fri 10 Jul 2009 - Switch from command.com to cmd.exe so we work on 2008 or newer. 0.82 Thu 18 Dec 2008 - Moving changes in 0.81_01 to a production release 0.81_01 Wed 15 Oct 2008 - This is the first in a series of refactoring test releases. - Removed Makefile.PL message noisily asking users to do CPAN Testers dirty work. - Simplified the Makefile.PL code a little. - Upgraded all tests to Test::More - Added a $VERSION for all modules - Adding some missing POD sections - Various other clean ups 0.80 (missing) - IPC::Run::IO now retries on certain "temporarily unavailable" errors. This should fix several reported issues with t/run.t, test 69. Many thanks to < Eric (at) Scratch Computing (.com) > for the patch! - Applied documentation patch from RT. - Fixed documentation to work with '<' redirect 0.79 Wed Jan 19 15:39:00 PST 2005 - New maintainer: Richard Soderberg - Resolved several RT tickets (4934, 8263, 8060, 8400, 8624, 5870, 4658, 8940, 1474, 4311) - Skip certain tests on AIX and OpenBSD as they deadlock otherwise - Applied AIX patch from ActiveState (#8263) - Fixed t/run.t on OS X (#8940) - Add check for EINTR to _read (#5870) - FreeBSD uses fds up to 4 by default, fixed tests to start at 5 (#8060) 0.78 Tue Mar 9 01:49:25 EST 2004 - Removed all pseudohashes - Require Win32::Process when on Win32 () - Retry the select() instead of croaking when EINTR occurs (Ilya Martynov, ilya a t iponweb.net) - This needs further testing and analysis, but works for the submitter. 0.77 Fri Sep 26 15:36:56 EDT 2003 - Non-binmoded pipes are now s/\r//g on Win32 - Passes all tests on WinXPPro and WinNT - Deadlocks somewhere shortly after process creation on Win2K in some cases 0.76 (missing) - Does not use pseudohashes for perls >= 5.9.0 (reported by several users, patch by Nicholas Clark ) - pumpable() is now exported (reported by fetko@slaysys.com) - pumpable() now more thorough in checking for a dead child (reported by fetko@slaysys.com) - it checks for reapable processes when all pipes to the process are paused - pumpable() now yields the processor when all pipes to - Distro layout improved: Run.pm and Run/... are now under lib/IPC/... 0.75 Tue Jan 28 11:33:40 EST 2003 - Fix a bug that was causing _pipe() to seem to fail when feeding 0.74 Thu May 23 09:24:57 EDT 2002 - Skip a set of pty tests that deadlock on freebsd. Reported and investigated by Rocco Caputo . perldoc t/pty.t for details. 0.73 Wed May 22 09:03:26 EDT 2002 - Improved Win32 PATH and PATHEXT search; original patch by Ron Savage 0.72 Thu May 9 10:25:55 EDT 2002 - Doc patch from daniel@danielgardner.org - Backport Win32Helper to 5.00503 (compilation of this is tested on Unix or it would not have been spotted, not even by Matt Sergeant matts@sergeant.org). 0.71 Mon May 6 09:04:18 EDT 2002 - Fix the pesky run/t check for specific error string (test 134 at the moment, bad file descriptor test) that keeps tripping up cpantesters 0.70 Fri Apr 26 10:15:13 EDT 2002 - Massive performance improvements on Win32 See IPC::Run::Win32Helper's optimize() documentation. - moved data pump routine to IPC::Run::Win32Pump, now it loads much faster. - Where reasonably safe to do so, temporary files are used instead of pipes+pumps. - Setting $ENV{IPCRUNDEBUG}="notopt" can help find opportunities for optimizing. See IPC::Run::Debug for details. - Added 'noinherit => 1' option (parsed like 'debug => "basic") to allow stdin, stdout, and stderr to not be inherited by the child. - Factored debugging out in to IPC::Run::Debug so Win32Pump.pm need not load IPC::Run to get it. - Debugging code can be compile-time optimized away by setting $ENV{IPCRUNDEBUG} = "none" (or 0) before IPC::Run::Debug is first loaded causes all _debug... code to be optimized away before runtime. - Moved some functionality from IPC::Run in to IPC::Run::IO to allow IPC::Run::Win32IO to alter IPC::Run's behavior. More of this should happen; IPC::Run has grown too bloaty. - All the hokey hacky "manual imports" of IPC::Run's old _debug...() functions has been replaced by "use IPC::Run::Debug". - All the hokey hacky "manual imports" of IPC::Run's Win32_MODE() constant has been replaced by importing it from IPC::Run. - Cleaned up IPC::Run::Win32*'s debugging levels a bit to unclutter "basic" and "data" debugging level output. - exception handling in _open_pipes no longer silently eats exceptions. 0.67 Fri Apr 19 12:14:02 EDT 2002 - remove _q from the examples in the POD - it was inconsistent (the examples had bugs) and didn't help readability. Spotted by B.Rowlingson@lancaster.ac.uk. 0.66 Wed Mar 27 07:42:27 EST 2002 - Really dumb down that bad file descriptor test last tweaked in 0.64; the CLI does not script well under internationalization. 0.65 (unreleased) - Mostly focused on Win32 - pass filehandles to pumpers by number on the command line to avoid - use 2 arg binmode to force socket handles into/out of binmode - improve t/binmode.t - TODO: test ^Z and \000 pass-through. 0.64 Wed Mar 13 11:04:23 EST 2002 - Fix a test that fails on AIX because it uses a different message for "Bad file descriptor". Reported by "Dave Gomboc" - If IO::Pty is loadable, require IO::Pty 1.00 or later. 0.63 Wed Feb 27 12:25:22 EST 2002 - the select loop will now poll (with logarithmic fallback) when all I/O is closed but we have children running. Problem report by "William R. Pearson" . 0.62 Tue Jan 1 16:40:54 EST 2002 - Have all children close all file descriptors opened by the parent harness, otherwise children of different harnesses can unwittingly keep open fds the parent closes, thus preventing other children from seeing them close. Reported by Blair Zajac . 0.61 Fri Dec 7 05:21:28 EST 2001 - Fix up signal.t to not fail due to printing not working quite right in signal handlers. Spotted in the wild by Blair Zajac . 0.6 Thu Dec 6 04:36:57 EST 2001 - Get binmode--(">", binary) and ("<", binary)--working on Win32. 0.56 Sun Dec 2 09:18:19 EST 2001 - IPC::Run now throws exceptions from the post-fork, pre-exec child process back to the parent process using an additional pipe. This pipe also is used to pause the parent until the child performs the exec(), so that (when a new version of IO::Pty implements it) pty creation can be completed before the parent tries to write to it. 0.55 Sat Dec 1 17:15:02 EST 2001 - Fixups to Win32 code to get it compiling ok (added t/win32_compile.t to ensure that Win32Helper.pm at least compiles Ok). - Minor tweak to deal with "_" in $IO::Pty::VERSION, which is "0.92_04", including quotes, in the current version. 0.54 Fri Nov 30 11:46:05 EST 2001 - Win32 SUPPORT!!!!! - Added support for env. var. IPCRUNDEBUG=1 (or 2, 3, 4) to make it easier for users to debug the test suite. - Adapt to IO::Pty 0.91, which creates slave fds in new(), forcing us to close them in the parent after the fork(). We don't check for IO::Pty's version number, perhaps we should (waiting for a response from Roland Giersig about what he intends, since this could affect all users of older IO::Ptys that upgrade). - Add a sleep(1) to allow the slave pty to be initted, otherwise a premature write() to the slave's input can be lost. This is a bogus hack, but IO::Pty 0.9x should fix it when it's released. - removed spurious use Errno qw( EAGAIN ), since this causes warnings with perl5.00505. Reported by Christian Jaeger (pflanze). - IPC::Run::start() now does a kill_kill() if called on an already started harness. This is needed on Win32 to pass the test suite, but it's also a nice thing. - The debug file descriptor is built by dup()ing STDERR in the parent and passing it to the kids. This keeps us from needing to worry about debugging info in the select() loop and removes unnecessary complications. Still needs a bit of work: it should be dup()ed in _open_pipes and its value should be stored in the harness, not a global. - child processes are now a little more clearly identified in debug output. - Some debugging messages are now clearer. - debugging is now almost ready to be compile-time optimized away. - "time since script start" is now shown when debugging. We should check to see if Time::HiRes is loaded and make this more accurate. - pipe opens are now down in Run::IO::open_pipe(). - map_fds won't complain about no open fds unnecessarily (which was rare, but still). - the debug fd is now determined per-harness, not globally. This requires a bit of a hack (since I don't want to require $harness->_debug everywhere _debug might be called), but it seems worthwhile. 0.5 Sat Nov 10 21:32:58 EST 2001 - confess() when undef passed to _exec() - Cleaned up some POD and code comments. - Added patch to make the write side of pipes & ptys that IPC::Run must write to be non-blocking. Added a test for pipes, but Boris reports that Solaris 8 something seems to still block in the pty case, though Linux does not, so I did not add a test for that case. Probably should add one and complain bitterly if it fails (rather than actually failing the tests) and ptys are used. Patch from Borislav Deianov . - Added a patch to invalidate the search path cache if the file is no longer executable, also from Borislav Deianov - Started implementation of an adopt() external call that would let you aggregate harnesses, and a t/adopt.t, but different children need to properly close all FDs: they're inheriting each other's FDs and not properly closing them. - Close $debug_fd in &sub coprocesses. - Document the problems with &sub coprocesses. - Fixed fork error return detection to actually work, spotted by Dave Mitchell . - Give errors if a path with a directory separator is passed in if the indicated filename does not exist, is not a file, or is not executable. They're unixish errors, but hey... - Allowed harness \@cmd, '>', $foo, timeout 10 ; to parse (it was mistakenly thinking I wanted to send output to the IPC::Run::Timer created by timeout(). - pumpable() now returns true if there are any kids left alive, so that timers may continue to run. - A timeout of 1 second is forced if there are no I/O pipes left open, so that the select loop won't hang in select() if there is no I/O to do. Perhaps should only do that if there are timers. - Added a signal() to send specified signals to processes. Chose this over the more traditional Unix kill() to avoid people thinking that kill() should kill off processes. - Added kill_kill() which does kill off processes and clean up the harness. Sends TERM then (if need be) waits and sends KILL. - timeouts now work. - Removed eval{}s from a few subs, we were being over protective. - Preserve pos() across updates to scalars we append to, so m//g matches will work. - Cleaned up the examples/ - Added abuse/ for (mostly user contributed) scripts that I can use as a manual regression test. Most/all are reflected in t/*.t, but not verbatim, so it's good to have to originals around in case they happen to trigger something t/*.t miss. - Cleaned up SYNOPSIS a bit: it was too scary. Still is, but less so. 0.44 Mon Oct 2 17:20:29 EDT 2000 - Commented out all code dealing with select()'s exception file descriptor mask. Exceptions are vaguely defined and until somebody asks for them I don't want to do anything automatic with them. Croaking on them was certainly a bad idea: FreeBSD and some other platforms raise an exception when a pipe is closed, even if there's data in the pipe. IPC::Run closes a pipe filehandle if it sees sysread() return an error or 0 bytes read. 0.43 Thu Aug 17 23:26:34 EDT 2000 - Added flushing of STDOUT and STDERR before fork()/spawn() so that the children won't inherit bufferloads of unflushed output. This seems to be automatic in 5.6.0, but can cause loads of grief in 5.00503. I wish there were a way to flush all open filehandles, like stdio's fflush( NULL ) ; 0.42 Thu Aug 17 23:26:34 EDT 2000 - Worked around pseudo-hash features not implemented in perl5.00503 - Deprecated passing hashes of options in favor of just passing name-value pairs. 0.41 (missing) - Added result, results, full_result, full_results. I added so many variations because I expect that result and full_result are the most likely to get a lot of use, but I wanted to be able to return a list as well, without misusing wantarray. 0.4 Thu Jun 15 14:59:22 EDT 2000 - Added IPC::Run::IO and IPC::Run::Timer, bunches of tests. IPC::Run can now do more than just run child processes. - Scribbled more documentation. Needs a good edit. - Fixed some minor bugs here and there. 0.34 Thu Jun 8 06:39:23 EDT 2000 - Fixed bug in t/pty.t that prevented it from noticing IO::Pty - Converted IPC::Run to use fields. 0.32 Thu Jun 8 06:15:17 EDT 2000 - Added warning about missing IO::Pty in MakeMaker.PL. Thought about making it a prerequisite, but it's not: IPC::Run can do pipes, etc, if it's not found, and IO::Pty is more unix-specific than IPC::Run is. What I'd really like is an 'ENABLERS' section to MakeMaker.PL that tells CPAN.pm to try to install it but not to stress if it can't. - t/pty.t skips all tests if require IO::Pty fails. 0.31 Tue Jun 6 01:54:59 EDT 2000 - t/pty.t should now report what was received when checking it against a regex. This is because 0.3's failing a few tests on ppc-linux and the ok( $out =~ /.../ ) ; wasn't giving me enough info. I chose the 1 arg form due to older perl dists' Test.pm not grokking ok( $out, qr// ) ;. I should really do this to t/*.t, but I'm tired. - Removed the misfired Run/Pty.pm from the dist. 0.3 Sat Jun 3 08:33:17 EDT 2000 - Changed spelling of '<|<' and '>|>' to 'pipe'. This is to make it less confusing (I hope), since '>|' is a valid construct in some shells with totally unrelated semantics, and I plan on adding it to IPC::Run if a noclobber option ever makes it in. - Added 'pty>' operators. 0.21 Fri Jun 2 12:49:08 EDT 2000 - Added some advice for dealing with obstinate children - Converted many methods to plain subs for simplicity & performance - Converted to using local $debug to control debugging status for simplicity's sake. Don't know about performance effects, since dynamic scope lookups can be slow. 0.2 Thu Jun 1 01:48:29 EDT 2000 - Undid the creation of a pipe when passing a \*FOO or an IO::Handle ref and added '<|<', \*IN and '>|>', \*OUT syntax instead. This was because some very subtle bugs might have occurred if \*FOO was left in the wrong opened/closed state before calling run(), start() or harness(). Now, \*FOO must be open before the start() call, and '<|<' and '>|>' will close \*IN or \*OUT (or whatever) and open a pipe on it. This is analogous to IPC/Open{2,3}.pm behaviors. - Added eg/factorial_scalar and eg/runsh. Rewrote eg/factorial_pipe. - Fixed bug that was preventing input scalar refs (ie input for the child process) from ever being read from a second time. This caused pump() to hang. - Cleaned up calculation and use of timeout values so that when select() times out, it isn't called again. It's now adding one second to the timeout value because time() resolution is 1 second and we want to guarantee a minimum timeout even when we sample the start time at the end of a second - minor name changes to some field names to make the code marginally less obscure. - Fixed the MakeMaker settings and the directory layout so "make install" actually works. 0.1 Tue Apr 25 22:10:07 2000 - Initial release IPC-Run-20260402.0/MANIFEST000644 000765 000024 00000003021 15163535532 016147 0ustar00todd.rinaldostaff000000 000000 AI_POLICY.md Changelog eg/abuse/blocking_debug_with_sub_coprocess eg/abuse/blocking_writes eg/abuse/broken_pipe_on_bad_executable_name eg/abuse/timers eg/factorial eg/factorial_pipe eg/factorial_scalar eg/run_daemon eg/runsh eg/runsu eg/synopsis_scripting lib/IPC/Run.pm lib/IPC/Run/Debug.pm lib/IPC/Run/IO.pm lib/IPC/Run/Timer.pm lib/IPC/Run/Win32Helper.pm lib/IPC/Run/Win32IO.pm lib/IPC/Run/Win32Process.pm lib/IPC/Run/Win32Pump.pm LICENSE Makefile.PL MANIFEST This list of files MANIFEST.SKIP README.md t/accessors.t t/adopt.t t/adopt_ptys.t t/autoflush.t t/autovivifyfh.t t/binmode.t t/bogus.t t/child_fd_inadvertently_closed.t t/close_stdin.t t/early_exit.t t/eintr.t t/false_string_input.t t/filter.t t/finished.t t/gh_57_external_pipe_child_dies.t t/harness.t t/input_buffer_growth.t t/io.t t/kill_kill.t t/large_write.t t/lib/Test.pm t/parallel.t t/parent_and_child_fds_match.t t/pty.t t/pty_error_handling.t t/pump.t t/readonly.t t/result.t t/result_sigchld.t t/run.t t/run_stdin-callback-return-array.t t/scalar_ref_pipe.t t/search_path_cache.t t/sigchld_empty_handler.t t/signal.t t/started.t t/tied_stderr.t t/timeout.t t/timer.t t/undef_args.t t/undef_as_timeout.t t/undef_params.t t/utf8.t t/win32_compile.t t/win32_newlines.t t/win32_no_tempdir_handle_inheritance.t t/win32_parse.t t/windows_search_path.t xt/98_pod.t xt/98_pod_coverage.t xt/99_perl_minimum_version.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) IPC-Run-20260402.0/AI_POLICY.md000644 000765 000024 00000013036 15163275321 016714 0ustar00todd.rinaldostaff000000 000000 # AI Policy > **TL;DR** — AI tools assist our workflow at every stage. Humans remain in control of every decision, every review, and every release. --- ## Overview This document describes how artificial intelligence tools are used in the maintenance and development of this project. It is intended to be transparent with our contributors, users, and the broader open-source community about the role AI plays — and, equally importantly, the role it does **not** play. We believe in honest, clear communication about AI-assisted workflows. This policy will be updated as our practices evolve. --- ## Our Guiding Principle **AI assists. Humans decide.** The maintainers who have been stewarding this project for years remain fully responsible for every line of code that ships. AI tools extend our capacity to review, research, and improve — they do not replace human judgment, expertise, or accountability. --- ## How AI Is Used in This Project ### 1. Code and Issue Analysis AI tools help us process and understand incoming issues, pull requests, and code changes at scale. This includes: - Summarising issue reports and identifying patterns across similar bugs - Analysing code diffs for potential problems, regressions, or style inconsistencies - Surfacing relevant context from the codebase, documentation, and prior discussions - Flagging potential security concerns for human review This analysis is **always** used as input to human decision-making, never as a substitute for it. ### 2. Draft Pull Requests AI may generate draft pull requests as a starting point for a fix, a refactor, or an improvement. These drafts: - Are clearly labelled as AI-generated when created - Represent a first pass only — they are never considered complete or correct without human review - May be substantially reworked, rejected, or replaced entirely by maintainers Think of these drafts the way you would think of a junior contributor's first attempt: useful raw material that still needs experienced eyes. ### 3. Human Review of Every Pull Request **Every pull request — whether AI-drafted or human-authored — is reviewed by a human maintainer before it can be merged.** During review, maintainers actively use AI as a tool to assist their own thinking: - Asking AI to explain or justify specific implementation choices - Challenging AI-generated code and requesting alternative approaches - Using AI to research edge cases, relevant standards, or upstream behaviour - Requesting targeted rewrites of individual sections based on review feedback The maintainer's judgment always takes precedence. AI answers are treated as input to be verified, not conclusions to be accepted. ### 4. Test Coverage and Defect Detection AI helps us improve the quality and completeness of our test suite by: - Suggesting test cases for edge conditions and failure modes - Identifying gaps in existing test coverage - Proposing tests that target known classes of defects or security issues - Helping reproduce and characterise reported bugs All suggested tests are reviewed and validated by maintainers before being committed. ### 5. Security Review AI tools assist in identifying potential security issues, including: - Common vulnerability patterns (injection, insecure defaults, deprecated APIs, etc.) - Dependencies with known CVEs - Code paths that may warrant closer scrutiny Security findings from AI are **always** verified by a human maintainer. We do not act on AI-flagged security issues without independent assessment. --- ## What AI Does Not Do To be explicit about the limits of AI involvement in this project: | ❌ AI does not… | ✅ A human maintainer does… | |---|---| | Approve or merge pull requests | Review and decide on every PR | | Make architectural decisions | Own all design and direction choices | | Triage and close issues autonomously | Assess and respond to all issues | | Publish releases | Tag, build, and release manually | | Represent the project publicly | Communicate on behalf of the project | --- ## Releases Releases are performed manually by the same long-standing maintainers as always. The release process — including changelog review, version tagging, and publication — uses standard Perl ecosystem tooling (e.g. ExtUtils::MakeMaker, Dist::Zilla, Module::Build) but involves no AI-driven automation. Every release is initiated, supervised, and published by a human maintainer. AI may assist in drafting changelogs or release notes, but these are always reviewed and edited before publication. --- ## Attribution and Transparency Where AI has played a material role in generating code or content within a pull request, we aim to note this in the PR description (e.g. via a `Generated-By` or `AI-Assisted` label or note). We do not consider AI the author of any contribution — the maintainer who reviewed and approved the work takes responsibility for it. --- ## Why We Do This Open-source software is built on trust. Our users and downstream dependants trust us to ship correct, secure, and well-considered code. AI tools help us do that work better — but they do not change who is responsible for the outcome. We use AI because it makes our maintainers more effective, not because it replaces them. --- ## Questions and Feedback If you have questions about our use of AI, or concerns about a specific pull request or change, please open an issue or start a discussion. We are committed to being open about our process. --- *Last updated: 2026-03-23* *This policy is maintained by the project maintainers and subject to revision as AI tooling and community norms evolve.* IPC-Run-20260402.0/t/000755 000765 000024 00000000000 15163535532 015265 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/xt/000755 000765 000024 00000000000 15163535532 015455 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/README.md000644 000765 000024 00000232430 15163534170 016302 0ustar00todd.rinaldostaff000000 000000 [![testsuite](https://github.com/cpan-authors/IPC-Run/actions/workflows/testsuite.yml/badge.svg)](https://github.com/cpan-authors/IPC-Run/actions/workflows/testsuite.yml) # NAME IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32) # SYNOPSIS ## First,a command to run: my @cat = qw( cat ); ## Using run() instead of system(): use IPC::Run qw( run timeout ); run \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?"; # Can do I/O to sub refs and filenames, too: run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?"; run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt"; # Redirecting using pseudo-terminals instead of pipes. run \@cat, 'pty>', \$out_and_err; ## Scripting subprocesses (like Expect): use IPC::Run qw( start pump finish timeout ); # Incrementally read from / write to scalars. # $in is drained as it is fed to cat's stdin, # $out accumulates cat's stdout # $err accumulates cat's stderr # $h is for "harness". my $h = start \@cat, \$in, \$out, \$err, timeout( 10 ); $in .= "some input\n"; pump $h until $out =~ /input\n/g; $in .= "some more input\n"; pump $h until $out =~ /\G.*more input\n/; $in .= "some final input\n"; finish $h or die "cat returned $?"; warn $err if $err; print $out; ## All of cat's output # Piping between children run \@cat, '|', \@gzip; # Multiple children simultaneously (run() blocks until all # children exit, use start() for background execution): run \@foo1, '&', \@foo2; # Calling \&set_up_child in the child before it executes the # command (only works on systems with true fork() & exec()) # exceptions thrown in set_up_child() will be propagated back # to the parent and thrown from run(). run \@cat, \$in, \$out, init => \&set_up_child; # Read from / write to file handles you open and close open IN, 'out.txt' or die $!; print OUT "preamble\n"; run \@cat, \*IN, \*OUT or die "cat returned $?"; print OUT "postamble\n"; close IN; close OUT; # Create pipes for you to read / write (like IPC::Open2 & 3). $h = start \@cat, 'pipe', \*OUT, '2>pipe', \*ERR or die "cat returned $?"; print IN "some input\n"; close IN; print , ; finish $h; # Mixing input and output modes run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG; # Other redirection constructs run \@cat, '>&', \$out_and_err; run \@cat, '2>&1'; run \@cat, '0<&3'; run \@cat, '<&-'; run \@cat, '3<', \$in3; run \@cat, '4>', \$out4; # etc. # Passing options: run \@cat, 'in.txt', debug => 1; # Call this system's shell, returns TRUE on 0 exit code # THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE run "cat a b c" or die "cat returned $?"; # Launch a sub process directly, no shell. Can't do redirection # with this form, it's here to behave like system() with an # inverted result. $r = run "cat a b c"; # Read from a file in to a scalar run io( "filename", 'r', \$recv ); run io( \*HANDLE, 'r', \$recv ); # DESCRIPTION IPC::Run allows you to run and interact with child processes using files, pipes, and pseudo-ttys. Both system()-style and scripted usages are supported and may be mixed. Likewise, functional and OO API styles are both supported and may be mixed. Various redirection operators reminiscent of those seen on common Unix and DOS command lines are provided. # SIMPLE QUICKSTART Here's a quick guide to basic usage of using IPC::Run's `run()` function. ## Capturing output and errors from an external command Say you want to run a command in your shell. We'll use `ls` for simplicity, although there are far better ways to get a list of files, such as the `glob()` function or the [File::Find](https://metacpan.org/pod/File%3A%3AFind) module. The basic form of `run()` has the command and its arguments passed as an arrayref in the first argument. The command cannot be a single string. @cmd = [ 'ls', '-a', '-l', '-r', '-t' ]; # Yes @cmd = ( 'ls -a -l -r -t' ); # No After the command, pass a scalar reference `\$in` for the input to pass in, and scalar references `\$out` and `\$err` to receive the content of stdout and stderr. use IPC::Run qw( run ); @cmd = qw( ls -l -a -r -t ); run( \@cmd, \$in, \$out, \$err ) or die $?; print("\$err is ", length($err), " bytes long\n"); print($err, "\n"); print("\$out is ", length($out), " bytes long\n"); print($out, "\n"); Running this will show something like: $err is 0 bytes long $out is 1410 bytes long total 392 drwxr-xr-x 3 andy staff 96 Mar 17 11:53 .github -rw-r--r-- 1 andy staff 158 Mar 17 11:53 .gitignore ... etc ... Note that `$out` and `$err` are always defined after a call to `run()`, even if they receive no data. ## Passing input to the external program If you have input to pass in, put it in the `$in` variables. For example, to use the `wc` command to count lines, words and characters in a block of text: $in = <<'CARROLL'; 'Twas brillig, and the slithy toves Did gyre and gimble in the wabe: All mimsy were the borogoves, And the mome raths outgrabe. CARROLL @cmd = qw( wc ); run( \@cmd, \$in, \$out, \$err ) or die $?; print "$out"; This gives the output: 4 23 140 ## Handling errors It's important to check the return code of `run()` to see if the command ran successfully. `run()` returns a boolean true on success, and false on failure. Note that this is the opposite of Perl's `system()`, which returns 0 on success and a non-zero value on failures. For the specific subprocess error code, check `$?` directly. @cmd = qw( tar xzvf nonexistent.tar ); if ( !run( \@cmd, \$in, \$out, \$err ) ) { print "\$? = $?\n"; print "err = $err\n"; } Running this gives: $? = 256 err = tar: Error opening archive: Failed to open 'nonexistent.tar' If the program does not exist, then `run()` will `die` and won't return at all. For example: @cmd = qw( bogus-command ); my $rc = run( \@cmd, \$in, \$out, \$err ); print "run returned ", ($rc ? "true" : "false"), "\n"; Running this doesn't make it to the `print` statement. Command 'bogus-command' not found in [ list of paths ] at program.pl line N. To handle the possibility of a non-existent program, call `run()` inside an `eval`. my $rc; eval { $rc = run( \@cmd, \$in, \$out, \$out ); 1; }; if ( !defined($rc) ) { print "run died: $@\n"; } else { if ( $rc ) { print "run returned true\n"; } else { print "run returned false\n"; print "\$? = $?\n"; } } ## And beyond That's the basics of using `run()` as a replacement for `system()`. If you'd like to do more, such as having subprocesses communicate with each other, setting timeouts on long-running processes, kill running subprocesses, redirecting output, closing file descriptors and much much MUCH more, read on. # THE DETAILS Before digging in to the details a few LIMITATIONS are important enough to be mentioned right up front: - Win32 Support Win32 support is working but **EXPERIMENTAL**, but does pass all relevant tests on NT 4.0. See ["Win32 LIMITATIONS"](#win32-limitations). - pty Support If you need pty support, IPC::Run should work well enough most of the time, but IO::Pty is being improved, and IPC::Run will be improved to use IO::Pty's new features when it is released. The basic problem is that the pty needs to initialize itself before the parent writes to the master pty, or the data written gets lost. So IPC::Run does a sleep(1) in the parent after forking to (hopefully) give the child a chance to run. This is a kludge that works well on non heavily loaded systems :(. ptys are not supported yet under Win32, but will be emulated... - Debugging Tip You may use the environment variable `IPCRUNDEBUG` to see what's going on under the hood: $ IPCRUNDEBUG=basic myscript # prints minimal debugging $ IPCRUNDEBUG=data myscript # prints all data reads/writes $ IPCRUNDEBUG=details myscript # prints lots of low-level details $ IPCRUNDEBUG=gory myscript # (Win32 only) prints data moving through # the helper processes. ## Harnesses Child processes and I/O handles are gathered in to a harness, then started and run until the processing is finished or aborted. ## run() vs. start(); pump(); finish(); There are two modes you can run harnesses in: run() functions as an enhanced system(), and start()/pump()/finish() allow for background processes and scripted interactions with them. When using run(), all data to be sent to the harness is set up in advance (though one can feed subprocesses input from subroutine refs to get around this limitation). The harness is run and all output is collected from it, then any child processes are waited for: run \@cmd, \<pump until $out =~ /^smb.*> \Z/m; die "error cding to /src:\n$out" if $out =~ "ERR"; $out = ''; $in = "mget *\n"; $h->pump until $out =~ /^smb.*> \Z/m; die "error retrieving files:\n$out" if $out =~ "ERR"; $in = "quit\n"; $h->finish; Notice that we carefully clear $out after the first command/response cycle? That's because IPC::Run does not delete $out when we continue, and we don't want to trip over the old output in the second command/response cycle. Say you want to accumulate all the output in $out and analyze it afterwards. Perl offers incremental regular expression matching using the `m//gc` and pattern matching idiom and the `\G` assertion. IPC::Run is careful not to disturb the current `pos()` value for scalars it appends data to, so we could modify the above so as not to destroy $out by adding a couple of `/gc` modifiers. The `/g` keeps us from tripping over the previous prompt and the `/c` keeps us from resetting the prior match position if the expected prompt doesn't materialize immediately: $h = harness \@smbclient, \$in, \$out; $in = "cd /src\n"; $h->pump until $out =~ /^smb.*> \Z/mgc; die "error cding to /src:\n$out" if $out =~ "ERR"; $in = "mget *\n"; $h->pump until $out =~ /^smb.*> \Z/mgc; die "error retrieving files:\n$out" if $out =~ "ERR"; $in = "quit\n"; $h->finish; analyze( $out ); When using this technique, you may want to preallocate $out to have plenty of memory or you may find that the act of growing $out each time new input arrives causes an `O(length($out)^2)` slowdown as $out grows. Say we expect no more than 10,000 characters of input at the most. To preallocate memory to $out, do something like: my $out = "x" x 10_000; $out = ""; `perl` will allocate at least 10,000 characters' worth of space, then mark the $out as having 0 length without freeing all that yummy RAM. ## Timeouts and Timers More than likely, you don't want your subprocesses to run forever, and sometimes it's nice to know that they're going a little slowly. Timeouts throw exceptions after a some time has elapsed, timers merely cause pump() to return after some time has elapsed. Neither is reset/restarted automatically. Timeout objects are created by calling timeout( $interval ) and passing the result to run(), start() or harness(). The timeout period starts ticking just after all the child processes have been fork()ed or spawn()ed, and are polled for expiration in run(), pump() and finish(). If/when they expire, an exception is thrown. This is typically useful to keep a subprocess from taking too long. If a timeout occurs in run(), all child processes will be terminated and all file/pipe/ptty descriptors opened by run() will be closed. File descriptors opened by the parent process and passed in to run() are not closed in this event. If a timeout occurs in pump(), pump\_nb(), or finish(), it's up to you to decide whether to kill\_kill() all the children or to implement some more graceful fallback. No I/O will be closed in pump(), pump\_nb() or finish() by such an exception (though I/O is often closed down in those routines during the natural course of events). Often an exception is too harsh. timer( $interval ) creates timer objects that merely prevent pump() from blocking forever. This can be useful for detecting stalled I/O or printing a soothing message or "." to pacify an anxious user. Timeouts and timers can both be restarted at any time using the timer's start() method (this is not the start() that launches subprocesses). To restart a timer, you need to keep a reference to the timer: ## Start with a nice long timeout to let smbclient connect. If ## pump or finish take too long, an exception will be thrown. my $h; eval { $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 ); sleep 11; # No effect: timer not running yet start $h; $in = "cd /src\n"; pump $h until ! length $in; $in = "ls\n"; ## Now use a short timeout, since this should be faster $t->start( 5 ); pump $h until ! length $in; $t->start( 10 ); ## Give smbclient a little while to shut down. $h->finish; }; if ( $@ ) { my $x = $@; ## Preserve $@ in case another exception occurs $h->kill_kill; ## kill it gently, then brutally if need be, or just ## brutally on Win32. die $x; } Timeouts and timers are _not_ checked once the subprocesses are shut down; they will not expire in the interval between the last valid process and when IPC::Run scoops up the processes' result codes, for instance. ## Spawning synchronization, child exception propagation start() pauses the parent until the child executes the command or CODE reference and propagates any exceptions thrown (including exec() failure) back to the parent. This has several pleasant effects: any exceptions thrown in the child, including exec() failure, come flying out of start() or run() as though they had occurred in the parent. This includes exceptions your code thrown from init subs. In this example: eval { run \@cmd, init => sub { die "blast it! foiled again!" }; }; print $@; the exception "blast it! foiled again" will be thrown from the child process (preventing the exec()) and printed by the parent. In situations like run \@cmd1, "|", \@cmd2, "|", \@cmd3; @cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before @cmd3. This can save time and prevent oddball errors emitted by later commands when earlier commands fail to execute. Note that IPC::Run doesn't start any commands unless it can find the executables referenced by all commands. These executables must pass both the `-f` and `-x` tests described in [perlfunc](https://metacpan.org/pod/perlfunc). Another nice effect is that init() subs can take their time doing things and there will be no problems caused by a parent continuing to execute before a child's init() routine is complete. Say the init() routine needs to open a socket or a temp file that the parent wants to connect to; without this synchronization, the parent will need to implement a retry loop to wait for the child to run, since often, the parent gets a lot of things done before the child's first timeslice is allocated. This is also quite necessary for pseudo-tty initialization, which needs to take place before the parent writes to the child via pty. Writes that occur before the pty is set up can get lost. A final, minor, nicety is that debugging output from the child will be emitted before the parent continues on, making for much clearer debugging output in complex situations. The only drawback I can conceive of is that the parent can't continue to operate while the child is being initted. If this ever becomes a problem in the field, we can implement an option to avoid this behavior, but I don't expect it to. **Win32**: executing CODE references isn't supported on Win32, see ["Win32 LIMITATIONS"](#win32-limitations) for details. ## Syntax run(), start(), and harness() can all take a harness specification as input. A harness specification is either a single string to be passed to the systems' shell: run "echo 'hi there'"; or a list of commands, io operations, and/or timers/timeouts to execute. Consecutive commands must be separated by a pipe operator '|' or an '&'. External commands are passed in as array references or [IPC::Run::Win32Process](https://metacpan.org/pod/IPC%3A%3ARun%3A%3AWin32Process) objects. On systems supporting fork(), Perl code may be passed in as subs: run \@cmd; run \@cmd1, '|', \@cmd2; run \@cmd1, '&', \@cmd2; run \&sub1; run \&sub1, '|', \&sub2; run \&sub1, '&', \&sub2; '|' pipes the stdout of \\@cmd1 the stdin of \\@cmd2, just like a shell pipe. '&' does not. Child processes to the right of a '&' will have their stdin closed unless it's redirected-to. [IPC::Run::IO](https://metacpan.org/pod/IPC%3A%3ARun%3A%3AIO) objects may be passed in as well, whether or not child processes are also specified: run io( "infile", ">", \$in ), io( "outfile", "<", \$in ); as can [IPC::Run::Timer](https://metacpan.org/pod/IPC%3A%3ARun%3A%3ATimer) objects: run \@cmd, io( "outfile", "<", \$in ), timeout( 10 ); Commands may be followed by scalar, sub, or i/o handle references for redirecting child process input & output: run \@cmd, \undef, \$out; run \@cmd, \$in, \$out; run \@cmd1, \&in, '|', \@cmd2, \*OUT; run \@cmd1, \*IN, '|', \@cmd2, \&out; This is known as succinct redirection syntax, since run(), start() and harness(), figure out which file descriptor to redirect and how. File descriptor 0 is presumed to be an input for the child process, all others are outputs. The assumed file descriptor always starts at 0, unless the command is being piped to, in which case it starts at 1. To be explicit about your redirects, or if you need to do more complex things, there's also a redirection operator syntax: run \@cmd, '<', \undef, '>', \$out; run \@cmd, '<', \undef, '>&', \$out_and_err; run( \@cmd1, '<', \$in, '|', \@cmd2, \$out ); Operator syntax is required if you need to do something other than simple redirection to/from scalars or subs, like duping or closing file descriptors or redirecting to/from a named file. The operators are covered in detail below. After each \\@cmd (or \\&foo), parsing begins in succinct mode and toggles to operator syntax mode when an operator (ie plain scalar, not a ref) is seen. Once in operator syntax mode, parsing only reverts to succinct mode when a '|' or '&' is seen. In succinct mode, each parameter after the \\@cmd specifies what to do with the next highest file descriptor. These File descriptor start with 0 (stdin) unless stdin is being piped to (`'|', \@cmd`), in which case they start with 1 (stdout). Currently, being on the left of a pipe (`\@cmd, \$out, \$err, '|'`) does _not_ cause stdout to be skipped, though this may change since it's not as DWIMerly as it could be. Only stdin is assumed to be an input in succinct mode, all others are assumed to be outputs. If no piping or redirection is specified for a child, it will inherit the parent's open file handles as dictated by your system's close-on-exec behavior and the $^F flag, except that processes after a '&' will not inherit the parent's stdin. Also note that $^F does not affect file descriptors obtained via POSIX, since it only applies to full-fledged Perl file handles. Such processes will have their stdin closed unless it has been redirected-to. If you want to close a child processes stdin, you may do any of: run \@cmd, \undef; run \@cmd, \""; run \@cmd, '<&-'; run \@cmd, '0<&-'; Redirection is done by placing redirection specifications immediately after a command or child subroutine: run \@cmd1, \$in, '|', \@cmd2, \$out; run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out; If you omit the redirection operators, descriptors are counted starting at 0. Descriptor 0 is assumed to be input, all others are outputs. A leading '|' consumes descriptor 0, so this works as expected. run \@cmd1, \$in, '|', \@cmd2, \$out; The parameter following a redirection operator can be a scalar ref, a subroutine ref, a file name, an open filehandle, or a closed filehandle. If it's a scalar ref, the child reads input from or sends output to that variable: $in = "Hello World.\n"; run \@cat, \$in, \$out; print $out; Scalars used in incremental (start()/pump()/finish()) applications are treated as queues: input is removed from input scalars, resulting in them dwindling to '', and output is appended to output scalars. This is not true of harnesses run() in batch mode. It's usually wise to append new input to be sent to the child to the input queue, and you'll often want to zap output queues to '' before pumping. $h = start \@cat, \$in; $in = "line 1\n"; pump $h; $in .= "line 2\n"; pump $h; $in .= "line 3\n"; finish $h; The final call to finish() must be there: it allows the child process(es) to run to completion and waits for their exit values. # OBSTINATE CHILDREN Interactive applications are usually optimized for human use. This can help or hinder trying to interact with them through modules like IPC::Run. Frequently, programs alter their behavior when they detect that stdin, stdout, or stderr are not connected to a tty, assuming that they are being run in batch mode. Whether this helps or hurts depends on which optimizations change. And there's often no way of telling what a program does in these areas other than trial and error and occasionally, reading the source. This includes different versions and implementations of the same program. All hope is not lost, however. Most programs behave in reasonably tractable manners, once you figure out what it's trying to do. Here are some of the issues you might need to be aware of. - fflush()ing stdout and stderr This lets the user see stdout and stderr immediately. Many programs undo this optimization if stdout is not a tty, making them harder to manage by things like IPC::Run. Many programs decline to fflush stdout or stderr if they do not detect a tty there. Some ftp commands do this, for instance. If this happens to you, look for a way to force interactive behavior, like a command line switch or command. If you can't, you will need to use a pseudo terminal ('<pty<' and '>pty>'). - false prompts Interactive programs generally do not guarantee that output from user commands won't contain a prompt string. For example, your shell prompt might be a '$', and a file named '$' might be the only file in a directory listing. This can make it hard to guarantee that your output parser won't be fooled into early termination of results. To help work around this, you can see if the program can alter its prompt, and use something you feel is never going to occur in actual practice. You should also look for your prompt to be the only thing on a line: pump $h until $out =~ /^\s?\z/m; (use `(?!\n)\Z` in place of `\z` on older perls). You can also take the approach that IPC::ChildSafe takes and emit a command with known output after each 'real' command you issue, then look for this known output. See new\_appender() and new\_chunker() for filters that can help with this task. If it's not convenient or possibly to alter a prompt or use a known command/response pair, you might need to autodetect the prompt in case the local version of the child program is different then the one you tested with, or if the user has control over the look & feel of the prompt. - Refusing to accept input unless stdin is a tty. Some programs, for security reasons, will only accept certain types of input from a tty. su, notable, will not prompt for a password unless it's connected to a tty. If this is your situation, use a pseudo terminal ('<pty<' and '>pty>'). - Not prompting unless connected to a tty. Some programs don't prompt unless stdin or stdout is a tty. See if you can turn prompting back on. If not, see if you can come up with a command that you can issue after every real command and look for its output, as IPC::ChildSafe does. There are two filters included with IPC::Run that can help with doing this: appender and chunker (see new\_appender() and new\_chunker()). - Different output format when not connected to a tty. Some commands alter their formats to ease machine parsability when they aren't connected to a pipe. This is actually good, but can be surprising. # PSEUDO TERMINALS On systems providing pseudo terminals under /dev, IPC::Run can use IO::Pty (available on CPAN) to provide a terminal environment to subprocesses. This is necessary when the subprocess really wants to think it's connected to a real terminal. ## CAVEATS Pseudo-terminals are not pipes, though they are similar. Here are some differences to watch out for. - Echoing Sending to stdin will cause an echo on stdout, which occurs before each line is passed to the child program. There is currently no way to disable this, although the child process can and should disable it for things like passwords. - Shutdown IPC::Run cannot close a pty until all output has been collected. This means that it is not possible to send an EOF to stdin by half-closing the pty, as we can when using a pipe to stdin. This means that you need to send the child process an exit command or signal, or run() / finish() will time out. Be careful not to expect a prompt after sending the exit command. - Command line editing Some subprocesses, notable shells that depend on the user's prompt settings, will reissue the prompt plus the command line input so far once for each character. - '>pty>' means '&>pty>', not '1>pty>' The pseudo terminal redirects both stdout and stderr unless you specify a file descriptor. If you want to grab stderr separately, do this: start \@cmd, 'pty>', \$out, '2>', \$err; - stdin, stdout, and stderr not inherited Child processes harnessed to a pseudo terminal have their stdin, stdout, and stderr completely closed before any redirection operators take effect. This casts off the bonds of the controlling terminal. This is not done when using pipes. Right now, this affects all children in a harness that has a pty in use, even if that pty would not affect a particular child. That's a bug and will be fixed. Until it is, it's best not to mix-and-match children. ## Redirection Operators Operator SHNP Description ======== ==== =========== <, N< SHN Redirects input to a child's fd N (0 assumed) >, N> SHN Redirects output from a child's fd N (1 assumed) >>, N>> SHN Like '>', but appends to scalars or named files >&, &> SHN Redirects stdout & stderr from a child process pty, N>pty S Like '>', but uses a pseudo-tty instead of a pipe N<&M Dups input fd N to input fd M M>&N Dups output fd N to input fd M N<&- Closes fd N pipe, N>pipe P Pipe opens H for caller to read, write, close. 'N' and 'M' are placeholders for integer file descriptor numbers. The terms 'input' and 'output' are from the child process's perspective. The SHNP field indicates what parameters an operator can take: S: \$scalar or \&function references. Filters may be used with these operators (and only these). H: \*HANDLE or IO::Handle for caller to open, and close N: "file name". P: \*HANDLE or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read and written to and closed by the caller (like IPC::Open3). - Redirecting input: \[n\]<, \[n\]<pipe, \[n\]<blocking\_pipe You can input the child reads on file descriptor number n to come from a scalar variable, subroutine, file handle, or a named file. If stdin is not redirected, the parent's stdin is inherited. run \@cat, \undef ## Closes child's stdin immediately or die "cat returned $?"; run \@cat, \$in; run \@cat, \<finish; `, \[n\]>>, \[n\]>&\[m\], \[n\]>pipe You can redirect any output the child emits to a scalar variable, subroutine, file handle, or file name. You can have &run truncate or append to named files or scalars. If you are redirecting stdin as well, or if the command is on the receiving end of a pipeline ('|'), you can omit the redirection operator: @ls = ( 'ls' ); run \@ls, \undef, \$out or die "ls returned $?"; run \@ls, \undef, \&out; ## Calls &out each time some output ## is received from the child's ## when undef is returned. run \@ls, \undef, '2>ls.err'; run \@ls, '2>', 'ls.err'; The two parameter form guarantees that the filename will not be interpreted as a redirection operator: run \@ls, '>', "&more"; run \@ls, '2>', ">foo\n"; You can pass file handles you've opened for writing: open( *OUT, ">out.txt" ); open( *ERR, ">err.txt" ); run \@cat, \*OUT, \*ERR; Passing a scalar reference and a code reference requires a little more work, but allows you to capture all of the output in a scalar or each piece of output by a callback: These two do the same things: run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } ); does the same basic thing as: run( [ 'ls' ], '2>', \$err_out ); The subroutine will be called each time some data is read from the child. The >pipe operator is different in concept than the other '>' operators, although its syntax is similar: $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR; $in = "hello world\n"; finish $h; print ; print ; 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, ', >&, &>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( ... ); $h->start; $h->pump; $h->finish; $h = start( .... ); $h->pump; ... Of course, using method call syntax lets you deal with any IPC::Run subclasses that might crop up, but don't hold your breath waiting for any. run() and finish() return TRUE when all subcommands exit with a 0 result code. **This is the opposite of perl's system() command**. All routines raise exceptions (via die()) when error conditions are recognized. A non-zero command result is not treated as an error condition, since some commands are tests whose results are reported in their exit codes. # ROUTINES - clearcache() Clears the cache of executable paths that IPC::Run maintains internally. IPC::Run caches the full path of each command it resolves via `$PATH` to avoid repeated filesystem searches. If you change `$PATH` at runtime (or install a new executable into a directory that is already on `$PATH`), call `clearcache()` to force IPC::Run to search `$PATH` again on the next run. local $ENV{PATH} = "/new/bin:$ENV{PATH}"; IPC::Run::clearcache(); run ['mycommand'], ...; The cache is also invalidated automatically whenever `$ENV{PATH}` changes between calls. - run Run takes a harness or harness specification and runs it, pumping all input to the child(ren), closing the input pipes when no more input is available, collecting all output that arrives, until the pipes delivering output are closed, then waiting for the children to exit and reaping their result codes. You may think of `run( ... )` as being like start( ... )->finish(); , though there is one subtle difference: run() does not set \\$input\_scalars to '' like finish() does. If an exception is thrown from run(), all children will be killed off "gently", and then "annihilated" if they do not go gently (in to that dark night. sorry). If any exceptions are thrown, this does a ["kill\_kill"](#kill_kill) before propagating them. - signal ## To send it a specific signal by name ("USR1"): signal $h, "USR1"; $h->signal ( "USR1" ); If $signal is provided and defined, sends a signal to all child processes. Try not to send numeric signals, use `"KILL"` instead of `9`, for instance. Numeric signals aren't portable. Throws an exception if $signal is undef. This will _not_ clean up the harness, `finish` it if you kill it. Normally TERM kills a process gracefully (this is what the command line utility `kill` does by default), INT is sent by one of the keys `^C`, `Backspace` or ``, and `QUIT` is used to kill a process and make it coredump. The `HUP` signal is often used to get a process to "restart", rereading config files, and `USR1` and `USR2` for really application-specific things. Often, running `kill -l` (that's a lower case "L") on the command line will list the signals present on your operating system. **WARNING**: The signal subsystem is not at all portable. We \*may\* offer to simulate `TERM` and `KILL` on some operating systems, submit code to me if you want this. **WARNING 2**: Up to and including perl v5.6.1, doing almost anything in a signal handler could be dangerous. The most safe code avoids all mallocs and system calls, usually by preallocating a flag before entering the signal handler, altering the flag's value in the handler, and responding to the changed value in the main system: my $got_usr1 = 0; sub usr1_handler { ++$got_signal } $SIG{USR1} = \&usr1_handler; while () { sleep 1; print "GOT IT" while $got_usr1--; } Even this approach is perilous if ++ and -- aren't atomic on your system (I've never heard of this on any modern CPU large enough to run perl). - kill\_kill ## To kill off a process: $h->kill_kill; kill_kill $h; ## To specify the grace period other than 30 seconds: kill_kill $h, grace => 5; ## To send QUIT instead of KILL if a process refuses to die: kill_kill $h, coup_d_grace => "QUIT"; Sends a `TERM`, waits for all children to exit for up to 30 seconds, then sends a `KILL` to any that survived the `TERM`. Will wait for up to 30 more seconds for the OS to successfully `KILL` the processes. The 30 seconds may be overridden by setting the `grace` option, this overrides both timers. The harness is then cleaned up. The doubled name indicates that this function may kill again and avoids colliding with the core Perl `kill` function. Returns undef if the `TERM` was sufficient, or a 1 if `KILL` was required. Throws an exception if `KILL` did not permit the children to be reaped. **NOTE**: The grace period is actually up to 1 second longer than that given. This is because the granularity of `time` is 1 second. Let me know if you need finer granularity, we can leverage Time::HiRes here. **Win32**: Win32 does not support signals, so `KILL` is sent immediately instead of `TERM`. The return value is `undef` when the process exits after the initial `KILL`, or `1` if a second `KILL` was needed. Grace periods have no meaning on Win32. - harness Takes a harness specification and returns a harness. This harness is blessed in to IPC::Run, allowing you to use method call syntax for run(), start(), et al if you like. harness() is provided so that you can pre-build harnesses if you would like to, but it's not required.. You may proceed to run(), start() or pump() after calling harness() (pump() calls start() if need be). Alternatively, you may pass your harness specification to run() or start() and let them harness() for you. You can't pass harness specifications to pump(), though. - close\_terminal This is used as (or in) an init sub to cast off the bonds of a controlling terminal. It must precede all other redirection ops that affect STDIN, STDOUT, or STDERR to be guaranteed effective. - start $h = start( \@cmd, \$in, \$out, ..., timeout( 30, name => "process timeout" ), $stall_timeout = timeout( 10, name => "stall timeout" ), ); $h = start \@cmd, '<', \$in, '|', \@cmd2, ...; start() accepts a harness or harness specification and returns a harness after building all of the pipes and launching (via fork()/exec(), or, maybe someday, spawn()) all the child processes. It does not send or receive any data on the pipes, see pump() and finish() for that. You may call harness() and then pass its result to start() if you like, but you only need to if it helps you structure or tune your application. If you do call harness(), you may skip start() and proceed directly to pump. start() also starts all timers in the harness. See [IPC::Run::Timer](https://metacpan.org/pod/IPC%3A%3ARun%3A%3ATimer) for more information. start() flushes STDOUT and STDERR to help you avoid duplicate output. It has no way of asking Perl to flush all your open filehandles, so you are going to need to flush any others you have open. Sorry. Here's how if you don't want to alter the state of $| for your filehandle: $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh; If you don't mind leaving output unbuffered on HANDLE, you can do the slightly shorter $ofh = select HANDLE; $| = 1; select $ofh; Or, you can use IO::Handle's flush() method: use IO::Handle; flush HANDLE; Perl needs the equivalent of C's fflush( (FILE \*)NULL ). - adopt Experimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS BETTER IN CHILDREN. SEE t/adopt.t for a test suite. - pump pump $h; $h->pump; Pump accepts a single parameter harness. It blocks until it delivers some input or receives some output. It returns TRUE if there is still input or output to be done, FALSE otherwise. pump() will automatically call start() if need be, so you may call harness() then proceed to pump() if that helps you structure your application. If pump() is called after all harnessed activities have completed, a "process ended prematurely" exception to be thrown. This allows for simple scripting of external applications without having to add lots of error handling code at each step of the script: $h = harness \@smbclient, \$in, \$out, $err; $in = "cd /foo\n"; $h->pump until $out =~ /^smb.*> \Z/m; die "error cding to /foo:\n$out" if $out =~ "ERR"; $out = ''; $in = "mget *\n"; $h->pump until $out =~ /^smb.*> \Z/m; die "error retrieving files:\n$out" if $out =~ "ERR"; $h->finish; warn $err if $err; - pump\_nb pump_nb $h; $h->pump_nb; "pump() non-blocking", pumps if anything's ready to be pumped, returns immediately otherwise. This is useful if you're doing some long-running task in the foreground, but don't want to starve any child processes. - close\_stdin $h->close_stdin; Closes the input pipe(s) to the child process(es), signaling EOF on the child's STDIN. Does **not** wait for the child to finish or drain remaining output. After calling this, the caller can continue to `pump()` to retrieve output incrementally. This is useful when streaming large amounts of data through a child process (e.g., decompression) where you want to signal end-of-input but continue draining output without buffering it all in memory: my ( $in, $out ) = ( '', '' ); my $h = start \@cmd, \$in, \$out, timeout( 30 ); while ( read_more_input_into( $in ) ) { $h->pump; process_output( $out ) if length $out; $out = ''; } $h->close_stdin; while ( $h->pumpable ) { $h->pump; process_output( $out ) if length $out; $out = ''; } $h->finish; **Note:** Always use a `timeout()` with this pattern. Without one, the `pump()` calls can deadlock if the child blocks on writing output while you are blocked trying to write input (or vice versa). Without `close_stdin()`, calling `finish()` would accumulate all remaining output in `$out` before returning, potentially exhausting memory for children that produce large output (like decompressors). Returns the harness object for chaining. - started Returns TRUE if the harness has been started and has not yet finished. This is useful when a harness may or may not have been started by the caller, and you want to conditionally start it: $h->start unless $h->started; - pumpable Returns TRUE if calling pump() won't throw an immediate "process ended prematurely" exception. This means that there are open I/O channels or active processes. May yield the parent processes' time slice for 0.01 second if all pipes are to the child and all are paused. In this case we can't tell if the child is dead, so we yield the processor and then attempt to reap the child in a nonblocking way. To wait for child processes to exit during an event loop, poll `$h-`pumpable> until it returns false, then call `finish`. See also ["finished"](#finished) to test whether the harness has already been finished. - reap\_nb Attempts to reap child processes, but does not block. Does not currently take any parameters, one day it will allow specific children to be reaped. Only call this from a signal handler if your `perl` is recent enough to have safe signal handling (5.6.1 did not, IIRC, but it was being discussed on perl5-porters). Calling this (or doing any significant work) in a signal handler on older `perl`s is asking for seg faults. - finish This must be called after the last start() or pump() call for a harness, or your system will accumulate defunct processes and you may "leak" file descriptors. finish() returns TRUE if all children returned 0 (and were not signaled and did not coredump, ie ! $?), and FALSE otherwise (this is like run(), and the opposite of system()). Once a harness has been finished, it may be run() or start()ed again, including by pump()s auto-start. If this throws an exception rather than a normal exit, the harness may be left in an unstable state, it's best to kill the harness to get rid of all the child processes, etc. Specifically, if a timeout expires in finish(), finish() will not kill all the children. Call `$h->kill_kill` in this case if you care. This differs from the behavior of ["run"](#run). - result $h->result; Returns the first non-zero result code (ie $? >> 8). See ["full\_result"](#full_result) to get the $? value for a child process. To get the result of a particular child, do: $h->result( 0 ); # first child's $? >> 8 $h->result( 1 ); # second child or ($h->results)[0] ($h->results)[1] Returns undef if no child processes were spawned and no child number was specified. Throws an exception if an out-of-range child number is passed. Note that `result` returns `undef` both when no children have exited and when all children exited with a zero exit code. Use ["finished"](#finished) to determine whether the harness has actually completed, or use ["results"](#results) to get the exit codes of all children (including zeros). - results Returns a list of child exit values. See ["full\_results"](#full_results) if you want to know if a signal killed the child. Throws an exception if the harness is not in a finished state. - full\_result $h->full_result; Returns the first non-zero $?. See ["result"](#result) to get the first $? >> 8 value for a child process. To get the result of a particular child, do: $h->full_result( 0 ); # first child's $? $h->full_result( 1 ); # second child or ($h->full_results)[0] ($h->full_results)[1] Returns undef if no child processes were spawned and no child number was specified. Throws an exception if an out-of-range child number is passed. - full\_results Returns a list of child exit values as returned by `wait`. See ["results"](#results) if you don't care about coredumps or signals. Throws an exception if the harness is not in a finished state. - pid $h->pid; Returns the process ID of the first child process, or undef if no child processes have been spawned yet. To get the PID of a particular child, do: $h->pid( 0 ); # first child's PID $h->pid( 1 ); # second child's PID or ($h->pids)[0] ($h->pids)[1] PIDs are available as soon as the harness has been started with ["start"](#start). - pids 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": run( \@cmd, '<', new_appender( "\n" ), \&commands, ); Here's a typical filter sub that might be created by new\_appender(): sub newline_appender { my ( $in_ref, $out_ref ) = @_; return input_avail && do { $$out_ref = join( '', $$out_ref, $$in_ref, "\n" ); $$in_ref = ''; 1; } }; - new\_string\_source TODO: Needs confirmation. Was previously undocumented. in this module. This is a filter which is exportable. Returns a sub which appends the data passed in to the output buffer and returns 1 if data was appended. 0 if it was an empty string and undef if no data was passed. NOTE: Any additional variables passed to new\_string\_source will be passed to the sub every time it's called and appended to the output. - new\_string\_sink TODO: Needs confirmation. Was previously undocumented. This is a filter which is exportable. Returns a sub which pops the data out of the input stream and pushes it onto the string. - io Takes a filename or filehandle, a redirection operator, optional filters, and a source or destination (depends on the redirection operator). Returns an IPC::Run::IO object suitable for harness()ing (including via start() or run()). This is shorthand for require IPC::Run::IO; ... IPC::Run::IO->new(...) ... - timer $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) ); pump $h until $out =~ /expected stuff/ || $t->is_expired; Instantiates a non-fatal timer. pump() returns once each time a timer expires. Has no direct effect on run(), but you can pass a subroutine to fire when the timer expires. See ["timeout"](#timeout) for building timers that throw exceptions on expiration. See ["timer" in IPC::Run::Timer](https://metacpan.org/pod/IPC%3A%3ARun%3A%3ATimer#timer) for details. - timeout $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) ); pump $h until $out =~ /expected stuff/; Instantiates a timer that throws an exception when it expires. If you don't provide an exception, a default exception that matches /^IPC::Run: .\*timed out/ is thrown by default. You can pass in your own exception scalar or reference: $h = start( \@cmd, \$in, \$out, $t = timeout( 5, exception => 'slowpoke' ), ); or set the name used in debugging message and in the default exception string: $h = start( \@cmd, \$in, \$out, timeout( 50, name => 'process timer' ), $stall_timer = timeout( 5, name => 'stall timer' ), ); pump $h until $out =~ /started/; $in = 'command 1'; $stall_timer->start; pump $h until $out =~ /command 1 finished/; $in = 'command 2'; $stall_timer->start; pump $h until $out =~ /command 2 finished/; $in = 'very slow command 3'; $stall_timer->start( 10 ); pump $h until $out =~ /command 3 finished/; $stall_timer->start( 5 ); $in = 'command 4'; pump $h until $out =~ /command 4 finished/; $stall_timer->reset; # Prevent restarting or expirng finish $h; See ["timer"](#timer) for building non-fatal timers. See ["timer" in IPC::Run::Timer](https://metacpan.org/pod/IPC%3A%3ARun%3A%3ATimer#timer) for details. # FILTER IMPLEMENTATION FUNCTIONS These functions are for use from within filters. - input\_avail Returns TRUE if input is available. If none is available, then &get\_more\_input is called and its result is returned. This is usually used in preference to &get\_more\_input so that the calling filter removes all data from the $in\_ref before more data gets read in to $in\_ref. `input_avail` is usually used as part of a return expression: 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). - no support for subroutine subprocesses (CODE refs) Can't fork(), so the subroutines would have no context, and closures certainly have no meaning Perhaps with Win32 fork() emulation, this can be supported in a limited fashion, but there are other very serious problems with that: all parent fds get dup()ed in to the thread emulating the forked process, and that keeps the parent from being able to close all of the appropriate fds. - no support for init => sub {} routines. Win32 processes are created from scratch, there is no way to do an init routine that will affect the running child. Some limited support might be implemented one day, do chdir() and %ENV changes can be made. - signals Win32 does not fully support signals. signal() is likely to cause errors unless sending a signal that Perl emulates, and `kill_kill()` is immediately fatal (there is no grace period). - `$?` cannot represent all Win32 exit codes Prefer `full_result( ... )`, `result( ... )`, or other IPC::Run methods. - helper processes IPC::Run uses helper processes, one per redirected file, to adapt between the anonymous pipe connected to the child and the TCP socket connected to the parent. This is a waste of resources and will change in the future to either use threads (instead of helper processes) or a WaitForMultipleObjects call (instead of select). Please contact me if you can help with the WaitForMultipleObjects() approach; I haven't figured out how to get at it without C code. - shutdown pause There seems to be a pause of up to 1 second between when a child program exits and the corresponding sockets indicate that they are closed in the parent. Not sure why. - binmode binmode is not supported yet. The underpinnings are implemented, just ask if you need it. - IPC::Run::IO IPC::Run::IO objects can be used on Unix to read or write arbitrary files. On Win32, they will need to use the same helper processes to adapt from non-select()able filehandles to select()able ones (or perhaps WaitForMultipleObjects() will work with them, not sure). - startup race conditions There seems to be an occasional race condition between child process startup and pipe closings. It seems like if the child is not fully created by the time CreateProcess returns and we close the TCP socket being handed to it, the parent socket can also get closed. This is seen with the Win32 pumper applications, not the "real" child process being spawned. I assume this is because the kernel hasn't gotten around to incrementing the reference count on the child's end (since the child was slow in starting), so the parent's closing of the child end causes the socket to be closed, thus closing the parent socket. Being a race condition, it's hard to reproduce, but I encountered it while testing this code on a drive share to a samba box. In this case, it takes t/run.t a long time to spawn its child processes (the parent hangs in the first select for several seconds until the child emits any debugging output). I have not seen it on local drives, and can't reproduce it at will, unfortunately. The symptom is a "bad file descriptor in select()" error, and, by turning on debugging, it's possible to see that select() is being called on a no longer open file descriptor that was returned from the \_socket() routine in Win32Helper. There's a new confess() that checks for this ("PARENT\_HANDLE no longer open"), but I haven't been able to reproduce it (typically). # LIMITATIONS On Unix, requires a system that supports `waitpid( $pid, WNOHANG )` so it can tell if a child process is still running. PTYs don't seem to be non-blocking on some versions of Solaris. Here's a test script contributed by Borislav Deianov to see if you have the problem. If it dies, you have the problem. #!/usr/bin/perl use IPC::Run qw(run); use Fcntl; use IO::Pty; sub makecmd { return ['perl', '-e', ', print "\n" x '.$_[0].'; while(){last if /end/}']; } #pipe R, W; #fcntl(W, F_SETFL, O_NONBLOCK); #while (syswrite(W, "\n", 1)) { $pipebuf++ }; #print "pipe buffer size is $pipebuf\n"; my $pipebuf=4096; my $in = "\n" x ($pipebuf * 2) . "end\n"; my $out; $SIG{ALRM} = sub { die "Never completed!\n" }; print "reading from scalar via pipe..."; alarm( 2 ); run(makecmd($pipebuf * 2), '<', \$in, '>', \$out); alarm( 0 ); print "done\n"; print "reading from code via pipe... "; alarm( 2 ); run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out); alarm( 0 ); print "done\n"; $pty = IO::Pty->new(); $pty->blocking(0); $slave = $pty->slave(); while ($pty->syswrite("\n", 1)) { $ptybuf++ }; print "pty buffer size is $ptybuf\n"; $in = "\n" x ($ptybuf * 3) . "end\n"; print "reading via pty... "; alarm( 2 ); run(makecmd($ptybuf * 3), '', \$out); alarm(0); print "done\n"; IO::Pty version 1.21 and later added a `DESTROY` method that automatically closes the cached slave pty handle when the master is destroyed. IPC::Run works around this by detaching the slave before closing the master in the child process; no user action is required. No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run() returns TRUE when the command exits with a 0 result code. Does not provide shell-like string interpolation. No support for `cd` or `export`: do `cd` in an init() sub. For setting environment variables in the child process without affecting the parent, use the `env` option (a hash reference of key/value pairs): run( \cmd, ... env => { FOO => 'BAR', BAZ => 'QUX' } ); The `env` variables are applied in the child process before any `init` subs run, so `init` can still override individual variables if needed. The parent process `%ENV` is not modified. Alternatively, use an `init` sub for more complex setup: run( \cmd, ... init => sub { chdir $dir or die $!; $ENV{FOO}='BAR' } ); Timeout calculation does not allow absolute times, or specification of days, months, etc. **WARNING:** Function coprocesses (`run \&foo, ...`) suffer from two limitations. The first is that it is difficult to close all filehandles the child inherits from the parent, since there is no way to scan all open FILEHANDLEs in Perl and it is both painful and a bit dangerous to close all open file descriptors with `POSIX::close()`. Painful because we can't tell which fds are open at the POSIX level, either, so we'd have to scan all possible fds and close any that we don't want open (normally `exec()` closes any non-inheritable but we don't `exec()` for &sub processes). The second problem is that Perl's DESTROY subs and other on-exit cleanup gets run in the child process. If objects are instantiated in the parent before the child is forked, the DESTROY will get run once in the parent and once in the child. When coprocess subs exit, POSIX::\_exit is called to work around this, but it means that objects that are still referred to at that time are not cleaned up. So setting package vars or closure vars to point to objects that rely on DESTROY to affect things outside the process (files, etc), will lead to bugs. I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both oddities. # TODO - Allow one harness to "adopt" another: $new_h = harness \@cmd2; $h->adopt( $new_h ); - Close all filehandles not explicitly marked to stay open. The problem with this one is that there's no good way to scan all open FILEHANDLEs in Perl, yet you don't want child processes inheriting handles willy-nilly. # INSPIRATION Well, select() and waitpid() badly needed wrapping, and open3() isn't open-minded enough for me. The shell-like API inspired by a message Russ Allbery sent to perl5-porters, which included: I've thought for some time that it would be nice to have a module that could handle full Bourne shell pipe syntax internally, with fork and exec, without ever invoking a shell. Something that you could give things like: pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3'); Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04. # SUPPORT Bugs should always be submitted via the GitHub bug tracker [https://github.com/cpan-authors/IPC-Run/issues](https://github.com/cpan-authors/IPC-Run/issues) # AUTHORS Adam Kennedy Barrie Slaymaker # COPYRIGHT Some parts copyright 2008 - 2009 Adam Kennedy. Copyright 1999 Barrie Slaymaker. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the README file. IPC-Run-20260402.0/MANIFEST.SKIP000644 000765 000024 00000000205 15160014620 016700 0ustar00todd.rinaldostaff000000 000000 \.appveyor.cmd \.appveyor.yml \.git \.perltidyrc \.travis.yml cpanfile ^MANIFEST.bak ^MYMETA.json ^MYMETA.yml ^Makefile$ ^CLAUDE\.md$IPC-Run-20260402.0/META.yml000644 000765 000024 00000001556 15163535532 016302 0ustar00todd.rinaldostaff000000 000000 --- abstract: 'system() and background procs w/ piping, redirs, ptys (Unix, Win32)' author: - 'Barrie Slaymaker ' build_requires: ExtUtils::MakeMaker: '0' Readonly::Array: '0' Test::More: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.76, CPAN::Meta::Converter version 2.150010' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: IPC-Run no_index: directory: - t - inc recommends: IO::Pty: '1.25' Readonly: '0' requires: IO::Pty: '1.25' Test::More: '0.47' resources: bugtracker: https://github.com/cpan-authors/IPC-Run/issues license: https://dev.perl.org/licenses/ repository: https://github.com/cpan-authors/IPC-Run version: '20260402.0' x_serialization_backend: 'CPAN::Meta::YAML version 0.020' IPC-Run-20260402.0/lib/000755 000765 000024 00000000000 15163535532 015570 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/Makefile.PL000644 000765 000024 00000005734 15163304533 017000 0ustar00todd.rinaldostaff000000 000000 use strict; use warnings; use ExtUtils::MakeMaker; # Calculate the dependencies my %PREREQ_PM; if ( $^O ne 'MSWin32' ) { foreach ( eval { require IO::Pty; IO::Pty->VERSION } ) { s/_//g if defined $_; unless ( defined $_ ) { warn("WARNING: \"IO::Pty not found\".\nWARNING: 'pty>' will not work.\n\n"); last; } $PREREQ_PM{'IO::Pty'} = '1.25'; } } else { $PREREQ_PM{'Win32'} = '0.27'; $PREREQ_PM{'Win32::Process'} = '0.14'; $PREREQ_PM{'Win32::ShellQuote'} = 0; $PREREQ_PM{'Win32API::File'} = '0.0901'; if ( $] >= 5.021006 ) { $PREREQ_PM{'Win32API::File'} = '0.1203'; } if ( !eval "use Socket qw( IPPROTO_TCP TCP_NODELAY ); 1" ) { warn <<"TOHERE"; $@ IPC::Run on Win32 requires a recent Sockets.pm in order to handle more complex interactions with subprocesses. They are not needed for most casual uses of run(), but it is impossible to tell whether all uses of IPC::Run in your installed modules meet the requirements, so IPC::Run should not be installed on Win32 machines with older perls. TOHERE ## Die nicely in case some install manager cares about the canonical ## error message for this. Not that I've ever seen one, but those ## wacky CPANPLUSers might just do something cool in this case. ## Older perls' Socket.pm don't export IPPROTO_TCP require 5.006; ## Most of the time it's not needed (since IPC::Run tries not to ## use sockets), but the user is not likely to know what the hell ## went wrong running sb. else's program. ## If something really odd is happening... exit 1; } } if ( $] < 5.008001 ) { # need Scalar::Util::looks_like_number $PREREQ_PM{'Scalar::List::Utils'} = '1.10'; } WriteMakefile( NAME => 'IPC::Run', ABSTRACT => 'system() and background procs w/ piping, redirs, ptys (Unix, Win32)', AUTHOR => 'Barrie Slaymaker ', VERSION_FROM => 'lib/IPC/Run.pm', ( $ExtUtils::MakeMaker::VERSION >= 6.3002 ? ( 'LICENSE' => 'perl', ) : () ), PREREQ_PM => { 'Test::More' => '0.47', %PREREQ_PM, }, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, clean => { FILES => 'IPC-Run-*' }, META_MERGE => { recommends => { 'IO::Pty' => '1.25', 'Readonly' => 0, }, build_requires => { 'Test::More' => 0, # For testing 'Readonly::Array' => 0, }, resources => { license => 'https://dev.perl.org/licenses/', bugtracker => 'https://github.com/cpan-authors/IPC-Run/issues', repository => 'https://github.com/cpan-authors/IPC-Run', } } ); sub MY::libscan { package MY; my $self = shift; my ($path) = @_; return '' if $path =~ m/\.sw[a-z]\z/msx; return '' unless length $self->SUPER::libscan($path); return $path; } IPC-Run-20260402.0/eg/000755 000765 000024 00000000000 15163535532 015415 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/META.json000644 000765 000024 00000002667 15163535532 016456 0ustar00todd.rinaldostaff000000 000000 { "abstract" : "system() and background procs w/ piping, redirs, ptys (Unix, Win32)", "author" : [ "Barrie Slaymaker " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.76, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "IPC-Run", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0", "Readonly::Array" : "0", "Test::More" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "recommends" : { "IO::Pty" : "1.25", "Readonly" : "0" }, "requires" : { "IO::Pty" : "1.25", "Test::More" : "0.47" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://github.com/cpan-authors/IPC-Run/issues" }, "license" : [ "https://dev.perl.org/licenses/" ], "repository" : { "url" : "https://github.com/cpan-authors/IPC-Run" } }, "version" : "20260402.0", "x_serialization_backend" : "JSON::PP version 4.16" } IPC-Run-20260402.0/eg/run_daemon000644 000765 000024 00000000532 15157373136 017472 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## An example of how to daemonize. See the IPC::Run LIMITATIONS section for ## some reasons why this can be a bit dangerous. use strict; use IPC::Run qw( run close_terminal ); run( sub { # ... your code here ... sleep 15; }, init => sub { close_terminal; exit if fork; } ); IPC-Run-20260402.0/eg/synopsis_scripting000644 000765 000024 00000001132 15163523655 021311 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w use strict; my @cat = qw( cat ); my ( $in_q, $out_q, $err_q ); use IPC::Run qw( start pump finish timeout ); # Incrementally read from / write to scalars. Note that $in_q # is a queue that is drained as it is used. $h is for "harness". my $h = start \@cat, \$in_q, \$out_q, \$err_q, timeout(10), debug => 1; $in_q .= "some input\n"; pump $h until $out_q =~ /input\n/g; $in_q .= "some more input\n"; pump $h until $out_q =~ /\G.*more input\n/; $in_q .= "some final input\n"; finish $h or die "cat returned $?"; warn $err_q if $err_q; print $out_q ; ## All of cat's output IPC-Run-20260402.0/eg/factorial000644 000765 000024 00000003254 15157373136 017313 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Demonstration of event-driven interaction with a subprocess ## Event driven programming is a pain. This code is not that readable ## and is not a good place to start, especially since few people (including ## me) are familiar with bc's nuances. use strict; use IPC::Run qw( run ); die "usage: $0 \n\nwhere is a positive integer\n" unless @ARGV; my $i = shift; die "\$i must be > 0, not '$i'" unless $i =~ /^\d+$/ && $i > 0; ## bc instructions to initialize two variables and print one out my $stdin_queue = "a = i = $i ; i\n"; ## Note the FALSE on failure result (opposite of system()). die $! unless run( ['bc'], sub { ## Consume all input and return it. This is used instead of a plain ## scalar because run() would close bc's stdin the first time the ## scalar emptied. my $r = $stdin_queue; $stdin_queue = ''; return $r; }, sub { my $out = shift; print "bc said: ", $out; if ( $out =~ s/.*?(\d+)\n/$1/g ) { ## Grab the number from bc. Assume all numbers are delivered in ## single chunks and all numbers are significant. if ( $out > $i ) { ## i! is always >i for i > 0 print "result = ", $out, "\n"; $stdin_queue = undef; } elsif ( $out == '1' ) { ## End of calculation loop, get bc to output the result. $stdin_queue = "a\n"; } else { ## get bc to calculate the next iteration and print it out. $stdin_queue = "i = i - 1 ; a = a * i ; i\n"; } } }, ); IPC-Run-20260402.0/eg/runsu000644 000765 000024 00000001673 15157373136 016526 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Demonstration of chatting with a bash shell. use strict; use IPC::Run qw( start pump finish timeout ); $IPC::Run::debug = 10; my ( $in, $out ); die "usage: runsu " unless @ARGV; my $user = @ARGV > 1 ? shift : $ENV{USER} || $ENV{USERNAME}; my $passwd = shift; my $h = start( [ qw(su - ), $user ], 'pty>', \$out, timeout(5), ); pump $h until $out =~ /^password/im; $in = "$passwd\n"; ## Assume atomic prompt writes ## and that a non-word is the last char in the prompt. $out = ''; pump $h until $out =~ /([^\r\n\w]\s*)(?!\n)$/; my $prompt = $1; print "Detected prompt string = '$prompt'\n"; $prompt = quotemeta $prompt; for (qw( ls ps fOoBaR pwd )) { $in = $_ . "\n"; $out = ''; $h->timeout(5); # restart the timeout pump $h until $out =~ s/\A((?s:.*))(?=^.*?$prompt(?!\n)\Z)//m; print map { "su: $_\n" } split( /\n/m, $1 ); } $in = "exit\n"; finish $h ; IPC-Run-20260402.0/eg/runsh000644 000765 000024 00000002156 15157373136 016506 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Demonstration of chatting with a bash shell. use strict; use IPC::Run qw( start pump finish timeout ); my ( $in, $out, $err ); my $h = start( [qw(sh -login -i )], \$in, \$out, \$err, debug => 0, timeout(5), ); ## The first thing we do is to convert the user's prompt. Normally, we would ## do a '' as the first command in the for () loop so we could detect errors ## that bash might emit on startup. In this case, we need to do this ## initialization first so that we have a prompt to look for so we know that ## it's ready to accept input. This is all because the startup scripts ## that bash runs set PS1, and we can't have that. $in = "PS1=' '\n"; ## bash prompts on stderr. Consume everything before the first ## (which is the second prompt bash issues). pump $h until $err =~ s/.*(?=^ (?!\n)\Z)//ms; for (qw( ls ps fOoBaR pwd )) { $in = $_ . "\n"; $out = ''; pump $h until $err =~ s/\A( .*)(?=^ (?!\n)\Z)//ms; print map { "sh err: $_\n" } split( /\n/m, $1 ); print map { "sh: $_\n" } split( /\n/m, $out ); } finish $h ; IPC-Run-20260402.0/eg/factorial_pipe000644 000765 000024 00000001540 15157373136 020324 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Demonstration using a pipe to send input to a child process use strict; use IPC::Run qw( start pump finish ); die "usage: $0 \n\nwhere is a positive integer\n" unless @ARGV; my $i = shift; die "\$i must be > 0, not '$i'" unless $i =~ /^\d+$/ && $i > 0; my $out; my $h = start ['bc'], '', \$out; my $tmp = select IN; $| = 1; select $tmp; print IN "a = i = $i ; i\n"; while () { $out = ''; pump $h until $out =~ s/.*?(\d+)\n/$1/g; print "bc said: $out\n"; if ( $out > $i ) { ## i! is always >i for i > 0 print "result = ", $out, "\n"; close(IN); last; } elsif ( $out == '1' ) { ## End of calculation loop, get bc to output the result print IN "a\n"; } else { print IN "i = i - 1 ; a = a * i ; i\n"; } } finish $h ; IPC-Run-20260402.0/eg/abuse/000755 000765 000024 00000000000 15163535532 016514 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/eg/factorial_scalar000644 000765 000024 00000001415 15157373136 020635 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Demonstration of using a scalar to queue input to a child process use strict; use IPC::Run qw( start timeout ); die "usage: $0 \n\nwhere is a positive integer\n" unless @ARGV; my $i = shift; die "\$i must be > 0, not '$i'" unless $i =~ /^\d+$/ && $i > 0; my ( $in, $out ); my $h = start ['bc'], \$in, \$out, timeout(5); $in = "a = i = $i ; i\n"; while () { $out = ''; $h->pump until $out =~ s/.*?(\d+)\n/$1/g; print "bc said: $out\n"; if ( $out > $i ) { print "result = $out\n"; $in = undef; last; } elsif ( $out == '1' ) { ## End of calculation loop, get bc to output the result $in = "a\n"; } else { $in = "i = i - 1 ; a = a * i ; i\n"; } } $h->finish; IPC-Run-20260402.0/eg/abuse/blocking_debug_with_sub_coprocess000644 000765 000024 00000001460 15157373136 025365 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Submitted by Blair Zajac ## Tests blocking when piping though a &sub coprocess. ## Fixed, now in test suite. $| = 1; use strict; use Carp; use Symbol; use IPC::Run 0.44 qw(start); print "My pid is $$\n"; my $out_fd = gensym; open( $out_fd, ">ZZZ.test" ) or die "$0: open: $!\n"; my $queue = ''; my @commands = ( [ [ 'cat', '-' ], \$queue, '|' ], [ ['cat'], '|' ], [ \&double, '>', $out_fd ] ); my $harness = start 'debug' => 10, map { @$_ } @commands; $harness or die "$0: harness\n"; close($out_fd) or die "$0: cannot close: $!\n"; for ( 1 .. 100 ) { $queue .= rand(100) . "\n"; $harness->pump; } $harness->finish or die "$0: finish\n"; exit 0; sub double { while () { s/\s+$//; print "$_ $_\n"; } } IPC-Run-20260402.0/eg/abuse/timers000644 000765 000024 00000000314 15157373136 017743 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w use strict; use IPC::Run qw( :all ); $IPC::Run::debug = 10; alarm 5; $SIG{ALRM} = sub { die "timeout never fired!" }; my $out; run [ $^X, '-e', 'sleep 10' ], ">", \$out, timeout 1; IPC-Run-20260402.0/eg/abuse/blocking_writes000644 000765 000024 00000002031 15157373136 021623 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl ## Submitted by Borislav Deianov ## This stresses the blocking write to see if it blocks. use Fcntl; use IO::Pty; use IPC::Run qw(run); sub makecmd { return [ 'perl', '-e', ', print "\n" x ' . $_[0] . '; while(){last if /end/}' ]; } pipe R, W; fcntl( W, F_SETFL, O_NONBLOCK ); while ( syswrite( W, "\n", 1 ) ) { $pipebuf++ } print "pipe buffer size is $pipebuf\n"; $in = "\n" x ( $pipebuf * 3 ) . "end\n"; print "reading from scalar via pipe... "; run( makecmd( $pipebuf * 3 ), '<', \$in, '>', \$out ); print "done\n"; print "reading from code via pipe... "; run( makecmd( $pipebuf * 3 ), '<', sub { $t = $in; undef $in; $t }, '>', \$out ); print "done\n"; $pty = IO::Pty->new(); $pty->blocking(0); $slave = $pty->slave(); while ( $pty->syswrite( "\n", 1 ) ) { $ptybuf++ } print "pty buffer size is $ptybuf\n"; $in = "\n" x ( $ptybuf * 3 ) . "end\n"; print "reading via pty... "; run( makecmd( $ptybuf * 3 ), '', \$out ); print "done\n"; IPC-Run-20260402.0/eg/abuse/broken_pipe_on_bad_executable_name000644 000765 000024 00000000457 15157373136 025450 0ustar00todd.rinaldostaff000000 000000 #!/usr/bin/perl -w ## Submitted by Dave Mitchell use IPC::Run qw(run timeout); $IPC::Run::debug = 10; warn "parent id=$$\n"; $res = run [ './nosuchfile', 0 ], \"foo", \$out, \$err; warn "running after 'run', pid=$$\n\$?=$?\nstderr=[[[[$err]]]]\nstdout=[[[[$out]]]]\n"; IPC-Run-20260402.0/lib/IPC/000755 000765 000024 00000000000 15163535532 016203 5ustar00todd.rinaldostaff000000 000000 IPC-Run-20260402.0/lib/IPC/Run.pm000644 000765 000024 00000514174 15163534150 017314 0ustar00todd.rinaldostaff000000 000000 package IPC::Run; use bytes; =pod =for markdown [![testsuite](https://github.com/cpan-authors/IPC-Run/actions/workflows/testsuite.yml/badge.svg)](https://github.com/cpan-authors/IPC-Run/actions/workflows/testsuite.yml) =head1 NAME IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32) =head1 SYNOPSIS ## First,a command to run: my @cat = qw( cat ); ## Using run() instead of system(): use IPC::Run qw( run timeout ); run \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?"; # Can do I/O to sub refs and filenames, too: run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?"; run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt"; # Redirecting using pseudo-terminals instead of pipes. run \@cat, 'pty>', \$out_and_err; ## Scripting subprocesses (like Expect): use IPC::Run qw( start pump finish timeout ); # Incrementally read from / write to scalars. # $in is drained as it is fed to cat's stdin, # $out accumulates cat's stdout # $err accumulates cat's stderr # $h is for "harness". my $h = start \@cat, \$in, \$out, \$err, timeout( 10 ); $in .= "some input\n"; pump $h until $out =~ /input\n/g; $in .= "some more input\n"; pump $h until $out =~ /\G.*more input\n/; $in .= "some final input\n"; finish $h or die "cat returned $?"; warn $err if $err; print $out; ## All of cat's output # Piping between children run \@cat, '|', \@gzip; # Multiple children simultaneously (run() blocks until all # children exit, use start() for background execution): run \@foo1, '&', \@foo2; # Calling \&set_up_child in the child before it executes the # command (only works on systems with true fork() & exec()) # exceptions thrown in set_up_child() will be propagated back # to the parent and thrown from run(). run \@cat, \$in, \$out, init => \&set_up_child; # Read from / write to file handles you open and close open IN, 'out.txt' or die $!; print OUT "preamble\n"; run \@cat, \*IN, \*OUT or die "cat returned $?"; print OUT "postamble\n"; close IN; close OUT; # Create pipes for you to read / write (like IPC::Open2 & 3). $h = start \@cat, 'pipe', \*OUT, '2>pipe', \*ERR or die "cat returned $?"; print IN "some input\n"; close IN; print , ; finish $h; # Mixing input and output modes run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG; # Other redirection constructs run \@cat, '>&', \$out_and_err; run \@cat, '2>&1'; run \@cat, '0<&3'; run \@cat, '<&-'; run \@cat, '3<', \$in3; run \@cat, '4>', \$out4; # etc. # Passing options: run \@cat, 'in.txt', debug => 1; # Call this system's shell, returns TRUE on 0 exit code # THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE run "cat a b c" or die "cat returned $?"; # Launch a sub process directly, no shell. Can't do redirection # with this form, it's here to behave like system() with an # inverted result. $r = run "cat a b c"; # Read from a file in to a scalar run io( "filename", 'r', \$recv ); run io( \*HANDLE, 'r', \$recv ); =head1 DESCRIPTION IPC::Run allows you to run and interact with child processes using files, pipes, and pseudo-ttys. Both system()-style and scripted usages are supported and may be mixed. Likewise, functional and OO API styles are both supported and may be mixed. Various redirection operators reminiscent of those seen on common Unix and DOS command lines are provided. =head1 SIMPLE QUICKSTART Here's a quick guide to basic usage of using IPC::Run's C function. =head2 Capturing output and errors from an external command Say you want to run a command in your shell. We'll use C for simplicity, although there are far better ways to get a list of files, such as the C function or the L module. The basic form of C has the command and its arguments passed as an arrayref in the first argument. The command cannot be a single string. @cmd = [ 'ls', '-a', '-l', '-r', '-t' ]; # Yes @cmd = ( 'ls -a -l -r -t' ); # No After the command, pass a scalar reference C<\$in> for the input to pass in, and scalar references C<\$out> and C<\$err> to receive the content of stdout and stderr. use IPC::Run qw( run ); @cmd = qw( ls -l -a -r -t ); run( \@cmd, \$in, \$out, \$err ) or die $?; print("\$err is ", length($err), " bytes long\n"); print($err, "\n"); print("\$out is ", length($out), " bytes long\n"); print($out, "\n"); Running this will show something like: $err is 0 bytes long $out is 1410 bytes long total 392 drwxr-xr-x 3 andy staff 96 Mar 17 11:53 .github -rw-r--r-- 1 andy staff 158 Mar 17 11:53 .gitignore ... etc ... Note that C<$out> and C<$err> are always defined after a call to C, even if they receive no data. =head2 Passing input to the external program If you have input to pass in, put it in the C<$in> variables. For example, to use the C command to count lines, words and characters in a block of text: $in = <<'CARROLL'; 'Twas brillig, and the slithy toves Did gyre and gimble in the wabe: All mimsy were the borogoves, And the mome raths outgrabe. CARROLL @cmd = qw( wc ); run( \@cmd, \$in, \$out, \$err ) or die $?; print "$out"; This gives the output: 4 23 140 =head2 Handling errors It's important to check the return code of C to see if the command ran successfully. C returns a boolean true on success, and false on failure. Note that this is the opposite of Perl's C, which returns 0 on success and a non-zero value on failures. For the specific subprocess error code, check C<$?> directly. @cmd = qw( tar xzvf nonexistent.tar ); if ( !run( \@cmd, \$in, \$out, \$err ) ) { print "\$? = $?\n"; print "err = $err\n"; } Running this gives: $? = 256 err = tar: Error opening archive: Failed to open 'nonexistent.tar' If the program does not exist, then C will C and won't return at all. For example: @cmd = qw( bogus-command ); my $rc = run( \@cmd, \$in, \$out, \$err ); print "run returned ", ($rc ? "true" : "false"), "\n"; Running this doesn't make it to the C statement. Command 'bogus-command' not found in [ list of paths ] at program.pl line N. To handle the possibility of a non-existent program, call C inside an C. my $rc; eval { $rc = run( \@cmd, \$in, \$out, \$out ); 1; }; if ( !defined($rc) ) { print "run died: $@\n"; } else { if ( $rc ) { print "run returned true\n"; } else { print "run returned false\n"; print "\$? = $?\n"; } } =head2 And beyond That's the basics of using C as a replacement for C. If you'd like to do more, such as having subprocesses communicate with each other, setting timeouts on long-running processes, kill running subprocesses, redirecting output, closing file descriptors and much much MUCH more, read on. =head1 THE DETAILS Before digging in to the details a few LIMITATIONS are important enough to be mentioned right up front: =over =item Win32 Support Win32 support is working but B, but does pass all relevant tests on NT 4.0. See L. =item pty Support If you need pty support, IPC::Run should work well enough most of the time, but IO::Pty is being improved, and IPC::Run will be improved to use IO::Pty's new features when it is released. The basic problem is that the pty needs to initialize itself before the parent writes to the master pty, or the data written gets lost. So IPC::Run does a sleep(1) in the parent after forking to (hopefully) give the child a chance to run. This is a kludge that works well on non heavily loaded systems :(. ptys are not supported yet under Win32, but will be emulated... =item Debugging Tip You may use the environment variable C to see what's going on under the hood: $ IPCRUNDEBUG=basic myscript # prints minimal debugging $ IPCRUNDEBUG=data myscript # prints all data reads/writes $ IPCRUNDEBUG=details myscript # prints lots of low-level details $ IPCRUNDEBUG=gory myscript # (Win32 only) prints data moving through # the helper processes. =back =head2 Harnesses Child processes and I/O handles are gathered in to a harness, then started and run until the processing is finished or aborted. =head2 run() vs. start(); pump(); finish(); There are two modes you can run harnesses in: run() functions as an enhanced system(), and start()/pump()/finish() allow for background processes and scripted interactions with them. When using run(), all data to be sent to the harness is set up in advance (though one can feed subprocesses input from subroutine refs to get around this limitation). The harness is run and all output is collected from it, then any child processes are waited for: run \@cmd, \< and C<$err> in our examples. Regular expressions can be used to wait for appropriate output in several ways. The C example in the previous section demonstrates how to pump() until some string appears in the output. Here's an example that uses C to fetch files from a remote server: $h = harness \@smbclient, \$in, \$out; $in = "cd /src\n"; $h->pump until $out =~ /^smb.*> \Z/m; die "error cding to /src:\n$out" if $out =~ "ERR"; $out = ''; $in = "mget *\n"; $h->pump until $out =~ /^smb.*> \Z/m; die "error retrieving files:\n$out" if $out =~ "ERR"; $in = "quit\n"; $h->finish; Notice that we carefully clear $out after the first command/response cycle? That's because IPC::Run does not delete $out when we continue, and we don't want to trip over the old output in the second command/response cycle. Say you want to accumulate all the output in $out and analyze it afterwards. Perl offers incremental regular expression matching using the C and pattern matching idiom and the C<\G> assertion. IPC::Run is careful not to disturb the current C value for scalars it appends data to, so we could modify the above so as not to destroy $out by adding a couple of C modifiers. The C keeps us from tripping over the previous prompt and the C keeps us from resetting the prior match position if the expected prompt doesn't materialize immediately: $h = harness \@smbclient, \$in, \$out; $in = "cd /src\n"; $h->pump until $out =~ /^smb.*> \Z/mgc; die "error cding to /src:\n$out" if $out =~ "ERR"; $in = "mget *\n"; $h->pump until $out =~ /^smb.*> \Z/mgc; die "error retrieving files:\n$out" if $out =~ "ERR"; $in = "quit\n"; $h->finish; analyze( $out ); When using this technique, you may want to preallocate $out to have plenty of memory or you may find that the act of growing $out each time new input arrives causes an C slowdown as $out grows. Say we expect no more than 10,000 characters of input at the most. To preallocate memory to $out, do something like: my $out = "x" x 10_000; $out = ""; C will allocate at least 10,000 characters' worth of space, then mark the $out as having 0 length without freeing all that yummy RAM. =head2 Timeouts and Timers More than likely, you don't want your subprocesses to run forever, and sometimes it's nice to know that they're going a little slowly. Timeouts throw exceptions after a some time has elapsed, timers merely cause pump() to return after some time has elapsed. Neither is reset/restarted automatically. Timeout objects are created by calling timeout( $interval ) and passing the result to run(), start() or harness(). The timeout period starts ticking just after all the child processes have been fork()ed or spawn()ed, and are polled for expiration in run(), pump() and finish(). If/when they expire, an exception is thrown. This is typically useful to keep a subprocess from taking too long. If a timeout occurs in run(), all child processes will be terminated and all file/pipe/ptty descriptors opened by run() will be closed. File descriptors opened by the parent process and passed in to run() are not closed in this event. If a timeout occurs in pump(), pump_nb(), or finish(), it's up to you to decide whether to kill_kill() all the children or to implement some more graceful fallback. No I/O will be closed in pump(), pump_nb() or finish() by such an exception (though I/O is often closed down in those routines during the natural course of events). Often an exception is too harsh. timer( $interval ) creates timer objects that merely prevent pump() from blocking forever. This can be useful for detecting stalled I/O or printing a soothing message or "." to pacify an anxious user. Timeouts and timers can both be restarted at any time using the timer's start() method (this is not the start() that launches subprocesses). To restart a timer, you need to keep a reference to the timer: ## Start with a nice long timeout to let smbclient connect. If ## pump or finish take too long, an exception will be thrown. my $h; eval { $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 ); sleep 11; # No effect: timer not running yet start $h; $in = "cd /src\n"; pump $h until ! length $in; $in = "ls\n"; ## Now use a short timeout, since this should be faster $t->start( 5 ); pump $h until ! length $in; $t->start( 10 ); ## Give smbclient a little while to shut down. $h->finish; }; if ( $@ ) { my $x = $@; ## Preserve $@ in case another exception occurs $h->kill_kill; ## kill it gently, then brutally if need be, or just ## brutally on Win32. die $x; } Timeouts and timers are I checked once the subprocesses are shut down; they will not expire in the interval between the last valid process and when IPC::Run scoops up the processes' result codes, for instance. =head2 Spawning synchronization, child exception propagation start() pauses the parent until the child executes the command or CODE reference and propagates any exceptions thrown (including exec() failure) back to the parent. This has several pleasant effects: any exceptions thrown in the child, including exec() failure, come flying out of start() or run() as though they had occurred in the parent. This includes exceptions your code thrown from init subs. In this example: eval { run \@cmd, init => sub { die "blast it! foiled again!" }; }; print $@; the exception "blast it! foiled again" will be thrown from the child process (preventing the exec()) and printed by the parent. In situations like run \@cmd1, "|", \@cmd2, "|", \@cmd3; @cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before @cmd3. This can save time and prevent oddball errors emitted by later commands when earlier commands fail to execute. Note that IPC::Run doesn't start any commands unless it can find the executables referenced by all commands. These executables must pass both the C<-f> and C<-x> tests described in L. Another nice effect is that init() subs can take their time doing things and there will be no problems caused by a parent continuing to execute before a child's init() routine is complete. Say the init() routine needs to open a socket or a temp file that the parent wants to connect to; without this synchronization, the parent will need to implement a retry loop to wait for the child to run, since often, the parent gets a lot of things done before the child's first timeslice is allocated. This is also quite necessary for pseudo-tty initialization, which needs to take place before the parent writes to the child via pty. Writes that occur before the pty is set up can get lost. A final, minor, nicety is that debugging output from the child will be emitted before the parent continues on, making for much clearer debugging output in complex situations. The only drawback I can conceive of is that the parent can't continue to operate while the child is being initted. If this ever becomes a problem in the field, we can implement an option to avoid this behavior, but I don't expect it to. B: executing CODE references isn't supported on Win32, see L for details. =head2 Syntax run(), start(), and harness() can all take a harness specification as input. A harness specification is either a single string to be passed to the systems' shell: run "echo 'hi there'"; or a list of commands, io operations, and/or timers/timeouts to execute. Consecutive commands must be separated by a pipe operator '|' or an '&'. External commands are passed in as array references or L objects. On systems supporting fork(), Perl code may be passed in as subs: run \@cmd; run \@cmd1, '|', \@cmd2; run \@cmd1, '&', \@cmd2; run \&sub1; run \&sub1, '|', \&sub2; run \&sub1, '&', \&sub2; '|' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell pipe. '&' does not. Child processes to the right of a '&' will have their stdin closed unless it's redirected-to. L objects may be passed in as well, whether or not child processes are also specified: run io( "infile", ">", \$in ), io( "outfile", "<", \$in ); as can L objects: run \@cmd, io( "outfile", "<", \$in ), timeout( 10 ); Commands may be followed by scalar, sub, or i/o handle references for redirecting child process input & output: run \@cmd, \undef, \$out; run \@cmd, \$in, \$out; run \@cmd1, \&in, '|', \@cmd2, \*OUT; run \@cmd1, \*IN, '|', \@cmd2, \&out; This is known as succinct redirection syntax, since run(), start() and harness(), figure out which file descriptor to redirect and how. File descriptor 0 is presumed to be an input for the child process, all others are outputs. The assumed file descriptor always starts at 0, unless the command is being piped to, in which case it starts at 1. To be explicit about your redirects, or if you need to do more complex things, there's also a redirection operator syntax: run \@cmd, '<', \undef, '>', \$out; run \@cmd, '<', \undef, '>&', \$out_and_err; run( \@cmd1, '<', \$in, '|', \@cmd2, \$out ); Operator syntax is required if you need to do something other than simple redirection to/from scalars or subs, like duping or closing file descriptors or redirecting to/from a named file. The operators are covered in detail below. After each \@cmd (or \&foo), parsing begins in succinct mode and toggles to operator syntax mode when an operator (ie plain scalar, not a ref) is seen. Once in operator syntax mode, parsing only reverts to succinct mode when a '|' or '&' is seen. In succinct mode, each parameter after the \@cmd specifies what to do with the next highest file descriptor. These File descriptor start with 0 (stdin) unless stdin is being piped to (C<'|', \@cmd>), in which case they start with 1 (stdout). Currently, being on the left of a pipe (C<\@cmd, \$out, \$err, '|'>) does I cause stdout to be skipped, though this may change since it's not as DWIMerly as it could be. Only stdin is assumed to be an input in succinct mode, all others are assumed to be outputs. If no piping or redirection is specified for a child, it will inherit the parent's open file handles as dictated by your system's close-on-exec behavior and the $^F flag, except that processes after a '&' will not inherit the parent's stdin. Also note that $^F does not affect file descriptors obtained via POSIX, since it only applies to full-fledged Perl file handles. Such processes will have their stdin closed unless it has been redirected-to. If you want to close a child processes stdin, you may do any of: run \@cmd, \undef; run \@cmd, \""; run \@cmd, '<&-'; run \@cmd, '0<&-'; Redirection is done by placing redirection specifications immediately after a command or child subroutine: run \@cmd1, \$in, '|', \@cmd2, \$out; run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out; If you omit the redirection operators, descriptors are counted starting at 0. Descriptor 0 is assumed to be input, all others are outputs. A leading '|' consumes descriptor 0, so this works as expected. run \@cmd1, \$in, '|', \@cmd2, \$out; The parameter following a redirection operator can be a scalar ref, a subroutine ref, a file name, an open filehandle, or a closed filehandle. If it's a scalar ref, the child reads input from or sends output to that variable: $in = "Hello World.\n"; run \@cat, \$in, \$out; print $out; Scalars used in incremental (start()/pump()/finish()) applications are treated as queues: input is removed from input scalars, resulting in them dwindling to '', and output is appended to output scalars. This is not true of harnesses run() in batch mode. It's usually wise to append new input to be sent to the child to the input queue, and you'll often want to zap output queues to '' before pumping. $h = start \@cat, \$in; $in = "line 1\n"; pump $h; $in .= "line 2\n"; pump $h; $in .= "line 3\n"; finish $h; The final call to finish() must be there: it allows the child process(es) to run to completion and waits for their exit values. =head1 OBSTINATE CHILDREN Interactive applications are usually optimized for human use. This can help or hinder trying to interact with them through modules like IPC::Run. Frequently, programs alter their behavior when they detect that stdin, stdout, or stderr are not connected to a tty, assuming that they are being run in batch mode. Whether this helps or hurts depends on which optimizations change. And there's often no way of telling what a program does in these areas other than trial and error and occasionally, reading the source. This includes different versions and implementations of the same program. All hope is not lost, however. Most programs behave in reasonably tractable manners, once you figure out what it's trying to do. Here are some of the issues you might need to be aware of. =over =item * fflush()ing stdout and stderr This lets the user see stdout and stderr immediately. Many programs undo this optimization if stdout is not a tty, making them harder to manage by things like IPC::Run. Many programs decline to fflush stdout or stderr if they do not detect a tty there. Some ftp commands do this, for instance. If this happens to you, look for a way to force interactive behavior, like a command line switch or command. If you can't, you will need to use a pseudo terminal ('pty>'). =item * false prompts Interactive programs generally do not guarantee that output from user commands won't contain a prompt string. For example, your shell prompt might be a '$', and a file named '$' might be the only file in a directory listing. This can make it hard to guarantee that your output parser won't be fooled into early termination of results. To help work around this, you can see if the program can alter its prompt, and use something you feel is never going to occur in actual practice. You should also look for your prompt to be the only thing on a line: pump $h until $out =~ /^\s?\z/m; (use C<(?!\n)\Z> in place of C<\z> on older perls). You can also take the approach that IPC::ChildSafe takes and emit a command with known output after each 'real' command you issue, then look for this known output. See new_appender() and new_chunker() for filters that can help with this task. If it's not convenient or possibly to alter a prompt or use a known command/response pair, you might need to autodetect the prompt in case the local version of the child program is different then the one you tested with, or if the user has control over the look & feel of the prompt. =item * Refusing to accept input unless stdin is a tty. Some programs, for security reasons, will only accept certain types of input from a tty. su, notable, will not prompt for a password unless it's connected to a tty. If this is your situation, use a pseudo terminal ('pty>'). =item * Not prompting unless connected to a tty. Some programs don't prompt unless stdin or stdout is a tty. See if you can turn prompting back on. If not, see if you can come up with a command that you can issue after every real command and look for its output, as IPC::ChildSafe does. There are two filters included with IPC::Run that can help with doing this: appender and chunker (see new_appender() and new_chunker()). =item * Different output format when not connected to a tty. Some commands alter their formats to ease machine parsability when they aren't connected to a pipe. This is actually good, but can be surprising. =back =head1 PSEUDO TERMINALS On systems providing pseudo terminals under /dev, IPC::Run can use IO::Pty (available on CPAN) to provide a terminal environment to subprocesses. This is necessary when the subprocess really wants to think it's connected to a real terminal. =head2 CAVEATS Pseudo-terminals are not pipes, though they are similar. Here are some differences to watch out for. =over =item Echoing Sending to stdin will cause an echo on stdout, which occurs before each line is passed to the child program. There is currently no way to disable this, although the child process can and should disable it for things like passwords. =item Shutdown IPC::Run cannot close a pty until all output has been collected. This means that it is not possible to send an EOF to stdin by half-closing the pty, as we can when using a pipe to stdin. This means that you need to send the child process an exit command or signal, or run() / finish() will time out. Be careful not to expect a prompt after sending the exit command. =item Command line editing Some subprocesses, notable shells that depend on the user's prompt settings, will reissue the prompt plus the command line input so far once for each character. =item '>pty>' means '&>pty>', not '1>pty>' The pseudo terminal redirects both stdout and stderr unless you specify a file descriptor. If you want to grab stderr separately, do this: start \@cmd, 'pty>', \$out, '2>', \$err; =item stdin, stdout, and stderr not inherited Child processes harnessed to a pseudo terminal have their stdin, stdout, and stderr completely closed before any redirection operators take effect. This casts off the bonds of the controlling terminal. This is not done when using pipes. Right now, this affects all children in a harness that has a pty in use, even if that pty would not affect a particular child. That's a bug and will be fixed. Until it is, it's best not to mix-and-match children. =back =head2 Redirection Operators Operator SHNP Description ======== ==== =========== <, N< SHN Redirects input to a child's fd N (0 assumed) >, N> SHN Redirects output from a child's fd N (1 assumed) >>, N>> SHN Like '>', but appends to scalars or named files >&, &> SHN Redirects stdout & stderr from a child process pty, N>pty S Like '>', but uses a pseudo-tty instead of a pipe N<&M Dups input fd N to input fd M M>&N Dups output fd N to input fd M N<&- Closes fd N pipe, N>pipe P Pipe opens H for caller to read, write, close. 'N' and 'M' are placeholders for integer file descriptor numbers. The terms 'input' and 'output' are from the child process's perspective. The SHNP field indicates what parameters an operator can take: S: \$scalar or \&function references. Filters may be used with these operators (and only these). H: \*HANDLE or IO::Handle for caller to open, and close N: "file name". P: \*HANDLE or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read and written to and closed by the caller (like IPC::Open3). =over =item Redirecting input: [n]<, [n] and L for more information. The : The pipe must be closed before calling pump() for commands that buffer their output until stdin is closed (e.g. C). For interactive commands that produce output in response to each line of input, you may interleave writes and pump() calls without closing first. Unlike the other '<' operators, IPC::Run does nothing further with it: you are responsible for it. The previous example is functionally equivalent to: pipe( \*R, \*IN ) or die $!; $h = start \@cat, '<', \*R; print IN "hello world\n"; close IN; pump $h; finish $h; This is like the behavior of IPC::Open2 and IPC::Open3. B: The write end of the pipe opened by C<< > is set to B mode. This allows IPC::Run to fill the pipe buffer and continue to its select() loop without stalling. However, if you write a large amount of data faster than the child process reads it, you may receive C / C errors from print(). If you need blocking writes (for example, when acting as the start of a pipeline where you want to write at the child's pace), use C<< > instead: $h = start \@wc, 'finish; C<< > behaves identically to C<< >, but does not set the write end to non-blocking mode. B: The handle returned is actually a socket handle, so you can use select() on it. =item Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe You can redirect any output the child emits to a scalar variable, subroutine, file handle, or file name. You can have &run truncate or append to named files or scalars. If you are redirecting stdin as well, or if the command is on the receiving end of a pipeline ('|'), you can omit the redirection operator: @ls = ( 'ls' ); run \@ls, \undef, \$out or die "ls returned $?"; run \@ls, \undef, \&out; ## Calls &out each time some output ## is received from the child's ## when undef is returned. run \@ls, \undef, '2>ls.err'; run \@ls, '2>', 'ls.err'; The two parameter form guarantees that the filename will not be interpreted as a redirection operator: run \@ls, '>', "&more"; run \@ls, '2>', ">foo\n"; You can pass file handles you've opened for writing: open( *OUT, ">out.txt" ); open( *ERR, ">err.txt" ); run \@cat, \*OUT, \*ERR; Passing a scalar reference and a code reference requires a little more work, but allows you to capture all of the output in a scalar or each piece of output by a callback: These two do the same things: run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } ); does the same basic thing as: run( [ 'ls' ], '2>', \$err_out ); The subroutine will be called each time some data is read from the child. The >pipe operator is different in concept than the other '>' operators, although its syntax is similar: $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR; $in = "hello world\n"; finish $h; print ; print ; 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. B: The handle returned is actually a socket handle, so you can use select() on it. =item Duplicating output descriptors: >&m, n>&m This duplicates output descriptor number n (default is 1 if n is omitted) from descriptor number m. =item Duplicating input descriptors: <&m, n<&m This duplicates input descriptor number n (default is 0 if n is omitted) from descriptor number m =item 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, ', >&, &>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. =item 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, ); =back =head2 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 ); =head2 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; =over =item debug Enables debugging output in parent and child. Debugging info is emitted to the STDERR that was present when IPC::Run was first Ced (it's Ced out of the way so that it can be redirected in children without having debugging output emitted on it). =back =head1 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( ... ); $h->start; $h->pump; $h->finish; $h = start( .... ); $h->pump; ... Of course, using method call syntax lets you deal with any IPC::Run subclasses that might crop up, but don't hold your breath waiting for any. run() and finish() return TRUE when all subcommands exit with a 0 result code. B. All routines raise exceptions (via die()) when error conditions are recognized. A non-zero command result is not treated as an error condition, since some commands are tests whose results are reported in their exit codes. =head1 ROUTINES =over =cut use strict; use warnings; use Exporter (); use vars qw{$VERSION @ISA @FILTER_IMP @FILTERS @API @EXPORT_OK %EXPORT_TAGS}; BEGIN { $VERSION = '20260402.0'; @ISA = qw{ Exporter }; ## We use @EXPORT for the end user's convenience: there's only one function ## exported, it's homonymous with the module, it's an unusual name, and ## it can be suppressed by "use IPC::Run ();". @FILTER_IMP = qw( input_avail get_more_input ); @FILTERS = qw( new_appender new_chunker new_string_source new_string_sink ); @API = qw( run harness start pump pumpable finish signal kill_kill reap_nb io timer timeout close_terminal binary clearcache ); @EXPORT_OK = ( @API, @FILTER_IMP, @FILTERS, qw( Win32_MODE ) ); %EXPORT_TAGS = ( 'filter_imp' => \@FILTER_IMP, 'all' => \@EXPORT_OK, 'filters' => \@FILTERS, 'api' => \@API, ); } use strict; use warnings; use IPC::Run::Debug; use Exporter; use Fcntl; use POSIX (); BEGIN { if ( $] < 5.008 ) { require Symbol; } } use Carp; use File::Spec (); use IO::Handle; require IPC::Run::IO; require IPC::Run::Timer; use constant Win32_MODE => $^O =~ /os2|Win32/i; BEGIN { if (Win32_MODE) { eval "use IPC::Run::Win32Helper; 1;" or ( $@ && die ) or die "$!"; } else { eval "use File::Basename; 1;" or die $!; } } sub input_avail(); sub get_more_input(); ############################################################################### ## ## Error constants, not too locale-dependent use vars qw( $_EIO $_EAGAIN ); use Errno qw( EIO EAGAIN EPIPE ); BEGIN { local $!; $! = EIO; $_EIO = qr/^$!/; $! = EAGAIN; $_EAGAIN = qr/^$!/; } ## ## State machine states, set in $self->{STATE} ## ## These must be in ascending order numerically ## sub _newed() { 0 } sub _harnessed() { 1 } sub _finished() { 2 } ## _finished behave almost exactly like _harnessed sub _started() { 3 } ## ## Which fds have been opened in the parent. This may have extra fds, since ## we aren't all that rigorous about closing these off, but that's ok. This ## is used on Unixish OSs to close all fds in the child that aren't needed ## by that particular child. my %fds; ## There's a bit of hackery going on here. ## ## We want to have any code anywhere be able to emit ## debugging statements without knowing what harness the code is ## being called in/from, since we'd need to pass a harness around to ## everything. ## ## Thus, $cur_self was born. use vars qw( $cur_self ); sub _debug_fd { ## STDERR may be tied to a handle that doesn't implement FILENO (e.g. a ## tied filehandle without a real underlying fd). Wrap fileno() in eval ## so we degrade gracefully instead of dying with "Can't locate object ## method FILENO". Returns undef when no real fd is available, which is ## safe: callers that receive undef simply skip debug-fd setup. my $stderr_fd = eval { fileno STDERR }; return $stderr_fd unless defined $cur_self; if ( _debugging && !defined $cur_self->{DEBUG_FD} ) { if ( defined $stderr_fd ) { my $fd = select STDERR; $| = 1; select $fd; $cur_self->{DEBUG_FD} = POSIX::dup $stderr_fd; _debug("debugging fd is $cur_self->{DEBUG_FD}\n") if _debugging_details; } } return $stderr_fd unless defined $cur_self->{DEBUG_FD}; return $cur_self->{DEBUG_FD}; } sub DESTROY { ## We absolutely do not want to do anything else here. We are likely ## to be in a child process and we don't want to do things like kill_kill ## ourself or cause other destruction. my IPC::Run $self = shift; POSIX::close $self->{DEBUG_FD} if defined $self->{DEBUG_FD}; $self->{DEBUG_FD} = undef; for my $kid ( @{$self->{KIDS}} ) { for my $op ( @{$kid->{OPS}} ) { delete $op->{FILTERS}; } } } ## ## Support routines (NOT METHODS) ## my %cmd_cache; my $_cmd_cache_path = ''; # value of $ENV{PATH} when %cmd_cache was last populated =item clearcache() Clears the cache of executable paths that IPC::Run maintains internally. IPC::Run caches the full path of each command it resolves via C<$PATH> to avoid repeated filesystem searches. If you change C<$PATH> at runtime (or install a new executable into a directory that is already on C<$PATH>), call C to force IPC::Run to search C<$PATH> again on the next run. local $ENV{PATH} = "/new/bin:$ENV{PATH}"; IPC::Run::clearcache(); run ['mycommand'], ...; The cache is also invalidated automatically whenever C<$ENV{PATH}> changes between calls. =cut sub clearcache { %cmd_cache = (); $_cmd_cache_path = ''; return; } sub _search_path { my ($cmd_name) = @_; croak "command name is undefined or empty" unless defined $cmd_name && length $cmd_name; if ( File::Spec->file_name_is_absolute($cmd_name) && -x $cmd_name ) { _debug "'", $cmd_name, "' is absolute" if _debugging_details; return $cmd_name; } my $dirsep = ( Win32_MODE ? '[/\\\\]' : $^O =~ /MacOS/ ? ':' : $^O =~ /VMS/ ? '[\[\]]' : '/' ); if ( Win32_MODE && ( $cmd_name =~ /$dirsep/ ) && ( $cmd_name !~ m!\.[^\\/\.]+$! ) ) { _debug "no extension(.exe), checking ENV{PATHEXT}" if _debugging; for ( split /;/, $ENV{PATHEXT} || ".COM;.BAT;.EXE" ) { my $name = "$cmd_name$_"; $cmd_name = $name, last if -f $name && -x _; } _debug "cmd_name is now '$cmd_name'" if _debugging; } if ( $cmd_name =~ /($dirsep)/ ) { _debug "'$cmd_name' contains '$1'" if _debugging; croak "file not found: $cmd_name" unless -e $cmd_name; croak "not a file: $cmd_name" unless -f $cmd_name; croak "permission denied: $cmd_name" unless -x $cmd_name; return $cmd_name; } # Invalidate the entire cache when $PATH has changed so that commands are # re-resolved against the new search path (analogous to the shell "rehash"). my $current_path = defined $ENV{PATH} ? $ENV{PATH} : ''; if ( $current_path ne $_cmd_cache_path ) { _debug "PATH changed, clearing cmd_cache" if _debugging; %cmd_cache = (); $_cmd_cache_path = $current_path; } if ( exists $cmd_cache{$cmd_name} ) { _debug "'$cmd_name' found in cache: '$cmd_cache{$cmd_name}'" if _debugging; return $cmd_cache{$cmd_name} if -x $cmd_cache{$cmd_name}; _debug "'$cmd_cache{$cmd_name}' no longer executable, searching..." if _debugging; delete $cmd_cache{$cmd_name}; } my @searched_in; ## This next bit is Unix/Win32 specific, unfortunately. ## There's been some conversation about extending File::Spec to provide ## a universal interface to PATH, but I haven't seen it yet. my $re = Win32_MODE ? qr/;/ : qr/:/; LOOP: for ( split( $re, $ENV{PATH} || '', -1 ) ) { $_ = "." unless length $_; push @searched_in, $_; my $prospect = File::Spec->catfile( $_, $cmd_name ); my @prospects; @prospects = ( Win32_MODE && !( -f $prospect && -x _ ) ) ? map "$prospect$_", split /;/, $ENV{PATHEXT} || ".COM;.BAT;.EXE" : ($prospect); for my $found (@prospects) { if ( -f $found && -x _ ) { $cmd_cache{$cmd_name} = $found; last LOOP; } } } if ( exists $cmd_cache{$cmd_name} ) { _debug "'", $cmd_name, "' added to cache: '", $cmd_cache{$cmd_name}, "'" if _debugging_details; return $cmd_cache{$cmd_name}; } croak "Command '$cmd_name' not found in " . join( ", ", @searched_in ); } # Translate a command or CODE reference (a $kid->{VAL}) to a list of strings # suitable for passing to _debug(). sub _debugstrings { my $operand = shift; if ( !defined $operand ) { return ''; } my $ref = ref $operand; if ( !$ref ) { return length $operand < 50 ? "'$operand'" : join( '', "'", substr( $operand, 0, 10 ), "...'" ); } elsif ( $ref eq 'ARRAY' ) { return ( '[ ', join( " ", map /[^\w.-]/ ? "'$_'" : $_, @$operand ), ' ]' ); } elsif ( UNIVERSAL::isa( $operand, 'IPC::Run::Win32Process' ) ) { return "$operand"; } return $ref; } sub _empty($) { !( defined $_[0] && length $_[0] ) } ## 'safe' versions of otherwise fun things to do. See also IPC::Run::Win32Helper. sub _close { confess 'undef' unless defined $_[0]; my $fd = $_[0] =~ /^\d+$/ ? $_[0] : fileno $_[0]; if (Win32_MODE) { # Perl close() or POSIX::close() on the read end of a pipe hangs if # another process is in a read attempt on the same pipe # (https://github.com/Perl/perl5/issues/19963). Since IPC::Run creates # pipes and shares them with user-defined kids, it's affected. Work # around that by first using dup2() to replace the FD with a non-pipe. # Unfortunately, for socket FDs, dup2() closes the SOCKET with # CloseHandle(). CloseHandle() documentation leaves its behavior # undefined for sockets. However, tests on Windows Server 2022 did not # leak memory, leak ports, or reveal any other obvious trouble. # # No failure here is fatal. (_close() has worked that way, either due # to a principle or just due to a history of callers passing closed # FDs.) croak() on EMFILE would be a bad user experience. Better to # proceed and hope that $fd is not a being-read pipe. # # Since start() and other user-facing methods _close() many FDs, we # could optimize this by opening and closing the non-pipe FD just once # per method call. The overhead of this simple approach was in the # noise, however. my $nul_fd = POSIX::open 'NUL'; if ( !defined $nul_fd ) { _debug "open( NUL ) = ERROR $!" if _debugging_details; } else { my $r = POSIX::dup2( $nul_fd, $fd ); _debug "dup2( $nul_fd, $fd ) = ERROR $!" if _debugging_details && !defined $r; $r = POSIX::close $nul_fd; _debug "close( $nul_fd (NUL) ) = ERROR $!" if _debugging_details && !defined $r; } } my $r = POSIX::close $fd; $r = $r ? '' : " ERROR $!"; delete $fds{$fd}; _debug "close( $fd ) = " . ( $r || 0 ) if _debugging_details; } sub _dup { confess 'undef' unless defined $_[0]; my $r = POSIX::dup( $_[0] ); croak "$!: dup( $_[0] )" unless defined $r; $r = 0 if $r eq '0 but true'; _debug "dup( $_[0] ) = $r" if _debugging_details; $fds{$r} = {}; return $r; } sub _dup2_rudely { confess 'undef' unless defined $_[0] && defined $_[1]; my $r = POSIX::dup2( $_[0], $_[1] ); croak "$!: dup2( $_[0], $_[1] )" unless defined $r; $r = 0 if $r eq '0 but true'; _debug "dup2( $_[0], $_[1] ) = $r" if _debugging_details; $fds{$r} = {}; return $r; } sub _exec { confess 'undef passed' if grep !defined, @_; # exec @_ or croak "$!: exec( " . join( ', ', @_ ) . " )"; _debug 'exec()ing ', join " ", map "'$_'", @_ if _debugging_details; # { ## Commented out since we don't call this on Win32. # # This works around the bug where 5.6.1 complains # # "Can't exec ...: No error" after an exec on NT, where # # exec() is simulated and actually returns in Perl's C # # code, though Perl's &exec does not... # no warnings "exec"; # # # Just in case the no warnings workaround # # stops being a workaround, we don't want # # old values of $! causing spurious strerr() # # messages to appear in the "Can't exec" message # undef $!; exec { $_[0] } @_; # } # croak "$!: exec( " . join( ', ', map "'$_'", @_ ) . " )"; ## Fall through so $! can be reported to parent. } sub _sysopen { confess 'undef' unless defined $_[0] && defined $_[1]; _debug sprintf( "O_RDONLY=0x%02x ", O_RDONLY ), sprintf( "O_WRONLY=0x%02x ", O_WRONLY ), sprintf( "O_RDWR=0x%02x ", O_RDWR ), sprintf( "O_TRUNC=0x%02x ", O_TRUNC ), sprintf( "O_CREAT=0x%02x ", O_CREAT ), sprintf( "O_APPEND=0x%02x ", O_APPEND ), if _debugging_details; my $r = POSIX::open( $_[0], $_[1], 0666 ); croak "$!: open( $_[0], ", sprintf( "0x%03x", $_[1] ), " )" unless defined $r; _debug "open( $_[0], ", sprintf( "0x%03x", $_[1] ), " ) = $r" if _debugging_data; $fds{$r} = {}; return $r; } sub _pipe { ## Normal, blocking write for pipes that we read and the child writes, ## since most children expect writes to stdout to block rather than ## do a partial write. my ( $r, $w ) = POSIX::pipe; croak "$!: pipe()" unless defined $r; _debug "pipe() = ( $r, $w ) " if _debugging_details; @fds{$r, $w} = ( {}, {} ); return ( $r, $w ); } sub _pipe_nb { ## For pipes that we write, unblock the write side, so we can fill a buffer ## and continue to select(). ## Contributed by Borislav Deianov , with minor ## bugfix on fcntl result by me. local ( *R, *W ); my $f = pipe( R, W ); croak "$!: pipe()" unless defined $f; my ( $r, $w ) = ( fileno R, fileno W ); _debug "pipe_nb pipe() = ( $r, $w )" if _debugging_details; unless (Win32_MODE) { ## POSIX::fcntl doesn't take fd numbers, so gotta use Perl's and ## then _dup the originals (which get closed on leaving this block) my $fres = fcntl( W, &F_SETFL, O_WRONLY | O_NONBLOCK ); croak "$!: fcntl( $w, F_SETFL, O_NONBLOCK )" unless $fres; _debug "fcntl( $w, F_SETFL, O_NONBLOCK )" if _debugging_details; } ( $r, $w ) = ( _dup($r), _dup($w) ); _debug "pipe_nb() = ( $r, $w )" if _debugging_details; return ( $r, $w ); } sub _pty { require IO::Pty; my $pty = IO::Pty->new(); croak "$!: pty ()" unless $pty; $pty->autoflush(); $pty->blocking(0) or croak "$!: pty->blocking ( 0 )"; _debug "pty() = ( ", $pty->fileno, ", ", $pty->slave->fileno, " )" if _debugging_details; @fds{ $pty->fileno, $pty->slave->fileno } = ( {}, {} ); return $pty; } sub _read { confess 'undef' unless defined $_[0]; my $s = ''; my $r; do { $r = POSIX::read( $_[0], $s, 10_000 ); } while ( !defined($r) && $!{EINTR} ); croak "$!: read( $_[0] )" unless defined($r); $r ||= 0; _debug "read( $_[0] ) = $r chars '$s'" if _debugging_data; return $s; } ## A METHOD, not a function. sub _spawn { my IPC::Run $self = shift; my ($kid) = @_; croak "Can't spawn IPC::Run::Win32Process except on Win32" if UNIVERSAL::isa( $kid->{VAL}, 'IPC::Run::Win32Process' ); _debug "opening sync pipe ", $kid->{PID} if _debugging_details; my $sync_reader_fd; ( $sync_reader_fd, $self->{SYNC_WRITER_FD} ) = _pipe; ## GH#122: For CODE ref children, create a separate pipe to propagate ## exceptions back to the parent. We can't reuse the sync pipe because ## it must be closed before the CODE ref runs (to unblock the parent), ## but we still need a channel for the child to report die() messages. my $coderef_err_reader_fd; if ( ref $kid->{VAL} eq 'CODE' ) { ( $coderef_err_reader_fd, $self->{CODEREF_ERR_FD} ) = _pipe; } $kid->{PID} = fork(); croak "$! during fork" unless defined $kid->{PID}; unless ( $kid->{PID} ) { if ( $self->{_sigusr1_after_fork} ) { # sleep 10ms to improve chance of parent starting read() before it # handles the signal we're about to send. select undef, undef, undef, 0.01; kill 'USR1', getppid; } ## Close the parent's reader end of the error pipe in the child. POSIX::close $coderef_err_reader_fd if defined $coderef_err_reader_fd; ## _do_kid_and_exit closes sync_reader_fd since it closes all unwanted and ## unloved fds. $self->_do_kid_and_exit($kid); } _debug "fork() = ", $kid->{PID} if _debugging_details; ## Close the child's writer end of the error pipe in the parent. if ( defined $self->{CODEREF_ERR_FD} ) { POSIX::close $self->{CODEREF_ERR_FD}; $kid->{CODEREF_ERR_FD} = $coderef_err_reader_fd; } ## Wait for kid to get to its exec() and see if it fails. _close $self->{SYNC_WRITER_FD}; my $sync_pulse = _read $sync_reader_fd; _close $sync_reader_fd; if ( !defined $sync_pulse || length $sync_pulse ) { if ( waitpid( $kid->{PID}, 0 ) >= 0 ) { $kid->{RESULT} = $?; } else { $kid->{RESULT} = -1; } $sync_pulse = "error reading synchronization pipe for $kid->{NUM}, pid $kid->{PID}" unless length $sync_pulse; croak $sync_pulse; } return $kid->{PID}; } sub _write { confess 'undef' unless defined $_[0] && defined $_[1]; my $r = POSIX::write( $_[0], $_[1], length $_[1] ); unless ( defined $r ) { return undef if $! == EPIPE; ## caller handles broken pipe return 0 if $! == EAGAIN; ## non-blocking pipe buffer full, retry later croak "$!: write( $_[0], '$_[1]' )"; } _debug "write( $_[0], '$_[1]' ) = $r" if _debugging_data; return $r; } =pod =over =item run Run takes a harness or harness specification and runs it, pumping all input to the child(ren), closing the input pipes when no more input is available, collecting all output that arrives, until the pipes delivering output are closed, then waiting for the children to exit and reaping their result codes. You may think of C as being like start( ... )->finish(); , though there is one subtle difference: run() does not set \$input_scalars to '' like finish() does. If an exception is thrown from run(), all children will be killed off "gently", and then "annihilated" if they do not go gently (in to that dark night. sorry). If any exceptions are thrown, this does a L before propagating them. =cut use vars qw( $in_run ); ## No, not Enron;) sub run { local $in_run = 1; ## Allow run()-only optimizations. my IPC::Run $self = start(@_); my $r = eval { $self->{clear_ins} = 0; $self->finish; }; if ($@) { my $x = $@; $self->kill_kill; die $x; } return $r; } =pod =item signal ## To send it a specific signal by name ("USR1"): signal $h, "USR1"; $h->signal ( "USR1" ); If $signal is provided and defined, sends a signal to all child processes. Try not to send numeric signals, use C<"KILL"> instead of C<9>, for instance. Numeric signals aren't portable. Throws an exception if $signal is undef. This will I clean up the harness, C it if you kill it. Normally TERM kills a process gracefully (this is what the command line utility C does by default), INT is sent by one of the keys C<^C>, C or CDelE>, and C is used to kill a process and make it coredump. The C signal is often used to get a process to "restart", rereading config files, and C and C for really application-specific things. Often, running C (that's a lower case "L") on the command line will list the signals present on your operating system. B: The signal subsystem is not at all portable. We *may* offer to simulate C and C on some operating systems, submit code to me if you want this. B: Up to and including perl v5.6.1, doing almost anything in a signal handler could be dangerous. The most safe code avoids all mallocs and system calls, usually by preallocating a flag before entering the signal handler, altering the flag's value in the handler, and responding to the changed value in the main system: my $got_usr1 = 0; sub usr1_handler { ++$got_signal } $SIG{USR1} = \&usr1_handler; while () { sleep 1; print "GOT IT" while $got_usr1--; } Even this approach is perilous if ++ and -- aren't atomic on your system (I've never heard of this on any modern CPU large enough to run perl). =cut sub signal { my IPC::Run $self = shift; local $cur_self = $self; $self->_kill_kill_kill_pussycat_kill unless @_; Carp::cluck "Ignoring extra parameters passed to kill()" if @_ > 1; my ($signal) = @_; croak "Undefined signal passed to signal" unless defined $signal; for ( grep $_->{PID} && !defined $_->{RESULT}, @{ $self->{KIDS} } ) { _debug "sending $signal to $_->{PID}" if _debugging; kill $signal, $_->{PID} or _debugging && _debug "$! sending $signal to $_->{PID}"; } return; } =pod =item kill_kill ## To kill off a process: $h->kill_kill; kill_kill $h; ## To specify the grace period other than 30 seconds: kill_kill $h, grace => 5; ## To send QUIT instead of KILL if a process refuses to die: kill_kill $h, coup_d_grace => "QUIT"; Sends a C, waits for all children to exit for up to 30 seconds, then sends a C to any that survived the C. Will wait for up to 30 more seconds for the OS to successfully C the processes. The 30 seconds may be overridden by setting the C option, this overrides both timers. The harness is then cleaned up. The doubled name indicates that this function may kill again and avoids colliding with the core Perl C function. Returns undef if the C was sufficient, or a 1 if C was required. Throws an exception if C did not permit the children to be reaped. B: The grace period is actually up to 1 second longer than that given. This is because the granularity of C