From 8f6738ea086ed3b24b154e527749bc0115991abd Mon Sep 17 00:00:00 2001
From: Gwynne Raskind <gwynne@php.net>
Date: Wed, 27 Jun 2007 21:31:12 +0000
Subject: [PATCH] A couple of pages of new material. Committing now simplifies
 necessary changes to fix internals errors.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@238740 c90b9560-bf6c-de11-be94-00142212c4b1
---
 internals2/structure/files.xml     |   4 +-
 internals2/structure/modstruct.xml | 100 ++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 4 deletions(-)

diff --git a/internals2/structure/files.xml b/internals2/structure/files.xml
index 36fb1c1bce..03df6cb2e2 100644
--- a/internals2/structure/files.xml
+++ b/internals2/structure/files.xml
@@ -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>
 
diff --git a/internals2/structure/modstruct.xml b/internals2/structure/modstruct.xml
index 77f4857085..0ffb029d4b 100644
--- a/internals2/structure/modstruct.xml
+++ b/internals2/structure/modstruct.xml
@@ -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