Windows 用のビルドシステム: config.w32

Modified: phpdoc/ja/trunk/internals2/buildsys/configwin.xml =================================================================== --- phpdoc/ja/trunk/internals2/buildsys/configwin.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/buildsys/configwin.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + Windows 用のビルドシステム: config.w32 @@ -66,8 +66,8 @@ Modified: phpdoc/ja/trunk/internals2/funcs/index.xml =================================================================== --- phpdoc/ja/trunk/internals2/funcs/index.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/funcs/index.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,17 +1,364 @@ - + 関数の作成 - PHP はグルー言語 (訳注: 異なるシステムをつなぎ合わせるための - "接着材" としてはたらく言語) としても知られており、 - ジェネレータを使用して簡単に拡張することができます。 - ext_skel を使って C 言語の関数のスタブを作成すると、 - エクスポートされるすべての関数が - PHP_FUNCTION(func_name) - のようなシンプルなプロトタイプであることに気づかれるでしょう。 + One core element of an extension are functions which are exported to the + PHP userland. Even when you're planning to write object-oriented extensions + you are advised to read this chapter as most of the information is valid + for methods, too. + + + When adding a function to an extension, for instance after using the + ext_skel script to + create the raw infrastructure, you can create a function by implementing it + as a C function and then providing an entry for the extension's function + table. The function entry can contain a pointer to an argument information + structure. Providing this information ins not strictly necessary, unless + you plan to accept parameters by reference or want to return a reference, but + provides information that can be accessed via PHP's Reflection API. As you will see below the + parameters aren't passed as direct function parameters to the implementation + but passed on a stack, which is checked by the function's implementation + which can't directly serve as source for this information. + + + + Minimal PHP extension with one function + += 20010901 + STANDARD_MODULE_HEADER, +#endif + "demo", + demo_functions, + NULL, + NULL, + NULL, + NULL, + NULL, +#if ZEND_MODULE_API_NO >= 20010901 + "1.0.0", +#en + STANDARD_MODULE_PROPERTIES +} +/* }}} */ +]]> + + + + + In his example you can see the above discussed elements and the module + structure, if you don't remember his strucure go back to + . + + + + The first part of this extension is the actual implementation. As a + convention each exported function is preceded by a two line comment + describing the function's userland prototype and a short one line comment. + + + + For providing source code compatibility between different versions of PHP + the functions declaration is wrapped into the PHP_FUNCTION + macro. The compiler's preprocessor will, when using PHP 5.3 transform this + into a function like this: + + + + + + + + For preventing a naming conflict between a function exported to userland + and another C function with the same name the C symbol of the exported + function is prefixed with the prefix zif_. You can also see + that this prototype doesn't reference the argument stack. Accessing + parameters passed from PHP is described below. The following table lists + the C level parameters which are also defined in the + INTERNAL_FUNCTION_PARAMETERS macro. Mind that these parameters + might change between PHP versions and you should use the provide macros. + + + + INTERNAL_FUNCTION_PARAMETERS + + + + Name and type + Description + Access macros + + + + + + int ht + Number of actual parameters passed by user + ZEND_NUM_ARGS() + + + + zval *return_value + + Pointer to a PHP variable that can be filled with the return value + passed to the user. The default type is IS_NULL. + + RETVAL_*, RETURN_* + + + + zval **return_value_ptr + When returning references to PHP set this to a pointer to + your variable. It is not suggested to return references. + + + + + zval *this_ptr + + In case this is a method call this points to the PHP variable + holding the $this object. + + getThis() + + + + int return_value_used + + Flag indicating whether the returned value will be used by the + caller. + + + + + + +

