popen2 section for the library reference, contributed by Drew Csillag, with

some reorganization.

1 files changed, 71 insertions, 0 deletions

diff --git a/Doc/libpopen2.tex b/Doc/libpopen2.tex
new file mode 100644
index 0000000..9e8a0ca
--- /dev/null
+++ b/Doc/libpopen2.tex
@@ -0,0 +1,71 @@
+% This section was contributed by Drew Csillag
+% <drew_csillag@geocities.com>, with some re-organization by Fred L.
+% Drake, Jr. <fdrake@acm.org>.
+
+\section{Standard Module \module{popen2}}
+\label{module-popen2}
+\stmodindex{popen2}
+
+This module allows you to spawn processes and connect their 
+input/output/error pipes and obtain their return codes.
+
+The primary interface offered by this module is a pair of factory
+functions:
+
+\begin{funcdesc}{popen2}{cmd\optional{, bufsize}}
+Executes \var{cmd} as a sub-process.  If \var{bufsize} is specified, 
+it specifies the buffer size for the I/O pipes.  Returns
+\code{(\var{child_stdout}, \var{child_stdin})}.
+\end{funcdesc}
+
+\begin{funcdesc}{popen2}{cmd\optional{, bufsize}}
+Executes \var{cmd} as a sub-process.  If \var{bufsize} is specified, 
+it specifies the buffer size for the I/O pipes.  Returns
+\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}.
+\end{funcdesc}
+
+The class defining the objects returned by the factory functions is
+also available:
+
+\begin{classdesc}{Popen3}{cmd\optional{, capturestderr\optional{, bufsize}}}
+This class represents a child process.  Normally, \class{Popen3}
+instances are created using the 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}
+
+
+\subsection{Popen3 Objects}
+\label{popen3-objects}
+
+Instances of the \class{Popen3} class 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 return code of the child process.
+\end{methoddesc}
+
+
+The following attributes of \class{Popen3} objects are also available: 
+
+\begin{datadesc}{fromchild}
+A file object that provides output from the child process.
+\end{datadesc}
+
+\begin{datadesc}{tochild}
+A file object that provides input to the child process.
+\end{datadesc}
+
+\begin{datadesc}{childerr}
+Where the standard error from the child process goes is
+\var{capturestderr} was true for the constructor, or \code{None}.
+\end{datadesc}