Issue #18571: Implementation of the PEP 446: file descriptors and file handles

are now created non-inheritable; add functions os.get/set_inheritable(),
os.get/set_handle_inheritable() and socket.socket.get/set_inheritable().

6 files changed, 186 insertions, 15 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 399f1ff..67b77f7 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -979,6 +979,8 @@ are always available.  They are listed here in alphabetical order.
    :mod:`os.open` as *opener* results in functionality similar to passing
    ``None``).
 
+   The newly created file is :ref:`non-inheritable <fd_inheritance>`.
+
    The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
    :func:`os.open` function to open a file relative to a given directory::
 
@@ -992,10 +994,6 @@ are always available.  They are listed here in alphabetical order.
       ...
       >>> os.close(dir_fd)  # don't leak a file descriptor
 
-   .. versionchanged:: 3.3
-      The *opener* parameter was added.
-      The ``'x'`` mode was added.
-
    The type of :term:`file object` returned by the :func:`open` function
    depends on the mode.  When :func:`open` is used to open a file in a text
    mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
@@ -1022,10 +1020,15 @@ are always available.  They are listed here in alphabetical order.
    and :mod:`shutil`.
 
    .. versionchanged:: 3.3
+      The *opener* parameter was added.
+      The ``'x'`` mode was added.
       :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
       :exc:`FileExistsError` is now raised if the file opened in exclusive
       creation mode (``'x'``) already exists.
 
+   .. versionchanged:: 3.4
+      The file is now non-inheritable.
+
 
 .. XXX works for bytes too, but should it?
 .. function:: ord(c)
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 8f3964f..a218881 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -522,6 +522,8 @@ Raw File I/O
    :mod:`os.open` as *opener* results in functionality similar to passing
    ``None``).
 
+   The newly created file is :ref:`non-inheritable <fd_inheritance>`.
+
    See the :func:`open` built-in function for examples on using the *opener*
    parameter.
 
@@ -529,6 +531,9 @@ Raw File I/O
       The *opener* parameter was added.
       The ``'x'`` mode was added.
 
+   .. versionchanged:: 3.4
+      The file is now non-inheritable.
+
    In addition to the attributes and methods from :class:`IOBase` and
    :class:`RawIOBase`, :class:`FileIO` provides the following data
    attributes:
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 82d05ed..848fd16 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -685,17 +685,30 @@ as internal buffering of data.
 
 .. function:: dup(fd)
 
-   Return a duplicate of file descriptor *fd*.
+   Return a duplicate of file descriptor *fd*. The new file descriptor is
+   :ref:`non-inheritable <fd_inheritance>`.
+
+   On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
+   2: stderr), the new file descriptor is :ref:`inheritable
+   <fd_inheritance>`.
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.4
+      The new file descriptor is now non-inheritable.
+
 
-.. function:: dup2(fd, fd2)
+.. function:: dup2(fd, fd2, inheritable=True)
 
    Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
+   The file descriptor *fd2* is :ref:`inheritable <fd_inheritance>` by default,
+   or non-inheritable if *inheritable* is ``False``.
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.4
+      Add the optional *inheritable* parameter.
+
 
 .. function:: fchmod(fd, mode)
 
@@ -848,6 +861,7 @@ as internal buffering of data.
    Open the file *file* and set various flags according to *flags* and possibly
    its mode according to *mode*.  When computing *mode*, the current umask value
    is first masked out.  Return the file descriptor for the newly opened file.
+   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
 
    For a description of the flag and mode values, see the C run-time documentation;
    flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
@@ -859,6 +873,9 @@ as internal buffering of data.
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.4
+      The new file descriptor is now non-inheritable.
+
    .. note::
 
       This function is intended for low-level I/O.  For normal usage, use the
@@ -933,20 +950,28 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
 
    .. index:: module: pty
 
-   Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
-   slave)`` for the pty and the tty, respectively. For a (slightly) more portable
-   approach, use the :mod:`pty` module.
+   Open a new pseudo-terminal pair. Return a pair of file descriptors
+   ``(master, slave)`` for the pty and the tty, respectively. The new file
+   descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
+   portable approach, use the :mod:`pty` module.
 
    Availability: some flavors of Unix.
 
+   .. versionchanged:: 3.4
+      The new file descriptors are now non-inheritable.
+
 
 .. function:: pipe()
 
-   Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for reading
-   and writing, respectively.
+   Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for
+   reading and writing, respectively. The new file descriptor are
+   :ref:`non-inheritable <fd_inheritance>`.
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.4
+      The new file descriptors are now non-inheritable.
+
 
 .. function:: pipe2(flags)
 
@@ -1178,6 +1203,50 @@ Querying the size of a terminal
       Height of the terminal window in characters.
 
 
+.. _fd_inheritance:
+
+Inheritance of File Descriptors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A file descriptor has a inheritable flag which indicates if the file descriptor
+can be inherited or not in child processes. Since Python 3.4, file descriptors
+created by Python are non-inheritable by default.
+
+On UNIX, non-inheritable file descriptors are closed in child processes at the
+execution of a new program, other file descriptors are inherited.
+
+On Windows, non-inheritable handles and file descriptors are closed in child
+processes, except standard streams (file descriptors 0, 1 and 2: stdin, stdout
+and stderr) which are always inherited. Using :func:`os.spawn*` functions,
+all inheritable handles and all inheritable file descriptors are inherited.
+Using the :mod:`subprocess` module, all file descriptors except standard
+streams are closed, inheritable handles are only inherited if the *close_fds*
+parameter is ``False``.
+
+.. versionadded:: 3.4
+
+.. function:: get_inheritable(fd)
+
+   Get the `inheritable flag <fd_inheritance>`_ of the specified file
+   descriptor. Return a :class:`bool`.
+
+.. function:: set_inheritable(fd, inheritable)
+
+   Set the `inheritable flag <fd_inheritance>`_ of the specified file descriptor.
+
+.. function:: get_handle_inheritable(handle)
+
+   Get the `inheritable flag <fd_inheritance>`_ of the specified handle. Return a :class:`bool`.
+
+   Availability: Windows.
+
+.. function:: set_handle_inheritable(handle, inheritable)
+
+   Set the `inheritable flag <fd_inheritance>`_ of the specified handle.
+
+   Availability: Windows.
+
+
 .. _os-file-dir:
 
 Files and Directories
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 2b5225d..02ce775 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -37,8 +37,13 @@ The module defines the following:
    increases this value, :c:func:`devpoll` may return an
    incomplete list of active file descriptors.
 
