cpython: f8fae22a1ff0 (original) (raw)

Mercurial > cpython

changeset 69701:f8fae22a1ff0

Fix #11961. Document STARTUPINFO and creation flag options. [#11961]

Brian Curtin brian@python.org
date	Fri, 29 Apr 2011 22:21:35 -0500
parents	2665a28643b8(current diff)f0092c611004(diff)
children	0c21de0cca44
files	Doc/library/subprocess.rst
diffstat	1 files changed, 107 insertions(+), 3 deletions(-)[+] [-] Doc/library/subprocess.rst 110

line wrap: on

line diff

--- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -214,9 +214,10 @@ This module defines one class called :cl :attr:stdout, :attr:stdin and :attr:stderr are not updated by the :meth:communicate method.

The startupinfo and creationflags, if given, will be passed to the
underlying CreateProcess() function. They can specify things such as appearance
of the main window and priority for the new process. (Windows only)

If given, startupinfo will be a :class:STARTUPINFO object, which is
passed to the underlying CreateProcess function.
creationflags, if given, can be :data:CREATE_NEW_CONSOLE or
:data:CREATE_NEW_PROCESS_GROUP. (Windows only) Popen objects are supported as context managers via the :keyword:with statement, closing any open file descriptors on exit. @@ -551,6 +552,109 @@ The following attributes are also availa N (Unix only).

+Windows Popen Helpers +--------------------- + +The :class:STARTUPINFO class and following constants are only available +on Windows. + +.. class:: STARTUPINFO() +

Partial support of the Windows
STARTUPINFO <http://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>__
structure is used for :class:Popen creation. +
.. attribute:: dwFlags +

 A bit field that determines whether certain :class:`STARTUPINFO` members[](#l1.35)

 are used when the process creates a window. ::[](#l1.36)

    si = subprocess.STARTUPINFO()[](#l1.38)

    si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW[](#l1.39)

.. attribute:: hStdInput +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.43)

 the standard input handle for the process. If :data:`STARTF_USESTDHANDLES`[](#l1.44)

 is not specified, the default for standard input is the keyboard buffer.[](#l1.45)

.. attribute:: hStdOutput +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.49)

 the standard output handle for the process. Otherwise, this member is[](#l1.50)

 ignored and the default for standard output is the console window's[](#l1.51)

```
 buffer.[](#l1.52)
```

.. attribute:: hStdError +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.56)

 the standard error handle for the process. Otherwise, this member is[](#l1.57)

 ignored and the default for standard error is the console window's buffer.[](#l1.58)

.. attribute:: wShowWindow +

 If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this member[](#l1.62)

 can be any of the values that can be specified in the ``nCmdShow``[](#l1.63)

```
 parameter for the[](#l1.64)
```

 `ShowWindow <http://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__[](#l1.65)

 function, except for ``SW_SHOWDEFAULT``. Otherwise, this member is[](#l1.66)

```
 ignored.[](#l1.67)
```

 :data:`SW_HIDE` is provided for this attribute. It is used when[](#l1.69)

 :class:`Popen` is called with ``shell=True``.[](#l1.70)

+ + +Constants +^^^^^^^^^ + +The :mod:subprocess module exposes the following constants. + +.. data:: STD_INPUT_HANDLE +

The standard input device. Initially, this is the console input buffer,
CONIN$. +

+.. data:: STD_OUTPUT_HANDLE +

The standard output device. Initially, this is the active console screen
buffer, CONOUT$. +

+.. data:: STD_ERROR_HANDLE +

The standard error device. Initially, this is the active console screen
buffer, CONOUT$. +

+.. data:: SW_HIDE +

Hides the window. Another window will be activated. +

+.. data:: STARTF_USESTDHANDLES +

Specifies that the :attr:STARTUPINFO.hStdInput,
:attr:STARTUPINFO.hStdOutput, and :attr:STARTUPINFO.hStdError members
contain additional information. +

+.. data:: STARTF_USESHOWWINDOW +

Specifies that the :attr:STARTUPINFO.wShowWindow member contains
additional information. +

+.. data:: CREATE_NEW_CONSOLE +

The new process has a new console, instead of inheriting its parent's
console (the default). +
This flag is always set when :class:Popen is created with shell=True. +

+.. data:: CREATE_NEW_PROCESS_GROUP +

A :class:Popen creationflags parameter to specify that a new process
group will be created. This flag is necessary for using :func:os.kill
on the subprocess. +
This flag is ignored if :data:CREATE_NEW_CONSOLE is specified. +

+ .. _subprocess-replacements: Replacing Older Functions with the subprocess Module