The list and table have been merged into a single annotated table for conciseness and readability

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@252766 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind 2008-02-12 14:35:12 +00:00
parent 5fd4ab47ee
commit 7e7617eb07

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<sect1 xml:id="internals2.structure.modstruct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>The zend_module structure</title>
<para>
@ -103,190 +103,24 @@ struct _zend_module_entry {
globals.
</para>
<variablelist>
<note>
<para>
Fields which are not intended for developers to use are marked by an
asterisk (*).
</para>
</note>
<varlistentry>
<term><literal>size</literal> *</term>
<listitem>
<para>
The size in bytes of the structure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>zend_api</literal></term>
<listitem>
<para>
The version of the Zend API this module was compiled against.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>zend_debug</literal></term>
<term><literal>zts</literal></term>
<listitem>
<para>
Flags indicating whether the module was compiled with debugging turned on
and/or ZTS (TSRM) enabled.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ini_entry</literal></term>
<listitem>
<para>
This pointer is used internally by Zend to keep a non-local reference to
any INI entries declared for the module.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>deps</literal></term>
<listitem>
<para>
A pointer to a list of dependencies for the module.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>name</literal></term>
<listitem>
<para>
The name of the module. This is the short name, such as
&quot;spl&quot; or &quot;standard&quot;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>functions</literal></term>
<listitem>
<para>
A pointer to the module's function table, which Zend uses to expose
functions in the module to user space.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>module_startup_func</literal></term>
<term><literal>module_shutdown_func</literal></term>
<term><literal>request_startup_func</literal></term>
<term><literal>request_shutdown_func</literal></term>
<listitem>
<para>
These are callback functions that Zend will call at particular times
during PHP's processing. Specifically, at first initialization, at final
shutdown, at the start of each particular request, and at the end of each
request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>info_func</literal></term>
<listitem>
<para>
This is another callback function, which Zend will call when a script
invokes <function>phpinfo</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>version</literal></term>
<listitem>
<para>
A string giving the version of the module, as specified by the module
developer. It is <emphasis>strongly</emphasis> recommended that the
version number be either in the format expected by
<function>version_compare</function>, or a CVS or SVN revision number
(i.e. &quot;$Rev$&quot;).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>globals_size</literal> (*)</term>
<listitem>
<para>
The size of the data structure containing the module's globals, if any.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>globals_id_ptr</literal> (*)</term>
<term><literal>globals_ptr</literal> (*)</term>
<listitem>
<para>
Only one of these two fields will exist, depending upon whether the
<constant>USING_ZTS</constant> constant is &true;. The former is an index
into TSRM&apos;s allocation table for the module&apos;s globals, and the
latter is a pointer directly to the globals.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>globals_ctor</literal></term>
<term><literal>globals_dtor</literal></term>
<listitem>
<para>
These functions are called by Zend to set up and destroy a module&apos;s
globals.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>post_deactivate_func</literal></term>
<listitem>
<para>
This function is called by Zend after request shutdown. It is rarely used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>module_started</literal> (*)</term>
<term><literal>type</literal> (*)</term>
<term><literal>handle</literal> (*)</term>
<term><literal>module_number</literal> (*)</term>
<listitem>
<para>
These fields are used for Zend's internal tracking information.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
This table gives the values that each field would have if the developer
were to fill in the structure entirely by hand, without recourse to any of
the shortcut macros. <emphasis>This is not recommended.</emphasis> The
&quot;correct&quot; values for many fields may change. Use the macros
whenever possible.
</para>
<note>
<para>
This table gives the values that each field would have if the developer
were to fill in the structure entirely by hand, without recourse to any of
the shortcut macros. <emphasis>This is not recommended.</emphasis> The
&quot;correct&quot; values for many fields may change. Use the macros
whenever possible.
</para>
</note>
<table xml:id="internals2.structure.modstruct.struct-values">
<title>Module structure field values</title>
<tgroup cols="2">
<tgroup cols="3">
<thead>
<row>
<entry>Field</entry><entry>Value</entry>
<entry>Field</entry>
<entry>Value</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
@ -294,23 +128,331 @@ struct _zend_module_entry {
<row>
<entry>
<varname>size</varname>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMHC">
<footnote xml:id="internals2.structure.modstruct.struct-values.not-for-dev">
<para>
This field is not intended for use by module developers.
</para>
</footnote>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMHE">
<para>
This field is filled in by <constant>STANDARD_MODULE_HEADER_EX</constant>.
</para>
</footnote>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMH">
<para>
This field is filled in by <constant>STANDARD_MODULE_HEADER</constant>.
</para>
</footnote>
</entry>
<entry><code>sizeof(zend_module_entry)</code></entry>
<entry>
The size in bytes of the structure.
</entry>
</row>
<row>
<entry>
<varname>zend_api</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHC"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
</entry>
<entry><constant>ZEND_MODULE_API_NO</constant></entry>
<entry>
The version of the Zend API this module was compiled against.
</entry>
</row>
<row>
<entry>
<varname>zend_debug</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
</entry>
<entry><constant>ZEND_DEBUG</constant></entry>
<entry>
A flag indicating whether the module was compiled with debugging turned
on.
</entry>
</row>
<row>
<entry>
<varname>zts</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
</entry>
<entry><constant>USING_ZTS</constant></entry>
<entry>
A flag indicating whether the module was compiled with ZTS (TSRM) enabled
(see <xref linkend="internals2.memory"/>).
</entry>
</row>
<row>
<entry>
<varname>ini_entry</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
</entry>
<entry>&null;</entry>
<entry>
This pointer is used internally by Zend to keep a non-local reference to
any INI entries declared for the module.
</entry>
</row>
<row>
<entry>
<varname>deps</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
</entry>
<entry>&null;</entry>
<entry>
A pointer to a list of dependencies for the module.
</entry>
</row>
<row>
<entry>
<varname>name</varname>
</entry>
<entry>&quot;mymodule&quot;</entry>
<entry>
The name of the module. This is the short name, such as &quot;spl&quot;
or &quot;standard&quot;.
</entry>
</row>
<row>
<entry>
<varname>functions</varname>
</entry>
<entry>mymodule_functions</entry>
<entry>
A pointer to the module's function table, which Zend uses to expose
functions in the module to user space.
</entry>
</row>
<row>
<entry>
<varname>module_startup_func</varname>
</entry>
<entry>PHP_MINIT(mymodule)</entry>
<entry>
A callback function that Zend will call the first time a module is loaded
into a particular instance of PHP.
</entry>
</row>
<row>
<entry>
<varname>module_shutdown_func</varname>
</entry>
<entry>PHP_MSHUTDOWN(mymodule)</entry>
<entry>
A callback function that Zend will call the when a module is unloaded
from a particular instance of PHP, typically during final shutdown.
</entry>
</row>
<row>
<entry>
<varname>request_startup_func</varname>
</entry>
<entry>PHP_RINIT(mymodule)</entry>
<entry>
A callback function that Zend will call at the beginning of each request.
</entry>
</row>
<row>
<entry>
<varname>request_shutdown_func</varname>
</entry>
<entry>PHP_RSHUTDOWN(mymodule)</entry>
<entry>
A callback function that Zend will call at the end of each request.
</entry>
</row>
<row>
<entry>
<varname>info_func</varname>
</entry>
<entry>PHP_MINFO(mymodule)</entry>
<entry>
A callback function that Zend will call when the <function>phpinfo</function>
function is called.
</entry>
</row>
<row>
<entry>
<varname>version</varname>
</entry>
<entry><constant>NO_VERSION_YET</constant></entry>
<entry>
A string giving the version of the module, as specified by the module
developer. It is recommended that the version number be either in the
format expected by version_compare() (e.g. &quot;1.0.5-dev&quot;), or a
CVS or SVN revision number (e.g. &quot;$Rev$&quot;).
</entry>
</row>
<row>
<entry>
<varname>globals_size</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMP">
<para>
This field is filled in by <constant>STANDARD_MODULE_PROPERTIES</constant>.
</para>
</footnote>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-NMG">
<para>
This field is filled in by <constant>NO_MODULE_GLOBALS</constant>.
</para>
</footnote>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-PMG">
<para>
This field is filled in by <constant>PHP_MODULE_GLOBALS</constant>.
</para>
</footnote>
</entry>
<entry>sizeof(zend_mymodule_globals)</entry>
<entry>
The size of the data structure containing the module's globals, if any.
</entry>
</row>
<row>
<entry>
<varname>globals_id_ptr</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
<footnote xml:id="internals2.structure.modstruct.struct-values.only-with-ZTS">
<para>
This field only exists when <constant>USING_ZTS</constant> is &true;.
</para>
</footnote>
</entry>
<entry>&amp;mymodule_globals_id</entry>
<entry morerows="1">
Only one of these two fields will exist, depending upon whether the
<constant>USING_ZTS</constant> constant is &true;. The former is an index
into TSRM's allocation table for the module's globals, and the latter is
a pointer directly to the globals.
</entry>
</row>
<row>
<entry>
<varname>globals_ptr</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
<footnote xml:id="internals2.structure.modstruct.struct-values.only-without-ZTS">
<para>
This field only exists when <constant>USING_ZTS</constant> is &false;.
</para>
</footnote>
</entry>
<entry>&amp;mymodule_globals</entry>
</row>
<row>
<entry>
<varname>globals_ctor</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
</entry>
<entry>PHP_GINIT(mymodule)</entry>
<entry>
This funtion is called to initialize a module's globals <emphasis>before</emphasis>
any <varname>module_startup_func</varname>.
</entry>
</row>
<row>
<entry>
<varname>globals_dtor</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
</entry>
<entry>PHP_GSHUTDOWN(mymodule)</entry>
<entry>
This funtion is called to deallocate a module's globals <emphasis>after</emphasis>
any <varname>module_shutdown_func</varname>.
</entry>
</row>
<row>
<entry>
<varname>post_deactivate_func</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
</entry>
<entry>ZEND_MODULE_POST_ZEND_DEACTIVATE_N(mymodule)</entry>
<entry>
This function is called by Zend after request shutdown. It is rarely used.
</entry>
</row>
<row>
<entry>
<varname>module_started</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMPE">
<para>
This field is filled in by <constant>STANDARD_MODULE_PROPERTIES_EX</constant>.
</para>
</footnote>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
</entry>
<entry>0</entry>
<entry morerows="3">
These fields are used for Zend's internal tracking information.
</entry>
</row>
<row>
<entry>
<varname>type</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
</entry>
<entry>0</entry>
</row>
<row>
<entry>
<varname>handle</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
</entry>
<entry>&null;</entry>
</row>
<row>
<entry>
<varname>module_number</varname>
<footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
</entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</table>