pythongh-105912: document gotcha with using os.fork on macOS (python#…

…112871) * pythongh-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. Co-authored-by: Carol Willing <[email protected]>
aisk · Feb 11, 2024 · d85dae2 · d85dae2
1 parent 27410fd
commit d85dae2
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 0 deletions.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -4383,6 +4383,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).
@@ -4422,6 +4427,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

diff --git 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
@@ -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: