bpo-20104: Improve error handling and fix a reference leak in os.posix_spawn(). (#6332)

1 files changed, 27 insertions, 11 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 2e81459..4b4e931 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -3365,25 +3365,41 @@ written in Python, such as a mail server's external command delivery program.
 
 .. function:: posix_spawn(path, argv, env, file_actions=None)
 
-   Wraps the posix_spawn() C library API for use from Python.
+   Wraps the :c:func:`posix_spawn` C library API for use from Python.
 
-   Most users should use :class:`subprocess.run` instead of posix_spawn.
+   Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`.
 
    The *path*, *args*, and *env* arguments are similar to :func:`execve`.
 
    The *file_actions* argument may be a sequence of tuples describing actions
    to take on specific file descriptors in the child process between the C
-   library implementation's fork and exec steps.  The first item in each tuple
-   must be one of the three type indicator listed below describing the
-   remaining tuple elements:
+   library implementation's :c:func:`fork` and :c:func:`exec` steps.
+   The first item in each tuple must be one of the three type indicator
+   listed below describing the remaining tuple elements:
 
-   (os.POSIX_SPAWN_OPEN, fd, path, open flags, mode)
-   (os.POSIX_SPAWN_CLOSE, fd)
-   (os.POSIX_SPAWN_DUP2, fd, new_fd)
+   .. data:: POSIX_SPAWN_OPEN
 
-   These tuples correspond to the C library posix_spawn_file_actions_addopen,
-   posix_spawn_file_actions_addclose, and posix_spawn_file_actions_adddup2 API
-   calls used to prepare for the posix_spawn call itself.
+      (``os.POSIX_SPAWN_OPEN``, *fd*, *path*, *flags*, *mode*)
+
+      Performs ``os.dup2(os.open(path, flags, mode), fd)``.
+
+   .. data:: POSIX_SPAWN_CLOSE
+
+      (``os.POSIX_SPAWN_CLOSE``, *fd*)
+
+      Performs ``os.close(fd)``.
+
+   .. data:: POSIX_SPAWN_DUP2
+
+      (``os.POSIX_SPAWN_DUP2``, *fd*, *new_fd*)
+
+      Performs ``os.dup2(fd, new_fd)``.
+
+   These tuples correspond to the C library
+   :c:func:`posix_spawn_file_actions_addopen`,
+   :c:func:`posix_spawn_file_actions_addclose`, and
+   :c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare
+   for the :c:func:`posix_spawn` call itself.
 
    .. versionadded:: 3.7