[3.14] 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 9416c758e51d95d18854472d403f4f13bcf3fe17..cb9ddc08a64d9b37561f61541b32d828655b950a 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 a0eae14aecdd82405f293a9cfad4c3ee9140a9a3..82e41bff87976d02cfdc490ce9070a10225c9ea7 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
 ---------------------