mingw/html/lib/IPC/Open3.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>open3 - open a process for reading, writing, and error handling</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;open3 - open a process for reading, writing, and error handling</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#warning">WARNING</a></li>
  26 </ul>
  27 <!-- INDEX END -->
  28
  29 <hr />
  30 <p>
  31 </p>
  32 <h1><a name="name">NAME</a></h1>
  33 <p>IPC::Open3, open3 - open a process for reading, writing, and error handling</p>
  34 <p>
  35 </p>
  36 <hr />
  37 <h1><a name="synopsis">SYNOPSIS</a></h1>
  38 <pre>
  39     $pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
  40                     'some cmd and args', 'optarg', ...);</pre>
  41 <pre>
  42     my($wtr, $rdr, $err);
  43     $pid = open3($wtr, $rdr, $err,
  44                     'some cmd and args', 'optarg', ...);</pre>
  45 <p>
  46 </p>
  47 <hr />
  48 <h1><a name="description">DESCRIPTION</a></h1>
  49 <p>Extremely similar to open2(), <code>open3()</code> spawns the given $cmd and
  50 connects CHLD_OUT for reading from the child, CHLD_IN for writing to
  51 the child, and CHLD_ERR for errors.  If CHLD_ERR is false, or the
  52 same file descriptor as CHLD_OUT, then STDOUT and STDERR of the child
  53 are on the same filehandle.  The CHLD_IN will have autoflush turned
  54 on.</p>
  55 <p>If CHLD_IN begins with <code>&lt;&amp;</code>, then CHLD_IN will be closed in the
  56 parent, and the child will read from it directly.  If CHLD_OUT or
  57 CHLD_ERR begins with <code>&gt;&amp;</code>, then the child will send output
  58 directly to that filehandle.  In both cases, there will be a <code>dup(2)</code>
  59 instead of a <code>pipe(2)</code> made.</p>
  60 <p>If either reader or writer is the null string, this will be replaced
  61 by an autogenerated filehandle.  If so, you must pass a valid lvalue
  62 in the parameter slot so it can be overwritten in the caller, or
  63 an exception will be raised.</p>
  64 <p>The filehandles may also be integers, in which case they are understood
  65 as file descriptors.</p>
  66 <p><code>open3()</code> returns the process ID of the child process.  It doesn't return on
  67 failure: it just raises an exception matching <code>/^open3:/</code>.  However,
  68 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_exec"><code>exec</code></a> failures in the child are not detected.  You'll have to
  69 trap SIGPIPE yourself.</p>
  70 <p>Note if you specify <code>-</code> as the command, in an analogous fashion to
  71 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open(FOO, &quot;-|&quot;)</code></a> the child process will just be the forked Perl
  72 process rather than an external command.  This feature isn't yet
  73 supported on Win32 platforms.</p>
  74 <p><code>open3()</code> does not wait for and reap the child process after it exits.
  75 Except for short programs where it's acceptable to let the operating system
  76 take care of this, you need to do this yourself.  This is normally as
  77 simple as calling <code>waitpid $pid, 0</code> when you're done with the process.
  78 Failing to do this can result in an accumulation of defunct or ``zombie''
  79 processes.  See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#waitpid">waitpid in the perlfunc manpage</a> for more information.</p>
  80 <p>If you try to read from the child's stdout writer and their stderr
  81 writer, you'll have problems with blocking, which means you'll want
  82 to use <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select()</code></a> or the IO::Select, which means you'd best use
  83 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_sysread"><code>sysread()</code></a> instead of <code>readline()</code> for normal stuff.</p>
  84 <p>This is very dangerous, as you may block forever.  It assumes it's
  85 going to talk to something like <strong>bc</strong>, both writing to it and reading
  86 from it.  This is presumably safe because you ``know'' that commands
  87 like <strong>bc</strong> will read a line at a time and output a line at a time.
  88 Programs like <strong>sort</strong> that read their entire input stream first,
  89 however, are quite apt to cause deadlock.</p>
  90 <p>The big problem with this approach is that if you don't have control
  91 over source code being run in the child process, you can't control
  92 what it does with pipe buffering.  Thus you can't just open a pipe to
  93 <code>cat -v</code> and continually read and write a line from it.</p>
  94 <p>
  95 </p>
  96 <hr />
  97 <h1><a name="warning">WARNING</a></h1>
  98 <p>The order of arguments differs from that of open2().</p>
  99 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 100 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 101 <big><strong><span class="block">&nbsp;open3 - open a process for reading, writing, and error handling</span></strong></big>
 102 </td></tr>
 103 </table>
 104
 105 </body>
 106
 107 </html>