Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit daf4555

Browse files
vstinnervstinner
committed
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().
1 parent 46e1ce2 commit daf4555

51 files changed

Lines changed: 1448 additions & 317 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/library/functions.rst‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -979,6 +979,8 @@ are always available. They are listed here in alphabetical order.
979979
:mod:`os.open` as *opener* results in functionality similar to passing
980980
``None``).
981981

982+
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
983+
982984
The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
983985
:func:`os.open` function to open a file relative to a given directory::
984986

@@ -992,10 +994,6 @@ are always available. They are listed here in alphabetical order.
992994
...
993995
>>> os.close(dir_fd) # don't leak a file descriptor
994996

995-
.. versionchanged:: 3.3
996-
The *opener* parameter was added.
997-
The ``'x'`` mode was added.
998-
999997
The type of :term:`file object` returned by the :func:`open` function
1000998
depends on the mode. When :func:`open` is used to open a file in a text
1001999
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.
10221020
and :mod:`shutil`.
10231021

10241022
.. versionchanged:: 3.3
1023+
The *opener* parameter was added.
1024+
The ``'x'`` mode was added.
10251025
:exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
10261026
:exc:`FileExistsError` is now raised if the file opened in exclusive
10271027
creation mode (``'x'``) already exists.
10281028

1029+
.. versionchanged:: 3.4
1030+
The file is now non-inheritable.
1031+
10291032

10301033
.. XXX works for bytes too, but should it?
10311034
.. function:: ord(c)

‎Doc/library/io.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -522,13 +522,18 @@ Raw File I/O
522522
:mod:`os.open` as *opener* results in functionality similar to passing
523523
``None``).
524524

525+
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
526+
525527
See the :func:`open` built-in function for examples on using the *opener*
526528
parameter.
527529

528530
.. versionchanged:: 3.3
529531
The *opener* parameter was added.
530532
The ``'x'`` mode was added.
531533

534+
.. versionchanged:: 3.4
535+
The file is now non-inheritable.
536+
532537
In addition to the attributes and methods from :class:`IOBase` and
533538
:class:`RawIOBase`, :class:`FileIO` provides the following data
534539
attributes:

‎Doc/library/os.rst‎

Lines changed: 76 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -685,17 +685,30 @@ as internal buffering of data.
685685

686686
.. function:: dup(fd)
687687

688-
Return a duplicate of file descriptor *fd*.
688+
Return a duplicate of file descriptor *fd*. The new file descriptor is
689+
:ref:`non-inheritable <fd_inheritance>`.
690+
691+
On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
692+
2: stderr), the new file descriptor is :ref:`inheritable
693+
<fd_inheritance>`.
689694

690695
Availability: Unix, Windows.
691696

697+
.. versionchanged:: 3.4
698+
The new file descriptor is now non-inheritable.
699+
692700

693-
.. function:: dup2(fd, fd2)
701+
.. function:: dup2(fd, fd2, inheritable=True)
694702

695703
Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
704+
The file descriptor *fd2* is :ref:`inheritable <fd_inheritance>` by default,
705+
or non-inheritable if *inheritable* is ``False``.
696706

697707
Availability: Unix, Windows.
698708

709+
.. versionchanged:: 3.4
710+
Add the optional *inheritable* parameter.
711+
699712

700713
.. function:: fchmod(fd, mode)
701714

@@ -848,6 +861,7 @@ as internal buffering of data.
848861
Open the file *file* and set various flags according to *flags* and possibly
849862
its mode according to *mode*. When computing *mode*, the current umask value
850863
is first masked out. Return the file descriptor for the newly opened file.
864+
The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
851865

852866
For a description of the flag and mode values, see the C run-time documentation;
853867
flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
@@ -859,6 +873,9 @@ as internal buffering of data.
859873

860874
Availability: Unix, Windows.
861875

876+
.. versionchanged:: 3.4
877+
The new file descriptor is now non-inheritable.
878+
862879
.. note::
863880

864881
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
933950

934951
.. index:: module: pty
935952