+ + + As said the function shown above will simply return NULL to the user and do + nothing else. The function can be called, from the PHP userland, with an + arbitrary number of parameters. A more useful function consists of four + parts in general: + + + + + + Declaration of local variables. In C we have to declare locale vars, so + we do this at the functions top. + + + + + Parameter parsing. PHP passes parameters on a special stack, we have to + read them from there, verify the types, cast them if needed and bail out + in case something goes wrong. + + + + + Actual logic. Do whatever is needed. + + + + + Set the return value, cleanup, return. + + + + + + In some cases the exact order of these steps may change. Especially the + last two steps are often mixed up, but it's a good idea to stay in that + order. + + + + A simple function + + + + + + + The function above shows these parts. Let's start the analysis with the + last lines: php_printf is - as one can guess easily - PHP's + version of standard C's printf. Unlike printf it + doesn't print to the process's STDOUT channel but to the + current output stream, which might be buffered by the user. It should be + noted that php_printf, unlike most parts of PHP's API is not + binary safe, so if name contains a NULL-byte the rest would be + ignored. For a binary safe output PHPWRITE should be used. + + + + + In general it is considered to directly print data to the output stream, + it is suggested to return data as string to the user instead so the user + can decide what to do. Exceptions to this rule might be functions dealing + with binary data like images while your API should provide a way to access + the data even there. + + + + + The RETURN_TRUE macro in the last line does three things: It + sets the type of the variable we got as return_value pointer to + IS_BOOLEAN and the value to a true value. Then it + returns from the C function. So when using this macro you're housekeeping + for memory and other resources has to be completed as further code of + this function won't be executed. + + + + The zend_parse_parameters() function is responsible for reading + the parameters passed by the user from the argument stack and putting it + with proper casting in local C variables. If the user doesn't pass the wrong + number of parameters or types that can't be casted the function will emit a + verbose error and return FAILURE. In that case we simply return + from the function - by not changing the return_value the + default return value of NULL will be returned to the user. + + + + + Please mind that FAILURE is represented by a -1 + and SUCCESS by 0. To make the code clear you + should always use the named constants for comparing the value. + + + + + The first parameter to zend_parse_parameters() is the number of + parameters that have actually been passed to the function by the user. The + number is passed as ht parameter to our function but, as + discussed above, this should be considered as an implementation detail and + ZEND_NUM_ARGS() should be used. + + + + For compatibility with PHP's thread-isolation, the thread-safe resource + manager, we also have to pass the thread context using + TSRMLS_CC. Unlike in other functions this can't be the last + parameter as zend_parse_parameters expects a variable number of + parameters - depending on the number of user-parameters to read. + + + + Following the thread context the expected parameters are declared. Each + parameter is represented by a character in the string describing the type. + In our case we expect one parameter as a string so our type specification + is simply "s". + + + + Lastly one has to pass one or more pointers to C variables which should be + filled with the variable's value or provide more details. In the case of a + string we get the actual string, which will always be NULL-terminated, as a + char* and its length, excluding the NULL-byte, as + int. + + + + A documentation of all type specifiers and the corresponding additional C + types can be found in the file README.PARAMETER_PARSING_API + which is part of the source distribution. The most important types can be + found in the table below. + + + + zend_parse_parameters() type specifiers + + + + Modifier + Additional parameter types + Description + + + + + + b + zend_bool + Boolean value + + + + l + long + A integer (long) value + + + + d + double + A float (double) value + + + + s + char*, int + A binary safe string + + + + h + HashTable* + An array's hash table + + + +

+ - + 基本的なメモリ管理 - - + + When programming in the C programming language the developer has to manually + care about memory management. As PHP is usually used as a web server + module memory management is from special relevance in order to prevent memory + leaks. Additionally you should be aware that PHP might be used in threaded + environments which means that global variables might lead to race + conditions. For information about dealing with thread-global data please + refer to the documentation on the , + which serves as thread-isolation facility. + + + Additionally to these requirements the Zend Engine is faced with a quite + special usage pattern where, within a relatively short time, many memory + blocks of the size of a zval structure or other small memory blocks are + requested and freed again. Memory management in PHP has also to respect + the memory_limit. + + + + For fulfilling the above requirements the Zend Engine provides a special + memory manager for handling request-bound data. Request-bound data is data + that is needed only for serving a single request and which will be freed at + the request's end at latest. Extension authors will mostly only have contact + with the routines listed in the table below. Although they are implemented + as macros for providing some convenience features this documentation will + treat them like functions. + + + + Main memory APIs + + + + Prototype + Description + + + + + + void *emalloc(size_t size) + Allocate size bytes of memory. + + + + void *ecalloc(size_t nmemb, size_t size) + + Allocate a buffer for nmemb elements of + size bytes and makes sure it is initialized with zeros. + + + + + void *erealloc(void *ptr, size_t size) + + Resize the buffer ptr, which was allocated using + emalloc to hold size bytes of memory. + + + + + void efree(void *ptr) + + Free the buffer pointed by ptr. The buffer had to be + allocated by emalloc. + + + + + + void *safe_emalloc(size_t nmemb, size_t size, size_t offset) + + + Allocate a buffer for holding nmemb blocks of each + size bytes and an additional offset bytes. + This is similar to emalloc(nmemb * size + offset) but adds + a special protection against overflows. + + + + + char *estrdup(const char *s) + + Allocate a buffer that can hold the NULL-terminated string + s and copy the s into that buffer. + + + + + + char *estrndup(const char *s, unsigned int length) + + + Similar to estrdup while the length of the + NULL-terminated string is already known. + + + + +

+ + + + Unlike their C standard library's counterparts the Zend Engine's memory + management functions won't return NULL in case of an problem while + allocating the requested memory but bail out and terminate the current + request. + + + + + As said above it is an essential part of the memory management to avoid + having memory leaks and therefore free all memory you've allocated as soon + as possible. As a safety net the Zend Engine will free all memory, which had + been allocated using above mentioned APIs at the end of a request. If PHP + was built using the --enable-debug configuration option this + will lead to a warning. + + + + PHP's leak warnings + + + + &example.outputs.similar; + + + + + + + + When dealing with PHP variables you have to make sure the variable's + memory is allocated using emalloc and take care of the reference count. + Details can be found in . + + + + + + This leak detection can only find leaks caused by blocks allocated by + emalloc. You're advised to use a memory checker like valgrind or libumem + for deeper analysis. To simplify the analysis PHP's memory manager can be + disabled by setting the environment variable USE_ZEND_ALLOC=0 before + starting PHP. + + + - + + Modified: phpdoc/ja/trunk/internals2/pdo/preparation.xml =================================================================== --- phpdoc/ja/trunk/internals2/pdo/preparation.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/pdo/preparation.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + 準備 Modified: phpdoc/ja/trunk/internals2/structure/basics.xml =================================================================== --- phpdoc/ja/trunk/internals2/structure/basics.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/structure/basics.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + 基本構造 @@ -41,11 +41,11 @@ #define phpext_counter_ptr &counter_module_entry #ifdef PHP_WIN32 -# define PHP_COUNTER_API __declspec(dllexport) +# define PHP_COUNTER_API __declspec(dllexport) #elif defined(__GNUC__) && __GNUC__ >= 4 -# define PHP_COUNTER_API __attribute__ ((visibility("default"))) +# define PHP_COUNTER_API __attribute__ ((visibility("default"))) #else -# define PHP_COUNTER_API +# define PHP_COUNTER_API #endif #ifdef ZTS Modified: phpdoc/ja/trunk/internals2/structure/lifecycle.xml =================================================================== --- phpdoc/ja/trunk/internals2/structure/lifecycle.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/structure/lifecycle.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,11 +1,11 @@ - + 拡張モジュールのライフサイクル - Zend 拡張モジュールは、そのライフサイクルにおいていくつかの段階をたどります。 + PHP の拡張モジュールは、そのライフサイクルにおいていくつかの段階をたどります。これらの段階を通じて、開発者はさまざまな初期化や後処理そして情報の取得などを行います。 Zend API には、拡張モジュールの 5 つの段階のそれぞれに対するフックがあります。これらは PHP の関数からコールされるのとは別のものです。 @@ -20,7 +20,7 @@ このリクエストごとにひとつのプロセスを実行します。しかし、それ以外の多くの実装 (有名どころでは Apache モジュールなど) では、複数のリクエストを単一の PHP プロセスに関連付けることができます。 - したがって、Zend 拡張モジュールはその生存期間中に多くのリクエストを処理することもありえます。 + したがって、PHP の拡張モジュールはその生存期間中に多くのリクエストを処理することもありえます。 Modified: phpdoc/ja/trunk/internals2/variables/index.xml =================================================================== --- phpdoc/ja/trunk/internals2/variables/index.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/variables/index.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,13 +1,91 @@ - + 変数の作成 - - +

