From 4573035033d364c1a5120a521ef41bd8f7ee2661 Mon Sep 17 00:00:00 2001 From: Gwynne Raskind Date: Mon, 4 Feb 2008 18:00:54 +0000 Subject: [PATCH] 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 --- internals2/structure/modstruct.xml | 204 +++++++++++++---------------- 1 file changed, 93 insertions(+), 111 deletions(-) diff --git a/internals2/structure/modstruct.xml b/internals2/structure/modstruct.xml index c8bb25b76c..9c130a6e3f 100644 --- a/internals2/structure/modstruct.xml +++ b/internals2/structure/modstruct.xml @@ -1,5 +1,5 @@ - + The zend_module structure @@ -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. The zend_module declaration from example.c looks like this before any code has been - written (the example file was generated by - ext_skel --extname=example): + written. The example file was generated by + ext_skel --extname=example, with some obsolete constructs + removed: @@ -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 = { This may look a bit daunting at first glance, but most of it is very simple to understand. Here's the declaration of zend_module from - zend_modules.h in PHP 5.2, along with a few relevant - nearby constants: + zend_modules.h in PHP 5.3: - zend_module definition in PHP 5.2 + zend_module definition in PHP 5.3 - + + + 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 STANDARD_MODULE_HEADER fills in + everything up to the deps field. Alternatively, the + STANDARD_MODULE_HEADER_EX will leave the + deps field empty for the developer's use. The developer is + always responsible for everything from name to + version. After that, the + STANDARD_MODULE_PROPERTIES macro will fill in the rest + of the structure, or the STANDARD_MODULE_PROPERTIES_EX + macro can be used to leave the extension globals and post-deactivation + function fields unfilled. Most modern extensions will make use of module + globals. + + - + + + Fields which are not intended for developers to use are marked by an + asterisk (*). + + + - size + size * - The size in bytes of the structure. This will always be to - sizeof(zend_module_entry). + The size in bytes of the structure. @@ -117,8 +124,7 @@ struct _zend_module_entry { zend_api - The version of the Zend API this module was compiled against. This is - always the constant ZEND_MODULE_API_NO. + The version of the Zend API this module was compiled against. @@ -129,8 +135,7 @@ struct _zend_module_entry { Flags indicating whether the module was compiled with debugging turned on - or ZTS (TSRM) enabled. These are always the constants - ZEND_DEBUG and USING_ZTS. + and/or ZTS (TSRM) enabled. @@ -139,9 +144,8 @@ struct _zend_module_entry { ini_entry - 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. @@ -214,17 +218,17 @@ struct _zend_module_entry { - globals_size + globals_size (*) - The size of the globals structure for this module, if any. + The size of the data structure containing the module's globals, if any. - globals_id_ptr - globals_ptr + globals_id_ptr (*) + globals_ptr (*) Only one of these two fields will exist, depending upon whether the @@ -256,83 +260,61 @@ struct _zend_module_entry { - module_started - type - handle - module_number + module_started (*) + type (*) + handle (*) + module_number (*) - 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. - - - STANDARD_MODULE_HEADER_EX - - - This macro is used by module developers to start the - zend_module structure when the module will specify INI - entries, dependencies, or both. - - - - - - STANDARD_MODULE_HEADER - - - This macro is used to start the zend_module - structure when the developer will not specify INI entries or dependencies. - - - - - - NO_VERSION_YET - - - This macro should be used by module developers to specify that the module - has no version. It is not recommended that this be used. - - - - - - STANDARD_MODULE_PROPERTIES_EX - - - This macro is used by module developers to end the - zend_module when the module will make use of - automatic globals, a post-deactivate callback, or both. - - - - - - STANDARD_MODULE_PROPERTIES - - - This macro is used by module developers to end the - zend_module when the module will not make use of - automatic globals or a post-deactivate callback. - - - - - - NO_MODULE_GLOBALS - - - This macro is used by module developers to specify values that tell Zend - that the module has no global variables. - - - - + + + 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. This is not recommended. The + "correct" values for many fields may change. Use the macros + whenever possible. + + + + Module structure field values + + + + FieldValue + + + + + + + size + + + This field is filled in by STANDARD_MODULE_HEADER. + + + + sizeof(zend_module_entry) + + + + + zend_api + + + ZEND_MODULE_API_NO + + + + +
+