gwynne Wed Jun 27 21:31:12 2007 UTC
Modified files:
/phpdoc/en/internals2/structure files.xml modstruct.xml
Log:
A couple of pages of new material. Committing now simplifies necessary
changes to fix internals errors.
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/files.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/internals2/structure/files.xml
diff -u phpdoc/en/internals2/structure/files.xml:1.1
phpdoc/en/internals2/structure/files.xml:1.2
--- phpdoc/en/internals2/structure/files.xml:1.1 Thu Jun 21 00:30:22 2007
+++ phpdoc/en/internals2/structure/files.xml Wed Jun 27 21:31:12 2007
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<sect1 xml:id="internals2.structure.files"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>Files which make up an extension</title>
<para>
Whether created by hand, using <command>ext_skel</command>, or by an
alternate extension generator, such as
- <link xlink:href="http://codegenerators.php-baustelle.de/";>CodeGen</link>,
+ <link xlink:href="&url.codegen;">CodeGen</link>,
all extensions will have at least four files:
</para>
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/modstruct.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/internals2/structure/modstruct.xml
diff -u phpdoc/en/internals2/structure/modstruct.xml:1.1
phpdoc/en/internals2/structure/modstruct.xml:1.2
--- phpdoc/en/internals2/structure/modstruct.xml:1.1 Thu Jun 21 00:30:22 2007
+++ phpdoc/en/internals2/structure/modstruct.xml Wed Jun 27 21:31:12 2007
@@ -1,8 +1,104 @@
<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<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/>
+ <para>
+ The main source file of a PHP extension contains several new constructs for
+ a C programmer. The most important of these, the one touched first when
+ starting a new extension, is the <literal>zend_module</literal> structure.
+ This structure contains a wealth of information that tells the Zend Engine
+ 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.
+ </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>):
+ </para>
+
+ <example xml:id="internals2.structure.modstruct.example-decl">
+ <title>zend_module declaration in an example extension</title>
+ <programlisting role="c">
+<![CDATA[
+/* {{{ 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),
+ PHP_MSHUTDOWN(example),
+ 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
+};
+/* }}} */
+]]>
+ </programlisting>
+ </example>
+
+ <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:
+ </para>
+
+ <example xml:id="internals2.structure.modstruct.struct-defn">
+ <title>zend_module definition in PHP 5.2</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;
+ int (*module_startup_func)(INIT_FUNC_ARGS);
+ int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
+ int (*request_startup_func)(INIT_FUNC_ARGS);
+ int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
+ void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
+ char *version;
+ size_t globals_size;
+#ifdef ZTS
+ ts_rsrc_id* globals_id_ptr;
+#else
+ void* globals_ptr;
+#endif
+ void (*globals_ctor)(void *global TSRMLS_DC);
+ void (*globals_dtor)(void *global TSRMLS_DC);
+ int (*post_deactivate_func)(void);
+ int module_started;
+ unsigned char type;
+ 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 ZE2_STANDARD_MODULE_HEADER \
+ STANDARD_MODULE_HEADER_EX, ini_entries, NULL
+
+#define STANDARD_MODULE_PROPERTIES_EX 0, 0, NULL, 0
+]]>
+ </programlisting>
+ </example>
+
</sect1>
<!-- Keep this comment at the end of the file
