From b5885eed7007adaba33f3786ea454d3d1f61d2f2 Mon Sep 17 00:00:00 2001 From: James Lownie Date: Wed, 16 Oct 2024 16:10:41 +1100 Subject: [PATCH 01/11] gh-125562: Updates documentation for exec* functions --- Doc/library/os.rst | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 33dd58febd9a5e..cdf417a72fed6a 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4210,15 +4210,6 @@ Process Management These functions may be used to create and manage processes. -The various :func:`exec\* ` functions take a list of arguments for the new -program loaded into the process. In each case, the first of these arguments is -passed to the new program as its own name rather than as an argument a user may -have typed on a command line. For the C programmer, this is the ``argv[0]`` -passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', -['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem -to be ignored. - - .. function:: abort() Generate a :const:`SIGABRT` signal to the current process. On Unix, the default @@ -4280,6 +4271,20 @@ to be ignored. :func:`sys.stdout.flush` or :func:`os.fsync` before calling an :func:`exec\* ` function. + *Arguments* + + The various :func:`exec\* ` functions take a list of arguments for the new + program loaded into the process. In each case, the first of these arguments must + be the name of the program itself, and not an argument that a user may + have typed on a command line. + + For the C programmer, this is the ``argv[0]`` + passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', + ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem + to be ignored. + + *Fixed and variable numbers of arguments* + The "l" and "v" variants of the :func:`exec\* ` functions differ in how command-line arguments are passed. The "l" variants are perhaps the easiest to work with if the number of parameters is fixed when the code is written; the @@ -4289,17 +4294,28 @@ to be ignored. parameter. In either case, the arguments to the child process should start with the name of the command being run, but this is not enforced. + *The location of the executable* + The variants which include a "p" near the end (:func:`execlp`, :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the environment is being replaced (using one of the :func:`exec\*e ` variants, discussed in the next paragraph), the new environment is used as the source of - the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`, + the :envvar:`PATH` variable. + + The other variants, :func:`execl`, :func:`execle`, :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to locate the executable; *path* must contain an appropriate absolute or relative path. Relative paths must include at least one slash, even on Windows, as plain names will not be resolved. + For :func:`execve` on some platforms, *path* may also be specified as an open + file descriptor. This functionality may not be supported on your platform; + you can check whether or not it is available using :data:`os.supports_fd`. + If it is unavailable, using it will raise a :exc:`NotImplementedError`. + + *Environment variables* + For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note that these all end in "e"), the *env* parameter must be a mapping which is used to define the environment variables for the new process (these are used @@ -4307,11 +4323,6 @@ to be ignored. :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to inherit the environment of the current process. - For :func:`execve` on some platforms, *path* may also be specified as an open - file descriptor. This functionality may not be supported on your platform; - you can check whether or not it is available using :data:`os.supports_fd`. - If it is unavailable, using it will raise a :exc:`NotImplementedError`. - .. audit-event:: os.exec path,args,env os.execl .. availability:: Unix, Windows, not WASI, not Android, not iOS. From 0a6e161db9e6b0dff276651eea470686e63dfcfc Mon Sep 17 00:00:00 2001 From: James Lownie Date: Wed, 16 Oct 2024 16:21:41 +1100 Subject: [PATCH 02/11] Minor change to section heading --- Doc/library/os.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index cdf417a72fed6a..ff4ef117063d47 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4294,7 +4294,7 @@ These functions may be used to create and manage processes. parameter. In either case, the arguments to the child process should start with the name of the command being run, but this is not enforced. - *The location of the executable* + *Location of the executable* The variants which include a "p" near the end (:func:`execlp`, :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the From 55edd0105062d8d03d33cad87db2f204b5a46045 Mon Sep 17 00:00:00 2001 From: James Lownie Date: Wed, 16 Oct 2024 18:15:33 +1100 Subject: [PATCH 03/11] gh-125562: Added links between the system(), spawnl() and execl() documentation sections --- Doc/library/os.rst | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index ff4ef117063d47..ad62c7e0a479fb 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4260,6 +4260,10 @@ These functions may be used to create and manage processes. execvp(file, args) execvpe(file, args, env) + (Note that the :mod:`subprocess` module provides more powerful facilities for + spawning new processes and retrieving their results; using that module is + preferable to using these functions.) + These functions all execute a new program, replacing the current process; they do not return. On Unix, the new executable is loaded into the current process, and will have the same process id as the caller. Errors will be reported as @@ -4334,6 +4338,11 @@ These functions may be used to create and manage processes. .. versionchanged:: 3.6 Accepts a :term:`path-like object`. + .. seealso:: + The :mod:`subprocess` module. + + The :func:`system` and :func:`spawnl` functions also execute a system command. + .. function:: _exit(n) Exit the process with status *n*, without calling cleanup handlers, flushing @@ -4839,13 +4848,14 @@ written in Python, such as a mail server's external command delivery program. spawnvp(mode, file, args) spawnvpe(mode, file, args, env) - Execute the program *path* in a new process. (Note that the :mod:`subprocess` module provides more powerful facilities for spawning new processes and retrieving their results; using that module is preferable to using these functions. Check especially the :ref:`subprocess-replacements` section.) + Execute the program *path* in a new process. + If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it exits normally, or ``-signal``, where *signal* is the signal that killed the @@ -4908,6 +4918,10 @@ written in Python, such as a mail server's external command delivery program. These functions are :term:`soft deprecated` and should no longer be used to write new code. The :mod:`subprocess` module is recommended instead. + .. seealso:: + The :mod:`subprocess` module. + + The :func:`system` and :func:`execl` functions also execute a system command. .. data:: P_NOWAIT P_NOWAITO @@ -4994,6 +5008,10 @@ written in Python, such as a mail server's external command delivery program. .. function:: system(command) + (Note that the :mod:`subprocess` module provides more powerful facilities for + executing programs; using that module is preferable to using these functions. + Refer to the :ref:`subprocess-replacements` section for some helpful recipes.) + Execute the command (a string) in a subshell. This is implemented by calling 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 @@ -5011,11 +5029,6 @@ written in Python, such as a mail server's external command delivery program. status of the command run; on systems using a non-native shell, consult your shell documentation. - The :mod:`subprocess` module provides more powerful facilities for spawning - new processes and retrieving their results; using that module is recommended - to using this function. See the :ref:`subprocess-replacements` section in - the :mod:`subprocess` documentation for some helpful recipes. - On Unix, :func:`waitstatus_to_exitcode` can be used to convert the result (exit status) into an exit code. On Windows, the result is directly the exit code. @@ -5024,6 +5037,10 @@ written in Python, such as a mail server's external command delivery program. .. availability:: Unix, Windows, not WASI, not Android, not iOS. + .. seealso:: + The :mod:`subprocess` module. + + The :func:`execl` and :func:`spawnl` functions also execute a system command. .. function:: times() From cbadaf5593ca71e13ab3448345720278f030bc04 Mon Sep 17 00:00:00 2001 From: jlownie Date: Sun, 20 Oct 2024 16:51:28 +1100 Subject: [PATCH 04/11] Update Doc/library/os.rst Co-authored-by: Martin Panter --- Doc/library/os.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index ad62c7e0a479fb..6419a3cb4791ec 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4275,7 +4275,7 @@ These functions may be used to create and manage processes. :func:`sys.stdout.flush` or :func:`os.fsync` before calling an :func:`exec\* ` function. - *Arguments* + *Program arguments* The various :func:`exec\* ` functions take a list of arguments for the new program loaded into the process. In each case, the first of these arguments must From fefa288a526522c4a6356978116084cfd7328076 Mon Sep 17 00:00:00 2001 From: James Lownie Date: Sun, 20 Oct 2024 16:59:50 +1100 Subject: [PATCH 05/11] gh-125562: Removed incorrect text regarding using subprocess.run instead of execl --- Doc/library/os.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index ad62c7e0a479fb..973af52b3c1a95 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4260,10 +4260,6 @@ These functions may be used to create and manage processes. execvp(file, args) execvpe(file, args, env) - (Note that the :mod:`subprocess` module provides more powerful facilities for - spawning new processes and retrieving their results; using that module is - preferable to using these functions.) - These functions all execute a new program, replacing the current process; they do not return. On Unix, the new executable is loaded into the current process, and will have the same process id as the caller. Errors will be reported as From 7ab5de36eb9a5df88829f91d2e8df4f0c87996cc Mon Sep 17 00:00:00 2001 From: James Lownie Date: Sun, 20 Oct 2024 17:05:02 +1100 Subject: [PATCH 06/11] gh-125562: Altered wording before 'argv[0]' in execl documentations --- Doc/library/os.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 973af52b3c1a95..68b4a366a250b6 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4278,8 +4278,8 @@ These functions may be used to create and manage processes. be the name of the program itself, and not an argument that a user may have typed on a command line. - For the C programmer, this is the ``argv[0]`` - passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', + This first argument is equivalent to the ``argv[0]`` + passed to a program's :c:func:`main` in a C program. For example, ``os.execv('/bin/echo', ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem to be ignored. From 090bce8e34f0dff09b9d721a8395430edb765ce4 Mon Sep 17 00:00:00 2001 From: jlownie Date: Sun, 20 Oct 2024 17:09:29 +1100 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: Martin Panter --- Doc/library/os.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 6419a3cb4791ec..d1a6a3edb4b98a 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4307,8 +4307,8 @@ These functions may be used to create and manage processes. discussed in the next paragraph), the new environment is used as the source of the :envvar:`PATH` variable. - The other variants, :func:`execl`, :func:`execle`, - :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to + The variants without "p" (:func:`execl`, :func:`execle`, + :func:`execv`, and :func:`execve`) will not use the :envvar:`PATH` variable to locate the executable; *path* must contain an appropriate absolute or relative path. Relative paths must include at least one slash, even on Windows, as plain names will not be resolved. @@ -4341,7 +4341,7 @@ These functions may be used to create and manage processes. .. seealso:: The :mod:`subprocess` module. - The :func:`system` and :func:`spawnl` functions also execute a system command. + The :func:`system` and :func:`spawn ` functions also execute a new program. .. function:: _exit(n) @@ -4921,7 +4921,7 @@ written in Python, such as a mail server's external command delivery program. .. seealso:: The :mod:`subprocess` module. - The :func:`system` and :func:`execl` functions also execute a system command. + The :func:`system` and :func:`exec ` functions also execute a new program. .. data:: P_NOWAIT P_NOWAITO @@ -5040,7 +5040,7 @@ written in Python, such as a mail server's external command delivery program. .. seealso:: The :mod:`subprocess` module. - The :func:`execl` and :func:`spawnl` functions also execute a system command. + The :func:`exec ` and :func:`spawn ` functions also execute a system command. .. function:: times() From 6c35df0ffccd8964aafff1aa1048d64549e65ebf Mon Sep 17 00:00:00 2001 From: jlownie Date: Sun, 17 Nov 2024 15:24:23 +1100 Subject: [PATCH 08/11] pythongh-125562: Rewording of documentation for execl function Incorporated vadmium's suggestion to reference the environment variables section Co-authored-by: Martin Panter --- Doc/library/os.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 869edf2dad3d67..39d40050c2bcba 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4315,8 +4315,8 @@ These functions may be used to create and manage processes. The variants which include a "p" near the end (:func:`execlp`, :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the - environment is being replaced (using one of the :func:`exec\*e ` variants, - discussed in the next paragraph), the new environment is used as the source of + environment is being replaced (see *Environment variables* + below), the new environment is used as the source of the :envvar:`PATH` variable. The variants without "p" (:func:`execl`, :func:`execle`, From 8d4d01049273a5684999456c293660c7b987b86f Mon Sep 17 00:00:00 2001 From: James Lownie Date: Sun, 17 Nov 2024 15:24:56 +1100 Subject: [PATCH 09/11] pythongh-125562: Rewording of documentation for execl function --- Doc/library/os.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index f6821ca2e25c57..962b04a8bc69f8 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4273,17 +4273,12 @@ These functions may be used to create and manage processes. *Program arguments* - The various :func:`exec\* ` functions take a list of arguments for the new - program loaded into the process. In each case, the first of these arguments must - be the name of the program itself, and not an argument that a user may - have typed on a command line. + The exec functions take a list of arguments for the new program. The first of these + is by convention the command name used on the command line, rather than an argument to the command, + and becomes argv[0] passed to the main function of a C program. - This first argument is equivalent to the ``argv[0]`` - passed to a program's :c:func:`main` in a C program. For example, ``os.execv('/bin/echo', - ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem - to be ignored. - - *Fixed and variable numbers of arguments* + For example, ``os.execv('/bin/echo', ['echo', 'foo', 'bar'])`` would only print ``foo bar``; + the echo argument would seem to be ignored. The "l" and "v" variants of the :func:`exec\* ` functions differ in how command-line arguments are passed. The "l" variants are perhaps the easiest From 7bd13df5a35846cc2ef13675002448d3bb0ad85d Mon Sep 17 00:00:00 2001 From: James Lownie Date: Mon, 20 Apr 2026 15:09:34 +1000 Subject: [PATCH 10/11] Removed trailing space --- Doc/library/os.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e28327f19b4881..a54918588061f9 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4720,7 +4720,7 @@ These functions may be used to create and manage processes. is by convention the command name used on the command line, rather than an argument to the command, and becomes argv[0] passed to the main function of a C program. - For example, ``os.execv('/bin/echo', ['echo', 'foo', 'bar'])`` would only print ``foo bar``; + For example, ``os.execv('/bin/echo', ['echo', 'foo', 'bar'])`` would only print ``foo bar``; the echo argument would seem to be ignored. The "l" and "v" variants of the :func:`exec\* ` functions differ in how From e3f6f7a22d66dc7b7bba6d963a732de5551fb4dc Mon Sep 17 00:00:00 2001 From: James Lownie Date: Mon, 20 Apr 2026 15:17:11 +1000 Subject: [PATCH 11/11] Removed trailing whitespace --- Doc/library/os.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index a54918588061f9..dbfd7d153fe0ef 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4716,8 +4716,8 @@ These functions may be used to create and manage processes. *Program arguments* - The exec functions take a list of arguments for the new program. The first of these - is by convention the command name used on the command line, rather than an argument to the command, + The exec functions take a list of arguments for the new program. The first of these + is by convention the command name used on the command line, rather than an argument to the command, and becomes argv[0] passed to the main function of a C program. For example, ``os.execv('/bin/echo', ['echo', 'foo', 'bar'])`` would only print ``foo bar``;