[3.13] gh-138234: clarify returncode behavior for subprocesses created with `shell...

gh-138234: clarify returncode behavior for subprocesses created with `shell=True` (GH-138536)
(cherry picked from commit 8a531f89df8f8bf4c4fe395f9edcdc19852bdf1c)

Co-authored-by: andreuu-tsai <32549555+andreuu-tsai@users.noreply.github.com>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>

diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 7ac9aa724ce0f896e56a97192ed4e942b38c3a4f..341d8a1b1480ce2887f3d7f69b9baad03b80cf05 100644 (file)
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -311,8 +311,16 @@ their completion.
 
       A ``None`` value indicates that the process has not terminated yet.
 
-      A negative value ``-N`` indicates that the child was terminated
-      by signal ``N`` (POSIX only).
+      For processes created with :func:`~asyncio.create_subprocess_exec`, a negative
+      value ``-N`` indicates that the child was terminated by signal ``N``
+      (POSIX only).
+
+      For processes created with :func:`~asyncio.create_subprocess_shell`, the
+      return code reflects the exit status of the shell itself (e.g. ``/bin/sh``),
+      which may map signals to codes such as ``128+N``. See the
+      documentation of the shell (for example, the Bash manual's Exit Status)
+      for details.
+
 
 
 .. _asyncio-subprocess-threads:

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index f6d9a6133fa8c0c45edfb47d26bd538f29c786c8..4b2a1a9f658601f191bbabc5cfbb8a3c784a28ab 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -952,6 +952,11 @@ Reassigning them to new values is unsupported:
    A negative value ``-N`` indicates that the child was terminated by signal
    ``N`` (POSIX only).
 
+   When ``shell=True``, the return code reflects the exit status of the shell
+   itself (e.g. ``/bin/sh``), which may map signals to codes such as
+   ``128+N``. See the documentation of the shell (for example, the Bash
+   manual's Exit Status) for details.
+
 
 Windows Popen Helpers
 ---------------------