Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 8a9db99

Browse files
freddrakefreddrake
committed
Updated documentation relating to the various flavors of popen[234]()
for Windows & Unix.
1 parent 18b9b93 commit 8a9db99

2 files changed

Lines changed: 79 additions & 24 deletions

File tree

‎Doc/lib/libos.tex‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,36 @@ \subsection{File Object Creation \label{os-newstreams}}
296296
\end{funcdesc}
297297

298298

299+
For each of these \function{popen()} variants, if \var{bufsize} is
300+
specified, it specifies the buffer size for the I/O pipes.
301+
\var{mode}, if provided, should be the string \code{'b'} or
302+
\code{'t'}; on Windows this is needed to determine whether the file
303+
objects should be opened in binary or text mode. The default value
304+
for \var{mode} is \code{'t'}.
305+
306+
\begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}}
307+
Executes \var{cmd} as a sub-process. Returns the file objects
308+
\code{(\var{child_stdin}, \var{child_stdout})}.
309+
\versionadded{2.0}
310+
\end{funcdesc}
311+
312+
\begin{funcdesc}{popen3}{cmd\optional{, bufsize\optional{, mode}}}
313+
Executes \var{cmd} as a sub-process. Returns the file objects
314+
\code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.
315+
\versionadded{2.0}
316+
\end{funcdesc}
317+
318+
\begin{funcdesc}{popen4}{cmd\optional{, bufsize\optional{, mode}}}
319+
Executes \var{cmd} as a sub-process. Returns the file objects
320+
\code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
321+
\versionadded{2.0}
322+
\end{funcdesc}
323+
324+
This functionality is also available in the \refmodule{popen2} module
325+
using functions of the same names, but the return values of those
326+
functions have a different order.
327+
328+
299329
\subsection{File Descriptor Operations \label{os-fd-ops}}
300330

301331
These functions operate on I/O streams referred to

‎Doc/lib/libpopen2.tex‎

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2,39 +2,53 @@ \section{\module{popen2} ---
22
Subprocesses with accessible I/O streams}
33

44
\declaremodule{standard}{popen2}
5-
\platform{Unix}
5+
\platform{Unix, Windows}
66
\modulesynopsis{Subprocesses with accessible standard I/O streams.}
77
\sectionauthor{Drew Csillag}{[email protected]}
88

99

10-
This module allows you to spawn processes and connect their
11-
input/output/error pipes and obtain their return codes under \UNIX.
12-
Similar functionality exists for Windows platforms using the
13-
\module{win32pipe} module provided as part of Mark Hammond's Windows
14-
extensions.
10+
This module allows you to spawn processes and connect to their
11+
input/output/error pipes and obtain their return codes under
12+
\UNIX{} and Windows.
1513

16-
The primary interface offered by this module is a pair of factory
17-
functions:
14+
Note that starting with Python 2.0, this functionality is available
15+
using functions from the \refmodule{os} module which have the same
16+
names as the factory functions here, but the order of the return
17+
values is more intuitive in the \refmodule{os} module variants.
1818

19-
\begin{funcdesc}{popen2}{cmd\optional{, bufsize}}
20-
Executes \var{cmd} as a sub-process. If \var{bufsize} is specified,
21-
it specifies the buffer size for the I/O pipes. Returns the file
22-
objects \code{(\var{child_stdout}, \var{child_stdin})}.
19+
The primary interface offered by this module is a trio of factory
20+
functions. For each of these, if \var{bufsize} is specified,
21+
it specifies the buffer size for the I/O pipes. \var{mode}, if
22+
provided, should be the string \code{'b'} or \code{'t'}; on Windows
23+
this is needed to determine whether the file objects should be opened
24+
in binary or text mode. The default value for \var{mode} is
25+
\code{'t'}.
26+
27+
\begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}}
28+
Executes \var{cmd} as a sub-process. Returns the file objects
29+
\code{(\var{child_stdout}, \var{child_stdin})}.
30+
\end{funcdesc}
31+
32+
\begin{funcdesc}{popen3}{cmd\optional{, bufsize\optional{, mode}}}
33+
Executes \var{cmd} as a sub-process. Returns the file objects
34+
\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}.
2335
\end{funcdesc}
2436

25-
\begin{funcdesc}{popen3}{cmd\optional{, bufsize}}
26-
Executes \var{cmd} as a sub-process. If \var{bufsize} is specified,
27-
it specifies the buffer size for the I/O pipes. Returns the file
28-
objects \code{(\var{child_stdout}, \var{child_stdin},
29-
\var{child_stderr})}.
37+
\begin{funcdesc}{popen4}{cmd\optional{, bufsize\optional{, mode}}}
38+
Executes \var{cmd} as a sub-process. Returns the file objects
39+
\code{(\var{child_stdout_and_stderr}, \var{child_stdin})}.
40+
\versionadded{2.0}
3041
\end{funcdesc}
3142

32-
The class defining the objects returned by the factory functions is
33-
also available:
43+
44+
On \UNIX, a class defining the objects returned by the factory
45+
functions is also available. These are not used for the Windows
46+
implementation, and are not available on that platform.
3447

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

3953
If not using one off the helper functions to create \class{Popen3}
4054
objects, the parameter \var{cmd} is the shell command to execute in a
@@ -44,10 +58,18 @@ \section{\module{popen2} ---
4458
specifies the size of the I/O buffers to/from the child process.
4559
\end{classdesc}
4660

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

48-
\subsection{Popen3 Objects \label{popen3-objects}}
69+
\subsection{Popen3 and Popen4 Objects \label{popen3-objects}}
4970

50-
Instances of the \class{Popen3} class have the following methods:
71+
Instances of the \class{Popen3} and \class{Popen4} classes have the
72+
following methods:
5173

5274
\begin{methoddesc}{poll}{}
5375
Returns \code{-1} if child process hasn't completed yet, or its return
@@ -59,10 +81,12 @@ \subsection{Popen3 Objects \label{popen3-objects}}
5981
\end{methoddesc}
6082

6183

62-
The following attributes of \class{Popen3} objects are also available:
84+
The following attributes are also available:
6385

6486
\begin{memberdesc}{fromchild}
65-
A file object that provides output from the child process.
87+
A file object that provides output from the child process. For
88+
\class{Popen4} instances, this will provide both the standard output
89+
and standard error streams.
6690
\end{memberdesc}
6791

6892
\begin{memberdesc}{tochild}
@@ -72,6 +96,7 @@ \subsection{Popen3 Objects \label{popen3-objects}}
7296
\begin{memberdesc}{childerr}
7397
Where the standard error from the child process goes is
7498
\var{capturestderr} was true for the constructor, or \code{None}.
99+
This will always be \code{None} for \class{Popen4} instances.
75100
\end{memberdesc}
76101

77102
\begin{memberdesc}{pid}

0 commit comments

Comments
 (0)