Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and

struct _inittab.

This closes SourceForge bug #111499.

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index c8731c97e930d89eb07fd2f3785af6f8c5876288..3c313c52046c466d6963479ddfaaa2184bc2fc10 100644 (file)
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -1238,7 +1238,7 @@ already imported.)
 This is the structure type definition for frozen module descriptors,
 as generated by the \program{freeze}\index{freeze utility} utility
 (see \file{Tools/freeze/} in the Python source distribution).  Its
-definition is:
+definition, found in \file{Include/import.h}, is:
 
 \begin{verbatim}
 struct _frozen {
@@ -1257,6 +1257,44 @@ this table.  Third-party code could play tricks with this to provide a
 dynamically created collection of frozen modules.
 \end{cvardesc}
 
+\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
+                                               void (*initfunc)(void)}
+Add a single module to the existing table of built-in modules.  This
+is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
+returning \code{-1} if the table could not be extended.  The new
+module can be imported by the name \var{name}, and uses the function
+\var{initfunc} as the initialization function called on the first
+attempted import.  This should be called before
+\cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_inittab]{struct _inittab}
+Structure describing a single entry in the list of built-in modules.
+Each of these structures gives the name and initialization function
+for a module built into the interpreter.  Programs which embed Python
+may use an array of these structures in conjunction with
+\cfunction{PyImport_ExtendInittab()} to provide additional built-in
+modules.  The structure is defined in \file{Include/import.h} as:
+
+\begin{verbatim}
+struct _inittab {
+    char *name;
+    void (*initfunc)(void);
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
+Add a collection of modules to the table of built-in modules.  The
+\var{newtab} array must end with a sentinel entry which contains
+\NULL{} for the \member{name} field; failure to provide the sentinel
+value can result in a memory fault.  Returns \code{0} on success or
+\code{-1} if insufficient memory could be allocated to extend the
+internal table.  In the event of failure, no modules are added to the
+internal table.  This should be called before
+\cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
 
 \chapter{Abstract Objects Layer \label{abstract}}