mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
updated descriptions to make a little more logical sense, started the table of expected values; NEED RENDERER UPDATE
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@252233 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind
parent
7f7735377b
commit
4573035033
1 changed files with 93 additions and 111 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1" ?>
|
||||
<!-- $Revision: 1.4 $ -->
|
||||
<!-- $Revision: 1.5 $ -->
|
||||
<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>
|
||||
|
|
@ -10,14 +10,15 @@
|
|||
about the extension's dependencies, version, callbacks, and other critical
|
||||
data. The structure has mutated considerably over time; this section will
|
||||
focus on the structure as it has appeared since PHP 5.0, and will identify
|
||||
the very few parts which have changed in PHP 5.1 and 5.2.
|
||||
the very few parts which have changed in PHP 5.1, 5.2, and 5.3.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <literal>zend_module</literal> declaration from
|
||||
<filename>example.c</filename> looks like this before any code has been
|
||||
written (the example file was generated by
|
||||
<command>ext_skel --extname=example</command>):
|
||||
written. The example file was generated by
|
||||
<command>ext_skel --extname=example</command>, with some obsolete constructs
|
||||
removed:
|
||||
</para>
|
||||
|
||||
<example xml:id="internals2.structure.modstruct.example-decl">
|
||||
|
|
@ -27,9 +28,7 @@
|
|||
/* {{{ example_module_entry
|
||||
*/
|
||||
zend_module_entry example_module_entry = {
|
||||
#if ZEND_MODULE_API_NO >= 20010901
|
||||
STANDARD_MODULE_HEADER,
|
||||
#endif
|
||||
"example",
|
||||
example_functions,
|
||||
PHP_MINIT(example),
|
||||
|
|
@ -37,9 +36,7 @@ zend_module_entry example_module_entry = {
|
|||
PHP_RINIT(example), /* Replace with NULL if there's nothing to do at request start */
|
||||
PHP_RSHUTDOWN(example), /* Replace with NULL if there's nothing to do at request end */
|
||||
PHP_MINFO(example),
|
||||
#if ZEND_MODULE_API_NO >= 20010901
|
||||
"0.1", /* Replace with version number for your extension */
|
||||
#endif
|
||||
STANDARD_MODULE_PROPERTIES
|
||||
};
|
||||
/* }}} */
|
||||
|
|
@ -50,24 +47,22 @@ zend_module_entry example_module_entry = {
|
|||
<para>
|
||||
This may look a bit daunting at first glance, but most of it is very simple
|
||||
to understand. Here's the declaration of <literal>zend_module</literal> from
|
||||
<filename>zend_modules.h</filename> in PHP 5.2, along with a few relevant
|
||||
nearby constants:
|
||||
<filename>zend_modules.h</filename> in PHP 5.3:
|
||||
</para>
|
||||
|
||||
<example xml:id="internals2.structure.modstruct.struct-defn">
|
||||
<title>zend_module definition in PHP 5.2</title>
|
||||
<title>zend_module definition in PHP 5.3</title>
|
||||
<programlisting role="c">
|
||||
<![CDATA[
|
||||
#define ZEND_MODULE_API_NO 20060613
|
||||
struct _zend_module_entry {
|
||||
unsigned short size;
|
||||
unsigned int zend_api;
|
||||
unsigned char zend_debug;
|
||||
unsigned char zts;
|
||||
struct _zend_ini_entry *ini_entry;
|
||||
struct _zend_module_dep *deps;
|
||||
char *name;
|
||||
struct _zend_function_entry *functions;
|
||||
const struct _zend_ini_entry *ini_entry;
|
||||
const struct _zend_module_dep *deps;
|
||||
const char *name;
|
||||
const struct _zend_function_entry *functions;
|
||||
int (*module_startup_func)(INIT_FUNC_ARGS);
|
||||
int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
|
||||
int (*request_startup_func)(INIT_FUNC_ARGS);
|
||||
|
|
@ -88,27 +83,39 @@ struct _zend_module_entry {
|
|||
void *handle;
|
||||
int module_number;
|
||||
};
|
||||
#define STANDARD_MODULE_HEADER_EX sizeof(zend_module_entry), ZEND_MODULE_API_NO, ZEND_DEBUG, USING_ZTS
|
||||
#define STANDARD_MODULE_HEADER \
|
||||
STANDARD_MODULE_HEADER_EX, NULL, NULL
|
||||
#define NO_VERSION_YET NULL
|
||||
|
||||
#define STANDARD_MODULE_PROPERTIES_EX 0, 0, NULL, 0
|
||||
#define STANDARD_MODULE_PROPERTIES \
|
||||
NO_MODULE_GLOBALS, NULL, STANDARD_MODULE_PROPERTIES_EX
|
||||
#define NO_MODULE_GLOBALS 0, NULL, NULL, NULL
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
|
||||
<para>
|
||||
Many of these fields will never be touched by an extension writer. There are
|
||||
a number of standard macros that set them to their proper values
|
||||
automatically. The macro <constant>STANDARD_MODULE_HEADER</constant> fills in
|
||||
everything up to the <varname>deps</varname> field. Alternatively, the
|
||||
<constant>STANDARD_MODULE_HEADER_EX</constant> will leave the
|
||||
<varname>deps</varname> field empty for the developer's use. The developer is
|
||||
always responsible for everything from <varname>name</varname> to
|
||||
<varname>version</varname>. After that, the
|
||||
<constant>STANDARD_MODULE_PROPERTIES</constant> macro will fill in the rest
|
||||
of the structure, or the <constant>STANDARD_MODULE_PROPERTIES_EX</constant>
|
||||
macro can be used to leave the extension globals and post-deactivation
|
||||
function fields unfilled. Most modern extensions will make use of module
|
||||
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>
|
||||
<term><literal>size</literal> *</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The size in bytes of the structure. This will always be to
|
||||
<literal>sizeof(zend_module_entry)</literal>.
|
||||
The size in bytes of the structure.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -117,8 +124,7 @@ struct _zend_module_entry {
|
|||
<term><literal>zend_api</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The version of the Zend API this module was compiled against. This is
|
||||
always the constant <constant>ZEND_MODULE_API_NO</constant>.
|
||||
The version of the Zend API this module was compiled against.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -129,8 +135,7 @@ struct _zend_module_entry {
|
|||
<listitem>
|
||||
<para>
|
||||
Flags indicating whether the module was compiled with debugging turned on
|
||||
or ZTS (TSRM) enabled. These are always the constants
|
||||
<constant>ZEND_DEBUG</constant> and <constant>USING_ZTS</constant>.
|
||||
and/or ZTS (TSRM) enabled.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -139,9 +144,8 @@ struct _zend_module_entry {
|
|||
<term><literal>ini_entry</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This pointer is used by Zend internally to keep a non-local reference to
|
||||
any INI entries declared for the module. It is managed by Zend and will
|
||||
always be given the initial value &null;.
|
||||
This pointer is used internally by Zend to keep a non-local reference to
|
||||
any INI entries declared for the module.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -214,17 +218,17 @@ struct _zend_module_entry {
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>globals_size</literal></term>
|
||||
<term><literal>globals_size</literal> (*)</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The size of the globals structure for this module, if any.
|
||||
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>
|
||||
<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
|
||||
|
|
@ -256,83 +260,61 @@ struct _zend_module_entry {
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>module_started</literal></term>
|
||||
<term><literal>type</literal></term>
|
||||
<term><literal>handle</literal></term>
|
||||
<term><literal>module_number</literal></term>
|
||||
<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 and must be
|
||||
considered reserved.
|
||||
These fields are used for Zend's internal tracking information.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>STANDARD_MODULE_HEADER_EX</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro is used by module developers to start the
|
||||
<varname>zend_module</varname> structure when the module will specify INI
|
||||
entries, dependencies, or both.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>STANDARD_MODULE_HEADER</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro is used to start the <varname>zend_module</varname>
|
||||
structure when the developer will not specify INI entries or dependencies.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>NO_VERSION_YET</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro should be used by module developers to specify that the module
|
||||
has no version. It is not recommended that this be used.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>STANDARD_MODULE_PROPERTIES_EX</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro is used by module developers to end the
|
||||
<varname>zend_module</varname> when the module will make use of
|
||||
automatic globals, a post-deactivate callback, or both.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>STANDARD_MODULE_PROPERTIES</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro is used by module developers to end the
|
||||
<varname>zend_module</varname> when the module will not make use of
|
||||
automatic globals or a post-deactivate callback.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>NO_MODULE_GLOBALS</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This macro is used by module developers to specify values that tell Zend
|
||||
that the module has no global variables.
|
||||
</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
|
||||
"correct" values for many fields may change. Use the macros
|
||||
whenever possible.
|
||||
</para>
|
||||
|
||||
<table xml:id="internals2.structure.modstruct.struct-values">
|
||||
<title>Module structure field values</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Field</entry><entry>Value</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
<varname>size</varname>
|
||||
<footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMHC">
|
||||
<para>
|
||||
This field is filled in by <constant>STANDARD_MODULE_HEADER</constant>.
|
||||
</para>
|
||||
</footnote>
|
||||
</entry>
|
||||
<entry><code>sizeof(zend_module_entry)</code></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
<varname>zend_api</varname>
|
||||
<footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHC"/>
|
||||
</entry>
|
||||
<entry><constant>ZEND_MODULE_API_NO</constant></entry>
|
||||
</row>
|
||||
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
|
|
|||
Loading…
Reference in a new issue