From 6dfce696934829d84ebfb47646db8e20d54cf6a7 Mon Sep 17 00:00:00 2001 From: uniocto Date: Wed, 12 May 2021 05:47:05 +0900 Subject: [PATCH] bpo-23750: Document os-system, subprocess. Patch by Martin Panter. (GH-26016) * Document os-system, subprocess Patch * Update Doc/library/os.rst Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> (cherry picked from commit 5f2eb87f2893c5e77ade4d662cebcce59d3f2c2f) Co-authored-by: uniocto --- Doc/library/os.rst | 8 ++++---- Doc/library/subprocess.rst | 8 +++++++- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 1198c4afb8386b..35a9f8cf3adb71 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3965,12 +3965,12 @@ written in Python, such as a mail server's external command delivery program. the Standard C function :c:func:`system`, and has the same limitations. Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the executed command. If *command* generates any output, it will be sent to - the interpreter standard output stream. + the interpreter standard output stream. The C standard does not + specify the meaning of the return value of the C function, so the return + value of the Python function is system-dependent. On Unix, the return value is the exit status of the process encoded in the - format specified for :func:`wait`. Note that POSIX does not specify the - meaning of the return value of the C :c:func:`system` function, so the return - value of the Python function is system-dependent. + format specified for :func:`wait`. On Windows, the return value is that returned by the system shell after running *command*. The shell is given by the Windows environment variable diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 3150aa60700ee7..762da9b1b4dca3 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -1268,11 +1268,17 @@ Replacing :func:`os.system` sts = os.system("mycmd" + " myarg") # becomes - sts = call("mycmd" + " myarg", shell=True) + retcode = call("mycmd" + " myarg", shell=True) Notes: * Calling the program through the shell is usually not required. +* The :func:`call` return value is encoded differently to that of + :func:`os.system`. + +* The :func:`os.system` function ignores SIGINT and SIGQUIT signals while + the command is running, but the caller must do this separately when + using the :mod:`subprocess` module. A more realistic example would look like this::