Skip to content

gh-125562: Update to documentation for exec* functions #125565

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
Open

gh-125562: Update to documentation for exec* functions #125565

Changes from 3 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
b5885ee
gh-125562: Updates documentation for exec* functions
jlownie Oct 16, 2024
0a6e161
Minor change to section heading
jlownie Oct 16, 2024
55edd01
gh-125562: Added links between the system(), spawnl() and execl() doc…
jlownie Oct 16, 2024
cbadaf5
Update Doc/library/os.rst
jlownie Oct 20, 2024
fefa288
gh-125562: Removed incorrect text regarding using subprocess.run inst…
jlownie Oct 20, 2024
7ab5de3
gh-125562: Altered wording before 'argv[0]' in execl documentations
jlownie Oct 20, 2024
090bce8
Apply suggestions from code review
jlownie Oct 20, 2024
22909cb
Merge branch 'exec_doco' of https://github.com/jlownie/cpython into e…
jlownie Oct 20, 2024
d339d8f
Merge branch 'main' into exec_doco
jlownie Oct 20, 2024
a506cbe
Merge branch 'main' into exec_doco
jlownie Nov 17, 2024
6c35df0
pythongh-125562: Rewording of documentation for execl function
jlownie Nov 17, 2024
8d4d010
pythongh-125562: Rewording of documentation for execl function
jlownie Nov 17, 2024
cbeaac2
Merge branch 'exec_doco' of https://github.com/jlownie/cpython into e…
jlownie Nov 17, 2024
5ed449f
Merge branch 'main' into exec_doco
jlownie Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 49 additions & 21 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4210,15 +4210,6 @@ Process Management

These functions may be used to create and manage processes.

The various :func:`exec\* <execl>` 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
Expand Down Expand Up @@ -4269,6 +4260,10 @@ to be ignored.
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
Expand All @@ -4280,6 +4275,20 @@ to be ignored.
:func:`sys.stdout.flush` or :func:`os.fsync` before calling an
:func:`exec\* <execl>` function.

*Arguments*

The various :func:`exec\* <execl>` 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since you already edited the second sentence, I’ll point out that often the first word on a command line is indeed the program name (e.g. shell command “echo bar”) so saying “not an argument . . . typed on a command line” is confusing if not wrong.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm open to any suggestions as to better wording? That phrasing came from the original documentation, I agree it's not great but I found it difficult to come up with something better that I was confident was correct.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is my attempt:

The exec functions take a list of arguments for the new program. The first of these is by convention the command name from 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; the echo argument would seem to be ignored.


For the C programmer, this is the ``argv[0]``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m not sure breaking the paragraph works. “This” refers to the name of the program (topic of the last sentence of the last paragraph), not the overall Program Arguments heading.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided to retain the paragraph break and instead reworded the first sentence in the paragraph. I'm not entirely sure what the documentation is getting at with the second sentence in the paragraph. I'm open to further suggestions for improving this paragraph - I feel it could be improved but I'm not sure how.

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\* <execl>` 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
Expand All @@ -4289,29 +4298,35 @@ 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.

*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 <execl>` 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
instead of the current process' environment); the functions :func:`execl`,
: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.
Expand All @@ -4323,6 +4338,11 @@ to be ignored.
.. 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
Expand Down Expand Up @@ -4828,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
Expand Down Expand Up @@ -4897,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
Expand Down Expand Up @@ -4983,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
Expand All @@ -5000,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.
Expand All @@ -5013,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()

Expand Down
Loading