+ Intro + + For working with variables in PHP's core you have to learn about different + fundamental concepts used in PHP. Firstly PHP is a dynamic and weak typed + language. Secondly PHP uses a copy on write mechanism with reference + counting for memory handling. Please check the chapter for details how + reference counting and references work. + + + PHP variables, in general, consist out of two things: The label, which + might, for instance, be an entry in a symbol table, and the actual variable + container. For the most parts of this manual we will focus on the variable + container. + + + The variable container, in code called zval, is holding all + data needed to handle the variable. This includes not only the actual value + but also the current type, a counter counting the number of labels pointing + to this container and a flag whether these labels should be treated as + references or copies. In PHP 5.3 the relevant structures, which you can + find in Zend/zend.h, look like this: + + + + + + In the zvalue_value one can find the internal representation + for the different types the fields used should be clear from the names and + comments - especially if one knows that PHP's arrays are infact hash + tables. Nonetheless, knowing PHP's types one might miss a few: + NULL, boolean and resources. For + NULL we need no value, as NULL is the value of + that type. For boolean and resource values PHP + re-uses the value field. In the case of a boolean it holds + either 0 for false or 1 for + true. For resource-typed variables it holds the + resource id. + + + Now the good message is that you don't have to know these things in detail + as there are - like always in PHP - acces macros. The bad news is that there + are many of them: There are macros to access any aspect of the + zval and then, as one often deals with pointers to + zvals and even pointers to pointers to zvals, for + most of them there are shortcuts dereferencing these pointers. These macros + are spread over Zend/zend.h, + Zend/zend_operators.h and Zend/zend_API.h. + +

+

+ Creating variables and setting values + + + +

+ - - - + - + 引数の扱い @@ -943,6 +943,7 @@ ]]> + パラメータが参照で渡されたかどうかを調べる Modified: phpdoc/ja/trunk/internals2/ze1/zendapi/macros/zend_me_mapping.xml =================================================================== --- phpdoc/ja/trunk/internals2/ze1/zendapi/macros/zend_me_mapping.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/ze1/zendapi/macros/zend_me_mapping.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + ZEND_ME_MAPPING @@ -15,6 +15,7 @@ ???name ???func_name ???arg_types + ???flags ... Modified: phpdoc/ja/trunk/internals2/ze1/zendapi/printing.xml =================================================================== --- phpdoc/ja/trunk/internals2/ze1/zendapi/printing.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/ze1/zendapi/printing.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + 情報の表示 @@ -150,6 +150,7 @@ ]]> + phpinfo() の出力 @@ -193,6 +194,7 @@ ]]> + 実行時の情報の表示 Modified: phpdoc/ja/trunk/internals2/ze1/zendapi/variables.xml =================================================================== --- phpdoc/ja/trunk/internals2/ze1/zendapi/variables.xml 2010-05-07 00:20:28 UTC (rev 299096) +++ phpdoc/ja/trunk/internals2/ze1/zendapi/variables.xml 2010-05-07 00:56:45 UTC (rev 299097) @@ -1,6 +1,6 @@ - + 変数の作成 @@ -182,6 +182,7 @@ ]]> + スコープが異なる変数の作成