bpo-38816: Add notes in the C-API docs about fork in subinterpreters. (GH-17176)

The C-API docs are a bit sparse on the interplay between C `fork()` and the CPython runtime.  This change adds some more information on the subject.

https://bugs.python.org/issue38816
(cherry picked from commit 73cdb0c6b2c3861e034004cdc57be5e726876078)

Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 212f4d1..d3bbee2 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -33,6 +33,12 @@ Operating System Utilities
    that clones the current process.
    Only available on systems where :c:func:`fork` is defined.
 
+   .. warning::
+      The C :c:func:`fork` call should only be made from the
+      :ref:`"main" thread <fork-and-threads>` (of the
+      :ref:`"main" interpreter <sub-interpreter-support>`).  The same is
+      true for ``PyOS_BeforeFork()``.
+
    .. versionadded:: 3.7
 
 
@@ -44,6 +50,12 @@ Operating System Utilities
    of whether process cloning was successful.
    Only available on systems where :c:func:`fork` is defined.
 
+   .. warning::
+      The C :c:func:`fork` call should only be made from the
+      :ref:`"main" thread <fork-and-threads>` (of the
+      :ref:`"main" interpreter <sub-interpreter-support>`).  The same is
+      true for ``PyOS_AfterFork_Parent()``.
+
    .. versionadded:: 3.7
 
 
@@ -55,6 +67,12 @@ Operating System Utilities
    any chance the process will call back into the Python interpreter.
    Only available on systems where :c:func:`fork` is defined.
 
+   .. warning::
+      The C :c:func:`fork` call should only be made from the
+      :ref:`"main" thread <fork-and-threads>` (of the
+      :ref:`"main" interpreter <sub-interpreter-support>`).  The same is
+      true for ``PyOS_AfterFork_Child()``.
+
    .. versionadded:: 3.7
 
    .. seealso::