diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/functions.rst | 11 | ||||
| -rw-r--r-- | Doc/library/io.rst | 5 | ||||
| -rw-r--r-- | Doc/library/os.rst | 83 | ||||
| -rw-r--r-- | Doc/library/select.rst | 13 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 56 | ||||
| -rw-r--r-- | Doc/whatsnew/3.4.rst | 33 |
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 --- |