[3.11] gh-105912: document gotcha with using os.fork on macOS (GH-112871) (#113135)

* gh-105912: document gotcha with using os.fork on macOS

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.

(cherry picked from commit 22511f77c2818a138a252e6ddae89725d082f8b0)

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 4c1d20b9b45d2966ddff752ce79930fee47056b8..f5010a27ddcd6d5ea15e5ce3d320d393e77b1ad4 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -3928,6 +3928,11 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.fork "" os.fork
 
+   .. 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).
@@ -3949,6 +3954,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.8
       Calling ``forkpty()`` in a subinterpreter is no longer supported
       (:exc:`RuntimeError` is raised).

diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst
index af9378464edb9f69166926f57a7febd405672bcf..bd2f5ed45cb8b48e1360f8c3a9685277de74d527 100644 (file)
--- a/Doc/library/pty.rst
+++ b/Doc/library/pty.rst
@@ -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()
 

diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 690f01c93a1ee7376aab4617812c15fc7f9f72c6..f55b6813d1e5bc1aa5a9290396bd15609efac02d 100644 (file)
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -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 environment 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: