cvs: phpdoc /en/internals2/structure files.xml modstruct.xml

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