gh-125562: Update to documentation for exec* functions

Doc/library/os.rst

@@ -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
@@ -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
@@ -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.
+
+   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\* <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
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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()