+   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
+
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.4
+      The new file descriptor is now non-inheritable.
+
 .. function:: epoll(sizehint=-1, flags=0)
 
    (Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
@@ -49,11 +54,14 @@ The module defines the following:
    :ref:`epoll-objects` below for the methods supported by epolling objects.
    They also support the :keyword:`with` statement.
 
+   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
+
    .. versionchanged:: 3.3
       Added the *flags* parameter.
 
    .. versionchanged:: 3.4
       Support for the :keyword:`with` statement was added.
+      The new file descriptor is now non-inheritable.
 
 
 .. function:: poll()
@@ -69,6 +77,11 @@ The module defines the following:
    (Only supported on BSD.)  Returns a kernel queue object; see section
    :ref:`kqueue-objects` below for the methods supported by kqueue objects.
 
+   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
+
+   .. versionchanged:: 3.4
+      The new file descriptor is now non-inheritable.
+
 
 .. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index edd196a..d666ace 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -460,7 +460,7 @@ The module :mod:`socket` exports the following constants and functions:
    ``'udp'``, otherwise any protocol will match.
 
 
-.. function:: socket([family[, type[, proto]]])
+.. function:: socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
 
    Create a new socket using the given address family, socket type and protocol
    number.  The address family should be :const:`AF_INET` (the default),
@@ -471,12 +471,18 @@ The module :mod:`socket` exports the following constants and functions:
    case where the address family is :const:`AF_CAN` the protocol should be one
    of :const:`CAN_RAW` or :const:`CAN_BCM`.
 
+   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
+
    .. versionchanged:: 3.3
       The AF_CAN family was added.
       The AF_RDS family was added.
 
-  .. versionchanged:: 3.4
-      The CAN_BCM protocol was added.
+   .. versionchanged:: 3.4
+       The CAN_BCM protocol was added.
+
+   .. versionchanged:: 3.4
+      The socket is now non-inheritable.
+
 
 .. function:: socketpair([family[, type[, proto]]])
 
@@ -486,12 +492,17 @@ The module :mod:`socket` exports the following constants and functions:
    if defined on the platform; otherwise, the default is :const:`AF_INET`.
    Availability: Unix.
 
+   The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
+
    .. versionchanged:: 3.2
       The returned socket objects now support the whole socket API, rather
       than a subset.
 
+   .. versionchanged:: 3.4
+      The sockets are now non-inheritable.
+
 
-.. function:: fromfd(fd, family, type[, proto])
+.. function:: fromfd(fd, family, type, proto=0)
 
    Duplicate the file descriptor *fd* (an integer as returned by a file object's
    :meth:`fileno` method) and build a socket object from the result.  Address
@@ -502,6 +513,11 @@ The module :mod:`socket` exports the following constants and functions:
    a socket passed to a program as standard input or output (such as a server
    started by the Unix inet daemon).  The socket is assumed to be in blocking mode.
 
+   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
+
+   .. versionchanged:: 3.4
+      The socket is now non-inheritable.
+
 
 .. function:: ntohl(x)
 
@@ -730,6 +746,11 @@ correspond to Unix system calls applicable to sockets.
    *new* socket object usable to send and receive data on the connection, and
    *address* is the address bound to the socket on the other end of the connection.
 
+   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
+
+   .. versionchanged:: 3.4
+      The socket is now non-inheritable.
+
 
 .. method:: socket.bind(address)
 
@@ -775,6 +796,16 @@ correspond to Unix system calls applicable to sockets.
    .. versionadded:: 3.2
 
 
+.. method:: socket.dup()
+
+   Duplicate the socket.
+
+   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
+
+   .. versionchanged:: 3.4
+      The socket is now non-inheritable.
+
+
 .. method:: socket.fileno()
 
    Return the socket's file descriptor (a small integer).  This is useful with
@@ -785,6 +816,15 @@ correspond to Unix system calls applicable to sockets.
    this limitation.
 
 
+.. method:: socket.get_inheritable()
+
+   Get the :ref:`inheritable flag <fd_inheritance>` of the socket's file
+   descriptor or socket's handle: ``True`` if the socket can be inherited in
+   child processes, ``False`` if it cannot.
+
+   .. versionadded:: 3.4
+
+
 .. method:: socket.getpeername()
 
    Return the remote address to which the socket is connected.  This is useful to
@@ -1068,6 +1108,14 @@ correspond to Unix system calls applicable to sockets.
    .. versionadded:: 3.3
 
 
+.. method:: socket.set_inheritable(inheritable)
+
+   Set the :ref:`inheritable flag <fd_inheritance>` of the socket's file
+   descriptor or socket's handle.
+
+   .. versionadded:: 3.4
+
+
 .. method:: socket.setblocking(flag)
 
    Set blocking or non-blocking mode of the socket: if *flag* is false, the
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index d56b422..41b161c 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -96,6 +96,7 @@ New built-in features:
 
 * :ref:`PEP 442: Safe object finalization <pep-442>`.
 * :ref:`PEP 445: Configurable memory allocators <pep-445>`.
+* :ref:`PEP 446: Make newly created file descriptors non-inheritable <pep-446>`.
 
 Implementation improvements:
 
@@ -118,6 +119,19 @@ Security improvements:
 
 Please read on for a comprehensive list of user-facing changes.
 
+.. _pep-446:
+
+PEP 446: Make newly created file descriptors non-inheritable
+============================================================
+
+The :pep:`446` makes newly created file descriptors `non-inheritable
+<fd_inheritance>`_. New functions and methods:
+
+* :func:`os.get_inheritable`, :func:`os.set_inheritable`
+* :func:`os.get_handle_inheritable`, :func:`os.set_handle_inheritable`
+* :meth:`socket.socket.get_inheritable`, :meth:`socket.socket.set_inheritable`
+
+
 .. _pep-445:
 
 PEP 445: Add new APIs to customize Python memory allocators
@@ -267,6 +281,16 @@ Also, except when using the old *fork* start method, child processes
 will no longer inherit unneeded handles/file descriptors from their parents.
 
 
+os
+--
+
+New functions to get and set the `inheritable flag <fd_inheritance>`_ of a file
+descriptors or a Windows handle:
+
+* :func:`os.get_inheritable`, :func:`os.set_inheritable`
+* :func:`os.get_handle_inheritable`, :func:`os.set_handle_inheritable`
+
+
 poplib
 ------
 
@@ -288,6 +312,15 @@ try/except statement by code that only cares whether or not an error occurred.
 (:issue:`2118`).
 
 
+socket
+------
+
+Socket objects have new methods to get or set their `inheritable flag
+<fd_inheritance>`_:
+
+* :meth:`socket.socket.get_inheritable`, :meth:`socket.socket.set_inheritable`
+
+
 ssl
 ---