[3.15] gh-141004: Document Py_FrozenMain (GH-159724) (GH-159922)

(cherry picked from commit 6f439ee)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

Author: miss-islington

Doc/c-api/interp-lifecycle.rst

@@ -536,6 +536,48 @@ Initializing and finalizing the interpreter
    first initialized).
 
 
+.. c:function:: int Py_FrozenMain(int argc, char **argv)
+
+   .. index:: single: freeze utility
+
+   The main program for a "frozen" Python program (an executable that embeds
+   the interpreter together with the bytecode of the program's modules, as
+   produced by the :program:`freeze` utility; see :source:`Tools/freeze`).
+
+   This function initializes the interpreter, imports the frozen module named
+   ``__main__``, and finalizes the interpreter.
+   The frozen modules must have been registered in
+   :c:var:`PyImport_FrozenModules` before calling this function;
+   it is a fatal error if ``__main__`` is not among them.
+
+   *argc* and *argv* are byte strings like the arguments of a C program's
+   ``main`` function, and are passed to the interpreter with
+   :c:func:`PyConfig_SetBytesArgv`.
+   Unlike :c:func:`Py_Main`, the arguments are not parsed as Python command
+   line options (:c:member:`PyConfig.parse_argv` is ``0``), so all of them
+   are made available to the program in :data:`sys.argv`.
+   Apart from that, the interpreter uses the
+   :ref:`Python Configuration <init-python-config>`, so environment variables
+   such as :envvar:`PYTHONPATH` are honored.
+   Warnings about the path configuration
+   (:c:member:`PyConfig.pathconfig_warnings`) are suppressed.
+   If :envvar:`PYTHONINSPECT` is set and standard input is a terminal, an
+   interactive prompt is run after ``__main__`` has finished, as with the
+   :option:`-i` option.
+
+   Return ``0`` if ``__main__`` ran without an unhandled exception, ``1``
+   otherwise, and ``120`` if finalizing the interpreter failed (see
+   :c:func:`Py_FinalizeEx`).
+   An unhandled :exc:`SystemExit` terminates the process.
+   If the interpreter cannot be initialized, the process exits via
+   :c:func:`Py_ExitStatusException`.
+
+   On Windows, this function is not exported by the Python DLL.
+   The :program:`freeze` utility compiles :file:`Python/frozenmain.c` into the
+   frozen program instead, together with the Windows-specific hooks that the
+   function requires.
+
+
 .. c:function:: int Py_RunMain(void)
 
    Executes the main module in a fully configured CPython runtime.

Tools/check-c-api-docs/ignored_c_api.txt

@@ -32,8 +32,6 @@ PyCFunction_GET_CLASS
 PyDescr_NAME
 PyDescr_TYPE
 PyWrapperFlag_KEYWORDS
-# cpython/pylifecycle.h
-Py_FrozenMain
 # cpython/objimpl.h
 PyObject_GET_WEAKREFS_LISTPTR
 # cpython/pythonrun.h