Skip to content

Commit

Permalink
pythongh-105912: document gotcha with using os.fork on macOS
Browse files Browse the repository at this point in the history
Using ``fork(2)`` on macOS when also using higher-level
system APIs in the parent proces can crash on macOS because
those system APIs are not written to handle this usage
pattern.

There's nothing we can do about this other than documenting
the problem.
  • Loading branch information
ronaldoussoren committed Dec 8, 2023
1 parent 2d76be2 commit 9df2d1b
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 0 deletions.
10 changes: 10 additions & 0 deletions Doc/library/os.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4373,6 +4373,11 @@ written in Python, such as a mail server's external command delivery program.
If you use TLS sockets in an application calling ``fork()``, see
the warning in the :mod:`ssl` documentation.

.. warning::

On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using :mod:`urllib.request`.

.. versionchanged:: 3.8
Calling ``fork()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
Expand Down Expand Up @@ -4412,6 +4417,11 @@ written in Python, such as a mail server's external command delivery program.

.. audit-event:: os.forkpty "" os.forkpty

.. warning::

On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using :mod:`urllib.request`.

.. versionchanged:: 3.12
If Python is able to detect that your process has multiple
threads, this now raises a :exc:`DeprecationWarning`. See the
Expand Down
3 changes: 3 additions & 0 deletions Doc/library/pty.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ The :mod:`pty` module defines the following functions:
file descriptor connected to the child's controlling terminal (and also to the
child's standard input and output).

.. warning:: On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using :mod:`urllib.request`.


.. function:: openpty()

Expand Down
8 changes: 8 additions & 0 deletions Doc/library/urllib.request.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,14 @@ authentication, redirections, cookies and more.
The `Requests package <https://requests.readthedocs.io/en/master/>`_
is recommended for a higher-level HTTP client interface.

.. warning::

On macOS it is unsafe to use this module in programs using
:func:`os.fork` because the :func:`getproxies` implementation for
macOS uses a higher-level system API. Set the environement variable
``no_proxy`` to ``*`` to avoid this problem
(e.g. ``os.environ["no_proxy"] = "*"``).

.. include:: ../includes/wasm-notavail.rst

The :mod:`urllib.request` module defines the following functions:
Expand Down

0 comments on commit 9df2d1b

Please sign in to comment.