local-lib5/man/man3/IPC::Run3.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::Run3 3"
 127 .TH IPC::Run3 3 "2009-05-30" "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::Run3 \- run a subprocess with input/ouput redirection
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 version 0.043
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 .Vb 1
 140 \&    use IPC::Run3;    # Exports run3() by default
 141 \&
 142 \&    run3 \e@cmd, \e$in, \e$out, \e$err;
 143 .Ve
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 This module allows you to run a subprocess and redirect stdin, stdout,
 147 and/or stderr to files and perl data structures.  It aims to satisfy 99% of the
 148 need for using \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`qx\*(C'\fR, and \f(CW\*(C`open3\*(C'\fR
 149 with a simple, extremely Perlish \s-1API\s0.
 150 .PP
 151 Speed, simplicity, and portability are paramount.  (That's speed of Perl code;
 152 which is often much slower than the kind of buffered I/O that this module uses
 153 to spool input to and output from the child command.)
 154 .ie n .SS """run3($cmd, $stdin, $stdout, $stderr, \e%options)"""
 155 .el .SS "\f(CWrun3($cmd, $stdin, $stdout, $stderr, \e%options)\fP"
 156 .IX Subsection "run3($cmd, $stdin, $stdout, $stderr, %options)"
 157 All parameters after \f(CW$cmd\fR are optional.
 158 .PP
 159 The parameters \f(CW$stdin\fR, \f(CW$stdout\fR and \f(CW$stderr\fR indicate
 160 how the child's corresponding filehandle
 161 (\f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR, resp.) will be redirected.
 162 Because the redirects come last, this allows \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR to default
 163 to the parent's by just not specifying them \*(-- a common use case.
 164 .PP
 165 \&\f(CW\*(C`run3\*(C'\fR throws an exception if the wrapped \f(CW\*(C`system\*(C'\fR call returned \-1
 166 or anything went wrong with \f(CW\*(C`run3\*(C'\fR's processing of filehandles.
 167 Otherwise it returns true.
 168 It leaves \f(CW$?\fR intact for inspection of exit and wait status.
 169 .PP
 170 Note that a true return value from \f(CW\*(C`run3\*(C'\fR doesn't mean that the command
 171 had a successful exit code. Hence you should always check \f(CW$?\fR.
 172 .PP
 173 See \*(L"%options\*(R" for an option to handle the case of \f(CW\*(C`system\*(C'\fR
 174 returning \-1 yourself.
 175 .PP
 176 \fI\f(CI$cmd\fI\fR
 177 .IX Subsection "$cmd"
 178 .PP
 179 Usually \f(CW$cmd\fR will be an \s-1ARRAY\s0 reference and the child is invoked via
 180 .PP
 181 .Vb 1
 182 \&  system @$cmd;
 183 .Ve
 184 .PP
 185 But \f(CW$cmd\fR may also be a string in which case the child is invoked via
 186 .PP
 187 .Vb 1
 188 \&  system $cmd;
 189 .Ve
 190 .PP
 191 (cf. \*(L"system\*(R" in perlfunc for the difference and the pitfalls of using
 192 the latter form).
 193 .PP
 194 \fI\f(CI$stdin\fI, \f(CI$stdout\fI, \f(CI$stderr\fI\fR
 195 .IX Subsection "$stdin, $stdout, $stderr"
 196 .PP
 197 The parameters \f(CW$stdin\fR, \f(CW$stdout\fR and \f(CW$stderr\fR
 198 can take one of the following forms:
 199 .ie n .IP """undef"" (or not specified at all)" 4
 200 .el .IP "\f(CWundef\fR (or not specified at all)" 4
 201 .IX Item "undef (or not specified at all)"
 202 The child inherits the corresponding filehandle from the parent.
 203 .Sp
 204 .Vb 2
 205 \&  run3 \e@cmd, $stdin;                   # child writes to same STDOUT and STDERR as parent
 206 \&  run3 \e@cmd, undef, $stdout, $stderr;  # child reads from same STDIN as parent
 207 .Ve
 208 .ie n .IP """\eundef""" 4
 209 .el .IP "\f(CW\eundef\fR" 4
 210 .IX Item "undef"
 211 The child's filehandle is redirected from or to the
 212 local equivalent of \f(CW\*(C`/dev/null\*(C'\fR (as returned by
 213 \&\f(CW\*(C`File::Spec\->devnull()\*(C'\fR).
 214 .Sp
 215 .Vb 1
 216 \&  run3 \e@cmd, \eundef, $stdout, $stderr; # child reads from /dev/null
 217 .Ve
 218 .IP "a simple scalar" 4
 219 .IX Item "a simple scalar"
 220 The parameter is taken to be the name of a file to read from
 221 or write to. In the latter case, the file will be opened via
 222 .Sp
 223 .Vb 1
 224 \&  open FH, ">", ...
 225 .Ve
 226 .Sp
 227 i.e. it is created if it doesn't exist and truncated otherwise.
 228 Note that the file is opened by the parent which will croak
 229 in case of failure.
 230 .Sp
 231 .Vb 1
 232 \&  run3 \e@cmd, \eundef, "out.txt";        # child writes to file "out.txt"
 233 .Ve
 234 .ie n .IP "a filehandle (either a reference to a \s-1GLOB\s0 or an ""IO::Handle"")" 4
 235 .el .IP "a filehandle (either a reference to a \s-1GLOB\s0 or an \f(CWIO::Handle\fR)" 4
 236 .IX Item "a filehandle (either a reference to a GLOB or an IO::Handle)"
 237 The filehandle is inherited by the child.
 238 .Sp
 239 .Vb 7
 240 \&  open my $fh, ">", "out.txt";
 241 \&  print $fh "prologue\en";
 242 \&  ...
 243 \&  run3 \e@cmd, \eundef, $fh;              # child writes to $fh
 244 \&  ...
 245 \&  print $fh "epilogue\en";
 246 \&  close $fh;
 247 .Ve
 248 .IP "a \s-1SCALAR\s0 reference" 4
 249 .IX Item "a SCALAR reference"
 250 The referenced scalar is treated as a string to be read from or
 251 written to. In the latter case, the previous content of the string
 252 is overwritten.
 253 .Sp
 254 .Vb 7
 255 \&  my $out;
 256 \&  run3 \e@cmd, \eundef, \e$out;           # child writes into string
 257 \&  run3 \e@cmd, \e<<EOF;                  # child reads from string (can use "here" notation)
 258 \&  Input
 259 \&  to
 260 \&  child
 261 \&  EOF
 262 .Ve
 263 .IP "an \s-1ARRAY\s0 reference" 4
 264 .IX Item "an ARRAY reference"
 265 For \f(CW$stdin\fR, the elements of \f(CW@$stdin\fR are simply spooled to the child.
 266 .Sp
 267 For \f(CW$stdout\fR or \f(CW$stderr\fR, the child's corresponding file descriptor
 268 is read line by line (as determined by the current setting of \f(CW$/\fR)
 269 into \f(CW@$stdout\fR or \f(CW@$stderr\fR, resp. The previous content of the array
 270 is overwritten.
 271 .Sp
 272 .Vb 2
 273 \&  my @lines;
 274 \&  run3 \e@cmd, \eundef, \e@lines;         # child writes into array
 275 .Ve
 276 .IP "a \s-1CODE\s0 reference" 4
 277 .IX Item "a CODE reference"
 278 For \f(CW$stdin\fR, \f(CW&$stdin\fR will be called repeatedly (with no arguments) and
 279 the return values are spooled to the child. \f(CW&$stdin\fR must signal the end of
 280 input by returning \f(CW\*(C`undef\*(C'\fR.
 281 .Sp
 282 For \f(CW$stdout\fR or \f(CW$stderr\fR, the child's corresponding file descriptor
 283 is read line by line (as determined by the current setting of \f(CW$/\fR)
 284 and \f(CW&$stdout\fR or \f(CW&$stderr\fR, resp., is called with the contents of the line.
 285 Note that there's no end-of-file indication.
 286 .Sp
 287 .Vb 4
 288 \&  my $i = 0;
 289 \&  sub producer {
 290 \&    return $i < 10 ? "line".$i++."\en" : undef;
 291 \&  }
 292 \&
 293 \&  run3 \e@cmd, \e&producer;              # child reads 10 lines
 294 .Ve
 295 .Sp
 296 Note that this form of redirecting the child's I/O doesn't imply
 297 any form of concurrency between parent and child \- \fIrun3()\fR's method of
 298 operation is the same no matter which form of redirection you specify.
 299 .PP
 300 If the same value is passed for \f(CW$stdout\fR and \f(CW$stderr\fR, then the child
 301 will write both \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR to the same filehandle.
 302 In general, this means that
 303 .PP
 304 .Vb 2
 305 \&    run3 \e@cmd, \eundef, "foo.txt", "foo.txt";
 306 \&    run3 \e@cmd, \eundef, \e$both, \e$both;
 307 .Ve
 308 .PP
 309 will \s-1DWIM\s0 and pass a single file handle to the child for both \f(CW\*(C`STDOUT\*(C'\fR and
 310 \&\f(CW\*(C`STDERR\*(C'\fR, collecting all into file \*(L"foo.txt\*(R" or \f(CW$both\fR.
 311 .PP
 312 \fI\f(CI\*(C`\e%options\*(C'\fI\fR
 313 .IX Subsection "%options"
 314 .PP
 315 The last parameter, \f(CW\*(C`\e%options\*(C'\fR, must be a hash reference if present.
 316 .PP
 317 Currently the following
 318 keys are supported:
 319 .ie n .IP """binmode_stdin"", ""binmode_stdout"", ""binmode_stderr""" 4
 320 .el .IP "\f(CWbinmode_stdin\fR, \f(CWbinmode_stdout\fR, \f(CWbinmode_stderr\fR" 4
 321 .IX Item "binmode_stdin, binmode_stdout, binmode_stderr"
 322 The value must a \*(L"layer\*(R" as described in \*(L"binmode\*(R" in perlfunc.
 323 If specified the corresponding
 324 parameter \f(CW$stdin\fR, \f(CW$stdout\fR or \f(CW$stderr\fR, resp., operates
 325 with the given layer.
 326 .Sp
 327 For backward compatibility, a true value that doesn't start with \*(L":\*(R"
 328 (e.g. a number) is interpreted as \*(L":raw\*(R". If the value is false
 329 or not specified, the default is \*(L":crlf\*(R" on Windows and \*(L":raw\*(R" otherwise.
 330 .Sp
 331 Don't expect that values other than the built-in layers \*(L":raw\*(R", \*(L":crlf\*(R",
 332 and (on newer Perls) \*(L":bytes\*(R", \*(L":utf8\*(R", \*(L":encoding(...)\*(R" will work.
 333 .ie n .IP """append_stdout"", ""append_stderr""" 4
 334 .el .IP "\f(CWappend_stdout\fR, \f(CWappend_stderr\fR" 4
 335 .IX Item "append_stdout, append_stderr"
 336 If their value is true then the corresponding
 337 parameter \f(CW$stdout\fR or \f(CW$stderr\fR, resp., will append the child's output
 338 to the existing \*(L"contents\*(R" of the redirector. This only makes
 339 sense if the redirector is a simple scalar (the corresponding file
 340 is opened in append mode), a \s-1SCALAR\s0 reference (the output is
 341 appended to the previous contents of the string)
 342 or an \s-1ARRAY\s0 reference (the output is \f(CW\*(C`push\*(C'\fRed onto the
 343 previous contents of the array).
 344 .ie n .IP """return_if_system_error""" 4
 345 .el .IP "\f(CWreturn_if_system_error\fR" 4
 346 .IX Item "return_if_system_error"
 347 If this is true \f(CW\*(C`run3\*(C'\fR does \fBnot\fR throw an exception if \f(CW\*(C`system\*(C'\fR
 348 returns \-1 (cf. \*(L"system\*(R" in perlfunc for possible
 349 failure scenarios.), but returns true instead.
 350 In this case \f(CW$?\fR has the value \-1 and \f(CW$!\fR
 351 contains the errno of the failing \f(CW\*(C`system\*(C'\fR call.
 352 .SH "HOW IT WORKS"
 353 .IX Header "HOW IT WORKS"
 354 .IP "(1)" 4
 355 .IX Item "(1)"
 356 For each redirector \f(CW$stdin\fR, \f(CW$stdout\fR, and \f(CW$stderr\fR,
 357 \&\f(CW\*(C`run3()\*(C'\fR furnishes a filehandle:
 358 .RS 4
 359 .IP "\(bu" 4
 360 if the redirector already specifies a filehandle it just uses that
 361 .IP "\(bu" 4
 362 if the redirector specifies a filename, \f(CW\*(C`run3()\*(C'\fR opens the file
 363 in the appropriate mode
 364 .IP "\(bu" 4
 365 in all other cases, \f(CW\*(C`run3()\*(C'\fR opens a temporary file
 366 (using tempfile)
 367 .RE
 368 .RS 4
 369 .RE
 370 .IP "(2)" 4
 371 .IX Item "(2)"
 372 If \f(CW\*(C`run3()\*(C'\fR opened a temporary file for \f(CW$stdin\fR in step (1),
 373 it writes the data using the specified method (either
 374 from a string, an array or returnd by a function) to the temporary file and rewinds it.
 375 .IP "(3)" 4
 376 .IX Item "(3)"
 377 \&\f(CW\*(C`run3()\*(C'\fR saves the parent's \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR by duplicating
 378 them to new filehandles. It duplicates the filehandles from step (1)
 379 to \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR, resp.
 380 .IP "(4)" 4
 381 .IX Item "(4)"
 382 \&\f(CW\*(C`run3()\*(C'\fR runs the child by invoking system
 383 with \f(CW$cmd\fR as specified above.
 384 .IP "(5)" 4
 385 .IX Item "(5)"
 386 \&\f(CW\*(C`run3()\*(C'\fR restores the parent's \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR saved in step (3).
 387 .IP "(6)" 4
 388 .IX Item "(6)"
 389 If \f(CW\*(C`run3()\*(C'\fR opened a temporary file for \f(CW$stdout\fR or \f(CW$stderr\fR in step (1),
 390 it rewinds it and reads back its contents using the specified method
 391 (either to a string, an array or by calling a function).
 392 .IP "(7)" 4
 393 .IX Item "(7)"
 394 \&\f(CW\*(C`run3()\*(C'\fR closes all filehandles that it opened explicitly in step (1).
 395 .PP
 396 Note that when using temporary files, \f(CW\*(C`run3()\*(C'\fR tries to amortize the overhead
 397 by reusing them (i.e. it keeps them open and rewinds and truncates them
 398 before the next operation).
 399 .SH "LIMITATIONS"
 400 .IX Header "LIMITATIONS"
 401 Often uses intermediate files (determined by File::Temp, and thus by the
 402 File::Spec defaults and the \s-1TMPDIR\s0 env. variable) for speed, portability and
 403 simplicity.
 404 .PP
 405 Use extrem caution when using \f(CW\*(C`run3\*(C'\fR in a threaded environment if
 406 concurrent calls of \f(CW\*(C`run3\*(C'\fR are possible. Most likely, I/O from different
 407 invocations will get mixed up. The reason is that in most thread
 408 implementations all threads in a process share the same \s-1STDIN/STDOUT/STDERR\s0.
 409 Known failures are Perl ithreads on Linux and Win32. Note that \f(CW\*(C`fork\*(C'\fR
 410 on Win32 is emulated via Win32 threads and hence I/O mix up is possible
 411 between forked children here (\f(CW\*(C`run3\*(C'\fR is \*(L"fork safe\*(R" on Unix, though).
 412 .SH "DEBUGGING"
 413 .IX Header "DEBUGGING"
 414 To enable debugging use the \s-1IPCRUN3DEBUG\s0 environment variable to
 415 a non-zero integer value:
 416 .PP
 417 .Vb 1
 418 \&  $ IPCRUN3DEBUG=1 myapp
 419 .Ve
 420 .SH "PROFILING"
 421 .IX Header "PROFILING"
 422 To enable profiling, set \s-1IPCRUN3PROFILE\s0 to a number to enable emitting profile
 423 information to \s-1STDERR\s0 (1 to get timestamps, 2 to get a summary report at the
 424 \&\s-1END\s0 of the program, 3 to get mini reports after each run) or to a filename to
 425 emit raw data to a file for later analysis.
 426 .SH "COMPARISON"
 427 .IX Header "COMPARISON"
 428 Here's how it stacks up to existing APIs:
 429 .ie n .SS "compared to ""system()"", ""qx\*(Aq\*(Aq"", ""open ""...|"""", ""open ""|..."""""
 430 .el .SS "compared to \f(CWsystem()\fP, \f(CWqx\*(Aq\*(Aq\fP, \f(CWopen ``...|''\fP, \f(CWopen ``|...''\fP"
 431 .IX Subsection "compared to system(), qx, open ""...|"", open ""|..."""
 432 .IP "+" 4
 433 redirects more than one file descriptor
 434 .IP "+" 4
 435 returns \s-1TRUE\s0 on success, \s-1FALSE\s0 on failure
 436 .IP "+" 4
 437 throws an error if problems occur in the parent process (or the pre-exec child)
 438 .IP "+" 4
 439 allows a very perlish interface to Perl data structures and subroutines
 440 .IP "+" 4
 441 allows 1 word invocations to avoid the shell easily:
 442 .Sp
 443 .Vb 1
 444 \& run3 ["foo"];  # does not invoke shell
 445 .Ve
 446 .IP "\-" 4
 447 does not return the exit code, leaves it in $?
 448 .ie n .SS "compared to ""open2()"", ""open3()"""
 449 .el .SS "compared to \f(CWopen2()\fP, \f(CWopen3()\fP"
 450 .IX Subsection "compared to open2(), open3()"
 451 .IP "+" 4
 452 no lengthy, error prone polling/select loop needed
 453 .IP "+" 4
 454 hides \s-1OS\s0 dependancies
 455 .IP "+" 4
 456 allows \s-1SCALAR\s0, \s-1ARRAY\s0, and \s-1CODE\s0 references to source and sink I/O
 457 .IP "+" 4
 458 I/O parameter order is like \f(CW\*(C`open3()\*(C'\fR  (not like \f(CW\*(C`open2()\*(C'\fR).
 459 .IP "\-" 4
 460 does not allow interaction with the subprocess
 461 .SS "compared to \fIIPC::Run::run()\fP"
 462 .IX Subsection "compared to IPC::Run::run()"
 463 .IP "+" 4
 464 smaller, lower overhead, simpler, more portable
 465 .IP "+" 4
 466 no \fIselect()\fR loop portability issues
 467 .IP "+" 4
 468 does not fall prey to Perl closure leaks
 469 .IP "\-" 4
 470 does not allow interaction with the subprocess (which
 471 \&\fIIPC::Run::run()\fR allows by redirecting subroutines)
 472 .IP "\-" 4
 473 lacks many features of \f(CW\*(C`IPC::Run::run()\*(C'\fR (filters, pipes,
 474 redirects, pty support)
 475 .SH "COPYRIGHT"
 476 .IX Header "COPYRIGHT"
 477 Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
 478 .SH "LICENSE"
 479 .IX Header "LICENSE"
 480 You may use this module under the terms of the \s-1BSD\s0, Artistic, or \s-1GPL\s0 licenses,
 481 any version.
 482 .SH "AUTHOR"
 483 .IX Header "AUTHOR"
 484 Barrie Slaymaker <\f(CW\*(C`barries@slaysys.com\*(C'\fR>
 485 .PP
 486 Ricardo \s-1SIGNES\s0 <\f(CW\*(C`rjbs@cpan.org\*(C'\fR> performed some routine maintenance in
 487 2005, thanks to help from the following ticket and/or patch submitters: Jody
 488 Belka, Roderich Schupp, David Morel, and anonymous others.