936-
Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
937-
slave)`` for the pty and the tty, respectively. For a (slightly) more portable
938-
approach, use the :mod:`pty` module.
953+
Open a new pseudo-terminal pair. Return a pair of file descriptors
954+
``(master, slave)`` for the pty and the tty, respectively. The new file
955+
descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
956+
portable approach, use the :mod:`pty` module.
939957

940958
Availability: some flavors of Unix.
941959

960+
.. versionchanged:: 3.4
961+
The new file descriptors are now non-inheritable.
962+
942963

943964
.. function:: pipe()
944965

945-
Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
946-
and writing, respectively.
966+
Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for
967+
reading and writing, respectively. The new file descriptor are
968+
:ref:`non-inheritable <fd_inheritance>`.
947969

948970
Availability: Unix, Windows.
949971

972+
.. versionchanged:: 3.4
973+
The new file descriptors are now non-inheritable.
974+
950975

951976
.. function:: pipe2(flags)
952977

@@ -1178,6 +1203,50 @@ Querying the size of a terminal
11781203
Height of the terminal window in characters.
11791204

11801205

1206+
.. _fd_inheritance:
1207+
1208+
Inheritance of File Descriptors
1209+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1210+
1211+
A file descriptor has a inheritable flag which indicates if the file descriptor
1212+
can be inherited or not in child processes. Since Python 3.4, file descriptors
1213+
created by Python are non-inheritable by default.
1214+
1215+
On UNIX, non-inheritable file descriptors are closed in child processes at the
1216+
execution of a new program, other file descriptors are inherited.
1217+
1218+
On Windows, non-inheritable handles and file descriptors are closed in child
1219+
processes, except standard streams (file descriptors 0, 1 and 2: stdin, stdout
1220+
and stderr) which are always inherited. Using :func:`os.spawn*` functions,
1221+
all inheritable handles and all inheritable file descriptors are inherited.
1222+
Using the :mod:`subprocess` module, all file descriptors except standard
1223+
streams are closed, inheritable handles are only inherited if the *close_fds*
1224+
parameter is ``False``.
1225+
1226+
.. versionadded:: 3.4
1227+
1228+
.. function:: get_inheritable(fd)
1229+
1230+
Get the `inheritable flag <fd_inheritance>`_ of the specified file
1231+
descriptor. Return a :class:`bool`.
1232+
1233+
.. function:: set_inheritable(fd, inheritable)
1234+
1235+
Set the `inheritable flag <fd_inheritance>`_ of the specified file descriptor.
1236+
1237+
.. function:: get_handle_inheritable(handle)
1238+
1239+
Get the `inheritable flag <fd_inheritance>`_ of the specified handle. Return a :class:`bool`.
1240+
1241+
Availability: Windows.
1242+
1243+
.. function:: set_handle_inheritable(handle, inheritable)
1244+
1245+
Set the `inheritable flag <fd_inheritance>`_ of the specified handle.
1246+
1247+
Availability: Windows.
1248+
1249+
11811250
.. _os-file-dir:
11821251

11831252
Files and Directories

‎Doc/library/select.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,13 @@ The module defines the following:
3737
increases this value, :c:func:`devpoll` may return an
3838
incomplete list of active file descriptors.
3939

40+
The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
41+
4042
.. versionadded:: 3.3
4143

44+
.. versionchanged:: 3.4
45+
The new file descriptor is now non-inheritable.
46+
4247
.. function:: epoll(sizehint=-1, flags=0)
4348

