{ "content": [ { "type": "text", "text": "# IPC::Run (info)\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\nfiles, pipes, and pseudo-ttys. Both system()-style and scripted usages\nare supported and may be mixed. Likewise, functional and OO API styles\nare both supported and may be mixed.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OBSTINATE CHILDREN**\n- **PSEUDO TERMINALS**\n- **RETURN VALUES**\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": "info", "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": 3, "subsections": [] }, { "name": "SYNOPSIS", "lines": 101, "subsections": [] }, { "name": "DESCRIPTION", "lines": 414, "subsections": [] }, { "name": "OBSTINATE CHILDREN", "lines": 84, "subsections": [] }, { "name": "PSEUDO TERMINALS", "lines": 312, "subsections": [] }, { "name": "RETURN VALUES", "lines": 25, "subsections": [] }, { "name": "ROUTINES", "lines": 309, "subsections": [] }, { "name": "FILTERS", "lines": 173, "subsections": [] }, { "name": "FILTER IMPLEMENTATION FUNCTIONS", "lines": 39, "subsections": [] }, { "name": "TODO", "lines": 9, "subsections": [] }, { "name": "Win32 LIMITATIONS", "lines": 97, "subsections": [] }, { "name": "LIMITATIONS", "lines": 94, "subsections": [] }, { "name": "INSPIRATION", "lines": 15, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix,\nWin32)\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# 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\nfiles, pipes, and pseudo-ttys. Both system()-style and scripted usages\nare supported and may be mixed. Likewise, functional and OO API styles\nare both supported and may be mixed.\n\nVarious redirection operators reminiscent of those seen on common Unix\nand DOS command lines are provided.\n\nBefore digging in to the details a few LIMITATIONS are important enough\nto be mentioned right up front:\n\nWin32 Support\nWin32 support is working but EXPERIMENTAL, but does pass all\nrelevant tests on NT 4.0. See \"Win32 LIMITATIONS\".\n\npty Support\nIf you need pty support, IPC::Run should work well enough most of\nthe time, but IO::Pty is being improved, and IPC::Run will be\nimproved to use IO::Pty's new features when it is release.\n\nThe basic problem is that the pty needs to initialize itself before\nthe parent writes to the master pty, or the data written gets lost.\nSo IPC::Run does a sleep(1) in the parent after forking to\n(hopefully) give the child a chance to run. This is a kludge that\nworks well on non 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\ngoing 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\nHarnesses\nChild processes and I/O handles are gathered in to a harness, then\nstarted and run until the processing is finished or aborted.\n\nrun() vs. start(); pump(); finish();\nThere are two modes you can run harnesses in: run() functions as an\nenhanced system(), and start()/pump()/finish() allow for background\nprocesses and scripted interactions with them.\n\nWhen using run(), all data to be sent to the harness is set up in\nadvance (though one can feed subprocesses input from subroutine refs to\nget around this limitation). The harness is run and all output is\ncollected 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\ncycle? That's because IPC::Run does not delete $out when we continue,\nand we don't want to trip over the old output in the second\ncommand/response cycle.\n\nSay you want to accumulate all the output in $out and analyze it\nafterwards. Perl offers incremental regular expression matching using\nthe \"m//gc\" and pattern matching idiom and the \"\\G\" assertion.\nIPC::Run is careful not to disturb the current \"pos()\" value for\nscalars it appends data to, so we could modify the above so as not to\ndestroy $out by adding a couple of \"/gc\" modifiers. The \"/g\" keeps us\nfrom tripping over the previous prompt and the \"/c\" keeps us from\nresetting the prior match position if the expected prompt doesn't\nmaterialize 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\nplenty of memory or you may find that the act of growing $out each time\nnew input arrives causes an \"O(length($out)^2)\" slowdown as $out grows.\nSay 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\nmark the $out as having 0 length without freeing all that yummy RAM.\n\nTimeouts and Timers\nMore than likely, you don't want your subprocesses to run forever, and\nsometimes it's nice to know that they're going a little slowly.\nTimeouts throw exceptions after a some time has elapsed, timers merely\ncause pump() to return after some time has elapsed. Neither is\nreset/restarted automatically.\n\nTimeout objects are created by calling timeout( $interval ) and passing\nthe result to run(), start() or harness(). The timeout period starts\nticking just after all the child processes have been fork()ed or\nspawn()ed, and are polled for expiration in run(), pump() and finish().\nIf/when they expire, an exception is thrown. This is typically useful\nto keep a subprocess from taking too long.\n\nIf a timeout occurs in run(), all child processes will be terminated\nand all file/pipe/ptty descriptors opened by run() will be closed.\nFile descriptors opened by the parent process and passed in to run()\nare not closed in this event.\n\nIf a timeout occurs in pump(), pumpnb(), or finish(), it's up to you\nto decide whether to killkill() all the children or to implement some\nmore graceful fallback. No I/O will be closed in pump(), pumpnb() or\nfinish() 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\nobjects that merely prevent pump() from blocking forever. This can be\nuseful for detecting stalled I/O or printing a soothing message or \".\"\nto pacify an anxious user.\n\nTimeouts and timers can both be restarted at any time using the timer's\nstart() method (this is not the start() that launches subprocesses).\nTo restart a timer, you need to keep a reference to the 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\ndown; they will not expire in the interval between the last valid\nprocess and when IPC::Run scoops up the processes' result codes, for\ninstance.\n\nSpawning synchronization, child exception propagation\nstart() pauses the parent until the child executes the command or CODE\nreference and propagates any exceptions thrown (including exec()\nfailure) back to the parent. This has several pleasant effects: any\nexceptions thrown in the child, including exec() failure, come flying\nout of start() or run() as though they had occurred in the parent.\n\nThis includes exceptions your code thrown from init subs. In this\nexample:\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\nprocess (preventing the exec()) and printed by the parent.\n\nIn situations like\n\nrun \\@cmd1, \"|\", \\@cmd2, \"|\", \\@cmd3;\n\n@cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before\n@cmd3. This can save time and prevent oddball errors emitted by later\ncommands when earlier commands fail to execute. Note that IPC::Run\ndoesn't start any commands unless it can find the executables\nreferenced by all commands. These executables must pass both the \"-f\"\nand \"-x\" tests described in perlfunc.\n\nAnother nice effect is that init() subs can take their time doing\nthings and there will be no problems caused by a parent continuing to\nexecute before a child's init() routine is complete. Say the init()\nroutine needs to open a socket or a temp file that the parent wants to\nconnect to; without this synchronization, the parent will need to\nimplement a retry loop to wait for the child to run, since often, the\nparent gets a lot of things done before the child's first timeslice is\nallocated.\n\nThis is also quite necessary for pseudo-tty initialization, which needs\nto take place before the parent writes to the child via pty. Writes\nthat occur before the pty is set up can get lost.\n\nA final, minor, nicety is that debugging output from the child will be\nemitted before the parent continues on, making for much clearer\ndebugging output in complex situations.\n\nThe only drawback I can conceive of is that the parent can't continue\nto operate while the child is being initted. If this ever becomes a\nproblem in the field, we can implement an option to avoid this\nbehavior, but I don't expect it to.\n\nWin32: executing CODE references isn't supported on Win32, see \"Win32\nLIMITATIONS\" for details.\n\nSyntax\nrun(), start(), and harness() can all take a harness specification as\ninput. A harness specification is either a single string to be passed\nto the systems' shell:\n\nrun \"echo 'hi there'\";\n\nor a list of commands, io operations, and/or timers/timeouts to\nexecute. Consecutive commands must be separated by a pipe operator '|'\nor an '&'. External commands are passed in as array references, and,\non 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\npipe. '&' does not. Child processes to the right of a '&' will have\ntheir stdin closed unless it's redirected-to.\n\nIPC::Run::IO objects may be passed in as well, whether or not child\nprocesses are also specified:\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\nredirecting child process input & 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\nharness(), figure out which file descriptor to redirect and how. File\ndescriptor 0 is presumed to be an input for the child process, all\nothers are outputs. The assumed file descriptor always starts at 0,\nunless the 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\nthings, there's also a redirection 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\nsimple redirection to/from scalars or subs, like duping or closing file\ndescriptors or redirecting to/from a named file. The operators are\ncovered in detail below.\n\nAfter each \\@cmd (or \\&foo), parsing begins in succinct mode and\ntoggles to operator syntax mode when an operator (ie plain scalar, not\na ref) is seen. Once in operator syntax mode, parsing only reverts to\nsuccinct mode when a '|' or '&' is seen.\n\nIn succinct mode, each parameter after the \\@cmd specifies what to do\nwith the next highest file descriptor. These File descriptor start with\n0 (stdin) unless stdin is being piped to (\"'|', \\@cmd\"), in which case\nthey start with 1 (stdout). Currently, being on the left of a pipe\n(\"\\@cmd, \\$out, \\$err, '|'\") does not cause stdout to be skipped,\nthough this may change since it's not as DWIMerly as it could be. Only\nstdin is assumed to be an input in succinct mode, all others are\nassumed to be outputs.\n\nIf no piping or redirection is specified for a child, it will inherit\nthe parent's open file handles as dictated by your system's close-on-\nexec behavior and the $^F flag, except that processes after a '&' will\nnot inherit the parent's stdin. Also note that $^F does not affect file\ndescriptors obtained via POSIX, since it only applies to full-fledged\nPerl file handles. Such processes will have their stdin closed unless\nit 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\nafter a command or child subroutine:\n\nrun \\@cmd1, \\$in, '|', \\@cmd2, \\$out;\nrun \\@cmd1, '<', \\$in, '|', \\@cmd2, '>', \\$out;\n\nIf you omit the redirection operators, descriptors are counted starting\nat 0. Descriptor 0 is assumed to be input, all others are outputs. A\nleading '|' consumes descriptor 0, so this works as expected.\n\nrun \\@cmd1, \\$in, '|', \\@cmd2, \\$out;\n\nThe parameter following a redirection operator can be a scalar ref, a\nsubroutine ref, a file name, an open filehandle, or a closed\nfilehandle.\n\nIf it's a scalar ref, the child reads input from or sends output to\nthat variable:\n\n$in = \"Hello World.\\n\";\nrun \\@cat, \\$in, \\$out;\nprint $out;\n\nScalars used in incremental (start()/pump()/finish()) applications are\ntreated as queues: input is removed from input scalers, resulting in\nthem dwindling to '', and output is appended to output scalars. This\nis 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\ninput queue, and you'll often want to zap output queues to '' before\npumping.\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\nprocess(es) to run to completion and waits for their exit values.\n", "subsections": [] }, "OBSTINATE CHILDREN": { "content": "Interactive applications are usually optimized for human use. This can\nhelp or hinder trying to interact with them through modules like\nIPC::Run. Frequently, programs alter their behavior when they detect\nthat stdin, stdout, or stderr are not connected to a tty, assuming that\nthey are being run in batch mode. Whether this helps or hurts depends\non which optimizations change. And there's often no way of telling\nwhat a program does in these areas other than trial and error and\noccasionally, reading the source. This includes different versions and\nimplementations of the same program.\n\nAll hope is not lost, however. Most programs behave in reasonably\ntractable manners, once you figure out what it's trying to do.\n\nHere are some of the issues you might need to be aware of.\n\no fflush()ing stdout and stderr\n\nThis lets the user see stdout and stderr immediately. Many\nprograms undo this optimization if stdout is not a tty, making them\nharder to manage by things like IPC::Run.\n\nMany programs decline to fflush stdout or stderr if they do not\ndetect a tty there. Some ftp commands do this, for instance.\n\nIf this happens to you, look for a way to force interactive\nbehavior, like a command line switch or command. If you can't, you\nwill need to use a pseudo terminal ('pty>').\n\no false prompts\n\nInteractive programs generally do not guarantee that output from\nuser commands won't contain a prompt string. For example, your\nshell prompt might be a '$', and a file named '$' might be the only\nfile in a directory listing.\n\nThis can make it hard to guarantee that your output parser won't be\nfooled into early termination of results.\n\nTo help work around this, you can see if the program can alter it's\nprompt, and use something you feel is never going to occur in\nactual practice.\n\nYou should also look for your prompt to be the only thing on a\nline:\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\ncommand with known output after each 'real' command you issue, then\nlook for this known output. See newappender() and newchunker()\nfor filters that can help with this task.\n\nIf it's not convenient or possibly to alter a prompt or use a known\ncommand/response pair, you might need to autodetect the prompt in\ncase the local version of the child program is different then the\none you tested with, or if the user has control over the look &\nfeel of the prompt.\n\no Refusing to accept input unless stdin is a tty.\n\nSome programs, for security reasons, will only accept certain types\nof input from a tty. su, notable, will not prompt for a password\nunless it's connected to a tty.\n\nIf this is your situation, use a pseudo terminal ('pty>').\n\no Not prompting unless connected to a tty.\n\nSome programs don't prompt unless stdin or stdout is a tty. See if\nyou can turn prompting back on. If not, see if you can come up\nwith a command that you can issue after every real command and look\nfor it's output, as IPC::ChildSafe does. There are two filters\nincluded with IPC::Run that can help with doing this: appender and\nchunker (see newappender() and newchunker()).\n\no Different output format when not connected to a tty.\n\nSome commands alter their formats to ease machine parsability when\nthey aren't connected to a pipe. This is actually good, but can be\nsurprising.\n", "subsections": [] }, "PSEUDO TERMINALS": { "content": "On systems providing pseudo terminals under /dev, IPC::Run can use\nIO::Pty (available on CPAN) to provide a terminal environment to\nsubprocesses. This is necessary when the subprocess really wants to\nthink it's connected to a real terminal.\n\nCAVEATS\nPseudo-terminals are not pipes, though they are similar. Here are some\ndifferences to watch out for.\n\nEchoing\nSending to stdin will cause an echo on stdout, which occurs before\neach line is passed to the child program. There is currently no\nway to disable this, although the child process can and should\ndisable it for things like passwords.\n\nShutdown\nIPC::Run cannot close a pty until all output has been collected.\nThis means that it is not possible to send an EOF to stdin by half-\nclosing the pty, as we can when using a pipe to stdin.\n\nThis means that you need to send the child process an exit command\nor signal, or run() / finish() will time out. Be careful not to\nexpect a prompt after sending the exit command.\n\nCommand line editing\nSome subprocesses, notable shells that depend on the user's prompt\nsettings, will reissue the prompt plus the command line input so\nfar once for each character.\n\n'>pty>' means '&>pty>', not '1>pty>'\nThe pseudo terminal redirects both stdout and stderr unless you\nspecify a file descriptor. If you want to grab stderr separately,\ndo 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,\nstdout, and stderr completely closed before any redirection\noperators take effect. This casts of the bonds of the controlling\nterminal. This is not done when using pipes.\n\nRight now, this affects all children in a harness that has a pty in\nuse, even if that pty would not affect a particular child. That's\na bug and will be fixed. Until it is, it's best not to mix-and-\nmatch children.\n\nRedirection Operators\nOperator 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\nterms 'input' and 'output' are 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,\nsubroutine, file handle, or file name. You can have &run truncate\nor append to named files or scalars. If you are redirecting stdin\nas well, or if the command is on the receiving end of a pipeline\n('|'), you 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\ninterpreted as a redirection operator:\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\nmore work, but allows you to capture all of the output in a scalar\nor 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\nchild.\n\nThe >pipe operator is different in concept than the other '>'\noperators, although it's syntax 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\nstdout and stderr, respectively, and the other left open on OUT and\nERR, so that the script can manually read(), select(), etc. on\nthem. This is like the behavior of IPC::Open2 and IPC::Open3.\n\nWin32: The handle returned is actually a socket handle, so you can\nuse select() on it.\n\nDuplicating output descriptors: >&m, n>&m\nThis duplicates output descriptor number n (default is 1 if n is\nomitted) from descriptor number m.\n\nDuplicating input descriptors: <&m, n<&m\nThis duplicates input descriptor number n (default is 0 if n is\nomitted) from descriptor number m\n\nClosing descriptors: <&-, 3<&-\nThis closes descriptor number n (default is 0 if n is omitted).\nThe following commands are equivalent:\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\nof these operators, and the '&' may occur on either end of the\noperator.\n\nThe '&>pipe' and '>pipe&' variants behave like the '>pipe'\noperator, except that both stdout and stderr write to the created\npipe.\n\nRedirection Filters\nBoth input redirections and output redirections that use scalars or\nsubs as endpoints may have an arbitrary number of filter subs\nplaced between them and the child process. This is useful if you\nwant to receive output in chunks, or if you want to massage each\nchunk of data sent to the child. To use this feature, you must use\noperator 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.\nBecause these may take an argument, you need to use the constructor\nfunctions newappender() and newchunker() rather than using \\&\nsyntax:\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\nmay specify a filehandle or filename instead of a command in the\nharness specification:\n\nrun io( \"filename\", '>', \\$recv );\n\n$h = start io( $io, '>', \\$recv );\n\n$h = harness \\@cmd, '&', io( \"file\", '<', \\$send );\n\nOptions\nOptions 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\ncan see what parsing is going on:\n\nrun debug => 1, \\@cat, \\$in;\n\ndebug\nEnables debugging output in parent and child. Debugging info is\nemitted to the STDERR that was present when IPC::Run was first\n\"use()\"ed (it's \"dup()\"ed out of the way so that it can be\nredirected in children without having debugging output emitted on\nit).\n", "subsections": [] }, "RETURN VALUES": { "content": "harness() and start() return a reference to an IPC::Run harness. This\nis blessed in to the IPC::Run package, so you may make later calls to\nfunctions 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\nsubclasses that might crop up, but don't hold your breath waiting for\nany.\n\nrun() and finish() return TRUE when all subcommands exit with a 0\nresult code. This is the opposite of perl's system() command.\n\nAll routines raise exceptions (via die()) when error conditions are\nrecognized. A non-zero command result is not treated as an error\ncondition, since some commands are tests whose results are reported in\ntheir exit codes.\n", "subsections": [] }, "ROUTINES": { "content": "run Run takes a harness or harness specification and runs it,\npumping all input to the child(ren), closing the input pipes\nwhen no more input is available, collecting all output that\narrives, until the pipes delivering output are closed, then\nwaiting for the children to exit and reaping their result\ncodes.\n\nYou may think of \"run( ... )\" as being like\n\nstart( ... )->finish();\n\n, though there is one subtle difference: run() does not set\n\\$inputscalars to '' like finish() does. If an exception is\nthrown from run(), all children will be killed off \"gently\",\nand then \"annihilated\" if they do not go gently (in to that\ndark night. sorry).\n\nIf any exceptions are thrown, this does a \"killkill\" before\npropagating 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\nprocesses. Try not to send numeric signals, use \"KILL\" instead\nof 9, for instance. Numeric signals aren't portable.\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\ncommand line utility \"kill\" does by default), INT is sent by\none of the keys \"^C\", \"Backspace\" or \"\", and \"QUIT\" is\nused to kill a process and make it coredump.\n\nThe \"HUP\" signal is often used to get a process to \"restart\",\nrereading config files, and \"USR1\" and \"USR2\" for really\napplication-specific things.\n\nOften, running \"kill -l\" (that's a lower case \"L\") on the\ncommand line will list the signals present on your operating\nsystem.\n\nWARNING: The signal subsystem is not at all portable. We *may*\noffer to simulate \"TERM\" and \"KILL\" on some operating systems,\nsubmit code to me if you want this.\n\nWARNING 2: Up to and including perl v5.6.1, doing almost\nanything in a signal handler could be dangerous. The most safe\ncode avoids all mallocs and system calls, usually by\npreallocating a flag before entering the signal handler,\naltering the flag's value in the handler, and responding to the\nchanged 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\nyour system (I've never heard of this on any modern CPU large\nenough 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\nseconds, then sends a \"KILL\" to any that survived the \"TERM\".\n\nWill wait for up to 30 more seconds for the OS to successfully\n\"KILL\" the processes.\n\nThe 30 seconds may be overridden by setting the \"grace\" option,\nthis overrides both timers.\n\nThe harness is then cleaned up.\n\nThe doubled name indicates that this function may kill again\nand avoids colliding with the core Perl \"kill\" function.\n\nReturns a 1 if the \"TERM\" was sufficient, or a 0 if \"KILL\" was\nrequired. Throws an exception if \"KILL\" did not permit the\nchildren to be reaped.\n\nNOTE: The grace period is actually up to 1 second longer than\nthat given. This is because the granularity of \"time\" is 1\nsecond. Let me know if you need finer granularity, we can\nleverage Time::HiRes here.\n\nWin32: Win32 does not know how to send real signals, so \"TERM\"\nis a full-force kill on Win32. Thus all talk of grace periods,\netc. do not apply to Win32.\n\nharness\nTakes a harness specification and returns a harness. This\nharness is blessed in to IPC::Run, allowing you to use method\ncall syntax for run(), start(), et al if you like.\n\nharness() is provided so that you can pre-build harnesses if\nyou would like to, but it's not required..\n\nYou may proceed to run(), start() or pump() after calling\nharness() (pump() calls start() if need be). Alternatively,\nyou may pass your harness specification to run() or start() and\nlet them harness() for you. You can't pass harness\nspecifications to pump(), though.\n\ncloseterminal\nThis is used as (or in) an init sub to cast off the bonds of a\ncontrolling terminal. It must precede all other redirection\nops that affect STDIN, STDOUT, or STDERR to be guaranteed\neffective.\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\na harness after building all of the pipes and launching (via\nfork()/exec(), or, maybe someday, spawn()) all the child\nprocesses. It does not send or receive any data on the pipes,\nsee pump() and finish() for that.\n\nYou may call harness() and then pass it's result to start() if\nyou like, but you only need to if it helps you structure or\ntune your application. If you do call harness(), you may skip\nstart() and proceed directly to pump.\n\nstart() also starts all timers in the harness. See\nIPC::Run::Timer for more information.\n\nstart() flushes STDOUT and STDERR to help you avoid duplicate\noutput. It has no way of asking Perl to flush all your open\nfilehandles, so you are going to need to flush any others you\nhave open. Sorry.\n\nHere's how if you don't want to alter the state of $| for your\nfilehandle:\n\n$ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;\n\nIf you don't mind leaving output unbuffered on HANDLE, you can\ndo 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\nBETTER IN CHILDREN. SEE t/adopt.t for a test suite.\n\npump\npump $h;\n$h->pump;\n\nPump accepts a single parameter harness. It blocks until it\ndelivers some input or receives some output. It returns TRUE\nif there is still input or output to be done, FALSE otherwise.\n\npump() will automatically call start() if need be, so you may\ncall harness() then proceed to pump() if that helps you\nstructure your application.\n\nIf pump() is called after all harnessed activities have\ncompleted, a \"process ended prematurely\" exception to be\nthrown. This allows for simple scripting of external\napplications without having to add lots of error handling code\nat each step of the script:\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,\nreturns immediately otherwise. This is useful if you're doing\nsome long-running task in the foreground, but don't want to\nstarve any child processes.\n\npumpable\nReturns TRUE if calling pump() won't throw an immediate\n\"process ended prematurely\" exception. This means that there\nare open I/O channels or active processes. May yield the parent\nprocesses' time slice for 0.01 second if all pipes are to the\nchild and all are paused. In this case we can't tell if the\nchild is dead, so we yield the processor and then attempt to\nreap 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\nspecific children to be reaped.\n\nOnly call this from a signal handler if your \"perl\" is recent\nenough to have safe signal handling (5.6.1 did not, IIRC, but\nit was being discussed on perl5-porters). Calling this (or\ndoing any significant work) in a signal handler on older\n\"perl\"s is asking for seg faults.\n\nfinish\nThis must be called after the last start() or pump() call for a\nharness, or your system will accumulate defunct processes and\nyou may \"leak\" file descriptors.\n\nfinish() returns TRUE if all children returned 0 (and were not\nsignaled and did not coredump, ie ! $?), and FALSE otherwise\n(this is like run(), and the opposite of system()).\n\nOnce a harness has been finished, it may be run() or start()ed\nagain, including by pump()s auto-start.\n\nIf this throws an exception rather than a normal exit, the\nharness may be left in an unstable state, it's best to kill the\nharness to get rid of all the child processes, etc.\n\nSpecifically, if a timeout expires in finish(), finish() will\nnot kill all the children. Call \"<$h-\"killkill>> in this case\nif you care. This differs from the behavior of \"run\".\n\nresult\n$h->result;\n\nReturns the first non-zero result code (ie $? >> 8). See\n\"fullresult\" to get the $? value 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\nnumber was specified. Throws an exception if an out-of-range\nchild number is passed.\n\nresults\nReturns a list of child exit values. See \"fullresults\" if you\nwant to know if a signal killed 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\n$? >> 8 value for a child process.\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\nnumber was specified. Throws an exception if an out-of-range\nchild number is passed.\n\nfullresults\nReturns a list of child exit values as returned by \"wait\". See\n\"results\" if you don't care 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\nprocess and a scalar or subroutine 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\nto keep the carriage returns that would ordinarily be edited out\nfor you (binmode is usually off). This is not a real filter, but\nan option masquerading as a filter.\n\nIt's not named \"binmode\" because you're likely to want to call\nPerl's binmode in programs that are piping binary data around.\n\nnewchunker\nThis breaks a stream of data in to chunks, based on an optional\nscalar or regular expression parameter. The default is the Perl\ninput record separator in $/, which is a newline be default.\n\nrun \\@cmd, '>', newchunker, \\&lineshandler;\nrun \\@cmd, '>', newchunker( \"\\r\\n\" ), \\&lineshandler;\n\nBecause this uses $/ by default, you should always pass in a\nparameter if you are worried about other code (modules, etc)\nmodifying $/.\n\nIf this filter is last in a filter chain that dumps in to a scalar,\nthe scalar must be set to '' before a new chunk will be written to\nit.\n\nAs an example of how a filter like this can be written, here's a\nchunker that splits on newlines:\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\nsource scalar or sub. This might be useful if you're writing\ncommands to a child process that always must end in a fixed string,\nlike \"\\n\":\n\nrun( \\@cmd,\n'<', newappender( \"\\n\" ), \\&commands,\n);\n\nHere's a typical filter sub that might be created by\nnewappender():\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\nmodule.\n\nThis is a filter which is exportable. Returns a sub which appends\nthe data passed in to the output buffer and returns 1 if data was\nappended. 0 if it was an empty string and undef if no data was\npassed.\n\nNOTE: Any additional variables passed to newstringsource will be\npassed to the sub every time it's called and appended to the\noutput.\n\nnewstringsink\nTODO: Needs confirmation. Was previously undocumented.\n\nThis is a filter which is exportable. Returns a sub which pops the\ndata out of the input stream and pushes it onto the string.\n\nio Takes a filename or filehandle, a redirection operator, optional\nfilters, and a source or destination (depends on the redirection\noperator). Returns an IPC::Run::IO object suitable for\nharness()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\ntimer expires. Has no direct effect on run(), but you can pass a\nsubroutine to fire when the timer expires.\n\nSee \"timeout\" for building timers that throw exceptions on\nexpiration.\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\nyou don't provide an exception, a default exception that matches\n/^IPC::Run: .*timed out/ is thrown by default. You can pass in\nyour 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\nexception 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\n&getmoreinput is called and its result is returned.\n\nThis is usually used in preference to &getmoreinput so that the\ncalling filter removes all data from the $inref before more data\ngets 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\nfilter normally returns when there's no input to process. If a\nfilter stores intermediate values, however, it will need to react\nto 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\nreturns undef if there will never be any more input, 0 if there is\nnone now, but there might be in the future, and TRUE if more input\nwas gotten.\n\n\"getmoreinput\" is usually used as part of a return expression,\nsee \"inputavail\" for more information.\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\nopen FILEHANDLEs in Perl, yet you don't want child processes\ninheriting 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\nbecause I don't use that system any more. The Win32 subsysem has\nbeen extended to use temporary files in simple run() invocations\nand these may actually work on Win9X too, but I don't have time to\nwork on it.\n\nMay deadlock on Win2K (but not WinNT4 or WinXPPro)\nSpawning more than one subprocess on Win2K causes a deadlock I\nhaven't figured out yet, but simple uses of run() often work.\nPasses all tests on WinXPPro and WinNT.\n\nno support yet for pty>\nThese are likely to be implemented as \"<\" and \">\" with binmode on,\nnot sure.\n\nno support for file descriptors higher than 2 (stderr)\nWin32 only allows passing explicit fds 0, 1, and 2. If you really,\nreally need to pass file handles, us Win32API:: GetOsFHandle() or\n::FdGetOsFHandle() to get the integer handle and pass it to the\nchild process using the command line, environment, stdin,\nintermediary file, or other IPC mechanism. Then use that handle in\nthe child (Win32API.pm provides ways to reconstitute Perl file\nhandles from Win32 file handles).\n\nno support for subroutine subprocesses (CODE refs)\nCan't fork(), so the subroutines would have no context, and\nclosures certainly have no meaning\n\nPerhaps with Win32 fork() emulation, this can be supported in a\nlimited fashion, but there are other very serious problems with\nthat: all parent fds get dup()ed in to the thread emulating the\nforked process, and that keeps the parent from being able to close\nall of the appropriate fds.\n\nno support for init => sub {} routines.\nWin32 processes are created from scratch, there is no way to do an\ninit routine that will affect the running child. Some limited\nsupport might be implemented one day, do chdir() and %ENV changes\ncan be made.\n\nsignals\nWin32 does not fully support signals. signal() is likely to cause\nerrors unless sending a signal that Perl emulates, and\n\"killkill()\" is immediately fatal (there is no grace period).\n\nhelper processes\nIPC::Run uses helper processes, one per redirected file, to adapt\nbetween the anonymous pipe connected to the child and the TCP\nsocket connected to the parent. This is a waste of resources and\nwill change in the future to either use threads (instead of helper\nprocesses) or a WaitForMultipleObjects call (instead of select).\nPlease contact me if you can help with the WaitForMultipleObjects()\napproach; I haven't figured out how to get at it without C code.\n\nshutdown pause\nThere seems to be a pause of up to 1 second between when a child\nprogram exits and the corresponding sockets indicate that they are\nclosed in the parent. Not sure why.\n\nbinmode\nbinmode is not supported yet. The underpinnings are implemented,\njust ask if you need it.\n\nIPC::Run::IO\nIPC::Run::IO objects can be used on Unix to read or write arbitrary\nfiles. On Win32, they will need to use the same helper processes\nto adapt from non-select()able filehandles to select()able ones (or\nperhaps WaitForMultipleObjects() will work with them, not sure).\n\nstartup race conditions\nThere seems to be an occasional race condition between child\nprocess startup and pipe closings. It seems like if the child is\nnot fully created by the time CreateProcess returns and we close\nthe TCP socket being handed to it, the parent socket can also get\nclosed. This is seen with the Win32 pumper applications, not the\n\"real\" child process being spawned.\n\nI assume this is because the kernel hasn't gotten around to\nincrementing the reference count on the child's end (since the\nchild was slow in starting), so the parent's closing of the child\nend causes the socket to be closed, thus closing the parent socket.\n\nBeing a race condition, it's hard to reproduce, but I encountered\nit while testing this code on a drive share to a samba box. In\nthis case, it takes t/run.t a long time to spawn it's child\nprocesses (the parent hangs in the first select for several seconds\nuntil the child emits any debugging output).\n\nI have not seen it on local drives, and can't reproduce it at will,\nunfortunately. The symptom is a \"bad file descriptor in select()\"\nerror, and, by turning on debugging, it's possible to see that\nselect() is being called on a no longer open file descriptor that\nwas returned from the socket() routine in Win32Helper. There's a\nnew confess() that checks for this (\"PARENTHANDLE no longer\nopen\"), 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\nit can tell if a child process is still running.\n\nPTYs don't seem to be non-blocking on some versions of Solaris. Here's\na test script contributed by Borislav Deianov to\nsee if you have the problem. If it dies, you have the 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()\nreturns TRUE when the command 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\ndays, months, etc.\n\nWARNING: Function coprocesses (\"run \\&foo, ...\") suffer from two\nlimitations. The first is that it is difficult to close all\nfilehandles the child inherits from the parent, since there is no way\nto scan all open FILEHANDLEs in Perl and it both painful and a bit\ndangerous to close all open file descriptors with \"POSIX::close()\".\nPainful because we can't tell which fds are open at the POSIX level,\neither, so we'd have to scan all possible fds and close any that we\ndon't want open (normally \"exec()\" closes any non-inheritable but we\ndon't \"exec()\" for &sub processes.\n\nThe second problem is that Perl's DESTROY subs and other on-exit\ncleanup gets run in the child process. If objects are instantiated in\nthe parent before the child is forked, the DESTROY will get run once in\nthe parent and once in the child. When coprocess subs exit,\nPOSIX::exit is called to work around this, but it means that objects\nthat are still referred to at that time are not cleaned up. So setting\npackage vars or closure vars to point to objects that rely on DESTROY\nto affect things outside the process (files, etc), will lead to bugs.\n\nI goofed on the syntax: \"filename\" are both\noddities.\n", "subsections": [] }, "INSPIRATION": { "content": "Well, select() and waitpid() badly needed wrapping, and open3() isn't\nopen-minded enough for me.\n\nThe shell-like API inspired by a message Russ Allbery sent to\nperl5-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\nLicense or the Artistic License, as specified in the README file.\n\nperl v5.30.0 2020-05-09 IPC::Run(3pm)", "subsections": [] } } } }