local-lib5/man/man3/IPC::Run.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "IPC::Run 3"
 127 .TH IPC::Run 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 IPC::Run \- system() and background procs w/ piping, redirs, ptys (Unix, Win32)
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&   ## First,a command to run:
 138 \&      my @cat = qw( cat );
 139 \&
 140 \&   ## Using run() instead of system():
 141 \&      use IPC::Run qw( run timeout );
 142 \&
 143 \&      run \e@cmd, \e$in, \e$out, \e$err, timeout( 10 ) or die "cat: $?"
 144 \&
 145 \&      # Can do I/O to sub refs and filenames, too:
 146 \&      run \e@cmd, \*(Aq<\*(Aq, "in.txt", \e&out, \e&err or die "cat: $?"
 147 \&      run \e@cat, \*(Aq<\*(Aq, "in.txt", \*(Aq>>\*(Aq, "out.txt", \*(Aq2>>\*(Aq, "err.txt";
 148 \&
 149 \&
 150 \&      # Redirecting using psuedo\-terminals instad of pipes.
 151 \&      run \e@cat, \*(Aq<pty<\*(Aq, \e$in,  \*(Aq>pty>\*(Aq, \e$out_and_err;
 152 \&
 153 \&   ## Scripting subprocesses (like Expect):
 154 \&
 155 \&      use IPC::Run qw( start pump finish timeout );
 156 \&
 157 \&      # Incrementally read from / write to scalars.
 158 \&      # $in is drained as it is fed to cat\*(Aqs stdin,
 159 \&      # $out accumulates cat\*(Aqs stdout
 160 \&      # $err accumulates cat\*(Aqs stderr
 161 \&      # $h is for "harness".
 162 \&      my $h = start \e@cat, \e$in, \e$out, \e$err, timeout( 10 );
 163 \&
 164 \&      $in .= "some input\en";
 165 \&      pump $h until $out =~ /input\en/g;
 166 \&
 167 \&      $in .= "some more input\en";
 168 \&      pump $h until $out =~ /\eG.*more input\en/;
 169 \&
 170 \&      $in .= "some final input\en";
 171 \&      finish $h or die "cat returned $?";
 172 \&
 173 \&      warn $err if $err;
 174 \&      print $out;         ## All of cat\*(Aqs output
 175 \&
 176 \&   # Piping between children
 177 \&      run \e@cat, \*(Aq|\*(Aq, \e@gzip;
 178 \&
 179 \&   # Multiple children simultaneously (run() blocks until all
 180 \&   # children exit, use start() for background execution):
 181 \&      run \e@foo1, \*(Aq&\*(Aq, \e@foo2;
 182 \&
 183 \&   # Calling \e&set_up_child in the child before it executes the
 184 \&   # command (only works on systems with true fork() & exec())
 185 \&   # exceptions thrown in set_up_child() will be propagated back
 186 \&   # to the parent and thrown from run().
 187 \&      run \e@cat, \e$in, \e$out,
 188 \&         init => \e&set_up_child;
 189 \&
 190 \&   # Read from / write to file handles you open and close
 191 \&      open IN,  \*(Aq<in.txt\*(Aq  or die $!;
 192 \&      open OUT, \*(Aq>out.txt\*(Aq or die $!;
 193 \&      print OUT "preamble\en";
 194 \&      run \e@cat, \e*IN, \e*OUT or die "cat returned $?";
 195 \&      print OUT "postamble\en";
 196 \&      close IN;
 197 \&      close OUT;
 198 \&
 199 \&   # Create pipes for you to read / write (like IPC::Open2 & 3).
 200 \&      $h = start
 201 \&         \e@cat,
 202 \&            \*(Aq<pipe\*(Aq, \e*IN,
 203 \&            \*(Aq>pipe\*(Aq, \e*OUT,
 204 \&            \*(Aq2>pipe\*(Aq, \e*ERR
 205 \&         or die "cat returned $?";
 206 \&      print IN "some input\en";
 207 \&      close IN;
 208 \&      print <OUT>, <ERR>;
 209 \&      finish $h;
 210 \&
 211 \&   # Mixing input and output modes
 212 \&      run \e@cat, \*(Aqin.txt\*(Aq, \e&catch_some_out, \e*ERR_LOG );
 213 \&
 214 \&   # Other redirection constructs
 215 \&      run \e@cat, \*(Aq>&\*(Aq, \e$out_and_err;
 216 \&      run \e@cat, \*(Aq2>&1\*(Aq;
 217 \&      run \e@cat, \*(Aq0<&3\*(Aq;
 218 \&      run \e@cat, \*(Aq<&\-\*(Aq;
 219 \&      run \e@cat, \*(Aq3<\*(Aq, \e$in3;
 220 \&      run \e@cat, \*(Aq4>\*(Aq, \e$out4;
 221 \&      # etc.
 222 \&
 223 \&   # Passing options:
 224 \&      run \e@cat, \*(Aqin.txt\*(Aq, debug => 1;
 225 \&
 226 \&   # Call this system\*(Aqs shell, returns TRUE on 0 exit code
 227 \&   # THIS IS THE OPPOSITE SENSE OF system()\*(Aqs RETURN VALUE
 228 \&      run "cat a b c" or die "cat returned $?";
 229 \&
 230 \&   # Launch a sub process directly, no shell.  Can\*(Aqt do redirection
 231 \&   # with this form, it\*(Aqs here to behave like system() with an
 232 \&   # inverted result.
 233 \&      $r = run "cat a b c";
 234 \&
 235 \&   # Read from a file in to a scalar
 236 \&      run io( "filename", \*(Aqr\*(Aq, \e$recv );
 237 \&      run io( \e*HANDLE,   \*(Aqr\*(Aq, \e$recv );
 238 .Ve
 239 .SH "DESCRIPTION"
 240 .IX Header "DESCRIPTION"
 241 IPC::Run allows you run and interact with child processes using files, pipes,
 242 and pseudo-ttys.  Both \fIsystem()\fR\-style and scripted usages are supported and
 243 may be mixed.  Likewise, functional and \s-1OO\s0 \s-1API\s0 styles are both supported and
 244 may be mixed.
 245 .PP
 246 Various redirection operators reminiscent of those seen on common Unix and \s-1DOS\s0
 247 command lines are provided.
 248 .PP
 249 Before digging in to the details a few \s-1LIMITATIONS\s0 are important enough
 250 to be mentioned right up front:
 251 .IP "Win32 Support" 4
 252 .IX Item "Win32 Support"
 253 Win32 support is working but \fB\s-1EXPERIMENTAL\s0\fR, but does pass all relevant tests
 254 on \s-1NT\s0 4.0.  See \*(L"Win32 \s-1LIMITATIONS\s0\*(R".
 255 .IP "pty Support" 4
 256 .IX Item "pty Support"
 257 If you need pty support, IPC::Run should work well enough most of the
 258 time, but IO::Pty is being improved, and IPC::Run will be improved to
 259 use IO::Pty's new features when it is release.
 260 .Sp
 261 The basic problem is that the pty needs to initialize itself before the
 262 parent writes to the master pty, or the data written gets lost.  So
 263 IPC::Run does a \fIsleep\fR\|(1) in the parent after forking to (hopefully) give
 264 the child a chance to run.  This is a kludge that works well on non
 265 heavily loaded systems :(.
 266 .Sp
 267 ptys are not supported yet under Win32, but will be emulated...
 268 .IP "Debugging Tip" 4
 269 .IX Item "Debugging Tip"
 270 You may use the environment variable \f(CW\*(C`IPCRUNDEBUG\*(C'\fR to see what's going on
 271 under the hood:
 272 .Sp
 273 .Vb 5
 274 \&   $ IPCRUNDEBUG=basic   myscript     # prints minimal debugging
 275 \&   $ IPCRUNDEBUG=data    myscript     # prints all data reads/writes
 276 \&   $ IPCRUNDEBUG=details myscript     # prints lots of low\-level details
 277 \&   $ IPCRUNDEBUG=gory    myscript     # (Win32 only) prints data moving through
 278 \&                                      # the helper processes.
 279 .Ve
 280 .PP
 281 We now return you to your regularly scheduled documentation.
 282 .SS "Harnesses"
 283 .IX Subsection "Harnesses"
 284 Child processes and I/O handles are gathered in to a harness, then
 285 started and run until the processing is finished or aborted.
 286 .SS "\fIrun()\fP vs. \fIstart()\fP; \fIpump()\fP; \fIfinish()\fP;"
 287 .IX Subsection "run() vs. start(); pump(); finish();"
 288 There are two modes you can run harnesses in: \fIrun()\fR functions as an
 289 enhanced \fIsystem()\fR, and \fIstart()\fR/\fIpump()\fR/\fIfinish()\fR allow for background
 290 processes and scripted interactions with them.
 291 .PP
 292 When using \fIrun()\fR, all data to be sent to the harness is set up in
 293 advance (though one can feed subprocesses input from subroutine refs to
 294 get around this limitation). The harness is run and all output is
 295 collected from it, then any child processes are waited for:
 296 .PP
 297 .Vb 3
 298 \&   run \e@cmd, \e<<IN, \e$out;
 299 \&   blah
 300 \&   IN
 301 \&
 302 \&   ## To precompile harnesses and run them later:
 303 \&   my $h = harness \e@cmd, \e<<IN, \e$out;
 304 \&   blah
 305 \&   IN
 306 \&
 307 \&   run $h;
 308 .Ve
 309 .PP
 310 The background and scripting \s-1API\s0 is provided by \fIstart()\fR, \fIpump()\fR, and
 311 \&\fIfinish()\fR: \fIstart()\fR creates a harness if need be (by calling \fIharness()\fR)
 312 and launches any subprocesses, \fIpump()\fR allows you to poll them for
 313 activity, and \fIfinish()\fR then monitors the harnessed activities until they
 314 complete.
 315 .PP
 316 .Vb 3
 317 \&   ## Build the harness, open all pipes, and launch the subprocesses
 318 \&   my $h = start \e@cat, \e$in, \e$out;
 319 \&   $in = "first input\en";
 320 \&
 321 \&   ## Now do I/O.  start() does no I/O.
 322 \&   pump $h while length $in;  ## Wait for all input to go
 323 \&
 324 \&   ## Now do some more I/O.
 325 \&   $in = "second input\en";
 326 \&   pump $h until $out =~ /second input/;
 327 \&
 328 \&   ## Clean up
 329 \&   finish $h or die "cat returned $?";
 330 .Ve
 331 .PP
 332 You can optionally compile the harness with \fIharness()\fR prior to
 333 \&\fIstart()\fRing or \fIrun()\fRing, and you may omit \fIstart()\fR between \fIharness()\fR and
 334 \&\fIpump()\fR.  You might want to do these things if you compile your harnesses
 335 ahead of time.
 336 .SS "Using regexps to match output"
 337 .IX Subsection "Using regexps to match output"
 338 As shown in most of the scripting examples, the read-to-scalar facility
 339 for gathering subcommand's output is often used with regular expressions
 340 to detect stopping points.  This is because subcommand output often
 341 arrives in dribbles and drabs, often only a character or line at a time.
 342 This output is input for the main program and piles up in variables like
 343 the \f(CW$out\fR and \f(CW$err\fR in our examples.
 344 .PP
 345 Regular expressions can be used to wait for appropriate output in
 346 several ways.  The \f(CW\*(C`cat\*(C'\fR example in the previous section demonstrates
 347 how to \fIpump()\fR until some string appears in the output.  Here's an
 348 example that uses \f(CW\*(C`smb\*(C'\fR to fetch files from a remote server:
 349 .PP
 350 .Vb 1
 351 \&   $h = harness \e@smbclient, \e$in, \e$out;
 352 \&
 353 \&   $in = "cd /src\en";
 354 \&   $h\->pump until $out =~ /^smb.*> \eZ/m;
 355 \&   die "error cding to /src:\en$out" if $out =~ "ERR";
 356 \&   $out = \*(Aq\*(Aq;
 357 \&
 358 \&   $in = "mget *\en";
 359 \&   $h\->pump until $out =~ /^smb.*> \eZ/m;
 360 \&   die "error retrieving files:\en$out" if $out =~ "ERR";
 361 \&
 362 \&   $in = "quit\en";
 363 \&   $h\->finish;
 364 .Ve
 365 .PP
 366 Notice that we carefully clear \f(CW$out\fR after the first command/response
 367 cycle? That's because IPC::Run does not delete \f(CW$out\fR when we continue,
 368 and we don't want to trip over the old output in the second
 369 command/response cycle.
 370 .PP
 371 Say you want to accumulate all the output in \f(CW$out\fR and analyze it
 372 afterwards.  Perl offers incremental regular expression matching using
 373 the \f(CW\*(C`m//gc\*(C'\fR and pattern matching idiom and the \f(CW\*(C`\eG\*(C'\fR assertion.
 374 IPC::Run is careful not to disturb the current \f(CW\*(C`pos()\*(C'\fR value for
 375 scalars it appends data to, so we could modify the above so as not to
 376 destroy \f(CW$out\fR by adding a couple of \f(CW\*(C`/gc\*(C'\fR modifiers.  The \f(CW\*(C`/g\*(C'\fR keeps us
 377 from tripping over the previous prompt and the \f(CW\*(C`/c\*(C'\fR keeps us from
 378 resetting the prior match position if the expected prompt doesn't
 379 materialize immediately:
 380 .PP
 381 .Vb 1
 382 \&   $h = harness \e@smbclient, \e$in, \e$out;
 383 \&
 384 \&   $in = "cd /src\en";
 385 \&   $h\->pump until $out =~ /^smb.*> \eZ/mgc;
 386 \&   die "error cding to /src:\en$out" if $out =~ "ERR";
 387 \&
 388 \&   $in = "mget *\en";
 389 \&   $h\->pump until $out =~ /^smb.*> \eZ/mgc;
 390 \&   die "error retrieving files:\en$out" if $out =~ "ERR";
 391 \&
 392 \&   $in = "quit\en";
 393 \&   $h\->finish;
 394 \&
 395 \&   analyze( $out );
 396 .Ve
 397 .PP
 398 When using this technique, you may want to preallocate \f(CW$out\fR to have
 399 plenty of memory or you may find that the act of growing \f(CW$out\fR each time
 400 new input arrives causes an \f(CW\*(C`O(length($out)^2)\*(C'\fR slowdown as \f(CW$out\fR grows.
 401 Say we expect no more than 10,000 characters of input at the most.  To
 402 preallocate memory to \f(CW$out\fR, do something like:
 403 .PP
 404 .Vb 2
 405 \&   my $out = "x" x 10_000;
 406 \&   $out = "";
 407 .Ve
 408 .PP
 409 \&\f(CW\*(C`perl\*(C'\fR will allocate at least 10,000 characters' worth of space, then
 410 mark the \f(CW$out\fR as having 0 length without freeing all that yummy \s-1RAM\s0.
 411 .SS "Timeouts and Timers"
 412 .IX Subsection "Timeouts and Timers"
 413 More than likely, you don't want your subprocesses to run forever, and
 414 sometimes it's nice to know that they're going a little slowly.
 415 Timeouts throw exceptions after a some time has elapsed, timers merely
 416 cause \fIpump()\fR to return after some time has elapsed.  Neither is
 417 reset/restarted automatically.
 418 .PP
 419 Timeout objects are created by calling timeout( \f(CW$interval\fR ) and passing
 420 the result to \fIrun()\fR, \fIstart()\fR or \fIharness()\fR.  The timeout period starts
 421 ticking just after all the child processes have been \fIfork()\fRed or
 422 \&\fIspawn()\fRed, and are polled for expiration in \fIrun()\fR, \fIpump()\fR and \fIfinish()\fR.
 423 If/when they expire, an exception is thrown.  This is typically useful
 424 to keep a subprocess from taking too long.
 425 .PP
 426 If a timeout occurs in \fIrun()\fR, all child processes will be terminated and
 427 all file/pipe/ptty descriptors opened by \fIrun()\fR will be closed.  File
 428 descriptors opened by the parent process and passed in to \fIrun()\fR are not
 429 closed in this event.
 430 .PP
 431 If a timeout occurs in \fIpump()\fR, \fIpump_nb()\fR, or \fIfinish()\fR, it's up to you to
 432 decide whether to \fIkill_kill()\fR all the children or to implement some more
 433 graceful fallback.  No I/O will be closed in \fIpump()\fR, \fIpump_nb()\fR or
 434 \&\fIfinish()\fR by such an exception (though I/O is often closed down in those
 435 routines during the natural course of events).
 436 .PP
 437 Often an exception is too harsh.  timer( \f(CW$interval\fR ) creates timer
 438 objects that merely prevent \fIpump()\fR from blocking forever.  This can be
 439 useful for detecting stalled I/O or printing a soothing message or \*(L".\*(R"
 440 to pacify an anxious user.
 441 .PP
 442 Timeouts and timers can both be restarted at any time using the timer's
 443 \&\fIstart()\fR method (this is not the \fIstart()\fR that launches subprocesses).  To
 444 restart a timer, you need to keep a reference to the timer:
 445 .PP
 446 .Vb 2
 447 \&   ## Start with a nice long timeout to let smbclient connect.  If
 448 \&   ## pump or finish take too long, an exception will be thrown.
 449 \&
 450 \& my $h;
 451 \& eval {
 452 \&   $h = harness \e@smbclient, \e$in, \e$out, \e$err, ( my $t = timeout 30 );
 453 \&   sleep 11;  # No effect: timer not running yet
 454 \&
 455 \&   start $h;
 456 \&   $in = "cd /src\en";
 457 \&   pump $h until ! length $in;
 458 \&
 459 \&   $in = "ls\en";
 460 \&   ## Now use a short timeout, since this should be faster
 461 \&   $t\->start( 5 );
 462 \&   pump $h until ! length $in;
 463 \&
 464 \&   $t\->start( 10 );  ## Give smbclient a little while to shut down.
 465 \&   $h\->finish;
 466 \& };
 467 \& if ( $@ ) {
 468 \&   my $x = $@;    ## Preserve $@ in case another exception occurs
 469 \&   $h\->kill_kill; ## kill it gently, then brutally if need be, or just
 470 \&                   ## brutally on Win32.
 471 \&   die $x;
 472 \& }
 473 .Ve
 474 .PP
 475 Timeouts and timers are \fInot\fR checked once the subprocesses are shut
 476 down; they will not expire in the interval between the last valid
 477 process and when IPC::Run scoops up the processes' result codes, for
 478 instance.
 479 .SS "Spawning synchronization, child exception propagation"
 480 .IX Subsection "Spawning synchronization, child exception propagation"
 481 \&\fIstart()\fR pauses the parent until the child executes the command or \s-1CODE\s0
 482 reference and propagates any exceptions thrown (including \fIexec()\fR
 483 failure) back to the parent.  This has several pleasant effects: any
 484 exceptions thrown in the child, including \fIexec()\fR failure, come flying
 485 out of \fIstart()\fR or \fIrun()\fR as though they had ocurred in the parent.
 486 .PP
 487 This includes exceptions your code thrown from init subs.  In this
 488 example:
 489 .PP
 490 .Vb 4
 491 \&   eval {
 492 \&      run \e@cmd, init => sub { die "blast it! foiled again!" };
 493 \&   };
 494 \&   print $@;
 495 .Ve
 496 .PP
 497 the exception \*(L"blast it! foiled again\*(R" will be thrown from the child
 498 process (preventing the \fIexec()\fR) and printed by the parent.
 499 .PP
 500 In situations like
 501 .PP
 502 .Vb 1
 503 \&   run \e@cmd1, "|", \e@cmd2, "|", \e@cmd3;
 504 .Ve
 505 .PP
 506 \&\f(CW@cmd1\fR will be initted and \fIexec()\fRed before \f(CW@cmd2\fR, and \f(CW@cmd2\fR before \f(CW@cmd3\fR.
 507 This can save time and prevent oddball errors emitted by later commands
 508 when earlier commands fail to execute.  Note that IPC::Run doesn't start
 509 any commands unless it can find the executables referenced by all
 510 commands.  These executables must pass both the \f(CW\*(C`\-f\*(C'\fR and \f(CW\*(C`\-x\*(C'\fR tests
 511 described in perlfunc.
 512 .PP
 513 Another nice effect is that \fIinit()\fR subs can take their time doing things
 514 and there will be no problems caused by a parent continuing to execute
 515 before a child's \fIinit()\fR routine is complete.  Say the \fIinit()\fR routine
 516 needs to open a socket or a temp file that the parent wants to connect
 517 to; without this synchronization, the parent will need to implement a
 518 retry loop to wait for the child to run, since often, the parent gets a
 519 lot of things done before the child's first timeslice is allocated.
 520 .PP
 521 This is also quite necessary for pseudo-tty initialization, which needs
 522 to take place before the parent writes to the child via pty.  Writes
 523 that occur before the pty is set up can get lost.
 524 .PP
 525 A final, minor, nicety is that debugging output from the child will be
 526 emitted before the parent continues on, making for much clearer debugging
 527 output in complex situations.
 528 .PP
 529 The only drawback I can conceive of is that the parent can't continue to
 530 operate while the child is being initted.  If this ever becomes a
 531 problem in the field, we can implement an option to avoid this behavior,
 532 but I don't expect it to.
 533 .PP
 534 \&\fBWin32\fR: executing \s-1CODE\s0 references isn't supported on Win32, see
 535 \&\*(L"Win32 \s-1LIMITATIONS\s0\*(R" for details.
 536 .SS "Syntax"
 537 .IX Subsection "Syntax"
 538 \&\fIrun()\fR, \fIstart()\fR, and \fIharness()\fR can all take a harness specification
 539 as input.  A harness specification is either a single string to be passed
 540 to the systems' shell:
 541 .PP
 542 .Vb 1
 543 \&   run "echo \*(Aqhi there\*(Aq";
 544 .Ve
 545 .PP
 546 or a list of commands, io operations, and/or timers/timeouts to execute.
 547 Consecutive commands must be separated by a pipe operator '|' or an '&'.
 548 External commands are passed in as array references, and, on systems
 549 supporting \fIfork()\fR, Perl code may be passed in as subs:
 550 .PP
 551 .Vb 6
 552 \&   run \e@cmd;
 553 \&   run \e@cmd1, \*(Aq|\*(Aq, \e@cmd2;
 554 \&   run \e@cmd1, \*(Aq&\*(Aq, \e@cmd2;
 555 \&   run \e&sub1;
 556 \&   run \e&sub1, \*(Aq|\*(Aq, \e&sub2;
 557 \&   run \e&sub1, \*(Aq&\*(Aq, \e&sub2;
 558 .Ve
 559 .PP
 560 \&'|' pipes the stdout of \e@cmd1 the stdin of \e@cmd2, just like a
 561 shell pipe.  '&' does not.  Child processes to the right of a '&'
 562 will have their stdin closed unless it's redirected-to.
 563 .PP
 564 IPC::Run::IO objects may be passed in as well, whether or not
 565 child processes are also specified:
 566 .PP
 567 .Vb 1
 568 \&   run io( "infile", ">", \e$in ), io( "outfile", "<", \e$in );
 569 .Ve
 570 .PP
 571 as can IPC::Run::Timer objects:
 572 .PP
 573 .Vb 1
 574 \&   run \e@cmd, io( "outfile", "<", \e$in ), timeout( 10 );
 575 .Ve
 576 .PP
 577 Commands may be followed by scalar, sub, or i/o handle references for
 578 redirecting
 579 child process input & output:
 580 .PP
 581 .Vb 4
 582 \&   run \e@cmd,  \eundef,            \e$out;
 583 \&   run \e@cmd,  \e$in,              \e$out;
 584 \&   run \e@cmd1, \e&in, \*(Aq|\*(Aq, \e@cmd2, \e*OUT;
 585 \&   run \e@cmd1, \e*IN, \*(Aq|\*(Aq, \e@cmd2, \e&out;
 586 .Ve
 587 .PP
 588 This is known as succinct redirection syntax, since \fIrun()\fR, \fIstart()\fR
 589 and \fIharness()\fR, figure out which file descriptor to redirect and how.
 590 File descriptor 0 is presumed to be an input for
 591 the child process, all others are outputs.  The assumed file
 592 descriptor always starts at 0, unless the command is being piped to,
 593 in which case it starts at 1.
 594 .PP
 595 To be explicit about your redirects, or if you need to do more complex
 596 things, there's also a redirection operator syntax:
 597 .PP
 598 .Vb 8
 599 \&   run \e@cmd, \*(Aq<\*(Aq, \eundef, \*(Aq>\*(Aq,  \e$out;
 600 \&   run \e@cmd, \*(Aq<\*(Aq, \eundef, \*(Aq>&\*(Aq, \e$out_and_err;
 601 \&   run(
 602 \&      \e@cmd1,
 603 \&         \*(Aq<\*(Aq, \e$in,
 604 \&      \*(Aq|\*(Aq, \e@cmd2,
 605 \&         \e$out
 606 \&   );
 607 .Ve
 608 .PP
 609 Operator syntax is required if you need to do something other than simple
 610 redirection to/from scalars or subs, like duping or closing file descriptors
 611 or redirecting to/from a named file.  The operators are covered in detail
 612 below.
 613 .PP
 614 After each \e@cmd (or \e&foo), parsing begins in succinct mode and toggles to
 615 operator syntax mode when an operator (ie plain scalar, not a ref) is seen.
 616 Once in
 617 operator syntax mode, parsing only reverts to succinct mode when a '|' or
 618 \&'&' is seen.
 619 .PP
 620 In succinct mode, each parameter after the \e@cmd specifies what to
 621 do with the next highest file descriptor. These File descriptor start
 622 with 0 (stdin) unless stdin is being piped to (\f(CW\*(C`\*(Aq|\*(Aq, \e@cmd\*(C'\fR), in which
 623 case they start with 1 (stdout).  Currently, being on the left of
 624 a pipe (\f(CW\*(C`\e@cmd, \e$out, \e$err, \*(Aq|\*(Aq\*(C'\fR) does \fInot\fR cause stdout to be
 625 skipped, though this may change since it's not as DWIMerly as it
 626 could be.  Only stdin is assumed to be an
 627 input in succinct mode, all others are assumed to be outputs.
 628 .PP
 629 If no piping or redirection is specified for a child, it will inherit
 630 the parent's open file handles as dictated by your system's
 631 close-on-exec behavior and the $^F flag, except that processes after a
 632 \&'&' will not inherit the parent's stdin. Also note that $^F does not
 633 affect file desciptors obtained via \s-1POSIX\s0, since it only applies to
 634 full-fledged Perl file handles.  Such processes will have their stdin
 635 closed unless it has been redirected-to.
 636 .PP
 637 If you want to close a child processes stdin, you may do any of:
 638 .PP
 639 .Vb 4
 640 \&   run \e@cmd, \eundef;
 641 \&   run \e@cmd, \e"";
 642 \&   run \e@cmd, \*(Aq<&\-\*(Aq;
 643 \&   run \e@cmd, \*(Aq0<&\-\*(Aq;
 644 .Ve
 645 .PP
 646 Redirection is done by placing redirection specifications immediately
 647 after a command or child subroutine:
 648 .PP
 649 .Vb 2
 650 \&   run \e@cmd1,      \e$in, \*(Aq|\*(Aq, \e@cmd2,      \e$out;
 651 \&   run \e@cmd1, \*(Aq<\*(Aq, \e$in, \*(Aq|\*(Aq, \e@cmd2, \*(Aq>\*(Aq, \e$out;
 652 .Ve
 653 .PP
 654 If you omit the redirection operators, descriptors are counted
 655 starting at 0.  Descriptor 0 is assumed to be input, all others
 656 are outputs.  A leading '|' consumes descriptor 0, so this
 657 works as expected.
 658 .PP
 659 .Vb 1
 660 \&   run \e@cmd1, \e$in, \*(Aq|\*(Aq, \e@cmd2, \e$out;
 661 .Ve
 662 .PP
 663 The parameter following a redirection operator can be a scalar ref,
 664 a subroutine ref, a file name, an open filehandle, or a closed
 665 filehandle.
 666 .PP
 667 If it's a scalar ref, the child reads input from or sends output to
 668 that variable:
 669 .PP
 670 .Vb 3
 671 \&   $in = "Hello World.\en";
 672 \&   run \e@cat, \e$in, \e$out;
 673 \&   print $out;
 674 .Ve
 675 .PP
 676 Scalars used in incremental (\fIstart()\fR/\fIpump()\fR/\fIfinish()\fR) applications are treated
 677 as queues: input is removed from input scalers, resulting in them dwindling
 678 to '', and output is appended to output scalars.  This is not true of
 679 harnesses \fIrun()\fR in batch mode.
 680 .PP
 681 It's usually wise to append new input to be sent to the child to the input
 682 queue, and you'll often want to zap output queues to '' before pumping.
 683 .PP
 684 .Vb 7
 685 \&   $h = start \e@cat, \e$in;
 686 \&   $in = "line 1\en";
 687 \&   pump $h;
 688 \&   $in .= "line 2\en";
 689 \&   pump $h;
 690 \&   $in .= "line 3\en";
 691 \&   finish $h;
 692 .Ve
 693 .PP
 694 The final call to \fIfinish()\fR must be there: it allows the child process(es)
 695 to run to completion and waits for their exit values.
 696 .SH "OBSTINATE CHILDREN"
 697 .IX Header "OBSTINATE CHILDREN"
 698 Interactive applications are usually optimized for human use.  This
 699 can help or hinder trying to interact with them through modules like
 700 IPC::Run.  Frequently, programs alter their behavior when they detect
 701 that stdin, stdout, or stderr are not connected to a tty, assuming that
 702 they are being run in batch mode.  Whether this helps or hurts depends
 703 on which optimizations change.  And there's often no way of telling
 704 what a program does in these areas other than trial and error and,
 705 occasionally, reading the source.  This includes different versions
 706 and implementations of the same program.
 707 .PP
 708 All hope is not lost, however.  Most programs behave in reasonably
 709 tractable manners, once you figure out what it's trying to do.
 710 .PP
 711 Here are some of the issues you might need to be aware of.
 712 .IP "\(bu" 4
 713 \&\fIfflush()\fRing stdout and stderr
 714 .Sp
 715 This lets the user see stdout and stderr immediately.  Many programs
 716 undo this optimization if stdout is not a tty, making them harder to
 717 manage by things like IPC::Run.
 718 .Sp
 719 Many programs decline to fflush stdout or stderr if they do not
 720 detect a tty there.  Some ftp commands do this, for instance.
 721 .Sp
 722 If this happens to you, look for a way to force interactive behavior,
 723 like a command line switch or command.  If you can't, you will
 724 need to use a pseudo terminal ('<pty<' and '>pty>').
 725 .IP "\(bu" 4
 726 false prompts
 727 .Sp
 728 Interactive programs generally do not guarantee that output from user
 729 commands won't contain a prompt string.  For example, your shell prompt
 730 might be a '$', and a file named '$' might be the only file in a directory
 731 listing.
 732 .Sp
 733 This can make it hard to guarantee that your output parser won't be fooled
 734 into early termination of results.
 735 .Sp
 736 To help work around this, you can see if the program can alter it's
 737 prompt, and use something you feel is never going to occur in actual
 738 practice.
 739 .Sp
 740 You should also look for your prompt to be the only thing on a line:
 741 .Sp
 742 .Vb 1
 743 \&   pump $h until $out =~ /^<SILLYPROMPT>\es?\ez/m;
 744 .Ve
 745 .Sp
 746 (use \f(CW\*(C`(?!\en)\eZ\*(C'\fR in place of \f(CW\*(C`\ez\*(C'\fR on older perls).
 747 .Sp
 748 You can also take the approach that IPC::ChildSafe takes and emit a
 749 command with known output after each 'real' command you issue, then
 750 look for this known output.  See \fInew_appender()\fR and \fInew_chunker()\fR for
 751 filters that can help with this task.
 752 .Sp
 753 If it's not convenient or possibly to alter a prompt or use a known
 754 command/response pair, you might need to autodetect the prompt in case
 755 the local version of the child program is different then the one
 756 you tested with, or if the user has control over the look & feel of
 757 the prompt.
 758 .IP "\(bu" 4
 759 Refusing to accept input unless stdin is a tty.
 760 .Sp
 761 Some programs, for security reasons, will only accept certain types
 762 of input from a tty.  su, notable, will not prompt for a password unless
 763 it's connected to a tty.
 764 .Sp
 765 If this is your situation, use a pseudo terminal ('<pty<' and '>pty>').
 766 .IP "\(bu" 4
 767 Not prompting unless connected to a tty.
 768 .Sp
 769 Some programs don't prompt unless stdin or stdout is a tty.  See if you can
 770 turn prompting back on.  If not, see if you can come up with a command that
 771 you can issue after every real command and look for it's output, as
 772 IPC::ChildSafe does.   There are two filters included with IPC::Run that
 773 can help with doing this: appender and chunker (see \fInew_appender()\fR and
 774 \&\fInew_chunker()\fR).
 775 .IP "\(bu" 4
 776 Different output format when not connected to a tty.
 777 .Sp
 778 Some commands alter their formats to ease machine parsability when they
 779 aren't connected to a pipe.  This is actually good, but can be surprising.
 780 .SH "PSEUDO TERMINALS"
 781 .IX Header "PSEUDO TERMINALS"
 782 On systems providing pseudo terminals under /dev, IPC::Run can use IO::Pty
 783 (available on \s-1CPAN\s0) to provide a terminal environment to subprocesses.
 784 This is necessary when the subprocess really wants to think it's connected
 785 to a real terminal.
 786 .SS "\s-1CAVEATS\s0"
 787 .IX Subsection "CAVEATS"
 788 Psuedo-terminals are not pipes, though they are similar.  Here are some
 789 differences to watch out for.
 790 .IP "Echoing" 4
 791 .IX Item "Echoing"
 792 Sending to stdin will cause an echo on stdout, which occurs before each
 793 line is passed to the child program.  There is currently no way to
 794 disable this, although the child process can and should disable it for
 795 things like passwords.
 796 .IP "Shutdown" 4
 797 .IX Item "Shutdown"
 798 IPC::Run cannot close a pty until all output has been collected.  This
 799 means that it is not possible to send an \s-1EOF\s0 to stdin by half-closing
 800 the pty, as we can when using a pipe to stdin.
 801 .Sp
 802 This means that you need to send the child process an exit command or
 803 signal, or \fIrun()\fR / \fIfinish()\fR will time out.  Be careful not to expect a
 804 prompt after sending the exit command.
 805 .IP "Command line editing" 4
 806 .IX Item "Command line editing"
 807 Some subprocesses, notable shells that depend on the user's prompt
 808 settings, will reissue the prompt plus the command line input so far
 809 once for each character.
 810 .IP "'>pty>' means '&>pty>', not '1>pty>'" 4
 811 .IX Item "'>pty>' means '&>pty>', not '1>pty>'"
 812 The pseudo terminal redirects both stdout and stderr unless you specify
 813 a file descriptor.  If you want to grab stderr separately, do this:
 814 .Sp
 815 .Vb 1
 816 \&   start \e@cmd, \*(Aq<pty<\*(Aq, \e$in, \*(Aq>pty>\*(Aq, \e$out, \*(Aq2>\*(Aq, \e$err;
 817 .Ve
 818 .IP "stdin, stdout, and stderr not inherited" 4
 819 .IX Item "stdin, stdout, and stderr not inherited"
 820 Child processes harnessed to a pseudo terminal have their stdin, stdout,
 821 and stderr completely closed before any redirection operators take
 822 effect.  This casts of the bonds of the controlling terminal.  This is
 823 not done when using pipes.
 824 .Sp
 825 Right now, this affects all children in a harness that has a pty in use,
 826 even if that pty would not affect a particular child.  That's a bug and
 827 will be fixed.  Until it is, it's best not to mix-and-match children.
 828 .SS "Redirection Operators"
 829 .IX Subsection "Redirection Operators"
 830 .Vb 3
 831 \&   Operator       SHNP   Description
 832 \&   ========       ====   ===========
 833 \&   <, N<          SHN    Redirects input to a child\*(Aqs fd N (0 assumed)
 834 \&
 835 \&   >, N>          SHN    Redirects output from a child\*(Aqs fd N (1 assumed)
 836 \&   >>, N>>        SHN    Like \*(Aq>\*(Aq, but appends to scalars or named files
 837 \&   >&, &>         SHN    Redirects stdout & stderr from a child process
 838 \&
 839 \&   <pty, N<pty    S      Like \*(Aq<\*(Aq, but uses a pseudo\-tty instead of a pipe
 840 \&   >pty, N>pty    S      Like \*(Aq>\*(Aq, but uses a pseudo\-tty instead of a pipe
 841 \&
 842 \&   N<&M                  Dups input fd N to input fd M
 843 \&   M>&N                  Dups output fd N to input fd M
 844 \&   N<&\-                  Closes fd N
 845 \&
 846 \&   <pipe, N<pipe     P   Pipe opens H for caller to read, write, close.
 847 \&   >pipe, N>pipe     P   Pipe opens H for caller to read, write, close.
 848 .Ve
 849 .PP
 850 \&'N' and 'M' are placeholders for integer file descriptor numbers.  The
 851 terms 'input' and 'output' are from the child process's perspective.
 852 .PP
 853 The \s-1SHNP\s0 field indicates what parameters an operator can take:
 854 .PP
 855 .Vb 6
 856 \&   S: \e$scalar or \e&function references.  Filters may be used with
 857 \&      these operators (and only these).
 858 \&   H: \e*HANDLE or IO::Handle for caller to open, and close
 859 \&   N: "file name".
 860 \&   P: \e*HANDLE opened by IPC::Run as the parent end of a pipe, but read
 861 \&      and written to and closed by the caller (like IPC::Open3).
 862 .Ve
 863 .IP "Redirecting input: [n]<, [n]<pipe" 4
 864 .IX Item "Redirecting input: [n]<, [n]<pipe"
 865 You can input the child reads on file descriptor number n to come from a
 866 scalar variable, subroutine, file handle, or a named file.  If stdin
 867 is not redirected, the parent's stdin is inherited.
 868 .Sp
 869 .Vb 2
 870 \&   run \e@cat, \eundef          ## Closes child\*(Aqs stdin immediately
 871 \&      or die "cat returned $?";
 872 \&
 873 \&   run \e@cat, \e$in;
 874 \&
 875 \&   run \e@cat, \e<<TOHERE;
 876 \&   blah
 877 \&   TOHERE
 878 \&
 879 \&   run \e@cat, \e&input;       ## Calls &input, feeding data returned
 880 \&                              ## to child\*(Aqs.  Closes child\*(Aqs stdin
 881 \&                              ## when undef is returned.
 882 .Ve
 883 .Sp
 884 Redirecting from named files requires you to use the input
 885 redirection operator:
 886 .Sp
 887 .Vb 2
 888 \&   run \e@cat, \*(Aq<.profile\*(Aq;
 889 \&   run \e@cat, \*(Aq<\*(Aq, \*(Aq.profile\*(Aq;
 890 \&
 891 \&   open IN, "<foo";
 892 \&   run \e@cat, \e*IN;
 893 \&   run \e@cat, *IN{IO};
 894 .Ve
 895 .Sp
 896 The form used second example here is the safest,
 897 since filenames like \*(L"0\*(R" and \*(L"&more\en\*(R" won't confuse &run:
 898 .Sp
 899 You can't do either of
 900 .Sp
 901 .Vb 2
 902 \&   run \e@a, *IN;      ## INVALID
 903 \&   run \e@a, \*(Aq<\*(Aq, *IN; ## BUGGY: Reads file named like "*main::A"
 904 .Ve
 905 .Sp
 906 because perl passes a scalar containing a string that
 907 looks like \*(L"*main::A\*(R" to &run, and &run can't tell the difference
 908 between that and a redirection operator or a file name.  &run guarantees
 909 that any scalar you pass after a redirection operator is a file name.
 910 .Sp
 911 If your child process will take input from file descriptors other
 912 than 0 (stdin), you can use a redirection operator with any of the
 913 valid input forms (scalar ref, sub ref, etc.):
 914 .Sp
 915 .Vb 1
 916 \&   run \e@cat, \*(Aq3<\*(Aq, \e$in3;
 917 .Ve
 918 .Sp
 919 When redirecting input from a scalar ref, the scalar ref is
 920 used as a queue.  This allows you to use &harness and \fIpump()\fR to
 921 feed incremental bits of input to a coprocess.  See \*(L"Coprocesses\*(R"
 922 below for more information.
 923 .Sp
 924 The <pipe operator opens the write half of a pipe on the filehandle
 925 glob reference it takes as an argument:
 926 .Sp
 927 .Vb 5
 928 \&   $h = start \e@cat, \*(Aq<pipe\*(Aq, \e*IN;
 929 \&   print IN "hello world\en";
 930 \&   pump $h;
 931 \&   close IN;
 932 \&   finish $h;
 933 .Ve
 934 .Sp
 935 Unlike the other '<' operators, IPC::Run does nothing further with
 936 it: you are responsible for it.  The previous example is functionally
 937 equivalent to:
 938 .Sp
 939 .Vb 6
 940 \&   pipe( \e*R, \e*IN ) or die $!;
 941 \&   $h = start \e@cat, \*(Aq<\*(Aq, \e*IN;
 942 \&   print IN "hello world\en";
 943 \&   pump $h;
 944 \&   close IN;
 945 \&   finish $h;
 946 .Ve
 947 .Sp
 948 This is like the behavior of IPC::Open2 and IPC::Open3.
 949 .Sp
 950 \&\fBWin32\fR: The handle returned is actually a socket handle, so you can
 951 use \fIselect()\fR on it.
 952 .IP "Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe" 4
 953 .IX Item "Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe"
 954 You can redirect any output the child emits
 955 to a scalar variable, subroutine, file handle, or file name.  You
 956 can have &run truncate or append to named files or scalars.  If
 957 you are redirecting stdin as well, or if the command is on the
 958 receiving end of a pipeline ('|'), you can omit the redirection
 959 operator:
 960 .Sp
 961 .Vb 3
 962 \&   @ls = ( \*(Aqls\*(Aq );
 963 \&   run \e@ls, \eundef, \e$out
 964 \&      or die "ls returned $?";
 965 \&
 966 \&   run \e@ls, \eundef, \e&out;  ## Calls &out each time some output
 967 \&                              ## is received from the child\*(Aqs
 968 \&                              ## when undef is returned.
 969 \&
 970 \&   run \e@ls, \eundef, \*(Aq2>ls.err\*(Aq;
 971 \&   run \e@ls, \*(Aq2>\*(Aq, \*(Aqls.err\*(Aq;
 972 .Ve
 973 .Sp
 974 The two parameter form guarantees that the filename
 975 will not be interpreted as a redirection operator:
 976 .Sp
 977 .Vb 2
 978 \&   run \e@ls, \*(Aq>\*(Aq, "&more";
 979 \&   run \e@ls, \*(Aq2>\*(Aq, ">foo\en";
 980 .Ve
 981 .Sp
 982 You can pass file handles you've opened for writing:
 983 .Sp
 984 .Vb 3
 985 \&   open( *OUT, ">out.txt" );
 986 \&   open( *ERR, ">err.txt" );
 987 \&   run \e@cat, \e*OUT, \e*ERR;
 988 .Ve
 989 .Sp
 990 Passing a scalar reference and a code reference requires a little
 991 more work, but allows you to capture all of the output in a scalar
 992 or each piece of output by a callback:
 993 .Sp
 994 These two do the same things:
 995 .Sp
 996 .Vb 1
 997 \&   run( [ \*(Aqls\*(Aq ], \*(Aq2>\*(Aq, sub { $err_out .= $_[0] } );
 998 .Ve
 999 .Sp
1000 does the same basic thing as:
1001 .Sp
1002 .Vb 1
1003 \&   run( [ \*(Aqls\*(Aq ], \*(Aq2>\*(Aq, \e$err_out );
1004 .Ve
1005 .Sp
1006 The subroutine will be called each time some data is read from the child.
1007 .Sp
1008 The >pipe operator is different in concept than the other '>' operators,
1009 although it's syntax is similar:
1010 .Sp
1011 .Vb 7
1012 \&   $h = start \e@cat, $in, \*(Aq>pipe\*(Aq, \e*OUT, \*(Aq2>pipe\*(Aq, \e*ERR;
1013 \&   $in = "hello world\en";
1014 \&   finish $h;
1015 \&   print <OUT>;
1016 \&   print <ERR>;
1017 \&   close OUT;
1018 \&   close ERR;
1019 .Ve
1020 .Sp
1021 causes two pipe to be created, with one end attached to cat's stdout
1022 and stderr, respectively, and the other left open on \s-1OUT\s0 and \s-1ERR\s0, so
1023 that the script can manually
1024 \&\fIread()\fR, \fIselect()\fR, etc. on them.  This is like
1025 the behavior of IPC::Open2 and IPC::Open3.
1026 .Sp
1027 \&\fBWin32\fR: The handle returned is actually a socket handle, so you can
1028 use \fIselect()\fR on it.
1029 .IP "Duplicating output descriptors: >&m, n>&m" 4
1030 .IX Item "Duplicating output descriptors: >&m, n>&m"
1031 This duplicates output descriptor number n (default is 1 if n is omitted)
1032 from descriptor number m.
1033 .IP "Duplicating input descriptors: <&m, n<&m" 4
1034 .IX Item "Duplicating input descriptors: <&m, n<&m"
1035 This duplicates input descriptor number n (default is 0 if n is omitted)
1036 from descriptor number m
1037 .IP "Closing descriptors: <&\-, 3<&\-" 4
1038 .IX Item "Closing descriptors: <&-, 3<&-"
1039 This closes descriptor number n (default is 0 if n is omitted).  The
1040 following commands are equivalent:
1041 .Sp
1042 .Vb 3
1043 \&   run \e@cmd, \eundef;
1044 \&   run \e@cmd, \*(Aq<&\-\*(Aq;
1045 \&   run \e@cmd, \*(Aq<in.txt\*(Aq, \*(Aq<&\-\*(Aq;
1046 .Ve
1047 .Sp
1048 Doing
1049 .Sp
1050 .Vb 1
1051 \&   run \e@cmd, \e$in, \*(Aq<&\-\*(Aq;    ## SIGPIPE recipe.
1052 .Ve
1053 .Sp
1054 is dangerous: the parent will get a \s-1SIGPIPE\s0 if \f(CW$in\fR is not empty.
1055 .IP "Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&" 4
1056 .IX Item "Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&"
1057 The following pairs of commands are equivalent:
1058 .Sp
1059 .Vb 2
1060 \&   run \e@cmd, \*(Aq>&\*(Aq, \e$out;       run \e@cmd, \*(Aq>\*(Aq, \e$out,     \*(Aq2>&1\*(Aq;
1061 \&   run \e@cmd, \*(Aq>&\*(Aq, \*(Aqout.txt\*(Aq;   run \e@cmd, \*(Aq>\*(Aq, \*(Aqout.txt\*(Aq, \*(Aq2>&1\*(Aq;
1062 .Ve
1063 .Sp
1064 etc.
1065 .Sp
1066 File descriptor numbers are not permitted to the left or the right of
1067 these operators, and the '&' may occur on either end of the operator.
1068 .Sp
1069 The '&>pipe' and '>pipe&' variants behave like the '>pipe' operator, except
1070 that both stdout and stderr write to the created pipe.
1071 .IP "Redirection Filters" 4
1072 .IX Item "Redirection Filters"
1073 Both input redirections and output redirections that use scalars or
1074 subs as endpoints may have an arbitrary number of filter subs placed
1075 between them and the child process.  This is useful if you want to
1076 receive output in chunks, or if you want to massage each chunk of
1077 data sent to the child.  To use this feature, you must use operator
1078 syntax:
1079 .Sp
1080 .Vb 5
1081 \&   run(
1082 \&      \e@cmd
1083 \&         \*(Aq<\*(Aq, \e&in_filter_2, \e&in_filter_1, $in,
1084 \&         \*(Aq>\*(Aq, \e&out_filter_1, \e&in_filter_2, $out,
1085 \&   );
1086 .Ve
1087 .Sp
1088 This capability is not provided for \s-1IO\s0 handles or named files.
1089 .Sp
1090 Two filters are provided by IPC::Run: appender and chunker.  Because
1091 these may take an argument, you need to use the constructor functions
1092 \&\fInew_appender()\fR and \fInew_chunker()\fR rather than using \e& syntax:
1093 .Sp
1094 .Vb 5
1095 \&   run(
1096 \&      \e@cmd
1097 \&         \*(Aq<\*(Aq, new_appender( "\en" ), $in,
1098 \&         \*(Aq>\*(Aq, new_chunker, $out,
1099 \&   );
1100 .Ve
1101 .SS "Just doing I/O"
1102 .IX Subsection "Just doing I/O"
1103 If you just want to do I/O to a handle or file you open yourself, you
1104 may specify a filehandle or filename instead of a command in the harness
1105 specification:
1106 .PP
1107 .Vb 1
1108 \&   run io( "filename", \*(Aq>\*(Aq, \e$recv );
1109 \&
1110 \&   $h = start io( $io, \*(Aq>\*(Aq, \e$recv );
1111 \&
1112 \&   $h = harness \e@cmd, \*(Aq&\*(Aq, io( "file", \*(Aq<\*(Aq, \e$send );
1113 .Ve
1114 .SS "Options"
1115 .IX Subsection "Options"
1116 Options are passed in as name/value pairs:
1117 .PP
1118 .Vb 1
1119 \&   run \e@cat, \e$in, debug => 1;
1120 .Ve
1121 .PP
1122 If you pass the debug option, you may want to pass it in first, so you
1123 can see what parsing is going on:
1124 .PP
1125 .Vb 1
1126 \&   run debug => 1, \e@cat, \e$in;
1127 .Ve
1128 .IP "debug" 4
1129 .IX Item "debug"
1130 Enables debugging output in parent and child.  Debugging info is emitted
1131 to the \s-1STDERR\s0 that was present when IPC::Run was first \f(CW\*(C`use()\*(C'\fRed (it's
1132 \&\f(CW\*(C`dup()\*(C'\fRed out of the way so that it can be redirected in children without
1133 having debugging output emitted on it).
1134 .SH "RETURN VALUES"
1135 .IX Header "RETURN VALUES"
1136 \&\fIharness()\fR and \fIstart()\fR return a reference to an IPC::Run harness.  This is
1137 blessed in to the IPC::Run package, so you may make later calls to
1138 functions as members if you like:
1139 .PP
1140 .Vb 4
1141 \&   $h = harness( ... );
1142 \&   $h\->start;
1143 \&   $h\->pump;
1144 \&   $h\->finish;
1145 \&
1146 \&   $h = start( .... );
1147 \&   $h\->pump;
1148 \&   ...
1149 .Ve
1150 .PP
1151 Of course, using method call syntax lets you deal with any IPC::Run
1152 subclasses that might crop up, but don't hold your breath waiting for
1153 any.
1154 .PP
1155 \&\fIrun()\fR and \fIfinish()\fR return \s-1TRUE\s0 when all subcommands exit with a 0 result
1156 code.  \fBThis is the opposite of perl's \f(BIsystem()\fB command\fR.
1157 .PP
1158 All routines raise exceptions (via \fIdie()\fR) when error conditions are
1159 recognized.  A non-zero command result is not treated as an error
1160 condition, since some commands are tests whose results are reported
1161 in their exit codes.
1162 .SH "ROUTINES"
1163 .IX Header "ROUTINES"
1164 .IP "run" 4
1165 .IX Item "run"
1166 Run takes a harness or harness specification and runs it, pumping
1167 all input to the child(ren), closing the input pipes when no more
1168 input is available, collecting all output that arrives, until the
1169 pipes delivering output are closed, then waiting for the children to
1170 exit and reaping their result codes.
1171 .Sp
1172 You may think of \f(CW\*(C`run( ... )\*(C'\fR as being like
1173 .Sp
1174 .Vb 1
1175 \&   start( ... )\->finish();
1176 .Ve
1177 .Sp
1178 , though there is one subtle difference: \fIrun()\fR does not
1179 set \e$input_scalars to '' like \fIfinish()\fR does.  If an exception is thrown
1180 from \fIrun()\fR, all children will be killed off \*(L"gently\*(R", and then \*(L"annihilated\*(R"
1181 if they do not go gently (in to that dark night. sorry).
1182 .Sp
1183 If any exceptions are thrown, this does a \*(L"kill_kill\*(R" before propogating
1184 them.
1185 .IP "signal" 4
1186 .IX Item "signal"
1187 .Vb 3
1188 \&   ## To send it a specific signal by name ("USR1"):
1189 \&   signal $h, "USR1";
1190 \&   $h\->signal ( "USR1" );
1191 .Ve
1192 .Sp
1193 If \f(CW$signal\fR is provided and defined, sends a signal to all child processes.  Try
1194 not to send numeric signals, use \f(CW"KILL"\fR instead of \f(CW9\fR, for instance.
1195 Numeric signals aren't portable.
1196 .Sp
1197 Throws an exception if \f(CW$signal\fR is undef.
1198 .Sp
1199 This will \fInot\fR clean up the harness, \f(CW\*(C`finish\*(C'\fR it if you kill it.
1200 .Sp
1201 Normally \s-1TERM\s0 kills a process gracefully (this is what the command line utility
1202 \&\f(CW\*(C`kill\*(C'\fR does by default), \s-1INT\s0 is sent by one of the keys \f(CW\*(C`^C\*(C'\fR, \f(CW\*(C`Backspace\*(C'\fR or
1203 \&\f(CW\*(C`<Del>\*(C'\fR, and \f(CW\*(C`QUIT\*(C'\fR is used to kill a process and make it coredump.
1204 .Sp
1205 The \f(CW\*(C`HUP\*(C'\fR signal is often used to get a process to \*(L"restart\*(R", rereading
1206 config files, and \f(CW\*(C`USR1\*(C'\fR and \f(CW\*(C`USR2\*(C'\fR for really application-specific things.
1207 .Sp
1208 Often, running \f(CW\*(C`kill \-l\*(C'\fR (that's a lower case \*(L"L\*(R") on the command line will
1209 list the signals present on your operating system.
1210 .Sp
1211 \&\fB\s-1WARNING\s0\fR: The signal subsystem is not at all portable.  We *may* offer
1212 to simulate \f(CW\*(C`TERM\*(C'\fR and \f(CW\*(C`KILL\*(C'\fR on some operating systems, submit code
1213 to me if you want this.
1214 .Sp
1215 \&\fB\s-1WARNING\s0 2\fR: Up to and including perl v5.6.1, doing almost anything in a
1216 signal handler could be dangerous.  The most safe code avoids all
1217 mallocs and system calls, usually by preallocating a flag before
1218 entering the signal handler, altering the flag's value in the
1219 handler, and responding to the changed value in the main system:
1220 .Sp
1221 .Vb 2
1222 \&   my $got_usr1 = 0;
1223 \&   sub usr1_handler { ++$got_signal }
1224 \&
1225 \&   $SIG{USR1} = \e&usr1_handler;
1226 \&   while () { sleep 1; print "GOT IT" while $got_usr1\-\-; }
1227 .Ve
1228 .Sp
1229 Even this approach is perilous if ++ and \*(-- aren't atomic on your system
1230 (I've never heard of this on any modern \s-1CPU\s0 large enough to run perl).
1231 .IP "kill_kill" 4
1232 .IX Item "kill_kill"
1233 .Vb 3
1234 \&   ## To kill off a process:
1235 \&   $h\->kill_kill;
1236 \&   kill_kill $h;
1237 \&
1238 \&   ## To specify the grace period other than 30 seconds:
1239 \&   kill_kill $h, grace => 5;
1240 \&
1241 \&   ## To send QUIT instead of KILL if a process refuses to die:
1242 \&   kill_kill $h, coup_d_grace => "QUIT";
1243 .Ve
1244 .Sp
1245 Sends a \f(CW\*(C`TERM\*(C'\fR, waits for all children to exit for up to 30 seconds, then
1246 sends a \f(CW\*(C`KILL\*(C'\fR to any that survived the \f(CW\*(C`TERM\*(C'\fR.
1247 .Sp
1248 Will wait for up to 30 more seconds for the \s-1OS\s0 to sucessfully \f(CW\*(C`KILL\*(C'\fR the
1249 processes.
1250 .Sp
1251 The 30 seconds may be overriden by setting the \f(CW\*(C`grace\*(C'\fR option, this
1252 overrides both timers.
1253 .Sp
1254 The harness is then cleaned up.
1255 .Sp
1256 The doubled name indicates that this function may kill again and avoids
1257 colliding with the core Perl \f(CW\*(C`kill\*(C'\fR function.
1258 .Sp
1259 Returns a 1 if the \f(CW\*(C`TERM\*(C'\fR was sufficient, or a 0 if \f(CW\*(C`KILL\*(C'\fR was
1260 required.  Throws an exception if \f(CW\*(C`KILL\*(C'\fR did not permit the children
1261 to be reaped.
1262 .Sp
1263 \&\fB\s-1NOTE\s0\fR: The grace period is actually up to 1 second longer than that
1264 given.  This is because the granularity of \f(CW\*(C`time\*(C'\fR is 1 second.  Let me
1265 know if you need finer granularity, we can leverage Time::HiRes here.
1266 .Sp
1267 \&\fBWin32\fR: Win32 does not know how to send real signals, so \f(CW\*(C`TERM\*(C'\fR is
1268 a full-force kill on Win32.  Thus all talk of grace periods, etc. do
1269 not apply to Win32.
1270 .IP "harness" 4
1271 .IX Item "harness"
1272 Takes a harness specification and returns a harness.  This harness is
1273 blessed in to IPC::Run, allowing you to use method call syntax for
1274 \&\fIrun()\fR, \fIstart()\fR, et al if you like.
1275 .Sp
1276 \&\fIharness()\fR is provided so that you can pre-build harnesses if you
1277 would like to, but it's not required..
1278 .Sp
1279 You may proceed to \fIrun()\fR, \fIstart()\fR or \fIpump()\fR after calling \fIharness()\fR (\fIpump()\fR
1280 calls \fIstart()\fR if need be).  Alternatively, you may pass your
1281 harness specification to \fIrun()\fR or \fIstart()\fR and let them \fIharness()\fR for
1282 you.  You can't pass harness specifications to \fIpump()\fR, though.
1283 .IP "close_terminal" 4
1284 .IX Item "close_terminal"
1285 This is used as (or in) an init sub to cast off the bonds of a controlling
1286 terminal.  It must precede all other redirection ops that affect
1287 \&\s-1STDIN\s0, \s-1STDOUT\s0, or \s-1STDERR\s0 to be guaranteed effective.
1288 .IP "start" 4
1289 .IX Item "start"
1290 .Vb 5
1291 \&   $h = start(
1292 \&      \e@cmd, \e$in, \e$out, ...,
1293 \&      timeout( 30, name => "process timeout" ),
1294 \&      $stall_timeout = timeout( 10, name => "stall timeout"   ),
1295 \&   );
1296 \&
1297 \&   $h = start \e@cmd, \*(Aq<\*(Aq, \e$in, \*(Aq|\*(Aq, \e@cmd2, ...;
1298 .Ve
1299 .Sp
1300 \&\fIstart()\fR accepts a harness or harness specification and returns a harness
1301 after building all of the pipes and launching (via \fIfork()\fR/\fIexec()\fR, or, maybe
1302 someday, \fIspawn()\fR) all the child processes.  It does not send or receive any
1303 data on the pipes, see \fIpump()\fR and \fIfinish()\fR for that.
1304 .Sp
1305 You may call \fIharness()\fR and then pass it's result to \fIstart()\fR if you like,
1306 but you only need to if it helps you structure or tune your application.
1307 If you do call \fIharness()\fR, you may skip \fIstart()\fR and proceed directly to
1308 pump.
1309 .Sp
1310 \&\fIstart()\fR also starts all timers in the harness.  See IPC::Run::Timer
1311 for more information.
1312 .Sp
1313 \&\fIstart()\fR flushes \s-1STDOUT\s0 and \s-1STDERR\s0 to help you avoid duplicate output.
1314 It has no way of asking Perl to flush all your open filehandles, so
1315 you are going to need to flush any others you have open.  Sorry.
1316 .Sp
1317 Here's how if you don't want to alter the state of $| for your
1318 filehandle:
1319 .Sp
1320 .Vb 1
1321 \&   $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;
1322 .Ve
1323 .Sp
1324 If you don't mind leaving output unbuffered on \s-1HANDLE\s0, you can do
1325 the slightly shorter
1326 .Sp
1327 .Vb 1
1328 \&   $ofh = select HANDLE; $| = 1; select $ofh;
1329 .Ve
1330 .Sp
1331 Or, you can use IO::Handle's \fIflush()\fR method:
1332 .Sp
1333 .Vb 2
1334 \&   use IO::Handle;
1335 \&   flush HANDLE;
1336 .Ve
1337 .Sp
1338 Perl needs the equivalent of C's fflush( (\s-1FILE\s0 *)NULL ).
1339 .IP "pump" 4
1340 .IX Item "pump"
1341 .Vb 2
1342 \&   pump $h;
1343 \&   $h\->pump;
1344 .Ve
1345 .Sp
1346 Pump accepts a single parameter harness.  It blocks until it delivers some
1347 input or recieves some output.  It returns \s-1TRUE\s0 if there is still input or
1348 output to be done, \s-1FALSE\s0 otherwise.
1349 .Sp
1350 \&\fIpump()\fR will automatically call \fIstart()\fR if need be, so you may call \fIharness()\fR
1351 then proceed to \fIpump()\fR if that helps you structure your application.
1352 .Sp
1353 If \fIpump()\fR is called after all harnessed activities have completed, a \*(L"process
1354 ended prematurely\*(R" exception to be thrown.  This allows for simple scripting
1355 of external applications without having to add lots of error handling code at
1356 each step of the script:
1357 .Sp
1358 .Vb 1
1359 \&   $h = harness \e@smbclient, \e$in, \e$out, $err;
1360 \&
1361 \&   $in = "cd /foo\en";
1362 \&   $h\->pump until $out =~ /^smb.*> \eZ/m;
1363 \&   die "error cding to /foo:\en$out" if $out =~ "ERR";
1364 \&   $out = \*(Aq\*(Aq;
1365 \&
1366 \&   $in = "mget *\en";
1367 \&   $h\->pump until $out =~ /^smb.*> \eZ/m;
1368 \&   die "error retrieving files:\en$out" if $out =~ "ERR";
1369 \&
1370 \&   $h\->finish;
1371 \&
1372 \&   warn $err if $err;
1373 .Ve
1374 .IP "pump_nb" 4
1375 .IX Item "pump_nb"
1376 .Vb 2
1377 \&   pump_nb $h;
1378 \&   $h\->pump_nb;
1379 .Ve
1380 .Sp
1381 \&\*(L"\fIpump()\fR non-blocking\*(R", pumps if anything's ready to be pumped, returns
1382 immediately otherwise.  This is useful if you're doing some long-running
1383 task in the foreground, but don't want to starve any child processes.
1384 .IP "pumpable" 4
1385 .IX Item "pumpable"
1386 Returns \s-1TRUE\s0 if calling \fIpump()\fR won't throw an immediate \*(L"process ended
1387 prematurely\*(R" exception.  This means that there are open I/O channels or
1388 active processes. May yield the parent processes' time slice for 0.01
1389 second if all pipes are to the child and all are paused.  In this case
1390 we can't tell if the child is dead, so we yield the processor and
1391 then attempt to reap the child in a nonblocking way.
1392 .IP "reap_nb" 4
1393 .IX Item "reap_nb"
1394 Attempts to reap child processes, but does not block.
1395 .Sp
1396 Does not currently take any parameters, one day it will allow specific
1397 children to be reaped.
1398 .Sp
1399 Only call this from a signal handler if your \f(CW\*(C`perl\*(C'\fR is recent enough
1400 to have safe signal handling (5.6.1 did not, \s-1IIRC\s0, but it was beign discussed
1401 on perl5\-porters).  Calling this (or doing any significant work) in a signal
1402 handler on older \f(CW\*(C`perl\*(C'\fRs is asking for seg faults.
1403 .IP "finish" 4
1404 .IX Item "finish"
1405 This must be called after the last \fIstart()\fR or \fIpump()\fR call for a harness,
1406 or your system will accumulate defunct processes and you may \*(L"leak\*(R"
1407 file descriptors.
1408 .Sp
1409 \&\fIfinish()\fR returns \s-1TRUE\s0 if all children returned 0 (and were not signaled and did
1410 not coredump, ie ! $?), and \s-1FALSE\s0 otherwise (this is like \fIrun()\fR, and the
1411 opposite of \fIsystem()\fR).
1412 .Sp
1413 Once a harness has been finished, it may be \fIrun()\fR or \fIstart()\fRed again,
1414 including by \fIpump()\fRs auto-start.
1415 .Sp
1416 If this throws an exception rather than a normal exit, the harness may
1417 be left in an unstable state, it's best to kill the harness to get rid
1418 of all the child processes, etc.
1419 .Sp
1420 Specifically, if a timeout expires in \fIfinish()\fR, \fIfinish()\fR will not
1421 kill all the children.  Call \f(CW\*(C`<$h\-\*(C'\fRkill_kill>> in this case if you care.
1422 This differs from the behavior of \*(L"run\*(R".
1423 .IP "result" 4
1424 .IX Item "result"
1425 .Vb 1
1426 \&   $h\->result;
1427 .Ve
1428 .Sp
1429 Returns the first non-zero result code (ie $? >> 8).  See \*(L"full_result\*(R" to
1430 get the $? value for a child process.
1431 .Sp
1432 To get the result of a particular child, do:
1433 .Sp
1434 .Vb 2
1435 \&   $h\->result( 0 );  # first child\*(Aqs $? >> 8
1436 \&   $h\->result( 1 );  # second child
1437 .Ve
1438 .Sp
1439 or
1440 .Sp
1441 .Vb 2
1442 \&   ($h\->results)[0]
1443 \&   ($h\->results)[1]
1444 .Ve
1445 .Sp
1446 Returns undef if no child processes were spawned and no child number was
1447 specified.  Throws an exception if an out-of-range child number is passed.
1448 .IP "results" 4
1449 .IX Item "results"
1450 Returns a list of child exit values.  See \*(L"full_results\*(R" if you want to
1451 know if a signal killed the child.
1452 .Sp
1453 Throws an exception if the harness is not in a finished state.
1454 .IP "full_result" 4
1455 .IX Item "full_result"
1456 .Vb 1
1457 \&   $h\->full_result;
1458 .Ve
1459 .Sp
1460 Returns the first non-zero $?.  See \*(L"result\*(R" to get the first $? >> 8
1461 value for a child process.
1462 .Sp
1463 To get the result of a particular child, do:
1464 .Sp
1465 .Vb 2
1466 \&   $h\->full_result( 0 );  # first child\*(Aqs $? >> 8
1467 \&   $h\->full_result( 1 );  # second child
1468 .Ve
1469 .Sp
1470 or
1471 .Sp
1472 .Vb 2
1473 \&   ($h\->full_results)[0]
1474 \&   ($h\->full_results)[1]
1475 .Ve
1476 .Sp
1477 Returns undef if no child processes were spawned and no child number was
1478 specified.  Throws an exception if an out-of-range child number is passed.
1479 .IP "full_results" 4
1480 .IX Item "full_results"
1481 Returns a list of child exit values as returned by \f(CW\*(C`wait\*(C'\fR.  See \*(L"results\*(R"
1482 if you don't care about coredumps or signals.
1483 .Sp
1484 Throws an exception if the harness is not in a finished state.
1485 .SH "FILTERS"
1486 .IX Header "FILTERS"
1487 These filters are used to modify input our output between a child
1488 process and a scalar or subroutine endpoint.
1489 .IP "binary" 4
1490 .IX Item "binary"
1491 .Vb 3
1492 \&   run \e@cmd, ">", binary, \e$out;
1493 \&   run \e@cmd, ">", binary, \e$out;  ## Any TRUE value to enable
1494 \&   run \e@cmd, ">", binary 0, \e$out;  ## Any FALSE value to disable
1495 .Ve
1496 .Sp
1497 This is a constructor for a \*(L"binmode\*(R" \*(L"filter\*(R" that tells IPC::Run to keep
1498 the carriage returns that would ordinarily be edited out for you (binmode
1499 is usually off).  This is not a real filter, but an option masquerading as
1500 a filter.
1501 .Sp
1502 It's not named \*(L"binmode\*(R" because you're likely to want to call Perl's binmode
1503 in programs that are piping binary data around.
1504 .IP "new_chunker" 4
1505 .IX Item "new_chunker"
1506 This breaks a stream of data in to chunks, based on an optional
1507 scalar or regular expression parameter.  The default is the Perl
1508 input record separator in $/, which is a newline be default.
1509 .Sp
1510 .Vb 2
1511 \&   run \e@cmd, \*(Aq>\*(Aq, new_chunker, \e&lines_handler;
1512 \&   run \e@cmd, \*(Aq>\*(Aq, new_chunker( "\er\en" ), \e&lines_handler;
1513 .Ve
1514 .Sp
1515 Because this uses $/ by default, you should always pass in a parameter
1516 if you are worried about other code (modules, etc) modifying $/.
1517 .Sp
1518 If this filter is last in a filter chain that dumps in to a scalar,
1519 the scalar must be set to '' before a new chunk will be written to it.
1520 .Sp
1521 As an example of how a filter like this can be written, here's a
1522 chunker that splits on newlines:
1523 .Sp
1524 .Vb 2
1525 \&   sub line_splitter {
1526 \&      my ( $in_ref, $out_ref ) = @_;
1527 \&
1528 \&      return 0 if length $$out_ref;
1529 \&
1530 \&      return input_avail && do {
1531 \&         while (1) {
1532 \&            if ( $$in_ref =~ s/\eA(.*?\en)// ) {
1533 \&               $$out_ref .= $1;
1534 \&               return 1;
1535 \&            }
1536 \&            my $hmm = get_more_input;
1537 \&            unless ( defined $hmm ) {
1538 \&               $$out_ref = $$in_ref;
1539 \&               $$in_ref = \*(Aq\*(Aq;
1540 \&               return length $$out_ref ? 1 : 0;
1541 \&            }
1542 \&            return 0 if $hmm eq 0;
1543 \&         }
1544 \&      }
1545 \&   };
1546 .Ve
1547 .IP "new_appender" 4
1548 .IX Item "new_appender"
1549 This appends a fixed string to each chunk of data read from the source
1550 scalar or sub.  This might be useful if you're writing commands to a
1551 child process that always must end in a fixed string, like \*(L"\en\*(R":
1552 .Sp
1553 .Vb 3
1554 \&   run( \e@cmd,
1555 \&      \*(Aq<\*(Aq, new_appender( "\en" ), \e&commands,
1556 \&   );
1557 .Ve
1558 .Sp
1559 Here's a typical filter sub that might be created by \fInew_appender()\fR:
1560 .Sp
1561 .Vb 2
1562 \&   sub newline_appender {
1563 \&      my ( $in_ref, $out_ref ) = @_;
1564 \&
1565 \&      return input_avail && do {
1566 \&         $$out_ref = join( \*(Aq\*(Aq, $$out_ref, $$in_ref, "\en" );
1567 \&         $$in_ref = \*(Aq\*(Aq;
1568 \&         1;
1569 \&      }
1570 \&   };
1571 .Ve
1572 .IP "io" 4
1573 .IX Item "io"
1574 Takes a filename or filehandle, a redirection operator, optional filters,
1575 and a source or destination (depends on the redirection operator).  Returns
1576 an IPC::Run::IO object suitable for \fIharness()\fRing (including via \fIstart()\fR
1577 or \fIrun()\fR).
1578 .Sp
1579 This is shorthand for
1580 .Sp
1581 .Vb 1
1582 \&   require IPC::Run::IO;
1583 \&
1584 \&      ... IPC::Run::IO\->new(...) ...
1585 .Ve
1586 .IP "timer" 4
1587 .IX Item "timer"
1588 .Vb 1
1589 \&   $h = start( \e@cmd, \e$in, \e$out, $t = timer( 5 ) );
1590 \&
1591 \&   pump $h until $out =~ /expected stuff/ || $t\->is_expired;
1592 .Ve
1593 .Sp
1594 Instantiates a non-fatal timer.  \fIpump()\fR returns once each time a timer
1595 expires.  Has no direct effect on \fIrun()\fR, but you can pass a subroutine
1596 to fire when the timer expires.
1597 .Sp
1598 See \*(L"timeout\*(R" for building timers that throw exceptions on
1599 expiration.
1600 .Sp
1601 See \*(L"timer\*(R" in IPC::Run::Timer for details.
1602 .IP "timeout" 4
1603 .IX Item "timeout"
1604 .Vb 1
1605 \&   $h = start( \e@cmd, \e$in, \e$out, $t = timeout( 5 ) );
1606 \&
1607 \&   pump $h until $out =~ /expected stuff/;
1608 .Ve
1609 .Sp
1610 Instantiates a timer that throws an exception when it expires.
1611 If you don't provide an exception, a default exception that matches
1612 /^IPC::Run: .*timed out/ is thrown by default.  You can pass in your own
1613 exception scalar or reference:
1614 .Sp
1615 .Vb 4
1616 \&   $h = start(
1617 \&      \e@cmd, \e$in, \e$out,
1618 \&      $t = timeout( 5, exception => \*(Aqslowpoke\*(Aq ),
1619 \&   );
1620 .Ve
1621 .Sp
1622 or set the name used in debugging message and in the default exception
1623 string:
1624 .Sp
1625 .Vb 5
1626 \&   $h = start(
1627 \&      \e@cmd, \e$in, \e$out,
1628 \&      timeout( 50, name => \*(Aqprocess timer\*(Aq ),
1629 \&      $stall_timer = timeout( 5, name => \*(Aqstall timer\*(Aq ),
1630 \&   );
1631 \&
1632 \&   pump $h until $out =~ /started/;
1633 \&
1634 \&   $in = \*(Aqcommand 1\*(Aq;
1635 \&   $stall_timer\->start;
1636 \&   pump $h until $out =~ /command 1 finished/;
1637 \&
1638 \&   $in = \*(Aqcommand 2\*(Aq;
1639 \&   $stall_timer\->start;
1640 \&   pump $h until $out =~ /command 2 finished/;
1641 \&
1642 \&   $in = \*(Aqvery slow command 3\*(Aq;
1643 \&   $stall_timer\->start( 10 );
1644 \&   pump $h until $out =~ /command 3 finished/;
1645 \&
1646 \&   $stall_timer\->start( 5 );
1647 \&   $in = \*(Aqcommand 4\*(Aq;
1648 \&   pump $h until $out =~ /command 4 finished/;
1649 \&
1650 \&   $stall_timer\->reset; # Prevent restarting or expirng
1651 \&   finish $h;
1652 .Ve
1653 .Sp
1654 See \*(L"timer\*(R" for building non-fatal timers.
1655 .Sp
1656 See \*(L"timer\*(R" in IPC::Run::Timer for details.
1657 .SH "FILTER IMPLEMENTATION FUNCTIONS"
1658 .IX Header "FILTER IMPLEMENTATION FUNCTIONS"
1659 These functions are for use from within filters.
1660 .IP "input_avail" 4
1661 .IX Item "input_avail"
1662 Returns \s-1TRUE\s0 if input is available.  If none is available, then
1663 &get_more_input is called and its result is returned.
1664 .Sp
1665 This is usually used in preference to &get_more_input so that the
1666 calling filter removes all data from the \f(CW$in_ref\fR before more data
1667 gets read in to \f(CW$in_ref\fR.
1668 .Sp
1669 \&\f(CW\*(C`input_avail\*(C'\fR is usually used as part of a return expression:
1670 .Sp
1671 .Vb 4
1672 \&   return input_avail && do {
1673 \&      ## process the input just gotten
1674 \&      1;
1675 \&   };
1676 .Ve
1677 .Sp
1678 This technique allows input_avail to return the undef or 0 that a
1679 filter normally returns when there's no input to process.  If a filter
1680 stores intermediate values, however, it will need to react to an
1681 undef:
1682 .Sp
1683 .Vb 7
1684 \&   my $got = input_avail;
1685 \&   if ( ! defined $got ) {
1686 \&      ## No more input ever, flush internal buffers to $out_ref
1687 \&   }
1688 \&   return $got unless $got;
1689 \&   ## Got some input, move as much as need be
1690 \&   return 1 if $added_to_out_ref;
1691 .Ve
1692 .IP "get_more_input" 4
1693 .IX Item "get_more_input"
1694 This is used to fetch more input in to the input variable.  It returns
1695 undef if there will never be any more input, 0 if there is none now,
1696 but there might be in the future, and \s-1TRUE\s0 if more input was gotten.
1697 .Sp
1698 \&\f(CW\*(C`get_more_input\*(C'\fR is usually used as part of a return expression,
1699 see \*(L"input_avail\*(R" for more information.
1700 .SH "TODO"
1701 .IX Header "TODO"
1702 These will be addressed as needed and as time allows.
1703 .PP
1704 Stall timeout.
1705 .PP
1706 Expose a list of child process objects.  When I do this,
1707 each child process is likely to be blessed into IPC::Run::Proc.
1708 .PP
1709 \&\f(CW$kid\fR\->\fIabort()\fR, \f(CW$kid\fR\->\fIkill()\fR, \f(CW$kid\fR\->signal( \f(CW$num_or_name\fR ).
1710 .PP
1711 Write tests for /(full_)?results?/ subs.
1712 .PP
1713 Currently, \fIpump()\fR and \fIrun()\fR only work on systems where \fIselect()\fR works on the
1714 filehandles returned by \fIpipe()\fR.  This does *not* include ActiveState on Win32,
1715 although it does work on cygwin under Win32 (thought the tests whine a bit).
1716 I'd like to rectify that, suggestions and patches welcome.
1717 .PP
1718 Likewise \fIstart()\fR only fully works on \fIfork()\fR/\fIexec()\fR machines (well, just
1719 \&\fIfork()\fR if you only ever pass perl subs as subprocesses).  There's
1720 some scaffolding for calling \fIOpen3::spawn_with_handles()\fR, but that's
1721 untested, and not that useful with limited \fIselect()\fR.
1722 .PP
1723 Support for \f(CW\*(C`\e@sub_cmd\*(C'\fR as an argument to a command which
1724 gets replaced with /dev/fd or the name of a temporary file containing foo's
1725 output.  This is like <(sub_cmd ...) found in bash and csh (\s-1IIRC\s0).
1726 .PP
1727 Allow multiple harnesses to be combined as independant sets of processes
1728 in to one 'meta\-harness'.
1729 .PP
1730 Allow a harness to be passed in place of an \e@cmd.  This would allow
1731 multiple harnesses to be aggregated.
1732 .PP
1733 Ability to add external file descriptors w/ filter chains and endpoints.
1734 .PP
1735 Ability to add timeouts and timing generators (i.e. repeating timeouts).
1736 .PP
1737 High resolution timeouts.
1738 .SH "Win32 LIMITATIONS"
1739 .IX Header "Win32 LIMITATIONS"
1740 .IP "Fails on Win9X" 4
1741 .IX Item "Fails on Win9X"
1742 If you want Win9X support, you'll have to debug it or fund me because I
1743 don't use that system any more.  The Win32 subsysem has been extended to
1744 use temporary files in simple \fIrun()\fR invocations and these may actually
1745 work on Win9X too, but I don't have time to work on it.
1746 .IP "May deadlock on Win2K (but not WinNT4 or WinXPPro)" 4
1747 .IX Item "May deadlock on Win2K (but not WinNT4 or WinXPPro)"
1748 Spawning more than one subprocess on Win2K causes a deadlock I haven't
1749 figured out yet, but simple uses of \fIrun()\fR often work.  Passes all tests
1750 on WinXPPro and WinNT.
1751 .IP "no support yet for <pty< and >pty>" 4
1752 .IX Item "no support yet for <pty< and >pty>"
1753 These are likely to be implemented as \*(L"<\*(R" and \*(L">\*(R" with binmode on, not
1754 sure.
1755 .IP "no support for file descriptors higher than 2 (stderr)" 4
1756 .IX Item "no support for file descriptors higher than 2 (stderr)"
1757 Win32 only allows passing explicit fds 0, 1, and 2.  If you really, really need to pass file handles, us Win32API:: \fIGetOsFHandle()\fR or ::\fIFdGetOsFHandle()\fR to
1758 get the integer handle and pass it to the child process using the command
1759 line, environment, stdin, intermediary file, or other \s-1IPC\s0 mechnism.  Then
1760 use that handle in the child (Win32API.pm provides ways to reconstitute
1761 Perl file handles from Win32 file handles).
1762 .IP "no support for subroutine subprocesses (\s-1CODE\s0 refs)" 4
1763 .IX Item "no support for subroutine subprocesses (CODE refs)"
1764 Can't \fIfork()\fR, so the subroutines would have no context, and closures certainly
1765 have no meaning
1766 .Sp
1767 Perhaps with Win32 \fIfork()\fR emulation, this can be supported in a limited
1768 fashion, but there are other very serious problems with that: all parent
1769 fds get \fIdup()\fRed in to the thread emulating the forked process, and that
1770 keeps the parent from being able to close all of the appropriate fds.
1771 .IP "no support for init => sub {} routines." 4
1772 .IX Item "no support for init => sub {} routines."
1773 Win32 processes are created from scratch, there is no way to do an init
1774 routine that will affect the running child.  Some limited support might
1775 be implemented one day, do \fIchdir()\fR and \f(CW%ENV\fR changes can be made.
1776 .IP "signals" 4
1777 .IX Item "signals"
1778 Win32 does not fully support signals.  \fIsignal()\fR is likely to cause errors
1779 unless sending a signal that Perl emulates, and \f(CW\*(C`kill_kill()\*(C'\fR is immediately
1780 fatal (there is no grace period).
1781 .IP "helper processes" 4
1782 .IX Item "helper processes"
1783 IPC::Run uses helper processes, one per redirected file, to adapt between the
1784 anonymous pipe connected to the child and the \s-1TCP\s0 socket connected to the
1785 parent.  This is a waste of resources and will change in the future to either
1786 use threads (instead of helper processes) or a WaitForMultipleObjects call
1787 (instead of select).  Please contact me if you can help with the
1788 \&\fIWaitForMultipleObjects()\fR approach; I haven't figured out how to get at it
1789 without C code.
1790 .IP "shutdown pause" 4
1791 .IX Item "shutdown pause"
1792 There seems to be a pause of up to 1 second between when a child program exits
1793 and the corresponding sockets indicate that they are closed in the parent.
1794 Not sure why.
1795 .IP "binmode" 4
1796 .IX Item "binmode"
1797 binmode is not supported yet.  The underpinnings are implemented, just ask
1798 if you need it.
1799 .IP "IPC::Run::IO" 4
1800 .IX Item "IPC::Run::IO"
1801 IPC::Run::IO objects can be used on Unix to read or write arbitrary files.  On
1802 Win32, they will need to use the same helper processes to adapt from
1803 non\-\fIselect()\fRable filehandles to \fIselect()\fRable ones (or perhaps
1804 \&\fIWaitForMultipleObjects()\fR will work with them, not sure).
1805 .IP "startup race conditions" 4
1806 .IX Item "startup race conditions"
1807 There seems to be an occasional race condition between child process startup
1808 and pipe closings.  It seems like if the child is not fully created by the time
1809 CreateProcess returns and we close the \s-1TCP\s0 socket being handed to it, the
1810 parent socket can also get closed.  This is seen with the Win32 pumper
1811 applications, not the \*(L"real\*(R" child process being spawned.
1812 .Sp
1813 I assume this is because the kernel hasn't gotten around to incrementing the
1814 reference count on the child's end (since the child was slow in starting), so
1815 the parent's closing of the child end causes the socket to be closed, thus
1816 closing the parent socket.
1817 .Sp
1818 Being a race condition, it's hard to reproduce, but I encountered it while
1819 testing this code on a drive share to a samba box.  In this case, it takes
1820 t/run.t a long time to spawn it's chile processes (the parent hangs in the
1821 first select for several seconds until the child emits any debugging output).
1822 .Sp
1823 I have not seen it on local drives, and can't reproduce it at will,
1824 unfortunately.  The symptom is a \*(L"bad file descriptor in \fIselect()\fR\*(R" error, and,
1825 by turning on debugging, it's possible to see that \fIselect()\fR is being called on
1826 a no longer open file descriptor that was returned from the \fI_socket()\fR routine
1827 in Win32Helper.  There's a new \fIconfess()\fR that checks for this (\*(L"\s-1PARENT_HANDLE\s0
1828 no longer open\*(R"), but I haven't been able to reproduce it (typically).
1829 .SH "LIMITATIONS"
1830 .IX Header "LIMITATIONS"
1831 On Unix, requires a system that supports \f(CW\*(C`waitpid( $pid, WNOHANG )\*(C'\fR so
1832 it can tell if a child process is still running.
1833 .PP
1834 PTYs don't seem to be non-blocking on some versions of Solaris. Here's a
1835 test script contributed by Borislav Deianov <borislav@ensim.com> to see
1836 if you have the problem.  If it dies, you have the problem.
1837 .PP
1838 .Vb 1
1839 \&   #!/usr/bin/perl
1840 \&
1841 \&   use IPC::Run qw(run);
1842 \&   use Fcntl;
1843 \&   use IO::Pty;
1844 \&
1845 \&   sub makecmd {
1846 \&       return [\*(Aqperl\*(Aq, \*(Aq\-e\*(Aq,
1847 \&               \*(Aq<STDIN>, print "\en" x \*(Aq.$_[0].\*(Aq; while(<STDIN>){last if /end/}\*(Aq];
1848 \&   }
1849 \&
1850 \&   #pipe R, W;
1851 \&   #fcntl(W, F_SETFL, O_NONBLOCK);
1852 \&   #while (syswrite(W, "\en", 1)) { $pipebuf++ };
1853 \&   #print "pipe buffer size is $pipebuf\en";
1854 \&   my $pipebuf=4096;
1855 \&   my $in = "\en" x ($pipebuf * 2) . "end\en";
1856 \&   my $out;
1857 \&
1858 \&   $SIG{ALRM} = sub { die "Never completed!\en" };
1859 \&
1860 \&   print "reading from scalar via pipe...";
1861 \&   alarm( 2 );
1862 \&   run(makecmd($pipebuf * 2), \*(Aq<\*(Aq, \e$in, \*(Aq>\*(Aq, \e$out);
1863 \&   alarm( 0 );
1864 \&   print "done\en";
1865 \&
1866 \&   print "reading from code via pipe... ";
1867 \&   alarm( 2 );
1868 \&   run(makecmd($pipebuf * 3), \*(Aq<\*(Aq, sub { $t = $in; undef $in; $t}, \*(Aq>\*(Aq, \e$out);
1869 \&   alarm( 0 );
1870 \&   print "done\en";
1871 \&
1872 \&   $pty = IO::Pty\->new();
1873 \&   $pty\->blocking(0);
1874 \&   $slave = $pty\->slave();
1875 \&   while ($pty\->syswrite("\en", 1)) { $ptybuf++ };
1876 \&   print "pty buffer size is $ptybuf\en";
1877 \&   $in = "\en" x ($ptybuf * 3) . "end\en";
1878 \&
1879 \&   print "reading via pty... ";
1880 \&   alarm( 2 );
1881 \&   run(makecmd($ptybuf * 3), \*(Aq<pty<\*(Aq, \e$in, \*(Aq>\*(Aq, \e$out);
1882 \&   alarm(0);
1883 \&   print "done\en";
1884 .Ve
1885 .PP
1886 No support for ';', '&&', '||', '{ ... }', etc: use perl's, since \fIrun()\fR
1887 returns \s-1TRUE\s0 when the command exits with a 0 result code.
1888 .PP
1889 Does not provide shell-like string interpolation.
1890 .PP
1891 No support for \f(CW\*(C`cd\*(C'\fR, \f(CW\*(C`setenv\*(C'\fR, or \f(CW\*(C`export\*(C'\fR: do these in an \fIinit()\fR sub
1892 .PP
1893 .Vb 8
1894 \&   run(
1895 \&      \ecmd,
1896 \&         ...
1897 \&         init => sub {
1898 \&            chdir $dir or die $!;
1899 \&            $ENV{FOO}=\*(AqBAR\*(Aq
1900 \&         }
1901 \&   );
1902 .Ve
1903 .PP
1904 Timeout calculation does not allow absolute times, or specification of
1905 days, months, etc.
1906 .PP
1907 \&\fB\s-1WARNING:\s0\fR Function coprocesses (\f(CW\*(C`run \e&foo, ...\*(C'\fR) suffer from two
1908 limitations.  The first is that it is difficult to close all filehandles the
1909 child inherits from the parent, since there is no way to scan all open
1910 FILEHANDLEs in Perl and it both painful and a bit dangerous to close all open
1911 file descriptors with \f(CW\*(C`POSIX::close()\*(C'\fR. Painful because we can't tell which
1912 fds are open at the \s-1POSIX\s0 level, either, so we'd have to scan all possible fds
1913 and close any that we don't want open (normally \f(CW\*(C`exec()\*(C'\fR closes any
1914 non-inheritable but we don't \f(CW\*(C`exec()\*(C'\fR for &sub processes.
1915 .PP
1916 The second problem is that Perl's \s-1DESTROY\s0 subs and other on-exit cleanup gets
1917 run in the child process.  If objects are instantiated in the parent before the
1918 child is forked, the the \s-1DESTROY\s0 will get run once in the parent and once in
1919 the child.  When coprocess subs exit, POSIX::exit is called to work around this,
1920 but it means that objects that are still referred to at that time are not
1921 cleaned up.  So setting package vars or closure vars to point to objects that
1922 rely on \s-1DESTROY\s0 to affect things outside the process (files, etc), will
1923 lead to bugs.
1924 .PP
1925 I goofed on the syntax: \*(L"<pipe\*(R" vs. \*(L"<pty<\*(R" and \*(L">filename\*(R" are both
1926 oddities.
1927 .SH "TODO"
1928 .IX Header "TODO"
1929 .ie n .IP "Allow one harness to ""adopt"" another:" 4
1930 .el .IP "Allow one harness to ``adopt'' another:" 4
1931 .IX Item "Allow one harness to adopt another:"
1932 .Vb 2
1933 \&   $new_h = harness \e@cmd2;
1934 \&   $h\->adopt( $new_h );
1935 .Ve
1936 .IP "Close all filehandles not explicitly marked to stay open." 4
1937 .IX Item "Close all filehandles not explicitly marked to stay open."
1938 The problem with this one is that there's no good way to scan all open
1939 FILEHANDLEs in Perl, yet you don't want child processes inheriting handles
1940 willy-nilly.
1941 .SH "INSPIRATION"
1942 .IX Header "INSPIRATION"
1943 Well, \fIselect()\fR and \fIwaitpid()\fR badly needed wrapping, and \fIopen3()\fR isn't
1944 open-minded enough for me.
1945 .PP
1946 The shell-like \s-1API\s0 inspired by a message Russ Allbery sent to perl5\-porters,
1947 which included:
1948 .PP
1949 .Vb 4
1950 \&   I\*(Aqve thought for some time that it would be
1951 \&   nice to have a module that could handle full Bourne shell pipe syntax
1952 \&   internally, with fork and exec, without ever invoking a shell.  Something
1953 \&   that you could give things like:
1954 \&
1955 \&   pipeopen (PIPE, [ qw/cat file/ ], \*(Aq|\*(Aq, [ \*(Aqanalyze\*(Aq, @args ], \*(Aq>&3\*(Aq);
1956 .Ve
1957 .PP
1958 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1959 .SH "SUPPORT"
1960 .IX Header "SUPPORT"
1961 Bugs should always be submitted via the \s-1CPAN\s0 bug tracker
1962 .PP
1963 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC\-Run>
1964 .PP
1965 For other issues, contact the maintainer (the first listed author)
1966 .SH "AUTHORS"
1967 .IX Header "AUTHORS"
1968 Adam Kennedy <adamk@cpan.org>
1969 .PP
1970 Barrie Slaymaker <barries@slaysys.com>
1971 .SH "COPYRIGHT"
1972 .IX Header "COPYRIGHT"
1973 Some parts copyright 2008 \- 2009 Adam Kennedy.
1974 .PP
1975 Copyright 1999 Barrie Slaymaker.
1976 .PP
1977 You may distribute under the terms of either the \s-1GNU\s0 General Public
1978 License or the Artistic License, as specified in the \s-1README\s0 file.