diff options
Diffstat (limited to 'Doc/library/subprocess.rst')
| -rw-r--r-- | Doc/library/subprocess.rst | 223 |
1 files changed, 208 insertions, 15 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 6f2d55b145..e44e08d325 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -81,12 +81,28 @@ This module defines one class called :class:`Popen`: Popen(['/bin/sh', '-c', args[0], args[1], ...]) + .. warning:: + + Executing shell commands that incorporate unsanitized input from an + untrusted source makes a program vulnerable to `shell injection + <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_, + a serious security flaw which can result in arbitrary command execution. + For this reason, the use of *shell=True* is **strongly discouraged** in cases + where the command string is constructed from external input:: + + >>> from subprocess import call + >>> filename = input("What file would you like to display?\n") + What file would you like to display? + non_existent; rm -rf / # + >>> call("cat " + filename, shell=True) # Uh-oh. This will end badly... + + *shell=False* does not suffer from this vulnerability; the above Note may be + helpful in getting code using *shell=False* to work. + On Windows: the :class:`Popen` class uses CreateProcess() to execute the child - program, which operates on strings. If *args* is a sequence, it will be - converted to a string using the :meth:`list2cmdline` method. Please note that - not all MS Windows applications interpret the command line the same way: - :meth:`list2cmdline` is designed for applications using the same rules as the MS - C runtime. + child program, which operates on strings. If *args* is a sequence, it will + be converted to a string in a manner described in + :ref:`converting-argument-sequence`. *bufsize*, if given, has the same meaning as the corresponding argument to the built-in open() function: :const:`0` means unbuffered, :const:`1` means line @@ -162,9 +178,10 @@ This module defines one class called :class:`Popen`: :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the 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) .. data:: PIPE @@ -184,7 +201,7 @@ This module defines one class called :class:`Popen`: Convenience Functions ^^^^^^^^^^^^^^^^^^^^^ -This module also defines two shortcut functions: +This module also defines the following shortcut functions: .. function:: call(*popenargs, **kwargs) @@ -196,6 +213,13 @@ This module also defines two shortcut functions: >>> retcode = subprocess.call(["ls", "-l"]) + .. warning:: + + Like :meth:`Popen.wait`, this will deadlock when using + ``stdout=PIPE`` and/or ``stderr=PIPE`` and the child process + generates enough output to a pipe such that it blocks waiting + for the OS pipe buffer to accept more data. + .. function:: check_call(*popenargs, **kwargs) @@ -211,6 +235,35 @@ This module also defines two shortcut functions: .. versionadded:: 2.5 + .. warning:: + + See the warning for :func:`call`. + + +.. function:: check_output(*popenargs, **kwargs) + + Run command with arguments and return its output as a byte string. + + If the exit code was non-zero it raises a :exc:`CalledProcessError`. The + :exc:`CalledProcessError` object will have the return code in the + :attr:`returncode` + attribute and output in the :attr:`output` attribute. + + The arguments are the same as for the :class:`Popen` constructor. Example:: + + >>> subprocess.check_output(["ls", "-l", "/dev/null"]) + 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n' + + The stdout argument is not allowed as it is used internally. + To capture standard error in the result, use ``stderr=subprocess.STDOUT``:: + + >>> subprocess.check_output( + ... ["/bin/sh", "-c", "ls non_existent_file; exit 0"], + ... stderr=subprocess.STDOUT) + 'ls: non_existent_file: No such file or directory\n' + + .. versionadded:: 2.7 + Exceptions ^^^^^^^^^^ @@ -218,7 +271,7 @@ Exceptions Exceptions raised in the child process, before the new program has started to execute, will be re-raised in the parent. Additionally, the exception object will have one extra attribute called :attr:`child_traceback`, which is a string -containing traceback information from the childs point of view. +containing traceback information from the child's point of view. The most common exception raised is :exc:`OSError`. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for @@ -258,9 +311,10 @@ Instances of the :class:`Popen` class have the following methods: .. warning:: - This will deadlock if the child process generates enough output to a - stdout or stderr pipe such that it blocks waiting for the OS pipe buffer - to accept more data. Use :meth:`communicate` to avoid that. + This will deadlock when using ``stdout=PIPE`` and/or + ``stderr=PIPE`` and the child process generates enough output to + a pipe such that it blocks waiting for the OS pipe buffer to + accept more data. Use :meth:`communicate` to avoid that. .. method:: Popen.communicate(input=None) @@ -289,8 +343,9 @@ Instances of the :class:`Popen` class have the following methods: .. note:: - On Windows only SIGTERM is supported so far. It's an alias for - :meth:`terminate`. + On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and + CTRL_BREAK_EVENT can be sent to processes started with a *creationflags* + parameter which includes `CREATE_NEW_PROCESS_GROUP`. .. versionadded:: 2.6 @@ -359,6 +414,109 @@ The following attributes are also available: ``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 + are used when the process creates a window. :: + + si = subprocess.STARTUPINFO() + si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW + + .. attribute:: hStdInput + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard input handle for the process. If :data:`STARTF_USESTDHANDLES` + is not specified, the default for standard input is the keyboard buffer. + + .. attribute:: hStdOutput + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard output handle for the process. Otherwise, this member is + ignored and the default for standard output is the console window's + buffer. + + .. attribute:: hStdError + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard error handle for the process. Otherwise, this member is + ignored and the default for standard error is the console window's buffer. + + .. attribute:: wShowWindow + + If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this member + can be any of the values that can be specified in the ``nCmdShow`` + parameter for the + `ShowWindow <http://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__ + function, except for ``SW_SHOWDEFAULT``. Otherwise, this member is + ignored. + + :data:`SW_HIDE` is provided for this attribute. It is used when + :class:`Popen` is called with ``shell=True``. + + +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 @@ -394,8 +552,11 @@ Replacing shell pipeline ==> p1 = Popen(["dmesg"], stdout=PIPE) p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE) + p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits. output = p2.communicate()[0] +The p1.stdout.close() call after starting the p2 is important in order for p1 +to receive a SIGPIPE if p2 exits before p1. Replacing :func:`os.system` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -557,3 +718,35 @@ shell intervention. This usage can be replaced as follows:: * popen2 closes all file descriptors by default, but you have to specify ``close_fds=True`` with :class:`Popen`. +Notes +----- + +.. _converting-argument-sequence: + +Converting an argument sequence to a string on Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On Windows, an *args* sequence is converted to a string that can be parsed +using the following rules (which correspond to the rules used by the MS C +runtime): + +1. Arguments are delimited by white space, which is either a + space or a tab. + +2. A string surrounded by double quotation marks is + interpreted as a single argument, regardless of white space + contained within. A quoted string can be embedded in an + argument. + +3. A double quotation mark preceded by a backslash is + interpreted as a literal double quotation mark. + +4. Backslashes are interpreted literally, unless they + immediately precede a double quotation mark. + +5. If backslashes immediately precede a double quotation mark, + every pair of backslashes is interpreted as a literal + backslash. If the number of backslashes is odd, the last + backslash escapes the next double quotation mark as + described in rule 3. + |