[3.6] bpo-22635: subprocess.getstatusoutput doc update. (GH-3398) (#3411)

The `subprocess.getstatusoutput` API was inadvertently changed
in Python 3.3.4.  Document the change, it is too late to undo the
API change now as it has shipped in many stable releases.
(cherry picked from commit 738b7d9766e1a794aaaabfba0d515a467ba833ca)

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 663e232851b0672acd99837c873e9d9d14f0fbd0..27f3e825961e1a1b7d6a8f1c3de2894c848926c0 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -1166,27 +1166,32 @@ handling consistency are valid for these functions.
 
 .. function:: getstatusoutput(cmd)
 
-   Return ``(status, output)`` of executing *cmd* in a shell.
+   Return ``(exitcode, output)`` of executing *cmd* in a shell.
 
    Execute the string *cmd* in a shell with :meth:`Popen.check_output` and
-   return a 2-tuple ``(status, output)``. The locale encoding is used;
+   return a 2-tuple ``(exitcode, output)``. The locale encoding is used;
    see the notes on :ref:`frequently-used-arguments` for more details.
 
    A trailing newline is stripped from the output.
-   The exit status for the command can be interpreted
-   according to the rules for the C function :c:func:`wait`.  Example::
+   The exit code for the command can be interpreted as the return code
+   of subprocess.  Example::
 
       >>> subprocess.getstatusoutput('ls /bin/ls')
       (0, '/bin/ls')
       >>> subprocess.getstatusoutput('cat /bin/junk')
-      (256, 'cat: /bin/junk: No such file or directory')
+      (1, 'cat: /bin/junk: No such file or directory')
       >>> subprocess.getstatusoutput('/bin/junk')
-      (256, 'sh: /bin/junk: not found')
+      (127, 'sh: /bin/junk: not found')
+      >>> subprocess.getstatusoutput('/bin/kill $$')
+      (-15, '')
 
    Availability: POSIX & Windows
 
    .. versionchanged:: 3.3.4
-      Windows support added
+      Windows support was added.
+
+      The function now returns (exitcode, output) instead of (status, output)
+      as it did in Python 3.3.3 and earlier.  See :func:`WEXITSTATUS`.
 
 
 .. function:: getoutput(cmd)