local-lib5/man/man3/IPC::Cmd.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::Cmd 3"
 127 .TH IPC::Cmd 3 "2009-11-15" "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::Cmd \- finding and running system commands made easy
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use IPC::Cmd qw[can_run run run_forked];
 138 \&
 139 \&    my $full_path = can_run(\*(Aqwget\*(Aq) or warn \*(Aqwget is not installed!\*(Aq;
 140 \&
 141 \&    ### commands can be arrayrefs or strings ###
 142 \&    my $cmd = "$full_path \-b theregister.co.uk";
 143 \&    my $cmd = [$full_path, \*(Aq\-b\*(Aq, \*(Aqtheregister.co.uk\*(Aq];
 144 \&
 145 \&    ### in scalar context ###
 146 \&    my $buffer;
 147 \&    if( scalar run( command => $cmd,
 148 \&                    verbose => 0,
 149 \&                    buffer  => \e$buffer,
 150 \&                    timeout => 20 )
 151 \&    ) {
 152 \&        print "fetched webpage successfully: $buffer\en";
 153 \&    }
 154 \&
 155 \&
 156 \&    ### in list context ###
 157 \&    my( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
 158 \&            run( command => $cmd, verbose => 0 );
 159 \&
 160 \&    if( $success ) {
 161 \&        print "this is what the command printed:\en";
 162 \&        print join "", @$full_buf;
 163 \&    }
 164 \&
 165 \&    ### check for features
 166 \&    print "IPC::Open3 available: "  . IPC::Cmd\->can_use_ipc_open3;
 167 \&    print "IPC::Run available: "    . IPC::Cmd\->can_use_ipc_run;
 168 \&    print "Can capture buffer: "    . IPC::Cmd\->can_capture_buffer;
 169 \&
 170 \&    ### don\*(Aqt have IPC::Cmd be verbose, ie don\*(Aqt print to stdout or
 171 \&    ### stderr when running commands \-\- default is \*(Aq0\*(Aq
 172 \&    $IPC::Cmd::VERBOSE = 0;
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 IPC::Cmd allows you to run commands, interactively if desired,
 177 platform independent but have them still work.
 178 .PP
 179 The \f(CW\*(C`can_run\*(C'\fR function can tell you if a certain binary is installed
 180 and if so where, whereas the \f(CW\*(C`run\*(C'\fR function can actually execute any
 181 of the commands you give it and give you a clear return value, as well
 182 as adhere to your verbosity settings.
 183 .SH "CLASS METHODS"
 184 .IX Header "CLASS METHODS"
 185 .ie n .SS "$ipc_run_version = IPC::Cmd\->can_use_ipc_run( [\s-1VERBOSE\s0] )"
 186 .el .SS "\f(CW$ipc_run_version\fP = IPC::Cmd\->can_use_ipc_run( [\s-1VERBOSE\s0] )"
 187 .IX Subsection "$ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] )"
 188 Utility function that tells you if \f(CW\*(C`IPC::Run\*(C'\fR is available.
 189 If the verbose flag is passed, it will print diagnostic messages
 190 if \f(CW\*(C`IPC::Run\*(C'\fR can not be found or loaded.
 191 .ie n .SS "$ipc_open3_version = IPC::Cmd\->can_use_ipc_open3( [\s-1VERBOSE\s0] )"
 192 .el .SS "\f(CW$ipc_open3_version\fP = IPC::Cmd\->can_use_ipc_open3( [\s-1VERBOSE\s0] )"
 193 .IX Subsection "$ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )"
 194 Utility function that tells you if \f(CW\*(C`IPC::Open3\*(C'\fR is available.
 195 If the verbose flag is passed, it will print diagnostic messages
 196 if \f(CW\*(C`IPC::Open3\*(C'\fR can not be found or loaded.
 197 .ie n .SS "$bool = IPC::Cmd\->can_capture_buffer"
 198 .el .SS "\f(CW$bool\fP = IPC::Cmd\->can_capture_buffer"
 199 .IX Subsection "$bool = IPC::Cmd->can_capture_buffer"
 200 Utility function that tells you if \f(CW\*(C`IPC::Cmd\*(C'\fR is capable of
 201 capturing buffers in it's current configuration.
 202 .ie n .SS "$bool = IPC::Cmd\->can_use_run_forked"
 203 .el .SS "\f(CW$bool\fP = IPC::Cmd\->can_use_run_forked"
 204 .IX Subsection "$bool = IPC::Cmd->can_use_run_forked"
 205 Utility function that tells you if \f(CW\*(C`IPC::Cmd\*(C'\fR is capable of
 206 providing \f(CW\*(C`run_forked\*(C'\fR on the current platform.
 207 .SH "FUNCTIONS"
 208 .IX Header "FUNCTIONS"
 209 .ie n .SS "$path = can_run( \s-1PROGRAM\s0 );"
 210 .el .SS "\f(CW$path\fP = can_run( \s-1PROGRAM\s0 );"
 211 .IX Subsection "$path = can_run( PROGRAM );"
 212 \&\f(CW\*(C`can_run\*(C'\fR takes but a single argument: the name of a binary you wish
 213 to locate. \f(CW\*(C`can_run\*(C'\fR works much like the unix binary \f(CW\*(C`which\*(C'\fR or the bash
 214 command \f(CW\*(C`type\*(C'\fR, which scans through your path, looking for the requested
 215 binary .
 216 .PP
 217 Unlike \f(CW\*(C`which\*(C'\fR and \f(CW\*(C`type\*(C'\fR, this function is platform independent and
 218 will also work on, for example, Win32.
 219 .PP
 220 It will return the full path to the binary you asked for if it was
 221 found, or \f(CW\*(C`undef\*(C'\fR if it was not.
 222 .ie n .SS "$ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => \s-1COMMAND\s0, [verbose => \s-1BOOL\s0, buffer => \e$SCALAR, timeout => \s-1DIGIT\s0] );"
 223 .el .SS "\f(CW$ok\fP | ($ok, \f(CW$err\fP, \f(CW$full_buf\fP, \f(CW$stdout_buff\fP, \f(CW$stderr_buff\fP) = run( command => \s-1COMMAND\s0, [verbose => \s-1BOOL\s0, buffer => \e$SCALAR, timeout => \s-1DIGIT\s0] );"
 224 .IX Subsection "$ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => $SCALAR, timeout => DIGIT] );"
 225 \&\f(CW\*(C`run\*(C'\fR takes 4 arguments:
 226 .IP "command" 4
 227 .IX Item "command"
 228 This is the command to execute. It may be either a string or an array
 229 reference.
 230 This is a required argument.
 231 .Sp
 232 See \s-1CAVEATS\s0 for remarks on how commands are parsed and their
 233 limitations.
 234 .IP "verbose" 4
 235 .IX Item "verbose"
 236 This controls whether all output of a command should also be printed
 237 to \s-1STDOUT/STDERR\s0 or should only be trapped in buffers (\s-1NOTE:\s0 buffers
 238 require \f(CW\*(C`IPC::Run\*(C'\fR to be installed or your system able to work with
 239 \&\f(CW\*(C`IPC::Open3\*(C'\fR).
 240 .Sp
 241 It will default to the global setting of \f(CW$IPC::Cmd::VERBOSE\fR,
 242 which by default is 0.
 243 .IP "buffer" 4
 244 .IX Item "buffer"
 245 This will hold all the output of a command. It needs to be a reference
 246 to a scalar.
 247 Note that this will hold both the \s-1STDOUT\s0 and \s-1STDERR\s0 messages, and you
 248 have no way of telling which is which.
 249 If you require this distinction, run the \f(CW\*(C`run\*(C'\fR command in list context
 250 and inspect the individual buffers.
 251 .Sp
 252 Of course, this requires that the underlying call supports buffers. See
 253 the note on buffers right above.
 254 .IP "timeout" 4
 255 .IX Item "timeout"
 256 Sets the maximum time the command is allowed to run before aborting,
 257 using the built-in \f(CW\*(C`alarm()\*(C'\fR call. If the timeout is triggered, the
 258 \&\f(CW\*(C`errorcode\*(C'\fR in the return value will be set to an object of the
 259 \&\f(CW\*(C`IPC::Cmd::TimeOut\*(C'\fR class. See the \f(CW\*(C`errorcode\*(C'\fR section below for
 260 details.
 261 .Sp
 262 Defaults to \f(CW0\fR, meaning no timeout is set.
 263 .PP
 264 \&\f(CW\*(C`run\*(C'\fR will return a simple \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR when called in scalar
 265 context.
 266 In list context, you will be returned a list of the following items:
 267 .IP "success" 4
 268 .IX Item "success"
 269 A simple boolean indicating if the command executed without errors or
 270 not.
 271 .IP "error message" 4
 272 .IX Item "error message"
 273 If the first element of the return value (success) was 0, then some
 274 error occurred. This second element is the error message the command
 275 you requested exited with, if available. This is generally a pretty
 276 printed value of \f(CW$?\fR or \f(CW$@\fR. See \f(CW\*(C`perldoc perlvar\*(C'\fR for details on
 277 what they can contain.
 278 If the error was a timeout, the \f(CW\*(C`error message\*(C'\fR will be prefixed with
 279 the string \f(CW\*(C`IPC::Cmd::TimeOut\*(C'\fR, the timeout class.
 280 .IP "full_buffer" 4
 281 .IX Item "full_buffer"
 282 This is an arrayreference containing all the output the command
 283 generated.
 284 Note that buffers are only available if you have \f(CW\*(C`IPC::Run\*(C'\fR installed,
 285 or if your system is able to work with \f(CW\*(C`IPC::Open3\*(C'\fR \*(-- See below).
 286 This element will be \f(CW\*(C`undef\*(C'\fR if this is not the case.
 287 .IP "out_buffer" 4
 288 .IX Item "out_buffer"
 289 This is an arrayreference containing all the output sent to \s-1STDOUT\s0 the
 290 command generated.
 291 Note that buffers are only available if you have \f(CW\*(C`IPC::Run\*(C'\fR installed,
 292 or if your system is able to work with \f(CW\*(C`IPC::Open3\*(C'\fR \*(-- See below).
 293 This element will be \f(CW\*(C`undef\*(C'\fR if this is not the case.
 294 .IP "error_buffer" 4
 295 .IX Item "error_buffer"
 296 This is an arrayreference containing all the output sent to \s-1STDERR\s0 the
 297 command generated.
 298 Note that buffers are only available if you have \f(CW\*(C`IPC::Run\*(C'\fR installed,
 299 or if your system is able to work with \f(CW\*(C`IPC::Open3\*(C'\fR \*(-- See below).
 300 This element will be \f(CW\*(C`undef\*(C'\fR if this is not the case.
 301 .PP
 302 See the \f(CW\*(C`HOW IT WORKS\*(C'\fR Section below to see how \f(CW\*(C`IPC::Cmd\*(C'\fR decides
 303 what modules or function calls to use when issuing a command.
 304 .ie n .SS "$hashref = run_forked( command => \s-1COMMAND\s0, { child_stdin => \s-1SCALAR\s0, timeout => \s-1DIGIT\s0, stdout_handler => \s-1CODEREF\s0, stderr_handler => \s-1CODEREF\s0} );"
 305 .el .SS "\f(CW$hashref\fP = run_forked( command => \s-1COMMAND\s0, { child_stdin => \s-1SCALAR\s0, timeout => \s-1DIGIT\s0, stdout_handler => \s-1CODEREF\s0, stderr_handler => \s-1CODEREF\s0} );"
 306 .IX Subsection "$hashref = run_forked( command => COMMAND, { child_stdin => SCALAR, timeout => DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} );"
 307 \&\f(CW\*(C`run_forked\*(C'\fR is used to execute some program,
 308 optionally feed it with some input, get its return code
 309 and output (both stdout and stderr into seperate buffers).
 310 In addition it allows to terminate the program
 311 which take too long to finish.
 312 .PP
 313 The important and distinguishing feature of run_forked
 314 is execution timeout which at first seems to be
 315 quite a simple task but if you think
 316 that the program which you're spawning
 317 might spawn some children itself (which
 318 in their turn could do the same and so on)
 319 it turns out to be not a simple issue.
 320 .PP
 321 \&\f(CW\*(C`run_forked\*(C'\fR is designed to survive and
 322 successfully terminate almost any long running task,
 323 even a fork bomb in case your system has the resources
 324 to survive during given timeout.
 325 .PP
 326 This is achieved by creating separate watchdog process
 327 which spawns the specified program in a separate
 328 process session and supervises it: optionally
 329 feeds it with input, stores its exit code,
 330 stdout and stderr, terminates it in case
 331 it runs longer than specified.
 332 .PP
 333 Invocation requires the command to be executed and optionally a hashref of options:
 334 .ie n .IP """timeout""" 4
 335 .el .IP "\f(CWtimeout\fR" 4
 336 .IX Item "timeout"
 337 Specify in seconds how long the command may run for before it is killed with with \s-1SIG_KILL\s0 (9)
 338 which effectively terminates it and all of its children (direct or indirect).
 339 .ie n .IP """child_stdin""" 4
 340 .el .IP "\f(CWchild_stdin\fR" 4
 341 .IX Item "child_stdin"
 342 Specify some text that will be passed into \f(CW\*(C`STDIN\*(C'\fR of the executed program.
 343 .ie n .IP """stdout_handler""" 4
 344 .el .IP "\f(CWstdout_handler\fR" 4
 345 .IX Item "stdout_handler"
 346 You may provide a coderef of a subroutine that will be called a portion of data is received on
 347 stdout from the executing program.
 348 .ie n .IP """stderr_handler""" 4
 349 .el .IP "\f(CWstderr_handler\fR" 4
 350 .IX Item "stderr_handler"
 351 You may provide a coderef of a subroutine that will be called a portion of data is received on
 352 stderr from the executing program.
 353 .PP
 354 \&\f(CW\*(C`run_forked\*(C'\fR will return a \s-1HASHREF\s0 with the following keys:
 355 .ie n .IP """exit_code""" 4
 356 .el .IP "\f(CWexit_code\fR" 4
 357 .IX Item "exit_code"
 358 The exit code of the executed program.
 359 .ie n .IP """timeout""" 4
 360 .el .IP "\f(CWtimeout\fR" 4
 361 .IX Item "timeout"
 362 The number of seconds the program ran for before being terminated, or 0 if no timeout occurred.
 363 .ie n .IP """stdout""" 4
 364 .el .IP "\f(CWstdout\fR" 4
 365 .IX Item "stdout"
 366 Holds the standard output of the executed command
 367 (or empty string if there were no stdout output; it's always defined!)
 368 .ie n .IP """stderr""" 4
 369 .el .IP "\f(CWstderr\fR" 4
 370 .IX Item "stderr"
 371 Holds the standard error of the executed command
 372 (or empty string if there were no stderr output; it's always defined!)
 373 .ie n .IP """merged""" 4
 374 .el .IP "\f(CWmerged\fR" 4
 375 .IX Item "merged"
 376 Holds the standard output and error of the executed command merged into one stream
 377 (or empty string if there were no output at all; it's always defined!)
 378 .ie n .IP """err_msg""" 4
 379 .el .IP "\f(CWerr_msg\fR" 4
 380 .IX Item "err_msg"
 381 Holds some explanation in the case of an error.
 382 .ie n .SS "$q = \s-1QUOTE\s0"
 383 .el .SS "\f(CW$q\fP = \s-1QUOTE\s0"
 384 .IX Subsection "$q = QUOTE"
 385 Returns the character used for quoting strings on this platform. This is
 386 usually a \f(CW\*(C`\*(Aq\*(C'\fR (single quote) on most systems, but some systems use different
 387 quotes. For example, \f(CW\*(C`Win32\*(C'\fR uses \f(CW\*(C`"\*(C'\fR (double quote).
 388 .PP
 389 You can use it as follows:
 390 .PP
 391 .Vb 2
 392 \&  use IPC::Cmd qw[run QUOTE];
 393 \&  my $cmd = q[echo ] . QUOTE . q[foo bar] . QUOTE;
 394 .Ve
 395 .PP
 396 This makes sure that \f(CW\*(C`foo bar\*(C'\fR is treated as a string, rather than two
 397 seperate arguments to the \f(CW\*(C`echo\*(C'\fR function.
 398 .PP
 399 _\|_END_\|_
 400 .SH "HOW IT WORKS"
 401 .IX Header "HOW IT WORKS"
 402 \&\f(CW\*(C`run\*(C'\fR will try to execute your command using the following logic:
 403 .IP "\(bu" 4
 404 If you have \f(CW\*(C`IPC::Run\*(C'\fR installed, and the variable \f(CW$IPC::Cmd::USE_IPC_RUN\fR
 405 is set to true (See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR Section) use that to execute
 406 the command. You will have the full output available in buffers, interactive commands are sure to work  and you are guaranteed to have your verbosity
 407 settings honored cleanly.
 408 .IP "\(bu" 4
 409 Otherwise, if the variable \f(CW$IPC::Cmd::USE_IPC_OPEN3\fR is set to true
 410 (See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR Section), try to execute the command using
 411 \&\f(CW\*(C`IPC::Open3\*(C'\fR. Buffers will be available on all platforms except \f(CW\*(C`Win32\*(C'\fR,
 412 interactive commands will still execute cleanly, and also your verbosity
 413 settings will be adhered to nicely;
 414 .IP "\(bu" 4
 415 Otherwise, if you have the verbose argument set to true, we fall back
 416 to a simple \fIsystem()\fR call. We cannot capture any buffers, but
 417 interactive commands will still work.
 418 .IP "\(bu" 4
 419 Otherwise we will try and temporarily redirect \s-1STDERR\s0 and \s-1STDOUT\s0, do a
 420 \&\fIsystem()\fR call with your command and then re-open \s-1STDERR\s0 and \s-1STDOUT\s0.
 421 This is the method of last resort and will still allow you to execute
 422 your commands cleanly. However, no buffers will be available.
 423 .SH "Global Variables"
 424 .IX Header "Global Variables"
 425 The behaviour of IPC::Cmd can be altered by changing the following
 426 global variables:
 427 .ie n .SS "$IPC::Cmd::VERBOSE"
 428 .el .SS "\f(CW$IPC::Cmd::VERBOSE\fP"
 429 .IX Subsection "$IPC::Cmd::VERBOSE"
 430 This controls whether IPC::Cmd will print any output from the
 431 commands to the screen or not. The default is 0;
 432 .ie n .SS "$IPC::Cmd::USE_IPC_RUN"
 433 .el .SS "\f(CW$IPC::Cmd::USE_IPC_RUN\fP"
 434 .IX Subsection "$IPC::Cmd::USE_IPC_RUN"
 435 This variable controls whether IPC::Cmd will try to use IPC::Run
 436 when available and suitable. Defaults to true if you are on \f(CW\*(C`Win32\*(C'\fR.
 437 .ie n .SS "$IPC::Cmd::USE_IPC_OPEN3"
 438 .el .SS "\f(CW$IPC::Cmd::USE_IPC_OPEN3\fP"
 439 .IX Subsection "$IPC::Cmd::USE_IPC_OPEN3"
 440 This variable controls whether IPC::Cmd will try to use IPC::Open3
 441 when available and suitable. Defaults to true.
 442 .ie n .SS "$IPC::Cmd::WARN"
 443 .el .SS "\f(CW$IPC::Cmd::WARN\fP"
 444 .IX Subsection "$IPC::Cmd::WARN"
 445 This variable controls whether run time warnings should be issued, like
 446 the failure to load an \f(CW\*(C`IPC::*\*(C'\fR module you explicitly requested.
 447 .PP
 448 Defaults to true. Turn this off at your own risk.
 449 .SH "Caveats"
 450 .IX Header "Caveats"
 451 .IP "Whitespace and IPC::Open3 / \fIsystem()\fR" 4
 452 .IX Item "Whitespace and IPC::Open3 / system()"
 453 When using \f(CW\*(C`IPC::Open3\*(C'\fR or \f(CW\*(C`system\*(C'\fR, if you provide a string as the
 454 \&\f(CW\*(C`command\*(C'\fR argument, it is assumed to be appropriately escaped. You can
 455 use the \f(CW\*(C`QUOTE\*(C'\fR constant to use as a portable quote character (see above).
 456 However, if you provide and \f(CW\*(C`Array Reference\*(C'\fR, special rules apply:
 457 .Sp
 458 If your command contains \f(CW\*(C`Special Characters\*(C'\fR (< > | &), it will
 459 be internally stringified before executing the command, to avoid that these
 460 special characters are escaped and passed as arguments instead of retaining
 461 their special meaning.
 462 .Sp
 463 However, if the command contained arguments that contained whitespace,
 464 stringifying the command would loose the significance of the whitespace.
 465 Therefor, \f(CW\*(C`IPC::Cmd\*(C'\fR will quote any arguments containing whitespace in your
 466 command if the command is passed as an arrayref and contains special characters.
 467 .IP "Whitespace and IPC::Run" 4
 468 .IX Item "Whitespace and IPC::Run"
 469 When using \f(CW\*(C`IPC::Run\*(C'\fR, if you provide a string as the \f(CW\*(C`command\*(C'\fR argument,
 470 the string will be split on whitespace to determine the individual elements
 471 of your command. Although this will usually just Do What You Mean, it may
 472 break if you have files or commands with whitespace in them.
 473 .Sp
 474 If you do not wish this to happen, you should provide an array
 475 reference, where all parts of your command are already separated out.
 476 Note however, if there's extra or spurious whitespace in these parts,
 477 the parser or underlying code may not interpret it correctly, and
 478 cause an error.
 479 .Sp
 480 Example:
 481 The following code
 482 .Sp
 483 .Vb 1
 484 \&    gzip \-cdf foo.tar.gz | tar \-xf \-
 485 .Ve
 486 .Sp
 487 should either be passed as
 488 .Sp
 489 .Vb 1
 490 \&    "gzip \-cdf foo.tar.gz | tar \-xf \-"
 491 .Ve
 492 .Sp
 493 or as
 494 .Sp
 495 .Vb 1
 496 \&    [\*(Aqgzip\*(Aq, \*(Aq\-cdf\*(Aq, \*(Aqfoo.tar.gz\*(Aq, \*(Aq|\*(Aq, \*(Aqtar\*(Aq, \*(Aq\-xf\*(Aq, \*(Aq\-\*(Aq]
 497 .Ve
 498 .Sp
 499 But take care not to pass it as, for example
 500 .Sp
 501 .Vb 1
 502 \&    [\*(Aqgzip \-cdf foo.tar.gz\*(Aq, \*(Aq|\*(Aq, \*(Aqtar \-xf \-\*(Aq]
 503 .Ve
 504 .Sp
 505 Since this will lead to issues as described above.
 506 .IP "\s-1IO\s0 Redirect" 4
 507 .IX Item "IO Redirect"
 508 Currently it is too complicated to parse your command for \s-1IO\s0
 509 Redirections. For capturing \s-1STDOUT\s0 or \s-1STDERR\s0 there is a work around
 510 however, since you can just inspect your buffers for the contents.
 511 .IP "Interleaving \s-1STDOUT/STDERR\s0" 4
 512 .IX Item "Interleaving STDOUT/STDERR"
 513 Neither IPC::Run nor IPC::Open3 can interleave \s-1STDOUT\s0 and \s-1STDERR\s0. For short
 514 bursts of output from a program, ie this sample:
 515 .Sp
 516 .Vb 3
 517 \&    for ( 1..4 ) {
 518 \&        $_ % 2 ? print STDOUT $_ : print STDERR $_;
 519 \&    }
 520 .Ve
 521 .Sp
 522 IPC::[Run|Open3] will first read all of \s-1STDOUT\s0, then all of \s-1STDERR\s0, meaning
 523 the output looks like 1 line on each, namely '13' on \s-1STDOUT\s0 and '24' on \s-1STDERR\s0.
 524 .Sp
 525 It should have been 1, 2, 3, 4.
 526 .Sp
 527 This has been recorded in rt.cpan.org as bug #37532: Unable to interleave
 528 \&\s-1STDOUT\s0 and \s-1STDERR\s0
 529 .SH "See Also"
 530 .IX Header "See Also"
 531 \&\f(CW\*(C`IPC::Run\*(C'\fR, \f(CW\*(C`IPC::Open3\*(C'\fR
 532 .SH "ACKNOWLEDGEMENTS"
 533 .IX Header "ACKNOWLEDGEMENTS"
 534 Thanks to James Mastros and Martijn van der Streek for their
 535 help in getting IPC::Open3 to behave nicely.
 536 .PP
 537 Thanks to Petya Kohts for the \f(CW\*(C`run_forked\*(C'\fR code.
 538 .SH "BUG REPORTS"
 539 .IX Header "BUG REPORTS"
 540 Please report bugs or other issues to <bug\-ipc\-cmd@rt.cpan.org>.
 541 .SH "AUTHOR"
 542 .IX Header "AUTHOR"
 543 This module by Jos Boumans <kane@cpan.org>.
 544 .SH "COPYRIGHT"
 545 .IX Header "COPYRIGHT"
 546 This library is free software; you may redistribute and/or modify it
 547 under the same terms as Perl itself.