{ "content": [ { "type": "text", "text": "# IPC::Run (perldoc)\n\n## NAME\n\nIPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32)\n\n## SYNOPSIS\n\n## First,a command to run:\nmy @cat = qw( cat );\n## Using run() instead of system():\nuse IPC::Run qw( run timeout );\nrun \\@cat, \\$in, \\$out, \\$err, timeout( 10 ) or die \"cat: $?\";\n# Can do I/O to sub refs and filenames, too:\nrun \\@cat, '<', \"in.txt\", \\&out, \\&err or die \"cat: $?\";\nrun \\@cat, '<', \"in.txt\", '>>', \"out.txt\", '2>>', \"err.txt\";\n# Redirecting using pseudo-terminals instead of pipes.\nrun \\@cat, 'pty>', \\$outanderr;\n## Scripting subprocesses (like Expect):\nuse IPC::Run qw( start pump finish timeout );\n# Incrementally read from / write to scalars.\n# $in is drained as it is fed to cat's stdin,\n# $out accumulates cat's stdout\n# $err accumulates cat's stderr\n# $h is for \"harness\".\nmy $h = start \\@cat, \\$in, \\$out, \\$err, timeout( 10 );\n$in .= \"some input\\n\";\npump $h until $out =~ /input\\n/g;\n$in .= \"some more input\\n\";\npump $h until $out =~ /\\G.*more input\\n/;\n$in .= \"some final input\\n\";\nfinish $h or die \"cat returned $?\";\nwarn $err if $err;\nprint $out; ## All of cat's output\n# Piping between children\nrun \\@cat, '|', \\@gzip;\n# Multiple children simultaneously (run() blocks until all\n# children exit, use start() for background execution):\nrun \\@foo1, '&', \\@foo2;\n# Calling \\&setupchild in the child before it executes the\n# command (only works on systems with true fork() & exec())\n# exceptions thrown in setupchild() will be propagated back\n# to the parent and thrown from run().\nrun \\@cat, \\$in, \\$out,\ninit => \\&setupchild;\n# Read from / write to file handles you open and close\nopen IN, 'out.txt' or die $!;\nprint OUT \"preamble\\n\";\nrun \\@cat, \\*IN, \\*OUT or die \"cat returned $?\";\nprint OUT \"postamble\\n\";\nclose IN;\nclose OUT;\n# Create pipes for you to read / write (like IPC::Open2 & 3).\n$h = start\n\\@cat,\n'pipe', \\*OUT,\n'2>pipe', \\*ERR\nor die \"cat returned $?\";\nprint IN \"some input\\n\";\nclose IN;\nprint , ;\nfinish $h;\n# Mixing input and output modes\nrun \\@cat, 'in.txt', \\&catchsomeout, \\*ERRLOG;\n# Other redirection constructs\nrun \\@cat, '>&', \\$outanderr;\nrun \\@cat, '2>&1';\nrun \\@cat, '0<&3';\nrun \\@cat, '<&-';\nrun \\@cat, '3<', \\$in3;\nrun \\@cat, '4>', \\$out4;\n# etc.\n# Passing options:\nrun \\@cat, 'in.txt', debug => 1;\n# Call this system's shell, returns TRUE on 0 exit code\n# THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE\nrun \"cat a b c\" or die \"cat returned $?\";\n# Launch a sub process directly, no shell. Can't do redirection\n# with this form, it's here to behave like system() with an\n# inverted result.\n$r = run \"cat a b c\";\n# Read from a file in to a scalar\nrun io( \"filename\", 'r', \\$recv );\nrun io( \\*HANDLE, 'r', \\$recv );\n\n## DESCRIPTION\n\nIPC::Run allows you to run and interact with child processes using files, pipes, and\npseudo-ttys. Both system()-style and scripted usages are supported and may be mixed. Likewise,\nfunctional and OO API styles are both supported and may be mixed.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (13 subsections)\n- **OBSTINATE CHILDREN**\n- **PSEUDO TERMINALS** (2 subsections)\n- **RETURN VALUES** (2 subsections)\n- **ROUTINES**\n- **FILTERS**\n- **FILTER IMPLEMENTATION FUNCTIONS**\n- **TODO**\n- **Win32 LIMITATIONS**\n- **LIMITATIONS**\n- **INSPIRATION**\n- **SUPPORT**\n- **AUTHORS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "IPC::Run", "section": "", "mode": "perldoc", "summary": "IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32)", "synopsis": "## First,a command to run:\nmy @cat = qw( cat );\n## Using run() instead of system():\nuse IPC::Run qw( run timeout );\nrun \\@cat, \\$in, \\$out, \\$err, timeout( 10 ) or die \"cat: $?\";\n# Can do I/O to sub refs and filenames, too:\nrun \\@cat, '<', \"in.txt\", \\&out, \\&err or die \"cat: $?\";\nrun \\@cat, '<', \"in.txt\", '>>', \"out.txt\", '2>>', \"err.txt\";\n# Redirecting using pseudo-terminals instead of pipes.\nrun \\@cat, 'pty>', \\$outanderr;\n## Scripting subprocesses (like Expect):\nuse IPC::Run qw( start pump finish timeout );\n# Incrementally read from / write to scalars.\n# $in is drained as it is fed to cat's stdin,\n# $out accumulates cat's stdout\n# $err accumulates cat's stderr\n# $h is for \"harness\".\nmy $h = start \\@cat, \\$in, \\$out, \\$err, timeout( 10 );\n$in .= \"some input\\n\";\npump $h until $out =~ /input\\n/g;\n$in .= \"some more input\\n\";\npump $h until $out =~ /\\G.*more input\\n/;\n$in .= \"some final input\\n\";\nfinish $h or die \"cat returned $?\";\nwarn $err if $err;\nprint $out; ## All of cat's output\n# Piping between children\nrun \\@cat, '|', \\@gzip;\n# Multiple children simultaneously (run() blocks until all\n# children exit, use start() for background execution):\nrun \\@foo1, '&', \\@foo2;\n# Calling \\&setupchild in the child before it executes the\n# command (only works on systems with true fork() & exec())\n# exceptions thrown in setupchild() will be propagated back\n# to the parent and thrown from run().\nrun \\@cat, \\$in, \\$out,\ninit => \\&setupchild;\n# Read from / write to file handles you open and close\nopen IN, 'out.txt' or die $!;\nprint OUT \"preamble\\n\";\nrun \\@cat, \\*IN, \\*OUT or die \"cat returned $?\";\nprint OUT \"postamble\\n\";\nclose IN;\nclose OUT;\n# Create pipes for you to read / write (like IPC::Open2 & 3).\n$h = start\n\\@cat,\n'pipe', \\*OUT,\n'2>pipe', \\*ERR\nor die \"cat returned $?\";\nprint IN \"some input\\n\";\nclose IN;\nprint , ;\nfinish $h;\n# Mixing input and output modes\nrun \\@cat, 'in.txt', \\&catchsomeout, \\*ERRLOG;\n# Other redirection constructs\nrun \\@cat, '>&', \\$outanderr;\nrun \\@cat, '2>&1';\nrun \\@cat, '0<&3';\nrun \\@cat, '<&-';\nrun \\@cat, '3<', \\$in3;\nrun \\@cat, '4>', \\$out4;\n# etc.\n# Passing options:\nrun \\@cat, 'in.txt', debug => 1;\n# Call this system's shell, returns TRUE on 0 exit code\n# THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE\nrun \"cat a b c\" or die \"cat returned $?\";\n# Launch a sub process directly, no shell. Can't do redirection\n# with this form, it's here to behave like system() with an\n# inverted result.\n$r = run \"cat a b c\";\n# Read from a file in to a scalar\nrun io( \"filename\", 'r', \\$recv );\nrun io( \\*HANDLE, 'r', \\$recv );", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 102, "subsections": [] }, { "name": "DESCRIPTION", "lines": 37, "subsections": [ { "name": "Harnesses", "lines": 5 }, { "name": "start", "lines": 37 }, { "name": "Using regexps to match output", "lines": 61 }, { "name": "Timeouts and Timers", "lines": 6 }, { "name": "start", "lines": 9 }, { "name": "kill_kill", "lines": 4 }, { "name": "pump", "lines": 37 }, { "name": "Spawning synchronization, child exception propagation", "lines": 1 }, { "name": "start", "lines": 2 }, { "name": "start", "lines": 8 }, { "name": "exec", "lines": 28 }, { "name": "Syntax", "lines": 1 }, { "name": "run", "lines": 119 } ] }, { "name": "OBSTINATE CHILDREN", "lines": 72, "subsections": [] }, { "name": "PSEUDO TERMINALS", "lines": 40, "subsections": [ { "name": "Redirection Operators", "lines": 230 }, { "name": "Options", "lines": 14 } ] }, { "name": "RETURN VALUES", "lines": 1, "subsections": [ { "name": "harness", "lines": 14 }, { "name": "run", "lines": 6 } ] }, { "name": "ROUTINES", "lines": 276, "subsections": [] }, { "name": "FILTERS", "lines": 160, "subsections": [] }, { "name": "FILTER IMPLEMENTATION FUNCTIONS", "lines": 36, "subsections": [] }, { "name": "TODO", "lines": 8, "subsections": [] }, { "name": "Win32 LIMITATIONS", "lines": 79, "subsections": [] }, { "name": "LIMITATIONS", "lines": 87, "subsections": [] }, { "name": "INSPIRATION", "lines": 13, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32)\n", "subsections": [] }, "SYNOPSIS": { "content": "## First,a command to run:\nmy @cat = qw( cat );\n\n## Using run() instead of system():\nuse IPC::Run qw( run timeout );\n\nrun \\@cat, \\$in, \\$out, \\$err, timeout( 10 ) or die \"cat: $?\";\n\n# Can do I/O to sub refs and filenames, too:\nrun \\@cat, '<', \"in.txt\", \\&out, \\&err or die \"cat: $?\";\nrun \\@cat, '<', \"in.txt\", '>>', \"out.txt\", '2>>', \"err.txt\";\n\n\n# Redirecting using pseudo-terminals instead of pipes.\nrun \\@cat, 'pty>', \\$outanderr;\n\n## Scripting subprocesses (like Expect):\n\nuse IPC::Run qw( start pump finish timeout );\n\n# Incrementally read from / write to scalars.\n# $in is drained as it is fed to cat's stdin,\n# $out accumulates cat's stdout\n# $err accumulates cat's stderr\n# $h is for \"harness\".\nmy $h = start \\@cat, \\$in, \\$out, \\$err, timeout( 10 );\n\n$in .= \"some input\\n\";\npump $h until $out =~ /input\\n/g;\n\n$in .= \"some more input\\n\";\npump $h until $out =~ /\\G.*more input\\n/;\n\n$in .= \"some final input\\n\";\nfinish $h or die \"cat returned $?\";\n\nwarn $err if $err;\nprint $out; ## All of cat's output\n\n# Piping between children\nrun \\@cat, '|', \\@gzip;\n\n# Multiple children simultaneously (run() blocks until all\n# children exit, use start() for background execution):\nrun \\@foo1, '&', \\@foo2;\n\n# Calling \\&setupchild in the child before it executes the\n# command (only works on systems with true fork() & exec())\n# exceptions thrown in setupchild() will be propagated back\n# to the parent and thrown from run().\nrun \\@cat, \\$in, \\$out,\ninit => \\&setupchild;\n\n# Read from / write to file handles you open and close\nopen IN, 'out.txt' or die $!;\nprint OUT \"preamble\\n\";\nrun \\@cat, \\*IN, \\*OUT or die \"cat returned $?\";\nprint OUT \"postamble\\n\";\nclose IN;\nclose OUT;\n\n# Create pipes for you to read / write (like IPC::Open2 & 3).\n$h = start\n\\@cat,\n'pipe', \\*OUT,\n'2>pipe', \\*ERR\nor die \"cat returned $?\";\nprint IN \"some input\\n\";\nclose IN;\nprint , ;\nfinish $h;\n\n# Mixing input and output modes\nrun \\@cat, 'in.txt', \\&catchsomeout, \\*ERRLOG;\n\n# Other redirection constructs\nrun \\@cat, '>&', \\$outanderr;\nrun \\@cat, '2>&1';\nrun \\@cat, '0<&3';\nrun \\@cat, '<&-';\nrun \\@cat, '3<', \\$in3;\nrun \\@cat, '4>', \\$out4;\n# etc.\n\n# Passing options:\nrun \\@cat, 'in.txt', debug => 1;\n\n# Call this system's shell, returns TRUE on 0 exit code\n# THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE\nrun \"cat a b c\" or die \"cat returned $?\";\n\n# Launch a sub process directly, no shell. Can't do redirection\n# with this form, it's here to behave like system() with an\n# inverted result.\n$r = run \"cat a b c\";\n\n# Read from a file in to a scalar\nrun io( \"filename\", 'r', \\$recv );\nrun io( \\*HANDLE, 'r', \\$recv );\n", "subsections": [] }, "DESCRIPTION": { "content": "IPC::Run allows you to run and interact with child processes using files, pipes, and\npseudo-ttys. Both system()-style and scripted usages are supported and may be mixed. Likewise,\nfunctional and OO API styles are both supported and may be mixed.\n\nVarious redirection operators reminiscent of those seen on common Unix and DOS command lines are\nprovided.\n\nBefore digging in to the details a few LIMITATIONS are important enough to be mentioned right up\nfront:\n\nWin32 Support\nWin32 support is working but EXPERIMENTAL, but does pass all relevant tests on NT 4.0. See\n\"Win32 LIMITATIONS\".\n\npty Support\nIf you need pty support, IPC::Run should work well enough most of the time, but IO::Pty is\nbeing improved, and IPC::Run will be improved to use IO::Pty's new features when it is\nrelease.\n\nThe basic problem is that the pty needs to initialize itself before the parent writes to the\nmaster pty, or the data written gets lost. So IPC::Run does a sleep(1) in the parent after\nforking to (hopefully) give the child a chance to run. This is a kludge that works well on\nnon heavily loaded systems :(.\n\nptys are not supported yet under Win32, but will be emulated...\n\nDebugging Tip\nYou may use the environment variable \"IPCRUNDEBUG\" to see what's going on under the hood:\n\n$ IPCRUNDEBUG=basic myscript # prints minimal debugging\n$ IPCRUNDEBUG=data myscript # prints all data reads/writes\n$ IPCRUNDEBUG=details myscript # prints lots of low-level details\n$ IPCRUNDEBUG=gory myscript # (Win32 only) prints data moving through\n# the helper processes.\n\nWe now return you to your regularly scheduled documentation.\n", "subsections": [ { "name": "Harnesses", "content": "Child processes and I/O handles are gathered in to a harness, then started and run until the\nprocessing is finished or aborted.\n\nrun() vs. start(); pump(); finish();\nThere are two modes you can run harnesses in: run() functions as an enhanced system(), and" }, { "name": "start", "content": "When using run(), all data to be sent to the harness is set up in advance (though one can feed\nsubprocesses input from subroutine refs to get around this limitation). The harness is run and\nall output is collected from it, then any child processes are waited for:\n\nrun \\@cmd, \\<pump until $out =~ /^smb.*> \\Z/m;\ndie \"error cding to /src:\\n$out\" if $out =~ \"ERR\";\n$out = '';\n\n$in = \"mget *\\n\";\n$h->pump until $out =~ /^smb.*> \\Z/m;\ndie \"error retrieving files:\\n$out\" if $out =~ \"ERR\";\n\n$in = \"quit\\n\";\n$h->finish;\n\nNotice that we carefully clear $out after the first command/response cycle? That's because\nIPC::Run does not delete $out when we continue, and we don't want to trip over the old output in\nthe second command/response cycle.\n\nSay you want to accumulate all the output in $out and analyze it afterwards. Perl offers\nincremental regular expression matching using the \"m//gc\" and pattern matching idiom and the\n\"\\G\" assertion. IPC::Run is careful not to disturb the current \"pos()\" value for scalars it\nappends data to, so we could modify the above so as not to destroy $out by adding a couple of\n\"/gc\" modifiers. The \"/g\" keeps us from tripping over the previous prompt and the \"/c\" keeps us\nfrom resetting the prior match position if the expected prompt doesn't materialize immediately:\n\n$h = harness \\@smbclient, \\$in, \\$out;\n\n$in = \"cd /src\\n\";\n$h->pump until $out =~ /^smb.*> \\Z/mgc;\ndie \"error cding to /src:\\n$out\" if $out =~ \"ERR\";\n\n$in = \"mget *\\n\";\n$h->pump until $out =~ /^smb.*> \\Z/mgc;\ndie \"error retrieving files:\\n$out\" if $out =~ \"ERR\";\n\n$in = \"quit\\n\";\n$h->finish;\n\nanalyze( $out );\n\nWhen using this technique, you may want to preallocate $out to have plenty of memory or you may\nfind that the act of growing $out each time new input arrives causes an \"O(length($out)^2)\"\nslowdown as $out grows. Say we expect no more than 10,000 characters of input at the most. To\npreallocate memory to $out, do something like:\n\nmy $out = \"x\" x 10000;\n$out = \"\";\n\n\"perl\" will allocate at least 10,000 characters' worth of space, then mark the $out as having 0\nlength without freeing all that yummy RAM.\n" }, { "name": "Timeouts and Timers", "content": "More than likely, you don't want your subprocesses to run forever, and sometimes it's nice to\nknow that they're going a little slowly. Timeouts throw exceptions after a some time has\nelapsed, timers merely cause pump() to return after some time has elapsed. Neither is\nreset/restarted automatically.\n\nTimeout objects are created by calling timeout( $interval ) and passing the result to run()," }, { "name": "start", "content": "been fork()ed or spawn()ed, and are polled for expiration in run(), pump() and finish(). If/when\nthey expire, an exception is thrown. This is typically useful to keep a subprocess from taking\ntoo long.\n\nIf a timeout occurs in run(), all child processes will be terminated and all file/pipe/ptty\ndescriptors opened by run() will be closed. File descriptors opened by the parent process and\npassed in to run() are not closed in this event.\n\nIf a timeout occurs in pump(), pumpnb(), or finish(), it's up to you to decide whether to" }, { "name": "kill_kill", "content": "in pump(), pumpnb() or finish() by such an exception (though I/O is often closed down in those\nroutines during the natural course of events).\n\nOften an exception is too harsh. timer( $interval ) creates timer objects that merely prevent" }, { "name": "pump", "content": "soothing message or \".\" to pacify an anxious user.\n\nTimeouts and timers can both be restarted at any time using the timer's start() method (this is\nnot the start() that launches subprocesses). To restart a timer, you need to keep a reference to\nthe timer:\n\n## Start with a nice long timeout to let smbclient connect. If\n## pump or finish take too long, an exception will be thrown.\n\nmy $h;\neval {\n$h = harness \\@smbclient, \\$in, \\$out, \\$err, ( my $t = timeout 30 );\nsleep 11; # No effect: timer not running yet\n\nstart $h;\n$in = \"cd /src\\n\";\npump $h until ! length $in;\n\n$in = \"ls\\n\";\n## Now use a short timeout, since this should be faster\n$t->start( 5 );\npump $h until ! length $in;\n\n$t->start( 10 ); ## Give smbclient a little while to shut down.\n$h->finish;\n};\nif ( $@ ) {\nmy $x = $@; ## Preserve $@ in case another exception occurs\n$h->killkill; ## kill it gently, then brutally if need be, or just\n## brutally on Win32.\ndie $x;\n}\n\nTimeouts and timers are *not* checked once the subprocesses are shut down; they will not expire\nin the interval between the last valid process and when IPC::Run scoops up the processes' result\ncodes, for instance.\n" }, { "name": "Spawning synchronization, child exception propagation", "content": "" }, { "name": "start", "content": "any exceptions thrown (including exec() failure) back to the parent. This has several pleasant\neffects: any exceptions thrown in the child, including exec() failure, come flying out of" }, { "name": "start", "content": "This includes exceptions your code thrown from init subs. In this example:\n\neval {\nrun \\@cmd, init => sub { die \"blast it! foiled again!\" };\n};\nprint $@;\n\nthe exception \"blast it! foiled again\" will be thrown from the child process (preventing the" }, { "name": "exec", "content": "In situations like\n\nrun \\@cmd1, \"|\", \\@cmd2, \"|\", \\@cmd3;\n\n@cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before @cmd3. This can save time and\nprevent oddball errors emitted by later commands when earlier commands fail to execute. Note\nthat IPC::Run doesn't start any commands unless it can find the executables referenced by all\ncommands. These executables must pass both the \"-f\" and \"-x\" tests described in perlfunc.\n\nAnother nice effect is that init() subs can take their time doing things and there will be no\nproblems caused by a parent continuing to execute before a child's init() routine is complete.\nSay the init() routine needs to open a socket or a temp file that the parent wants to connect\nto; without this synchronization, the parent will need to implement a retry loop to wait for the\nchild to run, since often, the parent gets a lot of things done before the child's first\ntimeslice is allocated.\n\nThis is also quite necessary for pseudo-tty initialization, which needs to take place before the\nparent writes to the child via pty. Writes that occur before the pty is set up can get lost.\n\nA final, minor, nicety is that debugging output from the child will be emitted before the parent\ncontinues on, making for much clearer debugging output in complex situations.\n\nThe only drawback I can conceive of is that the parent can't continue to operate while the child\nis being initted. If this ever becomes a problem in the field, we can implement an option to\navoid this behavior, but I don't expect it to.\n\nWin32: executing CODE references isn't supported on Win32, see \"Win32 LIMITATIONS\" for details.\n" }, { "name": "Syntax", "content": "" }, { "name": "run", "content": "specification is either a single string to be passed to the systems' shell:\n\nrun \"echo 'hi there'\";\n\nor a list of commands, io operations, and/or timers/timeouts to execute. Consecutive commands\nmust be separated by a pipe operator '|' or an '&'. External commands are passed in as array\nreferences, and, on systems supporting fork(), Perl code may be passed in as subs:\n\nrun \\@cmd;\nrun \\@cmd1, '|', \\@cmd2;\nrun \\@cmd1, '&', \\@cmd2;\nrun \\&sub1;\nrun \\&sub1, '|', \\&sub2;\nrun \\&sub1, '&', \\&sub2;\n\n'|' pipes the stdout of \\@cmd1 the stdin of \\@cmd2, just like a shell pipe. '&' does not. Child\nprocesses to the right of a '&' will have their stdin closed unless it's redirected-to.\n\nIPC::Run::IO objects may be passed in as well, whether or not child processes are also\nspecified:\n\nrun io( \"infile\", \">\", \\$in ), io( \"outfile\", \"<\", \\$in );\n\nas can IPC::Run::Timer objects:\n\nrun \\@cmd, io( \"outfile\", \"<\", \\$in ), timeout( 10 );\n\nCommands may be followed by scalar, sub, or i/o handle references for redirecting child process\ninput & output:\n\nrun \\@cmd, \\undef, \\$out;\nrun \\@cmd, \\$in, \\$out;\nrun \\@cmd1, \\&in, '|', \\@cmd2, \\*OUT;\nrun \\@cmd1, \\*IN, '|', \\@cmd2, \\&out;\n\nThis is known as succinct redirection syntax, since run(), start() and harness(), figure out\nwhich file descriptor to redirect and how. File descriptor 0 is presumed to be an input for the\nchild process, all others are outputs. The assumed file descriptor always starts at 0, unless\nthe command is being piped to, in which case it starts at 1.\n\nTo be explicit about your redirects, or if you need to do more complex things, there's also a\nredirection operator syntax:\n\nrun \\@cmd, '<', \\undef, '>', \\$out;\nrun \\@cmd, '<', \\undef, '>&', \\$outanderr;\nrun(\n\\@cmd1,\n'<', \\$in,\n'|', \\@cmd2,\n\\$out\n);\n\nOperator syntax is required if you need to do something other than simple redirection to/from\nscalars or subs, like duping or closing file descriptors or redirecting to/from a named file.\nThe operators are covered in detail below.\n\nAfter each \\@cmd (or \\&foo), parsing begins in succinct mode and toggles to operator syntax mode\nwhen an operator (ie plain scalar, not a ref) is seen. Once in operator syntax mode, parsing\nonly reverts to succinct mode when a '|' or '&' is seen.\n\nIn succinct mode, each parameter after the \\@cmd specifies what to do with the next highest file\ndescriptor. These File descriptor start with 0 (stdin) unless stdin is being piped to (\"'|',\n\\@cmd\"), in which case they start with 1 (stdout). Currently, being on the left of a pipe\n(\"\\@cmd, \\$out, \\$err, '|'\") does *not* cause stdout to be skipped, though this may change since\nit's not as DWIMerly as it could be. Only stdin is assumed to be an input in succinct mode, all\nothers are assumed to be outputs.\n\nIf no piping or redirection is specified for a child, it will inherit the parent's open file\nhandles as dictated by your system's close-on-exec behavior and the $^F flag, except that\nprocesses after a '&' will not inherit the parent's stdin. Also note that $^F does not affect\nfile descriptors obtained via POSIX, since it only applies to full-fledged Perl file handles.\nSuch processes will have their stdin closed unless it has been redirected-to.\n\nIf you want to close a child processes stdin, you may do any of:\n\nrun \\@cmd, \\undef;\nrun \\@cmd, \\\"\";\nrun \\@cmd, '<&-';\nrun \\@cmd, '0<&-';\n\nRedirection is done by placing redirection specifications immediately after a command or child\nsubroutine:\n\nrun \\@cmd1, \\$in, '|', \\@cmd2, \\$out;\nrun \\@cmd1, '<', \\$in, '|', \\@cmd2, '>', \\$out;\n\nIf you omit the redirection operators, descriptors are counted starting at 0. Descriptor 0 is\nassumed to be input, all others are outputs. A leading '|' consumes descriptor 0, so this works\nas expected.\n\nrun \\@cmd1, \\$in, '|', \\@cmd2, \\$out;\n\nThe parameter following a redirection operator can be a scalar ref, a subroutine ref, a file\nname, an open filehandle, or a closed filehandle.\n\nIf it's a scalar ref, the child reads input from or sends output to that variable:\n\n$in = \"Hello World.\\n\";\nrun \\@cat, \\$in, \\$out;\nprint $out;\n\nScalars used in incremental (start()/pump()/finish()) applications are treated as queues: input\nis removed from input scalers, resulting in them dwindling to '', and output is appended to\noutput scalars. This is not true of harnesses run() in batch mode.\n\nIt's usually wise to append new input to be sent to the child to the input queue, and you'll\noften want to zap output queues to '' before pumping.\n\n$h = start \\@cat, \\$in;\n$in = \"line 1\\n\";\npump $h;\n$in .= \"line 2\\n\";\npump $h;\n$in .= \"line 3\\n\";\nfinish $h;\n\nThe final call to finish() must be there: it allows the child process(es) to run to completion\nand waits for their exit values.\n" } ] }, "OBSTINATE CHILDREN": { "content": "Interactive applications are usually optimized for human use. This can help or hinder trying to\ninteract with them through modules like IPC::Run. Frequently, programs alter their behavior when\nthey detect that stdin, stdout, or stderr are not connected to a tty, assuming that they are\nbeing run in batch mode. Whether this helps or hurts depends on which optimizations change. And\nthere's often no way of telling what a program does in these areas other than trial and error\nand occasionally, reading the source. This includes different versions and implementations of\nthe same program.\n\nAll hope is not lost, however. Most programs behave in reasonably tractable manners, once you\nfigure out what it's trying to do.\n\nHere are some of the issues you might need to be aware of.\n\n* fflush()ing stdout and stderr\n\nThis lets the user see stdout and stderr immediately. Many programs undo this optimization\nif stdout is not a tty, making them harder to manage by things like IPC::Run.\n\nMany programs decline to fflush stdout or stderr if they do not detect a tty there. Some ftp\ncommands do this, for instance.\n\nIf this happens to you, look for a way to force interactive behavior, like a command line\nswitch or command. If you can't, you will need to use a pseudo terminal ('pty>').\n\n* false prompts\n\nInteractive programs generally do not guarantee that output from user commands won't contain\na prompt string. For example, your shell prompt might be a '$', and a file named '$' might\nbe the only file in a directory listing.\n\nThis can make it hard to guarantee that your output parser won't be fooled into early\ntermination of results.\n\nTo help work around this, you can see if the program can alter it's prompt, and use\nsomething you feel is never going to occur in actual practice.\n\nYou should also look for your prompt to be the only thing on a line:\n\npump $h until $out =~ /^\\s?\\z/m;\n\n(use \"(?!\\n)\\Z\" in place of \"\\z\" on older perls).\n\nYou can also take the approach that IPC::ChildSafe takes and emit a command with known\noutput after each 'real' command you issue, then look for this known output. See\nnewappender() and newchunker() for filters that can help with this task.\n\nIf it's not convenient or possibly to alter a prompt or use a known command/response pair,\nyou might need to autodetect the prompt in case the local version of the child program is\ndifferent then the one you tested with, or if the user has control over the look & feel of\nthe prompt.\n\n* Refusing to accept input unless stdin is a tty.\n\nSome programs, for security reasons, will only accept certain types of input from a tty. su,\nnotable, will not prompt for a password unless it's connected to a tty.\n\nIf this is your situation, use a pseudo terminal ('pty>').\n\n* Not prompting unless connected to a tty.\n\nSome programs don't prompt unless stdin or stdout is a tty. See if you can turn prompting\nback on. If not, see if you can come up with a command that you can issue after every real\ncommand and look for it's output, as IPC::ChildSafe does. There are two filters included\nwith IPC::Run that can help with doing this: appender and chunker (see newappender() and\nnewchunker()).\n\n* Different output format when not connected to a tty.\n\nSome commands alter their formats to ease machine parsability when they aren't connected to\na pipe. This is actually good, but can be surprising.\n", "subsections": [] }, "PSEUDO TERMINALS": { "content": "On systems providing pseudo terminals under /dev, IPC::Run can use IO::Pty (available on CPAN)\nto provide a terminal environment to subprocesses. This is necessary when the subprocess really\nwants to think it's connected to a real terminal.\n\nCAVEATS\nPseudo-terminals are not pipes, though they are similar. Here are some differences to watch out\nfor.\n\nEchoing\nSending to stdin will cause an echo on stdout, which occurs before each line is passed to\nthe child program. There is currently no way to disable this, although the child process can\nand should disable it for things like passwords.\n\nShutdown\nIPC::Run cannot close a pty until all output has been collected. This means that it is not\npossible to send an EOF to stdin by half-closing the pty, as we can when using a pipe to\nstdin.\n\nThis means that you need to send the child process an exit command or signal, or run() /\nfinish() will time out. Be careful not to expect a prompt after sending the exit command.\n\nCommand line editing\nSome subprocesses, notable shells that depend on the user's prompt settings, will reissue\nthe prompt plus the command line input so far once for each character.\n\n'>pty>' means '&>pty>', not '1>pty>'\nThe pseudo terminal redirects both stdout and stderr unless you specify a file descriptor.\nIf you want to grab stderr separately, do this:\n\nstart \\@cmd, 'pty>', \\$out, '2>', \\$err;\n\nstdin, stdout, and stderr not inherited\nChild processes harnessed to a pseudo terminal have their stdin, stdout, and stderr\ncompletely closed before any redirection operators take effect. This casts of the bonds of\nthe controlling terminal. This is not done when using pipes.\n\nRight now, this affects all children in a harness that has a pty in use, even if that pty\nwould not affect a particular child. That's a bug and will be fixed. Until it is, it's best\nnot to mix-and-match children.\n", "subsections": [ { "name": "Redirection Operators", "content": "Operator SHNP Description\n======== ==== ===========\n<, N< SHN Redirects input to a child's fd N (0 assumed)\n\n>, N> SHN Redirects output from a child's fd N (1 assumed)\n>>, N>> SHN Like '>', but appends to scalars or named files\n>&, &> SHN Redirects stdout & stderr from a child process\n\npty, N>pty S Like '>', but uses a pseudo-tty instead of a pipe\n\nN<&M Dups input fd N to input fd M\nM>&N Dups output fd N to input fd M\nN<&- Closes fd N\n\npipe, N>pipe P Pipe opens H for caller to read, write, close.\n\n'N' and 'M' are placeholders for integer file descriptor numbers. The terms 'input' and 'output'\nare from the child process's perspective.\n\nThe SHNP field indicates what parameters an operator can take:\n\nS: \\$scalar or \\&function references. Filters may be used with\nthese operators (and only these).\nH: \\*HANDLE or IO::Handle for caller to open, and close\nN: \"file name\".\nP: \\*HANDLE or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read\nand written to and closed by the caller (like IPC::Open3).\n\nRedirecting input: [n]<, [n], [n]>>, [n]>&[m], [n]>pipe\nYou can redirect any output the child emits to a scalar variable, subroutine, file handle,\nor file name. You can have &run truncate or append to named files or scalars. If you are\nredirecting stdin as well, or if the command is on the receiving end of a pipeline ('|'),\nyou can omit the redirection operator:\n\n@ls = ( 'ls' );\nrun \\@ls, \\undef, \\$out\nor die \"ls returned $?\";\n\nrun \\@ls, \\undef, \\&out; ## Calls &out each time some output\n## is received from the child's\n## when undef is returned.\n\nrun \\@ls, \\undef, '2>ls.err';\nrun \\@ls, '2>', 'ls.err';\n\nThe two parameter form guarantees that the filename will not be interpreted as a redirection\noperator:\n\nrun \\@ls, '>', \"&more\";\nrun \\@ls, '2>', \">foo\\n\";\n\nYou can pass file handles you've opened for writing:\n\nopen( *OUT, \">out.txt\" );\nopen( *ERR, \">err.txt\" );\nrun \\@cat, \\*OUT, \\*ERR;\n\nPassing a scalar reference and a code reference requires a little more work, but allows you\nto capture all of the output in a scalar or each piece of output by a callback:\n\nThese two do the same things:\n\nrun( [ 'ls' ], '2>', sub { $errout .= $[0] } );\n\ndoes the same basic thing as:\n\nrun( [ 'ls' ], '2>', \\$errout );\n\nThe subroutine will be called each time some data is read from the child.\n\nThe >pipe operator is different in concept than the other '>' operators, although it's\nsyntax is similar:\n\n$h = start \\@cat, $in, '>pipe', \\*OUT, '2>pipe', \\*ERR;\n$in = \"hello world\\n\";\nfinish $h;\nprint ;\nprint ;\nclose OUT;\nclose ERR;\n\ncauses two pipe to be created, with one end attached to cat's stdout and stderr,\nrespectively, and the other left open on OUT and ERR, so that the script can manually\nread(), select(), etc. on them. This is like the behavior of IPC::Open2 and IPC::Open3.\n\nWin32: The handle returned is actually a socket handle, so you can use select() on it.\n\nDuplicating output descriptors: >&m, n>&m\nThis duplicates output descriptor number n (default is 1 if n is omitted) from descriptor\nnumber m.\n\nDuplicating input descriptors: <&m, n<&m\nThis duplicates input descriptor number n (default is 0 if n is omitted) from descriptor\nnumber m\n\nClosing descriptors: <&-, 3<&-\nThis closes descriptor number n (default is 0 if n is omitted). The following commands are\nequivalent:\n\nrun \\@cmd, \\undef;\nrun \\@cmd, '<&-';\nrun \\@cmd, ', >&, &>pipe, >pipe&\nThe following pairs of commands are equivalent:\n\nrun \\@cmd, '>&', \\$out; run \\@cmd, '>', \\$out, '2>&1';\nrun \\@cmd, '>&', 'out.txt'; run \\@cmd, '>', 'out.txt', '2>&1';\n\netc.\n\nFile descriptor numbers are not permitted to the left or the right of these operators, and\nthe '&' may occur on either end of the operator.\n\nThe '&>pipe' and '>pipe&' variants behave like the '>pipe' operator, except that both stdout\nand stderr write to the created pipe.\n\nRedirection Filters\nBoth input redirections and output redirections that use scalars or subs as endpoints may\nhave an arbitrary number of filter subs placed between them and the child process. This is\nuseful if you want to receive output in chunks, or if you want to massage each chunk of data\nsent to the child. To use this feature, you must use operator syntax:\n\nrun(\n\\@cmd\n'<', \\&infilter2, \\&infilter1, $in,\n'>', \\&outfilter1, \\&infilter2, $out,\n);\n\nThis capability is not provided for IO handles or named files.\n\nTwo filters are provided by IPC::Run: appender and chunker. Because these may take an\nargument, you need to use the constructor functions newappender() and newchunker() rather\nthan using \\& syntax:\n\nrun(\n\\@cmd\n'<', newappender( \"\\n\" ), $in,\n'>', newchunker, $out,\n);\n\nJust doing I/O\nIf you just want to do I/O to a handle or file you open yourself, you may specify a filehandle\nor filename instead of a command in the harness specification:\n\nrun io( \"filename\", '>', \\$recv );\n\n$h = start io( $io, '>', \\$recv );\n\n$h = harness \\@cmd, '&', io( \"file\", '<', \\$send );\n" }, { "name": "Options", "content": "Options are passed in as name/value pairs:\n\nrun \\@cat, \\$in, debug => 1;\n\nIf you pass the debug option, you may want to pass it in first, so you can see what parsing is\ngoing on:\n\nrun debug => 1, \\@cat, \\$in;\n\ndebug\nEnables debugging output in parent and child. Debugging info is emitted to the STDERR that\nwas present when IPC::Run was first \"use()\"ed (it's \"dup()\"ed out of the way so that it can\nbe redirected in children without having debugging output emitted on it).\n" } ] }, "RETURN VALUES": { "content": "", "subsections": [ { "name": "harness", "content": "IPC::Run package, so you may make later calls to functions as members if you like:\n\n$h = harness( ... );\n$h->start;\n$h->pump;\n$h->finish;\n\n$h = start( .... );\n$h->pump;\n...\n\nOf course, using method call syntax lets you deal with any IPC::Run subclasses that might crop\nup, but don't hold your breath waiting for any.\n" }, { "name": "run", "content": "opposite of perl's system() command.\n\nAll routines raise exceptions (via die()) when error conditions are recognized. A non-zero\ncommand result is not treated as an error condition, since some commands are tests whose results\nare reported in their exit codes.\n" } ] }, "ROUTINES": { "content": "run Run takes a harness or harness specification and runs it, pumping all input to the\nchild(ren), closing the input pipes when no more input is available, collecting all\noutput that arrives, until the pipes delivering output are closed, then waiting for the\nchildren to exit and reaping their result codes.\n\nYou may think of \"run( ... )\" as being like\n\nstart( ... )->finish();\n\n, though there is one subtle difference: run() does not set \\$inputscalars to '' like\nfinish() does. If an exception is thrown from run(), all children will be killed off\n\"gently\", and then \"annihilated\" if they do not go gently (in to that dark night.\nsorry).\n\nIf any exceptions are thrown, this does a \"killkill\" before propagating them.\n\nsignal\n## To send it a specific signal by name (\"USR1\"):\nsignal $h, \"USR1\";\n$h->signal ( \"USR1\" );\n\nIf $signal is provided and defined, sends a signal to all child processes. Try not to\nsend numeric signals, use \"KILL\" instead of 9, for instance. Numeric signals aren't\nportable.\n\nThrows an exception if $signal is undef.\n\nThis will *not* clean up the harness, \"finish\" it if you kill it.\n\nNormally TERM kills a process gracefully (this is what the command line utility \"kill\"\ndoes by default), INT is sent by one of the keys \"^C\", \"Backspace\" or \"\", and\n\"QUIT\" is used to kill a process and make it coredump.\n\nThe \"HUP\" signal is often used to get a process to \"restart\", rereading config files,\nand \"USR1\" and \"USR2\" for really application-specific things.\n\nOften, running \"kill -l\" (that's a lower case \"L\") on the command line will list the\nsignals present on your operating system.\n\nWARNING: The signal subsystem is not at all portable. We *may* offer to simulate \"TERM\"\nand \"KILL\" on some operating systems, submit code to me if you want this.\n\nWARNING 2: Up to and including perl v5.6.1, doing almost anything in a signal handler\ncould be dangerous. The most safe code avoids all mallocs and system calls, usually by\npreallocating a flag before entering the signal handler, altering the flag's value in\nthe handler, and responding to the changed value in the main system:\n\nmy $gotusr1 = 0;\nsub usr1handler { ++$gotsignal }\n\n$SIG{USR1} = \\&usr1handler;\nwhile () { sleep 1; print \"GOT IT\" while $gotusr1--; }\n\nEven this approach is perilous if ++ and -- aren't atomic on your system (I've never\nheard of this on any modern CPU large enough to run perl).\n\nkillkill\n## To kill off a process:\n$h->killkill;\nkillkill $h;\n\n## To specify the grace period other than 30 seconds:\nkillkill $h, grace => 5;\n\n## To send QUIT instead of KILL if a process refuses to die:\nkillkill $h, coupdgrace => \"QUIT\";\n\nSends a \"TERM\", waits for all children to exit for up to 30 seconds, then sends a \"KILL\"\nto any that survived the \"TERM\".\n\nWill wait for up to 30 more seconds for the OS to successfully \"KILL\" the processes.\n\nThe 30 seconds may be overridden by setting the \"grace\" option, this overrides both\ntimers.\n\nThe harness is then cleaned up.\n\nThe doubled name indicates that this function may kill again and avoids colliding with\nthe core Perl \"kill\" function.\n\nReturns a 1 if the \"TERM\" was sufficient, or a 0 if \"KILL\" was required. Throws an\nexception if \"KILL\" did not permit the children to be reaped.\n\nNOTE: The grace period is actually up to 1 second longer than that given. This is\nbecause the granularity of \"time\" is 1 second. Let me know if you need finer\ngranularity, we can leverage Time::HiRes here.\n\nWin32: Win32 does not know how to send real signals, so \"TERM\" is a full-force kill on\nWin32. Thus all talk of grace periods, etc. do not apply to Win32.\n\nharness\nTakes a harness specification and returns a harness. This harness is blessed in to\nIPC::Run, allowing you to use method call syntax for run(), start(), et al if you like.\n\nharness() is provided so that you can pre-build harnesses if you would like to, but it's\nnot required..\n\nYou may proceed to run(), start() or pump() after calling harness() (pump() calls\nstart() if need be). Alternatively, you may pass your harness specification to run() or\nstart() and let them harness() for you. You can't pass harness specifications to pump(),\nthough.\n\ncloseterminal\nThis is used as (or in) an init sub to cast off the bonds of a controlling terminal. It\nmust precede all other redirection ops that affect STDIN, STDOUT, or STDERR to be\nguaranteed effective.\n\nstart\n$h = start(\n\\@cmd, \\$in, \\$out, ...,\ntimeout( 30, name => \"process timeout\" ),\n$stalltimeout = timeout( 10, name => \"stall timeout\" ),\n);\n\n$h = start \\@cmd, '<', \\$in, '|', \\@cmd2, ...;\n\nstart() accepts a harness or harness specification and returns a harness after building\nall of the pipes and launching (via fork()/exec(), or, maybe someday, spawn()) all the\nchild processes. It does not send or receive any data on the pipes, see pump() and\nfinish() for that.\n\nYou may call harness() and then pass it's result to start() if you like, but you only\nneed to if it helps you structure or tune your application. If you do call harness(),\nyou may skip start() and proceed directly to pump.\n\nstart() also starts all timers in the harness. See IPC::Run::Timer for more information.\n\nstart() flushes STDOUT and STDERR to help you avoid duplicate output. It has no way of\nasking Perl to flush all your open filehandles, so you are going to need to flush any\nothers you have open. Sorry.\n\nHere's how if you don't want to alter the state of $| for your filehandle:\n\n$ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;\n\nIf you don't mind leaving output unbuffered on HANDLE, you can do the slightly shorter\n\n$ofh = select HANDLE; $| = 1; select $ofh;\n\nOr, you can use IO::Handle's flush() method:\n\nuse IO::Handle;\nflush HANDLE;\n\nPerl needs the equivalent of C's fflush( (FILE *)NULL ).\n\nadopt\nExperimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS BETTER IN CHILDREN. SEE\nt/adopt.t for a test suite.\n\npump\npump $h;\n$h->pump;\n\nPump accepts a single parameter harness. It blocks until it delivers some input or\nreceives some output. It returns TRUE if there is still input or output to be done,\nFALSE otherwise.\n\npump() will automatically call start() if need be, so you may call harness() then\nproceed to pump() if that helps you structure your application.\n\nIf pump() is called after all harnessed activities have completed, a \"process ended\nprematurely\" exception to be thrown. This allows for simple scripting of external\napplications without having to add lots of error handling code at each step of the\nscript:\n\n$h = harness \\@smbclient, \\$in, \\$out, $err;\n\n$in = \"cd /foo\\n\";\n$h->pump until $out =~ /^smb.*> \\Z/m;\ndie \"error cding to /foo:\\n$out\" if $out =~ \"ERR\";\n$out = '';\n\n$in = \"mget *\\n\";\n$h->pump until $out =~ /^smb.*> \\Z/m;\ndie \"error retrieving files:\\n$out\" if $out =~ \"ERR\";\n\n$h->finish;\n\nwarn $err if $err;\n\npumpnb\npumpnb $h;\n$h->pumpnb;\n\n\"pump() non-blocking\", pumps if anything's ready to be pumped, returns immediately\notherwise. This is useful if you're doing some long-running task in the foreground, but\ndon't want to starve any child processes.\n\npumpable\nReturns TRUE if calling pump() won't throw an immediate \"process ended prematurely\"\nexception. This means that there are open I/O channels or active processes. May yield\nthe parent processes' time slice for 0.01 second if all pipes are to the child and all\nare paused. In this case we can't tell if the child is dead, so we yield the processor\nand then attempt to reap the child in a nonblocking way.\n\nreapnb\nAttempts to reap child processes, but does not block.\n\nDoes not currently take any parameters, one day it will allow specific children to be\nreaped.\n\nOnly call this from a signal handler if your \"perl\" is recent enough to have safe signal\nhandling (5.6.1 did not, IIRC, but it was being discussed on perl5-porters). Calling\nthis (or doing any significant work) in a signal handler on older \"perl\"s is asking for\nseg faults.\n\nfinish\nThis must be called after the last start() or pump() call for a harness, or your system\nwill accumulate defunct processes and you may \"leak\" file descriptors.\n\nfinish() returns TRUE if all children returned 0 (and were not signaled and did not\ncoredump, ie ! $?), and FALSE otherwise (this is like run(), and the opposite of\nsystem()).\n\nOnce a harness has been finished, it may be run() or start()ed again, including by\npump()s auto-start.\n\nIf this throws an exception rather than a normal exit, the harness may be left in an\nunstable state, it's best to kill the harness to get rid of all the child processes,\netc.\n\nSpecifically, if a timeout expires in finish(), finish() will not kill all the children.\nCall \"<$h-\"killkill>> in this case if you care. This differs from the behavior of\n\"run\".\n\nresult\n$h->result;\n\nReturns the first non-zero result code (ie $? >> 8). See \"fullresult\" to get the $?\nvalue for a child process.\n\nTo get the result of a particular child, do:\n\n$h->result( 0 ); # first child's $? >> 8\n$h->result( 1 ); # second child\n\nor\n\n($h->results)[0]\n($h->results)[1]\n\nReturns undef if no child processes were spawned and no child number was specified.\nThrows an exception if an out-of-range child number is passed.\n\nresults\nReturns a list of child exit values. See \"fullresults\" if you want to know if a signal\nkilled the child.\n\nThrows an exception if the harness is not in a finished state.\n\nfullresult\n$h->fullresult;\n\nReturns the first non-zero $?. See \"result\" to get the first $? >> 8 value for a child\nprocess.\n\nTo get the result of a particular child, do:\n\n$h->fullresult( 0 ); # first child's $?\n$h->fullresult( 1 ); # second child\n\nor\n\n($h->fullresults)[0]\n($h->fullresults)[1]\n\nReturns undef if no child processes were spawned and no child number was specified.\nThrows an exception if an out-of-range child number is passed.\n\nfullresults\nReturns a list of child exit values as returned by \"wait\". See \"results\" if you don't\ncare about coredumps or signals.\n\nThrows an exception if the harness is not in a finished state.\n", "subsections": [] }, "FILTERS": { "content": "These filters are used to modify input our output between a child process and a scalar or\nsubroutine endpoint.\n\nbinary\nrun \\@cmd, \">\", binary, \\$out;\nrun \\@cmd, \">\", binary, \\$out; ## Any TRUE value to enable\nrun \\@cmd, \">\", binary 0, \\$out; ## Any FALSE value to disable\n\nThis is a constructor for a \"binmode\" \"filter\" that tells IPC::Run to keep the carriage\nreturns that would ordinarily be edited out for you (binmode is usually off). This is not a\nreal filter, but an option masquerading as a filter.\n\nIt's not named \"binmode\" because you're likely to want to call Perl's binmode in programs\nthat are piping binary data around.\n\nnewchunker\nThis breaks a stream of data in to chunks, based on an optional scalar or regular expression\nparameter. The default is the Perl input record separator in $/, which is a newline be\ndefault.\n\nrun \\@cmd, '>', newchunker, \\&lineshandler;\nrun \\@cmd, '>', newchunker( \"\\r\\n\" ), \\&lineshandler;\n\nBecause this uses $/ by default, you should always pass in a parameter if you are worried\nabout other code (modules, etc) modifying $/.\n\nIf this filter is last in a filter chain that dumps in to a scalar, the scalar must be set\nto '' before a new chunk will be written to it.\n\nAs an example of how a filter like this can be written, here's a chunker that splits on\nnewlines:\n\nsub linesplitter {\nmy ( $inref, $outref ) = @;\n\nreturn 0 if length $$outref;\n\nreturn inputavail && do {\nwhile (1) {\nif ( $$inref =~ s/\\A(.*?\\n)// ) {\n$$outref .= $1;\nreturn 1;\n}\nmy $hmm = getmoreinput;\nunless ( defined $hmm ) {\n$$outref = $$inref;\n$$inref = '';\nreturn length $$outref ? 1 : 0;\n}\nreturn 0 if $hmm eq 0;\n}\n}\n};\n\nnewappender\nThis appends a fixed string to each chunk of data read from the source scalar or sub. This\nmight be useful if you're writing commands to a child process that always must end in a\nfixed string, like \"\\n\":\n\nrun( \\@cmd,\n'<', newappender( \"\\n\" ), \\&commands,\n);\n\nHere's a typical filter sub that might be created by newappender():\n\nsub newlineappender {\nmy ( $inref, $outref ) = @;\n\nreturn inputavail && do {\n$$outref = join( '', $$outref, $$inref, \"\\n\" );\n$$inref = '';\n1;\n}\n};\n\nnewstringsource\nTODO: Needs confirmation. Was previously undocumented. in this module.\n\nThis is a filter which is exportable. Returns a sub which appends the data passed in to the\noutput buffer and returns 1 if data was appended. 0 if it was an empty string and undef if\nno data was passed.\n\nNOTE: Any additional variables passed to newstringsource will be passed to the sub every\ntime it's called and appended to the output.\n\nnewstringsink\nTODO: Needs confirmation. Was previously undocumented.\n\nThis is a filter which is exportable. Returns a sub which pops the data out of the input\nstream and pushes it onto the string.\n\nio Takes a filename or filehandle, a redirection operator, optional filters, and a source or\ndestination (depends on the redirection operator). Returns an IPC::Run::IO object suitable\nfor harness()ing (including via start() or run()).\n\nThis is shorthand for\n\nrequire IPC::Run::IO;\n\n... IPC::Run::IO->new(...) ...\n\ntimer\n$h = start( \\@cmd, \\$in, \\$out, $t = timer( 5 ) );\n\npump $h until $out =~ /expected stuff/ || $t->isexpired;\n\nInstantiates a non-fatal timer. pump() returns once each time a timer expires. Has no direct\neffect on run(), but you can pass a subroutine to fire when the timer expires.\n\nSee \"timeout\" for building timers that throw exceptions on expiration.\n\nSee \"timer\" in IPC::Run::Timer for details.\n\ntimeout\n$h = start( \\@cmd, \\$in, \\$out, $t = timeout( 5 ) );\n\npump $h until $out =~ /expected stuff/;\n\nInstantiates a timer that throws an exception when it expires. If you don't provide an\nexception, a default exception that matches /^IPC::Run: .*timed out/ is thrown by default.\nYou can pass in your own exception scalar or reference:\n\n$h = start(\n\\@cmd, \\$in, \\$out,\n$t = timeout( 5, exception => 'slowpoke' ),\n);\n\nor set the name used in debugging message and in the default exception string:\n\n$h = start(\n\\@cmd, \\$in, \\$out,\ntimeout( 50, name => 'process timer' ),\n$stalltimer = timeout( 5, name => 'stall timer' ),\n);\n\npump $h until $out =~ /started/;\n\n$in = 'command 1';\n$stalltimer->start;\npump $h until $out =~ /command 1 finished/;\n\n$in = 'command 2';\n$stalltimer->start;\npump $h until $out =~ /command 2 finished/;\n\n$in = 'very slow command 3';\n$stalltimer->start( 10 );\npump $h until $out =~ /command 3 finished/;\n\n$stalltimer->start( 5 );\n$in = 'command 4';\npump $h until $out =~ /command 4 finished/;\n\n$stalltimer->reset; # Prevent restarting or expirng\nfinish $h;\n\nSee \"timer\" for building non-fatal timers.\n\nSee \"timer\" in IPC::Run::Timer for details.\n", "subsections": [] }, "FILTER IMPLEMENTATION FUNCTIONS": { "content": "These functions are for use from within filters.\n\ninputavail\nReturns TRUE if input is available. If none is available, then &getmoreinput is called and\nits result is returned.\n\nThis is usually used in preference to &getmoreinput so that the calling filter removes all\ndata from the $inref before more data gets read in to $inref.\n\n\"inputavail\" is usually used as part of a return expression:\n\nreturn inputavail && do {\n## process the input just gotten\n1;\n};\n\nThis technique allows inputavail to return the undef or 0 that a filter normally returns\nwhen there's no input to process. If a filter stores intermediate values, however, it will\nneed to react to an undef:\n\nmy $got = inputavail;\nif ( ! defined $got ) {\n## No more input ever, flush internal buffers to $outref\n}\nreturn $got unless $got;\n## Got some input, move as much as need be\nreturn 1 if $addedtooutref;\n\ngetmoreinput\nThis is used to fetch more input in to the input variable. It returns undef if there will\nnever be any more input, 0 if there is none now, but there might be in the future, and TRUE\nif more input was gotten.\n\n\"getmoreinput\" is usually used as part of a return expression, see \"inputavail\" for more\ninformation.\n", "subsections": [] }, "TODO": { "content": "Allow one harness to \"adopt\" another:\n$newh = harness \\@cmd2;\n$h->adopt( $newh );\n\nClose all filehandles not explicitly marked to stay open.\nThe problem with this one is that there's no good way to scan all open FILEHANDLEs in Perl,\nyet you don't want child processes inheriting handles willy-nilly.\n", "subsections": [] }, "Win32 LIMITATIONS": { "content": "Fails on Win9X\nIf you want Win9X support, you'll have to debug it or fund me because I don't use that\nsystem any more. The Win32 subsysem has been extended to use temporary files in simple run()\ninvocations and these may actually work on Win9X too, but I don't have time to work on it.\n\nMay deadlock on Win2K (but not WinNT4 or WinXPPro)\nSpawning more than one subprocess on Win2K causes a deadlock I haven't figured out yet, but\nsimple uses of run() often work. Passes all tests on WinXPPro and WinNT.\n\nno support yet for pty>\nThese are likely to be implemented as \"<\" and \">\" with binmode on, not sure.\n\nno support for file descriptors higher than 2 (stderr)\nWin32 only allows passing explicit fds 0, 1, and 2. If you really, really need to pass file\nhandles, us Win32API:: GetOsFHandle() or ::FdGetOsFHandle() to get the integer handle and\npass it to the child process using the command line, environment, stdin, intermediary file,\nor other IPC mechanism. Then use that handle in the child (Win32API.pm provides ways to\nreconstitute Perl file handles from Win32 file handles).\n\nno support for subroutine subprocesses (CODE refs)\nCan't fork(), so the subroutines would have no context, and closures certainly have no\nmeaning\n\nPerhaps with Win32 fork() emulation, this can be supported in a limited fashion, but there\nare other very serious problems with that: all parent fds get dup()ed in to the thread\nemulating the forked process, and that keeps the parent from being able to close all of the\nappropriate fds.\n\nno support for init => sub {} routines.\nWin32 processes are created from scratch, there is no way to do an init routine that will\naffect the running child. Some limited support might be implemented one day, do chdir() and\n%ENV changes can be made.\n\nsignals\nWin32 does not fully support signals. signal() is likely to cause errors unless sending a\nsignal that Perl emulates, and \"killkill()\" is immediately fatal (there is no grace\nperiod).\n\nhelper processes\nIPC::Run uses helper processes, one per redirected file, to adapt between the anonymous pipe\nconnected to the child and the TCP socket connected to the parent. This is a waste of\nresources and will change in the future to either use threads (instead of helper processes)\nor a WaitForMultipleObjects call (instead of select). Please contact me if you can help with\nthe WaitForMultipleObjects() approach; I haven't figured out how to get at it without C\ncode.\n\nshutdown pause\nThere seems to be a pause of up to 1 second between when a child program exits and the\ncorresponding sockets indicate that they are closed in the parent. Not sure why.\n\nbinmode\nbinmode is not supported yet. The underpinnings are implemented, just ask if you need it.\n\nIPC::Run::IO\nIPC::Run::IO objects can be used on Unix to read or write arbitrary files. On Win32, they\nwill need to use the same helper processes to adapt from non-select()able filehandles to\nselect()able ones (or perhaps WaitForMultipleObjects() will work with them, not sure).\n\nstartup race conditions\nThere seems to be an occasional race condition between child process startup and pipe\nclosings. It seems like if the child is not fully created by the time CreateProcess returns\nand we close the TCP socket being handed to it, the parent socket can also get closed. This\nis seen with the Win32 pumper applications, not the \"real\" child process being spawned.\n\nI assume this is because the kernel hasn't gotten around to incrementing the reference count\non the child's end (since the child was slow in starting), so the parent's closing of the\nchild end causes the socket to be closed, thus closing the parent socket.\n\nBeing a race condition, it's hard to reproduce, but I encountered it while testing this code\non a drive share to a samba box. In this case, it takes t/run.t a long time to spawn it's\nchild processes (the parent hangs in the first select for several seconds until the child\nemits any debugging output).\n\nI have not seen it on local drives, and can't reproduce it at will, unfortunately. The\nsymptom is a \"bad file descriptor in select()\" error, and, by turning on debugging, it's\npossible to see that select() is being called on a no longer open file descriptor that was\nreturned from the socket() routine in Win32Helper. There's a new confess() that checks for\nthis (\"PARENTHANDLE no longer open\"), but I haven't been able to reproduce it (typically).\n", "subsections": [] }, "LIMITATIONS": { "content": "On Unix, requires a system that supports \"waitpid( $pid, WNOHANG )\" so it can tell if a child\nprocess is still running.\n\nPTYs don't seem to be non-blocking on some versions of Solaris. Here's a test script contributed\nby Borislav Deianov to see if you have the problem. If it dies, you have\nthe problem.\n\n#!/usr/bin/perl\n\nuse IPC::Run qw(run);\nuse Fcntl;\nuse IO::Pty;\n\nsub makecmd {\nreturn ['perl', '-e',\n', print \"\\n\" x '.$[0].'; while(){last if /end/}'];\n}\n\n#pipe R, W;\n#fcntl(W, FSETFL, ONONBLOCK);\n#while (syswrite(W, \"\\n\", 1)) { $pipebuf++ };\n#print \"pipe buffer size is $pipebuf\\n\";\nmy $pipebuf=4096;\nmy $in = \"\\n\" x ($pipebuf * 2) . \"end\\n\";\nmy $out;\n\n$SIG{ALRM} = sub { die \"Never completed!\\n\" };\n\nprint \"reading from scalar via pipe...\";\nalarm( 2 );\nrun(makecmd($pipebuf * 2), '<', \\$in, '>', \\$out);\nalarm( 0 );\nprint \"done\\n\";\n\nprint \"reading from code via pipe... \";\nalarm( 2 );\nrun(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \\$out);\nalarm( 0 );\nprint \"done\\n\";\n\n$pty = IO::Pty->new();\n$pty->blocking(0);\n$slave = $pty->slave();\nwhile ($pty->syswrite(\"\\n\", 1)) { $ptybuf++ };\nprint \"pty buffer size is $ptybuf\\n\";\n$in = \"\\n\" x ($ptybuf * 3) . \"end\\n\";\n\nprint \"reading via pty... \";\nalarm( 2 );\nrun(makecmd($ptybuf * 3), '', \\$out);\nalarm(0);\nprint \"done\\n\";\n\nNo support for ';', '&&', '||', '{ ... }', etc: use perl's, since run() returns TRUE when the\ncommand exits with a 0 result code.\n\nDoes not provide shell-like string interpolation.\n\nNo support for \"cd\", \"setenv\", or \"export\": do these in an init() sub\n\nrun(\n\\cmd,\n...\ninit => sub {\nchdir $dir or die $!;\n$ENV{FOO}='BAR'\n}\n);\n\nTimeout calculation does not allow absolute times, or specification of days, months, etc.\n\nWARNING: Function coprocesses (\"run \\&foo, ...\") suffer from two limitations. The first is that\nit is difficult to close all filehandles the child inherits from the parent, since there is no\nway to scan all open FILEHANDLEs in Perl and it both painful and a bit dangerous to close all\nopen file descriptors with \"POSIX::close()\". Painful because we can't tell which fds are open at\nthe POSIX level, either, so we'd have to scan all possible fds and close any that we don't want\nopen (normally \"exec()\" closes any non-inheritable but we don't \"exec()\" for &sub processes.\n\nThe second problem is that Perl's DESTROY subs and other on-exit cleanup gets run in the child\nprocess. If objects are instantiated in the parent before the child is forked, the DESTROY will\nget run once in the parent and once in the child. When coprocess subs exit, POSIX::exit is\ncalled to work around this, but it means that objects that are still referred to at that time\nare not cleaned up. So setting package vars or closure vars to point to objects that rely on\nDESTROY to affect things outside the process (files, etc), will lead to bugs.\n\nI goofed on the syntax: \"filename\" are both oddities.\n", "subsections": [] }, "INSPIRATION": { "content": "Well, select() and waitpid() badly needed wrapping, and open3() isn't open-minded enough for me.\n\nThe shell-like API inspired by a message Russ Allbery sent to perl5-porters, which included:\n\nI've thought for some time that it would be\nnice to have a module that could handle full Bourne shell pipe syntax\ninternally, with fork and exec, without ever invoking a shell. Something\nthat you could give things like:\n\npipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');\n\nMessage ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.\n", "subsections": [] }, "SUPPORT": { "content": "Bugs should always be submitted via the GitHub bug tracker\n\n\n", "subsections": [] }, "AUTHORS": { "content": "Adam Kennedy \n\nBarrie Slaymaker \n", "subsections": [] }, "COPYRIGHT": { "content": "Some parts copyright 2008 - 2009 Adam Kennedy.\n\nCopyright 1999 Barrie Slaymaker.\n\nYou may distribute under the terms of either the GNU General Public License or the Artistic\nLicense, as specified in the README file.\n", "subsections": [] } } } }