4449
(Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
@@ -49,11 +54,14 @@ The module defines the following:
4954
:ref:`epoll-objects` below for the methods supported by epolling objects.
5055
They also support the :keyword:`with` statement.
5156

57+
The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
58+
5259
.. versionchanged:: 3.3
5360
Added the *flags* parameter.
5461

5562
.. versionchanged:: 3.4
5663
Support for the :keyword:`with` statement was added.
64+
The new file descriptor is now non-inheritable.
5765

5866

5967
.. function:: poll()
@@ -69,6 +77,11 @@ The module defines the following:
6977
(Only supported on BSD.) Returns a kernel queue object; see section
7078
:ref:`kqueue-objects` below for the methods supported by kqueue objects.
7179

80+
The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
81+
82+
.. versionchanged:: 3.4
83+
The new file descriptor is now non-inheritable.
84+
7285

7386
.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
7487

‎Doc/library/socket.rst‎

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -460,7 +460,7 @@ The module :mod:`socket` exports the following constants and functions:
460460
``'udp'``, otherwise any protocol will match.
461461

462462

463-
.. function:: socket([family[, type[, proto]]])
463+
.. function:: socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
464464

465465
Create a new socket using the given address family, socket type and protocol
466466
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:
471471
case where the address family is :const:`AF_CAN` the protocol should be one
472472
of :const:`CAN_RAW` or :const:`CAN_BCM`.
473473

474+
The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
475+
474476
.. versionchanged:: 3.3
475477
The AF_CAN family was added.
476478
The AF_RDS family was added.
477479

478-
.. versionchanged:: 3.4
479-
The CAN_BCM protocol was added.
480+
.. versionchanged:: 3.4
481+
The CAN_BCM protocol was added.
482+
483+
.. versionchanged:: 3.4
484+
The socket is now non-inheritable.
485+
480486

481487
.. function:: socketpair([family[, type[, proto]]])
482488

@@ -486,12 +492,17 @@ The module :mod:`socket` exports the following constants and functions:
486492
if defined on the platform; otherwise, the default is :const:`AF_INET`.
487493
Availability: Unix.
488494

495+
The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
496+
489497
.. versionchanged:: 3.2
490498
The returned socket objects now support the whole socket API, rather
491499
than a subset.
492500

501+
.. versionchanged:: 3.4
502+
The sockets are now non-inheritable.
503+
493504

494-
.. function:: fromfd(fd, family, type[, proto])
505+
.. function:: fromfd(fd, family, type, proto=0)
495506

496507
Duplicate the file descriptor *fd* (an integer as returned by a file object's
497508
: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:
502513
a socket passed to a program as standard input or output (such as a server
503514
started by the Unix inet daemon). The socket is assumed to be in blocking mode.
504515

516+
The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
517+
518+
.. versionchanged:: 3.4
519+
The socket is now non-inheritable.
520+
505521

506522
.. function:: ntohl(x)
507523

@@ -730,6 +746,11 @@ correspond to Unix system calls applicable to sockets.
730746
*new* socket object usable to send and receive data on the connection, and
731747
*address* is the address bound to the socket on the other end of the connection.
732748

749+
The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
750+
751+
.. versionchanged:: 3.4
752+
The socket is now non-inheritable.
753+
733754

734755
.. method:: socket.bind(address)
735756

@@ -775,6 +796,16 @@ correspond to Unix system calls applicable to sockets.
775796
.. versionadded:: 3.2
776797

777798

799+
.. method:: socket.dup()
800+
801+
Duplicate the socket.
802+
803+
The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
804+
805+
.. versionchanged:: 3.4
806+
The socket is now non-inheritable.
807+
808+
778809
.. method:: socket.fileno()
779810

780811
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.
785816
this limitation.
786817

787818

819+
.. method:: socket.get_inheritable()
820+
821+
Get the :ref:`inheritable flag <fd_inheritance>` of the socket's file
822+
descriptor or socket's handle: ``True`` if the socket can be inherited in
823+
child processes, ``False`` if it cannot.
824+
825+
.. versionadded:: 3.4
826+
827+
788828
.. method:: socket.getpeername()
789829

790830
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.
10681108
.. versionadded:: 3.3
10691109

10701110

1111+
.. method:: socket.set_inheritable(inheritable)
1112+
1113+
Set the :ref:`inheritable flag <fd_inheritance>` of the socket's file
1114+
descriptor or socket's handle.
1115+
1116+
.. versionadded:: 3.4
1117+
1118+
10711119
.. method:: socket.setblocking(flag)
10721120

10731121
Set blocking or non-blocking mode of the socket: if *flag* is false, the

0 commit comments

Comments
 (0)