Doc/lib/libpopen2.tex

\section{\module{popen2} ---
         Subprocesses with accessible I/O streams}

\declaremodule{standard}{popen2}
  \platform{Unix, Windows}
\modulesynopsis{Subprocesses with accessible standard I/O streams.}
\sectionauthor{Drew Csillag}{drew_csillag@geocities.com}


This module allows you to spawn processes and connect to their
input/output/error pipes and obtain their return codes under
\UNIX{} and Windows.

Note that starting with Python 2.0, this functionality is available
using functions from the \refmodule{os} module which have the same
names as the factory functions here, but the order of the return
values is more intuitive in the \refmodule{os} module variants.

The primary interface offered by this module is a trio of factory
functions.  For each of these, if \var{bufsize} is specified, 
it specifies the buffer size for the I/O pipes.  \var{mode}, if
provided, should be the string \code{'b'} or \code{'t'}; on Windows
this is needed to determine whether the file objects should be opened
in binary or text mode.  The default value for \var{mode} is
\code{'t'}.

The only way to retrieve the return codes for the child processes is
by using the \method{poll()} or \method{wait()} methods on the
\class{Popen3} and \class{Popen4} classes; these are only available on
\UNIX.  This information is not available when using the
\function{popen2()}, \function{popen3()}, and \function{popen4()}
functions, or the equivalent functions in the \refmodule{os} module.

\begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}}
Executes \var{cmd} as a sub-process.  Returns the file objects
\code{(\var{child_stdout}, \var{child_stdin})}.
\end{funcdesc}

\begin{funcdesc}{popen3}{cmd\optional{, bufsize\optional{, mode}}}
Executes \var{cmd} as a sub-process.  Returns the file objects
\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}.
\end{funcdesc}

\begin{funcdesc}{popen4}{cmd\optional{, bufsize\optional{, mode}}}
Executes \var{cmd} as a sub-process.  Returns the file objects
\code{(\var{child_stdout_and_stderr}, \var{child_stdin})}.
\versionadded{2.0}
\end{funcdesc}


On \UNIX, a class defining the objects returned by the factory
functions is also available.  These are not used for the Windows
implementation, and are not available on that platform.

\begin{classdesc}{Popen3}{cmd\optional{, capturestderr\optional{, bufsize}}}
This class represents a child process.  Normally, \class{Popen3}
instances are created using the \function{popen2()} and
\function{popen3()} factory functions described above.

If not using one off the helper functions to create \class{Popen3}
objects, the parameter \var{cmd} is the shell command to execute in a
sub-process.  The \var{capturestderr} flag, if true, specifies that
the object should capture standard error output of the child process.
The default is false.  If the \var{bufsize} parameter is specified, it
specifies the size of the I/O buffers to/from the child process.
\end{classdesc}

\begin{classdesc}{Popen4}{cmd\optional{, bufsize}}
Similar to \class{Popen3}, but always captures standard error into the
same file object as standard output.  These are typically created
using \function{popen4()}.
\versionadded{2.0}
\end{classdesc}


\subsection{Popen3 and Popen4 Objects \label{popen3-objects}}

Instances of the \class{Popen3} and \class{Popen4} classes have the
following methods:

\begin{methoddesc}{poll}{}
Returns \code{-1} if child process hasn't completed yet, or its return 
code otherwise.
\end{methoddesc}

\begin{methoddesc}{wait}{}
Waits for and returns the status code of the child process.  The
status code encodes both the return code of the process and
information about whether it exited using the \cfunction{exit()}
system call or died due to a signal.  Functions to help interpret the
status code are defined in the \refmodule{os} module; see section
\ref{os-process} for the \function{W\var{*}()} family of functions.
\end{methoddesc}


The following attributes are also available: 

\begin{memberdesc}{fromchild}
A file object that provides output from the child process.  For
\class{Popen4} instances, this will provide both the standard output
and standard error streams.
\end{memberdesc}

\begin{memberdesc}{tochild}
A file object that provides input to the child process.
\end{memberdesc}

\begin{memberdesc}{childerr}
Where the standard error from the child process goes is
\var{capturestderr} was true for the constructor, or \code{None}.
This will always be \code{None} for \class{Popen4} instances.
\end{memberdesc}

\begin{memberdesc}{pid}
The process ID of the child process.
\end{memberdesc}