gh-138234: clarify returncode behavior for subprocesses created with `shell=True...

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 def6d58eabbeee2425584ee45950137071f0bf9c..9e261a0ca039023af2db4d3b1428d81fbf0919d8 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -964,6 +964,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
 ---------------------